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