alkstore/tasks/mem-doc-growth-outbox-notes.md

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

id	name	status	depends_on	scope	risk	impact	level	tags
mem-doc-growth-outbox-notes	Pin mem's growth postures and outbox semantics in the spec (review 004 items 10+11)	completed		narrow	trivial	isolated	implementation	review-004-fixes mem-engine docs

Description

Two recorded mem postures get their doc pins, per docs/reviews/004-pre-release-general-review.md §"Findings recorded, not fixed" items 10 and 11 (the review's "carry into the mem spec's growth section when next touched" — this is that touch).

(a) Growth postures (item 10) — two honest sentences in engine-mem.md's growth section:

• The subscribe path drains the full backlog into the receiver's pending deque before the first yield, and pending grows at publish rate for a stalled consumer (stream.rs:314-331 — the documented "drains to the tail then parks" shape, unbounded on the consumer side).
• The claim path is an O(total-live-rows) scan with full-row clones per claim (queue.rs:122-181) — blessed economics for the ephemeral tier.

(b) Outbox outcome swallow (item 11) — outbox run_once drops the ack/retry row-refs' booleans and returns Ok(true) even when delivery outlived the visibility window and nothing landed (outbox.rs:104-122). Inherent to the no-heartbeat outbox design (at-least-once reclaim is the recovery). Pin the "processed means delivered-or-reclaimable" semantic with a doc sentence in engine-mem.md's outbox section; add the debug_assert! too if it adds value without noise — the review offered either, implementer's call (record which and why).

Doc-only plus at most one debug_assert! — no behavioral change.

Acceptance Criteria

• engine-mem.md carries the two growth-posture sentences, anchored to the code sites
• The outbox "processed means delivered-or-reclaimable" semantic is pinned (doc sentence; debug_assert! per the recorded call)
• Doc gate green (RUSTDOCFLAGS="-D warnings" cargo doc --no-deps); mem tests green (the debug_assert! arm, if added, exercised by an existing outbox test)

References

• docs/reviews/004-pre-release-general-review.md §"Findings recorded, not fixed" items 10–11 (the findings, the blessed-economics framing)
• docs/architecture/engine-mem.md (the growth section, the outbox section)
• alkstore-mem/src/stream.rs:314-331, queue.rs:122-181, outbox.rs:104-122 (the anchored sites)

Notes

• Neither engine-mem.md growth nor outbox section existed — both were added (the review's "carry into the growth section" assumed a touch that creates them). Growth postures placed after the asymmetry-classification table; the outbox semantic as a ### Outbox semantics subsection under "Mapping the contract" (the table's scheduler/outbox row pointed there).
• The debug_assert! was not added (implementer's call, either was offered): a debug assertion that the dropped ack/retry booleans landed would also fire on legitimate in-closure handle ops — a delivery closure that calls ack/retry/fail on the boxed JobHandle (all available per ADR-019) makes the outer ack_row/retry_row refuse benignly, so the assertion would false-positive on valid flows and cannot distinguish a visibility lapse from a deliberate first-party outcome without re-reading the row's state (noise > value, debug-only). The doc sentence carries the semantic; it also names the in-closure-op case the assertion could not have separated.

Summary

Doc-only change, no behavioral code. docs/architecture/engine-mem.md gained: a ### Outbox semantics subsection pinning "processed means delivered-or-reclaimable" for the no-heartbeat outbox (run_once returns true even when the ack/retry application refuses — at-least-once reclaim is the recovery), and a ## Growth postures (review 004 items 10–11) section with the two recorded postures anchored to stream.rs:314-331 (subscribe drains the full backlog into pending before the first yield; pending grows at publish rate for a stalled consumer) and queue.rs:122-181 (O(total-live-rows) claim scan with full-row clones — blessed ephemeral-tier economics). Frontmatter last_updated refreshed. Verified: RUSTDOCFLAGS="-D warnings" cargo doc --no-deps clean; cargo test -p alkstore-mem green (102 unit + 26 suite + 1 doctest — outbox tests exercise the pinned run_once arms); cargo clippy -p alkstore-mem --all-targets -- -D warnings and cargo fmt --check clean.