Store: declared non-overlapping intervals and retry-safe host transactions (#902)

[jimhoyd]

Implements #902 items 1 and 3. Items 2, 4, 5 and 6 stay on #902; STORE.md's "What is not covered" points there.

Item 1: collections.<c>.intervals: {start, end, within?, scope?, when?}

• Rule: no two constrained records in the same scope, with equal within values, may overlap as half-open [start, end). Intervals that only touch are allowed.
  • Checked inside the write transaction for create, PUT, PATCH and transitions.
  • A clash refuses with 409 interval_conflict and writes nothing: no record, no retry claim, no audit event.
  • A refused move keeps the old slot.
• when: an equality filter such as {status: booked}, so cancelling frees a slot. Reopening into a taken slot is refused.
• scope: collection (the default) blocks across owners; owner constrains each owner's records alone.
• Privacy: conflict.id appears only when the caller may read the conflicting record. Another owner's booking blocks the slot and nothing about it is returned.
• Bounds:
  • start, end and within properties must be required and not increments.
  • Bounds are both numeric, or both date-time in UTC …Z (offsets are refused).
  • Date-times compare as epoch milliseconds in SQL, checked against JavaScript on 5,000 random values.
• Index:
  • A partial expression index per declaration makes the check one indexed step; a test asserts the query plan.
  • Activation refuses stored overlaps, naming both ids, and drops stale indexes.
  • reassign and ownerless-assign refuse moves that would overlap under scope: owner.

Item 3: StoreExports.transaction(work, {idempotencyKey, fingerprint?})

• Migration 3→4 adds store_transaction_results, which stores the key and fingerprint as SHA-256 only.
• Same fingerprint: returns the stored result without running work.
• Different fingerprint: 422 idempotency_key_reused.
• First run: stores the result in the same transaction. The result must be exact-round-trip JSON of at most 16 KiB. The newest 1000 keys are kept.

Measurements (npm run bench:store -- --intervals, M4 Pro, Node 26.10, SQLite 3.53.4)

p50	1k	10k
Check query through the index	1.8 µs	2.4 µs
Same query, index dropped	267 µs	3.2 ms
Previous host-transaction scan	23 µs	197 µs
Accepted create with / without intervals	81 / 65 µs	184 / 180 µs

Evidence

• intervals.test.ts (13 tests) covers:
  • adjacency, and the same instant written two ways;
  • the UTC and ordering 422s;
  • a refused move keeping its slot, cancel/reopen, privacy on owned collections, and scope: owner;
  • the reassign refusal, and rollback on an injected failure;
  • an in-process race and a worker-thread race;
  • activation refusals, the query plan and stale-index drop;
  • the OpenAPI description.
• transaction-retries.test.ts (5 tests) covers replay, a mismatched fingerprint, nothing kept on failure, restart, hashing, eviction and races.
• npm run verify and npm run test:package pass, based on main after Store collections name project schemas; defaults and readOnlyProperties on the collection (#908) #924.
• Store budget raised to 116 / 438 KiB (measured 114,883 / 445,013 bytes).

Limits

• Races were tested with worker threads, not separate processes; that is Store: declarative interval constraint, declarative transfer, retries for host transactions, multi-process serving #902 item 4.
• One slot per interval: no capacity above one, no recurring intervals.
• Stored transaction results are snapshots, so the docs advise returning ids.

🤖 Generated with Claude Code