release-crate-docs: crate docs final pass — doc gate green with -D warnings posture recorded in AGENTS.md, warn(missing_docs) adopted on the four published crates (audit probe 0; Error enum+fields, sqlite substrate fuzz-surface fns filled), accuracy pass fixed core drifts (trim_to wake nuance, ADR-023 §2 domain rules + shared paragraph, QueueOpts gloss, MemStore::new exception) and engine postures (eleven-vs-ten tx-method count, spawn_blocking rationale via sync substrate, one-host cross-process honesty element), spec-side aligned (pg locks family + row-backed wording, mem clock-accessor home), two boundary-wording dispositions recorded for release-contract-window-close (try_recv arms, 8000-byte <= reading), queue round-trip doctest landed in alkstore-mem crate docs; task -> completed with Notes + Summary

This commit is contained in:
glm-5.3-flash committed 2026-10-11 00:08:01 +00:00
1 parent 5f5f6741d5
commit 8e27f4b64b
22 files changed
+289 -49

No files matched your search

+3 -2
View File
@@ -27,7 +27,8 @@ obligations live in the core spec.
family as design reference
([ADR-005](decisions/005-dependency-ownership.md)); semantics depth
pinned by [ADR-010](decisions/010-queue-semantics-depth.md) — all
engine-owned tables (job, dead, stream, offsets, schedule) in one
engine-owned tables (job, dead, stream, offsets, schedule, locks)
in one
PostgreSQL schema (default `alkstore`), queues as rows, no
per-queue tables.
@@ -66,7 +67,7 @@ obligations live in the core spec.
| notify / listen | `pg_notify(...)` inside the caller's tx (delivers at commit — native commit-atomicity, [ADR-007](decisions/007-transactional-seam.md)); `listen()` via LISTEN on the forwarder's connection, fanout to receivers |
| streams | durable event table + per-consumer offset cursors; `pg_notify` as the wake trigger ([ADR-006](decisions/006-wake-and-delivery-contract.md) mechanism split: durable row, LISTEN wake — the pg-boss-family shape). Depth per [ADR-015](decisions/015-streams-depth.md): the event table carries the nullable key column (carried metadata), reads yield `offset ASC` (global FIFO — bigserial offsets, immutable), `publish_with_key_tx` validates + inserts inside the caller's tx, `trim_to` is a `DELETE … WHERE offset <= ?` on a pool connection (wakes nothing) |
| queues | re-derived queue table + `FOR UPDATE SKIP LOCKED` claim + LISTEN-driven wake with re-poll safety net (default consumption posture, measured 5–16× vs 50 ms poll; poll-only fallback); states/dead-letter/backoff/visibility per [ADR-010](decisions/010-queue-semantics-depth.md), all in the engine-owned schema; the curve/stamps arithmetic is computed engine-side per [ADR-012](decisions/012-forked-substrate-design.md) §2 (equivalence with the SQLite engine pinned by the contract suite) |
| named locks | advisory-lock-semantics TTL locks (pg-boss-family design reference; guarantee row pinned by [ADR-008](decisions/008-contract-v1-pinning.md) §7) |
| named locks | row-backed TTL locks (a `locks` table in the engine-owned schema — ADR-008 §7 pins row-backed machinery, not pg advisory locks; the pg-boss family is the design reference; guarantee row pinned by [ADR-008](decisions/008-contract-v1-pinning.md) §7) |
| scheduler / outbox | collapse shape ([ADR-009](decisions/009-scheduler-collapse.md)): schedule rows in the engine-owned schema, tick re-derived (boundary advance + 64-boundary catch-up cap, honker parity), leadership via the engine's lock machinery on `__alkstore_scheduler`; outbox = helper over queues |
| begin_tx | pool checkout + `BEGIN`, returning the caller-held handle ([ADR-007](decisions/007-transactional-seam.md)) |
| handle ops | straight `.await`s through the held object; commit/rollback returns the object to the pool |