Dispose the wave-6 class-1-window observations (release-contract-window-close)
The pre-release pass's last contract-text dispositions, each dated in-place citing the 2026-10-11 close-out pass (ADR-017 §2's terminal window): - Publish→wake ordering tolerance: documented tolerance (decided with the user) — core-contract.md streams paragraph + delivery-obligations bullet, ADR-015 §4 companion annotation; the wake = offset-order ADR amendment declined (commit-ordered pg visibility; hint-shaped wake posture). - ADR-023 §2: heartbeat(extend) and save_offset(offset) join the boundary/offset row (total — negatives well-defined), with the home rationale annotated; core-contract's domain paragraph mirrors; the backlog numeric-domain row registers the suite-duty follow-up. - ADR-021 §5: EventReceiver::try_recv's closed shape pinned (Err(Closed), mirroring ADR-008 §3); core-contract subscribe arms sentence extended. - get_job prose: core-contract queues section + queues.md's reads sentence now say the uniform id-global / get_job_tx-filtered split. - Mem-arithmetic observation: no-action disposition recorded in the task Notes (byte-level transplants; equivalence suite-pinned three-way). Suite stamps checked — no accumulation required (no cited § text changed meaning). Docs-only; gates green: build, workspace tests, clippy -D warnings, fmt, fuzz replay, rustdoc -D warnings, taskgraph validate (79 tasks).
This commit is contained in:
glm-5.3-flash committed
1 parent
8e27f4b64b
commit
a37c2887dc
6 files changed
+244
-31
No files matched your search
@@ -1,8 +1,6 @@
|
||||
---
|
||||
status: draft
|
||||
last_updated: "2026-10-10 (ADR-024 — the mem engine joins the family;
|
||||
the Store concept prose admits the engine-native constructor
|
||||
exception)"
|
||||
last_updated: "2026-10-11 (the pre-release class-1 close-out pass — the publish→wake ordering tolerance recorded; ADR-023 §2's `heartbeat(extend)`/`save_offset` classifications; `EventReceiver::try_recv`'s closed shape; `get_job`'s id-global prose)"
|
||||
---
|
||||
|
||||
# Core contract
|
||||
@@ -138,9 +136,18 @@ the engine's storage layer):
|
||||
chain); an exclusion mechanism must not silently hand back a lease
|
||||
the caller believes it holds.
|
||||
- **Boundaries/offsets** (`trim_to(horizon)`, enqueue `delay`/
|
||||
`run_at`/`expires`) — total: any `i64` is well-defined (a negative
|
||||
horizon deletes nothing; a negative delay resolves to a ready
|
||||
time in the past, i.e. ready now).
|
||||
`run_at`/`expires`, `heartbeat(extend)`, `save_offset(offset)`) —
|
||||
total: any `i64` is well-defined (a negative horizon deletes
|
||||
nothing; a negative delay resolves to a ready time in the past,
|
||||
i.e. ready now; a negative `heartbeat(extend)` — the renewed claim
|
||||
deadline is `now + extend` — shortens or voids the claim, and the
|
||||
validity predicate then refuses the ops, never an error; a negative
|
||||
offset save is stored, reads resume forward, and saves at-or-below
|
||||
the checkpoint are the monotone no-ops)
|
||||
*(the two 2026-10-11 classifications annotated in
|
||||
[ADR-023](decisions/023-fourth-review-round.md) §2 by the
|
||||
close-out pass; before that date the table covered only the first
|
||||
three arguments)*.
|
||||
|
||||
```text
|
||||
store.notify(channel, payload) handle.notify_tx(channel, payload)
|
||||
@@ -259,12 +266,40 @@ business-tx shape). Depth pinned by
|
||||
publish, informational, **not an ordering field** (offset is the
|
||||
only one); `payload_as<T>` decodes (the error is `Codec`).
|
||||
- **Ordering guarantee row** ([ADR-015](decisions/015-streams-depth.md)
|
||||
§4, extending [ADR-006](decisions/006-wake-and-delivery-contract.md)
|
||||
§2's streams row): `read_since`/`subscribe` yield `offset ASC` —
|
||||
global FIFO per stream; committed-event visibility and
|
||||
replay-on-attach as already pinned; offsets immutable. The
|
||||
contract suite pins cross-engine equivalence against this row
|
||||
(same publish sequence → same offset sequence → same read order).
|
||||
§4, extending [ADR-006](decisions/006-wake-and-delivery-contract.md)
|
||||
§2's streams row): `read_since`/`subscribe` yield `offset ASC` —
|
||||
global FIFO per stream; committed-event visibility and
|
||||
replay-on-attach as already pinned; offsets immutable. The
|
||||
contract suite pins cross-engine equivalence against this row
|
||||
(same publish sequence → same offset sequence → same read order).
|
||||
- **Wake-fire ordering tolerance** *(documented tolerance, 2026-10-11
|
||||
— the pre-release class-1 close-out pass,
|
||||
[ADR-017](decisions/017-contract-versioning.md) §2; disposes the
|
||||
wave-6 review gate's recorded observation)*: nothing in the
|
||||
contract pins wake-fire order to offset order. Offset allocation
|
||||
precedes insert+wake on a multi-threaded runtime (the mem engine;
|
||||
its documented current-thread posture never exercises it) and the
|
||||
offset is sequence-assigned pre-commit with the wake fired
|
||||
post-commit (the Postgres engine — commit order can invert
|
||||
sequence order), so two concurrent publishes can complete out of
|
||||
offset-allocation order. A subscriber's wake-driven drain that
|
||||
finishes between the two completions can checkpoint past the
|
||||
later-completing, lower-offset event: **the event stays in the
|
||||
log** — direct `read_since` always sees it, and a fresh
|
||||
`subscribe(consumer)` whose saved checkpoint is below it consumes
|
||||
it normally — but the live subscriber whose cursor passed it is
|
||||
not re-delivered it by the later wake. This is a documented
|
||||
consequence of the wake contract's best-effort posture (hints, not
|
||||
delivery promises); the offset-ASC read guarantee above is
|
||||
unaffected — reads always run over the committed log in offset
|
||||
order regardless of wake timing. Consumers requiring per-event
|
||||
completeness across concurrent same-stream publishers need the
|
||||
defensive re-read recipe (a lagged checkpoint, or a direct
|
||||
`read_since` sweep below it). Pinned as a tolerance, not an
|
||||
enforced guarantee (the heavier wake = offset-order amendment was
|
||||
weighed and declined with the user: enforcement against commit-
|
||||
ordered visibility is a redesign, and the wake mechanism's posture
|
||||
is hint-shaped by construction).
|
||||
- `read_since` / `read_from_consumer(offset)` — cursor-based reads;
|
||||
`get_offset(consumer)` — checkpoint inspection. A read from a
|
||||
trimmed-away offset region (below) resumes at the trim horizon's
|
||||
@@ -304,10 +339,14 @@ business-tx shape). Depth pinned by
|
||||
consumption: attach, read to current tail, resume after restart
|
||||
from the stored offset; explicit `save_offset` on the receiver
|
||||
(shape in [ADR-008](decisions/008-contract-v1-pinning.md) §8).
|
||||
**Error and close arms pinned**
|
||||
([ADR-021](decisions/021-tx-reads-and-value-shape-fixes.md) §5):
|
||||
`recv()`'s `Err` arm carries `Database` only (payloads cross raw;
|
||||
`Codec` lives at `payload_as<T>`; `Closed` is the `None` arm);
|
||||
**Error and close arms pinned**
|
||||
([ADR-021](decisions/021-tx-reads-and-value-shape-fixes.md) §5):
|
||||
`recv()`'s `Err` arm carries `Database` only (payloads cross raw;
|
||||
`Codec` lives at `payload_as<T>`; `Closed` is the `None` arm);
|
||||
the poll form's arms pin identically — `try_recv()`: `Ok(None)` =
|
||||
idle (no event pending right now), `Err(Closed)` = the receiver
|
||||
closed, `Database` otherwise (the closed shape annotated
|
||||
2026-10-11, the close-out pass);
|
||||
close is terminal and its *cause* is the documented engine
|
||||
asymmetry — SQLite's receiver closes on watcher death (POC-pinned),
|
||||
the pg receiver stays open across forwarder reconnects (reconnect
|
||||
@@ -399,9 +438,17 @@ obligations:
|
||||
([ADR-010](decisions/010-queue-semantics-depth.md) §2). Dead letters:
|
||||
move-to-dead storage, `get_job` sees dead rows (with
|
||||
`last_error`/`died_at`), retention via `dead_letter_retention_s`
|
||||
(default forever), no redrive API
|
||||
([ADR-010](decisions/010-queue-semantics-depth.md) §1–§4).
|
||||
`QueueOpts` stamp onto the job row at enqueue (§3a) — queues are
|
||||
(default forever), no redrive API
|
||||
([ADR-010](decisions/010-queue-semantics-depth.md) §1–§4).
|
||||
`get_job(job_id)` on the handle is an **id-global lookup** — the
|
||||
handle carries the queue, but the lookup keys on the id alone and
|
||||
resolves rows in any queue (uniform on all engines; annotated
|
||||
2026-10-11, the close-out pass — the wave-6 review's recorded
|
||||
prose ambiguity); the tx-side `get_job_tx(queue, job_id)` takes
|
||||
the queue name and **is** queue-filtered
|
||||
([ADR-019](decisions/019-mechanism-handle-surfaces.md) §1,
|
||||
[ADR-021](decisions/021-tx-reads-and-value-shape-fixes.md) §1).
|
||||
`QueueOpts` stamp onto the job row at enqueue (§3a) — queues are
|
||||
names, not config owners. The remaining v1-skeleton ops (`ack_batch`
|
||||
— the batch ack applies the uniform predicate per id, lapsed or
|
||||
non-claimed ids silently not counted; `cancel` — unconditional
|
||||
@@ -522,7 +569,12 @@ row is [ADR-009](decisions/009-scheduler-collapse.md) §4's. This spec
|
||||
inherits them and adds the consumer obligations:
|
||||
|
||||
- wake idempotence (notify's best-effort, coalescing behavior);
|
||||
- explicit offset saves (streams);
|
||||
- explicit offset saves (streams); wake-fire ordering is a
|
||||
documented tolerance, not a pinned guarantee — wake order need not
|
||||
match offset order and a wake-driven subscriber can drain past an
|
||||
event whose publish completed out of offset order (the streams
|
||||
section's tolerance paragraph, 2026-10-11); recovery rides the
|
||||
offset-ordered re-read the wake contract already obligates;
|
||||
- visibility-timeout budgeting — heartbeat inside the deadline for
|
||||
long work; the dual-execution window and reclaim-eats-attempt rules
|
||||
are documented consumer obligations
|
||||
@@ -734,9 +786,14 @@ before the engine specs are called `stable`:
|
||||
clamp to empty (`claim_batch(n <= 0)` claims nothing; stream reads
|
||||
with `limit <= 0` read nothing, never the whole queue/stream), so
|
||||
the SQLite `LIMIT -1` dialect artifact is dead on both engines;
|
||||
durations reject (`try_lock`/`renew` with `ttl <= 0` are opaque
|
||||
`Err`s on both engines); boundaries are total (a negative
|
||||
`trim_to` horizon deletes nothing, idempotently).
|
||||
durations reject (`try_lock`/`renew` with `ttl <= 0` are opaque
|
||||
`Err`s on both engines); boundaries are total (a negative
|
||||
`trim_to` horizon deletes nothing, idempotently; the same
|
||||
totality over non-positive values covers `heartbeat(extend)`'s
|
||||
relative-deadline argument and `save_offset`'s offset — both
|
||||
classified 2026-10-11 by the close-out pass, the ADR-023 §2
|
||||
annotation; their suite rows are the follow-up that
|
||||
classification implies).
|
||||
- **`encode_payload` typed failure**
|
||||
([ADR-023](decisions/023-fourth-review-round.md) §1) — the helper
|
||||
returns `Result<Vec<u8>, Error::Codec>`; enqueue/publish store and
|
||||
|
||||
Reference in new issue
Block a user