feat: reconcile legacy message identities

Assistant: codex
Assistant-Model: gpt-5.6-sol
Assistant-Session: 01a0230c-b06c-7641-808a-e191b6d1da49

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

@@ -0,0 +1,128 @@
+---
+id: HUB-WP-0008
+type: workplan
+title: "Legacy message identity reconciliation"
+domain: infotech
+repo: hub-core
+status: active
+owner: codex
+topic_slug: custodian
+created: "2026-08-23"
+updated: "2026-08-23"
+related:
+  - 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
+
+```task
+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
+
+```task
+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
+
+```task
+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
+
+```task
+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
+
+```task
+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
+
+- [x] Source record and false/malformed reference are distinguished
+- [x] Explicit aliases are durable, attributable, and conflict-safe
+- [x] Message operations preserve the canonical response identity
+- [x] No message content, chronology, or thread relationship is rewritten
+- [ ] `CUST-IN-0012` closure evidence reaches Custodian