coulomb/state-hub
4
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

docs: complete retirement inbox parity gate and track reader cutover

Browse source 
Assistant: codex
Assistant-Model: gpt-6-astra
Assistant-Session: 01a06ed7-828d-7ca0-a8d4-0c3e5a0c4102
This commit is contained in:
tegwick 2026-09-05 11:27:21 +02:00
parent 2c60e5bcf7
commit ccf691042d
4 changed files with 194 additions and 19 deletions
Download patch file Download diff file Expand all files Collapse all files

116
docs/evidence/statehub-inbox-pilot-20260905.json Normal file
View file

@ -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"
}
}

38
docs/evidence/statehub-inbox-pilot-20260905.md Normal file
View file

@ -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.

22
docs/retirement-cutover-slice-plan.md
View file

@ -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.

37
workplans/STATE-WP-0079-retirement-strangler.md
View file

@ -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