diff --git a/README.md b/README.md index 1f2e7a6..d0f8ca5 100644 --- a/README.md +++ b/README.md @@ -27,6 +27,7 @@ Architecture: - [Railiance app deployment guide](docs/RailianceAppDeploymentGuide.md) (`RMGR-WP-0006`) - [Repository standards v0.1](docs/repository-standards_v0.1.md) (`RMGR-WP-0004`) - [Repository registers v0.1](docs/repository-registers_v0.1.md) (`RMGR-WP-0008`) +- [InterfaceCanon consumer terminology](docs/interface-canon-statehub-consumer.md) ```bash make install # or: uv pip install -e ".[dev]" diff --git a/docs/interface-canon-statehub-consumer.md b/docs/interface-canon-statehub-consumer.md new file mode 100644 index 0000000..48c4cb1 --- /dev/null +++ b/docs/interface-canon-statehub-consumer.md @@ -0,0 +1,60 @@ +# 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. diff --git a/intakes/intakes.md b/intakes/intakes.md index 18f825a..5b3a54b 100644 --- a/intakes/intakes.md +++ b/intakes/intakes.md @@ -37,8 +37,19 @@ description: Before any new workplan is allocated under WHYNOT-WP, OPS-WP, or RE finished/archived files remain frozen. Re-run rmgr prefix-uniqueness and identifier preflight after assignment. created: '2026-08-21T20:34:42.177493+00:00' -updated: '2026-08-21T20:34:42.177493+00:00' +updated: '2026-09-09T20:42:09.617881Z' state_hub_intake_id: "01a02611-a663-7712-bd4b-e39c13e7bf20" +notes: + - content: >- + 2026-09-09 review: the registry already assigns WHYNOT-WP to whynot-design, + WNCTL-WP to whynot-control, OPS-WP to ops-hub, and BRIDGE-WP to ops-bridge. + Fleet prefix scan reports no sharing or reused identifiers for these + prefixes. However whynot-control/AGENTS.md still advertises WHYNOT-WP, + despite its WNCTL-WP workplan files. Align that repository's instructions + before its next allocation. REPO-WP remains unassigned in the registry. Current instructions advertise + CORE-WP for core-hub, DISCTL-WP for disaster-control, and REPO-WP for + repo-seed; finalize these registry assignments before reuse. + author: codex ``` ## RMGR-IN-0003 — Scope normal sync identity validation to actionable records diff --git a/workplans/RMGR-WP-0016-interface-canon-consumer-review.md b/workplans/RMGR-WP-0016-interface-canon-consumer-review.md new file mode 100644 index 0000000..eaea7d7 --- /dev/null +++ b/workplans/RMGR-WP-0016-interface-canon-consumer-review.md @@ -0,0 +1,50 @@ +--- +id: RMGR-WP-0016 +type: workplan +title: "Review and adopt InterfaceCanon projection terminology" +domain: infotech +repo: repo-manager +status: finished +owner: codex +topic_slug: infotech +created: "2026-09-09" +updated: "2026-09-09" +state_hub_workstream_id: "90035068-b251-5fb3-945d-ab2f5f3b1a37" +--- + +Origin: InterfaceCanon review request f3c2e50c-0d66-4567-9ac3-c428d40fc333, +INTERFACE-WP-0004-T02. User continuation authorizes the repository review. + +## Review the proposal against the implementation + +```task +id: RMGR-WP-0016-T01 +status: done +priority: medium +state_hub_task_id: "ec407152-d5a6-5c85-b433-a78c9bd900d4" +``` + +Read the requested model 0.1.1 revision and proposal package, current client, +provider router/request schema, and client tests. Accept the documentation +mapping with separate participation, contract, binding, endpoint, resource, +and selector descriptions. Attribute SHA normalization to the provider and +state the client's limited receipt validation. No runtime changes. + +## Publish the reviewed consumer documentation + +```task +id: RMGR-WP-0016-T02 +status: done +priority: medium +state_hub_task_id: "08c20711-75ae-51be-90bb-33f2976eef4c" +``` + +Add docs/interface-canon-statehub-consumer.md and a README link. Record codex +as reviewer and exact model, proposal, consumer, and provider source revisions. +Run the existing client tests and synchronize the applying commit. External +acceptance aggregation remains with INTERFACE-WP-0004-T02; no message delivery +is claimed by this local review. + +Validation: all seven existing fast-work-record client tests passed. Markdown +links and source pins checked; git diff --check passed. No implementation +residuals. External aggregation is already live in INTERFACE-WP-0004-T02.