# State Hub inbox read pilot

`GET /ports/projections/statehub-inbox` is an opt-in, authenticated read-only
projection over the existing `agent_messages` model. It is distinct from
`/ports/messaging/messages`, which accepts new message envelopes and does not
implement State Hub's read/archive lifecycle.

Enable only after validating and importing a consistent source snapshot:
`HUB_CORE_STATEHUB_INBOX_READS=1`, `HUB_CORE_STATEHUB_INBOX_AGENT=state-hub`.
PostgreSQL and the configured operator bearer token are required. Disabled by
default. No POST/PATCH/DELETE exists on the pilot endpoint. Imported history
never emits messages or notifications.

The response is the State Hub `MessageRead` list shape. Parameters are
`to_agent` (must match the configured pilot agent), exact `from_agent`,
`unread_only` and `limit` (1–1000, default 50). Broadcast messages are included;
archived messages are excluded. Results order by created_at descending, then ID
for ties. Query transactions are read-only. Responses carry `Cache-Control:
no-store` and `X-Hub-Core-Read-Mode: snapshot-pilot`.

This proves one literal agent inbox. It does not claim repository rename/alias
resolution, unscoped fleet reads, thread lookup, continuous freshness, or writer
cutover. The importer preserves thread roots so later history work need not
reconstruct dangling identities.

## Snapshot and import

Capture messages with one source PostgreSQL read-only, repeatable-read
transaction. Preserve id, sender, recipient, subject, body, thread_id, read_at,
archived_at and created_at, including archived/thread-root records. Keep the
raw snapshot in private temporary storage; commit only hashes and counts.

The bundle has schema `hub-core.statehub-inbox-snapshot.v1`, `source`,
`captured_at`, `messages`, `count`, and `content_hash`. Use `snapshot_hash` from
`hub_core.runtime.inbox_projection` for canonical UTC/UUID normalization.
`import_snapshot(session, bundle, expected_hash=..., apply=False)` validates;
`apply=True` imports under a caller-owned transaction. The caller must commit
only on success and roll back any exception. PostgreSQL apply locks the target
message table before inspecting it. Different existing content refuses all
changes; exact repeats are no-ops. Thread roots insert before replies. Duplicate
IDs, malformed rows, hash/count mismatch, absent provenance, missing roots and
cycles are rejected.

Use the existing workload database credential delivery inside the receiving
pod; never export database credentials into evidence. No schema migration or
new secret is required. This is a one-time migration helper, not a message
sending API or an automated synchronization loop.

## Pilot sequence and rollback

1. Keep State Hub as sole message writer; capture source revision, instance,
   repeatable-read snapshot, data hash and expected filtered inbox results.
2. Import only into an empty receiver, verify all row hashes/counts and replay
   as a no-op. Deploy the disabled reader image, then enable the private pilot.
3. Compare the same frozen source rows with authenticated receiver responses:
   all/unread/sender/limit cases, broadcast inclusion and archive exclusion.
   Check unauthenticated rejection and absence of writes. A later live State
   Hub read is a freshness observation, not the original snapshot oracle.
4. Disable the reader flag and verify the endpoint returns 404; re-enable and
   recheck the same hash. Retain the imported rows for review; do not delete
   history as a rollback technique. Runtime rollback uses the previous image.

Transport from State Hub must be explicitly admitted by rapp-core-hub's
NetworkPolicy. Scope any pilot exception to State Hub API pod labels and the
candidate port. No public Ingress or production message-writer change is part
of this pilot. The operator bearer stays in its existing credential lane;
production caller credentials and ongoing freshness require their own cutover.