tegwick
84df076e95
Assistant: codex Assistant-Model: gpt-6-astra Assistant-Session: 01a087d8-d22d-7d11-8169-bf22a729dff1
60 lines
3.9 KiB
Markdown
60 lines
3.9 KiB
Markdown
# 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.
|