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

id	type	title	domain	repo	status	owner	topic_slug	created	updated	related	state_hub_workstream_id
HUB-WP-0008	workplan	Legacy message identity reconciliation	infotech	hub-core	finished	codex	custodian	2026-08-23	2026-08-23	CUST-WP-0063 CUST-IN-0012	0d3b24ed-d400-5c4f-8a10-f1f9a27cf2d2

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
state_hub_task_id: "f97377cd-a330-5cc4-8422-41f95667df2f"

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
state_hub_task_id: "a5e43449-06a6-5914-9767-da18ee677c00"

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
state_hub_task_id: "e8979c50-c7f1-577e-a541-1874d7f0fb3e"

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
state_hub_task_id: "45c7d979-3830-53dd-9648-c3fbbd1c0087"

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: done
priority: high
state_hub_task_id: "593d78ba-6f24-5293-a87c-ae0ca9165f7d"

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.

Completed 2026-08-23. Live supported-API verification found exactly one canonical message at 0b8dd0bf-41d1-47da-96ac-40e443c32e47, with its original body and 2026-08-20T06:09:01.943176Z creation time intact and read_at set to 2026-08-22T23:16:34.490006Z. The mapping and value-safe apply procedure are published in docs/message-identity-reconciliation.md. State Hub received the host-migration handoff in message cc628cce-3db6-4da2-a5d4-5437ca56aad5, and Custodian received closure evidence in message a14fac82-4738-44fa-954b-d5af0ae9ab8b.

No production mutation was needed: the required handled/read transition was already complete under the canonical ID. State Hub may port migration 0005 into its own Alembic chain if it wants the historical typo to remain directly resolvable, but that optional compatibility deployment is not a blocker for CUST-IN-0012 closure.

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