repo-manager/docs/interface-canon-statehub-consumer.md

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 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.