alkstore/tasks/docs-pg-identifier-truncation-note.md

id, name, status, depends_on, scope, risk, impact, level, tags

id	name	status	depends_on	scope	risk	impact	level	tags
docs-pg-identifier-truncation-note	Document the pg identifier-truncation collision in the release text (review 004 item 13)	completed		single	trivial	isolated	implementation	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

• deployment.md carries the truncation-collision note with a dated annotation (mechanism + mitigation, honestly worded)
• engine-postgres.md carries it too if a wake-channel section exists there (or the absence recorded in Notes)
• The validation contract's no-cap verdict untouched
• 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).