---
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