coulomb/hub-core
4
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
hub-core/docs/message-identity-reconciliation.md
tegwick ed3feed310
Some checks failed
CI Smoke / host-smoke (push) Successful in 0s
Details
CI Smoke / pytest-smoke (push) Failing after 2s
Details
feat: reconcile legacy message identities 
Assistant: codex
Assistant-Model: gpt-5.6-sol
Assistant-Session: 01a0230c-b06c-7641-808a-e191b6d1da49
2026-08-23 11:59:52 +02:00

2.4 KiB
Raw Permalink Blame History

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:

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.