From ee0df5c9312365548babb3924f5eeb03acf8583b Mon Sep 17 00:00:00 2001 From: tegwick Date: Wed, 9 Sep 2026 22:05:18 +0200 Subject: [PATCH] Establish InterfaceCanon with Statehub integration and FIAM-derived model Assistant: codex Assistant-Model: gpt-6-astra Assistant-Session: 01a087be-d842-7252-81be-2105c4279c87 --- .custodian-brief.md | 27 +++ .gitignore | 5 + .repo-classification.yaml | 11 + AGENTS.md | 218 ++++++++++++++++++ INTENT.md | 16 ++ Makefile | 6 + README.md | 25 +- SCOPE.md | 21 ++ canon.yaml | 29 +++ docs/bootstrap-evidence.md | 15 ++ infospace/assimilation/fiam/README.md | 16 ++ infospace/assimilation/fiam/sources.json | 26 +++ infospace/interfaces/federation.yaml | 40 ++++ infospace/kernel/InterfaceCanonCore.md | 29 +++ infospace/mappings/upstream.md | 30 +++ .../interface/InterfaceCanonInterfaceModel.md | 168 ++++++++++++++ infospace/models/interface/imports.json | 49 ++++ tools/check.py | 60 +++++ .../INTERFACE-WP-0001-statehub-bootstrap.md | 55 +++++ .../INTERFACE-WP-0002-canon-foundation.md | 49 ++++ ...ACE-WP-0003-mapping-and-consumer-review.md | 44 ++++ 21 files changed, 937 insertions(+), 2 deletions(-) create mode 100644 .custodian-brief.md create mode 100644 .gitignore create mode 100644 .repo-classification.yaml create mode 100644 AGENTS.md create mode 100644 INTENT.md create mode 100644 Makefile create mode 100644 SCOPE.md create mode 100644 canon.yaml create mode 100644 docs/bootstrap-evidence.md create mode 100644 infospace/assimilation/fiam/README.md create mode 100644 infospace/assimilation/fiam/sources.json create mode 100644 infospace/interfaces/federation.yaml create mode 100644 infospace/kernel/InterfaceCanonCore.md create mode 100644 infospace/mappings/upstream.md create mode 100644 infospace/models/interface/InterfaceCanonInterfaceModel.md create mode 100644 infospace/models/interface/imports.json create mode 100644 tools/check.py create mode 100644 workplans/INTERFACE-WP-0001-statehub-bootstrap.md create mode 100644 workplans/INTERFACE-WP-0002-canon-foundation.md create mode 100644 workplans/INTERFACE-WP-0003-mapping-and-consumer-review.md diff --git a/.custodian-brief.md b/.custodian-brief.md new file mode 100644 index 0000000..9ee53d3 --- /dev/null +++ b/.custodian-brief.md @@ -0,0 +1,27 @@ + +# 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 diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..e4e0199 --- /dev/null +++ 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 diff --git a/.repo-classification.yaml b/.repo-classification.yaml new file mode 100644 index 0000000..27a6975 --- /dev/null +++ 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] diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..a8dccc5 --- /dev/null +++ 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//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": "", + "task_id": "" + }' +``` + +Omit `workplan_id` / `task_id` when not applicable. + +### Update task status + +```bash +curl -s -X PATCH "http://127.0.0.1:8000/tasks/" \ + -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/" \ + -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: `, 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 "" --json` to find the owning subsystem. Never store secrets in this repository or work records. + + + + +--- + +## 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-.md` + +**Archived location:** finished workplans may move to +`workplans/archived/YYMMDD-INTERFACE-WP-NNNN-.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: "" # 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: "" # 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. diff --git a/INTENT.md b/INTENT.md new file mode 100644 index 0000000..0682edc --- /dev/null +++ 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. diff --git a/Makefile b/Makefile new file mode 100644 index 0000000..3a7b987 --- /dev/null +++ b/Makefile @@ -0,0 +1,6 @@ +.PHONY: check check-sources +check: + python3 tools/check.py + +check-sources: + python3 tools/check.py --require-sources diff --git a/README.md b/README.md index 5a9918e..792b60d 100644 --- 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. \ No newline at end of file +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. diff --git a/SCOPE.md b/SCOPE.md new file mode 100644 index 0000000..d90c4c2 --- /dev/null +++ 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. diff --git a/canon.yaml b/canon.yaml new file mode 100644 index 0000000..3f29cdc --- /dev/null +++ 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 diff --git a/docs/bootstrap-evidence.md b/docs/bootstrap-evidence.md new file mode 100644 index 0000000..9393d30 --- /dev/null +++ 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. diff --git a/infospace/assimilation/fiam/README.md b/infospace/assimilation/fiam/README.md new file mode 100644 index 0000000..c47aa0c --- /dev/null +++ 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. diff --git a/infospace/assimilation/fiam/sources.json b/infospace/assimilation/fiam/sources.json new file mode 100644 index 0000000..435c8ff --- /dev/null +++ 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" + } + ] +} diff --git a/infospace/interfaces/federation.yaml b/infospace/interfaces/federation.yaml new file mode 100644 index 0000000..ffd4133 --- /dev/null +++ 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. diff --git a/infospace/kernel/InterfaceCanonCore.md b/infospace/kernel/InterfaceCanonCore.md new file mode 100644 index 0000000..4056129 --- /dev/null +++ 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. diff --git a/infospace/mappings/upstream.md b/infospace/mappings/upstream.md new file mode 100644 index 0000000..9d621c8 --- /dev/null +++ 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. diff --git a/infospace/models/interface/InterfaceCanonInterfaceModel.md b/infospace/models/interface/InterfaceCanonInterfaceModel.md new file mode 100644 index 0000000..d9861d6 --- /dev/null +++ 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. diff --git a/infospace/models/interface/imports.json b/infospace/models/interface/imports.json new file mode 100644 index 0000000..06f658f --- /dev/null +++ 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" + ] + } + ] +} diff --git a/tools/check.py b/tools/check.py new file mode 100644 index 0000000..3c66328 --- /dev/null +++ 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') diff --git a/workplans/INTERFACE-WP-0001-statehub-bootstrap.md b/workplans/INTERFACE-WP-0001-statehub-bootstrap.md new file mode 100644 index 0000000..e9c340b --- /dev/null +++ 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 +``` diff --git a/workplans/INTERFACE-WP-0002-canon-foundation.md b/workplans/INTERFACE-WP-0002-canon-foundation.md new file mode 100644 index 0000000..a9ff18c --- /dev/null +++ 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). diff --git a/workplans/INTERFACE-WP-0003-mapping-and-consumer-review.md b/workplans/INTERFACE-WP-0003-mapping-and-consumer-review.md new file mode 100644 index 0000000..5aa4c5a --- /dev/null +++ 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.