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

Complete interface mapping review and Repo Manager consumer proof

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:15:24 +02:00
parent dd6cdd7f83
commit b5aeeb940b
18 changed files with 357 additions and 28 deletions
Download patch file Download diff file Expand all files Collapse all files

56
infospace/examples/repo-manager-statehub.md Normal file
View file

@ -0,0 +1,56 @@
# 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.
It proves that the vocabulary can describe the consumer; it does not assert that
Repo Manager has adopted this canon or published a reciprocal card.
| 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 semantic ports, not TCP port numbers. |
| 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 and reciprocal acceptance are tracked in INTERFACE-WP-0004.