tegwick
6b33ac2388
Assistant: codex Assistant-Model: gpt-6-astra Assistant-Session: 01a087be-d842-7252-81be-2105c4279c87
47 lines
2.9 KiB
Diff
47 lines
2.9 KiB
Diff
--- a/README.md
|
|
+++ b/README.md
|
|
@@ -69,3 +69,7 @@
|
|
- [State Hub repo tooling research](history/2026-08-09-state-hub-repo-tooling-research.md)
|
|
- [Architecture blueprint (retirement path)](specs/ArchitectureBlueprint.md)
|
|
- Dual-run: [docs/dual-run.md](docs/dual-run.md) · [RMGR-WP-0002](workplans/RMGR-WP-0002-retirement-dual-run-strangler.md)
|
|
+
|
|
+## InterfaceCanon consumer terminology
|
|
+
|
|
+See [InterfaceCanon consumer terminology](docs/interface-canon-statehub-consumer.md) for the draft proposal and review scope.
|
|
--- /dev/null
|
|
+++ b/docs/interface-canon-statehub-consumer.md
|
|
@@ -0,0 +1,34 @@
|
|
+# Statehub projection interface terminology
|
|
+
|
|
+Status: draft adoption proposal for owner review. Canon reference:
|
|
+interface-canon `interface-model` 0.1.1 (draft), revision
|
|
+`1fc82ec6655ed286cea3be284e33d08e7b27edc3`. This adoption is limited to documenting the current
|
|
+Statehub synchronization interface; it adds no runtime dependency.
|
|
+
|
|
+The implementation remains authoritative in `src/repo_manager/projection_sync.py`.
|
|
+This is a transitional Statehub integration; it does not redefine Repo Manager's
|
|
+long-term hub-core boundary or change Statehub retirement plans.
|
|
+
|
|
+| InterfaceCanon concept | Repo Manager usage |
|
|
+| --- | --- |
|
|
+| Required Port / Interface Contract | Repository projection reconciliation client participation and semantic agreement to apply an exact pushed commit. |
|
|
+| Operation | ReconcileRepositoryProjection. |
|
|
+| Binding / Endpoint | JSON over configured HTTP API base, POST `/repos/{slug}/work-record-projection/reconcile`, idempotency/source-agent headers. |
|
|
+| Information Resource / Selector | Persisted work-record projection; repository slug scoped within Statehub. |
|
|
+| Request Information Shape | expected_commit, a normalized 40-hex SHA, and acknowledge_retirements, default false. |
|
|
+| Response Information Shape | Receipt with schema, instance identity, expected/derived commits, and outcome. |
|
|
+| Representation | JSON for request and receipt, independent of resource and shape identity. |
|
|
+| Channel | No separate exchange or mediation channel is established by this client; a local pending file is an artifact. |
|
|
+| Interaction Flow | Health check establishes primary identity before reconciliation POST. |
|
|
+
|
|
+The address and projection are distinct; queued intent is not successful provider
|
|
+execution. Missing TLS, HTTP-version, and gateway facts remain unknown.
|
|
+
|
|
+Evidence: the existing test
|
|
+`tests/test_fast_work_records.py::test_sync_uses_two_requests_and_exact_pushed_commit`
|
|
+checks the real client against MockTransport and a temporary Git remote. The
|
|
+InterfaceCanon worked example records provider source and schema pins separately.
|
|
+
|
|
+For adoption, the Repo Manager owner should review the mapping and record acceptance
|
|
+with reviewer identity and merge/review revision. Acceptance is for this documentation
|
|
+scope only, not blanket stable-canon approval or runtime FIAM conformance.
|