docs(mem): pin growth postures and outbox delivered-or-reclaimable semantic
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.
This commit is contained in:
1 parent
7700079158
commit
f2f5e03d7c
2 files changed
+77
-11
No files matched your search
@@ -1,13 +1,14 @@
|
|||||||
---
|
---
|
||||||
status: stable
|
status: stable
|
||||||
last_updated: "2026-10-10 (the wave-6 review gate passed: the
|
last_updated: "2026-10-11 (review-004 items 10+11 pinned: the growth
|
||||||
conformance read clean — three edge-domain fixes landed inline (the
|
postures section — subscribe backlog drain, O(live-rows) claim scan —
|
||||||
stream cursor read's `i64::MAX` overflow, `trim_to`'s horizon
|
and the outbox's delivered-or-reclaimable semantic; the wave-6
|
||||||
endpoint, the scheduler register-time interval overflow now rejecting
|
review gate had passed earlier — conformance read clean, three
|
||||||
with `InvalidSpec` like the SQLite register) plus scaffold-residue
|
edge-domain fixes landed inline (the stream cursor read's `i64::MAX`
|
||||||
cleanup; the third column's 25-row set green under the current-thread
|
overflow, `trim_to`'s horizon endpoint, the scheduler register-time
|
||||||
flavor; the wasm32 gate + feature subset verified; the rider's arms
|
interval overflow now rejecting with `InvalidSpec`), the third
|
||||||
verified)"
|
column's 25-row set green under the current-thread flavor, the
|
||||||
|
wasm32 gate + feature subset verified, the rider's arms verified)"
|
||||||
---
|
---
|
||||||
|
|
||||||
# Mem engine
|
# Mem engine
|
||||||
@@ -98,6 +99,23 @@ private to the caller's handle.
|
|||||||
| begin_tx | overlay allocation ([ADR-007](decisions/007-transactional-seam.md)) |
|
| begin_tx | overlay allocation ([ADR-007](decisions/007-transactional-seam.md)) |
|
||||||
| handle ops | direct `.await`s on guarded state; `encode_payload` via core (ADR-020 §4) |
|
| handle ops | direct `.await`s on guarded state; `encode_payload` via core (ADR-020 §4) |
|
||||||
|
|
||||||
|
### Outbox semantics
|
||||||
|
|
||||||
|
The outbox is a helper over queues ([ADR-014](decisions/014-outbox-tx-enqueue.md)):
|
||||||
|
`run_once` claims one job through the ordinary claim machinery and
|
||||||
|
applies the outcome when delivery returns — `Ok` ⇒ ack, `Err` ⇒
|
||||||
|
retry on the queue's own curve. The ack/retry application's
|
||||||
|
row-ref booleans are dropped: a delivery that outlived its
|
||||||
|
visibility window (or a consumer side-effect that handled the row
|
||||||
|
first, e.g. an in-closure `ack`/`retry` on the boxed handle) leaves
|
||||||
|
the outer outcome unapplied, and `run_once` still reports `true`.
|
||||||
|
Inherent to the no-heartbeat outbox design — at-least-once reclaim
|
||||||
|
is the recovery, not a second report. **Processed means
|
||||||
|
delivered-or-reclaimable**: `true` attests the claim was processed,
|
||||||
|
not that the ack/exhaust landed; renewal inside the window is the
|
||||||
|
consumer's obligation ([ADR-019](decisions/019-mechanism-handle-surfaces.md)
|
||||||
|
§5) and reclaim closes a lapsed one.
|
||||||
|
|
||||||
## Asymmetry classification (ADR-024 §3)
|
## Asymmetry classification (ADR-024 §3)
|
||||||
|
|
||||||
| Asymmetry | Mem posture |
|
| Asymmetry | Mem posture |
|
||||||
@@ -107,6 +125,24 @@ private to the caller's handle.
|
|||||||
| Receiver close | one close path: engine drop closes open receivers (process exit/shutdown); contract close-arm shapes apply unchanged ([ADR-021](decisions/021-tx-reads-and-value-shape-fixes.md)) |
|
| Receiver close | one close path: engine drop closes open receivers (process exit/shutdown); contract close-arm shapes apply unchanged ([ADR-021](decisions/021-tx-reads-and-value-shape-fixes.md)) |
|
||||||
| Wake coalescing | not applicable — direct at-commit delivery, per-subscriber FIFO; the engine spec line above pins it |
|
| Wake coalescing | not applicable — direct at-commit delivery, per-subscriber FIFO; the engine spec line above pins it |
|
||||||
|
|
||||||
|
## Growth postures (review 004 items 10–11)
|
||||||
|
|
||||||
|
Two perf/posture notes recorded at the pre-release general review
|
||||||
|
(the mem side of [deployment.md](deployment.md)'s accepted growth
|
||||||
|
families), pinned here as the code-level economics:
|
||||||
|
|
||||||
|
- **Subscribe backlog drain** — the subscribe path drains the full
|
||||||
|
event backlog into the receiver's pending deque *before the first
|
||||||
|
yield*, and pending keeps growing at publish rate while a consumer
|
||||||
|
is stalled (`alkstore-mem/src/stream.rs:314-331` — the documented
|
||||||
|
"drains to the tail then parks" shape, unbounded on the consumer
|
||||||
|
side). The feed ends at engine drop; `trim_to` bounds the stored
|
||||||
|
log, not a stalled consumer's pending deque.
|
||||||
|
- **Claim scan** — the claim path is an O(total-live-rows) scan with
|
||||||
|
full-row clones per claim (`alkstore-mem/src/queue.rs:122-181`) —
|
||||||
|
blessed economics for the ephemeral tier ([ADR-024](decisions/024-mem-engine.md)
|
||||||
|
§2).
|
||||||
|
|
||||||
## Isolation and the suite factory
|
## Isolation and the suite factory
|
||||||
|
|
||||||
Each `MemStore::new()` yields a distinct engine instance sharing
|
Each `MemStore::new()` yields a distinct engine instance sharing
|
||||||
|
|||||||
@@ -1,7 +1,7 @@
|
|||||||
---
|
---
|
||||||
id: mem-doc-growth-outbox-notes
|
id: mem-doc-growth-outbox-notes
|
||||||
name: Pin mem's growth postures and outbox semantics in the spec (review 004 items 10+11)
|
name: Pin mem's growth postures and outbox semantics in the spec (review 004 items 10+11)
|
||||||
status: pending
|
status: completed
|
||||||
depends_on: []
|
depends_on: []
|
||||||
scope: narrow
|
scope: narrow
|
||||||
risk: trivial
|
risk: trivial
|
||||||
@@ -60,8 +60,38 @@ Doc-only plus at most one `debug_assert!` — no behavioral change.
|
|||||||
|
|
||||||
## Notes
|
## Notes
|
||||||
|
|
||||||
> To be filled by implementation agent
|
- 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
|
## Summary
|
||||||
|
|
||||||
> To be filled on completion
|
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.
|
||||||
Reference in new issue
Block a user