facetted-interfaces/history/FIAM_v0.2_Draft6/history/FIAM-v0.2-Draft4-root-copy.md

FIAM v0.2-draft.4 — Estate Hardening

Status

FIAM v0.2-draft.4 hardens the Faceted Interface Architecture Model for estate-scale, incomplete, incremental and multi-environment discovery.

The Core is frozen. schemas/FIAM-Core-v0.2.schema.json is byte-identical to the v0.2-draft.1 and draft.3 Core. No new structural entity was introduced in this revision.

The work is concentrated in five operational contracts:

1. runtime aggregation and incremental catalog update;
2. stable runtime identity tuples and Zones;
3. scored reconciliation plus a non-destructive working-set projection;
4. coverage, ambiguity and gateway-aware lenses;
5. declared security ingest from OpenAPI.

The architectural posture

The estate catalog is not a trace warehouse.

telemetry occurrences
        |
        | aggregate by architectural participation
        v
runtime observation class
  operation + binding + role
  + channel/resource where relevant
        |
        +--> count / error_count
        +--> first_seen / last_seen
        +--> bounded evidence samples
        |
        v
FIAM architecture catalog

Full span occurrences remain in the telemetry backend. FIAM may retain a bounded sample of trace/span identifiers so an operator can return to the source evidence.

Runtime identity

Runtime discovery now constructs explicit identity tuples rather than using labels such as service.name as catalog keys.

A deployed service node is keyed from:

service namespace
+ service name
+ deployment environment
+ cluster identity
+ Kubernetes namespace
+ cloud account / region where supplied

FIAM deliberately distinguishes OpenTelemetry logical service identity from architectural deployment identity. OpenTelemetry specifies that deployment.environment.name does not change logical service identity; FIAM nevertheless uses deployment/cluster context to keep production and staging architecture records separate.

Zones are created for deployment environment, cluster and Kubernetes namespace when evidence supplies them.

Runtime aggregation

Default OTLP ingest aggregates spans by an architectural tuple containing:

domain
role
operation
binding
local node
remote node where known
channel or InformationResource where relevant

The aggregate stores:

• observation count;
• error count;
• first seen;
• last seen;
• bounded sample trace/span references.

The same values are materialized as idempotent evidence-backed assertions so lenses can query them through normal FIAM semantics.

--occurrences sample is the default. none and all are explicit diagnostic alternatives.

Incremental catalog semantics

otel_to_fiam.py --base catalog.yaml updates an existing FIAM catalog instead of rebuilding the declared model.

Properties:

• stable entity identities across batches;
• hash-derived assertion identifiers;
• exact-batch replay idempotency;
• evidence timestamps update rather than duplicate;
• processed batch hashes are retained;
• sampled absence does not imply architectural absence;
• only --authoritative-snapshot may close a runtime-active observation interval.

Exactly-once detection of spans that are repackaged into a semantically different OTLP batch remains the responsibility of a production ingestion/checkpoint layer. FIAM's file reference implementation guarantees exact replay idempotency for identical batches and stable architectural aggregation; it does not turn the YAML catalog into an unbounded event-deduplication database.

Cardinality and privacy boundaries

The runtime adapter does not use high-cardinality occurrence values as architecture identity when a low-cardinality semantic attribute is unavailable.

Examples:

• missing http.route -> one unknown-route Operation;
• raw url.path is not promoted to an Operation or identifier;
• raw span names are not persisted in the architecture catalog;
• db.query.text and query parameters are not copied;
• trace/span ids are retained only as bounded evidence references.

This deliberately prefers an explicit partial model over a falsely precise, high-cardinality catalog.

Partial telemetry is a first-class result

A green conformance run does not require unresolved = 0.

Fixtures now cover:

• RPC client span without the server span;
• messaging producer without a downstream span link;
• database span without a stable namespace/collection;
• HTTP span without http.route;
• ambiguous declared HTTP candidates.

Each remains a valid partial FIAM model with an explicit unresolved/candidate finding.

Reconciliation

Runtime reconciliation now builds candidate indexes and records scored candidates.

Possible states:

matched
ambiguous
near-match
unmatched

Only a sufficiently strong unique match produces fiam.relation.corresponds-to.

Ambiguity is therefore visible architecture intelligence rather than a silent no-match.

Working-set projection

working_set_view.py makes conservative identity usable without destructive merge.

observed record
   -- corresponds-to --> declared record
                |
                v
working-set preferred reference = declared record

The observed record, evidence and correspondence remain present. Ambiguous correspondences remain separate.

Runtime topology uses this projection so operators do not see unnecessary duplicate nodes when high-confidence declared/runtime correspondence already exists.

Gateways and proxies

Runtime ingest considers semantic destination evidence and network-peer evidence separately. server.address remains the logical destination when available; network.peer.* may identify the actually contacted intermediary.

When runtime client evidence reconciles to a declared target but the observed responder is a different service, the topology edge may be marked:

via_gateway: true
gateway: <observed proxy>
intended_target: <declared service>

This avoids silently replacing the intended architecture with a mesh/sidecar topology.

Declared coverage

The Declared-vs-Observed Lens now reports operation/channel coverage in addition to property differences:

• observed;
• declared-only;
• observed-only;
• ambiguous.

A deterministic security API fixture demonstrates one observed operation and three declared-but-unseen operations with architectural owner resolution.

OpenAPI security ingest

The OpenAPI adapter now maps declared security schemes and requirements into FIAM Security profiles.

Supported scheme families:

• API key;
• HTTP Basic;
• HTTP Bearer;
• OAuth 2.0;
• OpenID Connect;
• mutual TLS.

The adapter preserves OpenAPI Security Requirement semantics:

• schemes inside one requirement object are conjunctive;
• separate requirement objects are alternatives;
• {} allows anonymous access as an alternative;
• an operation security field overrides top-level security;
• security: [] explicitly removes inherited security.

The Security Coverage Lens computes effective declared security per operation. Generic OTLP is deliberately not interpreted as proof that authentication is absent.

Estate conformance

The draft.4 harness checks more than schema typing:

• Core byte freeze;
• all package schemas and Canon;
• 26 semantic specimens;
• deterministic OpenAPI ingest;
• OpenAPI security semantics;
• 5,000-span runtime aggregation;
• 7,000-observation incremental update;
• byte-idempotent exact replay;
• authoritative-snapshot activity closure;
• production/staging identity separation;
• four partial-telemetry fixtures;
• ambiguous reconciliation with no unsafe correspondence;
• working-set projection and gateway topology;
• declared operation coverage;
• cross-domain RPC/messaging/database topology;
• database privacy boundary;
• deterministic domain ingest;
• adversarial FIAM and OTLP cases.

Run:

make check

What remains deliberately outside the Core

Draft.4 does not add:

• Session;
• span/Occurrence entities to the Core;
• field lists on InformationShape;
• business ontology;
• automatic identity merge;
• a new interface family type.

Known adapter limitations include external OpenAPI $ref resolution, callbacks/webhooks, server-variable expansion and production-grade persistent indexing/checkpoint storage. These are adapter/catalog implementation work, not evidence for Core growth.

Conclusion

The main FIAM question has shifted.

It is no longer:

Can one Core represent HTTP, RPC, messaging and data access?

Draft.3 answered that.

The draft.4 question is:

Can that same Core remain useful when observations are numerous, incomplete, duplicated, ambiguous, environment-scoped and mediated by real infrastructure?

The current conformance suite says yes, provided aggregation, identity, evidence and projection are treated as first-class operational contracts around the frozen Core.