docs: the pg LISTEN identifier-truncation wake-collision note (review 004 item 13)

deployment.md's Postgres co-tenancy paragraph and engine-postgres.md's
connection-architecture wake-substrate section now carry the 63-byte
identifier-truncation collision note as dated annotations: two names
longer than 63 bytes sharing a 63-byte prefix silently register the
same server-side wake channel; pg_notify (the parameter path, untrun-
cated, rejecting >= 64-byte channels) is unaffected, so the collapse is
on the registration side. Mitigation: keep mechanism names at most 63
bytes (byte count). The naming contract's deliberate no-cap verdict is
untouched. Discharges review 004 'findings recorded, not fixed' item
13 (task docs-pg-identifier-truncation-note).
This commit is contained in:
glm-5.3-flash committed 2026-10-11 15:03:55 +00:00
1 parent f2f5e03d7c
commit 6a6ffd68de
3 files changed
+82 -9

No files matched your search

+26 -1
View File
@@ -1,6 +1,9 @@
---
status: stable
last_updated: "2026-10-11 (the log-facade decision of record landed —
last_updated: "2026-10-11 (the pg identifier-truncation wake-collision
note — review 004 item 13's doc-fix disposition — added to the
Postgres engine section).
Earlier the same day: the log-facade decision of record landed —
[ADR-025](decisions/025-log-facade.md): engine diagnostics route
through the `tracing` facade, silent by default, subscriber wiring on
the consumer/binary; the diagnostics-posture section added below.
@@ -90,6 +93,28 @@ engine-owned PostgreSQL schema (default `alkstore`, per-engine option)
— layout per [ADR-010](decisions/010-queue-semantics-depth.md) §8
(resolved from [queues.md](queues.md)'s namespace bullet).
One pg-specific naming caveat, dated per the family's amendment
convention *(annotated 2026-10-11 — review 004 item 13, recorded
"not fixed" in the review with a fold-into-the-next-doc-pass
disposition; this note is that fix)*: the wake machinery
interpolates the channel as a quoted SQL identifier on
`LISTEN`/`UNLISTEN`, and PostgreSQL truncates identifiers to
**63 bytes (`NAMEDATALEN` − 1)** server-side — with only a
`NOTICE`, never an error — so two distinct names longer than 63
bytes sharing a 63-byte prefix register the **same** server-side
wake channel (a silent cross-channel collision). The `pg_notify`
path is unaffected by the truncation — it carries the channel as a
text parameter, not an identifier, and the server rejects channels
of 64 bytes or more there ("channel name too long") — so the
collapse is on the registration side. The
[naming contract](core-contract.md#naming--reserved-namespace)
deliberately caps no name (the length-independence verdict stands),
so nothing engine-side warns. Mitigation:
**keep mechanism names under the PostgreSQL identifier limit —
at most 63 bytes; the limit counts bytes, not characters, so
multibyte names reach it sooner.** Distinct names within the limit
cannot collide.
### Mem engine
- No connections — there is nothing to budget. The engine instance