coulomb/hub-core
4
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

feat: reconcile legacy message identities
Some checks failed
CI Smoke / host-smoke (push) Successful in 0s
Details
CI Smoke / pytest-smoke (push) Failing after 2s
Details

Browse source 
Assistant: codex
Assistant-Model: gpt-5.6-sol
Assistant-Session: 01a0230c-b06c-7641-808a-e191b6d1da49
This commit is contained in:
tegwick 2026-08-23 11:59:52 +02:00
parent ab936a1e98
commit ed3feed310
13 changed files with 693 additions and 10 deletions
Download patch file Download diff file Expand all files Collapse all files

56
docs/message-identity-reconciliation.md Normal file
View file

@ -0,0 +1,56 @@
# 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.