alkstore/tasks/mem-engine-seam-tx.md at 57451cef465813399c489b1b5fc4e8bba6cf390c

0 Fork 0

Files

T

glm-5.3-flash 5abd351c86 Wave-6 decomposition (mem engine): eleven tasks per the pg-wave rhythm — foundations (crate scaffold, MemStore::new isolation, guarded state core, wake routing, wasm32 gate from birth), seam-tx (the load-bearing tx overlay: eleven staged _tx methods, commit-merge + wake-at-commit — pg-fix-tx-wake's discipline structural from the start, drop = discard trivial, with_tx panic posture), mechanisms mutually parallel (notify-listen close-at-engine-drop/no-replay/never-coalesced; queues = ADR-010 machine driver-free with the equal-jitter curve and opts resolution as ADR-012 §2's third owner; streams log+offsets+trim; locks TTL registry, no busy-path analog), scheduler-outbox (tick/catch-up-64/leadership through the __alkstore_scheduler lock, engine-uniform per ADR-009 §4; outbox over queues with the 60/5/5 seam stamp), integration (suite third StoreFactory column green on host under a current-thread flavor, wasm32 acceptance items, engine-mem.md to implementation-complete), and the review-wave-6 gate (born-pinned audit: conformance read, discharge-map wiring, wasm items, three-way equivalence green, class-1 window discipline). Window riders: suite-harness-current-thread — the wave's one suite-side pre-task, past_stamp_sleep's blocking sleep goes async per review 003's properties.rs:1683 posture note, enabling the current-thread flavor; pg-fix-scheduler-tick-seam — review 003 Finding 1, the cfg(test) transient-fault seam driving the real tick_with_retries through retry-then-success and exhaustion arms (the last uncovered wave-4 hardening arm, sqlite-commit-error-arm pattern). Task hygiene: pg-fix-open-path frontmatter fixed (unquoted 'max_size: 0' colon-space inside the name scalar broke YAML parsing — taskgraph validate had been red one-error since the wave-4 fix-batch decomposition; also restores review-wave-4-fixes' dependency resolution). implementation.md: wave-6 table row → decomposed, task-set listing with the parallelism note (rider + pre-task independent of the mem chain; rider closes before the gate), wave-6 decomposition bullet in the review-rounds record. Docs-only change; verified taskgraph validate (60 tasks, no cycles), cargo fmt --check, cross-reference read

2026-10-10 09:57:01 +00:00

4.5 KiB

Raw Blame History

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

name

status

depends_on

scope

risk

impact

level

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

4.5 KiB Raw Blame History