95 lines
4.5 KiB
Markdown
95 lines
4.5 KiB
Markdown
---
|
|
id: mem-engine-seam-tx
|
|
name: Mem engine — tx overlay, `Store` surface, `TxHandle` (staged `*_tx`, commit-merge + wake-at-commit, drop = discard)
|
|
status: pending
|
|
depends_on: [mem-engine-foundations]
|
|
scope: moderate
|
|
risk: high
|
|
impact: component
|
|
level: implementation
|
|
tags: [wave-6, mem-engine, seam]
|
|
---
|
|
|
|
## Description
|
|
|
|
The seam task, and the wave's load-bearing artifact
|
|
(engine-mem.md §The tx overlay): the `Store` trait impl plus the tx
|
|
overlay's full discipline.
|
|
|
|
- **`Store` surface**: the trait methods (`notify`, `stream`,
|
|
`queue`, `outbox`, `try_lock`, `listen`, `schedule`, `unschedule`,
|
|
`run_schedules`, `begin_tx`, `with_tx`) implemented over the
|
|
state core. `queue(name, opts)`/`outbox(name)` create/return
|
|
handles whose opts ride the handle (queues are names, not config
|
|
owners — the §3a stamp rules apply identically). Mechanism handles
|
|
are core-owned trait objects; engine types never appear in
|
|
signatures.
|
|
- **The tx overlay**: `begin_tx()` allocates a handle-private overlay.
|
|
All eleven `*_tx` methods stage effects in it — `enqueue_tx`,
|
|
`publish_tx`, `publish_with_key_tx`, `notify_tx`,
|
|
`save_offset_tx`, `get_job_tx`, `get_offset_tx`, `read_since_tx`,
|
|
`read_from_consumer_tx`, `outbox_enqueue_tx`, `commit`. Reads *inside* the tx merge the overlay over committed state (read-
|
|
your-own-writes, no round-trips: the tx-read rows'
|
|
`get_job_tx`/`read_since_tx` behaviors come free, but pin them).
|
|
Opt-stamping of staged effects runs at *enqueue* time on the
|
|
overlay (resolution identical to the no-handle paths, per
|
|
[ADR-020](../architecture/decisions/020-enqueue-opt-semantics-and-bridges.md)
|
|
§3: `enqueue_tx` stamps plain derived defaults 300/3/5/none;
|
|
`outbox_enqueue_tx` the 60/5/5 set).
|
|
- **Commit-merge + wake-at-commit**: commit merges the overlay
|
|
atomically (single guarded merge) and fires the overlay's pending
|
|
wakes *in the same operation* — a tx-staged notify delivers nothing
|
|
until the merge (the discipline pg got wrong and fixed via
|
|
`pg-fix-tx-wake`; here structural, and pinned from birth by the
|
|
suite's tx-commit-atomicity rows once integration wires them).
|
|
- **Drop = discard**: dropping the handle without commit/rollback
|
|
discards the overlay (rollback explicit form too) — no-ghosts
|
|
trivially, uncommitted state never touched committed state.
|
|
`with_tx` composition: `Ok` ⇒ commit, `Err`/drop/panic ⇒ rollback
|
|
(the N-5 panic posture applies; overlay discard must be panic-safe
|
|
through the unwind's drop).
|
|
- **Numeric domains** ([ADR-023](../architecture/decisions/023-fourth-review-round.md)
|
|
§2): validation at the trait-impl entry, before any storage-layer
|
|
effect — extents clamp empty, durations reject, boundaries total.
|
|
Same entry-point rule as the other engines, realized engine-side.
|
|
|
|
Engine-internal unit tests pin the overlay discipline directly
|
|
(merge atomicity, wake-after-not-before, drop-discard, panic-through-
|
|
unwind) in the family's mechanism-test posture; the suite column's
|
|
cross-engine rows land in `mem-engine-integration`.
|
|
|
|
## Acceptance Criteria
|
|
|
|
- [ ] The full `Store`/`TxHandle` trait surfaces implemented over
|
|
guarded state; no engine types in consumer signatures
|
|
- [ ] Overlay staging → commit-merge → wake-at-commit pinned by unit
|
|
tests (a tx-staged notify delivers nothing pre-commit, one wake
|
|
post-commit; enqueue/publish commit-atomicity shapes)
|
|
- [ ] Drop-without-commit and explicit rollback leave zero residue;
|
|
`with_tx` panic rolls back through the unwind's drop
|
|
- [ ] Tx reads see staged effects; other views see none pre-commit;
|
|
post-rollback reads' subjects gone (no-ghosts for reads)
|
|
- [ ] Numeric-domain guards at entry (extents/durations/boundaries)
|
|
pinned per [ADR-023](../architecture/decisions/023-fourth-review-round.md) §2
|
|
- [ ] `cargo check --target wasm32-unknown-unknown -p alkstore-mem`
|
|
clean; workspace gates green
|
|
|
|
## References
|
|
|
|
- docs/architecture/core-contract.md §The seam; §Cross-cutting contracts
|
|
- docs/architecture/decisions/007-transactional-seam.md;
|
|
014-outbox-tx-enqueue.md; 020-enqueue-opt-semantics-and-bridges.md
|
|
§3; 021-tx-reads-and-value-shape-fixes.md; 023-fourth-review-round.md §2
|
|
- docs/architecture/engine-mem.md §The tx overlay (the spec of record)
|
|
- tasks/pg-fix-tx-wake.md (the failure shape the overlay makes
|
|
structurally impossible)
|
|
- tasks/review-wave-5.md appendix (the suite rows whose mem wiring
|
|
consumes this task)
|
|
|
|
## Notes
|
|
|
|
> To be filled by implementation agent
|
|
|
|
## Summary
|
|
|
|
> To be filled on completion |