glm-5.3-flash
6a6ffd68de
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).
83 lines
3.7 KiB
Markdown
83 lines
3.7 KiB
Markdown
---
|
|
id: docs-pg-identifier-truncation-note
|
|
name: Document the pg identifier-truncation collision in the release text (review 004 item 13)
|
|
status: completed
|
|
depends_on: []
|
|
scope: single
|
|
risk: trivial
|
|
impact: isolated
|
|
level: implementation
|
|
tags: [review-004-fixes, postgres-engine, docs]
|
|
---
|
|
|
|
## Description
|
|
|
|
The pg identifier-truncation cross-channel collision, per
|
|
`docs/reviews/004-pre-release-general-review.md` §"Findings recorded,
|
|
not fixed" item 13: `LISTEN`/`UNLISTEN` interpolate the channel as a
|
|
quoted identifier (truncated at 63 bytes server-side) while
|
|
`pg_notify` carries it as a parameter — two distinct names sharing a
|
|
63-byte prefix can silently collapse into one wake channel. Names are
|
|
unbounded by the validation contract (the no-cap "length-independence"
|
|
verdict is deliberate — do not change it; the honest cheap fix is the
|
|
doc note the review prescribed).
|
|
|
|
Land the note in `deployment.md` (the pg rows / wherever the matrix
|
|
discusses naming or limits) and in `engine-postgres.md` if it has a
|
|
wake-channel section. The note states the mechanism (63-byte
|
|
identifier truncation; the `pg_notify` payload path unaffected) and
|
|
the mitigation (keep mechanism names under the PG identifier limit).
|
|
The deployment matrix is stable release text — a dated amendment
|
|
annotation per the family's convention.
|
|
|
|
## Acceptance Criteria
|
|
|
|
- [x] `deployment.md` carries the truncation-collision note with a
|
|
dated annotation (mechanism + mitigation, honestly worded)
|
|
- [x] `engine-postgres.md` carries it too if a wake-channel section
|
|
exists there (or the absence recorded in Notes)
|
|
- [x] The validation contract's no-cap verdict untouched
|
|
- [x] Doc gate green
|
|
|
|
## References
|
|
|
|
- docs/reviews/004-pre-release-general-review.md §"Findings recorded,
|
|
not fixed" item 13 (the finding, the "fold into whichever doc pass
|
|
runs next" disposition this task discharges)
|
|
- docs/architecture/deployment.md, engine-postgres.md (the landing
|
|
sites)
|
|
- alkstore-postgres/src/forwarder.rs (the LISTEN/UNLISTEN
|
|
interpolation sites, for the note's accuracy)
|
|
|
|
## Notes
|
|
|
|
Deployment matrix note: `deployment.md` has no standalone wake-channel
|
|
section — the landing site is the Postgres engine's co-tenancy
|
|
paragraph under "Connection budgets" (the one place the matrix
|
|
discusses naming), as a dated amendment annotation per the family
|
|
convention. `engine-postgres.md` has no dedicated wake-channel section
|
|
either; the note landed at the end of "Connection architecture" (the
|
|
wake substrate lives there) with a cross-reference to the
|
|
deployment-matrix statement. Accuracy sharpening beyond the review's
|
|
text (verified against Postgres master `commands/async.c`):
|
|
`pg_notify` does not merely escape identifier truncation — the server
|
|
*rejects* channels of 64 bytes or more there ("channel name too
|
|
long", an error), while quoted identifiers on the `LISTEN` side
|
|
truncate to 63 bytes silently (a `NOTICE`); the notes state the
|
|
collapse is on the registration side. The mitigation is phrased as a
|
|
consumer obligation (names at most 63 bytes; a byte count, not a
|
|
character count) — no validation contract change, per the task
|
|
description.
|
|
|
|
## Summary
|
|
|
|
Landed the pg identifier-truncation collision note in
|
|
`docs/architecture/deployment.md` (dated annotation, Postgres engine
|
|
section) and `docs/architecture/engine-postgres.md` (connection
|
|
architecture, wake-substrate section) — mechanism, honest send-vs-
|
|
registration-side statement, and the keep-names-under-63-bytes
|
|
mitigation. Frontmatter `last_updated` of both files carried forward.
|
|
Verified: `RUSTDOCFLAGS="-D warnings" cargo doc --no-deps` green,
|
|
`cargo fmt --check` green, `cargo clippy --all-targets -- -D warnings`
|
|
green; `core-contract.md`'s no-cap naming verdict untouched (diff
|
|
touching only the two doc files). |