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

Prepare owner review patches for InterfaceCanon federation and adoption

Browse source 
Assistant: codex
Assistant-Model: gpt-6-astra
Assistant-Session: 01a087be-d842-7252-81be-2105c4279c87
This commit is contained in:
tegwick 2026-09-09 22:19:14 +02:00
parent 1fc82ec665
commit 6b33ac2388
11 changed files with 248 additions and 6 deletions
Download patch file Download diff file Expand all files Collapse all files

6
WORK-RECORDS.md
View file

@ -11,7 +11,7 @@
| workplan | INTERFACE-WP-0001 | finished | — | workplans/INTERFACE-WP-0001-statehub-bootstrap.md |
| workplan | INTERFACE-WP-0002 | finished | — | workplans/INTERFACE-WP-0002-canon-foundation.md |
| workplan | INTERFACE-WP-0003 | finished | — | workplans/INTERFACE-WP-0003-mapping-and-consumer-review.md |
| workplan | INTERFACE-WP-0004 | proposed | — | workplans/INTERFACE-WP-0004-federation-acceptance.md |
| workplan | INTERFACE-WP-0004 | active | — | workplans/INTERFACE-WP-0004-federation-acceptance.md |
| task | INTERFACE-WP-0001-T01 | done | — | workplans/INTERFACE-WP-0001-statehub-bootstrap.md |
| task | INTERFACE-WP-0001-T02 | done | — | workplans/INTERFACE-WP-0001-statehub-bootstrap.md |
| task | INTERFACE-WP-0001-T03 | done | — | workplans/INTERFACE-WP-0001-statehub-bootstrap.md |
@ -21,5 +21,5 @@
| task | INTERFACE-WP-0003-T01 | done | — | workplans/INTERFACE-WP-0003-mapping-and-consumer-review.md |
| task | INTERFACE-WP-0003-T02 | done | — | workplans/INTERFACE-WP-0003-mapping-and-consumer-review.md |
| task | INTERFACE-WP-0003-T03 | done | — | workplans/INTERFACE-WP-0003-mapping-and-consumer-review.md |
| task | INTERFACE-WP-0004-T01 | todo | — | workplans/INTERFACE-WP-0004-federation-acceptance.md |
| task | INTERFACE-WP-0004-T02 | todo | — | workplans/INTERFACE-WP-0004-federation-acceptance.md |
| task | INTERFACE-WP-0004-T01 | wait | — | workplans/INTERFACE-WP-0004-federation-acceptance.md |
| task | INTERFACE-WP-0004-T02 | wait | — | workplans/INTERFACE-WP-0004-federation-acceptance.md |

7
infospace/reviews/2026-09-09/federation-review.md
View file

@ -26,3 +26,10 @@ message was sent as part of this review.
FIAM tree inspection: commit `135326756913363b098bcdee791628b5e864b8be`, command
`git ls-tree -r --name-only HEAD`, no path containing `federation`.
This is a filename-scoped absence check, not proof that no other contract exists.
## Scope clarification from INTERFACE-WP-0004
The pinned project GOAL.md and README show that the ownership ledger belongs to
the completed identity/commerce migration. Absence there is not a failed universal
registration gate. Future extension acceptance belongs with the current owners;
this review does not require reopening the historical migration project.

8
infospace/reviews/2026-09-09/prj-canon-federation-sources.json
View file

@ -6,6 +6,14 @@
{
"path": "ledger/concept-ownership.json",
"sha256": "7bc8d78a66ecad2987f1f0a68207b54db28578b91243bc097313ac7e830fc086"
},
{
"path": "GOAL.md",
"sha256": "b12dc84c2b3e53ffe4dc35e91691da356d0fb3da712b8f590a49a9d08ccb17ce"
},
{
"path": "README.md",
"sha256": "0352a7390694d3859a5ba4614c3b63aa9204cbbab469c913251b8f2d0e5ee909"
}
],
"review_workplan": "INTERFACE-WP-0003"

37
reviews/INTERFACE-WP-0004/README.md Normal file
View file

@ -0,0 +1,37 @@
# InterfaceCanon acceptance review package
INTERFACE-WP-0004. All three patches are prepared and passed `git apply --check`
in their target sibling repositories. They have not been applied or sent.
Each patch adds a bounded draft review/adoption document and a README link.
| Owner | Patch | Prepared request | Acceptance sought |
| --- | --- | --- | --- |
| InfoTechCanon | [Patch](info-tech-canon.patch) | [Request](info-tech-canon-request.md) | Shared-root boundaries and qualified mappings. |
| FIAM | [Patch](facetted-interfaces.patch) | [Request](facetted-interfaces-request.md) | Faithful derivation and retained FIAM authority. |
| Repo Manager | [Patch](repo-manager.patch) | [Request](repo-manager-request.md) | Consumer-owned use of terminology for its existing Statehub integration. |
## Acceptance record requirements
For each response retain reviewer identity, reviewed InterfaceCanon revision,
accepted scope or concrete corrections, and peer review/merge revision when
available. A sent request, locally generated patch, or local worked example is
not an acceptance record. Apply corrections and rerun source/card checks before
closing the corresponding task.
## Publication decision
Keep draft 0.1.1 while responses are absent. Reassess promotion only against actual
upstream and consumer evidence, including the draft status of the source FIAM
standard. Acceptance need not imply immediate stable promotion.
The prior ledger absence finding is narrowed: prj-canon-federation is a completed,
bounded identity/commerce migration. Its GOAL.md and README do not require all
future canon extensions to enter that ledger. No ledger mutation or project
reopening is proposed. Review belongs with the living canon/source/consumer owners.
## Next action
Send the three prepared requests through Statehub after explicit authorization
for messaging. Until then the files are review material only. Keep this workplan
open; do not manufacture owner approval or transfer these unfinished tasks into
another plan.

15
reviews/INTERFACE-WP-0004/facetted-interfaces-request.md Normal file
View file

@ -0,0 +1,15 @@
# Review request: facetted-interfaces
Recipient: `facetted-interfaces` via Statehub. Status: prepared, not sent.
Please review the attached/referenced interface-canon patch
`reviews/INTERFACE-WP-0004/facetted-interfaces.patch`, based on your commit `135326756913363b098bcdee791628b5e864b8be`.
It adds `docs/interface-canon-boundary.md` and a README entry. The proposed source model is
interface-model 0.1.1 at `1fc82ec6655ed286cea3be284e33d08e7b27edc3`.
Please respond with acceptance or specific corrections, reviewer identity, and
reviewed source revision. If accepting and applying, include the peer commit.
Approval is limited to the documented boundary or adoption scope. This request
does not ask you to promote InterfaceCanon to stable or modify the historical
identity/commerce ownership ledger. Reply to interface-canon against
INTERFACE-WP-0004 (T01).

37
reviews/INTERFACE-WP-0004/facetted-interfaces.patch Normal file
View file

@ -0,0 +1,37 @@
--- a/README.md
+++ b/README.md
@@ -13,3 +13,7 @@
Normative releases should be promoted into a versioned top-level release
layout; `history/` remains reserved for superseded drafts.
+
+## InterfaceCanon boundary review
+
+See [InterfaceCanon boundary review](docs/interface-canon-boundary.md) for the draft proposal and review scope.
--- /dev/null
+++ b/docs/interface-canon-boundary.md
@@ -0,0 +1,24 @@
+# InterfaceCanon derivation boundary
+
+Status: draft review proposal. Review target: interface-canon draft 0.1.1 at
+`1fc82ec6655ed286cea3be284e33d08e7b27edc3`. Acceptance requires the FIAM owner's recorded review.
+
+InterfaceCanon translates FIAM interface terminology into a focused extension to
+InfoTechCanon. FIAM retains authority over standard semantics, Core schemas,
+controlled terms, profiles, policies, reference implementation, and conformance.
+
+The consumer pins FIAM v0.2 Draft 6 at commit
+`135326756913363b098bcdee791628b5e864b8be`, including retained Draft 1 explanation,
+frozen Core schema, and Canon. InterfaceCanon owns its derived presentation and
+cross-canon mappings; it does not issue a new FIAM conformance specification.
+
+Review the definitions and distinctions in interface-canon
+`infospace/models/interface/InterfaceCanonInterfaceModel.md`, especially
+contract versus binding; endpoint versus resource selector; channel versus retained
+resource; shape versus describing artifact versus representation; and
+assertion/source versus derived lens conclusions.
+
+Accept or correct the derivation and record reviewer identity and revision.
+Acceptance concerns fidelity and authority boundaries, not FIAM release promotion,
+consumer runtime conformance, or stable InterfaceCanon publication. The FIAM draft
+and its historical package layout remain unchanged by this proposal.

15
reviews/INTERFACE-WP-0004/info-tech-canon-request.md Normal file
View file

@ -0,0 +1,15 @@
# Review request: info-tech-canon
Recipient: `info-tech-canon` via Statehub. Status: prepared, not sent.
Please review the attached/referenced interface-canon patch
`reviews/INTERFACE-WP-0004/info-tech-canon.patch`, based on your commit `8eb1c83f2e119de57e7ad448b901381f8e92fb57`.
It adds `infospace/interfaces/interface-canon-boundary.md` and a README entry. The proposed source model is
interface-model 0.1.1 at `1fc82ec6655ed286cea3be284e33d08e7b27edc3`.
Please respond with acceptance or specific corrections, reviewer identity, and
reviewed source revision. If accepting and applying, include the peer commit.
Approval is limited to the documented boundary or adoption scope. This request
does not ask you to promote InterfaceCanon to stable or modify the historical
identity/commerce ownership ledger. Reply to interface-canon against
INTERFACE-WP-0004 (T01).

48
reviews/INTERFACE-WP-0004/info-tech-canon.patch Normal file
View file

@ -0,0 +1,48 @@
--- a/README.md
+++ b/README.md
@@ -146,3 +146,7 @@
[Published interface card](infospace/interfaces/federation.yaml) declares exports, imports, authority,
source-of-truth boundaries and reciprocal canon references.
+
+## InterfaceCanon boundary review
+
+See [InterfaceCanon boundary review](infospace/interfaces/interface-canon-boundary.md) for the draft proposal and review scope.
--- /dev/null
+++ b/infospace/interfaces/interface-canon-boundary.md
@@ -0,0 +1,35 @@
+# InterfaceCanon extension boundary
+
+Status: draft review proposal. Review target: interface-canon draft 0.1.1 at
+`1fc82ec6655ed286cea3be284e33d08e7b27edc3`. This document proposes a reciprocal boundary reference;
+acceptance requires the InfoTechCanon owner's recorded review.
+
+InterfaceCanon derives interface-domain terminology from the FIAM standard in
+facetted-interfaces and references shared InfoTechCanon concepts. It supplies a
+focused interface model rather than replacing InfoTechCanon shared roots.
+
+Reviewed imports: ITC-LAND, ITC-IDENT, ITC-EVID, ITC-GOV, ITC-DATA, ITC-INFOSPACE,
+and ITC-NET. Source commits and hashes are in the InterfaceCanon import manifest.
+
+Boundary dispositions for acceptance:
+
+- FIAM Port is contract participation, distinct from ITC-NET network Port.
+- InterfaceContract describes semantic interface behavior; it is not an exact
+ alias for all Landscape/Network Interface meanings.
+- FIAM Endpoint locates a Binding. Network Endpoint is related where realization
+ is network-based; local bindings need not have a network endpoint.
+- InformationResource/InformationShape map contextually to Data concepts;
+ Dataset, DataObject, Record, DataType, and Constraint keep their shared owners.
+- FIAM Representation concerns participation encoding; Data Representation also
+ describes value-level forms. The two scopes must remain qualified.
+- Describing artifacts may be KnowledgeArtifact and Evidence Source. An assertion
+ drawn from the source remains distinct from the source container.
+
+Review material: interface-canon `infospace/mappings/review-2026-09-09.md` and
+`infospace/models/interface/imports.json` at the revision above.
+
+This proposal does not extend the completed identity/commerce migration ledger,
+transfer shared ownership, or assert a reverse semantic dependency. Record accepted
+or corrected dispositions, reviewer identity, and review/merge revision before
+InterfaceCanon uses this document as acceptance evidence. Draft availability is
+not evidence that consumers have adopted the model.

15
reviews/INTERFACE-WP-0004/repo-manager-request.md Normal file
View file

@ -0,0 +1,15 @@
# Review request: repo-manager
Recipient: `repo-manager` via Statehub. Status: prepared, not sent.
Please review the attached/referenced interface-canon patch
`reviews/INTERFACE-WP-0004/repo-manager.patch`, based on your commit `5ad49dd79e0ebc2f46bf5df68d2c1a079dc358c7`.
It adds `docs/interface-canon-statehub-consumer.md` and a README entry. The proposed source model is
interface-model 0.1.1 at `1fc82ec6655ed286cea3be284e33d08e7b27edc3`.
Please respond with acceptance or specific corrections, reviewer identity, and
reviewed source revision. If accepting and applying, include the peer commit.
Approval is limited to the documented boundary or adoption scope. This request
does not ask you to promote InterfaceCanon to stable or modify the historical
identity/commerce ownership ledger. Reply to interface-canon against
INTERFACE-WP-0004 (T02).

47
reviews/INTERFACE-WP-0004/repo-manager.patch Normal file
View file

@ -0,0 +1,47 @@
--- a/README.md
+++ b/README.md
@@ -69,3 +69,7 @@
- [State Hub repo tooling research](history/2026-08-09-state-hub-repo-tooling-research.md)
- [Architecture blueprint (retirement path)](specs/ArchitectureBlueprint.md)
- Dual-run: [docs/dual-run.md](docs/dual-run.md) · [RMGR-WP-0002](workplans/RMGR-WP-0002-retirement-dual-run-strangler.md)
+
+## InterfaceCanon consumer terminology
+
+See [InterfaceCanon consumer terminology](docs/interface-canon-statehub-consumer.md) for the draft proposal and review scope.
--- /dev/null
+++ b/docs/interface-canon-statehub-consumer.md
@@ -0,0 +1,34 @@
+# Statehub projection interface terminology
+
+Status: draft adoption proposal for owner review. Canon reference:
+interface-canon `interface-model` 0.1.1 (draft), revision
+`1fc82ec6655ed286cea3be284e33d08e7b27edc3`. This adoption is limited to documenting the current
+Statehub synchronization interface; it adds no runtime dependency.
+
+The implementation remains authoritative in `src/repo_manager/projection_sync.py`.
+This is a transitional Statehub integration; it does not redefine Repo Manager's
+long-term hub-core boundary or change Statehub retirement plans.
+
+| InterfaceCanon concept | Repo Manager usage |
+| --- | --- |
+| Required Port / Interface Contract | Repository projection reconciliation client participation and semantic agreement to apply an exact pushed commit. |
+| Operation | ReconcileRepositoryProjection. |
+| Binding / Endpoint | JSON over configured HTTP API base, POST `/repos/{slug}/work-record-projection/reconcile`, idempotency/source-agent headers. |
+| Information Resource / Selector | Persisted work-record projection; repository slug scoped within Statehub. |
+| Request Information Shape | expected_commit, a normalized 40-hex SHA, and acknowledge_retirements, default false. |
+| Response Information Shape | Receipt with schema, instance identity, expected/derived commits, and outcome. |
+| Representation | JSON for request and receipt, independent of resource and shape identity. |
+| Channel | No separate exchange or mediation channel is established by this client; a local pending file is an artifact. |
+| Interaction Flow | Health check establishes primary identity before reconciliation POST. |
+
+The address and projection are distinct; queued intent is not successful provider
+execution. Missing TLS, HTTP-version, and gateway facts remain unknown.
+
+Evidence: the existing test
+`tests/test_fast_work_records.py::test_sync_uses_two_requests_and_exact_pushed_commit`
+checks the real client against MockTransport and a temporary Git remote. The
+InterfaceCanon worked example records provider source and schema pins separately.
+
+For adoption, the Repo Manager owner should review the mapping and record acceptance
+with reviewer identity and merge/review revision. Acceptance is for this documentation
+scope only, not blanket stable-canon approval or runtime FIAM conformance.

19
workplans/INTERFACE-WP-0004-federation-acceptance.md
View file

@ -4,7 +4,7 @@ type: workplan
title: "Establish external federation acceptance and consumer adoption"
domain: infotech
repo: interface-canon
status: proposed
status: active
owner: codex
topic_slug: canon
origin: residual
@ -24,7 +24,7 @@ plan records the remaining work without claiming control over peer backlogs.
```task
id: INTERFACE-WP-0004-T01
status: todo
status: wait
priority: medium
state_hub_task_id: "5111826f-b039-5fb3-a194-b5e00595c5b2"
```
@ -39,7 +39,7 @@ Done when accepted boundaries and their source records are recorded.
```task
id: INTERFACE-WP-0004-T02
status: todo
status: wait
priority: medium
state_hub_task_id: "b9c8cedd-9aa0-5243-b3b5-880a3f0da9c9"
```
@ -48,3 +48,16 @@ Use the Repo Manager example as review material; obtain a consumer-owned referen
or another concrete adoption record. Reassess model/card status against both tasks'
evidence and document the outcome. A local worked example alone is insufficient.
Validation: source pins, federation schema, and named acceptance/adoption evidence.
## Prepared review package — 2026-09-09
[Review package](../reviews/INTERFACE-WP-0004/README.md) contains three
owner-specific patches and exact request texts. Each patch passed
`git apply --check` against its target checkout. The completed migration project's
GOAL.md and README are pinned as evidence that its ledger is not a universal
registration gate for future canon extensions.
T01 and T02 remain waiting: review material is prepared, but no request has been
sent and no owner acceptance has been obtained. Next action is authorization to
send the three named Statehub requests, then record actual responses. Model/card
publication remains draft 0.1.1. No peer checkout was changed.