# Message identity reconciliation

Hub-core supports explicit aliases for historical message references that are
not complete UUIDs. An alias points to one existing canonical message and
records its source, reason, creator, and creation time. Registration never
changes the canonical message row, body, thread, or timestamps.

Aliases are deliberately not inferred. A missing character, transposition, or
similar-looking UUID remains unresolved until an operator supplies an exact
mapping with provenance. Canonical UUIDs cannot be registered as aliases, and
an existing alias cannot be rebound to a different message.

## CUST-IN-0012 finding

The production message is intact under canonical ID
`0b8dd0bf-41d1-47da-96ac-40e443c32e47`. It was created at
`2026-08-20T06:09:01.943176Z` and marked read at
`2026-08-22T23:16:34.490006Z`. The residual reference
`0b8dd0bf-41d-47da-96ac-40e443c32e47` omitted the final `1` in the second
UUID group. This is a reference defect, not a malformed stored row.

The governed mapping is therefore:

| Historical reference | Canonical message ID | Source |
| --- | --- | --- |
| `0b8dd0bf-41d-47da-96ac-40e443c32e47` | `0b8dd0bf-41d1-47da-96ac-40e443c32e47` | `CUST-IN-0012` |

## Applying a mapping

New hub-core databases receive `agent_message_identity_aliases` through
migration `0005_message_identity_aliases`. Existing hosts with their own
Alembic history must port that single table migration into the host-owned
migration chain before updating the router package; they must not run the
entire hub-core migration history over pre-existing core tables.

After the host migration, an attended operator can register this mapping:

```bash
hub-core message-alias register \
  --alias 0b8dd0bf-41d-47da-96ac-40e443c32e47 \
  --message-id 0b8dd0bf-41d1-47da-96ac-40e443c32e47 \
  --source CUST-IN-0012 \
  --reason "Historical reference omitted one UUID character" \
  --created-by operator \
  --confirm
```

The database URL comes from `HUB_CORE_DATABASE_URL` unless `--database-url` is
provided. The command returns only the alias, canonical UUID, immutable
provenance, and whether a row was created. It does not return message content
or database credentials. Repeating the same mapping is idempotent; attempting
to rebind the alias fails.

Once registered, normal message routes accept either the canonical UUID or the
exact alias. Responses always contain the canonical UUID. Unknown malformed
references return 404 and are never repaired heuristically.