Establish InterfaceCanon with Statehub integration and FIAM-derived model

Assistant: codex Assistant-Model: gpt-6-astra Assistant-Session: 01a087be-d842-7252-81be-2105c4279c87
2026-09-09 22:05:18 +02:00 · 2026-09-09 22:05:18 +02:00 · ee0df5c931
commit ee0df5c931
parent af74f742de
21 changed files with 937 additions and 2 deletions
--- a/.custodian-brief.md
+++ b/.custodian-brief.md
@ -0,0 +1,27 @@
+<!-- custodian-brief: generated by statehub register; fix-consistency may replace this file -->
+# Custodian Brief - interface-canon
+
+**Project:** interface-canon
+**Domain:** infotech
+**State Hub:** http://127.0.0.1:8000
+**Topic ID:** `fe2aaa78-9c20-4feb-b3d2-4fe0529572a3`
+
+## Open Workplans
+
+### Bootstrap State Hub integration
+
+Workplan file: `workplans/INTERFACE-WP-0001-statehub-bootstrap.md`
+
+Open tasks:
+- T01 - Review generated integration files
+- T02 - Verify local developer workflow
+- T03 - Seed first real workplan
+
+## Session Start
+
+1. Read `INTENT.md`, `SCOPE.md`, and `AGENTS.md`.
+2. Check inbox: `GET /messages/?to_agent=interface-canon&unread_only=true`.
+3. Scan `workplans/`.
+4. Update task statuses in workplan files as work progresses.
+
+Last generated: 2026-09-09
--- a/.gitignore
+++ b/.gitignore
@ -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
--- a/.repo-classification.yaml
+++ b/.repo-classification.yaml
@ -0,0 +1,11 @@
+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: [canon, interface-architecture, terminology, knowledge]
+  business_stake: [technology, product, operations]
+  business_mechanics: [coordination, operation]
--- a/AGENTS.md
+++ b/AGENTS.md
@ -0,0 +1,218 @@
+# interface-canon — Agent Instructions
+
+## Repo Identity
+
+**Purpose:** Interface terminology and canonical models extending InfoTechCanon, derived from the FIAM facetted-interfaces standard.
+
+**Domain:** infotech
+**Repo slug:** interface-canon
+**Topic ID:** `fe2aaa78-9c20-4feb-b3d2-4fe0529572a3`
+**Workplan prefix:** `INTERFACE-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=interface-canon&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=interface-canon&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.
+
+---
+
+For credentials, use `warden route find "<need>" --json` to find the owning subsystem. Never store secrets in this repository or work records.
+
+<!-- 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/INTERFACE-WP-NNNN-<slug>.md`
+
+**Archived location:** finished workplans may move to
+`workplans/archived/YYMMDD-INTERFACE-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
+`INTERFACE-WP-ADHOC-YYYY-MM-DD`, and task ids
+`INTERFACE-WP-ADHOC-YYYY-MM-DD-T01`, etc. `INTERFACE-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: INTERFACE-WP-NNNN
+type: workplan
+title: "..."
+domain: infotech
+repo: interface-canon
+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: INTERFACE-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: INTERFACE-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.
+
+## InterfaceCanon workflow
+
+Read `canon.yaml`, the interface model, mappings, and source manifests before
+changing definitions. Preserve InfoTechCanon shared ownership and FIAM provenance.
+Do not add protocol-specific Core entities or claim source conformance locally.
+
+- Install/build/run: none; this is a Markdown-first semantic canon.
+- Validate: `make check` (Python 3 standard library).
+- Verify all upstream Git pins: `make check-sources` (sibling source checkouts).
+- Source standard conformance belongs to facetted-interfaces; run its package's
+  `make check` there only when changing or specifically auditing that standard.
+- Workplan prefix is `INTERFACE-WP-`; source files are authoritative.
--- a/INTENT.md
+++ b/INTENT.md
@ -0,0 +1,16 @@
+# Intent
+
+InterfaceCanon provides an implementation-neutral vocabulary for describing
+interface contracts, participation, realization, exchange, and information forms.
+It extends InfoTechCanon in the same architectural role that CommerceCanon serves
+for commercial terminology: import shared roots and contribute a focused domain model.
+
+Terminology is derived from the facetted-interfaces FIAM standard. Preserve its
+orthogonal distinctions and source identifiers, and pin each reviewed revision.
+FIAM remains the authority for its standard, schemas, profiles, and conformance.
+InterfaceCanon owns its derived definitions and cross-canon mappings, without
+claiming that upstream owners have approved reciprocal adoption or transferred concepts.
+
+The initial demand is the repository owner's 2026-09-09 request for this extension.
+Draft publication makes the model reviewable; stable promotion needs reviewed
+mappings and concrete consumer evidence.
--- a/6
+++ b/6
@ -0,0 +1,6 @@
+.PHONY: check check-sources
+check:
+	python3 tools/check.py
+
+check-sources:
+	python3 tools/check.py --require-sources
--- a/README.md
+++ b/README.md
@ -1,3 +1,24 @@
-# interface-canon
+# InterfaceCanon

-Othogonal vocabulary and canonical model for interface related concepts based on the fiam architecture control system.
+Interface terminology and canonical models extending InfoTechCanon, derived from
+the FIAM standard maintained in facetted-interfaces.
+
+Like CommerceCanon for commercial terminology, this repository adds domain
+semantics while importing shared concepts from InfoTechCanon. The initial model
+is **draft 0.1.0**, based on **FIAM v0.2 Draft 6** and its frozen v0.2 Core.
+
+- [Intent](INTENT.md) and [scope](SCOPE.md)
+- [Canon manifest](canon.yaml) and [contribution rules](infospace/kernel/InterfaceCanonCore.md)
+- [Interface model and terminology](infospace/models/interface/InterfaceCanonInterfaceModel.md)
+- [Upstream mappings](infospace/mappings/upstream.md) and [source provenance](infospace/assimilation/fiam/README.md)
+- [Federation interface card](infospace/interfaces/federation.yaml)
+- [Workplans](workplans/) and [agent workflow](AGENTS.md)
+
+Run `make check` to validate local metadata, links, and pinned-source integrity.
+Python 3 is the only requirement; no install, build, or runtime service is needed.
+Source verification uses sibling checkouts by default; `make check-sources`
+requires them and verifies the pinned Git blobs, independently of working-tree edits.
+
+Statehub identity: `interface-canon`, domain `infotech`, topic `canon`, workplan
+prefix `INTERFACE-WP-`. Repository work records are authoritative; Statehub indexes
+the committed Forge revision.
--- a/SCOPE.md
+++ b/SCOPE.md
@ -0,0 +1,21 @@
+# Scope
+
+## In scope
+
+- Interface-domain terminology derived from FIAM, with traceable source locators.
+- Explicit imports and mappings to InfoTechCanon shared semantics.
+- A kernel/models/standards layout, canon manifest, examples, and federation card.
+- Statehub registration, file-based workplans, provenance, and validation.
+
+## Out of scope
+
+- Forking FIAM schemas, its reference implementation, or conformance rules.
+- Runtime discovery, telemetry ingestion, architecture catalog services, or policy execution.
+- Redefining generic identity, evidence, governance, software, or network concepts.
+- Claiming cross-repository ownership transfers or reciprocal adoption without review.
+
+## Current state
+
+Draft 0.1.0 derives its vocabulary from FIAM v0.2 Draft 6 and the frozen Core.
+No local standard or runtime service is published. Source pins and unresolved
+mapping boundaries are explicit. Follow-up review is tracked in INTERFACE-WP-0003.
--- a/canon.yaml
+++ b/canon.yaml
@ -0,0 +1,29 @@
+repository: interface-canon
+title: InterfaceCanon
+status: draft
+version: 0.1.0
+description: Interface-domain semantics extending InfoTechCanon and derived from FIAM.
+layout:
+  layout_family: kernel-models-standards
+  infospace_root: infospace/
+classification:
+  kernel: Purpose, ownership boundaries, provenance, and contribution rules.
+  models: Interface-domain semantics with explicit shared imports.
+  standards: Normative rules; FIAM remains external and no local standard is published.
+kernel:
+  - id: interface-core
+    title: InterfaceCanon Core
+    path: infospace/kernel/InterfaceCanonCore.md
+    status: draft
+models:
+  - id: interface-model
+    title: InterfaceCanon Interface Model
+    path: infospace/models/interface/InterfaceCanonInterfaceModel.md
+    status: draft
+    version: 0.1.0
+standards: []
+interface_cards:
+  - id: interface-canon/federation-interface
+    path: infospace/interfaces/federation.yaml
+    status: draft
+    version: 0.1.0
--- a/docs/bootstrap-evidence.md
+++ b/docs/bootstrap-evidence.md
@ -0,0 +1,15 @@
+# Bootstrap evidence — 2026-09-09
+
+- Statehub registration succeeded on `primary / railiance01` for
+  `interface-canon`, domain `infotech`, topic `canon`.
+- Repo ID: `ad525bb5-70e7-4eb6-8b51-cccc547d42fe`.
+- Host path registered for `bnt-lap001`.
+- `make check-sources`: passed document links, manifest artifact paths,
+  12 unique work-record IDs, and all eight source Git-blob SHA-256 checks.
+- All local YAML parsed successfully; the federation card passed the current
+  InfoTechCanon `infospace/schemas/interface-card.schema.yaml` using jsonschema.
+- `git diff --check`: passed.
+
+These checks validate the documentation foundation and source integrity. They do
+not assert FIAM implementation conformance or cross-canon adoption. Remaining
+mapping review and consumer evidence are live tasks in INTERFACE-WP-0003.
--- a/infospace/assimilation/fiam/README.md
+++ b/infospace/assimilation/fiam/README.md
@ -0,0 +1,16 @@
+# FIAM derivation
+
+Source: sibling repository `facetted-interfaces`, maintained package
+`history/FIAM_v0.2_Draft6/`. [sources.json](sources.json) records the exact Git
+commit and SHA-256 for each reviewed artifact. Draft 6 supplies the operating
+boundary; its retained Draft 1 explains the frozen Core semantics. Core JSON
+pointers in the interface model provide term-level locators; the FIAM Canon
+supplies controlled facet and relation terms.
+
+Disposition: adapt the vocabulary into a draft domain model, reference schemas
+and conformance upstream, and map shared concepts explicitly. No upstream corpus
+is copied here. The source package is a draft in `history/`, not a promoted release.
+Do not infer stability from its frozen Core.
+
+Review basis: repository owner request, 2026-09-09; INTERFACE-WP-0002.
+Future source updates require changed-definition review and refreshed pins.
--- a/infospace/assimilation/fiam/sources.json
+++ b/infospace/assimilation/fiam/sources.json
@ -0,0 +1,26 @@
+{
+  "schema_version": 1,
+  "source_repository": "facetted-interfaces",
+  "source_commit": "135326756913363b098bcdee791628b5e864b8be",
+  "source_version": "0.2-draft.6",
+  "disposition": "adapt",
+  "status": "draft",
+  "sources": [
+    {
+      "path": "history/FIAM_v0.2_Draft6/FIAM-v0.2-Draft6.md",
+      "sha256": "2004357a259cd785fbbfbcdd0bc9f915f27e0859c6f558707d2e2f51b021e139"
+    },
+    {
+      "path": "history/FIAM_v0.2_Draft6/history/FIAM-v0.2-Draft1.md",
+      "sha256": "7b10961b1037e825ed222f15650254baeb380431080d915015f50ae1ab2a298b"
+    },
+    {
+      "path": "history/FIAM_v0.2_Draft6/schemas/FIAM-Core-v0.2.schema.json",
+      "sha256": "a6fce1b19ab7009069a1c8552fc6035cabd8707cb63b647350396d36785668d9"
+    },
+    {
+      "path": "history/FIAM_v0.2_Draft6/canon/FIAM-Canon-v0.2.yaml",
+      "sha256": "3b9e6210b0ec1f0568d401d220750d61c2b211fea80d325210dee7c3619dcef6"
+    }
+  ]
+}
--- a/infospace/interfaces/federation.yaml
+++ b/infospace/interfaces/federation.yaml
@ -0,0 +1,40 @@
+id: interface-canon/federation-interface
+title: InterfaceCanon Federation Interface Card
+consumer: interface-canon
+canon_surfaces: [interface-model]
+status: draft
+version: 0.1.0
+owner: interface-canon
+schema_source:
+  repository: info-tech-canon
+  path: infospace/schemas/interface-card.schema.yaml
+peers:
+  - repository: info-tech-canon
+    relationship: shared-concept upstream; interface-domain extension
+  - repository: facetted-interfaces
+    relationship: FIAM terminology and conformance authority
+  - repository: commerce-canon
+    relationship: structural precedent for a focused domain canon
+exports:
+  - artifact: interface-model
+    kind: domain-model
+    path: infospace/models/interface/InterfaceCanonInterfaceModel.md
+    status: draft
+    availability: referenceable for review; adoption not asserted
+imports:
+  - repository: info-tech-canon
+    artifacts: [itc-land, itc-ident, itc-evid, itc-gov]
+    manifest: infospace/models/interface/imports.json
+  - repository: facetted-interfaces
+    artifact: FIAM v0.2 Draft 6
+    manifest: infospace/assimilation/fiam/sources.json
+mapping_rules:
+  - Shared concepts retain their InfoTechCanon owner.
+  - FIAM retains ownership of standard semantics, schemas, and conformance.
+  - Local definitions remain FIAM-qualified where upstream names overlap.
+known_deviations:
+  - Reciprocal cards and federation ownership-ledger acceptance are not yet established.
+  - Evidence records require an explicit assertion/source mapping, not a direct alias.
+expectations:
+  - Review source changes and retain commit and content-hash provenance.
+  - Complete INTERFACE-WP-0003 before stable promotion.
--- a/infospace/kernel/InterfaceCanonCore.md
+++ b/infospace/kernel/InterfaceCanonCore.md
@ -0,0 +1,29 @@
+---
+id: interface-core
+title: InterfaceCanon Core
+type: kernel
+status: draft
+version: 0.1.0
+---
+
+# InterfaceCanon Core
+
+Maintain one focused domain model extending InfoTechCanon. `canon.yaml` is the
+entry-point registry. Models live under `infospace/models/`; standards, if later
+needed, belong under `infospace/standards/`. Workplans stay in the repository shell.
+CommerceCanon is the structural precedent, not an imported commercial dependency.
+
+Every new term must have a definition, distinguishing counterexample, source
+locator or explicit local rationale, and an ownership disposition. Preserve FIAM
+identifiers in mappings; do not relabel protocol families as primitive entity types.
+Import shared roots from their owner. A name collision requires an explicit
+mapping and review, not a silent replacement or an assertion of equivalence.
+
+Changes to source pins require review of changed semantics and a work record.
+Keep previous manifests in Git history. A draft may expose unresolved mappings;
+stable promotion requires their resolution and named consumer evidence. Do not
+represent availability as adoption or a local card as reciprocal federation acceptance.
+
+FIAM Core facts, exchange profiles, derived indexes, and policy/lens conclusions
+remain separate layers. This canon summarizes terminology; FIAM owns wire formats,
+validation, conformance, and implementation behavior.
--- a/infospace/mappings/upstream.md
+++ b/infospace/mappings/upstream.md
@ -0,0 +1,30 @@
+# Upstream ownership and mapping
+
+InfoTechCanon supplies shared semantics through the model's
+[import manifest](../models/interface/imports.json). FIAM supplies the specialized
+architecture vocabulary through its [source manifest](../assimilation/fiam/sources.json).
+This is a draft local mapping; no upstream ownership transfer is asserted.
+
+| FIAM/domain term | Shared owner or disposition | Mapping boundary |
+| --- | --- | --- |
+| InterfaceContract | Local interface specialization; ITC-LAND already seeds Interface | A semantic contract is one aspect of interface architecture; not an exact alias for every landscape Interface. |
+| Endpoint | ITC-LAND seeds Endpoint; local FIAM-qualified usage | The FIAM meaning is the locator of a Binding. Network interfaces and resource selectors are separate. |
+| Participant / SystemNode | Align with ITC-LAND SoftwareSystem/SoftwareComponent where applicable | No blanket equivalence to Actor, host, process, or deployment; choose by modeled scope. |
+| Entity identifier | ITC-IDENT Identifier / Scoped Identifier | FIAM identifier syntax alone does not establish global identity. |
+| same-entity-as | Relate to ITC-IDENT Synonymity Assertion | FIAM query-time equivalence has specific evidence constraints; no destructive merge or automatic cross-canon equivalence. |
+| Assertion | ITC-GOV Assertion | FIAM specializes architectural property/relation assertions with evidence and polarity. |
+| FIAM evidenceRecord | Map to ITC-EVID Evidence plus Evidence Source | FIAM evidenceRecord is support metadata with source, mode and confidence. ITC Evidence is an assertion drawn for a question; source container is separately identified. This is not a one-to-one rename. |
+| Evidence score | ITC-EVID Evidence strength | A FIAM Lens computes a policy-specific heuristic; confidence and support scores are not universal truth probabilities. |
+| Artifact | FIAM describing/implementing artifact role | It may serve as ITC Evidence Source when addressable and versioned; the artifact is not the assertion drawn from it. |
+| Zone / security profile | Reference FIAM contextual classifications | No transfer of generic network, security, trust, tenant, or authorization ownership. |
+| Policy / decision | ITC-GOV Policy / Decision | A Lens finding is an interpretation, not automatically a governed decision or authorization. |
+
+Port, Contract Participation, Operation, Binding, Channel, Interaction,
+Interaction Flow, Information Resource, Information Shape, Resource Selector,
+Facet, Representation, and Lens receive FIAM-derived interface-domain definitions.
+Names that overlap other ITC models remain qualified as `interface-model:*`;
+this initial import set is not an exhaustive federation ownership audit.
+
+INTERFACE-WP-0003 tracks review of these boundaries, including Information
+Resource/Shape against ITC-DATA and Artifact against Information Space. Keep
+publication draft until that review and a concrete consumer proof are complete.
--- a/infospace/models/interface/InterfaceCanonInterfaceModel.md
+++ b/infospace/models/interface/InterfaceCanonInterfaceModel.md
@ -0,0 +1,168 @@
+---
+id: interface-model
+title: InterfaceCanon Interface Model
+namespace: interface-model
+type: domain-model
+status: draft
+version: 0.1.0
+imports: [itc-land, itc-ident, itc-evid, itc-gov]
+import_manifest: imports.json
+source_manifest: ../../assimilation/fiam/sources.json
+---
+
+# InterfaceCanon Interface Model
+
+Draft terminology derived from FIAM v0.2 Draft 6. These are domain definitions,
+not a new FIAM schema or a claim of transferred ownership. The exact FIAM spellings
+and source JSON pointers are recorded below. [Upstream mappings](../../mappings/upstream.md)
+explain shared concepts and collisions; [imports.json](imports.json) pins InfoTechCanon.
+
+## Structural vocabulary
+
+Each source locator below is relative to `schemas/FIAM-Core-v0.2.schema.json`
+in the [pinned FIAM package](../../assimilation/fiam/README.md).
+
+### 1. Port
+
+An owned architectural participation point through which a participant or system node offers or requires a particular interface contract.
+
+An offer/require mode is contract participation, not message direction.
+
+Source: `#/$defs/port`. Local identifier: `interface-model:port`.
+
+### 2. Contract Participation
+
+The association of a Port with a specific InterfaceContract, an offers/requires mode, and contextual roles.
+
+Roles belong to the participation; a port-global role cannot describe every contract context.
+
+Source: `#/$defs/contractParticipation`. Local identifier: `interface-model:contractParticipation`.
+
+### 3. Interface Contract
+
+A semantic agreement organizing operations and their purposes independently of any particular transport realization.
+
+One contract can have multiple bindings; a specification file describes the contract.
+
+Source: `#/$defs/interfaceContract`. Local identifier: `interface-model:interfaceContract`.
+
+### 4. Operation
+
+A named unit of interface behavior within a contract, qualified by interaction style, temporal semantics, effects, and purpose.
+
+A runtime exchange selects or realizes an operation; the operation is not a trace occurrence.
+
+Source: `#/$defs/operation`. Local identifier: `interface-model:operation`.
+
+### 5. Binding
+
+A realization of a contract and selected operations through participating ports, communication stack, addressing, discovery, and optional channel or endpoints.
+
+A second transport can realize the same contract without creating new semantic operations.
+
+Source: `#/$defs/binding`. Local identifier: `interface-model:binding`.
+
+### 6. Endpoint
+
+A concrete locator or selector through which a Binding is reached.
+
+An endpoint may be reused by multiple bindings; it is not the information resource selected through that binding.
+
+Source: `#/$defs/endpoint`. Local identifier: `interface-model:endpoint`.
+
+### 7. Channel
+
+An exchange or mediation locus characterized by delivery, ordering, replay, or retention semantics where known.
+
+A Kafka topic as exchange channel may be backed by a retained-log resource; those roles remain distinct.
+
+Source: `#/$defs/channel`. Local identifier: `interface-model:channel`.
+
+### 8. Interaction
+
+An architectural participation in an exchange linking relevant operation, contract, binding, participants, and channel, with realization status where known.
+
+An interaction can be proposed or rejected; do not equate every interaction with an executed span.
+
+Source: `#/$defs/interaction`. Local identifier: `interface-model:interaction`.
+
+### 9. Interaction Flow
+
+An ordered composition of exchange steps referring to operations, interactions, bindings, and participants.
+
+It expresses composition rather than inventing a new protocol or contract family.
+
+Source: `#/$defs/interactionFlow`. Local identifier: `interface-model:interactionFlow`.
+
+### 10. Information Resource
+
+An identifiable information-bearing object, state, collection, or logical selection that can be addressed independently of a single interaction.
+
+A collection is a resource; its admissible form is a shape, and its access location is not automatically a binding endpoint.
+
+Source: `#/$defs/informationResource`. Local identifier: `interface-model:informationResource`.
+
+### 11. Information Shape
+
+An identifiable semantic or structural type or constraint set describing an admissible information form.
+
+A shape is distinct from an instance, a schema artifact, and JSON or another concrete encoding. Detailed fields remain in describing artifacts.
+
+Source: `#/$defs/informationShape`. Local identifier: `interface-model:informationShape`.
+
+### 12. Resource Selector
+
+A selector identifying an information resource within a provider, namespace, collection, or logical address space.
+
+A database collection selector does not locate the network binding.
+
+Source: `#/$defs/resourceSelector`. Local identifier: `interface-model:resourceSelector`.
+
+## Facets and interpretations
+
+A **Facet** records an orthogonal characteristic of a structural entity or assertion.
+FIAM uses controlled terms for such dimensions as interaction style, temporal
+semantics, effect, purpose, communication stack, and security. A facet is not a
+new structural interface type. Source: Core `#/$defs/facets` and the FIAM Canon.
+
+**Representation** is the concrete encoding or notation selected for information
+participation. It is authoritative on the most specific applicable shape-participation
+assertion. Operation-level and contract-level representation lists are deprecated.
+Source: Draft 1, “Representation stays relation-scoped”.
+
+A **Lens** is a named interpretation over architectural facts and their evidence.
+**Family labels** are derived lens results, with inferred provenance if cached;
+HTTP, RPC, messaging, or a label such as REST must not become invented Core classes.
+Source: Draft 1, “Cached family labels require provenance”; Draft 6 §§1, 6–7.
+
+## Relationships and invariants
+
+- A Port participates in a contract; a Binding realizes that contract and its operations.
+- Shape participation refines Operation → Binding → Interaction. Refinement uses
+  the same shape, identity-equivalent shape, or evidenced projection/version.
+  Multi-operation binding refinements identify the operation with `operation_ref`.
+- `conforms-to-shape` describes the whole addressed resource; `element-shape`
+  describes collection members. A collection's shape and its element shape differ.
+- Artifacts describe or implement architectural entities; representation encodes information.
+- Missing facts remain unknown. Explicit absence, not-applicable, and unknown differ.
+- Similarity supports correspondence, not automatic identity or destructive merging.
+- Lens evidence scores and governance conclusions remain policy-dependent results.
+
+Sources: Draft 1 “Stable structural spine” and hardening decisions 3–7;
+Core `assertion`; Draft 6 §§1, 6–7. These summaries preserve source semantics;
+FIAM remains authoritative for exact validation requirements.
+
+## Worked boundary cases
+
+| Case | Interpretation |
+| --- | --- |
+| Same MCP tools over stdio and HTTP | Shared contract/operations/shapes; distinct realization bindings. |
+| Kafka topic with retained events | Channel for exchange, Information Resource for retained log, related by `backed-by`. |
+| JSON document governed by a schema | Resource instance, Information Shape, describing Artifact, and Representation remain distinct. |
+| Port offers a request-response contract | Offers is participation mode; requests and responses still travel in different directions. |
+| Two schemas have identical fields | Correspondence candidate; no automatic identity assertion. |
+| Telemetry contains no authentication attributes | Unknown runtime authentication evidence; no inferred absence of protection. |
+
+These are explanatory cases derived from the pinned source, not executable FIAM
+fixtures or evidence of consumer adoption. Cross-canon review and a consumer proof
+are tracked in INTERFACE-WP-0003.
--- a/infospace/models/interface/imports.json
+++ b/infospace/models/interface/imports.json
@ -0,0 +1,49 @@
+{
+  "schema_version": 1,
+  "model": "interface-model",
+  "source_repository": "info-tech-canon",
+  "source_commit": "8eb1c83f2e119de57e7ad448b901381f8e92fb57",
+  "imports": [
+    {
+      "model": "itc-land",
+      "path": "infospace/models/landscape/InfoTechCanonLandscapeModel.md",
+      "sha256": "4190b044fbd5e3eecf7b28e08608e99c7de3af5dd5f3a7554edee02423967fb1",
+      "concepts": [
+        "Interface",
+        "Endpoint",
+        "SoftwareSystem",
+        "SoftwareComponent"
+      ]
+    },
+    {
+      "model": "itc-ident",
+      "path": "infospace/models/identity/InfoTechCanonIdentityModel.md",
+      "sha256": "20bc844d9de07041c40009cc5e3d6eeb42aeb7adcbb86b0194d4b2517aa23f32",
+      "concepts": [
+        "Identifier",
+        "Scoped Identifier",
+        "Synonymity Assertion"
+      ]
+    },
+    {
+      "model": "itc-evid",
+      "path": "infospace/models/evidence/InfoTechCanonEvidenceModel.md",
+      "sha256": "a93472818b3ae60c07a4c6226090d63eebf1402dfd9f46dad643dbb5608ed086",
+      "concepts": [
+        "Evidence",
+        "Evidence Source",
+        "Evidence strength"
+      ]
+    },
+    {
+      "model": "itc-gov",
+      "path": "infospace/models/governance/InfoTechCanonGovernanceModel.md",
+      "sha256": "5f3174147ec0d6f5bb6479a7ce4dc130bf61ecc0bab3936895b92c6baf21deb5",
+      "concepts": [
+        "Assertion",
+        "Policy",
+        "Decision"
+      ]
+    }
+  ]
+}
--- a/tools/check.py
+++ b/tools/check.py
@ -0,0 +1,60 @@
+"""Check document references, work-record identity, and immutable source provenance."""
+import argparse
+import hashlib
+import json
+from pathlib import Path
+import re
+import subprocess
+
+ROOT = Path(__file__).resolve().parents[1]
+parser = argparse.ArgumentParser()
+parser.add_argument('--require-sources', action='store_true')
+args = parser.parse_args()
+errors = []
+for path in ROOT.rglob('*.md'):
+    if '.git' in path.parts:
+        continue
+    for link in re.findall(r'\[[^\]]*\]\(([^)]+)\)', path.read_text()):
+        if '://' in link or link.startswith('#'):
+            continue
+        target = link.split('#')[0]
+        if target and not (path.parent / target).exists():
+            errors.append(f'{path.relative_to(ROOT)}: missing link {target}')
+ids = set()
+for path in sorted((ROOT / 'workplans').glob('*.md')):
+    text = path.read_text()
+    for identifier in re.findall(r'^id: (INTERFACE-WP-[^\s]+)$', text, re.M):
+        if identifier in ids:
+            errors.append(f'duplicate work-record id: {identifier}')
+        ids.add(identifier)
+    for status in re.findall(r'^status: (\S+)$', text, re.M):
+        if status not in {'proposed', 'ready', 'active', 'blocked', 'backlog', 'finished', 'archived', 'wait', 'todo', 'progress', 'done', 'cancel'}:
+            errors.append(f'{path.name}: invalid status {status}')
+for path in [ROOT / 'canon.yaml', ROOT / 'infospace/interfaces/federation.yaml']:
+    for target in re.findall(r'^\s*(?:path|manifest): (\S+)$', path.read_text(), re.M):
+        if target == 'infospace/schemas/interface-card.schema.yaml':
+            continue  # Explicitly owned upstream.
+        if not (ROOT / target).is_file():
+            errors.append(f'{path.name}: missing artifact {target}')
+for path in sorted((ROOT / 'infospace').rglob('*.json')):
+    manifest = json.loads(path.read_text())
+    revision = manifest['source_commit']
+    if not re.fullmatch('[0-9a-f]{40}', revision):
+        errors.append(f'{path}: invalid source commit')
+    source = ROOT.parent / manifest['source_repository']
+    records = manifest.get('sources', manifest.get('imports', []))
+    if not records:
+        errors.append(f'{path}: empty source manifest')
+    for record in records:
+        if not re.fullmatch('[0-9a-f]{64}', record['sha256']):
+            errors.append(f'{path}: invalid SHA-256')
+        if not (source / '.git').exists():
+            if args.require_sources:
+                errors.append(f'missing source checkout: {source}')
+            continue
+        result = subprocess.run(['git', '-C', str(source), 'show', f'{revision}:{record["path"]}'], capture_output=True)
+        if result.returncode or hashlib.sha256(result.stdout).hexdigest() != record['sha256']:
+            errors.append(f'{path.name}: source integrity failure for {record["path"]}')
+if errors:
+    raise SystemExit('\n'.join(errors))
+print(f'PASS: document links, artifact paths, {len(ids)} work-record IDs, and available pinned Git sources')
--- a/workplans/INTERFACE-WP-0001-statehub-bootstrap.md
+++ b/workplans/INTERFACE-WP-0001-statehub-bootstrap.md
@ -0,0 +1,55 @@
+---
+id: INTERFACE-WP-0001
+type: workplan
+title: "Bootstrap State Hub integration"
+domain: infotech
+repo: interface-canon
+status: finished
+owner: codex
+topic_slug: canon
+created: "2026-09-09"
+updated: "2026-09-09"
+---
+
+# Bootstrap State Hub integration
+
+Interface terminology and canonical models extending InfoTechCanon, derived from the FIAM facetted-interfaces standard.
+
+## Review Generated Integration Files
+
+```task
+id: INTERFACE-WP-0001-T01
+status: done
+priority: high
+```
+
+Review `INTENT.md`, `SCOPE.md`, `AGENTS.md`, and `.custodian-brief.md`.
+Replace generated placeholders with repo-specific facts where needed.
+
+## Verify Local Developer Workflow
+
+```task
+id: INTERFACE-WP-0001-T02
+status: done
+priority: high
+```
+
+Identify the repo's install, test, lint, build, and run commands. Add or refine
+those commands in the agent instructions so future coding sessions can verify
+changes confidently.
+
+## Seed First Real Workplan
+
+```task
+id: INTERFACE-WP-0001-T03
+status: done
+priority: medium
+```
+
+Create the first implementation workplan for the repository's most important
+next change. After workplan file updates, run the sync locally from this repo
+checkout:
+
+```bash
+uv run --project ~/repo-manager rmgr sync --path . --push
+```
--- a/workplans/INTERFACE-WP-0002-canon-foundation.md
+++ b/workplans/INTERFACE-WP-0002-canon-foundation.md
@ -0,0 +1,49 @@
+---
+id: INTERFACE-WP-0002
+type: workplan
+title: "FIAM-derived interface canon foundation"
+domain: infotech
+repo: interface-canon
+status: finished
+owner: codex
+topic_slug: canon
+created: "2026-09-09"
+updated: "2026-09-09"
+---
+
+# FIAM-derived interface canon foundation
+
+## Define canon boundary and layout
+
+```task
+id: INTERFACE-WP-0002-T01
+status: done
+priority: medium
+```
+
+Implemented in the canon manifest, model, mappings, source manifests, and validation workflow.
+
+## Derive terminology and pin upstream sources
+
+```task
+id: INTERFACE-WP-0002-T02
+status: done
+priority: medium
+```
+
+Implemented in the canon manifest, model, mappings, source manifests, and validation workflow.
+
+## Validate metadata and document review residuals
+
+```task
+id: INTERFACE-WP-0002-T03
+status: done
+priority: medium
+```
+
+Implemented in the canon manifest, model, mappings, source manifests, and validation workflow.
+
+## Evidence and handoff
+
+Validation is recorded in [bootstrap evidence](../docs/bootstrap-evidence.md).
+Residual review is tracked by [INTERFACE-WP-0003](INTERFACE-WP-0003-mapping-and-consumer-review.md).
--- a/workplans/INTERFACE-WP-0003-mapping-and-consumer-review.md
+++ b/workplans/INTERFACE-WP-0003-mapping-and-consumer-review.md
@ -0,0 +1,44 @@
+---
+id: INTERFACE-WP-0003
+type: workplan
+title: "Review shared concept mappings and consumer proof"
+domain: infotech
+repo: interface-canon
+status: ready
+owner: codex
+topic_slug: canon
+created: "2026-09-09"
+updated: "2026-09-09"
+---
+
+# Review shared concept mappings and consumer proof
+
+Residual of INTERFACE-WP-0002. The bootstrap publishes a draft; stable promotion requires this review.
+
+## Review ownership collisions across InfoTechCanon models
+
+```task
+id: INTERFACE-WP-0003-T01
+status: todo
+priority: medium
+```
+
+Review the model, mappings, canon manifest, and pinned source records.
+## Validate one named consumer interface description
+
+```task
+id: INTERFACE-WP-0003-T02
+status: todo
+priority: medium
+```
+
+Record a concrete consumer, its interpretation of contract/binding/channel/resource/shape, and unresolved ambiguity.
+## Review reciprocal federation cards and publication status
+
+```task
+id: INTERFACE-WP-0003-T03
+status: todo
+priority: medium
+```
+
+Validate metadata and provenance; retain draft status until mapping and adoption evidence support promotion.