glm-5.3-flash
f2f5e03d7c
Review 004 items 10+11: the two recorded mem growth postures (subscribe backlog drain unbounded on the consumer side; O(live-rows) claim scan with full-row clones) and the outbox's 'processed means delivered-or-reclaimable' semantic, pinned in engine-mem.md. The debug_assert arm was declined: the dropped ack/retry booleans also refuse benignly on legitimate in-closure handle ops, so it cannot separate a visibility lapse from a deliberate first-party outcome.
97 lines
4.4 KiB
Markdown
97 lines
4.4 KiB
Markdown
---
|
||
id: mem-doc-growth-outbox-notes
|
||
name: Pin mem's growth postures and outbox semantics in the spec (review 004 items 10+11)
|
||
status: completed
|
||
depends_on: []
|
||
scope: narrow
|
||
risk: trivial
|
||
impact: isolated
|
||
level: implementation
|
||
tags: [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. |