coulomb/facetted-interfaces
5
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Establish FIAM repository governance baseline

Browse source 
Assistant: codex
Assistant-Model: gpt-5.6-luna
Assistant-Session: 01a087b0-7b1e-7531-8ef3-6525ebaf7ee7
This commit is contained in:
tegwick 2026-09-09 21:53:43 +02:00
parent 4cad6cbc58
commit 1353267569
233 changed files with 43443 additions and 9 deletions
Download patch file Download diff file Expand all files Collapse all files

13
.custodian-brief.md
View file

@ -2,19 +2,16 @@
# Custodian Brief — facetted-interfaces
**Domain:** infotech
**Last synced:** 2026-09-09 19:45 UTC
**Last synced:** 2026-09-09 19:52 UTC
**State Hub:** http://127.0.0.1:8000 *(adjust if running on a remote machine)*
## Active Workstreams
### Bootstrap FIAM repository governance and baseline
Progress: 1/5 done | workplan_id: `df6dc111-064b-5154-964b-6683190a79f6`
*(none — repo may need first-session setup)*
**Open tasks:**
- · T02 — Register repository with State Hub `ab0919d3`
- · T03 — Verify and document the Draft 6 baseline `e49c82ce`
- · T04 — Plan the maintained FIAM release layout `19518be4`
- · T05 — Close out the bootstrap `e85b9157`
## SCOPE Freshness
- SCOPE.md says active but no open workplans remain — refresh Current State.
---
## MCP Orientation (when available)

5
.gitignore vendored Normal file
View file

@ -0,0 +1,5 @@
# state-hub: track .claude/rules
# Claude Code local state (track shared rules; ignore machine-specific files)
.claude/*
!.claude/rules/
!.claude/rules/*.md

20
.repo-classification.yaml Normal file
View file

@ -0,0 +1,20 @@
repo_classification:
standard: Repo Classification Standard
version: '1.0'
classified_at: '2026-09-09'
classified_by: agent
category: project
domain: infotech
secondary_domains: []
capability_tags:
- interface-architecture
- standards
- evidence
- traceability
- source-management
business_stake:
- technology
- operations
business_mechanics:
- coordination
- operation

205
AGENTS.md Normal file
View file

@ -0,0 +1,205 @@
# facetted-interfaces — Agent Instructions
## Repo Identity
**Purpose:** FIAM standard and reference architecture analytics and control implementation
**Domain:** infotech
**Repo slug:** facetted-interfaces
**Topic ID:** `fe2aaa78-9c20-4feb-b3d2-4fe0529572a3`
**Workplan prefix:** `FIAM-WP-`
---
## State Hub Integration
The Custodian State Hub tracks work across all domains. Codex uses HTTP REST and
the `statehub` CLI by default. MCP is opt-in because the current Codex MCP bridge
adds severe call latency; the full administrative MCP surface remains available
to clients that need it.
| Context | URL |
|---------|-----|
| Local workstation | `http://127.0.0.1:8000` |
| Remote via tunnel | `http://127.0.0.1:18000` |
| Optional local edge relay | http://127.0.0.1:18080 |
When an operator has enabled the edge relay, set API_BASE to the relay URL.
Queueable writes return an explicit queued receipt if the central hub is
unreachable. Treat that as pending local evidence, then ask the operator to run
statehub outbox status/replay after connectivity returns.
Codex workspace-write sandboxes need network access enabled to reach the host's
loopback listener. Bootstrap this once with `make -C ~/state-hub configure-codex`
and restart Codex. The canonical REST health endpoint is `/state/health`, not
`/health`. If a sandboxed loopback probe fails, retry it with escalated execution
before declaring State Hub unavailable; a managed Codex permission profile may
still enforce isolated networking. Experimental MCP can be enabled explicitly
with `make -C ~/state-hub configure-codex WITH_MCP=1`.
### Orient at session start
```bash
# Offline brief — works without hub connection
cat .custodian-brief.md
# Active workplans for this domain
curl -s "http://127.0.0.1:8000/workplans/?topic_id=fe2aaa78-9c20-4feb-b3d2-4fe0529572a3&status=active" \
| python3 -m json.tool
# Check inbox
curl -s "http://127.0.0.1:8000/messages/?to_agent=facetted-interfaces&unread_only=true" \
| python3 -m json.tool
```
Mark a message read:
```bash
curl -s -X PATCH "http://127.0.0.1:8000/messages/<id>/read" \
-H "Content-Type: application/json" -d '{}'
```
### Log progress (required at session close)
```bash
curl -s -X POST http://127.0.0.1:8000/progress/ \
-H "Content-Type: application/json" \
-d '{
"summary": "what was done",
"event_type": "note",
"author": "codex",
"workplan_id": "<uuid>",
"task_id": "<uuid>"
}'
```
Omit `workplan_id` / `task_id` when not applicable.
### Update task status
```bash
curl -s -X PATCH "http://127.0.0.1:8000/tasks/<task_id>" \
-H "Content-Type: application/json" \
-d '{"status": "progress"}'
# values: wait | todo | progress | done | cancel
```
### Flag a task for human review
```bash
curl -s -X PATCH "http://127.0.0.1:8000/tasks/<task_id>" \
-H "Content-Type: application/json" \
-d '{"needs_human": true, "intervention_note": "reason"}'
```
---
## Session Protocol
**Start:**
1. `cat .custodian-brief.md` — domain goal and open workplans (offline-safe)
2. Check inbox: `GET /messages/?to_agent=facetted-interfaces&unread_only=true`; mark read
3. Scan workplans: `ls workplans/` — note `status: ready`, `active`, or `blocked` files and open tasks
4. Check human-needed tasks: `GET /tasks/?needs_human=true`
**During work:**
- Update task statuses in workplan files as tasks progress
- Record significant decisions via `POST /decisions/`
**Close:**
1. Update workplan file task statuses to reflect progress
2. If finishing a workplan: hand off **residuals** as live work records first
(intake with `origin: residual` + `origin_ref: <WP-id>`, or a next workplan /
decision / engagement). Do not park leftovers only in prose or `SCOPE.md`.
Canon: `the-custodian/canon/standards/work-record-types_v0.1.md` § Residuals.
3. Log: `POST /progress/` with a summary of what changed (name handoff ids)
4. After workplan file changes, run:
```bash
uv run --project ~/repo-manager rmgr sync --path . --push
```
This assigns only missing deterministic identifiers, verifies the pushed
Forgejo commit and `primary/railliance01`, then requests one central
reconciliation. A queued receipt is pending evidence; rerun after
connectivity returns. Use `statehub fix-consistency` for a separate deep audit.
---
{CREDENTIAL_ROUTING}
<!-- REPO-AGENTS-EXTENSIONS -->
<!-- Append repo-specific agent instructions below this marker.
The state-hub template sync preserves content after this line. -->
---
## Workplan Convention (ADR-001)
Work items originate as files in this repo — not in the hub. The hub is a
read/cache/index layer that rebuilds from files.
**File location:** `workplans/FIAM-WP-NNNN-<slug>.md`
**Archived location:** finished workplans may move to
`workplans/archived/YYMMDD-FIAM-WP-NNNN-<slug>.md`. The `YYMMDD` prefix is
the completion/archive date; the frontmatter `id` does not change.
**Ad Hoc Tasks:** small opportunistic fixes discovered during a session use
`workplans/ADHOC-YYYY-MM-DD.md`, workplan id
`FIAM-WP-ADHOC-YYYY-MM-DD`, and task ids
`FIAM-WP-ADHOC-YYYY-MM-DD-T01`, etc. `FIAM-WP` includes its final `-WP`
token. Unqualified historic `ADHOC-*` ids are grandfathered and must not be
copied into new records. Use this only for low-risk work completed directly;
create a normal workplan for anything needing analysis, design, approval,
dependencies, or multiple phases.
**Frontmatter:**
```yaml
---
id: FIAM-WP-NNNN
type: workplan
title: "..."
domain: infotech
repo: facetted-interfaces
status: proposed | ready | active | blocked | backlog | finished | archived
owner: codex
topic_slug: ...
created: "YYYY-MM-DD"
updated: "YYYY-MM-DD"
state_hub_workstream_id: "<uuid>" # deterministic UUIDv5; managed by Repo Manager
---
```
Use `proposed` for a new draft, `ready` after review against current repo
state, and `finished` after implementation. `stalled` and `needs_review` are
derived health labels, not frontmatter statuses.
**Terminology:** workplan is the fleet term; `workstream` appears only in legacy
API/MCP/frontmatter bridges until `STATE-WP-0069` retires them — see
`the-custodian/canon/standards/workplan-terminology-fleet_v0.1.md`.
**Task block format** (one per `##` section):
```
## Task Title
` ` `task
id: FIAM-WP-NNNN-T01
status: wait | todo | progress | done | cancel
priority: high | medium | low
state_hub_task_id: "<uuid>" # deterministic UUIDv5; managed by Repo Manager
` ` `
Task description text.
```
Status progression: `todo` → `progress` → `done`; use `wait` for waiting/blocked work and `cancel` for stopped work.
**Residuals when finishing:** actionable leftovers become live work records
before `status: finished` — usually an intake (`origin: residual`,
`origin_ref: FIAM-WP-NNNN`) or a spawned workplan. Residual is a *role*,
not a kind. Fleet list lives on State Hub, not in `SCOPE.md`.
To create a new workplan:
1. Write the file following the format above
2. Run `uv run --project ~/repo-manager rmgr sync --path . --push`.
3. Run `statehub fix-consistency` only when a separate deep audit is needed.

56
INTENT.md Normal file
View file

@ -0,0 +1,56 @@
# INTENT
## Purpose
This repository develops and maintains the FIAM (Facetted Interface
Architecture Model) standard and its reference architecture, analytics, and
control implementation.
FIAM provides a precise way to describe interfaces as composable facets,
connect declared architecture with runtime evidence, and query the resulting
architecture without confusing observations with declarations.
## Intended Users
The primary users are architects, platform engineers, implementers of
interface and architecture tooling, and agents working across the FIAM
ecosystem. The repository should make the standard understandable and
executable for both humans and automation.
## Scope
This repository owns:
- the FIAM vocabulary, canonical model, and conformance rules;
- schemas and examples for declared, observed, and composite architectures;
- reference converters, catalog/index tools, and analytical lenses;
- validation, adversarial fixtures, and semantic-regression checks;
- documentation of versioning, identity, evidence, snapshots, and migration.
It does not own deployment of a consuming platform, a general-purpose
service catalog, or the product UI of downstream architecture products.
## Architectural Principles
- Keep interface identity, representation shape, and evidence distinct.
- Preserve source records and provenance; inferred correspondence is not a
destructive merge.
- Treat declared and observed architecture as complementary projections.
- Make uncertainty, ambiguity, staleness, and missing evidence explicit.
- Prefer deterministic, schema-validated artifacts and reproducible checks.
- Evolve the standard deliberately, with migration and conformance guidance.
## Current Baseline
The current repository is a seed containing the FIAM v0.2 Draft 6 reference
material under `history/FIAM_v0.2_Draft6/`. That material is the starting
baseline, not yet a complete actively maintained release layout. The first
operational priority is to establish ownership, validation, and a clear path
from the archived draft to the next maintained FIAM release.
## Completion Condition
The intent is being fulfilled when FIAM has a maintained normative release,
an executable conformance suite, documented extension and migration rules,
and reference tooling that produces trustworthy architecture intelligence from
declared and runtime interface evidence.

14
README.md
View file

@ -1,3 +1,15 @@
# facetted-interfaces
The FIAM Facetted Interface Architecture Model standard with it's reference architecture analytics and control reference implementation.
The FIAM Facetted Interface Architecture Model standard with it's reference architecture analytics and control reference implementation.
## Repository baseline
The maintained starting point is the FIAM v0.2 Draft 6 reference tree in
`history/FIAM_v0.2_Draft6/`. Its conformance suite is run with:
```bash
make -C history/FIAM_v0.2_Draft6 check
```
Normative releases should be promoted into a versioned top-level release
layout; `history/` remains reserved for superseded drafts.

32
SCOPE.md Normal file
View file

@ -0,0 +1,32 @@
# SCOPE
> This file was generated by `statehub register`. Refine it as the repository
> boundaries become clearer.
## One-liner
FIAM standard and reference architecture analytics and control implementation
## Core Idea
facetted-interfaces exists to provide the capability described in INTENT.md.
## In Scope
- Maintain the repository's primary implementation.
- Keep docs, tests, and operational metadata current.
## Out of Scope
- Own unrelated adjacent systems.
- Make irreversible operational decisions without human approval.
## Current State
- Status: active; implementation and stability should be verified by the repo agent.
## Getting Oriented
- Start with: INTENT.md
- Agent instructions: AGENTS.md
- Workplans: workplans/

16
WORK-RECORDS.md Normal file
View file

@ -0,0 +1,16 @@
# Work Records — facetted-interfaces
> Generated by `statehub fix-consistency` (CUST-WP-0061-T04, work-record
> stage 3). Do not edit by hand — edit the source file/block listed for
> each record and re-run fix-consistency to refresh this index. Archived
> workplans are omitted; closed decisions/intakes/engagements stay listed
> so recently-resolved work is still visible. [auto]
| Kind | ID | Status | Lane | Source |
| --- | --- | --- | --- | --- |
| workplan | FIAM-WP-0001 | finished | — | workplans/FIAM-WP-0001-statehub-bootstrap-and-baseline.md |
| task | FIAM-WP-0001-T01 | done | — | workplans/FIAM-WP-0001-statehub-bootstrap-and-baseline.md |
| task | FIAM-WP-0001-T02 | done | — | workplans/FIAM-WP-0001-statehub-bootstrap-and-baseline.md |
| task | FIAM-WP-0001-T03 | done | — | workplans/FIAM-WP-0001-statehub-bootstrap-and-baseline.md |
| task | FIAM-WP-0001-T04 | done | — | workplans/FIAM-WP-0001-statehub-bootstrap-and-baseline.md |
| task | FIAM-WP-0001-T05 | done | — | workplans/FIAM-WP-0001-statehub-bootstrap-and-baseline.md |

80
history/FIAM_v0.2_Draft6/ARCHITECTURE-INTELLIGENCE-INDEX-v0.2.md Normal file
View file

@ -0,0 +1,80 @@
# FIAM v0.2 — Architecture Intelligence Index Contract
## Derived query plane
The index is a rebuildable query projection. It MUST NOT become the sole copy of FIAM evidence or Catalog Exchange history.
Draft.6 indexes:
- latest entities plus historical entity versions;
- raw assertions and raw evidence;
- non-destructive working identities;
- generic declared relation inventory;
- runtime aggregates;
- **scope-owned topology observation intervals**;
- **population-level logical topology intervals** formed by unioning observation scopes;
- unresolved observations and reconciliation candidates;
- temporal Zone memberships.
## Observation scope vs logical architecture
A logical architectural edge has one `edge_key`. Each observing collector has a distinct `observation_scope` and therefore a distinct observation interval:
```text
logical Orders -> Inventory
observed by prod-cluster-a-app-traces
observed by prod-cluster-a-mesh
```
The logical edge remains active while any covering observation scope remains active. Closing one collector's observation never closes another collector's interval.
This avoids both collector identity contaminating Core architectural identity and one platform team accidentally closing another team's observations.
## Complete snapshot closure
A complete snapshot can close only observations:
- owned by its observation scope;
- in domains covered by its authority grant;
- missing for the configured number of consecutive complete snapshots;
- whose `last_seen` is older than the configured grace period.
The observation interval records:
- `last_seen` — evidence time;
- `closed_at` — policy-action time;
- `close_reason`;
- `absence_streak` in current observation state.
Population-level logical intervals close only when every active observation scope for that edge has closed.
## Raw evidence only
The index stores raw evidence records. It MUST NOT persist evidence-strength scores as architectural facts. Evidence scores are computed by a Lens at query time and every result identifies the scoring policy id/hash.
## Declaration inventory
Declared relation assertions are indexed generically with subject/object owner projections. The query-time declaration matcher determines whether a runtime edge is declared using target, intended target, Channel, working-set identity, and domain-aware relation semantics.
## Catalog-native write path
Continuous ingestion SHOULD use Catalog Exchange records directly:
```text
adapter -> Catalog Exchange/NDJSON -> index
```
A whole FIAM YAML model is not required as a write-ahead log. FIAM model conversion remains available for audit, interoperability and fixtures.
The index can export a scope checkpoint as Catalog Exchange, but the checkpoint does not replace original evidence/source documents.
## Retention
Closed intervals and historical entity/assertion/evidence versions are retained until an explicit derived-index purge. A purge:
- requires an explicit confirmation flag;
- removes only index rows older than the requested time;
- MUST NOT delete Catalog Exchange or source artifacts;
- makes older historical queries unavailable until the index is rebuilt from retained exchange artifacts.
This preserves the distinction between **disposable index retention** and **evidence/audit retention**.

74
history/FIAM_v0.2_Draft6/CATALOG-EXCHANGE-PROFILE-v0.2.md Normal file
View file

@ -0,0 +1,74 @@
# FIAM v0.2 — Catalog Exchange Profile
## Purpose
The Catalog Exchange Profile is the **versioned operational interchange contract** between FIAM adapters and persistent architecture catalogs. It makes the runtime/catalog extensions public and stable without changing the frozen FIAM Core.
FIAM Core models remain the architecture/evidence exchange form for hand-authored and reconstructed models. Catalog Exchange documents are optimized for incremental catalog ingestion, replay, audit, and index rebuild.
## Envelope
Every exchange document contains:
```yaml
catalog_exchange_version: '0.2'
profile_id: fiam.catalog-exchange.v0.2
exchange_id: exchange.<stable-hash>
created_at: 2026-09-09T12:00:00Z
source:
source_id: collector.prod.app-traces
source_kind: otlp-adapter
source_ref: estate://collector/app-traces
observation:
mode: incremental # incremental | complete-snapshot | declared-snapshot
observation_scope: prod-cluster-a-app-traces
population_id: prod-cluster-a
population: {environment: prod, cluster: cluster-a}
domains: [http, rpc]
snapshot_time: 2026-09-09T12:00:00Z
records:
entities: []
assertions: []
zone_memberships: []
runtime_aggregates: []
topology_observations: []
unresolved: []
reconciliation_candidates: []
```
For `complete-snapshot`, the source and observation scope MUST be authorized by the Snapshot Authority Policy. Incremental documents never close absence.
## Record stability
Within the v0.2 line:
- existing field meanings MUST NOT be silently changed;
- new optional fields may be added;
- `catalog_exchange_version` changes if an incompatible exchange change is required;
- Core entity payloads are carried unchanged inside `records.entities[*].entity`;
- assertions preserve their complete Core assertion/evidence payload;
- topology and aggregate records use stable architectural identifiers rather than span ids.
## Zone membership
`zone_memberships` is explicit in the exchange profile because it is required for temporal boundary queries. Deployment environment, cluster, and Kubernetes namespace membership SHOULD be derived automatically from runtime identity tuples. Trust and organization Zones remain declared knowledge unless a separate authoritative source provides them.
## Streaming serialization
The canonical logical model is the envelope above. The same content may be serialized as NDJSON:
```text
{"record_type":"header", ...}
{"record_type":"entity", ...}
{"record_type":"assertion", ...}
{"record_type":"topology", ...}
...
```
An index may ingest this stream directly. It need not create or rewrite a whole FIAM YAML model for every telemetry batch.
## Rebuildability
A Catalog Index MUST be rebuildable from a retained sequence of Catalog Exchange documents plus referenced FIAM declared artifacts. SQLite/PostgreSQL/graph indexes are projections; exchange documents and their original evidence references remain the audit surface.
Index export is supported for inspection and checkpointing, but an exported index view does not replace the original evidence-bearing exchange history.

24
history/FIAM_v0.2_Draft6/CONFORMANCE.txt Normal file
View file

@ -0,0 +1,24 @@
FIAM v0.2-draft.6 Catalog Operations & Policy conformance: PASS
CORE-FREEZE PASS byte-identical frozen v0.2 Core
SEMANTIC-CORPUS PASS 26 specimens
SNAPSHOT-AUTHORITY-POLICY PASS validated scoped authority grants
CATALOG-EXCHANGE PASS versioned exchange fixtures
AUTHORITY-GRACE PASS first missing complete snapshot does not close recent/once-missing edge
AUTHORITY-CLOSURE PASS last_seen evidence remains distinct from closed_at policy action
TEMPORAL-QUERY PASS appeared/disappeared/newly-undeclared with governed closure
BOUNDARY-DRIFT PASS trust + organization crossing
POLICY-INTELLIGENCE PASS undeclared partner dependency is high-materiality + policy violation under named policy
TEMPORAL-REAPPEARANCE PASS closed history preserved and new interval opened
QUERY-TIME-SCORING PASS index stores raw evidence, not policy scores
RETENTION PASS explicit purge affects derived index only
AUTHORITY-DOMAIN PASS HTTP completeness cannot close RPC
MULTI-SCOPE PASS app scope closes while mesh scope keeps one logical dependency active
AUTHORITY-OWNERSHIP PASS source cannot claim another source observation scope
DECLARATION-MATCHING PASS Channel + gateway intended target + working-set preferred ids
ZONE-DERIVATION PASS deployment identity automatically yields environment/cluster/namespace memberships
OPERATION-COVERAGE PASS observed + dormant + never-observed declared capabilities
SECURITY-EVIDENCE-COVERAGE PASS declared auth + observed operation remains runtime-security unknown
EVIDENCE-HEALTH PASS conflict + challenge + stale evidence; scoring policy id/hash explicit
INDEX-NATIVE-INGEST PASS NDJSON direct write + replay idempotency + Catalog Exchange export
SET-ORIENTED-INDEX PASS 1000 logical edges via direct Catalog Exchange (not a performance benchmark)
ADVERSARIAL-FIAM PASS existing semantic rejection suite

15
history/FIAM_v0.2_Draft6/DECLARATION-MATCHING-v0.2.md Normal file
View file

@ -0,0 +1,15 @@
# FIAM v0.2 — Declaration Matching Contract
`declared` is not a shortcut for “the runtime target node appears in a `uses` assertion.” It is a time-aware graph query.
For a runtime logical edge `(from, target, domain, channel?, intended_target?)` at time `T`:
1. project observed identifiers through the non-destructive working-set mapping effective at `T`;
2. select the latest declared snapshot from each declaration source effective at `T` and applicable to the edge population;
3. resolve declaration subjects/objects to architectural owners where appropriate;
4. consider the runtime target, intended target, and mediating Channel as valid declaration surfaces according to domain;
5. return the matching declaration ids and reasons, not only a boolean.
A mediated messaging edge may therefore be declared by `Producer --uses--> Channel` even if the runtime topology view also resolves a downstream consumer. A gateway-mediated runtime edge is declared when the intended target is declared even though the observed responder is the gateway. An observed identifier and its preferred declared working-set identity are treated as the same query-time navigation target without merging the source records.
Ambiguous or absent declarations remain explicit findings. The declaration matcher never creates `same-entity-as` and never changes evidence.

94
history/FIAM_v0.2_Draft6/DECLARED-OBSERVED-LENS-v0.2.md Normal file
View file

@ -0,0 +1,94 @@
# 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:
```text
observed -- corresponds-to --> declared
```
Reconciliation also exposes scored candidate lists even when no correspondence is safe.
This lets the Lens distinguish:
```text
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:
```text
declared: fiam.protocol.http
observed: fiam.protocol.http2
=> compatible-refinement
```
while:
```text
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:
```text
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.

85
history/FIAM_v0.2_Draft6/EVIDENCE-SCORING-v0.2.md Normal file
View file

@ -0,0 +1,85 @@
# FIAM Evidence Scoring v0.2
## Intent
FIAM preserves evidence records rather than collapsing observations into one current fact. Architecture-intelligence tools still need to rank claims, conflicts, and stale evidence.
Evidence strength is therefore a **query-time heuristic under an explicit policy**. It is neither a canonical FIAM property nor a calibrated probability of truth.
## Persistence rule
The Architecture Intelligence Index stores raw assertion/evidence payloads only. It MUST NOT persist canonical columns such as:
```text
support_score
challenge_score
net_support
```
Every scored result must identify the exact scoring policy id and SHA-256. Re-evaluating the same raw evidence under another policy is a new query interpretation, not an estate change.
## Inputs
The reference policy uses existing evidence fields:
```text
confidence
mode
source type
source ref / locator
stance
observed_at
```
## Per-record strength
Conceptually:
```text
strength = confidence
* mode_weight
* source_type_weight
* freshness_factor
```
Factors are bounded to `[0,1]`. Runtime/inferred evidence may decay for ranking; declared/static evidence has no default freshness decay. Decay never deletes or invalidates historical evidence.
## Independence
Repeated evidence from one evidential source must not masquerade as independent corroboration.
Default independence key:
```text
mode
source.type
source.ref
source.locator
```
The strongest record in each independence group contributes. Independent supports combine via bounded noisy-OR:
```text
support = 1 - product(1 - strength_i)
```
Challenges combine separately. `net_support = support - challenge` is only a ranking convenience.
## Evidence Health Lens
`fiam.lens.evidence-health` uses the scoring policy to surface operational questions rather than to rewrite facts:
- conflicting supported values for one subject/predicate;
- facts with challenging evidence;
- runtime-only claims whose latest evidence is stale;
- low-support claims.
The reference fixture yields one of each category and includes the policy id/hash in its result.
## Governance
Reference policy:
`policies/EVIDENCE-SCORING-v0.2.yaml`
Organizations may tune weights and freshness windows. Different policies may legitimately rank the same evidence differently; this is why scores are deliberately excluded from the stored assertion table.

255
history/FIAM_v0.2_Draft6/FIAM-v0.2-Draft6.md Normal file
View file

@ -0,0 +1,255 @@
# FIAM v0.2-draft.6 — Catalog Operations & Policy
## Status
FIAM v0.2-draft.6 hardens the **operating contract** around the frozen v0.2 Core. It does not add Core entities or change Core semantics. The focus is authority, exchange, incremental persistence, temporal truth, declaration matching, policy projections, evidence health, and practical estate queries.
The Core freeze remains intentional: difficult operational cases are first solved in adapters, profiles, policies, indexes, or lenses. A new Core concept should be considered only after those layers demonstrably cannot express the problem.
## 1. Architectural boundary
Draft.6 separates four layers explicitly:
```text
FIAM Core model
stable architectural facts + evidence-bearing assertions
Catalog Exchange Profile
versioned operational records for incremental/replayable catalog ingestion
Architecture Intelligence Index
rebuildable temporal/query projection over retained exchange artifacts
Lenses + Policies
named, versioned interpretations: drift, materiality, compliance, dormancy,
evidence health, security coverage
```
The index is never the sole evidence store, and a Lens result is never silently promoted into a Core fact.
## 2. Authoritative snapshot governance
Completeness is no longer an ingestion flag. A `complete-snapshot` is accepted only when a validated Snapshot Authority Policy grants a source authority for an exact combination of:
- source id;
- observation scope;
- architectural population;
- covered domains;
- optional population qualifiers such as environment, cluster, and platform.
A complete HTTP/RPC snapshot cannot close messaging or database observations merely because those observations occur in the same cluster. A source can close only its own observation scope.
The reference policy requires both:
```text
consecutive missing complete snapshots >= absence_snapshots
snapshot_time - last_seen >= grace_hours
```
before an observation interval closes. `last_seen` remains evidence time; `closed_at` records the later policy action. A reappearance opens a new interval rather than rewriting history.
Multiple collectors that observe the same architectural dependency normally use distinct observation scopes. Their active observations are unioned into one logical topology edge. Closing one collector therefore does not close the logical dependency while another still observes it.
Shared observation-scope ownership is rejected unless a layered policy explicitly defines precedence. In the reference implementation only the highest-precedence source is allowed to make the closing completeness claim for such a layered scope.
## 3. Catalog Exchange Profile
The former runtime extension bags are now an explicit, versioned operational interchange profile:
```text
fiam.catalog-exchange.v0.2
```
The profile carries:
- Core entities;
- Core assertions/evidence;
- temporal Zone memberships;
- runtime aggregates;
- topology observations;
- unresolved observations;
- reconciliation candidates;
- declaration inventory.
YAML and JSON remain useful audit/export forms. NDJSON provides a direct streaming write path:
```text
OTLP / OpenAPI / other adapter
↓
Catalog Exchange records
↓
persistent FIAM index
```
A continuous catalog therefore does **not** need to rewrite an ever-growing FIAM YAML document per batch. The index can export Catalog Exchange checkpoints for inspection, while retained source/exchange history remains the rebuild/audit surface.
## 4. Observation identity and scope
Architectural edge identity excludes collector identity. Observation state does not.
```text
logical edge: Orders -> Inventory
observation scope A: application traces active/closed independently
observation scope B: service mesh active/closed independently
```
The population-level logical edge stays active while at least one valid observation scope remains active. This prevents both duplicate logical dependencies and one platform collector erasing another platform's evidence.
Deployment-oriented Zone membership is derived from runtime identity tuples where possible:
```text
environment -> deployment-environment Zone
cluster -> cluster Zone
namespace -> Kubernetes-namespace Zone
```
Trust and organization Zones remain declared/governed knowledge unless a separately authoritative source supplies them.
## 5. Declaration matching as a graph query
“Declared” is no longer equivalent to “the source node has a direct `uses` relation to the exact runtime target id.” The declaration matcher evaluates the historical graph at the edge timestamp using:
- non-destructive working-set identity;
- direct target and intended target;
- mediated Channel;
- owner projections;
- domain-appropriate declared relations.
The included fixtures prove three cases that must **not** create false undeclared findings:
1. the producer declares the Channel while runtime topology resolves a downstream consumer;
2. the client declares the intended server while runtime traverses a gateway;
3. the declaration uses an observed id while the working-set projection prefers a declared id.
Ambiguity remains explicit rather than forcing a match.
## 6. Query-time evidence strength
Evidence strength remains a Lens heuristic. The persistent assertion table stores raw assertions/evidence only; it has no canonical `support_score`, `challenge_score`, or `net_support` columns.
Every scored result names:
```text
policy id
policy SHA-256
query/evaluation time
```
Changing evidence policy therefore changes a query interpretation, not the recorded estate. Duplicate evidence from one independence group does not masquerade as independent corroboration.
## 7. Policy intelligence
Draft.6 formalizes the distinction between facts and governance conclusions.
A newly observed dependency can have factual properties such as:
```text
undeclared = true
crosses trust boundary = true
crosses organization boundary = true
observation count = 12
```
A named governance policy may then classify it as material or non-compliant. The reference policy assigns the included `Orders -> Partner API` dependency a materiality score of `0.75` (`high`) and reports one high-severity violation because internal-to-partner trust-zone access requires declaration.
Those are **policy results**, not universal FIAM truth. Another organization can apply different weights/rules to the same evidence without changing the catalog.
## 8. First operational questions
The draft.6 reference fixtures now answer the four architecture-control questions that motivated this increment.
### Which new undeclared dependencies are material?
Included fixture:
```text
new dependencies 1
material dependencies 1
policy violations 1
```
`Orders -> Partner API` is undeclared and crosses both trust and organizational boundaries, producing reference-policy materiality `0.75 / high`.
### Which boundary crossings violate intended architecture?
The Boundary Drift Lens reports the descriptive crossing. The Architecture Policy Lens separately applies the named rule:
```text
require-declaration-internal-to-partner
severity: high
```
and reports the undeclared partner dependency as a violation.
### Which declared capabilities have been dormant for 90 days?
The operation-coverage fixture reports:
```text
observed in window 1
dormant 1
never observed 2
```
Dormant means previously observed but not within the evaluation window; never-observed remains distinct.
### Which facts rely on stale or conflicting evidence?
The evidence-health fixture reports:
```text
conflicting facts 1
challenged facts 1
stale runtime-only 1
low support 1
```
Scores are computed from raw evidence under the named evidence policy at query time.
A separate security-evidence query demonstrates an important open-world case: an operation may have declared authentication requirements and runtime activity while generic telemetry provides **unknown** runtime authentication evidence. Unknown is not converted to “unprotected.”
## 9. Snapshot and index retention
Index retention is operational and reversible. Closed intervals, entity versions, assertions, and evidence may be purged from the derived index only through an explicit derived-index purge operation. Such a purge must not modify or delete retained Catalog Exchange/source artifacts.
Historical queries older than the retained index horizon then require rebuilding from those retained artifacts. This keeps index retention and evidence/audit retention separate.
## 10. Conformance meaning
A draft.6 PASS means more than schema compatibility. It verifies:
- frozen Core hash;
- 26 semantic specimens;
- scoped authority and grace semantics;
- distinct `last_seen` and `closed_at` clocks;
- domain-specific completeness;
- multi-scope union and unauthorized authority rejection;
- Channel/gateway/working-set declaration matching;
- automatic deployment Zone derivation;
- operation dormancy and never-observed coverage;
- security-runtime unknown preservation;
- stale/conflicting evidence findings with policy hash;
- index-native NDJSON ingest, replay idempotency, and Catalog Exchange export;
- derived-index retention safety;
- direct set-oriented Catalog Exchange ingestion;
- existing FIAM semantic adversarial cases.
The set-oriented test is a conformance smoke test, **not** a performance benchmark.
## 11. What remains outside the Core
Draft.6 deliberately does not introduce:
- Session;
- domain-specific interface entities such as `GrpcInterface`;
- schema fields on `InformationShape`;
- automatic destructive entity merge;
- stored truth probabilities;
- global authoritative snapshots.
The remaining engineering work is increasingly a catalog/service problem: durable exchange retention, concurrency, operational deployment, broader declared-source adapters, policy administration, and estate-scale query optimization.
## 12. Recommended next milestone
The natural next milestone is no longer another FIAM draft driven by ontology. It is a **reference architecture-intelligence service** implementing this operating contract against a durable production-oriented store (for example PostgreSQL), with Catalog Exchange as the ingestion boundary and the existing lenses as an initial query API.

71
history/FIAM_v0.2_Draft6/IDENTITY-RECONCILIATION-v0.2.md Normal file
View file

@ -0,0 +1,71 @@
# FIAM v0.2 — Identity and Reconciliation Policy
## Principle
Discovery must not erase uncertainty.
FIAM therefore separates:
```text
correspondence
identity equivalence
working-set preference
physical merge
```
These are not synonyms.
## `corresponds-to`
`fiam.relation.corresponds-to` means two records plausibly describe the same architectural concern or exposure strongly enough to compare/project together.
Runtime reconciliation produces this relation only for a strong unique candidate.
Candidate search may still produce:
```text
ambiguous
near-match
unmatched
```
without asserting correspondence.
## `same-entity-as`
This is a stronger identity statement governed by the existing Shape/Entity identity rules.
An inferred `same-entity-as` requires multiple independent signals at high confidence. A single structural/name fingerprint is insufficient.
Even `same-entity-as` does not authorize destructive record deletion.
## Runtime deployed identity
Runtime SystemNode identity is an architectural deployment tuple, not merely `safe(service.name)`.
It combines service namespace/name with available deployment/cluster/namespace/cloud context so production and staging observations do not collapse into one node.
## Working set
A high-confidence correspondence can produce a declared-preferred working reference for navigation.
The observed entity remains attached with evidence and is never silently rewritten.
See `WORKING-SET-v0.2.md`.
## Reconciliation candidate visibility
Every adapter should prefer a scored candidate list over silent matching failure.
Candidate metadata should explain the signals used, such as:
- service name / namespace;
- protocol/system;
- HTTP method;
- normalized route similarity;
- declared/observed host;
- RPC method;
- messaging destination;
- database namespace/collection.
Ambiguity is therefore a queryable architecture finding.

66
history/FIAM_v0.2_Draft6/MIGRATION-v0.1.1-to-v0.2.md Normal file
View file

@ -0,0 +1,66 @@
# FIAM Migration — v0.1.1 to v0.2
## Structural additions
Add `information_resources[]` and `information_shapes[]` when the architecture contains independently meaningful information loci or admissible information forms.
Do not add them mechanically to every interface. Incomplete models remain valid.
## InformationShape
`shape_kind` is required for v0.2 shapes. Use `fiam.information-shape.object` for structured named-member forms; the experimental `record` term is deprecated.
Keep fine-grained members and constraints in schema/type Artifacts (OpenAPI, JSON Schema, protobuf, GraphQL, DDL, source declarations). FIAM Core identifies and relates the shape; it does not reimplement those schema languages.
## Representation
Remove authoritative use of `contracts[].representations` and `contracts[].operations[].representations`. These fields remain parseable only to support migration and produce warnings.
Attach representation to the most specific shape-participation relation: Operation for a semantic default only when appropriate, Binding for a realization, Interaction for what actually occurred.
## Shape relations
Use:
- `accepts-shape`
- `produces-shape`
- `errors-with-shape`
- `conforms-to-shape`
- `element-shape`
- `embeds-shape`
Binding-level shape participation on a Binding with multiple operations requires `facets.operation_ref`.
## Shape composition
`embeds-shape` and `element-shape` may carry `facets.slot` and `facets.role`. These are coarse architectural anchors, not a replacement for field-level schema definitions.
## Evidence
All v0.2 Assertions require evidence. Preserve conflicting/superseded assertions rather than overwriting discovery history.
## Identity
Follow `policies/FIAM-ShapeIdentity-v0.2.md`. Prefer `corresponds-to` while two discoveries are only candidate matches. Use `same-entity-as` only with sufficient evidence. Identity assertions do not delete source records.
## Specimen tests
v0.2 `tests.expected_properties` are executable checks. Move narrative expectations to `tests.notes`.
## draft.1 hardening notes
### Family labels
Do not manually carry forward `family_labels` as authoritative classifications. Either remove them or back each cached label with an inferred `fiam.property.family-label` assertion produced by a Lens. The validator rejects unproven family-label caches.
### Shape refinement
When migrating shape participations, verify Operation → Binding → Interaction refinement. A lower-level Shape must be the same/equivalent Shape or be related by `projection-of` / `version-of` to the parent declaration.
### Collection coherence
Collection-like InformationResources that use `conforms-to-shape` should point to a collection Shape. Use a separate `element-shape` relation for member shape.
### Identity
Do not convert similarity heuristics into `same-entity-as`. Ingest/reconciliation tools should emit `corresponds-to` until sufficient governed identity evidence exists. Purely inferred `same-entity-as` is rejected unless the current Canon evidence threshold is met.

51
history/FIAM_v0.2_Draft6/Makefile Normal file
View file

@ -0,0 +1,51 @@
.PHONY: check estate-check validate specimens exchange authority catalog-example policy-example runtime runtime-multidomain topology lens security reconcile working-set
check estate-check:
python3 tools/check_all.py
validate:
python3 tools/validate_fiam.py
specimens:
python3 tools/validate_fiam.py $$(find specimens -name '*.yaml' | sort)
authority:
python3 tools/validate_authority_policy.py policies/SNAPSHOT-AUTHORITY-v0.2.yaml
exchange:
python tools/catalog_exchange.py convert real-world/catalog-exchange/runtime-2026-09-01.yaml -o /tmp/fiam-runtime.ndjson --input-format yaml --format ndjson
catalog-example:
rm -f /tmp/fiam-estate.sqlite
python tools/catalog_index.py ingest-exchange /tmp/fiam-estate.sqlite real-world/catalog-exchange/declared-2026-09-01.yaml
python tools/catalog_index.py ingest-exchange /tmp/fiam-estate.sqlite real-world/catalog-exchange/runtime-2026-09-01.yaml --authority-policy policies/SNAPSHOT-AUTHORITY-v0.2.yaml
python tools/catalog_index.py ingest-exchange /tmp/fiam-estate.sqlite real-world/catalog-exchange/runtime-2026-09-08.yaml --authority-policy policies/SNAPSHOT-AUTHORITY-v0.2.yaml
python tools/catalog_index.py ingest-exchange /tmp/fiam-estate.sqlite real-world/catalog-exchange/runtime-2026-09-09.yaml --authority-policy policies/SNAPSHOT-AUTHORITY-v0.2.yaml
python tools/architecture_changes_lens.py /tmp/fiam-estate.sqlite --population prod-cluster-a --since 2026-09-07T00:00:00Z --until 2026-09-09T23:59:59Z -o /tmp/fiam-changes.yaml
policy-example: catalog-example
python tools/architecture_policy_lens.py /tmp/fiam-estate.sqlite --population prod-cluster-a --since 2026-09-07T00:00:00Z --until 2026-09-09T23:59:59Z --policy policies/ARCHITECTURE-GOVERNANCE-v0.2.yaml -o /tmp/fiam-policy.yaml
runtime:
python tools/otel_to_fiam.py real-world/otel/petstore-get-pet-http2.otlp.json --base real-world/openapi/petstore-identity-excerpt.fiam.yaml -o real-world/composite/petstore-openapi-plus-otel.fiam.yaml
runtime-multidomain:
python tools/otel_to_fiam.py real-world/otel/multidomain-runtime.otlp.json -o real-world/otel/multidomain-runtime.fiam.yaml
topology: runtime-multidomain
python tools/runtime_topology_lens.py real-world/otel/multidomain-runtime.fiam.yaml -o real-world/otel/multidomain-runtime.topology.yaml --markdown real-world/otel/multidomain-runtime.topology.md
lens:
python tools/declared_observed_lens.py real-world/composite/security-api-declared-plus-observed.fiam.yaml -o real-world/composite/security-api-declared-plus-observed.lens.yaml --markdown real-world/composite/security-api-declared-plus-observed.lens.md
security:
python tools/openapi_to_fiam.py real-world/openapi/estate-hardening/security-api.yaml -o real-world/openapi/estate-hardening/security-api.fiam.yaml
python tools/security_coverage_lens.py real-world/openapi/estate-hardening/security-api.fiam.yaml -o real-world/openapi/estate-hardening/security-api.security-coverage.yaml
working-set:
python tools/working_set_view.py real-world/composite/gateway-rpc.fiam.yaml -o real-world/composite/gateway-rpc.working-set.yaml
reconcile:
python tools/otel_to_fiam.py real-world/otel/grpc-runtime.otlp.json --base specimens/regression/04-grpc-bidirectional-stream.yaml -o real-world/composite/grpc-declared-plus-runtime.fiam.yaml
python tools/otel_to_fiam.py real-world/otel/kafka-runtime.otlp.json --base specimens/regression/06-kafka-topic.yaml -o real-world/composite/kafka-declared-plus-runtime.fiam.yaml
python tools/otel_to_fiam.py real-world/otel/postgres-runtime.otlp.json --base specimens/regression/03-shared-postgresql-table.yaml -o real-world/composite/postgres-declared-plus-runtime.fiam.yaml

87
history/FIAM_v0.2_Draft6/OPENAPI-INGEST-v0.2.md Normal file
View file

@ -0,0 +1,87 @@
# FIAM v0.2 — OpenAPI Declared-Ingest Profile (draft.4)
## Intent
Turn an OpenAPI 3.x description into a FIAM **declared architecture model** while preserving the distinction between architectural entities and the source artifact.
The importer is architecture-oriented, not a lossless OpenAPI converter. Detailed schema semantics remain in the OpenAPI Artifact.
## Mapping
| OpenAPI construct | FIAM expression |
|---|---|
| API document | `Artifact` (`fiam.artifact.api-description`) |
| API/service | `SystemNode` + offered `Port` + `InterfaceContract` |
| path + HTTP method | `Operation` |
| server URL | `Endpoint` |
| HTTP realization | `Binding` + communication stack |
| path template | logical-selection `InformationResource` |
| component or inline schema | `InformationShape` |
| response/request schema | Shape-participation relations |
| media type | relation-scoped `representation` |
| object/array composition | coarse `embeds-shape` / `element-shape` |
| source location | assertion Evidence locator |
| HTTP method | declared property assertion |
| generic HTTP family | declared `communication-protocol` assertion |
| `components.securitySchemes` | FIAM Security profiles |
| top-level / operation `security` | contract/operation Security requirements |
## Evidence
Relations and material property facts emitted from OpenAPI carry declared evidence with the source Artifact and JSON-pointer locator.
Observer:
```text
openapi-ingest/v0.2-draft.4
```
## Transport conservatism
An `https://` server URL declares secure HTTP addressing. It does **not** determine TCP versus QUIC, because the OpenAPI document normally does not state the negotiated HTTP version/transport.
Draft.4 therefore emits:
```text
HTTP
TLS
```
for an HTTPS declaration, but does not infer TCP.
This preserves the transport-conservative behavior introduced after draft.1.
## Shape identity
The importer reuses a FIAM Shape for repeated references to the same OpenAPI component identity. Different components remain distinct even when structurally identical.
Structural fingerprint equality emits only:
```text
Shape A --corresponds-to--> Shape B
```
never automatic `same-entity-as`.
## Current scope
Supported:
- OpenAPI 3.x YAML/JSON;
- component and common inline Shapes;
- coarse shape composition;
- request/response shape participation;
- common representations;
- server endpoints and HTTP/TLS stack;
- path-template Resources;
- evidence-backed HTTP method and generic protocol facts;
- structural-fingerprint candidate alignment;
- local OpenAPI security schemes and Security Requirement composition (see `OPENAPI-SECURITY-INGEST-v0.2.md`).
Not yet a goal:
- lossless parameter/schema conversion;
- complete external `$ref` resolution;
- full callback/webhook flows;
- automatic identity merge;
- schema fields in FIAM Core.

90
history/FIAM_v0.2_Draft6/OPENAPI-SECURITY-INGEST-v0.2.md Normal file
View file

@ -0,0 +1,90 @@
# FIAM v0.2 — OpenAPI Security Ingest Profile
## Purpose
Map declared OpenAPI security schemes and Security Requirement Objects into FIAM Security profiles without collapsing security into interface-family names.
## Supported Security Scheme families
The draft.4 adapter recognizes:
- `apiKey`;
- `http` Basic;
- `http` Bearer;
- `oauth2`;
- `openIdConnect`;
- `mutualTLS`.
These map to FIAM authentication/credential terms while preserving the original scheme metadata as facets.
## Requirement semantics
The adapter preserves OpenAPI requirement composition.
Within one Security Requirement Object:
```text
scheme A + scheme B = both required
```
Across multiple Security Requirement Objects:
```text
requirement 1 OR requirement 2
```
An empty requirement object `{}` represents an anonymous-access alternative.
Operation-level `security` overrides top-level security. An empty operation list `security: []` removes inherited security for that operation.
## FIAM profiles
Top-level requirements create Security profiles applying to the InterfaceContract.
Operation-level requirements create Security profiles applying to the Operation.
Profiles retain, where applicable:
- source scheme name/type;
- alternative number;
- required scopes;
- API-key location/name;
- OAuth flow names;
- OpenID Connect discovery URL;
- credential / transport-security semantics.
## Effective-security Lens
`tools/security_coverage_lens.py` evaluates effective declared security per operation.
Current classes:
```text
inherited-contract-security
operation-specific
anonymous-access-allowed
explicitly-unprotected
no-declared-security
```
The fixture `real-world/openapi/estate-hardening/security-api.yaml` covers the first four classes.
## Runtime boundary
Generic HTTP OTLP spans do not establish whether application authentication occurred.
Therefore the absence of an authentication-specific telemetry signal is **unknown**, not evidence of unprotected access.
A future runtime security source may enrich these same FIAM Security profiles/assertions; no Core change is implied.
## Current limitations
The reference OpenAPI adapter does not yet fully resolve:
- external `$ref` documents;
- callbacks and webhooks;
- all Server Object variable expansion;
- security schemes declared by external URI rather than local component reference;
- APIs intentionally split across multiple OpenAPI files.
These are adapter/composition concerns and remain outside the frozen Core.

145
history/FIAM_v0.2_Draft6/OTEL-INGEST-v0.2.md Normal file
View file

@ -0,0 +1,145 @@
# FIAM v0.2 — OpenTelemetry Runtime-Ingest Profile
## Intent
Map OpenTelemetry trace observations into an **incremental FIAM architecture catalog** without pretending telemetry is a complete architecture description and without mirroring every span as a permanent architectural Interaction.
The full estate aggregation and identity rules are normative in `RUNTIME-CATALOG-v0.2.md`.
## Standards basis
Draft.4 targets the current OpenTelemetry semantic-convention families used by the reference implementation:
- service/resource conventions — https://opentelemetry.io/docs/specs/semconv/resource/service/
- deployment environment — https://opentelemetry.io/docs/specs/semconv/resource/deployment-environment/
- HTTP spans — https://opentelemetry.io/docs/specs/semconv/http/http-spans/
- RPC spans — https://opentelemetry.io/docs/specs/semconv/rpc/rpc-spans/
- gRPC — https://opentelemetry.io/docs/specs/semconv/rpc/grpc/
- messaging spans — https://opentelemetry.io/docs/specs/semconv/messaging/messaging-spans/
- database spans — https://opentelemetry.io/docs/specs/semconv/db/database-spans/
- Trace API / SpanKind — https://opentelemetry.io/docs/specs/otel/trace/api/
- OTLP — https://opentelemetry.io/docs/specs/otlp/
OTLP/JSON integer enum encoding is enforced for `Span.kind`.
## Default output model
```text
many spans
|
v
architectural runtime aggregates
|
+--> stable FIAM Nodes / Ports / Operations / Bindings
+--> Channels or InformationResources when observed
+--> idempotent runtime assertions
+--> bounded Interaction samples
+--> unresolved/candidate findings
```
## HTTP server
| OpenTelemetry | FIAM |
|---|---|
| service identity + deployment context | deployed SystemNode + Zones |
| HTTP `SERVER` span | runtime aggregate + optional sample Interaction |
| method + `http.route` | Operation |
| missing route | `unknown-route` Operation + unresolved finding |
| server address/port | Endpoint |
| actual HTTP version | Binding runtime property |
| `network.peer.*` | competing locator evidence |
| status/error | aggregate error count / sample result |
Raw `url.path` and raw span names do not become architecture identifiers.
The adapter does not infer TCP merely from HTTPS/HTTP because lower transport may differ, including with HTTP/3.
## RPC / gRPC
RPC client/server observations create required/offered participation and stable runtime aggregates.
`rpc.system.name` and `rpc.method` provide the primary semantic inputs. For gRPC, the Canon protocol term is used.
When both sides of a trace are available, parent/child correlation can produce a direct-call topology observation. A client span without its server child remains an unresolved partial dependency instead of inventing a responder.
`service.peer.name`, `server.address` and network peer attributes are treated as separate evidence signals.
## Messaging
OpenTelemetry messaging operation type and SpanKind remain separate.
Examples:
```text
create -> producer semantics
send -> producer/client transport semantics
receive -> consumer semantics even when SpanKind = CLIENT
process -> consumer semantics
settle -> control/client semantics
```
Destination identity creates/reuses a Channel. Producer/consumer continuation is inferred only when trace/span links support it.
A producer without a linked downstream span remains a valid Channel observation with an unresolved continuation.
## Database
Database spans can create:
```text
required Port
Binding + Endpoint
InformationResource (namespace and/or collection)
read/write/target relation
```
If neither a stable namespace nor collection is supplied, FIAM retains the operation/binding evidence and reports the resource target as unresolved.
### Privacy boundary
The adapter deliberately excludes:
- `db.query.text`;
- `db.query.parameter.*`;
- raw span names.
Architecture discovery should not silently become a copy of application data or sensitive query material.
## Incremental behavior
```bash
python tools/otel_to_fiam.py new-batch.json \
--base estate-catalog.yaml \
--source-url estate://collector/traces \
-o estate-catalog-next.yaml
```
Exact replay of a processed batch is byte-idempotent. New batches update aggregate counts and validity timestamps. For continuous operation, the preferred path is OTLP → architectural aggregation → Catalog Exchange/NDJSON → persistent index rather than repeatedly rewriting a whole FIAM YAML model.
Ordinary sampled batches never retract architecture. In draft.6 the OTEL-to-model adapter does not accept a naked completeness switch. Absence/closure is handled only after conversion to Catalog Exchange and validation against `policies/SNAPSHOT-AUTHORITY-v0.2.yaml`, where source, observation scope, population, domains, grace, and repeated absence are explicit.
## Reconciliation
With a declared base, the adapter produces scored reconciliation candidates.
HTTP candidate signals include:
- method;
- exact/normalized/near route;
- server address.
Other domains use protocol/system, method/operation, destination/resource and service/locator evidence appropriate to the domain.
A result is one of:
```text
matched | ambiguous | near-match | unmatched
```
Only a strong unique result generates `corresponds-to`.
## Gateway/mesh interpretation
Logical destination evidence is not automatically replaced by actual network-peer or responder evidence.
The topology layer can retain both and mark a runtime edge as gateway-mediated when the observed responder differs from the reconciled declared target.

46
history/FIAM_v0.2_Draft6/POLICY-INTELLIGENCE-LENSES-v0.2.md Normal file
View file

@ -0,0 +1,46 @@
# FIAM v0.2 — Policy Intelligence Lenses
These lenses deliberately separate **architectural facts** from **organizational decisions**.
## Materiality
A new dependency is not intrinsically “material.” The reference policy scores independent facts such as:
- undeclared status;
- trust-boundary crossing;
- organizational-boundary crossing;
- observation volume;
- independent observation-scope corroboration.
The result names the governance policy id and hash. Changing policy changes the decision projection, not FIAM history.
## Intended-boundary compliance
Boundary policy rules may forbid a Zone pair or require a declaration for that pair. The Lens evaluates the actual historical Zone memberships effective when the edge appeared.
A rule violation is a policy finding, never a replacement for the underlying Boundary Drift fact.
## Dormancy
Operation Coverage compares the latest effective declaration against runtime aggregate `last_seen` within a chosen window:
- `observed-in-window`;
- `dormant` — observed historically, not in the window;
- `never-observed`.
Dormancy does not prove that a capability is unused if the runtime observation population is incomplete.
## Evidence health
Evidence Health evaluates raw evidence at query time with a named scoring policy. It reports:
- competing supported values for one subject/predicate;
- challenged assertions;
- runtime-backed facts whose latest runtime evidence is stale;
- low-support facts.
Scores are not persisted as estate facts.
## Security evidence coverage
Declared authentication can coexist with runtime security evidence `unknown`. Generic OTLP is not interpreted as proof that authentication is absent. The Lens makes that coverage gap visible without inventing an unprotected state.

101
history/FIAM_v0.2_Draft6/README.md Normal file
View file

@ -0,0 +1,101 @@
# FIAM v0.2-draft.6 — Catalog Operations & Policy
Implementation draft of the **Faceted Interface Architecture Model** focused on safe continuous catalog operation and architecture-control queries.
`fiam_version` remains `0.2`. **The Core is frozen and byte-identical to the v0.2 draft baseline.** Draft.6 changes profiles, policies, index semantics, adapters, and lenses—not Core entities.
## What draft.6 adds
- scoped Snapshot Authority Policy: source + observation scope + population + domain;
- repeated-absence + grace closure, with `last_seen` distinct from `closed_at`;
- multi-scope observation union into one logical architectural edge;
- versioned **Catalog Exchange Profile** for YAML/JSON/NDJSON operational interchange;
- direct index-native Catalog Exchange ingest/export; whole-model YAML is no longer the operational write-ahead log;
- raw-evidence persistence with query-time scoring policy id/hash;
- generic declaration matching across Channel mediation, gateways, and working-set identities;
- automatic deployment environment/cluster/namespace Zone derivation from runtime identity tuples;
- Architecture Policy Lens for materiality and boundary-governance rules;
- Operation Coverage Lens for observed/dormant/never-observed declarations;
- Evidence Health Lens for conflict, challenge, staleness, and weak evidence;
- Security Evidence Coverage Lens that preserves runtime authentication **unknown**;
- explicit derived-index retention/purge contract.
## Main documents
- `FIAM-v0.2-Draft6.md` — design/status memo and operational decisions.
- `SNAPSHOT-AUTHORITY-v0.2.md` — completeness authority, overlap, clocks, and grace.
- `CATALOG-EXCHANGE-PROFILE-v0.2.md` — versioned operational exchange contract.
- `ARCHITECTURE-INTELLIGENCE-INDEX-v0.2.md` — derived persistent query plane.
- `DECLARATION-MATCHING-v0.2.md` — historical declaration matching semantics.
- `POLICY-INTELLIGENCE-LENSES-v0.2.md` — materiality, compliance, coverage, evidence health.
- `EVIDENCE-SCORING-v0.2.md` — query-time evidence-strength policy.
- `TEMPORAL-QUERY-LENSES-v0.2.md` — architecture change and boundary drift.
- `RUNTIME-CATALOG-v0.2.md` — aggregate/runtime catalog write path.
- `WORKING-SET-v0.2.md` — non-destructive preferred-id projection.
- `SEMANTIC-REGRESSION.md` — executable guarantees.
## Repository structure
```text
canon/ controlled vocabulary + semantic policies
schemas/ frozen Core plus profile/policy/result schemas
lenses/ executable Lens definitions
policies/ authority, evidence, governance, Core freeze, shape identity
specimens/ semantic regression corpus
real-world/ ingest, authority, declaration, catalog, and query fixtures
tools/ adapters, exchange/index tools, validators, lenses, harness
history/ previous draft memos
```
## Run conformance
```bash
make check
```
The checked result is `CONFORMANCE.txt`. The current reference run completes in roughly tens of seconds; the set-oriented fixture is a correctness smoke test, not a performance benchmark.
## Operational Catalog Exchange example
```bash
python tools/catalog_index.py ingest-exchange estate.sqlite \
real-world/catalog-exchange/runtime-2026-09-01.yaml \
--authority-policy policies/SNAPSHOT-AUTHORITY-v0.2.yaml
python tools/catalog_index.py ingest-exchange estate.sqlite \
real-world/catalog-exchange/runtime-2026-09-08.yaml \
--authority-policy policies/SNAPSHOT-AUTHORITY-v0.2.yaml
python tools/architecture_changes_lens.py estate.sqlite \
--population prod-cluster-a \
--since 2026-09-07T00:00:00Z --until 2026-09-09T23:59:59Z \
-o changes.yaml
```
Incremental feeds do not need completeness authority. A `complete-snapshot` is accepted only when its source/scope/population/domains are granted by the authority policy.
## Direct NDJSON path
```bash
python tools/catalog_exchange.py convert input.yaml -o stream.ndjson \
--input-format yaml --format ndjson
python tools/catalog_index.py ingest-exchange estate.sqlite stream.ndjson \
--format ndjson --authority-policy policies/SNAPSHOT-AUTHORITY-v0.2.yaml
```
## Reference architecture-control outputs
`real-world/catalog-operations/` contains reproducible outputs for:
- appeared/disappeared/newly-undeclared dependencies;
- trust/organization boundary drift;
- policy materiality and violation;
- 90-day operation dormancy/never-observed coverage;
- security runtime-evidence unknown;
- evidence conflict/challenge/staleness;
- Catalog Exchange export.
## Design posture
FIAM Core facts, Catalog Exchange records, index projections, and policy findings are deliberately separate. Do not add Core entities because an operational query is difficult. First ask whether the missing capability belongs to authority, exchange, indexing, reconciliation, evidence policy, Zone derivation, or a Lens.

47
history/FIAM_v0.2_Draft6/RUNTIME-CATALOG-v0.2.md Normal file
View file

@ -0,0 +1,47 @@
# FIAM v0.2 — Runtime Catalog Profile
The runtime catalog stores architectural aggregates, not a trace warehouse.
## Write path
Preferred continuous path:
```text
OTLP / runtime source
-> low-cardinality architectural aggregation
-> Catalog Exchange v0.2 records
-> persistent query index
```
Whole-model FIAM YAML remains an export/audit form and is not required for every batch.
## Identity
Runtime identity remains tuple-based and deployment-scoped. Raw paths/span names/query text are excluded from persistent identifiers.
Environment, cluster and Kubernetes namespace in the identity tuple produce derived Zone memberships in Catalog Exchange. Trust and organization Zones remain declared unless supplied by another authoritative source.
## Aggregation
Architectural aggregate tuple:
```text
(domain, role, operation, binding, local-node,
remote-node?, channel?, information-resource?)
```
Aggregate records carry count/error_count/first_seen/last_seen and bounded evidence samples. Catalog Exchange declares whether aggregate counters are `cumulative` or `delta`.
## Completeness
Ordinary runtime batches are `incremental`. They never close absence.
A `complete-snapshot` is valid only when its source has an explicit Snapshot Authority grant for the exact observation scope, population and domains. Closure follows grace and repeated-absence rules from `SNAPSHOT-AUTHORITY-v0.2.md`.
## Multi-source coverage
Different collectors covering one population use different observation scopes. The query index unions their observations into one logical architectural topology. Duplicate collector coverage therefore does not require duplicate Core entities and one collector cannot retract another collector's evidence.
## Privacy
The architecture catalog excludes raw query text/parameters, raw high-cardinality HTTP paths and raw span names. Occurrence systems remain the place to retrieve detailed telemetry under their own retention/access policy.

79
history/FIAM_v0.2_Draft6/RUNTIME-TOPOLOGY-LENS-v0.2.md Normal file
View file

@ -0,0 +1,79 @@
# FIAM v0.2 — Runtime Topology Lens
## Purpose
`fiam.lens.runtime-topology` projects **aggregated runtime observations** into architecture dependency edges while preserving different interaction mechanisms.
It does not require FIAM to retain every source span as an Interaction.
## RPC
When client/server trace evidence can be correlated:
```text
client SystemNode -> server SystemNode
```
If only one side is sampled, the partial dependency remains in the runtime catalog's unresolved findings rather than inventing an edge.
## Messaging
Span-link causality creates:
```text
producer SystemNode -> Channel -> consumer SystemNode
```
The Channel is not flattened into a direct service dependency.
A producer without a linked consumer still establishes production to the Channel, but downstream topology remains partial.
## Database
Database runtime aggregates and `reads-from` / `writes-to` / `targets` evidence project as:
```text
application SystemNode -> InformationResource
```
## Working-set projection
By default the Lens uses the non-destructive working-set view:
- a high-confidence observed->declared correspondence may display the declared id as preferred;
- the observed id is retained in the result;
- ambiguous mappings stay separate.
## Gateways and meshes
A reconciled intended target and an observed responder can coexist.
Example result:
```text
from: declared-client
to: observed-istio-proxy
via_gateway: true
gateway: observed-istio-proxy
intended_target: declared-server
```
This distinguishes deployment intermediaries from application ownership.
## Unresolved is not failure
The Lens result contains an unresolved section. Real sampled topology is expected to have unresolved observations.
The complete multi-domain fixture happens to resolve all five deterministic edges, but the estate conformance suite separately requires partial RPC, messaging, DB and HTTP cases to remain unresolved.
## Multi-domain proof
The deterministic fixture yields:
```text
RPC direct-call: 1
broker-mediated messaging: 2
database resource access: 2
```
All three are projected from one unchanged FIAM Core.

115
history/FIAM_v0.2_Draft6/SEMANTIC-REGRESSION.md Normal file
View file

@ -0,0 +1,115 @@
# FIAM v0.2-draft.6 Semantic and Operational Regression
## Core guarantee
`schemas/FIAM-Core-v0.2.schema.json` remains byte-identical to the frozen v0.2 Core. Draft.6 changes no Core entities.
## Semantic baseline
The harness retains the complete 26-specimen positive corpus and the existing adversarial suite. It continues to enforce Resource/Shape separation, evidence-backed relations, participation refinement, non-destructive identity, and the v0.2 Canon semantics.
## Snapshot authority regression
A complete runtime snapshot is valid only when a Snapshot Authority Policy grants its source the exact observation scope/population/domain claim.
The reference history proves:
```text
Sep 01 Inventory observed
Sep 08 Inventory absent in complete snapshot #1 -> remains active
Sep 09 Inventory absent in complete snapshot #2
and grace exceeded -> observation closes
Sep 10 Inventory observed again -> new interval opens
```
The closed interval preserves:
```text
last_seen = 2026-09-01 # evidence clock
closed_at = 2026-09-09 # policy-action clock
```
A complete HTTP-only snapshot must not advance absence/closure state for an RPC edge.
## Multi-scope regression
Application traces and service mesh observe the same logical Orders → Inventory dependency through separate observation scopes. Closing the application-trace observation must leave the logical dependency active while the mesh observation remains active.
A source attempting to claim another source's authoritative observation scope must be rejected.
## Declaration-matching regression
The harness verifies that runtime dependencies are treated as declared when declaration is expressed through:
1. the mediating Channel;
2. an intended server reached through a gateway;
3. an observed identity whose working-set projection prefers the declared identity.
None of these cases may be reported as newly undeclared.
## Zone derivation regression
A runtime identity tuple containing environment, cluster, and Kubernetes namespace must automatically produce the corresponding deployment Zone memberships. Trust and organization Zones are intentionally not inferred from those technical identifiers.
## Policy intelligence regression
The September estate fixture must produce:
```text
new dependencies 1
material dependencies 1
policy violations 1
```
The undeclared internal → partner dependency must classify as `high` materiality (`0.75`) under the named governance policy and violate the `require-declaration-internal-to-partner` rule.
## Coverage regression
For the included 90-day operation window:
```text
observed-in-window 1
dormant 1
never-observed 2
```
Security evidence coverage must preserve one observed operation with runtime authentication evidence classified as `unknown`, not “unprotected.”
## Evidence-health regression
Raw evidence is persisted without policy scores. Query-time evaluation under the named scoring policy must report exactly:
```text
conflicts 1
challenged 1
stale runtime-only 1
low support 1
```
The result must include the evidence-scoring policy id and SHA-256.
## Catalog Exchange regression
Catalog Exchange fixtures must validate against `FIAM-CatalogExchange-v0.2.schema.json`.
NDJSON must support:
```text
direct index ingest
exact replay -> already indexed
Catalog Exchange export
```
without requiring a whole-model YAML rewrite.
## Retention regression
An explicit derived-index purge may remove old index rows, but it must not mutate the source Catalog Exchange artifact used to rebuild those rows.
## Set-oriented persistence smoke test
The harness directly generates a 1,000-edge Catalog Exchange document and requires the index to expose 1,000 active logical topology edges. This is a correctness/conformance smoke test, **not** a throughput benchmark.
## Meaning of PASS
A green draft.6 run means the frozen Core can be operated through a governed, replayable catalog contract without letting completeness authority, collector overlap, identity projection, evidence scoring, or policy interpretation silently rewrite architectural history.

45
history/FIAM_v0.2_Draft6/SNAPSHOT-AUTHORITY-v0.2.md Normal file
View file

@ -0,0 +1,45 @@
# FIAM v0.2 — Authoritative Snapshot Governance
## Safety rule
An authoritative snapshot is a claim of **completeness for a named observation population, observation scope, and domain set**. It is never global and it is never inferred from a CLI flag alone.
Every complete snapshot MUST identify:
- `source_id` — the authority making the completeness claim;
- `observation_scope` — the stream whose absence state it owns;
- `population_id` and population qualifiers such as environment/cluster/platform;
- `domains` covered (`http`, `rpc`, `messaging`, `database`);
- `snapshot_time`;
- grace parameters or a reference to the authority policy.
A source may close only observations previously written in its own `observation_scope` and only for the domains named in the completeness claim. A complete HTTP/RPC snapshot cannot close Kafka observations merely because they share the same cluster.
## Overlap
Multiple collectors may cover the same architectural population. They MUST use distinct observation scopes unless an authority policy explicitly defines a layered precedence for one shared scope.
Query-time topology unions active observations across scopes into one logical architectural edge. Closing one scope therefore does not make the logical edge disappear while another scope still observes it.
Two authoritative sources attempting to own the same observation scope without an explicit layered rule MUST be rejected.
## Clocks and grace
`last_seen` is evidence time. `closed_at` is policy-action time. They are not interchangeable.
A missing edge is closed only when both conditions hold:
1. it has been absent from at least `absence_snapshots` consecutive complete snapshots for that scope/domain; and
2. `snapshot_time - last_seen >= grace_hours`.
Until then, the observation remains active with an increasing `absence_streak`.
A later reappearance opens a new observation interval and does not rewrite the closed interval.
## Default posture
Incremental ingestion is the default. Authoritative completeness MUST be declared through a validated authority profile; examples and wrappers SHOULD NOT expose a naked `--authoritative` switch as a normal operating path.
## Layered shared scopes
The preferred v0.2 operating model is one owner per `observation_scope`. If multiple sources are explicitly configured for one layered scope, the authority policy MUST provide precedence. The reference index permits closing completeness claims only from the highest-precedence source; lower-precedence sources must not independently retract that shared scope. This is intentionally stricter than silently unioning two sources under one scope.

89
history/FIAM_v0.2_Draft6/TEMPORAL-QUERY-LENSES-v0.2.md Normal file
View file

@ -0,0 +1,89 @@
# FIAM Temporal Query Lenses v0.2
## Observation time model
Temporal findings operate on **population-level logical topology intervals** derived from one or more scope-owned observation intervals.
Three clocks/contexts must remain distinct:
```text
first_seen / last_seen observed evidence time
snapshot_time completeness-evaluation time for one observation scope
closed_at policy-action time that closes one scope-owned interval
```
A missing incremental/sampled observation has no closing force. A complete snapshot may close only observations owned by its validated authority scope/domain, and only after the configured absence count plus grace period.
The logical architectural edge closes only when no covering observation scope remains active.
## Architecture Changes Lens
`fiam.lens.architecture-changes` operates over logical topology intervals for a named architectural population.
For `[since, until]` it returns:
### appeared
Logical intervals whose `valid_from` falls inside the window.
### disappeared
Logical intervals whose `valid_until` falls inside the window. Disappearance therefore represents governed absence, not simple sampling omission.
### newly-undeclared
Appeared dependencies for which the historical declaration matcher finds no satisfying declaration at the appearance time.
The matcher accounts for working-set identity, Channel mediation, intended targets/gateways, owners, and domain-appropriate declaration relations.
## Boundary Drift Lens
`fiam.lens.boundary-drift` evaluates Zone memberships effective at edge appearance time.
Default monitored Zone types include:
```text
trust-zone
organization
deployment-environment
cluster
```
A crossing is reported only when both sides have known membership for the monitored type and the memberships differ. Unknown Zone evidence remains unknown.
The crossing itself is descriptive. Policy compliance belongs to `fiam.lens.architecture-policy`.
## Example
Reference history:
```text
Sep 01 Orders -> Inventory
declared, internal trust/org
Sep 08 Orders -> Partner API appears
Inventory first missing complete snapshot (not yet closed)
Sep 09 Inventory second missing snapshot + grace -> closes
Partner remains active
```
Result for Sep 7–9:
```text
appeared 1
Orders -> Partner API
disappeared 1
Orders -> Inventory
newly undeclared 1
Orders -> Partner API
new trust crossings 1
new org crossings 1
```
## Temporal integrity
Declarations, Zone membership, entity ownership, and working identity are interpreted **as of the historical event time**. Later declarations or Zone moves must not retroactively make an old dependency declared or alter which boundary it crossed.

88
history/FIAM_v0.2_Draft6/WORKING-SET-v0.2.md Normal file
View file

@ -0,0 +1,88 @@
# FIAM v0.2 — Non-Destructive Working-Set Projection
## Problem
Evidence-preserving discovery intentionally creates separate declared and observed records:
```text
declared service
observed service
```
`corresponds-to` must not destroy either record, but forcing every operator and every Lens to manually choose between the two makes conservative identity unusable.
## Working-set rule
`tools/working_set_view.py` creates a projection, not a merge.
For a high-confidence, unique:
```text
observed --corresponds-to--> declared
```
the working set may choose the declared reference as the preferred navigation identity.
The projection records:
- observed reference;
- preferred declared reference;
- correspondence confidence;
- assertion id;
- `merged: false`.
## Non-destructive semantics
The projection does not:
- rewrite source ids;
- delete observed entities;
- assert `same-entity-as`;
- discard evidence;
- collapse ambiguous candidates.
It is therefore safe to rebuild at any time from the evidence graph.
## Ambiguity
When multiple candidates are too close, or correspondence confidence is below the threshold, no preferred id is chosen.
The ambiguity remains visible to query/lens consumers.
## Use in topology
The Runtime Topology Lens uses the working-set projection by default.
Example:
```text
observed client -> observed istio-proxy
| |
| corresponds | runtime responder
v v
declared client gateway/proxy
|
+---------- intended target ----------> declared server
```
Output can therefore report:
```text
from: declared-client
observed_from: observed-client
to: observed-proxy
via_gateway: true
intended_target: declared-server
```
This yields a usable architecture view without pretending the proxy and target are the same entity.
## Relationship to identity equivalence
`same-entity-as` remains a stronger identity assertion governed by the FIAM identity policy.
The working set does not need it. High-confidence correspondence is sufficient for **navigation preference**, not for ontological identity.
## Declaration matching
The working-set projection is also used by the draft.6 declaration matcher. A declaration attached to an observed identity or a declared preferred identity can satisfy the same historical dependency after non-destructive projection. The underlying ids and `corresponds-to` / `same-entity-as` evidence remain intact; the matcher does not merge records.

14
history/FIAM_v0.2_Draft6/adversarial-cases/01-deprecated-record.yaml Normal file
View file

@ -0,0 +1,14 @@
fiam_version: '0.2'
instance:
id: adversarial.deprecated-record
kind: specimen
title: Deprecated record kind
status: provisional
tests:
expected_properties:
- id: check.base
kind: no-deprecated-terms
information_shapes:
- id: shape.bad
kind: information-shape
shape_kind: fiam.information-shape.record

13
history/FIAM_v0.2_Draft6/adversarial-cases/02-missing-shape-kind.yaml Normal file
View file

@ -0,0 +1,13 @@
fiam_version: '0.2'
instance:
id: adversarial.missing-shape-kind
kind: specimen
title: Missing required shape kind
status: provisional
tests:
expected_properties:
- id: check.base
kind: no-deprecated-terms
information_shapes:
- id: shape.bad
kind: information-shape

29
history/FIAM_v0.2_Draft6/adversarial-cases/03-cross-kind-same-entity.yaml Normal file
View file

@ -0,0 +1,29 @@
fiam_version: '0.2'
instance:
id: adversarial.cross-kind-identity
kind: specimen
title: same-entity-as across kinds
status: provisional
tests:
expected_properties:
- id: check.evidence
kind: all-assertions-have-evidence
nodes:
- id: node.a
kind: system-node
node_type: fiam.node-type.application
information_shapes:
- id: shape.a
kind: information-shape
shape_kind: fiam.information-shape.object
assertions:
- id: assertion.bad
assertion_kind: relation
subject: node.a
predicate: fiam.relation.same-entity-as
polarity: asserted
object_ref: shape.a
evidence:
mode: fiam.evidence.declared
source: FIAM v0.2 semantic specimen
confidence: 0.98

30
history/FIAM_v0.2_Draft6/adversarial-cases/04-invalid-embed-facet.yaml Normal file
View file

@ -0,0 +1,30 @@
fiam_version: '0.2'
instance:
id: adversarial.invalid-embed-facet
kind: specimen
title: Invalid embed facet
status: provisional
tests:
expected_properties:
- id: check.evidence
kind: all-assertions-have-evidence
information_shapes:
- id: shape.a
kind: information-shape
shape_kind: fiam.information-shape.envelope
- id: shape.b
kind: information-shape
shape_kind: fiam.information-shape.object
assertions:
- id: assertion.bad
assertion_kind: relation
subject: shape.a
predicate: fiam.relation.embeds-shape
polarity: asserted
object_ref: shape.b
evidence:
mode: fiam.evidence.declared
source: FIAM v0.2 semantic specimen
confidence: 0.98
facets:
representation: fiam.representation.json

50
history/FIAM_v0.2_Draft6/adversarial-cases/05-ambiguous-binding-shape.yaml Normal file
View file

@ -0,0 +1,50 @@
fiam_version: '0.2'
instance:
id: adversarial.ambiguous-binding-shape
kind: specimen
title: Ambiguous binding shape participation
status: provisional
tests:
expected_properties:
- id: check.evidence
kind: all-assertions-have-evidence
nodes:
- id: node.s
kind: system-node
node_type: fiam.node-type.service
ports:
- id: port.s
owner: node.s
participations:
- contract: contract.c
mode: offers
contracts:
- id: contract.c
kind: interface-contract
operations:
- id: operation.a
- id: operation.b
bindings:
- id: binding.c
contract: contract.c
provider_port: port.s
operations:
- operation.a
- operation.b
information_shapes:
- id: shape.a
kind: information-shape
shape_kind: fiam.information-shape.object
assertions:
- id: assertion.bad
assertion_kind: relation
subject: binding.c
predicate: fiam.relation.produces-shape
polarity: asserted
object_ref: shape.a
evidence:
mode: fiam.evidence.declared
source: FIAM v0.2 semantic specimen
confidence: 0.98
facets:
representation: fiam.representation.json

21
history/FIAM_v0.2_Draft6/adversarial-cases/06-missing-evidence.yaml Normal file
View file

@ -0,0 +1,21 @@
fiam_version: '0.2'
instance:
id: adversarial.missing-evidence
kind: specimen
title: Assertion without evidence
status: provisional
tests:
expected_properties:
- id: check.base
kind: no-deprecated-terms
nodes:
- id: node.a
kind: system-node
node_type: fiam.node-type.application
assertions:
- id: assertion.bad
assertion_kind: property
subject: node.a
predicate: fiam.property.network-required
polarity: asserted
value: false

17
history/FIAM_v0.2_Draft6/adversarial-cases/07-legacy-operation-representation.yaml Normal file
View file

@ -0,0 +1,17 @@
fiam_version: '0.2'
instance:
id: adversarial.legacy-operation-representation
kind: specimen
title: Legacy operation representation
status: provisional
tests:
expected_properties:
- id: check.base
kind: no-deprecated-terms
contracts:
- id: contract.c
kind: interface-contract
operations:
- id: operation.a
representations:
- fiam.representation.json

16
history/FIAM_v0.2_Draft6/adversarial-cases/08-inline-shape-fields.yaml Normal file
View file

@ -0,0 +1,16 @@
fiam_version: '0.2'
instance:
id: adversarial.inline-shape-fields
kind: specimen
title: Inline fields on InformationShape
status: provisional
tests:
expected_properties:
- id: check.base
kind: no-deprecated-terms
information_shapes:
- id: shape.bad
kind: information-shape
shape_kind: fiam.information-shape.object
fields:
- name: x

43
history/FIAM_v0.2_Draft6/adversarial-cases/09-unexplained-operation-binding-mismatch.yaml Normal file
View file

@ -0,0 +1,43 @@
fiam_version: '0.2'
instance:
id: adversarial.operation-binding-mismatch
kind: specimen
title: Unexplained operation/binding mismatch
status: provisional
nodes:
- id: node.s
kind: system-node
node_type: fiam.node-type.service
ports:
- id: port.s.a
owner: node.s
participations:
- contract: contract.a
mode: offers
- id: port.s.b
owner: node.s
participations:
- contract: contract.b
mode: offers
contracts:
- id: contract.a
kind: interface-contract
operations:
- id: operation.a
- id: contract.b
kind: interface-contract
operations:
- id: operation.b
bindings:
- id: binding.a
contract: contract.a
provider_port: port.s.a
interactions:
- id: interaction.bad
kind: interaction
operation: operation.b
binding: binding.a
tests:
expected_properties:
- id: check.base
kind: no-deprecated-terms

252
history/FIAM_v0.2_Draft6/adversarial-cases/10-collection-conforms-object.yaml Normal file
View file

@ -0,0 +1,252 @@
fiam_version: '0.2'
instance:
id: adversarial.collection-conforms-object
kind: model
title: Kubernetes Pod collection and object
status: provisional
intent: Test API resource collection/object modeling while keeping representation kind/schema distinct from resource identity.
nodes:
- id: node.kubectl
kind: system-node
name: kubectl / API client
node_type: fiam.node-type.application
- id: node.apiserver
kind: system-node
name: Kubernetes API Server
node_type: fiam.node-type.service
ports:
- id: port.apiserver.api
owner: node.apiserver
participations:
- contract: contract.k8s-api
mode: offers
- id: port.kubectl.api
owner: node.kubectl
participations:
- contract: contract.k8s-api
mode: requires
contracts:
- id: contract.k8s-api
kind: interface-contract
purpose:
- fiam.purpose.transactional-data-access
- fiam.purpose.mutation
operations:
- id: operation.k8s.list-pods
name: list pods
effect: fiam.effect.read
- id: operation.k8s.watch-pods
name: watch pods
interaction_style: fiam.interaction-style.subscribe
- id: operation.k8s.patch-pod
name: patch pod
effect: fiam.effect.write
endpoints:
- id: endpoint.apiserver
kind: endpoint
address: https://cluster.example.invalid
address_scheme: fiam.address-scheme.https-url
bindings:
- id: binding.k8s-api
contract: contract.k8s-api
provider_port: port.apiserver.api
consumer_ports:
- port.kubectl.api
endpoints:
- endpoint.apiserver
communication_stack:
- role: fiam.stack-role.application-transfer-protocol
term: fiam.protocol.http
- role: fiam.stack-role.security-protocol
term: fiam.protocol.tls
information_resources:
- id: resource.k8s.default-pods
kind: information-resource
name: default namespace Pods collection
resource_kind: fiam.information-resource.api-resource-collection
resource_scope: fiam.resource-scope.concrete-collection
owner: node.apiserver
selectors:
- kind: fiam.resource-selector.kubernetes-resource-path
value: /api/v1/namespaces/default/pods
facets:
durability: fiam.durability.persistent
mutability: fiam.mutability.mutable
- id: resource.k8s.pod.demo
kind: information-resource
name: Pod default/demo
resource_kind: fiam.information-resource.api-resource-object
resource_scope: fiam.resource-scope.concrete-instance
owner: node.apiserver
selectors:
- kind: fiam.resource-selector.kubernetes-object-ref
value:
apiVersion: v1
kind: Pod
namespace: default
name: demo
facets:
durability: fiam.durability.persistent
mutability: fiam.mutability.mutable
interactions:
- id: interaction.k8s.list
kind: interaction
operation: operation.k8s.list-pods
binding: binding.k8s-api
- id: interaction.k8s.watch
kind: interaction
operation: operation.k8s.watch-pods
binding: binding.k8s-api
temporal_semantics: fiam.temporal.asynchronous
- id: interaction.k8s.patch
kind: interaction
operation: operation.k8s.patch-pod
binding: binding.k8s-api
assertions:
- id: assertion.pod.in-collection
assertion_kind: relation
subject: resource.k8s.pod.demo
predicate: fiam.relation.contained-in
polarity: asserted
object_ref: resource.k8s.default-pods
evidence:
mode: fiam.evidence.declared
source: modeling specimen
confidence: 0.98
- id: assertion.list.reads
assertion_kind: relation
subject: interaction.k8s.list
predicate: fiam.relation.reads-from
polarity: asserted
object_ref: resource.k8s.default-pods
evidence:
mode: fiam.evidence.declared
source: modeling specimen
confidence: 0.98
- id: assertion.watch.watches
assertion_kind: relation
subject: interaction.k8s.watch
predicate: fiam.relation.watches
polarity: asserted
object_ref: resource.k8s.default-pods
evidence:
mode: fiam.evidence.declared
source: modeling specimen
confidence: 0.98
- id: assertion.patch.writes
assertion_kind: relation
subject: interaction.k8s.patch
predicate: fiam.relation.writes-to
polarity: asserted
object_ref: resource.k8s.pod.demo
evidence:
mode: fiam.evidence.declared
source: modeling specimen
confidence: 0.98
- id: assertion.k8s.collection-conforms
assertion_kind: relation
subject: resource.k8s.default-pods
predicate: fiam.relation.conforms-to-shape
polarity: asserted
object_ref: shape.k8s.pod
evidence:
mode: fiam.evidence.declared
source: FIAM v0.2 semantic specimen
confidence: 0.98
- id: assertion.k8s.collection-element
assertion_kind: relation
subject: resource.k8s.default-pods
predicate: fiam.relation.element-shape
polarity: asserted
object_ref: shape.k8s.pod
evidence:
mode: fiam.evidence.declared
source: FIAM v0.2 semantic specimen
confidence: 0.98
facets:
role: fiam.shape-role.element
slot: items
- id: assertion.k8s.listshape-element
assertion_kind: relation
subject: shape.k8s.pod-list
predicate: fiam.relation.element-shape
polarity: asserted
object_ref: shape.k8s.pod
evidence:
mode: fiam.evidence.declared
source: FIAM v0.2 semantic specimen
confidence: 0.98
facets:
role: fiam.shape-role.element
slot: items
- id: assertion.k8s.object-conforms
assertion_kind: relation
subject: resource.k8s.pod.demo
predicate: fiam.relation.conforms-to-shape
polarity: asserted
object_ref: shape.k8s.pod
evidence:
mode: fiam.evidence.declared
source: FIAM v0.2 semantic specimen
confidence: 0.98
- id: assertion.k8s.list-produces
assertion_kind: relation
subject: operation.k8s.list-pods
predicate: fiam.relation.produces-shape
polarity: asserted
object_ref: shape.k8s.pod-list
evidence:
mode: fiam.evidence.declared
source: FIAM v0.2 semantic specimen
confidence: 0.98
facets:
role: fiam.shape-role.response
- id: assertion.k8s.list-binding-json
assertion_kind: relation
subject: binding.k8s-api
predicate: fiam.relation.produces-shape
polarity: asserted
object_ref: shape.k8s.pod-list
evidence:
mode: fiam.evidence.declared
source: FIAM v0.2 semantic specimen
confidence: 0.98
facets:
role: fiam.shape-role.response
representation: fiam.representation.json
operation_ref: operation.k8s.list-pods
- id: assertion.k8s.list-interaction-json
assertion_kind: relation
subject: interaction.k8s.list
predicate: fiam.relation.produces-shape
polarity: asserted
object_ref: shape.k8s.pod-list
evidence:
mode: fiam.evidence.declared
source: FIAM v0.2 semantic specimen
confidence: 0.98
facets:
role: fiam.shape-role.response
representation: fiam.representation.json
x-references:
- https://kubernetes.io/docs/reference/using-api/api-concepts/
- https://kubernetes.io/docs/reference/kubernetes-api/definitions/api-resource-v1-meta/
information_shapes:
- id: shape.k8s.pod
kind: information-shape
name: Kubernetes Pod
shape_kind: fiam.information-shape.object
- id: shape.k8s.pod-list
kind: information-shape
name: Kubernetes Pod collection representation
shape_kind: fiam.information-shape.collection
artifacts:
- id: artifact.k8s.openapi
kind: artifact
name: Kubernetes OpenAPI schema/discovery
artifact_type: fiam.artifact.api-description
describes:
- contract.k8s-api
- shape.k8s.pod
- shape.k8s.pod-list
locator: cluster://openapi

252
history/FIAM_v0.2_Draft6/adversarial-cases/11-element-shape-on-object.yaml Normal file
View file

@ -0,0 +1,252 @@
fiam_version: '0.2'
instance:
id: adversarial.element-on-object-shape
kind: model
title: Kubernetes Pod collection and object
status: provisional
intent: Test API resource collection/object modeling while keeping representation kind/schema distinct from resource identity.
nodes:
- id: node.kubectl
kind: system-node
name: kubectl / API client
node_type: fiam.node-type.application
- id: node.apiserver
kind: system-node
name: Kubernetes API Server
node_type: fiam.node-type.service
ports:
- id: port.apiserver.api
owner: node.apiserver
participations:
- contract: contract.k8s-api
mode: offers
- id: port.kubectl.api
owner: node.kubectl
participations:
- contract: contract.k8s-api
mode: requires
contracts:
- id: contract.k8s-api
kind: interface-contract
purpose:
- fiam.purpose.transactional-data-access
- fiam.purpose.mutation
operations:
- id: operation.k8s.list-pods
name: list pods
effect: fiam.effect.read
- id: operation.k8s.watch-pods
name: watch pods
interaction_style: fiam.interaction-style.subscribe
- id: operation.k8s.patch-pod
name: patch pod
effect: fiam.effect.write
endpoints:
- id: endpoint.apiserver
kind: endpoint
address: https://cluster.example.invalid
address_scheme: fiam.address-scheme.https-url
bindings:
- id: binding.k8s-api
contract: contract.k8s-api
provider_port: port.apiserver.api
consumer_ports:
- port.kubectl.api
endpoints:
- endpoint.apiserver
communication_stack:
- role: fiam.stack-role.application-transfer-protocol
term: fiam.protocol.http
- role: fiam.stack-role.security-protocol
term: fiam.protocol.tls
information_resources:
- id: resource.k8s.default-pods
kind: information-resource
name: default namespace Pods collection
resource_kind: fiam.information-resource.api-resource-collection
resource_scope: fiam.resource-scope.concrete-collection
owner: node.apiserver
selectors:
- kind: fiam.resource-selector.kubernetes-resource-path
value: /api/v1/namespaces/default/pods
facets:
durability: fiam.durability.persistent
mutability: fiam.mutability.mutable
- id: resource.k8s.pod.demo
kind: information-resource
name: Pod default/demo
resource_kind: fiam.information-resource.api-resource-object
resource_scope: fiam.resource-scope.concrete-instance
owner: node.apiserver
selectors:
- kind: fiam.resource-selector.kubernetes-object-ref
value:
apiVersion: v1
kind: Pod
namespace: default
name: demo
facets:
durability: fiam.durability.persistent
mutability: fiam.mutability.mutable
interactions:
- id: interaction.k8s.list
kind: interaction
operation: operation.k8s.list-pods
binding: binding.k8s-api
- id: interaction.k8s.watch
kind: interaction
operation: operation.k8s.watch-pods
binding: binding.k8s-api
temporal_semantics: fiam.temporal.asynchronous
- id: interaction.k8s.patch
kind: interaction
operation: operation.k8s.patch-pod
binding: binding.k8s-api
assertions:
- id: assertion.pod.in-collection
assertion_kind: relation
subject: resource.k8s.pod.demo
predicate: fiam.relation.contained-in
polarity: asserted
object_ref: resource.k8s.default-pods
evidence:
mode: fiam.evidence.declared
source: modeling specimen
confidence: 0.98
- id: assertion.list.reads
assertion_kind: relation
subject: interaction.k8s.list
predicate: fiam.relation.reads-from
polarity: asserted
object_ref: resource.k8s.default-pods
evidence:
mode: fiam.evidence.declared
source: modeling specimen
confidence: 0.98
- id: assertion.watch.watches
assertion_kind: relation
subject: interaction.k8s.watch
predicate: fiam.relation.watches
polarity: asserted
object_ref: resource.k8s.default-pods
evidence:
mode: fiam.evidence.declared
source: modeling specimen
confidence: 0.98
- id: assertion.patch.writes
assertion_kind: relation
subject: interaction.k8s.patch
predicate: fiam.relation.writes-to
polarity: asserted
object_ref: resource.k8s.pod.demo
evidence:
mode: fiam.evidence.declared
source: modeling specimen
confidence: 0.98
- id: assertion.k8s.collection-conforms
assertion_kind: relation
subject: resource.k8s.default-pods
predicate: fiam.relation.conforms-to-shape
polarity: asserted
object_ref: shape.k8s.pod-list
evidence:
mode: fiam.evidence.declared
source: FIAM v0.2 semantic specimen
confidence: 0.98
- id: assertion.k8s.collection-element
assertion_kind: relation
subject: resource.k8s.default-pods
predicate: fiam.relation.element-shape
polarity: asserted
object_ref: shape.k8s.pod
evidence:
mode: fiam.evidence.declared
source: FIAM v0.2 semantic specimen
confidence: 0.98
facets:
role: fiam.shape-role.element
slot: items
- id: assertion.k8s.listshape-element
assertion_kind: relation
subject: shape.k8s.pod
predicate: fiam.relation.element-shape
polarity: asserted
object_ref: shape.k8s.pod
evidence:
mode: fiam.evidence.declared
source: FIAM v0.2 semantic specimen
confidence: 0.98
facets:
role: fiam.shape-role.element
slot: items
- id: assertion.k8s.object-conforms
assertion_kind: relation
subject: resource.k8s.pod.demo
predicate: fiam.relation.conforms-to-shape
polarity: asserted
object_ref: shape.k8s.pod
evidence:
mode: fiam.evidence.declared
source: FIAM v0.2 semantic specimen
confidence: 0.98
- id: assertion.k8s.list-produces
assertion_kind: relation
subject: operation.k8s.list-pods
predicate: fiam.relation.produces-shape
polarity: asserted
object_ref: shape.k8s.pod-list
evidence:
mode: fiam.evidence.declared
source: FIAM v0.2 semantic specimen
confidence: 0.98
facets:
role: fiam.shape-role.response
- id: assertion.k8s.list-binding-json
assertion_kind: relation
subject: binding.k8s-api
predicate: fiam.relation.produces-shape
polarity: asserted
object_ref: shape.k8s.pod-list
evidence:
mode: fiam.evidence.declared
source: FIAM v0.2 semantic specimen
confidence: 0.98
facets:
role: fiam.shape-role.response
representation: fiam.representation.json
operation_ref: operation.k8s.list-pods
- id: assertion.k8s.list-interaction-json
assertion_kind: relation
subject: interaction.k8s.list
predicate: fiam.relation.produces-shape
polarity: asserted
object_ref: shape.k8s.pod-list
evidence:
mode: fiam.evidence.declared
source: FIAM v0.2 semantic specimen
confidence: 0.98
facets:
role: fiam.shape-role.response
representation: fiam.representation.json
x-references:
- https://kubernetes.io/docs/reference/using-api/api-concepts/
- https://kubernetes.io/docs/reference/kubernetes-api/definitions/api-resource-v1-meta/
information_shapes:
- id: shape.k8s.pod
kind: information-shape
name: Kubernetes Pod
shape_kind: fiam.information-shape.object
- id: shape.k8s.pod-list
kind: information-shape
name: Kubernetes Pod collection representation
shape_kind: fiam.information-shape.collection
artifacts:
- id: artifact.k8s.openapi
kind: artifact
name: Kubernetes OpenAPI schema/discovery
artifact_type: fiam.artifact.api-description
describes:
- contract.k8s-api
- shape.k8s.pod
- shape.k8s.pod-list
locator: cluster://openapi

256
history/FIAM_v0.2_Draft6/adversarial-cases/12-binding-unrelated-shape.yaml Normal file
View file

@ -0,0 +1,256 @@
fiam_version: '0.2'
instance:
id: adversarial.binding-unrelated-shape
kind: model
title: Kubernetes Pod collection and object
status: provisional
intent: Test API resource collection/object modeling while keeping representation kind/schema distinct from resource identity.
nodes:
- id: node.kubectl
kind: system-node
name: kubectl / API client
node_type: fiam.node-type.application
- id: node.apiserver
kind: system-node
name: Kubernetes API Server
node_type: fiam.node-type.service
ports:
- id: port.apiserver.api
owner: node.apiserver
participations:
- contract: contract.k8s-api
mode: offers
- id: port.kubectl.api
owner: node.kubectl
participations:
- contract: contract.k8s-api
mode: requires
contracts:
- id: contract.k8s-api
kind: interface-contract
purpose:
- fiam.purpose.transactional-data-access
- fiam.purpose.mutation
operations:
- id: operation.k8s.list-pods
name: list pods
effect: fiam.effect.read
- id: operation.k8s.watch-pods
name: watch pods
interaction_style: fiam.interaction-style.subscribe
- id: operation.k8s.patch-pod
name: patch pod
effect: fiam.effect.write
endpoints:
- id: endpoint.apiserver
kind: endpoint
address: https://cluster.example.invalid
address_scheme: fiam.address-scheme.https-url
bindings:
- id: binding.k8s-api
contract: contract.k8s-api
provider_port: port.apiserver.api
consumer_ports:
- port.kubectl.api
endpoints:
- endpoint.apiserver
communication_stack:
- role: fiam.stack-role.application-transfer-protocol
term: fiam.protocol.http
- role: fiam.stack-role.security-protocol
term: fiam.protocol.tls
information_resources:
- id: resource.k8s.default-pods
kind: information-resource
name: default namespace Pods collection
resource_kind: fiam.information-resource.api-resource-collection
resource_scope: fiam.resource-scope.concrete-collection
owner: node.apiserver
selectors:
- kind: fiam.resource-selector.kubernetes-resource-path
value: /api/v1/namespaces/default/pods
facets:
durability: fiam.durability.persistent
mutability: fiam.mutability.mutable
- id: resource.k8s.pod.demo
kind: information-resource
name: Pod default/demo
resource_kind: fiam.information-resource.api-resource-object
resource_scope: fiam.resource-scope.concrete-instance
owner: node.apiserver
selectors:
- kind: fiam.resource-selector.kubernetes-object-ref
value:
apiVersion: v1
kind: Pod
namespace: default
name: demo
facets:
durability: fiam.durability.persistent
mutability: fiam.mutability.mutable
interactions:
- id: interaction.k8s.list
kind: interaction
operation: operation.k8s.list-pods
binding: binding.k8s-api
- id: interaction.k8s.watch
kind: interaction
operation: operation.k8s.watch-pods
binding: binding.k8s-api
temporal_semantics: fiam.temporal.asynchronous
- id: interaction.k8s.patch
kind: interaction
operation: operation.k8s.patch-pod
binding: binding.k8s-api
assertions:
- id: assertion.pod.in-collection
assertion_kind: relation
subject: resource.k8s.pod.demo
predicate: fiam.relation.contained-in
polarity: asserted
object_ref: resource.k8s.default-pods
evidence:
mode: fiam.evidence.declared
source: modeling specimen
confidence: 0.98
- id: assertion.list.reads
assertion_kind: relation
subject: interaction.k8s.list
predicate: fiam.relation.reads-from
polarity: asserted
object_ref: resource.k8s.default-pods
evidence:
mode: fiam.evidence.declared
source: modeling specimen
confidence: 0.98
- id: assertion.watch.watches
assertion_kind: relation
subject: interaction.k8s.watch
predicate: fiam.relation.watches
polarity: asserted
object_ref: resource.k8s.default-pods
evidence:
mode: fiam.evidence.declared
source: modeling specimen
confidence: 0.98
- id: assertion.patch.writes
assertion_kind: relation
subject: interaction.k8s.patch
predicate: fiam.relation.writes-to
polarity: asserted
object_ref: resource.k8s.pod.demo
evidence:
mode: fiam.evidence.declared
source: modeling specimen
confidence: 0.98
- id: assertion.k8s.collection-conforms
assertion_kind: relation
subject: resource.k8s.default-pods
predicate: fiam.relation.conforms-to-shape
polarity: asserted
object_ref: shape.k8s.pod-list
evidence:
mode: fiam.evidence.declared
source: FIAM v0.2 semantic specimen
confidence: 0.98
- id: assertion.k8s.collection-element
assertion_kind: relation
subject: resource.k8s.default-pods
predicate: fiam.relation.element-shape
polarity: asserted
object_ref: shape.k8s.pod
evidence:
mode: fiam.evidence.declared
source: FIAM v0.2 semantic specimen
confidence: 0.98
facets:
role: fiam.shape-role.element
slot: items
- id: assertion.k8s.listshape-element
assertion_kind: relation
subject: shape.k8s.pod-list
predicate: fiam.relation.element-shape
polarity: asserted
object_ref: shape.k8s.pod
evidence:
mode: fiam.evidence.declared
source: FIAM v0.2 semantic specimen
confidence: 0.98
facets:
role: fiam.shape-role.element
slot: items
- id: assertion.k8s.object-conforms
assertion_kind: relation
subject: resource.k8s.pod.demo
predicate: fiam.relation.conforms-to-shape
polarity: asserted
object_ref: shape.k8s.pod
evidence:
mode: fiam.evidence.declared
source: FIAM v0.2 semantic specimen
confidence: 0.98
- id: assertion.k8s.list-produces
assertion_kind: relation
subject: operation.k8s.list-pods
predicate: fiam.relation.produces-shape
polarity: asserted
object_ref: shape.k8s.pod-list
evidence:
mode: fiam.evidence.declared
source: FIAM v0.2 semantic specimen
confidence: 0.98
facets:
role: fiam.shape-role.response
- id: assertion.k8s.list-binding-json
assertion_kind: relation
subject: binding.k8s-api
predicate: fiam.relation.produces-shape
polarity: asserted
object_ref: shape.unrelated
evidence:
mode: fiam.evidence.declared
source: FIAM v0.2 semantic specimen
confidence: 0.98
facets:
role: fiam.shape-role.response
representation: fiam.representation.json
operation_ref: operation.k8s.list-pods
- id: assertion.k8s.list-interaction-json
assertion_kind: relation
subject: interaction.k8s.list
predicate: fiam.relation.produces-shape
polarity: asserted
object_ref: shape.k8s.pod-list
evidence:
mode: fiam.evidence.declared
source: FIAM v0.2 semantic specimen
confidence: 0.98
facets:
role: fiam.shape-role.response
representation: fiam.representation.json
x-references:
- https://kubernetes.io/docs/reference/using-api/api-concepts/
- https://kubernetes.io/docs/reference/kubernetes-api/definitions/api-resource-v1-meta/
information_shapes:
- id: shape.k8s.pod
kind: information-shape
name: Kubernetes Pod
shape_kind: fiam.information-shape.object
- id: shape.k8s.pod-list
kind: information-shape
name: Kubernetes Pod collection representation
shape_kind: fiam.information-shape.collection
- id: shape.unrelated
kind: information-shape
name: Unrelated object
shape_kind: fiam.information-shape.object
artifacts:
- id: artifact.k8s.openapi
kind: artifact
name: Kubernetes OpenAPI schema/discovery
artifact_type: fiam.artifact.api-description
describes:
- contract.k8s-api
- shape.k8s.pod
- shape.k8s.pod-list
locator: cluster://openapi

256
history/FIAM_v0.2_Draft6/adversarial-cases/13-interaction-unrelated-shape.yaml Normal file
View file

@ -0,0 +1,256 @@
fiam_version: '0.2'
instance:
id: adversarial.interaction-unrelated-shape
kind: model
title: Kubernetes Pod collection and object
status: provisional
intent: Test API resource collection/object modeling while keeping representation kind/schema distinct from resource identity.
nodes:
- id: node.kubectl
kind: system-node
name: kubectl / API client
node_type: fiam.node-type.application
- id: node.apiserver
kind: system-node
name: Kubernetes API Server
node_type: fiam.node-type.service
ports:
- id: port.apiserver.api
owner: node.apiserver
participations:
- contract: contract.k8s-api
mode: offers
- id: port.kubectl.api
owner: node.kubectl
participations:
- contract: contract.k8s-api
mode: requires
contracts:
- id: contract.k8s-api
kind: interface-contract
purpose:
- fiam.purpose.transactional-data-access
- fiam.purpose.mutation
operations:
- id: operation.k8s.list-pods
name: list pods
effect: fiam.effect.read
- id: operation.k8s.watch-pods
name: watch pods
interaction_style: fiam.interaction-style.subscribe
- id: operation.k8s.patch-pod
name: patch pod
effect: fiam.effect.write
endpoints:
- id: endpoint.apiserver
kind: endpoint
address: https://cluster.example.invalid
address_scheme: fiam.address-scheme.https-url
bindings:
- id: binding.k8s-api
contract: contract.k8s-api
provider_port: port.apiserver.api
consumer_ports:
- port.kubectl.api
endpoints:
- endpoint.apiserver
communication_stack:
- role: fiam.stack-role.application-transfer-protocol
term: fiam.protocol.http
- role: fiam.stack-role.security-protocol
term: fiam.protocol.tls
information_resources:
- id: resource.k8s.default-pods
kind: information-resource
name: default namespace Pods collection
resource_kind: fiam.information-resource.api-resource-collection
resource_scope: fiam.resource-scope.concrete-collection
owner: node.apiserver
selectors:
- kind: fiam.resource-selector.kubernetes-resource-path
value: /api/v1/namespaces/default/pods
facets:
durability: fiam.durability.persistent
mutability: fiam.mutability.mutable
- id: resource.k8s.pod.demo
kind: information-resource
name: Pod default/demo
resource_kind: fiam.information-resource.api-resource-object
resource_scope: fiam.resource-scope.concrete-instance
owner: node.apiserver
selectors:
- kind: fiam.resource-selector.kubernetes-object-ref
value:
apiVersion: v1
kind: Pod
namespace: default
name: demo
facets:
durability: fiam.durability.persistent
mutability: fiam.mutability.mutable
interactions:
- id: interaction.k8s.list
kind: interaction
operation: operation.k8s.list-pods
binding: binding.k8s-api
- id: interaction.k8s.watch
kind: interaction
operation: operation.k8s.watch-pods
binding: binding.k8s-api
temporal_semantics: fiam.temporal.asynchronous
- id: interaction.k8s.patch
kind: interaction
operation: operation.k8s.patch-pod
binding: binding.k8s-api
assertions:
- id: assertion.pod.in-collection
assertion_kind: relation
subject: resource.k8s.pod.demo
predicate: fiam.relation.contained-in
polarity: asserted
object_ref: resource.k8s.default-pods
evidence:
mode: fiam.evidence.declared
source: modeling specimen
confidence: 0.98
- id: assertion.list.reads
assertion_kind: relation
subject: interaction.k8s.list
predicate: fiam.relation.reads-from
polarity: asserted
object_ref: resource.k8s.default-pods
evidence:
mode: fiam.evidence.declared
source: modeling specimen
confidence: 0.98
- id: assertion.watch.watches
assertion_kind: relation
subject: interaction.k8s.watch
predicate: fiam.relation.watches
polarity: asserted
object_ref: resource.k8s.default-pods
evidence:
mode: fiam.evidence.declared
source: modeling specimen
confidence: 0.98
- id: assertion.patch.writes
assertion_kind: relation
subject: interaction.k8s.patch
predicate: fiam.relation.writes-to
polarity: asserted
object_ref: resource.k8s.pod.demo
evidence:
mode: fiam.evidence.declared
source: modeling specimen
confidence: 0.98
- id: assertion.k8s.collection-conforms
assertion_kind: relation
subject: resource.k8s.default-pods
predicate: fiam.relation.conforms-to-shape
polarity: asserted
object_ref: shape.k8s.pod-list
evidence:
mode: fiam.evidence.declared
source: FIAM v0.2 semantic specimen
confidence: 0.98
- id: assertion.k8s.collection-element
assertion_kind: relation
subject: resource.k8s.default-pods
predicate: fiam.relation.element-shape
polarity: asserted
object_ref: shape.k8s.pod
evidence:
mode: fiam.evidence.declared
source: FIAM v0.2 semantic specimen
confidence: 0.98
facets:
role: fiam.shape-role.element
slot: items
- id: assertion.k8s.listshape-element
assertion_kind: relation
subject: shape.k8s.pod-list
predicate: fiam.relation.element-shape
polarity: asserted
object_ref: shape.k8s.pod
evidence:
mode: fiam.evidence.declared
source: FIAM v0.2 semantic specimen
confidence: 0.98
facets:
role: fiam.shape-role.element
slot: items
- id: assertion.k8s.object-conforms
assertion_kind: relation
subject: resource.k8s.pod.demo
predicate: fiam.relation.conforms-to-shape
polarity: asserted
object_ref: shape.k8s.pod
evidence:
mode: fiam.evidence.declared
source: FIAM v0.2 semantic specimen
confidence: 0.98
- id: assertion.k8s.list-produces
assertion_kind: relation
subject: operation.k8s.list-pods
predicate: fiam.relation.produces-shape
polarity: asserted
object_ref: shape.k8s.pod-list
evidence:
mode: fiam.evidence.declared
source: FIAM v0.2 semantic specimen
confidence: 0.98
facets:
role: fiam.shape-role.response
- id: assertion.k8s.list-binding-json
assertion_kind: relation
subject: binding.k8s-api
predicate: fiam.relation.produces-shape
polarity: asserted
object_ref: shape.k8s.pod-list
evidence:
mode: fiam.evidence.declared
source: FIAM v0.2 semantic specimen
confidence: 0.98
facets:
role: fiam.shape-role.response
representation: fiam.representation.json
operation_ref: operation.k8s.list-pods
- id: assertion.k8s.list-interaction-json
assertion_kind: relation
subject: interaction.k8s.list
predicate: fiam.relation.produces-shape
polarity: asserted
object_ref: shape.unrelated
evidence:
mode: fiam.evidence.declared
source: FIAM v0.2 semantic specimen
confidence: 0.98
facets:
role: fiam.shape-role.response
representation: fiam.representation.json
x-references:
- https://kubernetes.io/docs/reference/using-api/api-concepts/
- https://kubernetes.io/docs/reference/kubernetes-api/definitions/api-resource-v1-meta/
information_shapes:
- id: shape.k8s.pod
kind: information-shape
name: Kubernetes Pod
shape_kind: fiam.information-shape.object
- id: shape.k8s.pod-list
kind: information-shape
name: Kubernetes Pod collection representation
shape_kind: fiam.information-shape.collection
- id: shape.unrelated
kind: information-shape
name: Unrelated object
shape_kind: fiam.information-shape.object
artifacts:
- id: artifact.k8s.openapi
kind: artifact
name: Kubernetes OpenAPI schema/discovery
artifact_type: fiam.artifact.api-description
describes:
- contract.k8s-api
- shape.k8s.pod
- shape.k8s.pod-list
locator: cluster://openapi

281
history/FIAM_v0.2_Draft6/adversarial-cases/14-manual-family-label.yaml Normal file
View file

@ -0,0 +1,281 @@
fiam_version: '0.2'
instance:
id: adversarial.manual-family-label
kind: model
title: MCP server over stdio
status: provisional
intent: Model a local agent-to-tool interface using MCP over JSON-RPC and stdio.
nodes:
- id: node.agent-host
kind: system-node
name: Agent Host
node_type: fiam.node-type.application
- id: node.mcp-server
kind: system-node
name: Local MCP Server
node_type: fiam.node-type.process
ports:
- id: port.agent.mcp-client
owner: node.agent-host
participations:
- contract: contract.mcp.tools
mode: requires
roles:
- fiam.role.client
- id: port.server.mcp
owner: node.mcp-server
participations:
- contract: contract.mcp.tools
mode: offers
roles:
- fiam.role.server
contracts:
- id: contract.mcp.tools
kind: interface-contract
purpose:
- fiam.purpose.tool-invocation
contract_forms:
- fiam.contract-form.mcp
operations:
- id: operation.mcp.tools-list
name: tools/list
interaction_style: fiam.interaction-style.rpc
- id: operation.mcp.tools-call
name: tools/call
interaction_style: fiam.interaction-style.rpc
family_labels:
- fiam.family.agent-tool-interface
- id: contract.tool.read-file
kind: interface-contract
name: read_file tool
purpose:
- fiam.purpose.tool-invocation
operations:
- id: operation.tool.read-file
name: read_file
interaction_style: fiam.interaction-style.rpc
bindings:
- id: binding.mcp.stdio
contract: contract.mcp.tools
provider_port: port.server.mcp
consumer_ports:
- port.agent.mcp-client
binding_profile: fiam.binding-profile.mcp-stdio
communication_stack:
- role: fiam.stack-role.application-protocol
term: fiam.protocol.mcp
- role: fiam.stack-role.messaging-protocol
term: fiam.protocol.json-rpc-2.0
- role: fiam.stack-role.ipc-process-carrier
term: fiam.carrier.stdio
addressing:
kind: fiam.addressing.process-spawn
value: command invocation
session_model: fiam.session.long-lived-process
channels:
- id: channel.mcp.stdio
kind: channel
channel_type: fiam.channel.bidirectional-byte-stream
mediation: fiam.mediation.direct
interactions:
- id: interaction.tools-call
operation: operation.mcp.tools-call
binding: binding.mcp.stdio
channel: channel.mcp.stdio
temporal_semantics: fiam.temporal.synchronous
participants:
initiator: node.agent-host
responder: node.mcp-server
- id: interaction.read-file
kind: interaction
operation: operation.tool.read-file
binding: binding.mcp.stdio
channel: channel.mcp.stdio
temporal_semantics: fiam.temporal.synchronous
participants:
initiator: node.agent-host
responder: node.mcp-server
realization_status: fiam.interaction-status.executed
assertions:
- id: assertion.mcp.protocol
subject: binding.mcp.stdio
predicate: fiam.property.communication-protocol
value: fiam.protocol.mcp
evidence:
mode: fiam.evidence.declared
source: MCP specification
confidence: 1.0
assertion_kind: property
polarity: asserted
- id: assertion.local-boundary
subject: binding.mcp.stdio
predicate: fiam.property.execution-boundary
value: fiam.execution-boundary.local-process
evidence:
mode: fiam.evidence.inferred
source: stdio binding semantics
confidence: 0.99
assertion_kind: property
polarity: asserted
- id: assertion.mcp.catalog-elements
assertion_kind: relation
subject: shape.mcp.tool-catalog
predicate: fiam.relation.element-shape
polarity: asserted
object_ref: shape.mcp.tool-descriptor
evidence:
mode: fiam.evidence.declared
source: FIAM v0.2 semantic specimen
confidence: 0.98
facets:
slot: tools
role: fiam.shape-role.element
- id: assertion.mcp.tools-list-produces
assertion_kind: relation
subject: operation.mcp.tools-list
predicate: fiam.relation.produces-shape
polarity: asserted
object_ref: shape.mcp.tool-catalog
evidence:
mode: fiam.evidence.declared
source: FIAM v0.2 semantic specimen
confidence: 0.98
facets:
role: fiam.shape-role.response
representation: fiam.representation.json
- id: assertion.mcp.tool-discovered
assertion_kind: relation
subject: operation.tool.read-file
predicate: fiam.relation.discovered-via
polarity: asserted
object_ref: operation.mcp.tools-list
evidence:
mode: fiam.evidence.declared
source: FIAM v0.2 semantic specimen
confidence: 0.98
- id: assertion.mcp.tool-contract-embedded
assertion_kind: relation
subject: contract.tool.read-file
predicate: fiam.relation.embedded-in
polarity: asserted
object_ref: operation.mcp.tools-call
evidence:
mode: fiam.evidence.declared
source: FIAM v0.2 semantic specimen
confidence: 0.98
facets:
slot: params.arguments
- id: assertion.read-file.accepts
assertion_kind: relation
subject: operation.tool.read-file
predicate: fiam.relation.accepts-shape
polarity: asserted
object_ref: shape.read-file.args
evidence:
mode: fiam.evidence.declared
source: FIAM v0.2 semantic specimen
confidence: 0.98
facets:
role: fiam.shape-role.request
- id: assertion.read-file.produces
assertion_kind: relation
subject: operation.tool.read-file
predicate: fiam.relation.produces-shape
polarity: asserted
object_ref: shape.read-file.result
evidence:
mode: fiam.evidence.declared
source: FIAM v0.2 semantic specimen
confidence: 0.98
facets:
role: fiam.shape-role.response
- id: assertion.read-file.actual-input
assertion_kind: relation
subject: interaction.read-file
predicate: fiam.relation.accepts-shape
polarity: asserted
object_ref: shape.read-file.args
evidence:
mode: fiam.evidence.declared
source: FIAM v0.2 semantic specimen
confidence: 0.98
facets:
role: fiam.shape-role.request
representation: fiam.representation.json
- id: assertion.read-file.actual-output
assertion_kind: relation
subject: interaction.read-file
predicate: fiam.relation.produces-shape
polarity: asserted
object_ref: shape.read-file.result
evidence:
mode: fiam.evidence.declared
source: FIAM v0.2 semantic specimen
confidence: 0.98
facets:
role: fiam.shape-role.response
representation: fiam.representation.json
- id: assertion.mcp.tools-call-accepts
assertion_kind: relation
subject: operation.mcp.tools-call
predicate: fiam.relation.accepts-shape
polarity: asserted
object_ref: shape.mcp.tool-call-request
evidence:
mode: fiam.evidence.declared
source: MCP contract fixture
confidence: 0.98
facets:
role: fiam.shape-role.request
representation: fiam.representation.json
- id: assertion.mcp.tools-call-produces
assertion_kind: relation
subject: operation.mcp.tools-call
predicate: fiam.relation.produces-shape
polarity: asserted
object_ref: shape.mcp.tool-call-result
evidence:
mode: fiam.evidence.declared
source: MCP contract fixture
confidence: 0.98
facets:
role: fiam.shape-role.response
representation: fiam.representation.json
- id: assertion.mcp.call-embeds-tool-args
assertion_kind: relation
subject: shape.mcp.tool-call-request
predicate: fiam.relation.embeds-shape
polarity: asserted
object_ref: shape.read-file.args
evidence:
mode: fiam.evidence.declared
source: MCP contract fixture
confidence: 0.98
facets:
slot: params.arguments
role: fiam.shape-role.payload
information_shapes:
- id: shape.mcp.tool-catalog
kind: information-shape
name: MCP tool catalog
shape_kind: fiam.information-shape.collection
- id: shape.mcp.tool-descriptor
kind: information-shape
name: MCP tool descriptor
shape_kind: fiam.information-shape.object
- id: shape.read-file.args
kind: information-shape
name: read_file arguments
shape_kind: fiam.information-shape.object
- id: shape.read-file.result
kind: information-shape
name: read_file result
shape_kind: fiam.information-shape.object
- id: shape.mcp.tool-call-request
kind: information-shape
name: MCP tools/call request
shape_kind: fiam.information-shape.object
- id: shape.mcp.tool-call-result
kind: information-shape
name: MCP tools/call result
shape_kind: fiam.information-shape.object

56
history/FIAM_v0.2_Draft6/adversarial-cases/15-inferred-same-entity-one-signal.yaml Normal file
View file

@ -0,0 +1,56 @@
fiam_version: '0.2'
instance:
id: adversarial.inferred-same-entity-one-signal
kind: model
title: Shape identity across OpenAPI and source declarations
status: provisional
intent: Exercise candidate alignment versus confirmed shape identity without destructive merge.
nodes:
- id: node.user-service
kind: system-node
name: User service
node_type: fiam.node-type.service
information_shapes:
- id: shape.customer.openapi
kind: information-shape
name: Customer discovered from OpenAPI
shape_kind: fiam.information-shape.object
- id: shape.customer.java
kind: information-shape
name: Customer discovered from Java source
shape_kind: fiam.information-shape.object
artifacts:
- id: artifact.openapi
kind: artifact
name: openapi.yaml
artifact_type: fiam.artifact.api-description
describes: shape.customer.openapi
- id: artifact.customer-java
kind: artifact
name: Customer.java
artifact_type: fiam.artifact.source-code-type
describes: shape.customer.java
assertions:
- id: assertion.customer-corresponds
assertion_kind: relation
subject: shape.customer.openapi
predicate: fiam.relation.corresponds-to
polarity: asserted
object_ref: shape.customer.java
evidence:
mode: fiam.evidence.inferred
source: static analyzers matched names and structure
confidence: 0.78
- id: assertion.customer-same
assertion_kind: relation
subject: shape.customer.openapi
predicate: fiam.relation.same-entity-as
polarity: asserted
object_ref: shape.customer.java
evidence:
mode: fiam.evidence.inferred
source:
type: schema-structural-fingerprint
ref: one-signal
locator: fixture
confidence: 0.995

11
history/FIAM_v0.2_Draft6/adversarial-inputs/otel-kind-string.json Normal file
View file

@ -0,0 +1,11 @@
{
"resourceSpans": [{
"resource": {"attributes": [{"key":"service.name","value":{"stringValue":"bad.service"}}]},
"scopeSpans": [{"scope": {"name":"bad"}, "spans": [{
"traceId":"5B8EFFF798038103D269B633813FC60C",
"spanId":"EEE19B7EC3C1B174",
"name":"invalid OTLP JSON enum",
"kind":"SPAN_KIND_SERVER"
}]}]
}]
}

3064
history/FIAM_v0.2_Draft6/canon/FIAM-Canon-v0.2.yaml Normal file
View file

File diff suppressed because it is too large Load diff

219
history/FIAM_v0.2_Draft6/history/FIAM-v0.2-Draft1.md Normal file
View file

@ -0,0 +1,219 @@
# FIAM v0.2-draft.1 — Implementation-Hardened Baseline
## Status
**Draft implementation baseline.** `fiam_version` remains `0.2`; `draft.1` identifies this package/revision of the v0.2 specification work. No new Core entity is introduced in this pass.
This revision responds to implementation review by hardening the semantics of the existing spine and exercising it through a real declared-source ingest.
## Stable structural spine
```text
Participant / SystemNode
↓ owns / participates through
Port → InterfaceContract → Operation
↓ realization
Binding → Endpoint
│
├──────── Channel
│
└──────── Interaction → InteractionFlow
│
├── targets / reads / writes → InformationResource
└── accepts / produces / errors-with → InformationShape
Artifact ── describes / implements ──> Core entities
Assertion + Evidence ── qualifies facts and graph relations
```
The v0.2 distinctions remain unchanged:
```text
Endpoint = how/where a Binding is reached
Channel = exchange/mediation locus
InformationResource = identifiable information-bearing locus/state/collection
InformationShape = admissible semantic/structural form
Artifact = concrete description or implementation
Representation = encoding/notation selected for a participation
```
Channel and Resource remain orthogonal. Shape remains distinct from Artifact and Representation. Family labels remain lens-derived caches, not Core types.
## draft.1 hardening decisions
### 1. MCP bindings share one semantic contract graph
The stdio and Streamable HTTP specimens now use the same contract, operations, dynamically discovered tool contract and InformationShapes. Only realization-specific entities differ: processes/nodes, bindings, endpoint/channel and communication stack.
The shared dynamic pattern is:
```text
operation.mcp.tools-list
↑ discovered-via
operation.tool.read-file
contract.tool.read-file
── embedded-in ──> operation.mcp.tools-call
ToolCallRequest ── embeds-shape(params.arguments) ──> ReadFileArgs
```
This makes "same contract, multiple bindings" executable rather than rhetorical.
### 2. Kafka duplicate collapsed
The older dual-role Kafka specimen was removed. One regression specimen now carries all relevant facts together:
```text
Kafka topic as Channel
│
└── backed-by ──> retained-log InformationResource
publish / consume ── shape participation ──> OrderCreated
```
### 3. Shape-kind coherence is enforced
The validator now rejects, among other cases:
- collection-like Resources that `conforms-to-shape` a non-collection Shape;
- `element-shape` on a non-collection InformationShape;
- `element-shape` on an InformationResource that is not collection-like.
The normative distinction remains:
- `conforms-to-shape`: the Resource *as addressed* has that overall form;
- `element-shape`: members/elements of a collection-like Resource or Shape have that form.
### 4. Shape participation refinement is enforced
Shape participation follows:
```text
Operation semantic default
↓ refine
Binding realization
↓ refine
Interaction actual selection/observation
```
A lower-level participation must use the same Shape, an identity-equivalent Shape, or an evidenced `projection-of` / `version-of` Shape. Missing parent declarations remain valid under open-world semantics.
A multi-operation Binding must use `facets.operation_ref` to identify which Operation a Binding-level shape participation refines.
### 5. Representation stays relation-scoped
Representation is authoritative on the most specific relevant `accepts-shape`, `produces-shape` or `errors-with-shape` assertion. Contract/Operation `representations` fields remain migration-readable but warn as non-authoritative.
### 6. Cached family labels require provenance
Manual `family_labels` were removed from the positive corpus. A cached family label is now valid only when backed by an asserted `fiam.property.family-label` whose evidence mode is `fiam.evidence.inferred`.
This preserves the rule:
> family labels are results of lenses, not primitive classification supplied by specimen authors.
### 7. Identity is operational but non-destructive
`same-entity-as` defines a **query-time equivalence class**. It never deletes either entity or its evidence.
Automated discovery must not turn structural similarity into identity. The default policy is:
```text
one structural/fingerprint signal
→ corresponds-to
same-entity-as
→ explicit declared/governed identity decision
OR, for inferred promotion eligibility,
at least 2 independent signals
each meeting confidence >= 0.98
```
Even if the inferred eligibility threshold is met, default tooling does **not** auto-promote; it requests governed reconciliation.
The validator rejects a purely inferred `same-entity-as` with insufficient independent evidence. `tools/identity_view.py` implements the corresponding query view without merging IDs.
### 8. Specimen tests and discovered models are separated
`tests.expected_properties` is mandatory for `instance.kind: specimen` fixtures and is executed by the validator.
Ordinary ingested architecture models (`instance.kind: model`) do not need to pretend to be test fixtures. Their confidence comes from schema/Canon/semantic validation plus real provenance.
## First declared ingest: OpenAPI → FIAM
`tools/openapi_to_fiam.py` is the first ingestion adapter. It currently accepts OpenAPI 3.x YAML/JSON and produces a declared FIAM model containing, where available:
- provider SystemNode, Port and InterfaceContract;
- Operations with HTTP method/path provenance;
- HTTP/TLS/TCP Binding and server Endpoint;
- HTTP path-template InformationResources;
- component and inline InformationShapes;
- coarse shape composition (`embeds-shape`, `element-shape`), without schema fields in Core;
- Operation semantic shape defaults;
- Binding-level representation refinements with `operation_ref`;
- OpenAPI Artifact with source URL and version metadata;
- per-assertion evidence with JSON-pointer-like source locators;
- structural-fingerprint candidate identity as `corresponds-to`, never automatic `same-entity-as`.
The adapter is architecture-oriented rather than a lossless OpenAPI translator. The OpenAPI Artifact remains authoritative for detailed parameter/property/schema semantics.
## Real-world identity run
The package includes a normalized excerpt from the Swagger Petstore OpenAPI document, retaining the live source URL and the `Category`, `Tag`, and `Pet` schemas.
`Category` and `Tag` normalize to the same structural fingerprint (`id:int64`, `name:string`). The importer therefore emits:
```text
Category ── corresponds-to ──> Tag
confidence = 0.75
mode = inferred
```
It emits **no `same-entity-as`**. `identity_view.py` consequently reports no equivalence class and recommends that the pair remain correspondence candidates.
This is the desired behavior: schema duplication/similarity is evidence for reconciliation, not identity proof.
## Validation meaning in draft.1
A positive PASS checks:
- JSON Schema validity;
- entity-reference resolution;
- Canon term resolution and deprecation;
- Canon term-usage constraints;
- assertion predicate scheme/type constraints;
- relation domain/range constraints;
- relation-facet constraints;
- assertion evidence presence;
- contract participation and Binding consistency;
- dynamic embedded-contract Operation/Binding consistency;
- shape-kind coherence;
- Operation → Binding → Interaction shape refinement;
- family-label cache provenance;
- identity same-kind/self-edge rules;
- inferred `same-entity-as` promotion eligibility;
- executable specimen expectations.
The current results are:
```text
Synthetic positive specimen corpus: 26 PASS, 0 errors, 0 warnings
Real-world OpenAPI ingest model: 1 PASS, 0 errors, 0 warnings
Adversarial suite: 14 rejected as intended
Migration-warning case: 1 accepted with 1 warning
```
## Deliberate exclusions remain
No new Core entity was introduced. In particular:
- no `Session`;
- no fields/member lists inside InformationShape;
- no business/domain ontology;
- no RDF requirement;
- no destructive merge engine;
- no automatic family labels;
- no automatic identity promotion.
The next implementation pressure should come from additional ingest/observation adapters and useful lenses, not from ontology expansion.

171
history/FIAM_v0.2_Draft6/history/FIAM-v0.2-Draft2.md Normal file
View file

@ -0,0 +1,171 @@
# FIAM v0.2-draft.2
## Status
`v0.2-draft.2` is the first FIAM baseline with **independent declared and runtime-observed ingest paths plus an executable comparison Lens**.
It intentionally introduces **no new Core entity and no Core schema change**. The `FIAM-Core-v0.2.schema.json` file is byte-identical to draft.1. This revision pressures the stable spine through ingestion, reconciliation and analysis instead of extending the metamodel.
## What changed
### 1. OpenTelemetry / OTLP runtime ingest
`tools/otel_to_fiam.py` accepts OTLP/JSON trace exports. It can emit a standalone partial runtime model or enrich a declared FIAM model supplied with `--base`.
The first supported high-value mapping is an HTTP `SERVER` span:
```text
OTel resource service.name
-> observed SystemNode
HTTP SERVER span
-> observed Contract / Operation
-> observed Binding / Endpoint
-> Interaction
-> runtime-observed Assertions + Evidence
```
Ordinary spans without enough interface semantics still become partial runtime Interactions. Incomplete runtime models remain valid.
The adapter deliberately does **not** infer payload `InformationShape`s from HTTP spans.
### 2. Runtime facts are assertions
The Canon gains runtime-oriented properties including:
- `fiam.property.service-name`
- `fiam.property.service-namespace`
- `fiam.property.http-method`
- `fiam.property.http-route`
- `fiam.property.server-address`
- `fiam.property.server-port`
- `fiam.property.network-protocol-version`
- `fiam.property.http-response-status-code`
Observed protocol versions map to versioned protocol terms (`HTTP/1.1`, `HTTP/2`, `HTTP/3`) while retaining the raw `network.protocol.version` observation.
### 3. Reconciliation remains weaker than identity
When a runtime HTTP span matches a declared operation by host + method + normalized route, the adapter emits evidenced:
```text
observed Operation --corresponds-to--> declared Operation
observed Binding --corresponds-to--> declared Binding
observed Endpoint --corresponds-to--> declared Endpoint
```
It does **not** emit `same-entity-as` automatically and does not merge source records.
### 4. First executable Lens
`lenses/declared-vs-observed.yaml` plus `tools/declared_observed_lens.py` compare declared and runtime-observed facts over `corresponds-to` pairs.
Current finding classes:
- `exact`
- `compatible-refinement`
- `observed-less-specific`
- `declared-only`
- `observed-only`
- `conflict`
Protocol comparison understands the Canon hierarchy. Therefore:
```text
declared HTTP
observed HTTP/2
=> compatible-refinement
```
while:
```text
declared HTTP/1.1
observed HTTP/2
=> conflict
```
The Lens resolves the architectural owner through the declared Binding's provider Port and owning SystemNode.
### 5. OpenAPI ingest became more conservative
Runtime comparison exposed one overstatement in draft.1: an OpenAPI `https://` server URL does not justify declaring TCP because HTTP/3 may use QUIC. The OpenAPI adapter now declares generic HTTP + TLS from HTTPS, but no transport unless a source actually provides one.
This is a useful example of FIAM's intended learning loop: **the Core did not change; ingest semantics became more accurate.**
## Demonstration
The package combines:
- the normalized Swagger Petstore OpenAPI excerpt already used in draft.1;
- an OTLP/JSON HTTP server-span fixture following current OpenTelemetry semantic-convention field names;
- the generated composite FIAM graph;
- two Lens runs.
### Run A — ordinary OpenAPI declaration
The OpenAPI source declares generic HTTP. The observed trace records protocol version `2`.
Result:
```text
compatible-refinement: 1
exact: 2
observed-only: 2
conflict: 0
```
The observed-only facts are useful rather than errors: OpenAPI does not declare the actual negotiated network protocol version or the default port as an explicit fact.
### Run B — controlled operational expectation
A separate architecture declaration states that the same Binding is expected to use HTTP/1.1. This is explicitly a test fixture, not a claim about Swagger's public service.
The runtime observation remains HTTP/2.
Result:
```text
conflict: 1
exact: 2
observed-only: 2
```
The conflict contains both evidence chains and resolves the declared owning service node.
## Conformance meaning in draft.2
`make check` now covers:
1. Core byte stability against draft.1;
2. all JSON Schemas plus the new Lens schema;
3. Canon validation;
4. all 26 positive semantic specimens;
5. deterministic OpenAPI ingest;
6. OTLP/JSON format ingest;
7. deterministic runtime ingest;
8. declared/runtime reconciliation;
9. conservative no-Shape runtime behavior;
10. deterministic Lens execution;
11. expected compatible-refinement behavior;
12. expected HTTP/1.1 vs HTTP/2 conflict behavior;
13. OTLP/JSON adapter-level rejection of invalid enum encoding;
14. the existing FIAM adversarial corpus.
A green draft.2 therefore exercises an actual **declare -> observe -> reconcile -> analyze** loop.
## Core posture
The Core remains closed. No `Session`, schema fields, business ontology, merge entity or additional family type has been added.
The next Core change should require a real ingestion or analysis failure that cannot be represented with the current spine.
## Standards basis
The runtime profile is based on:
- OpenTelemetry Semantic Conventions 1.44.0: https://opentelemetry.io/docs/specs/semconv/
- HTTP span semantic conventions: https://opentelemetry.io/docs/specs/semconv/http/http-spans/
- OpenTelemetry Trace API / SpanKind: https://opentelemetry.io/docs/specs/otel/trace/api/
- OTLP 1.11.0: https://opentelemetry.io/docs/specs/otlp/
- official OTLP/JSON trace example repository: https://github.com/open-telemetry/opentelemetry-proto/tree/main/examples

200
history/FIAM_v0.2_Draft6/history/FIAM-v0.2-Draft3.md Normal file
View file

@ -0,0 +1,200 @@
# FIAM v0.2-draft.3 — Cross-Domain Runtime Architecture
## Status
FIAM v0.2-draft.3 keeps the **Core schema closed and byte-identical to draft.1**. The revision extends runtime ingestion and analysis across three additional architectural domains:
- RPC / gRPC;
- messaging producer/consumer/client operations;
- database client operations.
The purpose is not to add more interface types. It is to test whether one FIAM Core can reconstruct materially different runtime topologies from one telemetry substrate.
## Result
The Core survives the cross-domain pressure test without modification.
The same structural vocabulary produces three distinct runtime structures:
```text
RPC
Service A ───────────────> Service B
direct call
Messaging
Producer ──> Channel ──> Consumer
brokered
Database
Application ─────────────> InformationResource
reads/writes
```
This distinction is intentional. A runtime topology lens must not flatten a Kafka flow, a gRPC call and a table read into the same generic `service -> service` edge.
## Standards basis
The runtime adapter targets:
- OpenTelemetry Semantic Conventions 1.44.0 — https://opentelemetry.io/docs/specs/semconv/
- RPC spans — https://opentelemetry.io/docs/specs/semconv/rpc/rpc-spans/
- gRPC conventions — https://opentelemetry.io/docs/specs/semconv/rpc/grpc/
- Messaging spans — https://opentelemetry.io/docs/specs/semconv/messaging/messaging-spans/
- Database client spans — https://opentelemetry.io/docs/specs/semconv/db/database-spans/
- OTLP 1.11.0 — https://opentelemetry.io/docs/specs/otlp/
The maturity of those conventions is not uniform. Database client span conventions are Stable; RPC/gRPC are currently Release Candidate; messaging span conventions remain Development. FIAM therefore preserves raw OTel semantic values as evidence properties instead of treating every convention detail as permanent FIAM ontology.
## Runtime mappings
### RPC / gRPC
An RPC `CLIENT` or `SERVER` span with `rpc.system.name` and `rpc.method` can create or enrich:
```text
SystemNode
Port (requires/offers)
InterfaceContract
Operation (RPC)
Binding
Endpoint, where server.address is available
Interaction
```
`rpc.system.name=grpc` maps to the canonical gRPC protocol term. FIAM does **not** infer HTTP/2 or a transport merely from the fact that the RPC system is gRPC unless another observation establishes that lower layer.
Client/server spans in one trace can be correlated by parent span identity. This is used by the Runtime Topology Lens to produce a direct dependency without merging the two independently observed interface records.
### Messaging
OpenTelemetry messaging semantics distinguish operation type from SpanKind. In particular:
```text
create -> PRODUCER
send -> PRODUCER or CLIENT depending on creation context
receive -> CLIENT
process -> CONSUMER
settle -> CLIENT
```
FIAM therefore preserves both:
```text
OTel SpanKind
messaging.operation.type
```
and derives the architectural producer/consumer participation from the messaging operation semantics rather than assuming that every consumer operation must have SpanKind `CONSUMER`.
A messaging destination becomes a FIAM `Channel`; producer and consumer bindings remain separate. Span links can create an `InteractionFlow` of type `message-propagation` while retaining the Channel as the mediation locus.
### Database clients
A database client span can create:
```text
local application Node
required database Port
observed database Contract/Operation
client Binding
database Endpoint
remote database placeholder Node, when address is known
InformationResource, when db.collection.name is known
Interaction
```
For PostgreSQL, an observed collection is modeled as a relational-table InformationResource. `SELECT`-like operations can infer `reads-from`; mutation operations can infer `writes-to`. The inference is separately evidenced from the directly observed `db.operation.name`.
FIAM does not ingest `db.query.text` into the architecture model. Queries may contain sensitive or high-cardinality application data and are not required to establish the architectural relationship.
## Reconciliation
The runtime adapter can reconcile against existing FIAM declarations without destructive identity merge.
The draft.3 conformance suite exercises:
- gRPC runtime observations against the pre-existing bidirectional-stream specimen;
- Kafka producer/consumer observations against the durable-topic specimen;
- PostgreSQL client observations against the shared-table specimen.
Successful matches emit `corresponds-to` assertions with reconciliation evidence. Current checked outcomes are:
```text
gRPC 6 correspondence edges
Kafka 7 correspondence edges
Postgres 8 correspondence edges
```
The PostgreSQL case includes Resource and Endpoint correspondence in addition to Binding/Operation/Node reconciliation.
## Runtime Topology Lens
Draft.3 introduces `fiam.lens.runtime-topology`.
It intentionally projects domains differently:
- RPC: client service -> server service, using trace parentage;
- Messaging: producer -> Channel -> consumer, using message-propagation InteractionFlows derived from span links;
- Database: application -> InformationResource, preserving read/write semantics and resource ownership.
The combined fixture yields:
```text
1 RPC direct-call edge
2 mediated messaging edges
2 database resource edges
0 unresolved correlations
```
A pull-based Kafka `receive` span is deliberately included with SpanKind `CLIENT`; FIAM still gives it a consumer participation role and reconstructs its message flow through the span link.
## Canon additions
No Core entity was added. The Canon gained only runtime vocabulary required to preserve observed facts and selectors, including:
- host/port endpoint addressing;
- generic message destination Channel type;
- message-propagation Flow type;
- generic database collection resource kind;
- RPC system/method/status properties;
- messaging system/destination/operation properties;
- database system/namespace/collection/operation/status properties;
- raw OpenTelemetry SpanKind property.
These terms capture evidence; they are not new interface families.
## Conformance posture
`make check` now verifies:
- Core byte stability;
- eight schemas;
- Canon and two Lens definitions;
- 26 semantic specimens;
- deterministic OpenAPI ingest;
- deterministic HTTP and generic OTLP ingest;
- declared-vs-observed HTTP refinement/conflict behavior;
- deterministic multi-domain OTLP ingest;
- conservative no-Shape runtime behavior;
- database query-text exclusion;
- OTel messaging CLIENT-vs-consumer semantics;
- message-link flow reconstruction;
- Runtime Topology Lens output and result schema;
- gRPC/Kafka/Postgres declared-runtime reconciliation;
- adversarial OTLP and FIAM cases.
## Design conclusion
The runtime pass strengthens the decision to keep the Core closed.
FIAM now has evidence that one structural spine can describe:
```text
synchronous service invocation
asynchronous mediated communication
shared/persistent data access
```
without minting `GrpcInterface`, `KafkaInterface`, `DatabaseInterface`, or another domain-specific Core branch.
The next productive pressure is operational rather than ontological: consume larger heterogeneous trace sets, improve entity reconciliation across incomplete observations, and build architecture questions/lenses on top of the resulting graph.

266
history/FIAM_v0.2_Draft6/history/FIAM-v0.2-Draft4-root-copy.md Normal file
View file

@ -0,0 +1,266 @@
# 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**.
```text
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:
```text
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:
```text
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:
```text
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.
```text
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:
```text
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:
```bash
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.

266
history/FIAM_v0.2_Draft6/history/FIAM-v0.2-Draft4.md Normal file
View file

@ -0,0 +1,266 @@
# 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**.
```text
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:
```text
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:
```text
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:
```text
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.
```text
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:
```text
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:
```bash
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.

179
history/FIAM_v0.2_Draft6/history/FIAM-v0.2-Draft5.md Normal file
View file

@ -0,0 +1,179 @@
# FIAM v0.2-draft.5 — Architecture Intelligence Queries
## Status
FIAM v0.2-draft.5 moves the project from an estate-aware catalog toward an **architecture intelligence query system**.
The Core remains frozen. `schemas/FIAM-Core-v0.2.schema.json` is byte-identical to the Core used since v0.2-draft.1. No structural entity was added.
Draft.5 works above the Core in four areas:
1. persistent but rebuildable indexing;
2. temporal topology state;
3. evidence-strength projection;
4. executable architecture-change and boundary-drift questions.
## Persistent index, not another truth store
FIAM YAML/JSON models retain evidence, provenance and open-world semantics. Repeated estate queries should not require scanning every model file, so draft.5 introduces a SQLite reference index.
```text
FIAM declared/runtime models
|
| index / normalize
v
rebuildable SQLite projection
entities + historical versions
assertions + evidence scores
working identities
declared dependencies
Zone memberships
topology intervals
|
+--> temporal lenses
+--> boundary lenses
+--> evidence-ranked queries
```
The database is disposable. It is never permitted to become the only copy of evidence.
## Temporal topology semantics
A runtime topology edge has an observation interval. Append/sample ingestion can extend what has been seen, but absence has no meaning. Only an **authoritative snapshot** may close an active interval.
```text
sample batch without edge
-> unknown; do not close
authoritative snapshot without edge
-> close active interval at snapshot time
```
If the edge later reappears, the index opens another interval rather than erasing the prior one. The included September 10 fixture verifies that the Orders → Inventory dependency receives a second interval while the August/September interval remains closed and queryable.
Declarations and Zone memberships are evaluated **as-of the query/edge time**, not using the latest estate state. A later deployment move therefore does not retroactively rewrite an old boundary crossing.
## Architecture Changes Lens
The first temporal Lens answers three concrete questions over a window:
- which runtime dependencies appeared;
- which runtime dependencies disappeared;
- which newly appeared dependencies were not declared at that time.
The deterministic estate-history fixture produces:
```text
2026-09-01
Orders -> Inventory declared + observed
2026-09-08 authoritative snapshot
Orders -> Inventory absent -> interval closed
Orders -> Partner API newly observed, undeclared
```
For the September 7–9 window the Lens reports:
```text
appeared: 1
Orders -> Partner API
disappeared: 1
Orders -> Inventory [declared]
newly undeclared: 1
Orders -> Partner API
```
This is the first FIAM query that combines declaration, runtime history and temporal semantics rather than comparing one current model.
## Boundary Drift Lens
Zones remain normal FIAM Core entities. Draft.5 adds Canon terms for `trust-zone`, `organization`, and `network-segment` and a Lens that compares Zone membership on newly appearing topology edges.
In the estate-history fixture:
```text
Orders -> internal trust zone / internal organization
Partner API -> partner trust zone / partner organization
```
The newly observed dependency therefore yields:
```text
new cross-Zone edges: 1
new trust-boundary crossings: 1
new organization crossings: 1
```
The Lens is intentionally descriptive. Whether a crossing is acceptable belongs to a security/governance policy layered on top.
## Evidence-strength policy
FIAM already stores `confidence`, evidence mode, source, observer, stance and observation time. Draft.5 provides a query-time scoring policy so tools can rank claims without mutating them.
The reference score combines:
```text
source confidence
* evidence-mode weight
* source-type weight
* freshness factor where configured
```
Independent evidential sources combine using a bounded noisy-OR. Repeated records from the same source locator count once.
Supporting and challenging evidence are scored separately.
Important: **the resulting number is a ranking heuristic, not a calibrated probability that the assertion is true.**
Conformance verifies that:
- duplicating one source does not increase the score;
- an independent corroborating source does increase support;
- stale runtime evidence ranks below equally strong fresh runtime evidence;
- source assertions are not rewritten.
## Working identity and temporal indexing
The persistent index uses the existing non-destructive working-set policy. An observed record with one unambiguous declared correspondence may use the declared id as its preferred query identity, while both source records and all evidence remain available.
The index additionally stores historical entity versions so temporal Zone/owner questions are not forced through the latest object serialization.
## Scale fixture
The query-index conformance generates a 5,000-edge FIAM topology snapshot and verifies:
```text
entities: 5,001
active topology: 5,000
topology intervals: 5,000
```
This is not presented as a performance benchmark. It verifies that the query contract is set-oriented and persistent rather than a collection of fixture-specific YAML scans.
## What draft.5 deliberately does not do
It does not introduce:
- new Core entities;
- automatic deletion based on sampled absence;
- a truth-probability model;
- a graph database requirement;
- policy decisions about whether a boundary crossing is allowed;
- automatic destructive entity merge.
SQLite is the reference query projection, not a mandated storage engine. The normalized contract can later be implemented in PostgreSQL, a graph store or another indexed backend without changing FIAM Core.
## Next pressure
The strongest next tests are now query/operations tests rather than ontology tests:
- longer historical windows and reappearance of dependencies;
- evidence conflict/challenge queries;
- risk/governance policy over boundary crossings;
- declared-interface disappearance and reintroduction across releases;
- materialized estate summaries and incremental query serving;
- multiple source streams with overlapping scopes and different authority.
The architectural question is no longer whether FIAM can describe the estate. It is whether it can support useful, explainable decisions over the estate's changing state while preserving uncertainty and evidence.

28
history/FIAM_v0.2_Draft6/history/draft5-fixtures/estate-history/boundary-drift.yaml Normal file
View file

@ -0,0 +1,28 @@
lens_id: fiam.lens.boundary-drift
window:
since: '2026-09-07T00:00:00Z'
until: '2026-09-09T00:00:00Z'
scope: prod-runtime
summary:
new_cross_zone: 1
new_trust_boundary: 1
new_organization_boundary: 1
crossings:
- edge_key: edge.210c03e257e70068c68df0c0
kind: direct-call
from: node.orders
target: node.partner
first_seen: '2026-09-08T00:00:00Z'
zone_crossings:
- zone_type: fiam.zone-type.trust-zone
from_zones:
- zone.trust.internal
target_zones:
- zone.trust.partner
- zone_type: fiam.zone-type.organization
from_zones:
- zone.org.internal
target_zones:
- zone.org.partner
trust_boundary: true
organization_boundary: true

54
history/FIAM_v0.2_Draft6/history/draft5-fixtures/estate-history/changes.yaml Normal file
View file

@ -0,0 +1,54 @@
lens_id: fiam.lens.architecture-changes
window:
since: '2026-09-07T00:00:00Z'
until: '2026-09-09T00:00:00Z'
scope: prod-runtime
summary:
appeared: 1
disappeared: 1
newly_undeclared: 1
appeared:
- edge_key: edge.210c03e257e70068c68df0c0
domain: rpc
kind: direct-call
from: node.orders
target: node.partner
target_kind: node
channel: null
first_seen: '2026-09-08T00:00:00Z'
last_seen: '2026-09-08T00:00:00Z'
valid_from: '2026-09-08T00:00:00Z'
valid_until: null
observation_count: 12
declared: false
close_reason: null
disappeared:
- edge_key: edge.be323ef1b2f1274e52be419c
domain: rpc
kind: direct-call
from: node.orders
target: node.inventory
target_kind: node
channel: null
first_seen: '2026-08-25T00:00:00Z'
last_seen: '2026-09-01T00:00:00Z'
valid_from: '2026-08-25T00:00:00Z'
valid_until: '2026-09-08T00:00:00Z'
observation_count: 100
declared: true
close_reason: absent-from-authoritative-snapshot
newly_undeclared:
- edge_key: edge.210c03e257e70068c68df0c0
domain: rpc
kind: direct-call
from: node.orders
target: node.partner
target_kind: node
channel: null
first_seen: '2026-09-08T00:00:00Z'
last_seen: '2026-09-08T00:00:00Z'
valid_from: '2026-09-08T00:00:00Z'
valid_until: null
observation_count: 12
declared: false
close_reason: null

BIN
history/FIAM_v0.2_Draft6/history/draft5-fixtures/estate-history/estate.sqlite Normal file
View file

Binary file not shown.

375
history/FIAM_v0.2_Draft6/history/draft5-fixtures/estate-history/evidence-scores.yaml Normal file
View file

@ -0,0 +1,375 @@
policy_id: fiam.policy.evidence-scoring.default
evaluated_at: '2026-09-09T08:00:00Z'
assertions:
- assertion_id: assertion.openapi.0001
support_score: 1.0
challenge_score: 0.0
neutral_score: 0.0
net_support: 1.0
support_class: strong
evidence_sources:
- stance: supports
mode: fiam.evidence.declared
source_type: openapi-document
source_ref: artifact.openapi.swagger-petstore---identity-ingest-excerpt
strength: 1.0
- assertion_id: assertion.openapi.0002
support_score: 1.0
challenge_score: 0.0
neutral_score: 0.0
net_support: 1.0
support_class: strong
evidence_sources:
- stance: supports
mode: fiam.evidence.declared
source_type: openapi-document
source_ref: artifact.openapi.swagger-petstore---identity-ingest-excerpt
strength: 1.0
- assertion_id: assertion.openapi.0003
support_score: 1.0
challenge_score: 0.0
neutral_score: 0.0
net_support: 1.0
support_class: strong
evidence_sources:
- stance: supports
mode: fiam.evidence.declared
source_type: openapi-document
source_ref: artifact.openapi.swagger-petstore---identity-ingest-excerpt
strength: 1.0
- assertion_id: assertion.openapi.0004
support_score: 1.0
challenge_score: 0.0
neutral_score: 0.0
net_support: 1.0
support_class: strong
evidence_sources:
- stance: supports
mode: fiam.evidence.declared
source_type: openapi-document
source_ref: artifact.openapi.swagger-petstore---identity-ingest-excerpt
strength: 1.0
- assertion_id: assertion.openapi.0005
support_score: 1.0
challenge_score: 0.0
neutral_score: 0.0
net_support: 1.0
support_class: strong
evidence_sources:
- stance: supports
mode: fiam.evidence.declared
source_type: openapi-document
source_ref: artifact.openapi.swagger-petstore---identity-ingest-excerpt
strength: 1.0
- assertion_id: assertion.openapi.0006
support_score: 1.0
challenge_score: 0.0
neutral_score: 0.0
net_support: 1.0
support_class: strong
evidence_sources:
- stance: supports
mode: fiam.evidence.declared
source_type: openapi-document
source_ref: artifact.openapi.swagger-petstore---identity-ingest-excerpt
strength: 1.0
- assertion_id: assertion.openapi.0007
support_score: 1.0
challenge_score: 0.0
neutral_score: 0.0
net_support: 1.0
support_class: strong
evidence_sources:
- stance: supports
mode: fiam.evidence.declared
source_type: openapi-document
source_ref: artifact.openapi.swagger-petstore---identity-ingest-excerpt
strength: 1.0
- assertion_id: assertion.openapi.0008
support_score: 1.0
challenge_score: 0.0
neutral_score: 0.0
net_support: 1.0
support_class: strong
evidence_sources:
- stance: supports
mode: fiam.evidence.declared
source_type: openapi-document
source_ref: artifact.openapi.swagger-petstore---identity-ingest-excerpt
strength: 1.0
- assertion_id: assertion.openapi.0009
support_score: 1.0
challenge_score: 0.0
neutral_score: 0.0
net_support: 1.0
support_class: strong
evidence_sources:
- stance: supports
mode: fiam.evidence.declared
source_type: openapi-document
source_ref: artifact.openapi.swagger-petstore---identity-ingest-excerpt
strength: 1.0
- assertion_id: assertion.openapi.0010
support_score: 1.0
challenge_score: 0.0
neutral_score: 0.0
net_support: 1.0
support_class: strong
evidence_sources:
- stance: supports
mode: fiam.evidence.declared
source_type: openapi-document
source_ref: artifact.openapi.swagger-petstore---identity-ingest-excerpt
strength: 1.0
- assertion_id: assertion.openapi.0011
support_score: 1.0
challenge_score: 0.0
neutral_score: 0.0
net_support: 1.0
support_class: strong
evidence_sources:
- stance: supports
mode: fiam.evidence.declared
source_type: openapi-document
source_ref: artifact.openapi.swagger-petstore---identity-ingest-excerpt
strength: 1.0
- assertion_id: assertion.openapi.0012
support_score: 1.0
challenge_score: 0.0
neutral_score: 0.0
net_support: 1.0
support_class: strong
evidence_sources:
- stance: supports
mode: fiam.evidence.declared
source_type: openapi-document
source_ref: artifact.openapi.swagger-petstore---identity-ingest-excerpt
strength: 1.0
- assertion_id: assertion.openapi.0013
support_score: 0.1365
challenge_score: 0.0
neutral_score: 0.0
net_support: 0.1365
support_class: very-weak
evidence_sources:
- stance: supports
mode: fiam.evidence.inferred
source_type: schema-structural-fingerprint
source_ref: schema-structural-fingerprint
strength: 0.1365
- assertion_id: assertion.otel.16f147bdd9999831cb01
support_score: 0.889561
challenge_score: 0.0
neutral_score: 0.0
net_support: 0.889561
support_class: strong
evidence_sources:
- stance: supports
mode: fiam.evidence.runtime-observed
source_type: otlp-trace-stream
source_ref: artifact.otel.stream.petstore-get-pet-http2.otlp.272fc480612d
strength: 0.889561
- assertion_id: assertion.otel.1b96a634e434b4917c7c
support_score: 0.394483
challenge_score: 0.0
neutral_score: 0.0
net_support: 0.394483
support_class: weak
evidence_sources:
- stance: supports
mode: fiam.evidence.inferred
source_type: reconciliation-rule
source_ref: artifact.otel.stream.petstore-get-pet-http2.otlp.272fc480612d
strength: 0.394483
- assertion_id: assertion.otel.2d67c52ae9f110cd2ee1
support_score: 0.889561
challenge_score: 0.0
neutral_score: 0.0
net_support: 0.889561
support_class: strong
evidence_sources:
- stance: supports
mode: fiam.evidence.runtime-observed
source_type: otlp-trace-stream
source_ref: artifact.otel.stream.petstore-get-pet-http2.otlp.272fc480612d
strength: 0.889561
- assertion_id: assertion.otel.3a4db6ee91268ef5d9f9
support_score: 0.917652
challenge_score: 0.0
neutral_score: 0.0
net_support: 0.917652
support_class: strong
evidence_sources:
- stance: supports
mode: fiam.evidence.runtime-observed
source_type: otlp-aggregate
source_ref: artifact.otel.stream.petstore-get-pet-http2.otlp.272fc480612d
strength: 0.917652
- assertion_id: assertion.otel.3df6f40fdae3bb2fad5d
support_score: 0.889561
challenge_score: 0.0
neutral_score: 0.0
net_support: 0.889561
support_class: strong
evidence_sources:
- stance: supports
mode: fiam.evidence.runtime-observed
source_type: otlp-trace-stream
source_ref: artifact.otel.stream.petstore-get-pet-http2.otlp.272fc480612d
strength: 0.889561
- assertion_id: assertion.otel.58c30a6371a6c8d18707
support_score: 0.889561
challenge_score: 0.0
neutral_score: 0.0
net_support: 0.889561
support_class: strong
evidence_sources:
- stance: supports
mode: fiam.evidence.runtime-observed
source_type: otlp-trace-stream
source_ref: artifact.otel.stream.petstore-get-pet-http2.otlp.272fc480612d
strength: 0.889561
- assertion_id: assertion.otel.61ee643dcd4ae2f35c1f
support_score: 0.398679
challenge_score: 0.0
neutral_score: 0.0
net_support: 0.398679
support_class: weak
evidence_sources:
- stance: supports
mode: fiam.evidence.inferred
source_type: reconciliation-rule
source_ref: artifact.otel.stream.petstore-get-pet-http2.otlp.272fc480612d
strength: 0.398679
- assertion_id: assertion.otel.65f037d1b849a5deb24b
support_score: 0.917652
challenge_score: 0.0
neutral_score: 0.0
net_support: 0.917652
support_class: strong
evidence_sources:
- stance: supports
mode: fiam.evidence.runtime-observed
source_type: otlp-aggregate
source_ref: artifact.otel.stream.petstore-get-pet-http2.otlp.272fc480612d
strength: 0.917652
- assertion_id: assertion.otel.8dab97bea0366143d688
support_score: 0.889561
challenge_score: 0.0
neutral_score: 0.0
net_support: 0.889561
support_class: strong
evidence_sources:
- stance: supports
mode: fiam.evidence.runtime-observed
source_type: otlp-trace-stream
source_ref: artifact.otel.stream.petstore-get-pet-http2.otlp.272fc480612d
strength: 0.889561
- assertion_id: assertion.otel.94ebba5afc8db554f52f
support_score: 0.917652
challenge_score: 0.0
neutral_score: 0.0
net_support: 0.917652
support_class: strong
evidence_sources:
- stance: supports
mode: fiam.evidence.runtime-observed
source_type: otlp-aggregate
source_ref: artifact.otel.stream.petstore-get-pet-http2.otlp.272fc480612d
strength: 0.917652
- assertion_id: assertion.otel.a7000cafd39483a9ae54
support_score: 0.407073
challenge_score: 0.0
neutral_score: 0.0
net_support: 0.407073
support_class: weak
evidence_sources:
- stance: supports
mode: fiam.evidence.inferred
source_type: reconciliation-rule
source_ref: artifact.otel.stream.petstore-get-pet-http2.otlp.272fc480612d
strength: 0.407073
- assertion_id: assertion.otel.c16f4fe5d33d669cef5b
support_score: 0.889561
challenge_score: 0.0
neutral_score: 0.0
net_support: 0.889561
support_class: strong
evidence_sources:
- stance: supports
mode: fiam.evidence.runtime-observed
source_type: otlp-trace-stream
source_ref: artifact.otel.stream.petstore-get-pet-http2.otlp.272fc480612d
strength: 0.889561
- assertion_id: assertion.otel.c39aee943e445c5b5bb2
support_score: 0.889561
challenge_score: 0.0
neutral_score: 0.0
net_support: 0.889561
support_class: strong
evidence_sources:
- stance: supports
mode: fiam.evidence.runtime-observed
source_type: otlp-trace-stream
source_ref: artifact.otel.stream.petstore-get-pet-http2.otlp.272fc480612d
strength: 0.889561
- assertion_id: assertion.otel.ce45dcb72eb26f2c19a0
support_score: 0.917652
challenge_score: 0.0
neutral_score: 0.0
net_support: 0.917652
support_class: strong
evidence_sources:
- stance: supports
mode: fiam.evidence.runtime-observed
source_type: otlp-aggregate
source_ref: artifact.otel.stream.petstore-get-pet-http2.otlp.272fc480612d
strength: 0.917652
- assertion_id: assertion.otel.dfa6f7f01d962e73b3d0
support_score: 0.889561
challenge_score: 0.0
neutral_score: 0.0
net_support: 0.889561
support_class: strong
evidence_sources:
- stance: supports
mode: fiam.evidence.runtime-observed
source_type: otlp-trace-stream
source_ref: artifact.otel.stream.petstore-get-pet-http2.otlp.272fc480612d
strength: 0.889561
- assertion_id: assertion.otel.f3415412240b68ce80e8
support_score: 0.917652
challenge_score: 0.0
neutral_score: 0.0
net_support: 0.917652
support_class: strong
evidence_sources:
- stance: supports
mode: fiam.evidence.runtime-observed
source_type: otlp-aggregate
source_ref: artifact.otel.stream.petstore-get-pet-http2.otlp.272fc480612d
strength: 0.917652
- assertion_id: assertion.otel.fc3df934322d8fddcd9d
support_score: 0.402876
challenge_score: 0.0
neutral_score: 0.0
net_support: 0.402876
support_class: weak
evidence_sources:
- stance: supports
mode: fiam.evidence.inferred
source_type: reconciliation-rule
source_ref: artifact.otel.stream.petstore-get-pet-http2.otlp.272fc480612d
strength: 0.402876
- assertion_id: assertion.otel.fc7a428bfb9170e4c495
support_score: 0.889561
challenge_score: 0.0
neutral_score: 0.0
net_support: 0.889561
support_class: strong
evidence_sources:
- stance: supports
mode: fiam.evidence.runtime-observed
source_type: otlp-trace-stream
source_ref: artifact.otel.stream.petstore-get-pet-http2.otlp.272fc480612d
strength: 0.889561

111
history/FIAM_v0.2_Draft6/history/draft5-fixtures/estate-history/snapshot-2026-09-01.yaml Normal file
View file

@ -0,0 +1,111 @@
fiam_version: '0.2'
instance:
id: model.estate-history.prod
kind: model
title: Estate history — production
status: provisional
intent: Temporal architecture-intelligence fixture.
nodes:
- id: node.orders
kind: system-node
name: Orders
node_type: fiam.node-type.service
- id: node.inventory
kind: system-node
name: Inventory
node_type: fiam.node-type.service
- id: node.partner
kind: system-node
name: Partner API
node_type: fiam.node-type.application
ports:
- id: port.inventory.api
kind: port
owner: node.inventory
participations:
- contract: contract.inventory
mode: offers
roles: [fiam.role.server]
contracts:
- id: contract.inventory
kind: interface-contract
name: Inventory API
purpose: [fiam.purpose.query]
operations:
- id: operation.inventory.get
kind: operation
name: getInventory
interaction_style: fiam.interaction-style.request-response
bindings:
- id: binding.inventory
kind: binding
contract: contract.inventory
provider_port: port.inventory.api
operations: [operation.inventory.get]
zones:
- id: zone.environment.prod
kind: zone
name: production
zone_type: fiam.zone-type.deployment-environment
members: [node.orders, node.inventory, node.partner]
- id: zone.trust.internal
kind: zone
name: internal trust domain
zone_type: fiam.zone-type.trust-zone
members: [node.orders, node.inventory]
- id: zone.trust.partner
kind: zone
name: partner trust domain
zone_type: fiam.zone-type.trust-zone
members: [node.partner]
- id: zone.org.internal
kind: zone
name: internal organization
zone_type: fiam.zone-type.organization
members: [node.orders, node.inventory]
- id: zone.org.partner
kind: zone
name: partner organization
zone_type: fiam.zone-type.organization
members: [node.partner]
assertions:
- id: assertion.declared.orders-uses-inventory
assertion_kind: relation
subject: node.orders
predicate: fiam.relation.uses
polarity: asserted
object_ref: binding.inventory
evidence:
mode: fiam.evidence.declared
source:
type: architecture-declaration
ref: fixture://estate-history/declared
locator: dependency/orders-inventory
observer: fixture.owner
confidence: 1.0
stance: supports
observed_at: '2026-09-01T00:00:00Z'
extensions:
org.fiam.catalog:
version: 0.2-draft.5
processed_batches: ['1111111111111111111111111111111111111111111111111111111111111111']
declared_entity_ids: [node.orders, node.inventory, node.partner, port.inventory.api, contract.inventory, operation.inventory.get, binding.inventory]
last_ingest_at: '2026-09-01T00:00:00Z'
runtime_policy: aggregate-by-architectural-tuple
occurrence_retention: none
sample_size: 0
org.fiam.runtime_aggregates: []
org.fiam.runtime_topology_observations:
- id: topology.orders-inventory
domain: rpc
kind: direct-call
from: node.orders
to: node.inventory
binding: binding.inventory
operation: operation.inventory.get
count: 100
first_seen: '2026-08-25T00:00:00Z'
last_seen: '2026-09-01T00:00:00Z'
correlation: fixture
org.fiam.runtime_unresolved: []
org.fiam.reconciliation_candidates: []

129
history/FIAM_v0.2_Draft6/history/draft5-fixtures/estate-history/snapshot-2026-09-08.yaml Normal file
View file

@ -0,0 +1,129 @@
fiam_version: '0.2'
instance:
id: model.estate-history.prod
kind: model
title: "Estate history \u2014 production"
status: provisional
intent: Temporal architecture-intelligence fixture.
nodes:
- id: node.orders
kind: system-node
name: Orders
node_type: fiam.node-type.service
- id: node.inventory
kind: system-node
name: Inventory
node_type: fiam.node-type.service
- id: node.partner
kind: system-node
name: Partner API
node_type: fiam.node-type.application
ports:
- id: port.inventory.api
kind: port
owner: node.inventory
participations:
- contract: contract.inventory
mode: offers
roles:
- fiam.role.server
contracts:
- id: contract.inventory
kind: interface-contract
name: Inventory API
purpose:
- fiam.purpose.query
operations:
- id: operation.inventory.get
kind: operation
name: getInventory
interaction_style: fiam.interaction-style.request-response
bindings:
- id: binding.inventory
kind: binding
contract: contract.inventory
provider_port: port.inventory.api
operations:
- operation.inventory.get
zones:
- id: zone.environment.prod
kind: zone
name: production
zone_type: fiam.zone-type.deployment-environment
members:
- node.orders
- node.inventory
- node.partner
- id: zone.trust.internal
kind: zone
name: internal trust domain
zone_type: fiam.zone-type.trust-zone
members:
- node.orders
- node.inventory
- id: zone.trust.partner
kind: zone
name: partner trust domain
zone_type: fiam.zone-type.trust-zone
members:
- node.partner
- id: zone.org.internal
kind: zone
name: internal organization
zone_type: fiam.zone-type.organization
members:
- node.orders
- node.inventory
- id: zone.org.partner
kind: zone
name: partner organization
zone_type: fiam.zone-type.organization
members:
- node.partner
assertions:
- id: assertion.declared.orders-uses-inventory
assertion_kind: relation
subject: node.orders
predicate: fiam.relation.uses
polarity: asserted
object_ref: binding.inventory
evidence:
mode: fiam.evidence.declared
source:
type: architecture-declaration
ref: fixture://estate-history/declared
locator: dependency/orders-inventory
observer: fixture.owner
confidence: 1.0
stance: supports
observed_at: '2026-09-08T00:00:00Z'
extensions:
org.fiam.catalog:
version: 0.2-draft.5
processed_batches:
- '2222222222222222222222222222222222222222222222222222222222222222'
declared_entity_ids:
- node.orders
- node.inventory
- node.partner
- port.inventory.api
- contract.inventory
- operation.inventory.get
- binding.inventory
last_ingest_at: '2026-09-08T00:00:00Z'
runtime_policy: aggregate-by-architectural-tuple
occurrence_retention: none
sample_size: 0
org.fiam.runtime_aggregates: []
org.fiam.runtime_topology_observations:
- id: topology.orders-partner
domain: rpc
kind: direct-call
from: node.orders
to: node.partner
count: 12
first_seen: '2026-09-08T00:00:00Z'
last_seen: '2026-09-08T00:00:00Z'
correlation: fixture
org.fiam.runtime_unresolved: []
org.fiam.reconciliation_candidates: []

140
history/FIAM_v0.2_Draft6/history/draft5-fixtures/estate-history/snapshot-2026-09-10.yaml Normal file
View file

@ -0,0 +1,140 @@
fiam_version: '0.2'
instance:
id: model.estate-history.prod
kind: model
title: "Estate history \u2014 production"
status: provisional
intent: Temporal architecture-intelligence fixture.
nodes:
- id: node.orders
kind: system-node
name: Orders
node_type: fiam.node-type.service
- id: node.inventory
kind: system-node
name: Inventory
node_type: fiam.node-type.service
- id: node.partner
kind: system-node
name: Partner API
node_type: fiam.node-type.application
ports:
- id: port.inventory.api
kind: port
owner: node.inventory
participations:
- contract: contract.inventory
mode: offers
roles:
- fiam.role.server
contracts:
- id: contract.inventory
kind: interface-contract
name: Inventory API
purpose:
- fiam.purpose.query
operations:
- id: operation.inventory.get
kind: operation
name: getInventory
interaction_style: fiam.interaction-style.request-response
bindings:
- id: binding.inventory
kind: binding
contract: contract.inventory
provider_port: port.inventory.api
operations:
- operation.inventory.get
zones:
- id: zone.environment.prod
kind: zone
name: production
zone_type: fiam.zone-type.deployment-environment
members:
- node.orders
- node.inventory
- node.partner
- id: zone.trust.internal
kind: zone
name: internal trust domain
zone_type: fiam.zone-type.trust-zone
members:
- node.orders
- node.inventory
- id: zone.trust.partner
kind: zone
name: partner trust domain
zone_type: fiam.zone-type.trust-zone
members:
- node.partner
- id: zone.org.internal
kind: zone
name: internal organization
zone_type: fiam.zone-type.organization
members:
- node.orders
- node.inventory
- id: zone.org.partner
kind: zone
name: partner organization
zone_type: fiam.zone-type.organization
members:
- node.partner
assertions:
- id: assertion.declared.orders-uses-inventory
assertion_kind: relation
subject: node.orders
predicate: fiam.relation.uses
polarity: asserted
object_ref: binding.inventory
evidence:
mode: fiam.evidence.declared
source:
type: architecture-declaration
ref: fixture://estate-history/declared
locator: dependency/orders-inventory
observer: fixture.owner
confidence: 1.0
stance: supports
observed_at: '2026-09-10T00:00:00Z'
extensions:
org.fiam.catalog:
version: 0.2-draft.5
processed_batches:
- '4444444444444444444444444444444444444444444444444444444444444444'
declared_entity_ids:
- node.orders
- node.inventory
- node.partner
- port.inventory.api
- contract.inventory
- operation.inventory.get
- binding.inventory
last_ingest_at: '2026-09-10T00:00:00Z'
runtime_policy: aggregate-by-architectural-tuple
occurrence_retention: none
sample_size: 0
org.fiam.runtime_aggregates: []
org.fiam.runtime_topology_observations:
- id: topology.orders-partner
domain: rpc
kind: direct-call
from: node.orders
to: node.partner
count: 20
first_seen: '2026-09-08T00:00:00Z'
last_seen: '2026-09-10T00:00:00Z'
correlation: fixture
- id: topology.orders-inventory.reappeared
domain: rpc
kind: direct-call
from: node.orders
to: node.inventory
binding: binding.inventory
operation: operation.inventory.get
count: 5
first_seen: '2026-09-10T00:00:00Z'
last_seen: '2026-09-10T00:00:00Z'
correlation: fixture
org.fiam.runtime_unresolved: []
org.fiam.reconciliation_candidates: []

17
history/FIAM_v0.2_Draft6/lenses/README.md Normal file
View file

@ -0,0 +1,17 @@
# FIAM Lenses
A Lens is an analysis/projection over the evidence-preserving FIAM graph and derived Architecture Intelligence Index. It is not a competing ontology and does not introduce primitive interface types.
Draft.6 ships these executable/reference lenses:
- `declared-vs-observed.yaml` — evidence-backed property agreement/refinement/conflict;
- `runtime-topology.yaml` — direct RPC, mediated messaging, and resource-oriented DB topology;
- `architecture-changes.yaml` — appeared/disappeared/newly-undeclared logical dependencies;
- `boundary-drift.yaml` — new Zone/trust/organization crossings;
- `architecture-policy.yaml` — named governance/materiality policy over factual findings;
- `operation-coverage.yaml` — observed/dormant/never-observed declared capabilities;
- `security-coverage.yaml` — effective declared security requirements;
- `security-evidence-coverage.yaml` — declared security alongside runtime evidence coverage/unknown;
- `evidence-health.yaml` — conflict, challenge, staleness, and weak support under a named scoring policy.
Lens outputs are derived query artifacts. They MUST identify relevant policy ids/hashes when interpretation depends on policy and MUST NOT silently rewrite FIAM assertions or historical intervals.

11
history/FIAM_v0.2_Draft6/lenses/architecture-changes.yaml Normal file
View file

@ -0,0 +1,11 @@
id: fiam.lens.architecture-changes
version: 0.2-draft.6
title: Architecture Changes
intent: Surface newly observed, disappeared, and newly undeclared runtime dependencies over a time window from the
persistent FIAM query index.
source: persistent-index
requires_authoritative_closure_for_disappearance: true
classifications:
- appeared
- disappeared
- newly-undeclared

6
history/FIAM_v0.2_Draft6/lenses/architecture-policy.yaml Normal file
View file

@ -0,0 +1,6 @@
id: fiam.lens.architecture-policy
version: 0.2-draft.6
intent: Project named governance policy over architecture-change and boundary facts without mutating FIAM history.
outputs:
- material-dependencies
- policy-violations

11
history/FIAM_v0.2_Draft6/lenses/boundary-drift.yaml Normal file
View file

@ -0,0 +1,11 @@
id: fiam.lens.boundary-drift
version: 0.2-draft.6
title: Boundary Drift
intent: Surface newly observed runtime dependencies whose endpoints occupy different monitored FIAM Zones, emphasizing
trust-zone and organizational crossings.
source: persistent-index
monitored_zone_types:
- fiam.zone-type.trust-zone
- fiam.zone-type.organization
- fiam.zone-type.deployment-environment
- fiam.zone-type.cluster

40
history/FIAM_v0.2_Draft6/lenses/declared-vs-observed.yaml Normal file
View file

@ -0,0 +1,40 @@
id: fiam.lens.declared-vs-observed
version: 0.2-draft.6
title: Declared vs Observed Architecture
description: 'Compares evidence-backed declared properties with runtime-observed properties on architectural records
related by corresponds-to. It preserves both source records and classifies agreement, refinement, gaps, and conflicts
without merging identities.
'
pair_relation: fiam.relation.corresponds-to
declared_evidence_modes:
- fiam.evidence.declared
observed_evidence_modes:
- fiam.evidence.runtime-observed
comparisons:
- predicate: fiam.property.communication-protocol
subject_kinds:
- binding
strategy: canon-hierarchy
include_missing: true
- predicate: fiam.property.network-protocol-version
subject_kinds:
- binding
strategy: exact
include_missing: true
- predicate: fiam.property.http-method
subject_kinds:
- operation
strategy: exact
include_missing: true
- predicate: fiam.property.server-address
subject_kinds:
- endpoint
strategy: exact
include_missing: true
- predicate: fiam.property.server-port
subject_kinds:
- endpoint
strategy: exact
include_missing: true
owner_resolution: provider-port-owner

12
history/FIAM_v0.2_Draft6/lenses/evidence-health.yaml Normal file
View file

@ -0,0 +1,12 @@
id: fiam.lens.evidence-health
version: 0.2-draft.6
intent: Surface conflicting, challenged, stale, and weak architectural facts using query-time evidence scoring.
inputs:
- indexed-assertions
- indexed-evidence
- evidence-scoring-policy
outputs:
- conflicts
- challenged
- stale-runtime-only
- low-support

7
history/FIAM_v0.2_Draft6/lenses/operation-coverage.yaml Normal file
View file

@ -0,0 +1,7 @@
id: fiam.lens.operation-coverage
version: 0.2-draft.6
intent: Compare effective declared operations with runtime aggregate last-seen evidence over a window.
outputs:
- observed-in-window
- dormant
- never-observed

22
history/FIAM_v0.2_Draft6/lenses/runtime-topology.yaml Normal file
View file

@ -0,0 +1,22 @@
id: fiam.lens.runtime-topology
version: 0.2-draft.6
title: Runtime Interaction Topology
description: 'Projects aggregated runtime-observed FIAM architecture observations into dependency/topology edges
while preserving the different structural semantics of RPC calls, mediated messaging, and database resource access.
It does not flatten Channels or InformationResources into generic service-to-service edges.
'
evidence_modes:
- fiam.evidence.runtime-observed
- fiam.evidence.inferred
domains:
- rpc
- messaging
- database
preserve_mediation: true
rpc_correlation: trace-parent-when-available
messaging_correlation: span-link-when-available
database_target_relations:
- fiam.relation.reads-from
- fiam.relation.writes-to
- fiam.relation.targets

7
history/FIAM_v0.2_Draft6/lenses/security-coverage.yaml Normal file
View file

@ -0,0 +1,7 @@
id: fiam.lens.security-coverage
version: 0.2-draft.6
title: Declared Security Coverage
description: Projects effective declared security requirements per operation, preserving OpenAPI OR alternatives
and AND-within-requirement semantics. Generic OTLP is not treated as evidence that authentication is absent.
source: declared-security-profiles
runtime_absence_semantics: unknown

7
history/FIAM_v0.2_Draft6/lenses/security-evidence-coverage.yaml Normal file
View file

@ -0,0 +1,7 @@
id: fiam.lens.security-evidence-coverage
version: 0.2-draft.6
intent: Show declared authentication coverage alongside explicit runtime security-evidence coverage while preserving
unknown.
outputs:
- declared-security-runtime-evidence-unknown
- declared-security-operation-not-observed

32
history/FIAM_v0.2_Draft6/policies/ARCHITECTURE-GOVERNANCE-v0.2.yaml Normal file
View file

@ -0,0 +1,32 @@
id: fiam.policy.architecture-governance.v0.2
version: '0.2'
status: provisional
materiality:
thresholds:
high: 0.75
medium: 0.45
weights:
undeclared: 0.35
trust_boundary: 0.25
organization_boundary: 0.15
high_volume: 0.15
strong_evidence: 0.10
high_volume_observation_count: 100
boundary_rules:
- id: require-declaration-internal-to-partner
zone_type: fiam.zone-type.trust-zone
from_zone: zone.trust.internal
to_zone: zone.trust.partner
condition: require-declared
severity: high
- id: forbid-prod-to-untrusted
zone_type: fiam.zone-type.trust-zone
from_zone: zone.trust.internal
to_zone: zone.trust.untrusted
condition: forbid
severity: critical
dormancy:
default_days: 90
evidence_health:
stale_runtime_days: 30
conflict_min_support: 0.45

1
history/FIAM_v0.2_Draft6/policies/CORE-FREEZE.sha256 Normal file
View file

@ -0,0 +1 @@
a6fce1b19ab7009069a1c8552fc6035cabd8707cb63b647350396d36785668d9 schemas/FIAM-Core-v0.2.schema.json

51
history/FIAM_v0.2_Draft6/policies/EVIDENCE-SCORING-v0.2.yaml Normal file
View file

@ -0,0 +1,51 @@
policy_version: '0.2'
id: fiam.policy.evidence-scoring.default
intent: Rank evidential support for architecture-intelligence queries without turning heuristic scores into truth probabilities
or rewriting source assertions.
combination: independent-noisy-or
independence_key:
- mode
- source.type
- source.ref
- source.locator
mode_weights:
fiam.evidence.declared: 1.0
fiam.evidence.static-observed: 0.9
fiam.evidence.runtime-observed: 0.95
fiam.evidence.inferred: 0.65
source_type_weights:
openapi-document: 1.0
architecture-declaration: 1.0
otlp-trace-stream: 0.95
otlp-trace-export: 0.95
otlp-aggregate: 0.98
schema-structural-fingerprint: 0.7
reconciliation-rule: 0.65
database-resource-mapping: 0.8
database-operation-semantics: 0.8
architecture-fixture: 0.6
entity-ref: 0.85
default_source_type_weight: 0.8
default_confidence: 0.75
freshness:
fiam.evidence.runtime-observed:
half_life_days: 14
floor: 0.25
fiam.evidence.inferred:
half_life_days: 30
floor: 0.4
fiam.evidence.declared:
half_life_days: null
floor: 1.0
fiam.evidence.static-observed:
half_life_days: null
floor: 1.0
interpretation:
strong: 0.85
moderate: 0.6
weak: 0.3
notes:
- Scores are query-ranking heuristics, not calibrated probabilities.
- Supporting and challenging evidence are scored separately.
- Independent sources combine; repeated observations from one locator do not count as independent corroboration.
- Runtime freshness decays for ranking purposes without deleting or mutating historical evidence.

56
history/FIAM_v0.2_Draft6/policies/FIAM-ShapeIdentity-v0.2.md Normal file
View file

@ -0,0 +1,56 @@
# FIAM v0.2 — InformationShape Identity Policy
## Purpose
FIAM treats `InformationShape` as an architectural identity node, not as a schema document and not as a wire-format label. This policy governs when separately discovered descriptions should be represented as one shape, multiple related shapes, or unresolved candidates.
## Identity rule
Two observations may refer to the **same InformationShape** when they are intended to describe the same admissible semantic/structural form even if they originate in different artifacts, languages, bindings, or representations.
Examples: one `Customer` shape described by OpenAPI and standalone JSON Schema; the same `Product` shape encoded as JSON and CBOR; a Java declaration and an API schema that an authoritative source explicitly maps to the same contract type.
## New shape rule
Create a distinct shape identity when a structural/constraint difference matters to the architecture, when a shape is intentionally versioned, or when a projection/subset/view exposes a different admissible form. Use `version-of` for lineage and `projection-of` for intentional views/projections.
Do **not** mint a new shape merely because another artifact describes it or another representation carries it.
## Uncertain reconciliation
Independent ingest sources should not immediately use `same-entity-as`. Prefer `corresponds-to` or `observationally-equivalent-to` while identity is uncertain. Promote to evidence-backed `same-entity-as` only when there is sufficient authoritative evidence.
`same-entity-as`, `alias-of`, `version-of`, and `observationally-equivalent-to` require subject and object to have the same FIAM entity kind. Identity assertions never delete source entities or evidence; repository reconciliation is a separate operation.
## Resource and shape
A stable InformationResource can change shape over time. Preserve separate shape identities with validity windows rather than overwriting history. A collection-like resource may `conforms-to-shape` a collection shape and separately use `element-shape` for its members.
## Artifact, representation, and shape
- Artifact: concrete declaration/implementation (`openapi.yaml`, `.proto`, DDL, Java source).
- Shape: logical admissible form.
- Representation: JSON, protobuf, command tokens, native object, etc.
- Resource: identifiable information-bearing locus/state/collection.
These identities must not be collapsed.
## Operational query semantics (draft.1)
An asserted `same-entity-as` edge places the participating IDs in one **query-time equivalence class**. It does not physically merge records. Traversal or presentation layers may collapse the class for convenience, but must retain and expose the original IDs and their evidence.
`corresponds-to` and `observationally-equivalent-to` do not create identity equivalence classes.
## Operational promotion guard (draft.1)
Automated tools must not promote structural or fingerprint equality directly to `same-entity-as`.
Default behavior:
1. create `corresponds-to` for plausible matches;
2. accumulate independent evidence;
3. require a governed/authoritative identity decision for normal promotion;
4. if `same-entity-as` is asserted purely from inferred evidence, require at least two independent signals at confidence `>= 0.98`;
5. even when that inferred threshold is met, default tooling must not auto-promote without reconciliation policy/authority.
The validator operationalizes the minimum inferred-evidence guard. `tools/identity_view.py` operationalizes non-destructive query equivalence and candidate reporting.

47
history/FIAM_v0.2_Draft6/policies/SNAPSHOT-AUTHORITY-v0.2.yaml Normal file
View file

@ -0,0 +1,47 @@
id: fiam.policy.snapshot-authority.v0.2
version: '0.2'
status: provisional
principles:
- Authority is scoped to an explicitly named observation population and domain set.
- A source may close only observations owned by its observation_scope.
- Sampled or incremental sources never prove absence.
- Overlap between different observation scopes is allowed and unioned at query time; overlap inside one observation_scope requires explicit layering.
- Closure is a policy action distinct from last_seen evidence.
defaults:
grace_hours: 6
absence_snapshots: 2
sources:
collector.prod.app-traces:
authoritative: true
observation_scope: prod-cluster-a-app-traces
population_id: prod-cluster-a
population:
environment: prod
cluster: cluster-a
platform: application-traces
domains: [http, rpc, database]
grace_hours: 6
absence_snapshots: 2
collector.prod.messaging:
authoritative: true
observation_scope: prod-cluster-a-messaging
population_id: prod-cluster-a
population:
environment: prod
cluster: cluster-a
platform: messaging-telemetry
domains: [messaging]
grace_hours: 6
absence_snapshots: 2
collector.prod.mesh:
authoritative: true
observation_scope: prod-cluster-a-mesh
population_id: prod-cluster-a
population:
environment: prod
cluster: cluster-a
platform: service-mesh
domains: [http, rpc]
grace_hours: 6
absence_snapshots: 2
layered_scopes: []

170
history/FIAM_v0.2_Draft6/real-world/catalog-exchange/bad-authority-scope.yaml Normal file
View file

@ -0,0 +1,170 @@
catalog_exchange_version: '0.2'
created_at: '2026-09-01T00:00:00Z'
exchange_id: exchange.bad.authority-scope
observation:
aggregate_semantics: cumulative
authority_policy_id: fiam.policy.snapshot-authority.v0.2
domains:
- rpc
mode: complete-snapshot
observation_scope: prod-cluster-a-app-traces
population:
cluster: cluster-a
environment: prod
platform: service-mesh
population_id: prod-cluster-a
snapshot_time: '2026-09-01T00:00:00Z'
profile_id: fiam.catalog-exchange.v0.2
records:
assertions: []
declared_entity_ids: []
entities:
- entity:
id: node.orders
kind: system-node
name: Orders
node_type: fiam.node-type.service
section: nodes
- entity:
id: node.inventory
kind: system-node
name: Inventory
node_type: fiam.node-type.service
section: nodes
- entity:
id: node.partner
kind: system-node
name: Partner API
node_type: fiam.node-type.application
section: nodes
- entity:
id: port.inventory.api
kind: port
owner: node.inventory
participations:
- contract: contract.inventory
mode: offers
roles:
- fiam.role.server
section: ports
- entity:
id: contract.inventory
kind: interface-contract
name: Inventory API
operations:
- id: operation.inventory.get
interaction_style: fiam.interaction-style.request-response
kind: operation
name: getInventory
purpose:
- fiam.purpose.query
section: contracts
- entity:
contract: contract.inventory
id: binding.inventory
kind: binding
operations:
- operation.inventory.get
provider_port: port.inventory.api
section: bindings
- entity:
id: zone.environment.prod
kind: zone
members:
- node.orders
- node.inventory
- node.partner
name: production
zone_type: fiam.zone-type.deployment-environment
section: zones
- entity:
id: zone.trust.internal
kind: zone
members:
- node.orders
- node.inventory
name: internal trust domain
zone_type: fiam.zone-type.trust-zone
section: zones
- entity:
id: zone.trust.partner
kind: zone
members:
- node.partner
name: partner trust domain
zone_type: fiam.zone-type.trust-zone
section: zones
- entity:
id: zone.org.internal
kind: zone
members:
- node.orders
- node.inventory
name: internal organization
zone_type: fiam.zone-type.organization
section: zones
- entity:
id: zone.org.partner
kind: zone
members:
- node.partner
name: partner organization
zone_type: fiam.zone-type.organization
section: zones
reconciliation_candidates: []
runtime_aggregates: []
topology_observations:
- binding: binding.inventory
correlation: fixture
count: 100
domain: rpc
first_seen: '2026-08-25T00:00:00Z'
from: node.orders
id: topology.orders-inventory
kind: direct-call
last_seen: '2026-09-01T00:00:00Z'
operation: operation.inventory.get
to: node.inventory
unresolved: []
zone_memberships:
- derived: false
member_id: node.inventory
zone_id: zone.environment.prod
zone_type: fiam.zone-type.deployment-environment
- derived: false
member_id: node.orders
zone_id: zone.environment.prod
zone_type: fiam.zone-type.deployment-environment
- derived: false
member_id: node.partner
zone_id: zone.environment.prod
zone_type: fiam.zone-type.deployment-environment
- derived: false
member_id: node.inventory
zone_id: zone.org.internal
zone_type: fiam.zone-type.organization
- derived: false
member_id: node.orders
zone_id: zone.org.internal
zone_type: fiam.zone-type.organization
- derived: false
member_id: node.partner
zone_id: zone.org.partner
zone_type: fiam.zone-type.organization
- derived: false
member_id: node.inventory
zone_id: zone.trust.internal
zone_type: fiam.zone-type.trust-zone
- derived: false
member_id: node.orders
zone_id: zone.trust.internal
zone_type: fiam.zone-type.trust-zone
- derived: false
member_id: node.partner
zone_id: zone.trust.partner
zone_type: fiam.zone-type.trust-zone
source:
content_hash: 5d9aa3c294efa4a8b13b5c291837a19f9cb795e364370ec414f64202fa017c9b
source_id: collector.prod.mesh
source_kind: otel-mesh-adapter
source_ref: estate://collector/prod/mesh

177
history/FIAM_v0.2_Draft6/real-world/catalog-exchange/declared-2026-09-01.yaml Normal file
View file

@ -0,0 +1,177 @@
catalog_exchange_version: '0.2'
profile_id: fiam.catalog-exchange.v0.2
exchange_id: exchange.579770301744fd3e9b7d3709
created_at: '2026-09-01T00:00:00Z'
source:
source_id: architecture.git
source_kind: openapi-and-architecture
source_ref: estate://architecture/prod
content_hash: 5d9aa3c294efa4a8b13b5c291837a19f9cb795e364370ec414f64202fa017c9b
observation:
mode: declared-snapshot
snapshot_time: '2026-09-01T00:00:00Z'
observation_scope: null
population_id: prod-cluster-a
population: {}
domains: []
aggregate_semantics: cumulative
records:
entities:
- section: nodes
entity:
id: node.orders
kind: system-node
name: Orders
node_type: fiam.node-type.service
- section: nodes
entity:
id: node.inventory
kind: system-node
name: Inventory
node_type: fiam.node-type.service
- section: nodes
entity:
id: node.partner
kind: system-node
name: Partner API
node_type: fiam.node-type.application
- section: ports
entity:
id: port.inventory.api
kind: port
owner: node.inventory
participations:
- contract: contract.inventory
mode: offers
roles:
- fiam.role.server
- section: contracts
entity:
id: contract.inventory
kind: interface-contract
name: Inventory API
purpose:
- fiam.purpose.query
operations:
- id: operation.inventory.get
kind: operation
name: getInventory
interaction_style: fiam.interaction-style.request-response
- section: bindings
entity:
id: binding.inventory
kind: binding
contract: contract.inventory
provider_port: port.inventory.api
operations:
- operation.inventory.get
- section: zones
entity:
id: zone.environment.prod
kind: zone
name: production
zone_type: fiam.zone-type.deployment-environment
members:
- node.orders
- node.inventory
- node.partner
- section: zones
entity:
id: zone.trust.internal
kind: zone
name: internal trust domain
zone_type: fiam.zone-type.trust-zone
members:
- node.orders
- node.inventory
- section: zones
entity:
id: zone.trust.partner
kind: zone
name: partner trust domain
zone_type: fiam.zone-type.trust-zone
members:
- node.partner
- section: zones
entity:
id: zone.org.internal
kind: zone
name: internal organization
zone_type: fiam.zone-type.organization
members:
- node.orders
- node.inventory
- section: zones
entity:
id: zone.org.partner
kind: zone
name: partner organization
zone_type: fiam.zone-type.organization
members:
- node.partner
assertions:
- id: assertion.declared.orders-uses-inventory
assertion_kind: relation
subject: node.orders
predicate: fiam.relation.uses
polarity: asserted
object_ref: binding.inventory
evidence:
mode: fiam.evidence.declared
source:
type: architecture-declaration
ref: fixture://estate-history/declared
locator: dependency/orders-inventory
observer: fixture.owner
confidence: 1.0
stance: supports
observed_at: '2026-09-01T00:00:00Z'
zone_memberships:
- zone_id: zone.environment.prod
member_id: node.inventory
zone_type: fiam.zone-type.deployment-environment
derived: false
- zone_id: zone.environment.prod
member_id: node.orders
zone_type: fiam.zone-type.deployment-environment
derived: false
- zone_id: zone.environment.prod
member_id: node.partner
zone_type: fiam.zone-type.deployment-environment
derived: false
- zone_id: zone.org.internal
member_id: node.inventory
zone_type: fiam.zone-type.organization
derived: false
- zone_id: zone.org.internal
member_id: node.orders
zone_type: fiam.zone-type.organization
derived: false
- zone_id: zone.org.partner
member_id: node.partner
zone_type: fiam.zone-type.organization
derived: false
- zone_id: zone.trust.internal
member_id: node.inventory
zone_type: fiam.zone-type.trust-zone
derived: false
- zone_id: zone.trust.internal
member_id: node.orders
zone_type: fiam.zone-type.trust-zone
derived: false
- zone_id: zone.trust.partner
member_id: node.partner
zone_type: fiam.zone-type.trust-zone
derived: false
runtime_aggregates: []
topology_observations: []
unresolved: []
reconciliation_candidates: []
declared_entity_ids:
- node.orders
- node.inventory
- node.partner
- port.inventory.api
- contract.inventory
- operation.inventory.get
- binding.inventory

106
history/FIAM_v0.2_Draft6/real-world/catalog-exchange/evidence-health.yaml Normal file
View file

@ -0,0 +1,106 @@
catalog_exchange_version: '0.2'
profile_id: fiam.catalog-exchange.v0.2
exchange_id: exchange.evidence-health
created_at: '2026-09-09T00:00:00Z'
source:
source_id: fixture.evidence
source_kind: architecture-and-runtime
source_ref: fixture://evidence
content_hash: null
observation:
mode: declared-snapshot
observation_scope: null
population_id: evidence-pop
population: {}
domains: []
snapshot_time: '2026-09-09T00:00:00Z'
aggregate_semantics: cumulative
records:
entities:
- section: nodes
entity:
id: node.evidence.api
kind: system-node
name: Evidence API
node_type: fiam.node-type.service
assertions:
- id: assertion.protocol.http11
assertion_kind: property
subject: node.evidence.api
predicate: fiam.property.network-protocol-version
polarity: asserted
value: '1.1'
evidence:
- mode: fiam.evidence.declared
source:
type: architecture-declaration
ref: arch://http-policy
locator: fixture
observer: fixture
observed_at: '2026-09-08T00:00:00Z'
confidence: 0.95
stance: supports
- id: assertion.protocol.http2
assertion_kind: property
subject: node.evidence.api
predicate: fiam.property.network-protocol-version
polarity: asserted
value: '2'
evidence:
- mode: fiam.evidence.runtime-observed
source:
type: otlp-trace-stream
ref: otel://old-http2
locator: fixture
observer: fixture
observed_at: '2026-08-25T00:00:00Z'
confidence: 0.95
stance: supports
- id: assertion.service-name
assertion_kind: property
subject: node.evidence.api
predicate: fiam.property.service-name
polarity: asserted
value: evidence-api
evidence:
- mode: fiam.evidence.declared
source:
type: architecture-declaration
ref: arch://service
locator: fixture
observer: fixture
observed_at: '2026-09-08T00:00:00Z'
confidence: 0.95
stance: supports
- mode: fiam.evidence.runtime-observed
source:
type: otlp-trace-stream
ref: otel://challenge
locator: fixture
observer: fixture
observed_at: '2026-09-08T01:00:00Z'
confidence: 0.8
stance: challenges
- id: assertion.stale-peer
assertion_kind: property
subject: node.evidence.api
predicate: fiam.property.service-peer-name
polarity: asserted
value: legacy-peer
evidence:
- mode: fiam.evidence.runtime-observed
source:
type: otlp-trace-stream
ref: otel://legacy-peer
locator: fixture
observer: fixture
observed_at: '2026-06-01T00:00:00Z'
confidence: 0.95
stance: supports
zone_memberships: []
runtime_aggregates: []
topology_observations: []
unresolved: []
reconciliation_candidates: []
declared_entity_ids:
- node.evidence.api

170
history/FIAM_v0.2_Draft6/real-world/catalog-exchange/mesh-runtime-2026-09-01.yaml Normal file
View file

@ -0,0 +1,170 @@
catalog_exchange_version: '0.2'
profile_id: fiam.catalog-exchange.v0.2
exchange_id: exchange.32f0ef0c9e863d095b026e5d
created_at: '2026-09-01T00:00:00Z'
source:
source_id: collector.prod.mesh
source_kind: otel-mesh-adapter
source_ref: estate://collector/prod/mesh
content_hash: 5d9aa3c294efa4a8b13b5c291837a19f9cb795e364370ec414f64202fa017c9b
observation:
mode: complete-snapshot
snapshot_time: '2026-09-01T00:00:00Z'
observation_scope: prod-cluster-a-mesh
population_id: prod-cluster-a
population:
environment: prod
cluster: cluster-a
platform: service-mesh
domains:
- rpc
aggregate_semantics: cumulative
authority_policy_id: fiam.policy.snapshot-authority.v0.2
records:
entities:
- section: nodes
entity:
id: node.orders
kind: system-node
name: Orders
node_type: fiam.node-type.service
- section: nodes
entity:
id: node.inventory
kind: system-node
name: Inventory
node_type: fiam.node-type.service
- section: nodes
entity:
id: node.partner
kind: system-node
name: Partner API
node_type: fiam.node-type.application
- section: ports
entity:
id: port.inventory.api
kind: port
owner: node.inventory
participations:
- contract: contract.inventory
mode: offers
roles:
- fiam.role.server
- section: contracts
entity:
id: contract.inventory
kind: interface-contract
name: Inventory API
purpose:
- fiam.purpose.query
operations:
- id: operation.inventory.get
kind: operation
name: getInventory
interaction_style: fiam.interaction-style.request-response
- section: bindings
entity:
id: binding.inventory
kind: binding
contract: contract.inventory
provider_port: port.inventory.api
operations:
- operation.inventory.get
- section: zones
entity:
id: zone.environment.prod
kind: zone
name: production
zone_type: fiam.zone-type.deployment-environment
members:
- node.orders
- node.inventory
- node.partner
- section: zones
entity:
id: zone.trust.internal
kind: zone
name: internal trust domain
zone_type: fiam.zone-type.trust-zone
members:
- node.orders
- node.inventory
- section: zones
entity:
id: zone.trust.partner
kind: zone
name: partner trust domain
zone_type: fiam.zone-type.trust-zone
members:
- node.partner
- section: zones
entity:
id: zone.org.internal
kind: zone
name: internal organization
zone_type: fiam.zone-type.organization
members:
- node.orders
- node.inventory
- section: zones
entity:
id: zone.org.partner
kind: zone
name: partner organization
zone_type: fiam.zone-type.organization
members:
- node.partner
assertions: []
zone_memberships:
- zone_id: zone.environment.prod
member_id: node.inventory
zone_type: fiam.zone-type.deployment-environment
derived: false
- zone_id: zone.environment.prod
member_id: node.orders
zone_type: fiam.zone-type.deployment-environment
derived: false
- zone_id: zone.environment.prod
member_id: node.partner
zone_type: fiam.zone-type.deployment-environment
derived: false
- zone_id: zone.org.internal
member_id: node.inventory
zone_type: fiam.zone-type.organization
derived: false
- zone_id: zone.org.internal
member_id: node.orders
zone_type: fiam.zone-type.organization
derived: false
- zone_id: zone.org.partner
member_id: node.partner
zone_type: fiam.zone-type.organization
derived: false
- zone_id: zone.trust.internal
member_id: node.inventory
zone_type: fiam.zone-type.trust-zone
derived: false
- zone_id: zone.trust.internal
member_id: node.orders
zone_type: fiam.zone-type.trust-zone
derived: false
- zone_id: zone.trust.partner
member_id: node.partner
zone_type: fiam.zone-type.trust-zone
derived: false
runtime_aggregates: []
topology_observations:
- id: topology.orders-inventory
domain: rpc
kind: direct-call
from: node.orders
to: node.inventory
binding: binding.inventory
operation: operation.inventory.get
count: 100
first_seen: '2026-08-25T00:00:00Z'
last_seen: '2026-09-01T00:00:00Z'
correlation: fixture
unresolved: []
reconciliation_candidates: []
declared_entity_ids: []

170
history/FIAM_v0.2_Draft6/real-world/catalog-exchange/runtime-2026-09-01.yaml Normal file
View file

@ -0,0 +1,170 @@
catalog_exchange_version: '0.2'
profile_id: fiam.catalog-exchange.v0.2
exchange_id: exchange.d41216a2d3882ac1dff2b4e6
created_at: '2026-09-01T00:00:00Z'
source:
source_id: collector.prod.app-traces
source_kind: otlp-adapter
source_ref: estate://collector/prod/app-traces
content_hash: 5d9aa3c294efa4a8b13b5c291837a19f9cb795e364370ec414f64202fa017c9b
observation:
mode: complete-snapshot
snapshot_time: '2026-09-01T00:00:00Z'
observation_scope: prod-cluster-a-app-traces
population_id: prod-cluster-a
population:
environment: prod
cluster: cluster-a
platform: application-traces
domains:
- rpc
aggregate_semantics: cumulative
authority_policy_id: fiam.policy.snapshot-authority.v0.2
records:
entities:
- section: nodes
entity:
id: node.orders
kind: system-node
name: Orders
node_type: fiam.node-type.service
- section: nodes
entity:
id: node.inventory
kind: system-node
name: Inventory
node_type: fiam.node-type.service
- section: nodes
entity:
id: node.partner
kind: system-node
name: Partner API
node_type: fiam.node-type.application
- section: ports
entity:
id: port.inventory.api
kind: port
owner: node.inventory
participations:
- contract: contract.inventory
mode: offers
roles:
- fiam.role.server
- section: contracts
entity:
id: contract.inventory
kind: interface-contract
name: Inventory API
purpose:
- fiam.purpose.query
operations:
- id: operation.inventory.get
kind: operation
name: getInventory
interaction_style: fiam.interaction-style.request-response
- section: bindings
entity:
id: binding.inventory
kind: binding
contract: contract.inventory
provider_port: port.inventory.api
operations:
- operation.inventory.get
- section: zones
entity:
id: zone.environment.prod
kind: zone
name: production
zone_type: fiam.zone-type.deployment-environment
members:
- node.orders
- node.inventory
- node.partner
- section: zones
entity:
id: zone.trust.internal
kind: zone
name: internal trust domain
zone_type: fiam.zone-type.trust-zone
members:
- node.orders
- node.inventory
- section: zones
entity:
id: zone.trust.partner
kind: zone
name: partner trust domain
zone_type: fiam.zone-type.trust-zone
members:
- node.partner
- section: zones
entity:
id: zone.org.internal
kind: zone
name: internal organization
zone_type: fiam.zone-type.organization
members:
- node.orders
- node.inventory
- section: zones
entity:
id: zone.org.partner
kind: zone
name: partner organization
zone_type: fiam.zone-type.organization
members:
- node.partner
assertions: []
zone_memberships:
- zone_id: zone.environment.prod
member_id: node.inventory
zone_type: fiam.zone-type.deployment-environment
derived: false
- zone_id: zone.environment.prod
member_id: node.orders
zone_type: fiam.zone-type.deployment-environment
derived: false
- zone_id: zone.environment.prod
member_id: node.partner
zone_type: fiam.zone-type.deployment-environment
derived: false
- zone_id: zone.org.internal
member_id: node.inventory
zone_type: fiam.zone-type.organization
derived: false
- zone_id: zone.org.internal
member_id: node.orders
zone_type: fiam.zone-type.organization
derived: false
- zone_id: zone.org.partner
member_id: node.partner
zone_type: fiam.zone-type.organization
derived: false
- zone_id: zone.trust.internal
member_id: node.inventory
zone_type: fiam.zone-type.trust-zone
derived: false
- zone_id: zone.trust.internal
member_id: node.orders
zone_type: fiam.zone-type.trust-zone
derived: false
- zone_id: zone.trust.partner
member_id: node.partner
zone_type: fiam.zone-type.trust-zone
derived: false
runtime_aggregates: []
topology_observations:
- id: topology.orders-inventory
domain: rpc
kind: direct-call
from: node.orders
to: node.inventory
binding: binding.inventory
operation: operation.inventory.get
count: 100
first_seen: '2026-08-25T00:00:00Z'
last_seen: '2026-09-01T00:00:00Z'
correlation: fixture
unresolved: []
reconciliation_candidates: []
declared_entity_ids: []

168
history/FIAM_v0.2_Draft6/real-world/catalog-exchange/runtime-2026-09-08.yaml Normal file
View file

@ -0,0 +1,168 @@
catalog_exchange_version: '0.2'
profile_id: fiam.catalog-exchange.v0.2
exchange_id: exchange.8f690b6aa87b67f18cb9b593
created_at: '2026-09-08T00:00:00Z'
source:
source_id: collector.prod.app-traces
source_kind: otlp-adapter
source_ref: estate://collector/prod/app-traces
content_hash: 7384989f29f9a26eec85ed4eae54235a09856c705e96cc3e2d4e9dca8afcdb50
observation:
mode: complete-snapshot
snapshot_time: '2026-09-08T00:00:00Z'
observation_scope: prod-cluster-a-app-traces
population_id: prod-cluster-a
population:
environment: prod
cluster: cluster-a
platform: application-traces
domains:
- rpc
aggregate_semantics: cumulative
authority_policy_id: fiam.policy.snapshot-authority.v0.2
records:
entities:
- section: nodes
entity:
id: node.orders
kind: system-node
name: Orders
node_type: fiam.node-type.service
- section: nodes
entity:
id: node.inventory
kind: system-node
name: Inventory
node_type: fiam.node-type.service
- section: nodes
entity:
id: node.partner
kind: system-node
name: Partner API
node_type: fiam.node-type.application
- section: ports
entity:
id: port.inventory.api
kind: port
owner: node.inventory
participations:
- contract: contract.inventory
mode: offers
roles:
- fiam.role.server
- section: contracts
entity:
id: contract.inventory
kind: interface-contract
name: Inventory API
purpose:
- fiam.purpose.query
operations:
- id: operation.inventory.get
kind: operation
name: getInventory
interaction_style: fiam.interaction-style.request-response
- section: bindings
entity:
id: binding.inventory
kind: binding
contract: contract.inventory
provider_port: port.inventory.api
operations:
- operation.inventory.get
- section: zones
entity:
id: zone.environment.prod
kind: zone
name: production
zone_type: fiam.zone-type.deployment-environment
members:
- node.orders
- node.inventory
- node.partner
- section: zones
entity:
id: zone.trust.internal
kind: zone
name: internal trust domain
zone_type: fiam.zone-type.trust-zone
members:
- node.orders
- node.inventory
- section: zones
entity:
id: zone.trust.partner
kind: zone
name: partner trust domain
zone_type: fiam.zone-type.trust-zone
members:
- node.partner
- section: zones
entity:
id: zone.org.internal
kind: zone
name: internal organization
zone_type: fiam.zone-type.organization
members:
- node.orders
- node.inventory
- section: zones
entity:
id: zone.org.partner
kind: zone
name: partner organization
zone_type: fiam.zone-type.organization
members:
- node.partner
assertions: []
zone_memberships:
- zone_id: zone.environment.prod
member_id: node.inventory
zone_type: fiam.zone-type.deployment-environment
derived: false
- zone_id: zone.environment.prod
member_id: node.orders
zone_type: fiam.zone-type.deployment-environment
derived: false
- zone_id: zone.environment.prod
member_id: node.partner
zone_type: fiam.zone-type.deployment-environment
derived: false
- zone_id: zone.org.internal
member_id: node.inventory
zone_type: fiam.zone-type.organization
derived: false
- zone_id: zone.org.internal
member_id: node.orders
zone_type: fiam.zone-type.organization
derived: false
- zone_id: zone.org.partner
member_id: node.partner
zone_type: fiam.zone-type.organization
derived: false
- zone_id: zone.trust.internal
member_id: node.inventory
zone_type: fiam.zone-type.trust-zone
derived: false
- zone_id: zone.trust.internal
member_id: node.orders
zone_type: fiam.zone-type.trust-zone
derived: false
- zone_id: zone.trust.partner
member_id: node.partner
zone_type: fiam.zone-type.trust-zone
derived: false
runtime_aggregates: []
topology_observations:
- id: topology.orders-partner
domain: rpc
kind: direct-call
from: node.orders
to: node.partner
count: 12
first_seen: '2026-09-08T00:00:00Z'
last_seen: '2026-09-08T00:00:00Z'
correlation: fixture
unresolved: []
reconciliation_candidates: []
declared_entity_ids: []

168
history/FIAM_v0.2_Draft6/real-world/catalog-exchange/runtime-2026-09-09.yaml Normal file
View file

@ -0,0 +1,168 @@
catalog_exchange_version: '0.2'
profile_id: fiam.catalog-exchange.v0.2
exchange_id: exchange.5028fed51f1365aedeb7ca55
created_at: '2026-09-09T00:00:00Z'
source:
source_id: collector.prod.app-traces
source_kind: otlp-adapter
source_ref: estate://collector/prod/app-traces
content_hash: 7384989f29f9a26eec85ed4eae54235a09856c705e96cc3e2d4e9dca8afcdb50
observation:
mode: complete-snapshot
snapshot_time: '2026-09-09T00:00:00Z'
observation_scope: prod-cluster-a-app-traces
population_id: prod-cluster-a
population:
environment: prod
cluster: cluster-a
platform: application-traces
domains:
- rpc
aggregate_semantics: cumulative
authority_policy_id: fiam.policy.snapshot-authority.v0.2
records:
entities:
- section: nodes
entity:
id: node.orders
kind: system-node
name: Orders
node_type: fiam.node-type.service
- section: nodes
entity:
id: node.inventory
kind: system-node
name: Inventory
node_type: fiam.node-type.service
- section: nodes
entity:
id: node.partner
kind: system-node
name: Partner API
node_type: fiam.node-type.application
- section: ports
entity:
id: port.inventory.api
kind: port
owner: node.inventory
participations:
- contract: contract.inventory
mode: offers
roles:
- fiam.role.server
- section: contracts
entity:
id: contract.inventory
kind: interface-contract
name: Inventory API
purpose:
- fiam.purpose.query
operations:
- id: operation.inventory.get
kind: operation
name: getInventory
interaction_style: fiam.interaction-style.request-response
- section: bindings
entity:
id: binding.inventory
kind: binding
contract: contract.inventory
provider_port: port.inventory.api
operations:
- operation.inventory.get
- section: zones
entity:
id: zone.environment.prod
kind: zone
name: production
zone_type: fiam.zone-type.deployment-environment
members:
- node.orders
- node.inventory
- node.partner
- section: zones
entity:
id: zone.trust.internal
kind: zone
name: internal trust domain
zone_type: fiam.zone-type.trust-zone
members:
- node.orders
- node.inventory
- section: zones
entity:
id: zone.trust.partner
kind: zone
name: partner trust domain
zone_type: fiam.zone-type.trust-zone
members:
- node.partner
- section: zones
entity:
id: zone.org.internal
kind: zone
name: internal organization
zone_type: fiam.zone-type.organization
members:
- node.orders
- node.inventory
- section: zones
entity:
id: zone.org.partner
kind: zone
name: partner organization
zone_type: fiam.zone-type.organization
members:
- node.partner
assertions: []
zone_memberships:
- zone_id: zone.environment.prod
member_id: node.inventory
zone_type: fiam.zone-type.deployment-environment
derived: false
- zone_id: zone.environment.prod
member_id: node.orders
zone_type: fiam.zone-type.deployment-environment
derived: false
- zone_id: zone.environment.prod
member_id: node.partner
zone_type: fiam.zone-type.deployment-environment
derived: false
- zone_id: zone.org.internal
member_id: node.inventory
zone_type: fiam.zone-type.organization
derived: false
- zone_id: zone.org.internal
member_id: node.orders
zone_type: fiam.zone-type.organization
derived: false
- zone_id: zone.org.partner
member_id: node.partner
zone_type: fiam.zone-type.organization
derived: false
- zone_id: zone.trust.internal
member_id: node.inventory
zone_type: fiam.zone-type.trust-zone
derived: false
- zone_id: zone.trust.internal
member_id: node.orders
zone_type: fiam.zone-type.trust-zone
derived: false
- zone_id: zone.trust.partner
member_id: node.partner
zone_type: fiam.zone-type.trust-zone
derived: false
runtime_aggregates: []
topology_observations:
- id: topology.orders-partner
domain: rpc
kind: direct-call
from: node.orders
to: node.partner
count: 12
first_seen: '2026-09-08T00:00:00Z'
last_seen: '2026-09-08T00:00:00Z'
correlation: fixture
unresolved: []
reconciliation_candidates: []
declared_entity_ids: []

179
history/FIAM_v0.2_Draft6/real-world/catalog-exchange/runtime-2026-09-10.yaml Normal file
View file

@ -0,0 +1,179 @@
catalog_exchange_version: '0.2'
profile_id: fiam.catalog-exchange.v0.2
exchange_id: exchange.14331448fd1f498bb4d812cf
created_at: '2026-09-10T00:00:00Z'
source:
source_id: collector.prod.app-traces
source_kind: otlp-adapter
source_ref: estate://collector/prod/app-traces
content_hash: b1a6db4f17c375349d216a4e43aae340bbd3c9a1521902fc162f2e4ee79408cb
observation:
mode: complete-snapshot
snapshot_time: '2026-09-10T00:00:00Z'
observation_scope: prod-cluster-a-app-traces
population_id: prod-cluster-a
population:
environment: prod
cluster: cluster-a
platform: application-traces
domains:
- rpc
aggregate_semantics: cumulative
authority_policy_id: fiam.policy.snapshot-authority.v0.2
records:
entities:
- section: nodes
entity:
id: node.orders
kind: system-node
name: Orders
node_type: fiam.node-type.service
- section: nodes
entity:
id: node.inventory
kind: system-node
name: Inventory
node_type: fiam.node-type.service
- section: nodes
entity:
id: node.partner
kind: system-node
name: Partner API
node_type: fiam.node-type.application
- section: ports
entity:
id: port.inventory.api
kind: port
owner: node.inventory
participations:
- contract: contract.inventory
mode: offers
roles:
- fiam.role.server
- section: contracts
entity:
id: contract.inventory
kind: interface-contract
name: Inventory API
purpose:
- fiam.purpose.query
operations:
- id: operation.inventory.get
kind: operation
name: getInventory
interaction_style: fiam.interaction-style.request-response
- section: bindings
entity:
id: binding.inventory
kind: binding
contract: contract.inventory
provider_port: port.inventory.api
operations:
- operation.inventory.get
- section: zones
entity:
id: zone.environment.prod
kind: zone
name: production
zone_type: fiam.zone-type.deployment-environment
members:
- node.orders
- node.inventory
- node.partner
- section: zones
entity:
id: zone.trust.internal
kind: zone
name: internal trust domain
zone_type: fiam.zone-type.trust-zone
members:
- node.orders
- node.inventory
- section: zones
entity:
id: zone.trust.partner
kind: zone
name: partner trust domain
zone_type: fiam.zone-type.trust-zone
members:
- node.partner
- section: zones
entity:
id: zone.org.internal
kind: zone
name: internal organization
zone_type: fiam.zone-type.organization
members:
- node.orders
- node.inventory
- section: zones
entity:
id: zone.org.partner
kind: zone
name: partner organization
zone_type: fiam.zone-type.organization
members:
- node.partner
assertions: []
zone_memberships:
- zone_id: zone.environment.prod
member_id: node.inventory
zone_type: fiam.zone-type.deployment-environment
derived: false
- zone_id: zone.environment.prod
member_id: node.orders
zone_type: fiam.zone-type.deployment-environment
derived: false
- zone_id: zone.environment.prod
member_id: node.partner
zone_type: fiam.zone-type.deployment-environment
derived: false
- zone_id: zone.org.internal
member_id: node.inventory
zone_type: fiam.zone-type.organization
derived: false
- zone_id: zone.org.internal
member_id: node.orders
zone_type: fiam.zone-type.organization
derived: false
- zone_id: zone.org.partner
member_id: node.partner
zone_type: fiam.zone-type.organization
derived: false
- zone_id: zone.trust.internal
member_id: node.inventory
zone_type: fiam.zone-type.trust-zone
derived: false
- zone_id: zone.trust.internal
member_id: node.orders
zone_type: fiam.zone-type.trust-zone
derived: false
- zone_id: zone.trust.partner
member_id: node.partner
zone_type: fiam.zone-type.trust-zone
derived: false
runtime_aggregates: []
topology_observations:
- id: topology.orders-partner
domain: rpc
kind: direct-call
from: node.orders
to: node.partner
count: 20
first_seen: '2026-09-08T00:00:00Z'
last_seen: '2026-09-10T00:00:00Z'
correlation: fixture
- id: topology.orders-inventory.reappeared
domain: rpc
kind: direct-call
from: node.orders
to: node.inventory
binding: binding.inventory
operation: operation.inventory.get
count: 5
first_seen: '2026-09-10T00:00:00Z'
last_seen: '2026-09-10T00:00:00Z'
correlation: fixture
unresolved: []
reconciliation_candidates: []
declared_entity_ids: []

696
history/FIAM_v0.2_Draft6/real-world/catalog-exchange/security-declared.yaml Normal file
View file

@ -0,0 +1,696 @@
catalog_exchange_version: '0.2'
profile_id: fiam.catalog-exchange.v0.2
exchange_id: exchange.2d2eb13476c62be2b7514239
created_at: '2026-09-01T00:00:00Z'
source:
source_id: architecture.openapi
source_kind: openapi-adapter
source_ref: estate://openapi/security-api
content_hash: bf2b36b164e0549fcaabf775ce3e6ed08ce4dea89ec6086030717421c07e69c4
observation:
mode: declared-snapshot
snapshot_time: '2026-09-01T00:00:00Z'
observation_scope: null
population_id: security-prod
population: {}
domains: []
aggregate_semantics: cumulative
records:
entities:
- section: nodes
entity:
id: node.openapi.estate-security-api
kind: system-node
name: Estate Security API
node_type: fiam.node-type.service
- section: ports
entity:
id: port.openapi.estate-security-api
owner: node.openapi.estate-security-api
participations:
- contract: contract.openapi.estate-security-api
mode: offers
- section: contracts
entity:
id: contract.openapi.estate-security-api
kind: interface-contract
name: Estate Security API
contract_forms:
- fiam.contract-form.openapi
operations:
- id: operation.openapi.estate-security-api.listItems
kind: operation
name: listItems
description: ''
interaction_style: fiam.interaction-style.request-response
effect: fiam.effect.read
purpose:
- fiam.purpose.query
x-http-method: GET
x-openapi-path: /items
x-openapi-operation-id: listItems
- id: operation.openapi.estate-security-api.createItem
kind: operation
name: createItem
description: ''
interaction_style: fiam.interaction-style.request-response
effect: fiam.effect.write
purpose:
- fiam.purpose.mutation
x-http-method: POST
x-openapi-path: /items
x-openapi-operation-id: createItem
- id: operation.openapi.estate-security-api.optionalInfo
kind: operation
name: optionalInfo
description: ''
interaction_style: fiam.interaction-style.request-response
effect: fiam.effect.read
purpose:
- fiam.purpose.query
x-http-method: GET
x-openapi-path: /optional
x-openapi-operation-id: optionalInfo
- id: operation.openapi.estate-security-api.publicInfo
kind: operation
name: publicInfo
description: ''
interaction_style: fiam.interaction-style.request-response
effect: fiam.effect.read
purpose:
- fiam.purpose.query
x-http-method: GET
x-openapi-path: /public
x-openapi-operation-id: publicInfo
- section: endpoints
entity:
id: endpoint.openapi.estate-security-api.1
kind: endpoint
name: OpenAPI server 1
address: https://security.example.test
address_scheme: fiam.address-scheme.https-url
- section: bindings
entity:
id: binding.openapi.estate-security-api.1
kind: binding
contract: contract.openapi.estate-security-api
provider_port: port.openapi.estate-security-api
endpoints:
- endpoint.openapi.estate-security-api.1
communication_stack:
- role: fiam.stack-role.application-transfer-protocol
term: fiam.protocol.http
- role: fiam.stack-role.security-protocol
term: fiam.protocol.tls
operations:
- operation.openapi.estate-security-api.listItems
- operation.openapi.estate-security-api.createItem
- operation.openapi.estate-security-api.optionalInfo
- operation.openapi.estate-security-api.publicInfo
- section: information_resources
entity:
id: resource.openapi.estate-security-api.items
kind: information-resource
owner: node.openapi.estate-security-api
name: /items
resource_kind: fiam.information-resource.api-resource-collection
resource_scope: fiam.resource-scope.logical-selection
selectors:
- kind: fiam.resource-selector.http-path-template
value: /items
- section: information_resources
entity:
id: resource.openapi.estate-security-api.optional
kind: information-resource
owner: node.openapi.estate-security-api
name: /optional
resource_kind: fiam.information-resource.api-resource-collection
resource_scope: fiam.resource-scope.logical-selection
selectors:
- kind: fiam.resource-selector.http-path-template
value: /optional
- section: information_resources
entity:
id: resource.openapi.estate-security-api.public
kind: information-resource
owner: node.openapi.estate-security-api
name: /public
resource_kind: fiam.information-resource.api-resource-collection
resource_scope: fiam.resource-scope.logical-selection
selectors:
- kind: fiam.resource-selector.http-path-template
value: /public
- section: information_shapes
entity:
id: shape.openapi.estate-security-api.Item
kind: information-shape
name: Item
shape_kind: fiam.information-shape.object
facets:
openapi_component: Item
- section: information_shapes
entity:
id: shape.openapi.estate-security-api.inline.listItems-response.7b4df76d
kind: information-shape
name: listItems response
shape_kind: fiam.information-shape.collection
facets:
openapi_pointer: '#/paths/~1items/get/responses/200/content/application~1json/schema'
- section: artifacts
entity:
id: artifact.openapi.estate-security-api
kind: artifact
name: security-api.yaml
artifact_type: fiam.artifact.api-description
describes:
- contract.openapi.estate-security-api
- shape.openapi.estate-security-api.Item
- shape.openapi.estate-security-api.inline.listItems-response.7b4df76d
- security.openapi.estate-security-api.contract.openapi.estate-security-api.1.oidc
- security.openapi.estate-security-api.operation.openapi.estate-security-api.createItem.1.apiKey
- security.openapi.estate-security-api.operation.openapi.estate-security-api.optionalInfo.2.oidc
locator: real-world/openapi/estate-hardening/security-api.yaml
facets:
openapi_version: 3.2.0
document_version: 1.0.0
source_file: security-api.yaml
- section: security
entity:
id: security.openapi.estate-security-api.contract.openapi.estate-security-api.1.oidc
applies_to: contract.openapi.estate-security-api
authentication: fiam.security.authentication.openid-connect
facets:
openapi_security_scheme: oidc
openapi_security_type: openIdConnect
requirement_alternative: 1
requirement_operator: and-within-alternative
required_scopes:
- items.read
openapi_openIdConnectUrl: https://id.example.test/.well-known/openid-configuration
credential_artifacts:
- fiam.credential.id-token
- fiam.credential.access-token
- section: security
entity:
id: security.openapi.estate-security-api.operation.openapi.estate-security-api.createItem.1.apiKey
applies_to: operation.openapi.estate-security-api.createItem
authentication: fiam.security.authentication.api-key
facets:
openapi_security_scheme: apiKey
openapi_security_type: apiKey
requirement_alternative: 1
requirement_operator: and-within-alternative
required_scopes: []
openapi_name: X-API-Key
openapi_in: header
credential_artifacts:
- fiam.credential.api-key
- section: security
entity:
id: security.openapi.estate-security-api.operation.openapi.estate-security-api.optionalInfo.2.oidc
applies_to: operation.openapi.estate-security-api.optionalInfo
authentication: fiam.security.authentication.openid-connect
facets:
openapi_security_scheme: oidc
openapi_security_type: openIdConnect
requirement_alternative: 2
requirement_operator: and-within-alternative
required_scopes: []
openapi_openIdConnectUrl: https://id.example.test/.well-known/openid-configuration
credential_artifacts:
- fiam.credential.id-token
- fiam.credential.access-token
assertions:
- id: assertion.openapi.0001
assertion_kind: property
subject: contract.openapi.estate-security-api
predicate: fiam.property.security-override
polarity: asserted
value: declared
evidence:
mode: fiam.evidence.declared
source:
type: openapi-document
ref: artifact.openapi.estate-security-api
locator: '#/security'
metadata:
source_url: real-world/openapi/estate-hardening/security-api.yaml
observer: openapi-ingest/v0.2-draft.4
confidence: 1.0
stance: supports
- id: assertion.openapi.0002
assertion_kind: property
subject: security.openapi.estate-security-api.contract.openapi.estate-security-api.1.oidc
predicate: fiam.property.security-override
polarity: asserted
value: required
evidence:
mode: fiam.evidence.declared
source:
type: openapi-document
ref: artifact.openapi.estate-security-api
locator: '#/security/0/oidc'
metadata:
source_url: real-world/openapi/estate-hardening/security-api.yaml
observer: openapi-ingest/v0.2-draft.4
confidence: 1.0
stance: supports
facets:
applies_to: contract.openapi.estate-security-api
- id: assertion.openapi.0003
assertion_kind: property
subject: binding.openapi.estate-security-api.1
predicate: fiam.property.communication-protocol
polarity: asserted
value: fiam.protocol.http
evidence:
mode: fiam.evidence.declared
source:
type: openapi-document
ref: artifact.openapi.estate-security-api
locator: '#/servers/0'
metadata:
source_url: real-world/openapi/estate-hardening/security-api.yaml
observer: openapi-ingest/v0.2-draft.4
confidence: 1.0
stance: supports
- id: assertion.openapi.0004
assertion_kind: property
subject: endpoint.openapi.estate-security-api.1
predicate: fiam.property.server-address
polarity: asserted
value: security.example.test
evidence:
mode: fiam.evidence.declared
source:
type: openapi-document
ref: artifact.openapi.estate-security-api
locator: '#/servers/0/url'
metadata:
source_url: real-world/openapi/estate-hardening/security-api.yaml
observer: openapi-ingest/v0.2-draft.4
confidence: 1.0
stance: supports
- id: assertion.openapi.0005
assertion_kind: property
subject: operation.openapi.estate-security-api.listItems
predicate: fiam.property.http-method
polarity: asserted
value: GET
evidence:
mode: fiam.evidence.declared
source:
type: openapi-document
ref: artifact.openapi.estate-security-api
locator: '#/paths/~1items/get'
metadata:
source_url: real-world/openapi/estate-hardening/security-api.yaml
observer: openapi-ingest/v0.2-draft.4
confidence: 1.0
stance: supports
- id: assertion.openapi.0006
assertion_kind: property
subject: operation.openapi.estate-security-api.listItems
predicate: fiam.property.http-route
polarity: asserted
value: /items
evidence:
mode: fiam.evidence.declared
source:
type: openapi-document
ref: artifact.openapi.estate-security-api
locator: '#/paths/~1items/get'
metadata:
source_url: real-world/openapi/estate-hardening/security-api.yaml
observer: openapi-ingest/v0.2-draft.4
confidence: 1.0
stance: supports
- id: assertion.openapi.0007
assertion_kind: relation
subject: operation.openapi.estate-security-api.listItems
predicate: fiam.relation.targets
polarity: asserted
object_ref: resource.openapi.estate-security-api.items
evidence:
mode: fiam.evidence.declared
source:
type: openapi-document
ref: artifact.openapi.estate-security-api
locator: '#/paths/~1items/get'
metadata:
source_url: real-world/openapi/estate-hardening/security-api.yaml
observer: openapi-ingest/v0.2-draft.4
confidence: 1.0
stance: supports
- id: assertion.openapi.0008
assertion_kind: relation
subject: shape.openapi.estate-security-api.inline.listItems-response.7b4df76d
predicate: fiam.relation.element-shape
polarity: asserted
object_ref: shape.openapi.estate-security-api.Item
evidence:
mode: fiam.evidence.declared
source:
type: openapi-document
ref: artifact.openapi.estate-security-api
locator: '#/paths/~1items/get/responses/200/content/application~1json/schema/items'
metadata:
source_url: real-world/openapi/estate-hardening/security-api.yaml
observer: openapi-ingest/v0.2-draft.4
confidence: 1.0
stance: supports
facets:
slot: items
role: fiam.shape-role.element
- id: assertion.openapi.0009
assertion_kind: relation
subject: operation.openapi.estate-security-api.listItems
predicate: fiam.relation.produces-shape
polarity: asserted
object_ref: shape.openapi.estate-security-api.inline.listItems-response.7b4df76d
evidence:
mode: fiam.evidence.declared
source:
type: openapi-document
ref: artifact.openapi.estate-security-api
locator: '#/paths/~1items/get/responses/200/content/application~1json/schema'
metadata:
source_url: real-world/openapi/estate-hardening/security-api.yaml
observer: openapi-ingest/v0.2-draft.4
confidence: 1.0
stance: supports
facets:
role: fiam.shape-role.response
- id: assertion.openapi.0010
assertion_kind: relation
subject: binding.openapi.estate-security-api.1
predicate: fiam.relation.produces-shape
polarity: asserted
object_ref: shape.openapi.estate-security-api.inline.listItems-response.7b4df76d
evidence:
mode: fiam.evidence.declared
source:
type: openapi-document
ref: artifact.openapi.estate-security-api
locator: '#/paths/~1items/get/responses/200/content/application~1json/schema'
metadata:
source_url: real-world/openapi/estate-hardening/security-api.yaml
observer: openapi-ingest/v0.2-draft.4
confidence: 1.0
stance: supports
facets:
operation_ref: operation.openapi.estate-security-api.listItems
role: fiam.shape-role.response
representation: fiam.representation.json
- id: assertion.openapi.0011
assertion_kind: property
subject: operation.openapi.estate-security-api.createItem
predicate: fiam.property.security-override
polarity: asserted
value: operation
evidence:
mode: fiam.evidence.declared
source:
type: openapi-document
ref: artifact.openapi.estate-security-api
locator: '#/paths/~1items/post/security'
metadata:
source_url: real-world/openapi/estate-hardening/security-api.yaml
observer: openapi-ingest/v0.2-draft.4
confidence: 1.0
stance: supports
- id: assertion.openapi.0012
assertion_kind: property
subject: security.openapi.estate-security-api.operation.openapi.estate-security-api.createItem.1.apiKey
predicate: fiam.property.security-override
polarity: asserted
value: required
evidence:
mode: fiam.evidence.declared
source:
type: openapi-document
ref: artifact.openapi.estate-security-api
locator: '#/paths/~1items/post/security/0/apiKey'
metadata:
source_url: real-world/openapi/estate-hardening/security-api.yaml
observer: openapi-ingest/v0.2-draft.4
confidence: 1.0
stance: supports
facets:
applies_to: operation.openapi.estate-security-api.createItem
- id: assertion.openapi.0013
assertion_kind: property
subject: operation.openapi.estate-security-api.createItem
predicate: fiam.property.http-method
polarity: asserted
value: POST
evidence:
mode: fiam.evidence.declared
source:
type: openapi-document
ref: artifact.openapi.estate-security-api
locator: '#/paths/~1items/post'
metadata:
source_url: real-world/openapi/estate-hardening/security-api.yaml
observer: openapi-ingest/v0.2-draft.4
confidence: 1.0
stance: supports
- id: assertion.openapi.0014
assertion_kind: property
subject: operation.openapi.estate-security-api.createItem
predicate: fiam.property.http-route
polarity: asserted
value: /items
evidence:
mode: fiam.evidence.declared
source:
type: openapi-document
ref: artifact.openapi.estate-security-api
locator: '#/paths/~1items/post'
metadata:
source_url: real-world/openapi/estate-hardening/security-api.yaml
observer: openapi-ingest/v0.2-draft.4
confidence: 1.0
stance: supports
- id: assertion.openapi.0015
assertion_kind: relation
subject: operation.openapi.estate-security-api.createItem
predicate: fiam.relation.targets
polarity: asserted
object_ref: resource.openapi.estate-security-api.items
evidence:
mode: fiam.evidence.declared
source:
type: openapi-document
ref: artifact.openapi.estate-security-api
locator: '#/paths/~1items/post'
metadata:
source_url: real-world/openapi/estate-hardening/security-api.yaml
observer: openapi-ingest/v0.2-draft.4
confidence: 1.0
stance: supports
- id: assertion.openapi.0016
assertion_kind: relation
subject: operation.openapi.estate-security-api.createItem
predicate: fiam.relation.accepts-shape
polarity: asserted
object_ref: shape.openapi.estate-security-api.Item
evidence:
mode: fiam.evidence.declared
source:
type: openapi-document
ref: artifact.openapi.estate-security-api
locator: '#/paths/~1items/post/requestBody/content/application~1json/schema'
metadata:
source_url: real-world/openapi/estate-hardening/security-api.yaml
observer: openapi-ingest/v0.2-draft.4
confidence: 1.0
stance: supports
facets:
role: fiam.shape-role.request
- id: assertion.openapi.0017
assertion_kind: relation
subject: binding.openapi.estate-security-api.1
predicate: fiam.relation.accepts-shape
polarity: asserted
object_ref: shape.openapi.estate-security-api.Item
evidence:
mode: fiam.evidence.declared
source:
type: openapi-document
ref: artifact.openapi.estate-security-api
locator: '#/paths/~1items/post/requestBody/content/application~1json/schema'
metadata:
source_url: real-world/openapi/estate-hardening/security-api.yaml
observer: openapi-ingest/v0.2-draft.4
confidence: 1.0
stance: supports
facets:
operation_ref: operation.openapi.estate-security-api.createItem
role: fiam.shape-role.request
representation: fiam.representation.json
- id: assertion.openapi.0018
assertion_kind: property
subject: operation.openapi.estate-security-api.optionalInfo
predicate: fiam.property.security-override
polarity: asserted
value: anonymous-alternative
evidence:
mode: fiam.evidence.declared
source:
type: openapi-document
ref: artifact.openapi.estate-security-api
locator: '#/paths/~1optional/get/security'
metadata:
source_url: real-world/openapi/estate-hardening/security-api.yaml
observer: openapi-ingest/v0.2-draft.4
confidence: 1.0
stance: supports
- id: assertion.openapi.0019
assertion_kind: property
subject: security.openapi.estate-security-api.operation.openapi.estate-security-api.optionalInfo.2.oidc
predicate: fiam.property.security-override
polarity: asserted
value: required
evidence:
mode: fiam.evidence.declared
source:
type: openapi-document
ref: artifact.openapi.estate-security-api
locator: '#/paths/~1optional/get/security/1/oidc'
metadata:
source_url: real-world/openapi/estate-hardening/security-api.yaml
observer: openapi-ingest/v0.2-draft.4
confidence: 1.0
stance: supports
facets:
applies_to: operation.openapi.estate-security-api.optionalInfo
- id: assertion.openapi.0020
assertion_kind: property
subject: operation.openapi.estate-security-api.optionalInfo
predicate: fiam.property.http-method
polarity: asserted
value: GET
evidence:
mode: fiam.evidence.declared
source:
type: openapi-document
ref: artifact.openapi.estate-security-api
locator: '#/paths/~1optional/get'
metadata:
source_url: real-world/openapi/estate-hardening/security-api.yaml
observer: openapi-ingest/v0.2-draft.4
confidence: 1.0
stance: supports
- id: assertion.openapi.0021
assertion_kind: property
subject: operation.openapi.estate-security-api.optionalInfo
predicate: fiam.property.http-route
polarity: asserted
value: /optional
evidence:
mode: fiam.evidence.declared
source:
type: openapi-document
ref: artifact.openapi.estate-security-api
locator: '#/paths/~1optional/get'
metadata:
source_url: real-world/openapi/estate-hardening/security-api.yaml
observer: openapi-ingest/v0.2-draft.4
confidence: 1.0
stance: supports
- id: assertion.openapi.0022
assertion_kind: relation
subject: operation.openapi.estate-security-api.optionalInfo
predicate: fiam.relation.targets
polarity: asserted
object_ref: resource.openapi.estate-security-api.optional
evidence:
mode: fiam.evidence.declared
source:
type: openapi-document
ref: artifact.openapi.estate-security-api
locator: '#/paths/~1optional/get'
metadata:
source_url: real-world/openapi/estate-hardening/security-api.yaml
observer: openapi-ingest/v0.2-draft.4
confidence: 1.0
stance: supports
- id: assertion.openapi.0023
assertion_kind: property
subject: operation.openapi.estate-security-api.publicInfo
predicate: fiam.property.security-override
polarity: asserted
value: none
evidence:
mode: fiam.evidence.declared
source:
type: openapi-document
ref: artifact.openapi.estate-security-api
locator: '#/paths/~1public/get/security'
metadata:
source_url: real-world/openapi/estate-hardening/security-api.yaml
observer: openapi-ingest/v0.2-draft.4
confidence: 1.0
stance: supports
- id: assertion.openapi.0024
assertion_kind: property
subject: operation.openapi.estate-security-api.publicInfo
predicate: fiam.property.http-method
polarity: asserted
value: GET
evidence:
mode: fiam.evidence.declared
source:
type: openapi-document
ref: artifact.openapi.estate-security-api
locator: '#/paths/~1public/get'
metadata:
source_url: real-world/openapi/estate-hardening/security-api.yaml
observer: openapi-ingest/v0.2-draft.4
confidence: 1.0
stance: supports
- id: assertion.openapi.0025
assertion_kind: property
subject: operation.openapi.estate-security-api.publicInfo
predicate: fiam.property.http-route
polarity: asserted
value: /public
evidence:
mode: fiam.evidence.declared
source:
type: openapi-document
ref: artifact.openapi.estate-security-api
locator: '#/paths/~1public/get'
metadata:
source_url: real-world/openapi/estate-hardening/security-api.yaml
observer: openapi-ingest/v0.2-draft.4
confidence: 1.0
stance: supports
- id: assertion.openapi.0026
assertion_kind: relation
subject: operation.openapi.estate-security-api.publicInfo
predicate: fiam.relation.targets
polarity: asserted
object_ref: resource.openapi.estate-security-api.public
evidence:
mode: fiam.evidence.declared
source:
type: openapi-document
ref: artifact.openapi.estate-security-api
locator: '#/paths/~1public/get'
metadata:
source_url: real-world/openapi/estate-hardening/security-api.yaml
observer: openapi-ingest/v0.2-draft.4
confidence: 1.0
stance: supports
zone_memberships: []
runtime_aggregates: []
topology_observations: []
unresolved: []
reconciliation_candidates: []
declared_entity_ids:
- operation.openapi.estate-security-api.createItem
- operation.openapi.estate-security-api.listItems
- operation.openapi.estate-security-api.optionalInfo
- operation.openapi.estate-security-api.publicInfo

42
history/FIAM_v0.2_Draft6/real-world/catalog-exchange/security-old-coverage.yaml Normal file
View file

@ -0,0 +1,42 @@
catalog_exchange_version: '0.2'
profile_id: fiam.catalog-exchange.v0.2
exchange_id: exchange.security.old-coverage
created_at: '2026-09-09T00:00:00Z'
source:
source_id: collector.security.history
source_kind: runtime-aggregate
source_ref: fixture://security-history
content_hash: null
observation:
mode: incremental
observation_scope: security-prod-history
population_id: security-prod
population:
environment: prod
domains:
- http
snapshot_time: '2026-09-09T00:00:00Z'
aggregate_semantics: cumulative
records:
entities: []
assertions: []
zone_memberships: []
runtime_aggregates:
- id: aggregate.createItem.old
domain: http
role: server
operation: operation.openapi.estate-security-api.createItem
binding: null
local_node: node.openapi.estate-security-api
remote_node: null
channel: null
resource: null
count: 100
error_count: 0
first_seen: '2026-01-01T00:00:00Z'
last_seen: '2026-05-01T00:00:00Z'
sample_spans: []
topology_observations: []
unresolved: []
reconciliation_candidates: []
declared_entity_ids: []

1414
history/FIAM_v0.2_Draft6/real-world/catalog-exchange/security-runtime.yaml Normal file
View file

File diff suppressed because it is too large Load diff

16
history/FIAM_v0.2_Draft6/real-world/catalog-exchange/zone-derivation-input.yaml Normal file
View file

@ -0,0 +1,16 @@
fiam_version: '0.2'
instance:
id: fixture.zone-derivation
kind: runtime-model
nodes:
- id: node.zone-derived
kind: system-node
name: zone-derived
node_type: fiam.node-type.service
facets:
identity_tuple:
kind: service-deployment
service_name: zone-derived
environment: prod
cluster_name: cluster-a
k8s_namespace: payments

52
history/FIAM_v0.2_Draft6/real-world/catalog-exchange/zone-derivation.yaml Normal file
View file

@ -0,0 +1,52 @@
catalog_exchange_version: '0.2'
profile_id: fiam.catalog-exchange.v0.2
exchange_id: exchange.2ad173cc7bb31561462f1fc6
created_at: '2026-09-09T00:00:00Z'
source:
source_id: fixture.zone
source_kind: fiam-model
source_ref: real-world/catalog-exchange/zone-derivation-input.yaml
content_hash: 77eca2bbd97770a25cc51258270fffc6c60bda2ddd4a255b497a20a061aebaca
observation:
mode: incremental
snapshot_time: '2026-09-09T00:00:00Z'
observation_scope: zone-fixture
population_id: zone-pop
population: {}
domains:
- http
aggregate_semantics: cumulative
records:
entities:
- section: nodes
entity:
id: node.zone-derived
kind: system-node
name: zone-derived
node_type: fiam.node-type.service
facets:
identity_tuple:
kind: service-deployment
service_name: zone-derived
environment: prod
cluster_name: cluster-a
k8s_namespace: payments
assertions: []
zone_memberships:
- zone_id: zone.derived.cluster.e2b03c9fd730
member_id: node.zone-derived
zone_type: fiam.zone-type.cluster
derived: true
- zone_id: zone.derived.environment.efc534777568
member_id: node.zone-derived
zone_type: fiam.zone-type.deployment-environment
derived: true
- zone_id: zone.derived.k8s-namespace.3ee07e089e28
member_id: node.zone-derived
zone_type: fiam.zone-type.kubernetes-namespace
derived: true
runtime_aggregates: []
topology_observations: []
unresolved: []
reconciliation_candidates: []
declared_entity_ids: []

32
history/FIAM_v0.2_Draft6/real-world/catalog-operations/RESULT-SUMMARY.json Normal file
View file

@ -0,0 +1,32 @@
{
"architecture-changes.yaml": {
"appeared": 1,
"disappeared": 1,
"newly_undeclared": 1
},
"architecture-policy.yaml": {
"material_dependencies": 1,
"new_dependencies": 1,
"policy_violations": 1
},
"boundary-drift.yaml": {
"new_cross_zone": 1,
"new_organization_boundary": 1,
"new_trust_boundary": 1
},
"evidence-health.yaml": {
"challenged": 1,
"conflicts": 1,
"low_support": 1,
"stale_runtime_only": 1
},
"operation-coverage.yaml": {
"dormant": 1,
"never-observed": 2,
"observed-in-window": 1
},
"security-evidence-coverage.yaml": {
"declared_profile_operation_pairs": 6,
"observed_operations_with_security_unknown": 1
}
}

65
history/FIAM_v0.2_Draft6/real-world/catalog-operations/architecture-changes.yaml Normal file
View file

@ -0,0 +1,65 @@
lens_id: fiam.lens.architecture-changes
window:
since: '2026-09-07T00:00:00Z'
until: '2026-09-09T23:59:59Z'
population_id: prod-cluster-a
summary:
appeared: 1
disappeared: 1
newly_undeclared: 1
appeared:
- edge_key: edge.210c03e257e70068c68df0c0
domain: rpc
kind: direct-call
from: node.orders
target: node.partner
target_kind: node
channel: null
first_seen: '2026-09-08T00:00:00Z'
last_seen: '2026-09-08T00:00:00Z'
valid_from: '2026-09-08T00:00:00Z'
closed_at: null
observation_count: 12
declared: false
declaration_matches: &id001 []
declaration_reason: no-matching-declaration
close_reason: null
disappeared:
- edge_key: edge.be323ef1b2f1274e52be419c
domain: rpc
kind: direct-call
from: node.orders
target: node.inventory
target_kind: node
channel: null
first_seen: '2026-08-25T00:00:00Z'
last_seen: '2026-09-01T00:00:00Z'
valid_from: '2026-08-25T00:00:00Z'
closed_at: '2026-09-09T00:00:00Z'
observation_count: 100
declared: true
declaration_matches:
- declaration_id: assertion.declared.orders-uses-inventory
predicate: fiam.relation.uses
matched_via: target
matched_ref: node.inventory
source_id: architecture.git
declaration_reason: matched
close_reason: all-observation-scopes-closed
newly_undeclared:
- edge_key: edge.210c03e257e70068c68df0c0
domain: rpc
kind: direct-call
from: node.orders
target: node.partner
target_kind: node
channel: null
first_seen: '2026-09-08T00:00:00Z'
last_seen: '2026-09-08T00:00:00Z'
valid_from: '2026-09-08T00:00:00Z'
closed_at: null
observation_count: 12
declared: false
declaration_matches: *id001
declaration_reason: no-matching-declaration
close_reason: null

56
history/FIAM_v0.2_Draft6/real-world/catalog-operations/architecture-policy.yaml Normal file
View file

@ -0,0 +1,56 @@
lens_id: fiam.lens.architecture-policy
policy:
id: fiam.policy.architecture-governance.v0.2
sha256: f9fac195fba210643a84f15771632b146ead9f877b45b7e96d39e18a31e4fbdd
window:
since: '2026-09-07T00:00:00Z'
until: '2026-09-09T23:59:59Z'
population_id: prod-cluster-a
summary:
new_dependencies: 1
material_dependencies: 1
policy_violations: 1
dependencies:
- &id001
edge_key: edge.210c03e257e70068c68df0c0
from: node.orders
target: node.partner
domain: rpc
first_seen: '2026-09-08T00:00:00Z'
declared: false
observation_count: 12
corroborating_scopes:
- prod-cluster-a-app-traces
materiality_score: 0.75
materiality: high
components:
undeclared: true
trust_boundary: true
organization_boundary: true
high_volume: false
strong_evidence: false
zone_context:
from:
fiam.zone-type.deployment-environment:
- zone.environment.prod
fiam.zone-type.organization:
- zone.org.internal
fiam.zone-type.trust-zone:
- zone.trust.internal
target:
fiam.zone-type.deployment-environment:
- zone.environment.prod
fiam.zone-type.organization:
- zone.org.partner
fiam.zone-type.trust-zone:
- zone.trust.partner
material_dependencies:
- *id001
policy_violations:
- edge_key: edge.210c03e257e70068c68df0c0
rule_id: require-declaration-internal-to-partner
severity: high
condition: require-declared
from_zone: zone.trust.internal
to_zone: zone.trust.partner
declared: false

28
history/FIAM_v0.2_Draft6/real-world/catalog-operations/boundary-drift.yaml Normal file
View file

@ -0,0 +1,28 @@
lens_id: fiam.lens.boundary-drift
window:
since: '2026-09-07T00:00:00Z'
until: '2026-09-09T23:59:59Z'
population_id: prod-cluster-a
summary:
new_cross_zone: 1
new_trust_boundary: 1
new_organization_boundary: 1
crossings:
- edge_key: edge.210c03e257e70068c68df0c0
kind: direct-call
from: node.orders
target: node.partner
first_seen: '2026-09-08T00:00:00Z'
zone_crossings:
- zone_type: fiam.zone-type.trust-zone
from_zones:
- zone.trust.internal
target_zones:
- zone.trust.partner
- zone_type: fiam.zone-type.organization
from_zones:
- zone.org.internal
target_zones:
- zone.org.partner
trust_boundary: true
organization_boundary: true

186
history/FIAM_v0.2_Draft6/real-world/catalog-operations/catalog-export-app-traces.yaml Normal file
View file

@ -0,0 +1,186 @@
catalog_exchange_version: '0.2'
profile_id: fiam.catalog-exchange.v0.2
exchange_id: exchange.index-export.be86ca76e8a06411b98de3b5
created_at: '2026-09-09T00:00:00Z'
source:
source_id: fiam.index-export
source_kind: index-checkpoint
source_ref: /tmp/tmp.uHHDdXSsJj/estate.sqlite
content_hash: null
observation:
mode: incremental
observation_scope: prod-cluster-a-app-traces
population_id: prod-cluster-a
population: {}
domains:
- rpc
snapshot_time: '2026-09-09T00:00:00Z'
aggregate_semantics: cumulative
records:
entities:
- section: indexed
entity:
contract: contract.inventory
id: binding.inventory
kind: binding
operations:
- operation.inventory.get
provider_port: port.inventory.api
- section: indexed
entity:
id: contract.inventory
kind: interface-contract
name: Inventory API
operations:
- id: operation.inventory.get
interaction_style: fiam.interaction-style.request-response
kind: operation
name: getInventory
purpose:
- fiam.purpose.query
- section: indexed
entity:
id: node.inventory
kind: system-node
name: Inventory
node_type: fiam.node-type.service
- section: indexed
entity:
id: node.orders
kind: system-node
name: Orders
node_type: fiam.node-type.service
- section: indexed
entity:
id: node.partner
kind: system-node
name: Partner API
node_type: fiam.node-type.application
- section: indexed
entity:
id: operation.inventory.get
interaction_style: fiam.interaction-style.request-response
kind: operation
name: getInventory
- section: indexed
entity:
id: port.inventory.api
kind: port
owner: node.inventory
participations:
- contract: contract.inventory
mode: offers
roles:
- fiam.role.server
- section: indexed
entity:
id: zone.environment.prod
kind: zone
members:
- node.orders
- node.inventory
- node.partner
name: production
zone_type: fiam.zone-type.deployment-environment
- section: indexed
entity:
id: zone.org.internal
kind: zone
members:
- node.orders
- node.inventory
name: internal organization
zone_type: fiam.zone-type.organization
- section: indexed
entity:
id: zone.org.partner
kind: zone
members:
- node.partner
name: partner organization
zone_type: fiam.zone-type.organization
- section: indexed
entity:
id: zone.trust.internal
kind: zone
members:
- node.orders
- node.inventory
name: internal trust domain
zone_type: fiam.zone-type.trust-zone
- section: indexed
entity:
id: zone.trust.partner
kind: zone
members:
- node.partner
name: partner trust domain
zone_type: fiam.zone-type.trust-zone
assertions:
- assertion_kind: relation
evidence:
confidence: 1.0
mode: fiam.evidence.declared
observed_at: '2026-09-01T00:00:00Z'
observer: fixture.owner
source:
locator: dependency/orders-inventory
ref: fixture://estate-history/declared
type: architecture-declaration
stance: supports
id: assertion.declared.orders-uses-inventory
object_ref: binding.inventory
polarity: asserted
predicate: fiam.relation.uses
subject: node.orders
zone_memberships:
- zone_id: zone.environment.prod
member_id: node.inventory
zone_type: fiam.zone-type.deployment-environment
derived: false
- zone_id: zone.environment.prod
member_id: node.orders
zone_type: fiam.zone-type.deployment-environment
derived: false
- zone_id: zone.environment.prod
member_id: node.partner
zone_type: fiam.zone-type.deployment-environment
derived: false
- zone_id: zone.org.internal
member_id: node.inventory
zone_type: fiam.zone-type.organization
derived: false
- zone_id: zone.org.internal
member_id: node.orders
zone_type: fiam.zone-type.organization
derived: false
- zone_id: zone.org.partner
member_id: node.partner
zone_type: fiam.zone-type.organization
derived: false
- zone_id: zone.trust.internal
member_id: node.inventory
zone_type: fiam.zone-type.trust-zone
derived: false
- zone_id: zone.trust.internal
member_id: node.orders
zone_type: fiam.zone-type.trust-zone
derived: false
- zone_id: zone.trust.partner
member_id: node.partner
zone_type: fiam.zone-type.trust-zone
derived: false
runtime_aggregates: []
topology_observations:
- correlation: fixture
count: 12
domain: rpc
first_seen: '2026-09-08T00:00:00Z'
from: node.orders
id: topology.orders-partner
kind: direct-call
last_seen: '2026-09-08T00:00:00Z'
to: node.partner
unresolved: []
reconciliation_candidates: []
declared_entity_ids: []

38
history/FIAM_v0.2_Draft6/real-world/catalog-operations/evidence-health.yaml Normal file
View file

@ -0,0 +1,38 @@
lens_id: fiam.lens.evidence-health
evaluated_at: '2026-09-09T00:00:00Z'
policy:
id: fiam.policy.evidence-scoring.default
sha256: 595a0afe8aabe3a65358a672031ff60a58c575322662a4c0b8608e1717e454cc
summary:
conflicts: 1
challenged: 1
stale_runtime_only: 1
low_support: 1
conflicts:
- subject: node.evidence.api
predicate: fiam.property.network-protocol-version
alternatives:
- value: '"1.1"'
assertion_id: assertion.protocol.http11
support_score: 0.95
- value: '"2"'
assertion_id: assertion.protocol.http2
support_score: 0.40798
challenged:
- assertion_id: assertion.service-name
subject: node.evidence.api
predicate: fiam.property.service-name
support_score: 0.95
challenge_score: 0.688543
net_support: 0.261457
stale_runtime_only:
- assertion_id: assertion.stale-peer
subject: node.evidence.api
predicate: fiam.property.service-peer-name
latest_runtime_evidence: '2026-06-01T00:00:00Z'
support_score: 0.214344
low_support:
- assertion_id: assertion.stale-peer
subject: node.evidence.api
predicate: fiam.property.service-peer-name
support_score: 0.214344

29
history/FIAM_v0.2_Draft6/real-world/catalog-operations/operation-coverage.yaml Normal file
View file

@ -0,0 +1,29 @@
lens_id: fiam.lens.operation-coverage
population_id: security-prod
window:
since: '2026-06-11T23:59:59Z'
until: '2026-09-09T23:59:59Z'
days: 90
summary:
dormant: 1
never-observed: 2
observed-in-window: 1
operations:
- operation_ref: operation.openapi.estate-security-api.createItem
name: createItem
classification: dormant
last_seen: '2026-05-01T00:00:00Z'
count: 100
error_count: 0
- operation_ref: operation.openapi.estate-security-api.listItems
name: listItems
classification: observed-in-window
last_seen: '2026-09-09T01:00:00Z'
count: 1
error_count: 0
- operation_ref: operation.openapi.estate-security-api.optionalInfo
name: optionalInfo
classification: never-observed
- operation_ref: operation.openapi.estate-security-api.publicInfo
name: publicInfo
classification: never-observed

52
history/FIAM_v0.2_Draft6/real-world/catalog-operations/security-evidence-coverage.yaml Normal file
View file

@ -0,0 +1,52 @@
lens_id: fiam.lens.security-evidence-coverage
population_id: security-prod
window:
since: '2026-06-11T00:00:00Z'
until: '2026-09-09T23:59:59Z'
summary:
declared_profile_operation_pairs: 6
observed_operations_with_security_unknown: 1
profiles:
- profile_ref: security.openapi.estate-security-api.contract.openapi.estate-security-api.1.oidc
declared_at: contract.openapi.estate-security-api
operation_ref: operation.openapi.estate-security-api.createItem
authentication: fiam.security.authentication.openid-connect
operation_observed_in_window: false
runtime_security_evidence: unknown
interpretation: declared-security-operation-not-observed
- profile_ref: security.openapi.estate-security-api.contract.openapi.estate-security-api.1.oidc
declared_at: contract.openapi.estate-security-api
operation_ref: operation.openapi.estate-security-api.listItems
authentication: fiam.security.authentication.openid-connect
operation_observed_in_window: true
runtime_security_evidence: unknown
interpretation: declared-security-runtime-evidence-unknown
- profile_ref: security.openapi.estate-security-api.contract.openapi.estate-security-api.1.oidc
declared_at: contract.openapi.estate-security-api
operation_ref: operation.openapi.estate-security-api.optionalInfo
authentication: fiam.security.authentication.openid-connect
operation_observed_in_window: false
runtime_security_evidence: unknown
interpretation: declared-security-operation-not-observed
- profile_ref: security.openapi.estate-security-api.contract.openapi.estate-security-api.1.oidc
declared_at: contract.openapi.estate-security-api
operation_ref: operation.openapi.estate-security-api.publicInfo
authentication: fiam.security.authentication.openid-connect
operation_observed_in_window: false
runtime_security_evidence: unknown
interpretation: declared-security-operation-not-observed
- profile_ref: security.openapi.estate-security-api.operation.openapi.estate-security-api.createItem.1.apiKey
declared_at: operation.openapi.estate-security-api.createItem
operation_ref: operation.openapi.estate-security-api.createItem
authentication: fiam.security.authentication.api-key
operation_observed_in_window: false
runtime_security_evidence: unknown
interpretation: declared-security-operation-not-observed
- profile_ref: security.openapi.estate-security-api.operation.openapi.estate-security-api.optionalInfo.2.oidc
declared_at: operation.openapi.estate-security-api.optionalInfo
operation_ref: operation.openapi.estate-security-api.optionalInfo
authentication: fiam.security.authentication.openid-connect
operation_observed_in_window: false
runtime_security_evidence: unknown
interpretation: declared-security-operation-not-observed
note: Generic OTLP does not prove authentication presence or absence. Unknown is preserved.

597
history/FIAM_v0.2_Draft6/real-world/composite/ambiguous-http.fiam.yaml Normal file
View file

@ -0,0 +1,597 @@
fiam_version: '0.2'
instance:
id: model.declared.ambiguous-http.catalog
kind: model
title: Ambiguous HTTP declaration fixture — runtime catalog
status: provisional
intent: Incremental FIAM catalog combining declared architecture with aggregated runtime observations.
nodes:
- id: node.otel.service.gateway-observed.4ea22f0238ef
kind: system-node
name: gateway-observed
node_type: fiam.node-type.service
facets:
identity_tuple:
kind: service-deployment
service_namespace: ''
service_name: gateway-observed
environment: production
- id: node.service.alpha
kind: system-node
name: alpha
node_type: fiam.node-type.service
- id: node.service.beta
kind: system-node
name: beta
node_type: fiam.node-type.service
ports:
- id: port.alpha.http
kind: port
owner: node.service.alpha
participations:
- contract: contract.alpha.http
mode: offers
- id: port.beta.http
kind: port
owner: node.service.beta
participations:
- contract: contract.beta.http
mode: offers
- id: port.otel.http.gateway-observed.d93c4771fe17
kind: port
owner: node.otel.service.gateway-observed.4ea22f0238ef
participations:
- contract: contract.otel.http.gateway-observed.5205bb5e84c0
mode: offers
roles:
- fiam.role.server
contracts:
- id: contract.alpha.http
kind: interface-contract
name: Alpha HTTP
operations:
- id: operation.alpha.get-pet
kind: operation
name: get pet alpha
interaction_style: fiam.interaction-style.request-response
- id: contract.beta.http
kind: interface-contract
name: Beta HTTP
operations:
- id: operation.beta.get-pet
kind: operation
name: get pet beta
interaction_style: fiam.interaction-style.request-response
- id: contract.otel.http.gateway-observed.5205bb5e84c0
kind: interface-contract
name: Observed HTTP surface — gateway-observed
operations:
- id: operation.otel.http.GET--pets-id.dc9e2765dcf6
kind: operation
name: GET /pets/{id}
interaction_style: fiam.interaction-style.request-response
x-http-method: GET
x-http-route: /pets/{id}
endpoints:
- id: endpoint.alpha
kind: endpoint
address: https://alpha.example
address_scheme: fiam.address-scheme.https-url
- id: endpoint.beta
kind: endpoint
address: https://beta.example
address_scheme: fiam.address-scheme.https-url
- id: endpoint.otel.http.unlocated.80928725ff75
kind: endpoint
name: unlocated
address_scheme: fiam.address-scheme.http-url
facets:
identity_tuple:
address: null
address_scheme: fiam.address-scheme.http-url
zone:
- production
- ''
- ''
- ''
- ''
logical_server_address: ''
bindings:
- id: binding.alpha
kind: binding
contract: contract.alpha.http
provider_port: port.alpha.http
operations:
- operation.alpha.get-pet
endpoints:
- endpoint.alpha
communication_stack:
- role: fiam.stack-role.application-transfer-protocol
term: fiam.protocol.http
- id: binding.beta
kind: binding
contract: contract.beta.http
provider_port: port.beta.http
operations:
- operation.beta.get-pet
endpoints:
- endpoint.beta
communication_stack:
- role: fiam.stack-role.application-transfer-protocol
term: fiam.protocol.http
- id: binding.otel.http.gateway-observed-unlocated.715c2ecd9a06
kind: binding
contract: contract.otel.http.gateway-observed.5205bb5e84c0
provider_port: port.otel.http.gateway-observed.d93c4771fe17
endpoints:
- endpoint.otel.http.unlocated.80928725ff75
communication_stack:
- role: fiam.stack-role.application-transfer-protocol
term: fiam.protocol.http2
operations:
- operation.otel.http.GET--pets-id.dc9e2765dcf6
facets:
identity_tuple:
kind: http-binding
service_node: node.otel.service.gateway-observed.4ea22f0238ef
server_address: ''
server_port: null
zone:
- production
- ''
- ''
- ''
- ''
artifacts:
- id: artifact.ambiguous-declaration
kind: artifact
name: ambiguous fixture
artifact_type: fiam.artifact.architecture-declaration
- id: artifact.otel.stream.ambiguous-http.otlp.4f7c9d655f57
kind: artifact
name: OTLP runtime stream
artifact_type: fiam.artifact.telemetry-trace-export
locator: real-world/otel/estate-hardening/ambiguous-http.otlp.json
facets:
format: OTLP/JSON
observer_profile: OpenTelemetry Semantic Conventions 1.44.0
latest_batch_hash: b3421c406d9a5e66b75c94da6067d48540f2fa2abb39b0daf45ba77c1466bd77
describes:
- interaction.sample.1b5b9581923bee4418356756.3333333333333333
assertions:
- id: assertion.alpha.method
assertion_kind: property
subject: operation.alpha.get-pet
predicate: fiam.property.http-method
polarity: asserted
value: GET
evidence: &id001
mode: fiam.evidence.declared
source:
type: architecture-fixture
ref: artifact.ambiguous-declaration
locator: alpha
observer: fixture
confidence: 1.0
stance: supports
- id: assertion.alpha.route
assertion_kind: property
subject: operation.alpha.get-pet
predicate: fiam.property.http-route
polarity: asserted
value: /pets/{id}
evidence: *id001
- id: assertion.beta.method
assertion_kind: property
subject: operation.beta.get-pet
predicate: fiam.property.http-method
polarity: asserted
value: GET
evidence: *id001
- id: assertion.beta.route
assertion_kind: property
subject: operation.beta.get-pet
predicate: fiam.property.http-route
polarity: asserted
value: /pets/{id}
evidence: *id001
- id: assertion.otel.369ab89aa421dec3deb4
assertion_kind: property
subject: binding.otel.http.gateway-observed-unlocated.715c2ecd9a06
predicate: fiam.property.runtime-first-seen
polarity: asserted
value: '2026-09-09T07:00:00Z'
evidence:
mode: fiam.evidence.runtime-observed
source:
type: otlp-aggregate
ref: artifact.otel.stream.ambiguous-http.otlp.4f7c9d655f57
locator: aggregate:1b5b9581923bee4418356756
metadata:
source: real-world/otel/estate-hardening/ambiguous-http.otlp.json
semconv_basis: OpenTelemetry Semantic Conventions 1.44.0
otlp_basis: OTLP 1.11.0
locator_class: aggregate:1b5b9581923bee4418356756
aggregation_key: 1b5b9581923bee4418356756
sample_spans:
- trace:88888888888888888888888888888888/span:3333333333333333
observer: otel-ingest/v0.2-draft.4
confidence: 1.0
stance: supports
observed_at: '2026-09-09T07:00:00Z'
facets: &id002
aggregation_key: 1b5b9581923bee4418356756
domain: http
role: server
operation_ref: operation.otel.http.GET--pets-id.dc9e2765dcf6
local_node_ref: node.otel.service.gateway-observed.4ea22f0238ef
valid_time:
valid_from: '2026-09-09T07:00:00Z'
valid_until: '2026-09-09T07:00:00Z'
observed_at: '2026-09-09T07:00:00Z'
- id: assertion.otel.5375802da687e3923825
assertion_kind: property
subject: binding.otel.http.gateway-observed-unlocated.715c2ecd9a06
predicate: fiam.property.runtime-observation-count
polarity: asserted
value: 1
evidence:
mode: fiam.evidence.runtime-observed
source:
type: otlp-aggregate
ref: artifact.otel.stream.ambiguous-http.otlp.4f7c9d655f57
locator: aggregate:1b5b9581923bee4418356756
metadata:
source: real-world/otel/estate-hardening/ambiguous-http.otlp.json
semconv_basis: OpenTelemetry Semantic Conventions 1.44.0
otlp_basis: OTLP 1.11.0
locator_class: aggregate:1b5b9581923bee4418356756
aggregation_key: 1b5b9581923bee4418356756
sample_spans:
- trace:88888888888888888888888888888888/span:3333333333333333
observer: otel-ingest/v0.2-draft.4
confidence: 1.0
stance: supports
observed_at: '2026-09-09T07:00:00Z'
facets: *id002
valid_time:
valid_from: '2026-09-09T07:00:00Z'
valid_until: '2026-09-09T07:00:00Z'
observed_at: '2026-09-09T07:00:00Z'
- id: assertion.otel.5fc3e5ac747bd9982dff
assertion_kind: property
subject: operation.otel.http.GET--pets-id.dc9e2765dcf6
predicate: fiam.property.http-method
polarity: asserted
value: GET
evidence:
mode: fiam.evidence.runtime-observed
source:
type: otlp-trace-stream
ref: artifact.otel.stream.ambiguous-http.otlp.4f7c9d655f57
locator: attribute:http.request.method
metadata:
source: real-world/otel/estate-hardening/ambiguous-http.otlp.json
semconv_basis: OpenTelemetry Semantic Conventions 1.44.0
otlp_basis: OTLP 1.11.0
locator_class: attribute:http.request.method
sample_spans:
- trace:88888888888888888888888888888888/span:3333333333333333
observer: otel-ingest/v0.2-draft.4
confidence: 1.0
stance: supports
observed_at: '2026-09-09T07:00:00Z'
valid_time:
valid_from: '2026-09-09T07:00:00Z'
valid_until: '2026-09-09T07:00:00Z'
observed_at: '2026-09-09T07:00:00Z'
- id: assertion.otel.a159330db85e21da23d0
assertion_kind: property
subject: binding.otel.http.gateway-observed-unlocated.715c2ecd9a06
predicate: fiam.property.runtime-error-count
polarity: asserted
value: 0
evidence:
mode: fiam.evidence.runtime-observed
source:
type: otlp-aggregate
ref: artifact.otel.stream.ambiguous-http.otlp.4f7c9d655f57
locator: aggregate:1b5b9581923bee4418356756
metadata:
source: real-world/otel/estate-hardening/ambiguous-http.otlp.json
semconv_basis: OpenTelemetry Semantic Conventions 1.44.0
otlp_basis: OTLP 1.11.0
locator_class: aggregate:1b5b9581923bee4418356756
aggregation_key: 1b5b9581923bee4418356756
sample_spans:
- trace:88888888888888888888888888888888/span:3333333333333333
observer: otel-ingest/v0.2-draft.4
confidence: 1.0
stance: supports
observed_at: '2026-09-09T07:00:00Z'
facets: *id002
valid_time:
valid_from: '2026-09-09T07:00:00Z'
valid_until: '2026-09-09T07:00:00Z'
observed_at: '2026-09-09T07:00:00Z'
- id: assertion.otel.d4a9733ad29768dec5e9
assertion_kind: property
subject: binding.otel.http.gateway-observed-unlocated.715c2ecd9a06
predicate: fiam.property.communication-protocol
polarity: asserted
value: fiam.protocol.http2
evidence:
mode: fiam.evidence.runtime-observed
source:
type: otlp-trace-stream
ref: artifact.otel.stream.ambiguous-http.otlp.4f7c9d655f57
locator: attribute:network.protocol.version
metadata:
source: real-world/otel/estate-hardening/ambiguous-http.otlp.json
semconv_basis: OpenTelemetry Semantic Conventions 1.44.0
otlp_basis: OTLP 1.11.0
locator_class: attribute:network.protocol.version
sample_spans:
- trace:88888888888888888888888888888888/span:3333333333333333
observer: otel-ingest/v0.2-draft.4
confidence: 1.0
stance: supports
observed_at: '2026-09-09T07:00:00Z'
valid_time:
valid_from: '2026-09-09T07:00:00Z'
valid_until: '2026-09-09T07:00:00Z'
observed_at: '2026-09-09T07:00:00Z'
- id: assertion.otel.d9a82b1deece9db2b946
assertion_kind: property
subject: binding.otel.http.gateway-observed-unlocated.715c2ecd9a06
predicate: fiam.property.runtime-active
polarity: asserted
value: true
evidence:
mode: fiam.evidence.runtime-observed
source:
type: otlp-aggregate
ref: artifact.otel.stream.ambiguous-http.otlp.4f7c9d655f57
locator: aggregate:1b5b9581923bee4418356756
metadata:
source: real-world/otel/estate-hardening/ambiguous-http.otlp.json
semconv_basis: OpenTelemetry Semantic Conventions 1.44.0
otlp_basis: OTLP 1.11.0
locator_class: aggregate:1b5b9581923bee4418356756
aggregation_key: 1b5b9581923bee4418356756
sample_spans:
- trace:88888888888888888888888888888888/span:3333333333333333
observer: otel-ingest/v0.2-draft.4
confidence: 1.0
stance: supports
observed_at: '2026-09-09T07:00:00Z'
facets: *id002
valid_time:
valid_from: '2026-09-09T07:00:00Z'
valid_until: '2026-09-09T07:00:00Z'
observed_at: '2026-09-09T07:00:00Z'
- id: assertion.otel.e0e1ce2d5936ca1b563e
assertion_kind: property
subject: binding.otel.http.gateway-observed-unlocated.715c2ecd9a06
predicate: fiam.property.network-protocol-version
polarity: asserted
value: '2'
evidence:
mode: fiam.evidence.runtime-observed
source:
type: otlp-trace-stream
ref: artifact.otel.stream.ambiguous-http.otlp.4f7c9d655f57
locator: attribute:network.protocol.version
metadata:
source: real-world/otel/estate-hardening/ambiguous-http.otlp.json
semconv_basis: OpenTelemetry Semantic Conventions 1.44.0
otlp_basis: OTLP 1.11.0
locator_class: attribute:network.protocol.version
sample_spans:
- trace:88888888888888888888888888888888/span:3333333333333333
observer: otel-ingest/v0.2-draft.4
confidence: 1.0
stance: supports
observed_at: '2026-09-09T07:00:00Z'
valid_time:
valid_from: '2026-09-09T07:00:00Z'
valid_until: '2026-09-09T07:00:00Z'
observed_at: '2026-09-09T07:00:00Z'
- id: assertion.otel.e257946735f3a36cb8fa
assertion_kind: property
subject: node.otel.service.gateway-observed.4ea22f0238ef
predicate: fiam.property.service-name
polarity: asserted
value: gateway-observed
evidence:
mode: fiam.evidence.runtime-observed
source:
type: otlp-trace-stream
ref: artifact.otel.stream.ambiguous-http.otlp.4f7c9d655f57
locator: attribute:service.name
metadata:
source: real-world/otel/estate-hardening/ambiguous-http.otlp.json
semconv_basis: OpenTelemetry Semantic Conventions 1.44.0
otlp_basis: OTLP 1.11.0
locator_class: attribute:service.name
sample_spans:
- trace:88888888888888888888888888888888/span:3333333333333333
observer: otel-ingest/v0.2-draft.4
confidence: 1.0
stance: supports
observed_at: '2026-09-09T07:00:00Z'
valid_time:
valid_from: '2026-09-09T07:00:00Z'
valid_until: '2026-09-09T07:00:00Z'
observed_at: '2026-09-09T07:00:00Z'
- id: assertion.otel.e8bdc688c39fcbc6ac07
assertion_kind: property
subject: binding.otel.http.gateway-observed-unlocated.715c2ecd9a06
predicate: fiam.property.runtime-last-seen
polarity: asserted
value: '2026-09-09T07:00:00Z'
evidence:
mode: fiam.evidence.runtime-observed
source:
type: otlp-aggregate
ref: artifact.otel.stream.ambiguous-http.otlp.4f7c9d655f57
locator: aggregate:1b5b9581923bee4418356756
metadata:
source: real-world/otel/estate-hardening/ambiguous-http.otlp.json
semconv_basis: OpenTelemetry Semantic Conventions 1.44.0
otlp_basis: OTLP 1.11.0
locator_class: aggregate:1b5b9581923bee4418356756
aggregation_key: 1b5b9581923bee4418356756
sample_spans:
- trace:88888888888888888888888888888888/span:3333333333333333
observer: otel-ingest/v0.2-draft.4
confidence: 1.0
stance: supports
observed_at: '2026-09-09T07:00:00Z'
facets: *id002
valid_time:
valid_from: '2026-09-09T07:00:00Z'
valid_until: '2026-09-09T07:00:00Z'
observed_at: '2026-09-09T07:00:00Z'
- id: assertion.otel.f0b832f0f0a324a5f7bb
assertion_kind: property
subject: interaction.sample.1b5b9581923bee4418356756.3333333333333333
predicate: fiam.property.http-response-status-code
polarity: asserted
value: 200
evidence:
mode: fiam.evidence.runtime-observed
source:
type: otlp-trace-stream
ref: artifact.otel.stream.ambiguous-http.otlp.4f7c9d655f57
locator: attribute:http.response.status_code
metadata:
source: real-world/otel/estate-hardening/ambiguous-http.otlp.json
semconv_basis: OpenTelemetry Semantic Conventions 1.44.0
otlp_basis: OTLP 1.11.0
locator_class: attribute:http.response.status_code
sample_spans:
- trace:88888888888888888888888888888888/span:3333333333333333
observer: otel-ingest/v0.2-draft.4
confidence: 1.0
stance: supports
observed_at: '2026-09-09T07:00:00Z'
valid_time:
valid_from: '2026-09-09T07:00:00Z'
valid_until: '2026-09-09T07:00:00Z'
observed_at: '2026-09-09T07:00:00Z'
- id: assertion.otel.ff265ca66687a1339456
assertion_kind: property
subject: operation.otel.http.GET--pets-id.dc9e2765dcf6
predicate: fiam.property.http-route
polarity: asserted
value: /pets/{id}
evidence:
mode: fiam.evidence.runtime-observed
source:
type: otlp-trace-stream
ref: artifact.otel.stream.ambiguous-http.otlp.4f7c9d655f57
locator: attribute:http.route
metadata:
source: real-world/otel/estate-hardening/ambiguous-http.otlp.json
semconv_basis: OpenTelemetry Semantic Conventions 1.44.0
otlp_basis: OTLP 1.11.0
locator_class: attribute:http.route
sample_spans:
- trace:88888888888888888888888888888888/span:3333333333333333
observer: otel-ingest/v0.2-draft.4
confidence: 1.0
stance: supports
observed_at: '2026-09-09T07:00:00Z'
valid_time:
valid_from: '2026-09-09T07:00:00Z'
valid_until: '2026-09-09T07:00:00Z'
observed_at: '2026-09-09T07:00:00Z'
extensions:
org.fiam.catalog:
version: 0.2-draft.4
processed_batches:
- b3421c406d9a5e66b75c94da6067d48540f2fa2abb39b0daf45ba77c1466bd77
declared_entity_ids:
- artifact.ambiguous-declaration
- binding.alpha
- binding.beta
- contract.alpha.http
- contract.beta.http
- endpoint.alpha
- endpoint.beta
- node.service.alpha
- node.service.beta
- operation.alpha.get-pet
- operation.beta.get-pet
- port.alpha.http
- port.beta.http
last_ingest_at: '2026-09-09T07:00:00Z'
runtime_policy: aggregate-by-architectural-tuple
occurrence_retention: sample
sample_size: 3
org.fiam.runtime_aggregates:
- id: aggregate.otel.1b5b9581923bee4418356756
domain: http
role: server
operation: operation.otel.http.GET--pets-id.dc9e2765dcf6
binding: binding.otel.http.gateway-observed-unlocated.715c2ecd9a06
local_node: node.otel.service.gateway-observed.4ea22f0238ef
remote_node: null
channel: null
resource: null
method: GET
route: /pets/{id}
count: 1
error_count: 0
first_seen: '2026-09-09T07:00:00Z'
last_seen: '2026-09-09T07:00:00Z'
sample_spans:
- trace:88888888888888888888888888888888/span:3333333333333333
org.fiam.runtime_topology_observations: []
org.fiam.runtime_unresolved: []
org.fiam.reconciliation_candidates:
- observed_ref: operation.otel.http.GET--pets-id.dc9e2765dcf6
entity_kind: operation
status: ambiguous
candidates:
- declared_ref: operation.alpha.get-pet
binding_ref: binding.alpha
endpoint_ref: endpoint.alpha
node_ref: node.service.alpha
score: 0.8
signals:
- http-method
- http-route-exact
- declared_ref: operation.beta.get-pet
binding_ref: binding.beta
endpoint_ref: endpoint.beta
node_ref: node.service.beta
score: 0.8
signals:
- http-method
- http-route-exact
zones:
- id: zone.otel.environment.production.1521d207f3b6
kind: zone
name: production
zone_type: fiam.zone-type.deployment-environment
members:
- node.otel.service.gateway-observed.4ea22f0238ef
interactions:
- id: interaction.sample.1b5b9581923bee4418356756.3333333333333333
kind: interaction
operation: operation.otel.http.GET--pets-id.dc9e2765dcf6
contract: contract.otel.http.gateway-observed.5205bb5e84c0
binding: binding.otel.http.gateway-observed-unlocated.715c2ecd9a06
interaction_style: fiam.interaction-style.request-response
execution_boundary: fiam.execution-boundary.remote-network
realization_status: fiam.interaction-status.completed
participants:
responder: node.otel.service.gateway-observed.4ea22f0238ef
facets:
otel_trace_id: '88888888888888888888888888888888'
otel_span_id: '3333333333333333'
otel_span_kind: server
instrumentation_scope: fixture
observed_service: node.otel.service.gateway-observed.4ea22f0238ef

19
history/FIAM_v0.2_Draft6/real-world/composite/ambiguous-http.lens.md Normal file
View file

@ -0,0 +1,19 @@
# fiam.lens.declared-vs-observed result
Model: `model.declared.ambiguous-http.catalog`
## Property comparison
## Coverage
- **ambiguous:** 1
- **declared-only:** 2
## Property findings
## Coverage findings
- **declared-only** operation: `operation.alpha.get-pet`
- **declared-only** operation: `operation.beta.get-pet`
- **ambiguous** operation: `operation.otel.http.GET--pets-id.dc9e2765dcf6` (ambiguous)

50
history/FIAM_v0.2_Draft6/real-world/composite/ambiguous-http.lens.yaml Normal file
View file

@ -0,0 +1,50 @@
lens: fiam.lens.declared-vs-observed
lens_version: 0.2-draft.4
model: model.declared.ambiguous-http.catalog
summary:
pairs: 0
property_findings: 0
classifications: {}
coverage:
ambiguous: 1
declared-only: 2
findings: []
coverage_findings:
- entity_kind: operation
classification: declared-only
declared_ref: operation.alpha.get-pet
owner:
node_ref: node.service.alpha
name: alpha
- entity_kind: operation
classification: declared-only
declared_ref: operation.beta.get-pet
owner:
node_ref: node.service.beta
name: beta
- entity_kind: operation
classification: ambiguous
observed_ref: operation.otel.http.GET--pets-id.dc9e2765dcf6
candidate_status: ambiguous
candidates: &id001
- declared_ref: operation.alpha.get-pet
binding_ref: binding.alpha
endpoint_ref: endpoint.alpha
node_ref: node.service.alpha
score: 0.8
signals:
- http-method
- http-route-exact
- declared_ref: operation.beta.get-pet
binding_ref: binding.beta
endpoint_ref: endpoint.beta
node_ref: node.service.beta
score: 0.8
signals:
- http-method
- http-route-exact
reconciliation_candidates:
- observed_ref: operation.otel.http.GET--pets-id.dc9e2765dcf6
entity_kind: operation
status: ambiguous
candidates: *id001

1001
history/FIAM_v0.2_Draft6/real-world/composite/gateway-rpc.fiam.yaml Normal file
View file

File diff suppressed because it is too large Load diff

13
history/FIAM_v0.2_Draft6/real-world/composite/gateway-rpc.topology.md Normal file
View file

@ -0,0 +1,13 @@
# Runtime Interaction Topology
Model: `specimen.grpc.bidirectional-stream.catalog`
## Summary
- **rpc:** 1
- **unresolved:** 0
- **working-set attachments:** 3
## Edges
- RPC: **Telemetry Client** → **istio-proxy** via gateway **istio-proxy** toward **Telemetry Aggregator**

Some files were not shown because too many files have changed in this diff Show more