coulomb/repo-manager
4
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Adopt reviewed InterfaceCanon projection terminology

Browse source 
Assistant: codex
Assistant-Model: gpt-6-astra
Assistant-Session: 01a087d8-d22d-7d11-8169-bf22a729dff1
This commit is contained in:
tegwick 2026-09-09 22:42:31 +02:00
parent 3db3e7e297
commit 84df076e95
4 changed files with 123 additions and 1 deletions
Download patch file Download diff file Expand all files Collapse all files

60
docs/interface-canon-statehub-consumer.md Normal file
View file

@ -0,0 +1,60 @@
# State Hub projection interface terminology
Status: accepted for Repo Manager documentation by codex on 2026-09-09.
Reviewed proposal: InterfaceCanon package
`6b33ac2388190207c4373e6f288922ce5c0b0413`,
`reviews/INTERFACE-WP-0004/repo-manager.patch`, against interface-model 0.1.1
(draft), revision `1fc82ec6655ed286cea3be284e33d08e7b27edc3`.
This adoption documents the existing State Hub synchronization interface. It
adds no runtime dependency and leaves the repository-authority and long-term
hub-core boundaries in [INTENT.md](../INTENT.md) unchanged. Acceptance applies
to this mapping only; it does not promote the draft canon or assert runtime
FIAM conformance.
| InterfaceCanon concept | Repo Manager usage |
| --- | --- |
| Required Port / Contract Participation | The client requires the repository projection reconciliation contract. Requires describes participation, not message direction. |
| Interface Contract | Reconcile a repository's work-record projection from its exact pushed Forge commit. |
| Operation | ReconcileRepositoryProjection. |
| Binding | JSON over the configured HTTP API base, with `Idempotency-Key` and `X-StateHub-Source-Agent` request headers. |
| Endpoint | API base plus POST `/repos/{slug}/work-record-projection/reconcile`. |
| Information Resource | The repository's persisted work-record projection in State Hub. |
| Resource Selector | Repository slug scoped within the State Hub repository registry. |
| Request Information Shape | `expected_commit` and `acknowledge_retirements`, default false. The provider validates a full 40-hex SHA and normalizes it to lowercase. |
| Response Information Shape | Provider receipt containing schema, instance identity, expected/derived commits, and outcome. The provider returns a dictionary without a dedicated response model. |
| Representation | JSON for request and receipt participation, distinct from the resource and shape. |
| Channel | This client establishes no separate exchange or mediation channel; its local pending file is an artifact. |
| Interaction Flow | Git and identifier preflight, followed by primary health verification and reconciliation POST. Git push is a prerequisite with a separate integration. |
The client checks the health response for role `primary` and, by default,
label `railiance01`. The provider independently checks its primary role and
compares the derived Forge commit with the expected commit before applying the
projection. The client reads the receipt's outcome; it does not independently
validate the full receipt schema or compare its commit fields. Sending the
idempotency header alone does not prove provider deduplication behavior.
Queued intent is pending local evidence, not successful provider execution.
TLS, HTTP-version, authentication, and gateway properties are not established
by this mapping.
## Review evidence
- Consumer: `src/repo_manager/projection_sync.py`, Repo Manager revision
`3db3e7e2976f916446cf2358686af37ce61f7fed`.
- Provider: `api/routers/work_record_projection.py` and
`api/schemas/work_record_projection.py`, State Hub revision
`ccb285fc40d66125e485723fda851bbf75b90d14`.
- Vocabulary: `infospace/models/interface/InterfaceCanonInterfaceModel.md`
at the pinned InterfaceCanon revision above. Later model 0.1.2 clarifies the
network-port distinction; this review retains the requested 0.1.1 pin.
- Existing tests in `tests/test_fast_work_records.py` exercise the actual
client with MockTransport and temporary Git remotes, including exact pushed
commit requests, dirty-source refusal, and queuing on the wrong instance.
Mock responses establish client behavior; provider behavior was reviewed
separately in the pinned source files.
Review disposition: accepted with the distinctions and implementation limits
above. The applying commit is discoverable with
`git log --diff-filter=A --format=%H -- docs/interface-canon-statehub-consumer.md`.
Tracked locally in RMGR-WP-0016 and externally in INTERFACE-WP-0004-T02.