tegwick 1353267569 Establish FIAM repository governance baseline

Assistant: codex
Assistant-Model: gpt-5.6-luna
Assistant-Session: 01a087b0-7b1e-7531-8ef3-6525ebaf7ee7

2026-09-09 21:53:43 +02:00

2.5 KiB

Raw Blame History

FIAM v0.2 — Declared vs Observed Lens

Purpose

Answer architecture-intelligence questions over one evidence-preserving graph:

What was declared?
What was observed?
Where do properties agree, refine or conflict?
Which declared operations/channels have never been observed in the current evidence horizon?
Which runtime operations are undeclared or ambiguous?
Who owns the declared side of the finding?

Pairing and candidates

Property comparison uses evidence-backed:

observed -- corresponds-to --> declared

Reconciliation also exposes scored candidate lists even when no correspondence is safe.

This lets the Lens distinguish:

matched
ambiguous
near-match
unmatched

instead of treating every failed join as silence.

Property comparison

Current strategies include exact comparison and Canon-hierarchy comparison.

Example:

declared: fiam.protocol.http
observed: fiam.protocol.http2
=> compatible-refinement

while:

declared: fiam.protocol.http1.1
observed: fiam.protocol.http2
=> conflict

Coverage findings

Coverage is currently evaluated for Operations and Channels.

Classes:

Class	Meaning
`observed`	declared entity has a correlated runtime observation
`declared-only`	declared entity has no correlated observation in the available evidence
`observed-only`	runtime entity has no useful declared candidate
`ambiguous`	runtime entity has plausible declared candidates but no safe correspondence

declared-only does not mean unused forever. It means unseen in the current catalog/evidence horizon.

Ambiguity example

The estate-hardening fixture declares two GET /pets/{id} operations on different servers, then supplies a runtime span without server identity.

The Lens emits:

ambiguous observed operation
  candidate A score 0.8
  candidate B score 0.8

and no corresponds-to assertion.

Owner resolution

Binding/Operation/Endpoint findings resolve through the declared provider Port to its owning SystemNode. Channel and Resource findings may resolve through their owner when present.

This identifies architectural ownership; organizational team/person ownership remains unknown unless separately supplied.

Security

Security coverage is handled by the separate fiam.lens.security-coverage Lens because generic OTLP absence does not prove authentication absence.

The declared-vs-observed Lens may later compare security when an explicit runtime security evidence source exists.

2.5 KiB Raw Blame History