---
id: HUB-WP-0008
type: workplan
title: "Legacy message identity reconciliation"
domain: infotech
repo: hub-core
status: finished
owner: codex
topic_slug: custodian
created: "2026-08-23"
updated: "2026-08-23"
related:
  - CUST-WP-0063
  - CUST-IN-0012
state_hub_workstream_id: "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

```task
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

```task
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

```task
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

```task
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

```task
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

- [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
- [x] `CUST-IN-0012` closure evidence reaches Custodian