ADR-019/020: second review round — handle surfaces, enqueue semantics, payload bridge + mechanical fixes

ADR-019: mechanism-handle traits pinned (Queue/StreamHandle/Outbox/
Lock/JobHandle), Job/Schedule struct shapes, worker_id claimant
identity, core StopToken — closes the 'pin at implementation' residue
before ADR-017's amend-in-place window terminates at first release.

ADR-020: delay-wins-over-run_at precedence (honker parity), relative
expires, scheduler-fired stamps from derived queue defaults, serde_json
byte-level payload encoding.

Mechanical: overview/engine-postgres ADR tables completed through 020,
core-contract Errors section re-framed to class-1, ADR-014 sketch
annotated with publish_with_key_tx, ADR-015 status dated, reserved-
namespace kinds list normalized to six kinds, redrive gate wording
aligned, broken link fixed, StopToken deferral superseded in ADR-009.
This commit is contained in:
glm-5.3-flash committed 2026-10-06 13:06:23 +00:00
1 parent c49befd195
commit 8323a7853e
13 files changed
+661 -54

No files matched your search

+18 -4
View File
@@ -1,6 +1,6 @@
---
status: draft
last_updated: 2026-10-05
last_updated: 2026-10-06 (ADR-019/020 — handle surfaces, enqueue semantics)
---
# Queues, scheduler, outbox — semantics depth
@@ -39,7 +39,11 @@ made under; the ADRs carry the WHY.
- **Job options** (the contract v1 skeleton,
[ADR-008](decisions/008-contract-v1-pinning.md) §1, from the
honker-rs surface): `delay, priority, max_attempts, expires, run_at`
at enqueue; `ack / retry / fail / heartbeat` on the job handle.
at enqueue (`delay`-wins-over-`run_at` resolution and
relative-`expires` pinned by
[ADR-020](decisions/020-enqueue-opt-semantics-and-bridges.md) §1/§2);
`ack / retry / fail / heartbeat` on the boxed `JobHandle` a claim
returns ([ADR-019](decisions/019-mechanism-handle-surfaces.md)).
- **Cut-flag context**: result storage is
[ADR-002](decisions/002-feature-scope.md)'s cut-flag row;
[ADR-010](decisions/010-queue-semantics-depth.md) §7 reconsidered it
@@ -139,7 +143,8 @@ made under; the ADRs carry the WHY.
opt) makes `sweep_expired` enforce a per-queue dead TTL. Honker's
no-retention posture kept as default; the mechanism is ours.
- **No redrive API in v1**: the recipe is `get_job` + fresh `enqueue`.
No consumer names an API shape; re-entry needs an OQ.
No consumer names an API shape; re-entry gates on a
consumer-inventory row first (the ADR-002 row-first discipline).
## Sweep / maintenance (ADR-010 §5–§6)
@@ -187,6 +192,8 @@ Collapsed into queues: no `Scheduler` handle, no schedule objects.
(the no-ambient-timers posture). The runner: leadership lock →
{renew (on loss, return before ticking — `Err(LeadershipLost)`,
distinct from clean `Ok(())` stop) → fire due boundaries → sleep}.
The `stop` parameter is a core-crate cloneable `StopToken`
([ADR-019](decisions/019-mechanism-handle-surfaces.md) §4).
Leadership lock: reserved name `__alkstore_scheduler`
(engine-derived name under the reserved prefix,
[ADR-008](decisions/008-contract-v1-pinning.md) §4).
@@ -201,7 +208,12 @@ Collapsed into queues: no `Scheduler` handle, no schedule objects.
- Each boundary fire enqueues ordinary work: `payload` into the named
queue with `ScheduleOpts { priority, max_attempts, expires }` —
stamped onto the enqueued job per
[ADR-010](decisions/010-queue-semantics-depth.md) §3a; the queue
[ADR-010](decisions/010-queue-semantics-depth.md) §3a; the three
`ScheduleOpts` fields apply over the target queue's **derived engine
defaults** for the stamps the fire doesn't carry (no queue handle is
open — the same derived-defaults posture as the outbox's backing
queue, [ADR-020](decisions/020-enqueue-opt-semantics-and-bridges.md)
§3); the queue
mechanism's guarantees apply, no separate delivery machinery.
- Schedule storage is engine-internal (SQLite: the forked substrate's
`__alkstore_scheduler_tasks` table; Postgres: the engine-owned
@@ -270,6 +282,8 @@ Collapsed into queues: no `Scheduler` handle, no schedule objects.
| [011](decisions/011-sqlite-substrate-fork.md) | Substrate fork | SQLite-side queue ops re-derived in owned code; `__alkstore_*` naming |
| [012](decisions/012-forked-substrate-design.md) | Fork design | contract-blind substrate boundary; fidelity posture; port deltas |
| [014](decisions/014-outbox-tx-enqueue.md) | Outbox tx enqueue | `outbox_enqueue_tx` on `TxHandle`; derived backing queue reached only through the outbox surface |
| [019](decisions/019-mechanism-handle-surfaces.md) | Handle surfaces | queue ops on the `Queue` handle, `JobHandle` from claims, `worker_id` identity, `Job`/`Schedule` shapes, core `StopToken` |
| [020](decisions/020-enqueue-opt-semantics-and-bridges.md) | Enqueue options | delay-over-run_at; relative `expires`; scheduler fires stamp from derived queue defaults |
## Open Questions