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:
1 parent
5f5f6741d5
commit
8e27f4b64b
22 files changed
+289
-49
No files matched your search
@@ -58,7 +58,10 @@ daemons, the mem engine realizes with process-owned state:
|
||||
- **No background machinery to bootstrap** — no schema bootstrap, no
|
||||
watcher thread (nothing cross-connection to poll), no forwarder.
|
||||
The only async machinery is tokio-time-driven: lock TTLs, the
|
||||
scheduler's boundary waits, and wake delivery.
|
||||
scheduler's boundary waits, and wake delivery. All timestamps read
|
||||
the process clock through one internal accessor — no server clock
|
||||
to defer to, no per-mechanism clock reads (the wasm-posture note,
|
||||
[ADR-024](decisions/024-mem-engine.md) §5).
|
||||
- **Wake substrate**: in-process channels. Wakes deliver at the
|
||||
commit boundary directly to each open receiver — no batching
|
||||
boundary exists, so coalescing is not applicable; per-subscriber
|
||||
|
||||
@@ -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 |
|
||||
|
||||
Reference in new issue
Block a user