hub-core/workplans/HUB-WP-0008-legacy-message-identity-reconciliation.md

id	type	title	domain	repo	status	owner	topic_slug	created	updated	related
HUB-WP-0008	workplan	Legacy message identity reconciliation	infotech	hub-core	active	codex	custodian	2026-08-23	2026-08-23	CUST-WP-0063 CUST-IN-0012

Legacy message identity reconciliation

Goal

Provide a governed, auditable way to resolve malformed historical message references to their existing canonical message UUIDs. Preserve message body, threading, chronology, and canonical identity; do not rewrite message rows or silently guess aliases.

Establish the source record and repair boundary

id: HUB-WP-0008-T01
status: done
priority: high

Reproduce CUST-IN-0012, locate the source message without database mutation, and determine whether the defect is stored data or an external reference. Record the canonical identity, chronology, current read state, and the constraints that any repair must preserve.

Completed 2026-08-23. The production list and preserved coordination evidence show that the stored record is valid and unchanged at canonical ID 0b8dd0bf-41d1-47da-96ac-40e443c32e47, created at 2026-08-20T06:09:01.943176Z. The CUST-IN-0012 reference omitted the final 1 in the second UUID group. The canonical message was already marked read at 2026-08-22T23:16:34.490006Z; there is no malformed database row to rewrite.

Add durable explicit message aliases

id: HUB-WP-0008-T02
status: done
priority: high

Add a core-schema alias record keyed by the exact historical reference and pointing to one canonical message UUID. Require operator/migration provenance, reject alias conflicts, and keep canonical UUID lookup unchanged.

Completed 2026-08-23. MessageIdentityAlias and migration 0005_message_identity_aliases add a separate alias table with an exact text primary key, restrictive foreign key to the canonical message, immutable source/reason/creator provenance, and creation time. The registration service rejects canonical UUID shadowing, whitespace/path ambiguity, absent canonical messages, and conflicting rebinding; identical registration is idempotent.

Resolve aliases through message operations

id: HUB-WP-0008-T03
status: done
priority: high

Allow read, archive, reply, and thread operations to resolve only explicitly registered aliases. Unknown malformed identifiers remain rejected or not found; no edit-distance or UUID-repair guessing is permitted.

Completed 2026-08-23. The message router accepts string references at the thread/read/archive/reply boundaries, resolves complete UUIDs directly, and consults aliases only for non-UUID references. Every response continues to carry the canonical message UUID. hub-core message-alias register provides the attributable apply path and requires an explicit --confirm.

Prove preservation and failure behavior

id: HUB-WP-0008-T04
status: done
priority: medium

Test canonical lookup, alias lookup, idempotent registration, conflicting mapping rejection, unknown malformed references, and preservation of message body, chronology, threading, and canonical response identity.

Completed 2026-08-23. Four focused integration tests prove explicit and idempotent registration, immutable provenance, conflicting mapping and UUID shadow rejection, alias-based read/reply/thread/archive behavior, unchanged body and creation time, canonical response identity, and 404 for an unknown malformed reference. The full suite passes 104 tests; the wheel contains the service, model, migration, router, and CLI surfaces.

Hand off the production reconciliation

id: HUB-WP-0008-T05
status: wait
priority: high

Publish the canonical mapping for CUST-IN-0012, provide a value-safe migration/apply procedure to the State Hub retirement owner, verify the supported read transition, and notify Custodian with non-secret evidence.

Local handoff material is complete in docs/message-identity-reconciliation.md. Production registration remains wait: State Hub owns a separate Alembic history and must port migration 0005 into that chain before adopting the new router. The canonical message is already read, so there is no urgent message mutation and no justification for direct database access. After the host migration/deploy, register the exact alias through the confirmed CLI and verify both canonical and alias reads.

Acceptance

• Source record and false/malformed reference are distinguished
• Explicit aliases are durable, attributable, and conflict-safe
• Message operations preserve the canonical response identity
• No message content, chronology, or thread relationship is rewritten
• CUST-IN-0012 closure evidence reaches Custodian