hub-core/workplans/HUB-WP-0011-statehub-inbox-freshness-and-cutover.md

---
id: HUB-WP-0011
type: workplan
title: "State Hub inbox freshness and reader cutover"
domain: infotech
repo: hub-core
status: blocked
flavor: residual
owner: codex
topic_slug: infotech
created: "2026-09-05"
updated: "2026-09-27"
origin: residual
origin_ref: HUB-WP-0010
related:
  - STATE-WP-0079
  - RAPPCOREHUB-WP-0004
state_hub_workstream_id: "3c8034fc-fd90-58f5-99bc-99b4f93e5ee1"
---

## Establish ongoing inbox freshness

```task
id: HUB-WP-0011-T01
status: todo
flavor: residual
priority: high
state_hub_task_id: "588e4b58-4694-513c-8e7a-1fab38fb6ce3"
```

The deployed inbox reader is an explicitly labeled one-time snapshot pilot.
Define and implement monotonic source revision/cursor semantics, atomic refresh,
read/archive updates, deletes/retention treatment and stale-source signaling.
The initial importer deliberately refuses different existing rows; do not turn
it into an unconditional overwrite loop. Prove recovery and idempotency without
creating a second message writer. Decide the source/destination ownership
boundary before live client traffic moves.

Loose-ends review 2026-09-27: left `todo`, not implemented in this pass. This
task's own scope calls for a source/destination ownership boundary decision —
who is authoritative for a message once both State Hub and hub-core hold a
copy, and what "deletes/retention treatment" means for messages State Hub no
longer serves (archive locally, tombstone, or refuse) — before writing the
monotonic-cursor and upsert logic that would encode that decision durably
against live message data. That is the same kind of call this workplan's T02
requires external review for, and it should not be made unilaterally in a
loose-ends pass. Recommend Bernd (or a follow-up session with that decision
in hand) confirms the ownership/retention boundary, after which the cursor
and upsert implementation is a bounded, mechanical follow-on to the existing
`import_snapshot` in `hub_core/runtime/inbox_projection.py`.

## Admit the actual reader identity and full scope semantics

```task
id: HUB-WP-0011-T02
status: wait
flavor: residual
priority: high
state_hub_task_id: "35c5ae8b-f357-512f-af40-bc5915f3c02d"
```

Replace pilot operator authentication with the reviewed caller-specific access
contract and delivered workload credential. Preserve recipient authorization,
broadcast behavior, repository canonical/alias resolution, source timestamps
and thread/read/archive semantics for the selected reader. The existing pilot
supports only one literal agent and exact sender filters. Never distribute the
operator token as an application credential.

2026-09-28 integration dependency: `HUB-WP-0012-T02` through `T05` own the
shared NetKingdom identity, policy and workload-caller contract. Reuse that
contract here; this task retains inbox-specific recipient/alias semantics.
The root-only human milestone does not authorize an automated reader as root
or close the freshness and reader-switch tasks.

## Execute one reviewed client switch

```task
id: HUB-WP-0011-T03
status: wait
flavor: residual
priority: high
state_hub_task_id: "61c727a5-f4b1-54c0-b634-7d71a5416496"
```

After T01/T02 pass, produce live freshness and parity receipts for one State Hub
inbox reader; verify rollback to the current State Hub endpoint. Then execute
that bounded reader switch with the concrete deployment authorization. Retire
its compatibility dependency only after metered acceptance. Message-writer
cutover and all other route families remain separate STATE-WP-0079 work.