From ccf691042da6f3542138cf6125bc6fbfc3438f42 Mon Sep 17 00:00:00 2001 From: tegwick Date: Sat, 5 Sep 2026 11:27:21 +0200 Subject: [PATCH] docs: complete retirement inbox parity gate and track reader cutover Assistant: codex Assistant-Model: gpt-6-astra Assistant-Session: 01a06ed7-828d-7ca0-a8d4-0c3e5a0c4102 --- .../statehub-inbox-pilot-20260905.json | 116 ++++++++++++++++++ .../evidence/statehub-inbox-pilot-20260905.md | 38 ++++++ docs/retirement-cutover-slice-plan.md | 22 ++-- .../STATE-WP-0079-retirement-strangler.md | 37 ++++-- 4 files changed, 194 insertions(+), 19 deletions(-) create mode 100644 docs/evidence/statehub-inbox-pilot-20260905.json create mode 100644 docs/evidence/statehub-inbox-pilot-20260905.md diff --git a/docs/evidence/statehub-inbox-pilot-20260905.json b/docs/evidence/statehub-inbox-pilot-20260905.json new file mode 100644 index 0000000..185b3e8 --- /dev/null +++ b/docs/evidence/statehub-inbox-pilot-20260905.json @@ -0,0 +1,116 @@ +{ + "date": "2026-09-05", + "scope": "frozen-source-snapshot; no production reader switch", + "source": "state-hub/primary/railiance01", + "captured_at": "2026-09-05T08:38:37.982640+00:00", + "owner_commit": "6fb5ce2", + "package_enable_commit": "6972db5", + "image_digest": "sha256:a3461c0da805ef2b58caa0c862be3dc6562abcca186300d1257df9b96569b4c0", + "endpoint": "GET /ports/projections/statehub-inbox", + "import": { + "runs": [ + { + "status": "validated", + "count": 20, + "content_hash": "f952b1fb46469f43bbf8ec7de1041a6feae943708c3496d8b55287428e6ed60d" + }, + { + "status": "applied", + "count": 20, + "content_hash": "f952b1fb46469f43bbf8ec7de1041a6feae943708c3496d8b55287428e6ed60d" + }, + { + "status": "noop", + "count": 20, + "content_hash": "f952b1fb46469f43bbf8ec7de1041a6feae943708c3496d8b55287428e6ed60d" + } + ], + "target_hash": "f952b1fb46469f43bbf8ec7de1041a6feae943708c3496d8b55287428e6ed60d", + "source_count": 20 + }, + "parity": { + "source_count": 20, + "snapshot_hash": "f952b1fb46469f43bbf8ec7de1041a6feae943708c3496d8b55287428e6ed60d", + "cases": [ + { + "params": {}, + "count": 19, + "content_hash": "1b3d5beff1d081bec7c552d0c463ffe48999bd75caf5bae1189e421651467295", + "mode": "snapshot-pilot", + "parity": true + }, + { + "params": { + "unread_only": "true" + }, + "count": 0, + "content_hash": "4f53cda18c2baa0c0354bb5f9a3ecbe5ed12ab4d8e11ba873c2f11161202b945", + "mode": "snapshot-pilot", + "parity": true + }, + { + "params": { + "from_agent": "activity-core" + }, + "count": 8, + "content_hash": "a6fb59f2a35ecc7c9c445bbcd1056955828062179ee52b2c15f497ea76a5656a", + "mode": "snapshot-pilot", + "parity": true + }, + { + "params": { + "from_agent": "missing-pilot-sender" + }, + "count": 0, + "content_hash": "4f53cda18c2baa0c0354bb5f9a3ecbe5ed12ab4d8e11ba873c2f11161202b945", + "mode": "snapshot-pilot", + "parity": true + }, + { + "params": { + "limit": "1" + }, + "count": 1, + "content_hash": "84a3d3ea5eb407629009eef7440fca14219be63486ab7d61b7e1f2d44adc3bba", + "mode": "snapshot-pilot", + "parity": true + }, + { + "params": { + "limit": "1000" + }, + "count": 19, + "content_hash": "1b3d5beff1d081bec7c552d0c463ffe48999bd75caf5bae1189e421651467295", + "mode": "snapshot-pilot", + "parity": true + } + ], + "no_auth": 401, + "bad_auth": 401, + "post": 405, + "scope": "frozen-source-snapshot" + }, + "live_source_check": { + "live_source_api_count": 19, + "live_source_api_hash": "1b3d5beff1d081bec7c552d0c463ffe48999bd75caf5bae1189e421651467295", + "frozen_inbox_hash": "1b3d5beff1d081bec7c552d0c463ffe48999bd75caf5bae1189e421651467295", + "matches_frozen": true + }, + "transport_from_state_hub_without_token": 401, + "rollback": { + "configuration_revision": 25, + "rollback_revision": 27, + "readyz": 200, + "disabled_inbox": 404, + "restored_revision": 28, + "parity_repeated": true + }, + "checks": { + "hub_core_tests_passed": 116, + "packaging_tests_passed": 11, + "helm_lint": "passed", + "server_dry_run": "passed", + "family_validation": "14 declarations, 0 errors, 1 existing reef-railiance warning", + "verify_live": "passed" + } +} diff --git a/docs/evidence/statehub-inbox-pilot-20260905.md b/docs/evidence/statehub-inbox-pilot-20260905.md new file mode 100644 index 0000000..6c22dc4 --- /dev/null +++ b/docs/evidence/statehub-inbox-pilot-20260905.md @@ -0,0 +1,38 @@ +# Private State Hub inbox snapshot pilot — 2026-09-05 + +T08 receiving-readiness proof is complete. Hub Core exposes the authenticated, +GET-only `/ports/projections/statehub-inbox` for the literal `state-hub` inbox. +It is private, default-disabled in the chart, and enabled in the current private +production package. State Hub remains the writer; no production reader switched. + +A consistent source transaction captured 20 historical rows (including archived +rows and thread closure) at 08:38:37.982640 UTC. Import preserved identities, +timestamps and flags; validation, apply, identical replay/no-op and target hash +all agree. The visible inbox contains 19 rows. Six read cases match ordered IDs +and normalized whole-record hashes, covering unread/sender filters and limits. +The live source inbox also matched the frozen oracle at verification time. +Bodies and credentials are excluded from this evidence. + +Missing/bad authentication returns 401; POST returns 405. Scoped NetworkPolicy +admission now permits State Hub API pods to reach the authenticated boundary. +The prior prefix-only probe overlooked existing `/ports/messaging/messages`, +`/ports/events/progress` and named projection ports. Those native envelopes do +not by themselves establish State Hub history/read/archive compatibility. + +Image source is `hub-core@6fb5ce2`; package enablement is +`rapp-core-hub@6972db5`. Exact digest and content hashes are in the adjacent JSON. +Helm revision 25 installed the image with the pilot disabled; revision 26 enabled +it after import. Rollback to configuration 25 produced revision 27, readiness +200 and pilot 404. Roll-forward to revision 28 passed the same parity cases and +`make verify-live`. No State Hub image or writer configuration changed. + +Validation: 116 owner tests, 11 packaging tests, Helm lint and server dry-run +passed. Family validation passed 14 declarations with zero errors and one +pre-existing reef-railiance warning. The rmgr wrapper lacked jsonschema; the +same family validator succeeded with the State Hub virtualenv interpreter. + +Residual **HUB-WP-0011**, tracked by **STATE-WP-0079-T09**, owns ongoing monotonic +freshness/staleness, caller-specific credentials, canonical/alias scope and a +reviewed production reader switch. The operator-authenticated frozen pilot must +not be presented as a fresh inbox. B2/B3 migration and message-writer cutover +remain open; this proof does not retire those families. diff --git a/docs/retirement-cutover-slice-plan.md b/docs/retirement-cutover-slice-plan.md index 71b8257..092f226 100644 --- a/docs/retirement-cutover-slice-plan.md +++ b/docs/retirement-cutover-slice-plan.md @@ -32,8 +32,8 @@ No new permanent receiving authority belongs in State Hub during retirement. | A4 work/repo UI / 22 | hub-core projection + UI clients; RMGR-ADR-003 excludes a Repo Manager dashboard | No complete State Hub UI redirect receipt established | First prove backing reads; rollback redirects to the retained UI | | A5 topic spine / 8 | Published Repo Manager classification contract, accepted by HUB-WP-0004 | No complete State Hub caller-switch receipt established | Prove deployed consumer contract and parity; retain source-backed classification projection | | B1 catalogs / 34 | HUB-WP-0004/0005 receiving architecture and `/api/v2` absorption | Completion covers the Core Hub route groups, not every State Hub capability/registry route | Map each State Hub catalog to a deployed endpoint and migration receipt | -| B2 messaging/interface log / 22 | Shared `hub_core.routers.messages` exists; State Hub interface log is a separate family | Live Hub Core OpenAPI has **no `/messages` or `/interface-changes`**. `/api/v2/interaction-events` exists but is not asserted equivalent | **Next bounded read slice:** STATE-WP-0079-T08. Owner must expose/identify the message read contract and history projection before a parity run or switch. Retain current reads/writer | -| B3 telemetry / 32 | Shared `hub_core.routers.progress` exists; token/software catalogs need separate mappings | Live Hub Core OpenAPI has **no `/progress` or `/token-events`** | Owner runtime assembly/mapping plus historical identity/count parity; writer exclusivity and rollback receipts remain necessary | +| B2 messaging/interface log / 22 | Native `/ports/messaging/messages` uses a distinct envelope; new authenticated `/ports/projections/statehub-inbox` preserves bounded State Hub history | T08 complete: 20-row import, six parity cases, private transport and disable/re-enable proof; no production reader switched | T09 / HUB-WP-0011: freshness, caller credentials and aliases before one reader switch. Interface log and writer cutover remain separate | +| B3 telemetry / 32 | Native `/ports/events/progress` exists; token/software catalogs need separate mappings | Literal `/progress` and `/token-events` absence does not imply no native receiving contract | Map native semantics and historical identity/count parity; writer exclusivity and rollback receipts remain necessary | | B4 projection/policy / 20 | HUB-WP-0004/0005; policy publication belongs to policy-nexus | State Hub still serves its projection routes; no full family receipt established | Map individual projections and policy publication; retain source/runtime boundaries and current reads | | B5 hub UI / 17 | Hub Core runtime/console exists | Core Hub absorption does not establish replacement of State Hub dashboard pages | Prove A4/B1–B4 data contracts before redirect; retain UI rollback | | C1 execution / 13 | ACTIVITY-WP-0029 finished; Activity Core owns scheduling/ops_run | STATE-WP-0079 records launch-request rejection (410), replacement semantics, and corrected unconsumed requests | Verify every remaining execution caller uses the owner contract. Do not revive the obsolete launch queue for rollback | @@ -54,11 +54,10 @@ No new permanent receiving authority belongs in State Hub during retirement. - Direct Nexus `/sbom/report/licences/` and `/sbom/snapshots/` returned 200 from the State Hub pod. Their State Hub meter entries are now retired. This does **not** delete the compatibility handlers or historical data. -- Hub Core candidate runtime OpenAPI, read from its own pod loopback, has 31 - paths and lacks the four State Hub families identified above. The State Hub - pod's probes to both Core Hub service addresses were connection-refused; - the deployments reported 1/1 ready. Transport readiness must be resolved as - part of any proxy-based pilot; this review did not diagnose its cause. +- The earlier literal-prefix probe missed existing native messaging, event and + projection ports. The bounded inbox projection now has live parity evidence. + Scoped NetworkPolicy admission resolved State Hub-to-candidate transport; + unauthenticated requests from the source pod now reach the 401 boundary. - Session trace identifies ad-hoc legacy task reads in fluid-telegram and ops-warden. Their corrected canonical queries return 200 with 8 and 5 tasks. No evidence identifies the other historical callers yet. @@ -71,11 +70,10 @@ Evidence: `docs/evidence/STATE-WP-0079-sbom-retirement-20260905.json` and 1. T07: observe the remaining legacy readers with component attribution. The known caller repositories and bundled State Hub skill now prescribe canonical reads. Preserve the quiet clocks; do not exercise legacy URLs to test them. -2. T08: obtain one **deployed message-read contract** from hub-core, including - access/transport and historical projection. Use the State Hub inbox reader as - the bounded parity client. Compare message IDs and read/archive flags against - one consistent snapshot; do not change message writes during this proof. - Only after parity and rollback evidence should a concrete reader switch run. +2. T09 / HUB-WP-0011: establish monotonic freshness and stale-source behavior, + caller-specific credentials and canonical/alias scope before one production + inbox reader switch. T08's frozen snapshot parity and rollback are complete; + see `docs/evidence/statehub-inbox-pilot-20260905.md` and JSON receipt. 3. RAIL-FAB-WP-0028-T01 remains the owner decision for runtime, persistent store, auth, backup/restore and deployment repository. Its T02–T04 deliver deployment, freshness and final direct-consumer receipts; no new Fabric authority here. diff --git a/workplans/STATE-WP-0079-retirement-strangler.md b/workplans/STATE-WP-0079-retirement-strangler.md index c0cceba..97b27a2 100644 --- a/workplans/STATE-WP-0079-retirement-strangler.md +++ b/workplans/STATE-WP-0079-retirement-strangler.md @@ -604,18 +604,16 @@ an `unknown` bucket alone is sufficient to assign an owner. ```task id: STATE-WP-0079-T08 -status: todo +status: done priority: high state_hub_task_id: "9d508739-6123-5204-b829-750b3ebf0e63" ``` Receiving owner: hub-core; State Hub owns source/caller evidence under T04. -The live receiver's 31-path OpenAPI has no message/progress/token/interface-log -families. Identify or assemble the owner message-read contract, auth/transport, -and historical projection in the receiving runtime. State Hub-to-owner service -probes were connection-refused in this review; diagnose the actual transport -before assuming a usable proxy path. Do not substitute `/api/v2/interaction-events` -without an explicit semantic mapping. +The initial prefix-only probe overlooked the existing native +`/ports/messaging/messages` and `/ports/events/progress` contracts. Their +semantics differ from State Hub message history. The owner supplies the bounded +inbox projection; scoped NetworkPolicy admission resolves source-pod transport. Then run a bounded read-only inbox parity pilot over one consistent snapshot, checking message IDs, ordering, read/archive flags and scope filters; record @@ -624,6 +622,31 @@ readiness and parity/rollback receipts make one concrete reader switch reviewabl Production message writers stay unchanged during this proof. Related owners: HUB-WP-0004/0005; the full B2/B3 route migration is not implied by this task. +**Result (2026-09-05):** HUB-WP-0010 and RAPPCOREHUB-WP-0004 delivered +and deployed the private snapshot reader. Twenty imported rows retain the source +hash; six filter/order/content parity cases passed, with 19 visible inbox rows. +Authentication and method rejection passed. Disable/re-enable was rehearsed +(Helm revisions 27/28); the restored reader passed parity and live verification. +Evidence: `docs/evidence/statehub-inbox-pilot-20260905.md` and JSON receipt. +Ongoing freshness, caller credentials and alias handling remain explicit owner +residual HUB-WP-0011 and T09; no production client or writer switched. + +## Gate the production inbox reader switch + +```task +id: STATE-WP-0079-T09 +status: wait +priority: high +``` + +Owner handoff: HUB-WP-0011 (`origin: residual`, `origin_ref: HUB-WP-0010`). +T08 proves a frozen snapshot, not ongoing freshness or a production client +switch. Wait for the owner's monotonic refresh/staleness contract, caller-specific +credential delivery and canonical/alias scope semantics. Then review one client +switch and rollback using current source parity. State Hub remains the message +writer throughout this read cutover. The private snapshot reader must not be +advertised as a fresh production inbox. + ## Acceptance - [x] Freeze policy documented