interface-canon/infospace/examples/repo-manager-statehub.md

# Consumer proof: Repo Manager → Statehub

Consumer: `repo-manager`, function `sync_repository_projection` in
`src/repo_manager/projection_sync.py`. Provider: `state-hub`, router
`api/routers/work_record_projection.py`. Exact revisions and hashes are retained
in the [consumer source manifest](../reviews/2026-09-09/repo-manager-sources.json)
and [provider source manifest](../reviews/2026-09-09/state-hub-sources.json).

This is a source-based application of InterfaceCanon to an existing integration.
The initial example proved the vocabulary could describe the consumer. Repo
Manager has since accepted this documentation mapping in a
[pinned owner record](../reviews/acceptance/repo-manager-sources.json). Adoption
is limited to this interface description and reviewed model 0.1.1.

| Concept | Concrete interpretation | Source evidence |
| --- | --- | --- |
| System nodes | Repo Manager client and primary Statehub API | Consumer client construction and provider primary-role check. |
| Ports / participations | Client requires repository-projection contract; Statehub offers it | Client POST and matching provider router. These are FIAM contract-participation ports, distinct from both physical/device and protocol-level transport network ports. |
| Interface Contract | Reconcile a repository's work-record projection from an exact pushed Forge commit | Provider compares derived commit with expected_commit before reset. |
| Operation | ReconcileRepositoryProjection | POST `/repos/{slug}/work-record-projection/reconcile`. HTTP method/path realizes the semantic operation. |
| Binding | JSON over the configured HTTP API base with idempotency and source-agent headers | `httpx.Client`, `json=`, `Idempotency-Key`, `X-StateHub-Source-Agent`. No HTTP version or TLS property is inferred. |
| Endpoint | Configured API locator plus reconciliation route; local example `http://127.0.0.1:8000/repos/interface-canon/work-record-projection/reconcile` | `api_base` and the interpolated route. Loopback is host-relative; deployment routing is unknown from this code. |
| Channel | No separate exchange/mediation locus established by this direct API exchange | No broker/topic declared in this consumer. A pending JSON file is not evidence of a messaging Channel. |
| Information Resource | Statehub's derived work-record projection for the repository selected by slug | `reset_repository_projection` and the snapshot route. The projected state persists independently of one interaction. |
| Resource Selector | Repository slug, scoped within the Statehub repository registry | Router `slug` parameter. Its presence in an HTTP path does not make the resource identical to its endpoint. |
| Request Information Shape | Expected commit and retirement acknowledgement | `RepositoryProjectionReconcile`: 40-hex SHA, normalized to lowercase, acknowledgement defaults false. |
| Response Information Shape | Reconciliation receipt with schema, instance identity, expected/derived commits, outcome | Provider's returned dictionary. Response lacks a dedicated Pydantic response model; do not invent one. |
| Representation | JSON for the request/receipt participation | `json=` and `response.json()`. JSON is neither the projection resource nor its semantic shape. |
| Artifacts | Client source, router source, and Pydantic request schema source | Describing/implementing artifacts pinned independently of their modeled contract and shapes. |
| Interaction Flow | Verify primary health, then request reconciliation | GET `/state/health` precedes the POST. Git push is a prerequisite with its own integration, not part of the HTTP binding. |
| Interaction outcome | Applied/noop, queued locally, rejected, or unavailable | Consumer branches on role/network errors and receipt outcome. Queued is pending intent, not a successful provider interaction. |

## Verification and limits

The existing consumer test
`tests/test_fast_work_records.py::test_sync_uses_two_requests_and_exact_pushed_commit`
executes the actual client with MockTransport and a temporary Git remote. It
checks the health→reconcile path sequence, use of the pushed commit, and applied
result. The test ran successfully during this review. The provider route and
request shape were also read at the pinned revisions; mock success alone would
not establish provider behavior.

Boundary acceptance cases:

- The URL and repository projection refer to different concepts: Binding locator
  versus persistent projected resource.
- A pending file is an artifact of a deferred request; it supplies no broker,
  topic, or delivery-semantics evidence from which to infer a Channel.
- JSON describes encoding; the request constraint requires a 40-hex commit.
- A mocked applied result validates the client flow; production application is
  evidenced separately by the actual Statehub sync receipt at session close.
- Missing TLS/HTTP-version/gateway facts remain unknown. They do not require new
  Core entities or a fabricated exact communication stack.

Unresolved implementation detail: the response shape is implied by provider code
rather than a dedicated response schema. That limits machine contract checking,
not the ability to model the exchange. No provider change is required by this
review. Consumer adoption is now recorded in INTERFACE-WP-0004-T02;
InfoTechCanon boundary acceptance is recorded in completed T01.

## Consumer-owned review clarification

The consumer checks health identity and reads the receipt outcome. It does not
independently validate the full receipt schema or compare returned commit fields;
the provider enforces equality with the derived Forge commit. The presence of an
Idempotency-Key header alone does not prove provider deduplication behavior.
Authentication, TLS, HTTP-version, and gateway properties remain unestablished by
this mapping. These limits match the committed Repo Manager acceptance record.

## InfoTechCanon clarification checks

Apply the [accepted mappings](../mappings/upstream.md) to this same integration:

- **Port and Interface:** the client requires a semantic contract. A host NIC
  attachment and a TCP transport port describe network realization, not that
  participation. Neither implies a second semantic contract.
- **Endpoint and resource:** the configured API locator reaches the Binding;
  the repository slug selects persisted projection state. This HTTP example
  cannot establish that every possible FIAM Binding has a Network Endpoint.
- **Resource and shape:** projected work records constitute addressed state;
  the request's field constraints describe admissible input. Dataset, Record,
  DataType, and Constraint are contextual ITC mappings, not blanket replacements.
- **Representation:** the request uses JSON encoding. `acknowledge_retirements`
  has a boolean value form. These representation scopes are compatible but
  distinct; neither the field's false value nor its JSON bytes is a new shape.
- **Artifact and knowledge:** the schema source can describe reusable interface
  knowledge. The client implementation is a FIAM Artifact implementing behavior;
  that role alone does not classify it as KnowledgeArtifact.
- **Evidence:** the pinned provider schema Git blob is an addressable Evidence
  Source with a version. For the explicit interest “which commit references can
  the request accept?”, the assertion “expected_commit accepts a full 40-hex SHA”
  is separate Evidence, located at `RepositoryProjectionReconcile.validate_commit`.
  A future mutable schema page would additionally need a version or capture.

These are meaning checks for the existing example, not new implementation facts,
FIAM wire records, or an assertion of complete cross-canon equivalence.