Add the dispatch job: idempotent task generation, backfill-capable

[os-warren]

Fixes#2

The spine. Active recurring duties become tasks, once per period, forever, without a lock.

Gates green at fe7941a (the merged head, origin/main merged in for #36/#38): pnpm validate ✓ · pnpm typecheck ✓ · pnpm test243 passed (7 files) · pnpm build ✓.

Metadata-first: what is declarative, and what could not be

Declarative: the schedule, its timezone, the retry policy, the timeout, the duty-selection filter, and the identity constraint the whole design rests on (duly_task_dispatch_identity, already on the object).

Imperative: the period arithmetic — calendar maths in a per-row IANA zone, which no filter language expresses — and the insert loop. Two files, so the boundary is a file boundary:

src/jobs/dispatch.plan.ts	Pure. Every scheduling decision. No I/O, no clock, no platform import. Rows in, rows out.
src/jobs/dispatch.job.ts	The defineJob metadata, plus ~40 lines that talk to the engine.

A scheduled flow was the alternative and was measured, not assumed. It is expressible (get_record → script → loop → create_record) and it was rejected on three findings:

1. Its error handling cannot tell a duplicate from a disaster.try_catch and fault edges swallow every failure identically, because the create_record executor collapses the engine error to a string with no code before either can see it. For the one job the product cannot afford to fail quietly, "the run succeeded and created nothing" is the wrong failure to make easy.
2. Backfill cannot reach a scheduled flow.ScheduleTrigger hands the flow { event, params: { jobId, flowName, schedule } } — no input channel. IJobService.trigger(name, data) forwards data to a job handler, which is how { from, to } gets in.
3. No retry policy or timeout.ScheduleTrigger calls jobService.schedule(name, schedule, handler) with no options; defineJob threads both.

The product docs settle the shape independently (data-model.md: "the dispatcher can be a plain idempotent job"; duty.object.ts names this file), so this is not a re-litigation of that decision — it is the evidence for why it still holds.

Idempotency: attempt the insert, then ask the data

The happy path is a bare insert. No read-then-write guard — that is a race two overlapping runs lose, and it costs a query on every task every night for a collision that is rare.

The interesting part is the failure path, and it does not classify the error. Measured on 17.2.0, ObjectQL rethrows the raw driver error, so a duplicate arrives as code: 'SQLITE_CONSTRAINT_UNIQUE' here and would be 23505 on Postgres; the platform's dialect-independent predicate isUniqueViolationError lives in @objectstack/types, which an application cannot resolve. Hard-coding one dialect or matching a message are both a consumer growing tolerance for a producer that will not answer.

So on failure it asks the data, which every driver answers the same way: is the row there now?

• Present → the obligation exists exactly once, whoever won the race. Counted as existing. A run that inserts nothing because everything already exists is a successful run.
• Absent → the insert failed for a reason that is not "already dispatched". Re-thrown, so the run fails. That is the half a blanket swallow gets wrong.

The gap this could not close: a job handler has no data reach

Measured: a defineJob handler is invoked with exactly { jobId, data, bundle } — no engine, no service registry, no logger. So the one metadata shape the platform offers for scheduled work cannot, by itself, write a record.

Not worked around silently. runDispatch(engine, …) takes its engine as an argument; bindDispatchEngine is the one named seam; and until a host calls it dulyDispatchrefuses loudly, naming the wiring, rather than reporting a clean night on which nothing was dispatched.

• A defineJob handler is invoked with { jobId, data, bundle } and no data reach, so the platform's only scheduled-work metadata shape cannot read or write a record objectstack#14094 — the handler-context gap (measured probe, suggested one-line direction, additive).
• An application told to rely on a unique index cannot recognise the violation: ObjectQL rethrows the raw driver error and isUniqueViolationError is not reachable from an app objectstack#14095 — an app cannot recognise a uniqueness violation.
• Wire the dispatch job's engine at onEnable — one line, in the file #4 currently owns #42 (this repo) — the one-line onEnable wire. It lands in src/actions/register-handlers.ts, which One-click completion with undo, and skip-with-reason #4 owns and is editing now, so it is split out with Blocked-by: #4 rather than taken here. Until Wire the dispatch job's engine at onEnable — one line, in the file #4 currently owns #42 lands the job does not dispatch at runtime — loudly, by design.

Semantics worth reviewing

• One UTC pass, every zone resolved locally. The question asked per duty is "is this period's task due to exist yet", never "is it midnight here". Pinned: at 2026-08-31T20:00Z an Asia/Shanghai duty gets 2026-09 and an America/Los_Angeles duty gets 2026-08, on the same run.
• Which periods a scheduled run emits. The current period unconditionally — visible_from governs when a task shows up, not whether it exists — plus any later period whose lead window has already opened. The look-ahead is bounded at today + lead_days, which is exact rather than generous.
• Two effective-window tests. Duty-level on today (the scheduled run's selection rule, per the card); period-level on due_date, always. That second one is what stops a backfill inventing obligations that predate the duty, and it is why a backfill of a duty whose window has closed still works.
• The effective window is deliberately not in the SQL filter.effective_from/effective_to are calendar days in the duty's own zone, and "today" is a different day in Auckland and Los Angeles at one instant, so no single predicate is right for every row it matches. The query filters only the two zone-independent facts; the window test lives where the zone is known.
• last_dispatched_period advances, never regresses. Keys of one frequency are fixed-width and zero-padded, so a lexical compare is chronological. A run that created nothing writes nothing — which is also why a second identical run issues zero writes of any kind.
• The stagnation clock is untouched. The dispatcher writes duly_duty and never duly_task. Asserted directly: a spy engine records every update target across two runs at two clocks and duly_task must not appear.
• Backfill input is validated, not guessed.to on its own is refused — it could only mean "since the duty began", and effective_from is nullable, so that window has no floor.
• Paged reads. An unbounded sweep fails by dispatching a prefix of the duties, with no error anywhere.

Tests — and why they run on sqlite

test/dispatch.test.ts, 55 tests, three layers: wiring, the pure planner, and idempotency against a real booted engine.

The engine is sqlite, not memory, and that is the load-bearing choice. Measured: InMemoryDriver.create is a table.push() that stores no constraints, so two identical duly_task inserts both succeed and the table ends with two rows. A dispatcher suite on the memory driver reports idempotency passing while the index providing it was never consulted. One test asserts the index is genuinely enforced, so the suite cannot go green by absence.

Two ablations, each committed first, each confirmed on disk, each restored by a trap:

ablation	on-disk confirmation	result
sqlite → memory driver	removed-literal 1 → 0, injected-literal count 1, git diff --stat non-empty	4 red, including "the index is real on this engine" — the sqlite choice is load-bearing
dispatcher updates an existing duly_task row	anchor 1 → 0, injected engine.update('duly_task' count 1	1 red — exactly the stagnation-clock guard

Both restored clean (git status empty after each). Independent evidence that the suite bites: it caught a real bug during the first run — with lead_days: 0 the look-ahead passed the run's instant as from and midnight-of-today as to, so periodsBetween returned [] and every zero-lead duty silently dispatched nothing. Fixed, and the comment says why.

Acceptance criteria, each with a test: two runs → zero second-pass inserts · two concurrent runs → one task · Shanghai vs Los Angeles on one instant · standing produces nothing in any run · paused produces nothing and un-pausing produces only the current period, not the gap · last_dispatched_period advances and never regresses · a 13-month backfill produces exactly the expected key set and a second inserts nothing.

Files, and one note on scope

src/jobs/dispatch.job.ts, src/jobs/dispatch.plan.ts, src/jobs/index.ts, test/dispatch.test.ts — all inside the declared surface.

One addition outside it, named here rather than buried:src/functions/index.ts, to register the handler in dulyFunctions. A job needs two registrations — the schedule in dulyJobs and the handler in the functions map — and AppPlugin resolves the second as collectBundleFunctions(bundle)[job.handler], logging job handler not found in bundle.functions — skipping on a miss. Without that entry the job is registered, listed, validated, and never executed, with no author-time gate. The file is held by no other round-2 claim, and a test performs the same lookup the runtime performs.

objectstack.config.ts was not touched; the barrels were sufficient.

---

Generated by Claude Code

[os-warren]

Fixes#2

The spine. Active recurring duties become tasks, once per period, forever, without a lock.

Gates green at fe7941a (the merged head, origin/main merged in for #36/#38): pnpm validate ✓ · pnpm typecheck ✓ · pnpm test243 passed (7 files) · pnpm build ✓.

Metadata-first: what is declarative, and what could not be

Declarative: the schedule, its timezone, the retry policy, the timeout, the duty-selection filter, and the identity constraint the whole design rests on (duly_task_dispatch_identity, already on the object).

Imperative: the period arithmetic — calendar maths in a per-row IANA zone, which no filter language expresses — and the insert loop. Two files, so the boundary is a file boundary:

src/jobs/dispatch.plan.ts	Pure. Every scheduling decision. No I/O, no clock, no platform import. Rows in, rows out.
src/jobs/dispatch.job.ts	The defineJob metadata, plus ~40 lines that talk to the engine.

A scheduled flow was the alternative and was measured, not assumed. It is expressible (get_record → script → loop → create_record) and it was rejected on three findings:

1. Its error handling cannot tell a duplicate from a disaster.try_catch and fault edges swallow every failure identically, because the create_record executor collapses the engine error to a string with no code before either can see it. For the one job the product cannot afford to fail quietly, "the run succeeded and created nothing" is the wrong failure to make easy.
2. Backfill cannot reach a scheduled flow.ScheduleTrigger hands the flow { event, params: { jobId, flowName, schedule } } — no input channel. IJobService.trigger(name, data) forwards data to a job handler, which is how { from, to } gets in.
3. No retry policy or timeout.ScheduleTrigger calls jobService.schedule(name, schedule, handler) with no options; defineJob threads both.

The product docs settle the shape independently (data-model.md: "the dispatcher can be a plain idempotent job"; duty.object.ts names this file), so this is not a re-litigation of that decision — it is the evidence for why it still holds.

Idempotency: attempt the insert, then ask the data

The happy path is a bare insert. No read-then-write guard — that is a race two overlapping runs lose, and it costs a query on every task every night for a collision that is rare.

The interesting part is the failure path, and it does not classify the error. Measured on 17.2.0, ObjectQL rethrows the raw driver error, so a duplicate arrives as code: 'SQLITE_CONSTRAINT_UNIQUE' here and would be 23505 on Postgres; the platform's dialect-independent predicate isUniqueViolationError lives in @objectstack/types, which an application cannot resolve. Hard-coding one dialect or matching a message are both a consumer growing tolerance for a producer that will not answer.

So on failure it asks the data, which every driver answers the same way: is the row there now?

• Present → the obligation exists exactly once, whoever won the race. Counted as existing. A run that inserts nothing because everything already exists is a successful run.
• Absent → the insert failed for a reason that is not "already dispatched". Re-thrown, so the run fails. That is the half a blanket swallow gets wrong.

The gap this could not close: a job handler has no data reach

Measured: a defineJob handler is invoked with exactly { jobId, data, bundle } — no engine, no service registry, no logger. So the one metadata shape the platform offers for scheduled work cannot, by itself, write a record.

Not worked around silently. runDispatch(engine, …) takes its engine as an argument; bindDispatchEngine is the one named seam; and until a host calls it dulyDispatchrefuses loudly, naming the wiring, rather than reporting a clean night on which nothing was dispatched.

• A defineJob handler is invoked with { jobId, data, bundle } and no data reach, so the platform's only scheduled-work metadata shape cannot read or write a record objectstack#14094 — the handler-context gap (measured probe, suggested one-line direction, additive).
• An application told to rely on a unique index cannot recognise the violation: ObjectQL rethrows the raw driver error and isUniqueViolationError is not reachable from an app objectstack#14095 — an app cannot recognise a uniqueness violation.
• Wire the dispatch job's engine at onEnable — one line, in the file #4 currently owns #42 (this repo) — the one-line onEnable wire. It lands in src/actions/register-handlers.ts, which One-click completion with undo, and skip-with-reason #4 owns and is editing now, so it is split out with Blocked-by: #4 rather than taken here. Until Wire the dispatch job's engine at onEnable — one line, in the file #4 currently owns #42 lands the job does not dispatch at runtime — loudly, by design.

Semantics worth reviewing

• One UTC pass, every zone resolved locally. The question asked per duty is "is this period's task due to exist yet", never "is it midnight here". Pinned: at 2026-08-31T20:00Z an Asia/Shanghai duty gets 2026-09 and an America/Los_Angeles duty gets 2026-08, on the same run.
• Which periods a scheduled run emits. The current period unconditionally — visible_from governs when a task shows up, not whether it exists — plus any later period whose lead window has already opened. The look-ahead is bounded at today + lead_days, which is exact rather than generous.
• Two effective-window tests. Duty-level on today (the scheduled run's selection rule, per the card); period-level on due_date, always. That second one is what stops a backfill inventing obligations that predate the duty, and it is why a backfill of a duty whose window has closed still works.
• The effective window is deliberately not in the SQL filter.effective_from/effective_to are calendar days in the duty's own zone, and "today" is a different day in Auckland and Los Angeles at one instant, so no single predicate is right for every row it matches. The query filters only the two zone-independent facts; the window test lives where the zone is known.
• last_dispatched_period advances, never regresses. Keys of one frequency are fixed-width and zero-padded, so a lexical compare is chronological. A run that created nothing writes nothing — which is also why a second identical run issues zero writes of any kind.
• The stagnation clock is untouched. The dispatcher writes duly_duty and never duly_task. Asserted directly: a spy engine records every update target across two runs at two clocks and duly_task must not appear.
• Backfill input is validated, not guessed.to on its own is refused — it could only mean "since the duty began", and effective_from is nullable, so that window has no floor.
• Paged reads. An unbounded sweep fails by dispatching a prefix of the duties, with no error anywhere.

Tests — and why they run on sqlite

test/dispatch.test.ts, 55 tests, three layers: wiring, the pure planner, and idempotency against a real booted engine.

The engine is sqlite, not memory, and that is the load-bearing choice. Measured: InMemoryDriver.create is a table.push() that stores no constraints, so two identical duly_task inserts both succeed and the table ends with two rows. A dispatcher suite on the memory driver reports idempotency passing while the index providing it was never consulted. One test asserts the index is genuinely enforced, so the suite cannot go green by absence.

Two ablations, each committed first, each confirmed on disk, each restored by a trap:

ablation	on-disk confirmation	result
sqlite → memory driver	removed-literal 1 → 0, injected-literal count 1, git diff --stat non-empty	4 red, including "the index is real on this engine" — the sqlite choice is load-bearing
dispatcher updates an existing duly_task row	anchor 1 → 0, injected engine.update('duly_task' count 1	1 red — exactly the stagnation-clock guard

Both restored clean (git status empty after each). Independent evidence that the suite bites: it caught a real bug during the first run — with lead_days: 0 the look-ahead passed the run's instant as from and midnight-of-today as to, so periodsBetween returned [] and every zero-lead duty silently dispatched nothing. Fixed, and the comment says why.

Acceptance criteria, each with a test: two runs → zero second-pass inserts · two concurrent runs → one task · Shanghai vs Los Angeles on one instant · standing produces nothing in any run · paused produces nothing and un-pausing produces only the current period, not the gap · last_dispatched_period advances and never regresses · a 13-month backfill produces exactly the expected key set and a second inserts nothing.

Files, and one note on scope

src/jobs/dispatch.job.ts, src/jobs/dispatch.plan.ts, src/jobs/index.ts, test/dispatch.test.ts — all inside the declared surface.

One addition outside it, named here rather than buried:src/functions/index.ts, to register the handler in dulyFunctions. A job needs two registrations — the schedule in dulyJobs and the handler in the functions map — and AppPlugin resolves the second as collectBundleFunctions(bundle)[job.handler], logging job handler not found in bundle.functions — skipping on a miss. Without that entry the job is registered, listed, validated, and never executed, with no author-time gate. The file is held by no other round-2 claim, and a test performs the same lookup the runtime performs.

objectstack.config.ts was not touched; the barrels were sufficient.

---

Generated by Claude Code

[os-warren]

Fixes#2

The spine. Active recurring duties become tasks, once per period, forever, without a lock.

Gates green at fe7941a (the merged head, origin/main merged in for #36/#38): pnpm validate ✓ · pnpm typecheck ✓ · pnpm test243 passed (7 files) · pnpm build ✓.

Metadata-first: what is declarative, and what could not be

Declarative: the schedule, its timezone, the retry policy, the timeout, the duty-selection filter, and the identity constraint the whole design rests on (duly_task_dispatch_identity, already on the object).

Imperative: the period arithmetic — calendar maths in a per-row IANA zone, which no filter language expresses — and the insert loop. Two files, so the boundary is a file boundary:

src/jobs/dispatch.plan.ts	Pure. Every scheduling decision. No I/O, no clock, no platform import. Rows in, rows out.
src/jobs/dispatch.job.ts	The defineJob metadata, plus ~40 lines that talk to the engine.

A scheduled flow was the alternative and was measured, not assumed. It is expressible (get_record → script → loop → create_record) and it was rejected on three findings:

1. Its error handling cannot tell a duplicate from a disaster.try_catch and fault edges swallow every failure identically, because the create_record executor collapses the engine error to a string with no code before either can see it. For the one job the product cannot afford to fail quietly, "the run succeeded and created nothing" is the wrong failure to make easy.
2. Backfill cannot reach a scheduled flow.ScheduleTrigger hands the flow { event, params: { jobId, flowName, schedule } } — no input channel. IJobService.trigger(name, data) forwards data to a job handler, which is how { from, to } gets in.
3. No retry policy or timeout.ScheduleTrigger calls jobService.schedule(name, schedule, handler) with no options; defineJob threads both.

The product docs settle the shape independently (data-model.md: "the dispatcher can be a plain idempotent job"; duty.object.ts names this file), so this is not a re-litigation of that decision — it is the evidence for why it still holds.

Idempotency: attempt the insert, then ask the data

The happy path is a bare insert. No read-then-write guard — that is a race two overlapping runs lose, and it costs a query on every task every night for a collision that is rare.

The interesting part is the failure path, and it does not classify the error. Measured on 17.2.0, ObjectQL rethrows the raw driver error, so a duplicate arrives as code: 'SQLITE_CONSTRAINT_UNIQUE' here and would be 23505 on Postgres; the platform's dialect-independent predicate isUniqueViolationError lives in @objectstack/types, which an application cannot resolve. Hard-coding one dialect or matching a message are both a consumer growing tolerance for a producer that will not answer.

So on failure it asks the data, which every driver answers the same way: is the row there now?

• Present → the obligation exists exactly once, whoever won the race. Counted as existing. A run that inserts nothing because everything already exists is a successful run.
• Absent → the insert failed for a reason that is not "already dispatched". Re-thrown, so the run fails. That is the half a blanket swallow gets wrong.

The gap this could not close: a job handler has no data reach

Measured: a defineJob handler is invoked with exactly { jobId, data, bundle } — no engine, no service registry, no logger. So the one metadata shape the platform offers for scheduled work cannot, by itself, write a record.

Not worked around silently. runDispatch(engine, …) takes its engine as an argument; bindDispatchEngine is the one named seam; and until a host calls it dulyDispatchrefuses loudly, naming the wiring, rather than reporting a clean night on which nothing was dispatched.

• A defineJob handler is invoked with { jobId, data, bundle } and no data reach, so the platform's only scheduled-work metadata shape cannot read or write a record objectstack#14094 — the handler-context gap (measured probe, suggested one-line direction, additive).
• An application told to rely on a unique index cannot recognise the violation: ObjectQL rethrows the raw driver error and isUniqueViolationError is not reachable from an app objectstack#14095 — an app cannot recognise a uniqueness violation.
• Wire the dispatch job's engine at onEnable — one line, in the file #4 currently owns #42 (this repo) — the one-line onEnable wire. It lands in src/actions/register-handlers.ts, which One-click completion with undo, and skip-with-reason #4 owns and is editing now, so it is split out with Blocked-by: #4 rather than taken here. Until Wire the dispatch job's engine at onEnable — one line, in the file #4 currently owns #42 lands the job does not dispatch at runtime — loudly, by design.

Semantics worth reviewing

• One UTC pass, every zone resolved locally. The question asked per duty is "is this period's task due to exist yet", never "is it midnight here". Pinned: at 2026-08-31T20:00Z an Asia/Shanghai duty gets 2026-09 and an America/Los_Angeles duty gets 2026-08, on the same run.
• Which periods a scheduled run emits. The current period unconditionally — visible_from governs when a task shows up, not whether it exists — plus any later period whose lead window has already opened. The look-ahead is bounded at today + lead_days, which is exact rather than generous.
• Two effective-window tests. Duty-level on today (the scheduled run's selection rule, per the card); period-level on due_date, always. That second one is what stops a backfill inventing obligations that predate the duty, and it is why a backfill of a duty whose window has closed still works.
• The effective window is deliberately not in the SQL filter.effective_from/effective_to are calendar days in the duty's own zone, and "today" is a different day in Auckland and Los Angeles at one instant, so no single predicate is right for every row it matches. The query filters only the two zone-independent facts; the window test lives where the zone is known.
• last_dispatched_period advances, never regresses. Keys of one frequency are fixed-width and zero-padded, so a lexical compare is chronological. A run that created nothing writes nothing — which is also why a second identical run issues zero writes of any kind.
• The stagnation clock is untouched. The dispatcher writes duly_duty and never duly_task. Asserted directly: a spy engine records every update target across two runs at two clocks and duly_task must not appear.
• Backfill input is validated, not guessed.to on its own is refused — it could only mean "since the duty began", and effective_from is nullable, so that window has no floor.
• Paged reads. An unbounded sweep fails by dispatching a prefix of the duties, with no error anywhere.

Tests — and why they run on sqlite

test/dispatch.test.ts, 55 tests, three layers: wiring, the pure planner, and idempotency against a real booted engine.

The engine is sqlite, not memory, and that is the load-bearing choice. Measured: InMemoryDriver.create is a table.push() that stores no constraints, so two identical duly_task inserts both succeed and the table ends with two rows. A dispatcher suite on the memory driver reports idempotency passing while the index providing it was never consulted. One test asserts the index is genuinely enforced, so the suite cannot go green by absence.

Two ablations, each committed first, each confirmed on disk, each restored by a trap:

ablation	on-disk confirmation	result
sqlite → memory driver	removed-literal 1 → 0, injected-literal count 1, git diff --stat non-empty	4 red, including "the index is real on this engine" — the sqlite choice is load-bearing
dispatcher updates an existing duly_task row	anchor 1 → 0, injected engine.update('duly_task' count 1	1 red — exactly the stagnation-clock guard

Both restored clean (git status empty after each). Independent evidence that the suite bites: it caught a real bug during the first run — with lead_days: 0 the look-ahead passed the run's instant as from and midnight-of-today as to, so periodsBetween returned [] and every zero-lead duty silently dispatched nothing. Fixed, and the comment says why.

Acceptance criteria, each with a test: two runs → zero second-pass inserts · two concurrent runs → one task · Shanghai vs Los Angeles on one instant · standing produces nothing in any run · paused produces nothing and un-pausing produces only the current period, not the gap · last_dispatched_period advances and never regresses · a 13-month backfill produces exactly the expected key set and a second inserts nothing.

Files, and one note on scope

src/jobs/dispatch.job.ts, src/jobs/dispatch.plan.ts, src/jobs/index.ts, test/dispatch.test.ts — all inside the declared surface.

One addition outside it, named here rather than buried:src/functions/index.ts, to register the handler in dulyFunctions. A job needs two registrations — the schedule in dulyJobs and the handler in the functions map — and AppPlugin resolves the second as collectBundleFunctions(bundle)[job.handler], logging job handler not found in bundle.functions — skipping on a miss. Without that entry the job is registered, listed, validated, and never executed, with no author-time gate. The file is held by no other round-2 claim, and a test performs the same lookup the runtime performs.

objectstack.config.ts was not touched; the barrels were sufficient.

---

Generated by Claude Code

[os-warren]

Fixes#2

The spine. Active recurring duties become tasks, once per period, forever, without a lock.

Gates green at fe7941a (the merged head, origin/main merged in for #36/#38): pnpm validate ✓ · pnpm typecheck ✓ · pnpm test243 passed (7 files) · pnpm build ✓.

Metadata-first: what is declarative, and what could not be

Declarative: the schedule, its timezone, the retry policy, the timeout, the duty-selection filter, and the identity constraint the whole design rests on (duly_task_dispatch_identity, already on the object).

Imperative: the period arithmetic — calendar maths in a per-row IANA zone, which no filter language expresses — and the insert loop. Two files, so the boundary is a file boundary:

src/jobs/dispatch.plan.ts	Pure. Every scheduling decision. No I/O, no clock, no platform import. Rows in, rows out.
src/jobs/dispatch.job.ts	The defineJob metadata, plus ~40 lines that talk to the engine.

A scheduled flow was the alternative and was measured, not assumed. It is expressible (get_record → script → loop → create_record) and it was rejected on three findings:

1. Its error handling cannot tell a duplicate from a disaster.try_catch and fault edges swallow every failure identically, because the create_record executor collapses the engine error to a string with no code before either can see it. For the one job the product cannot afford to fail quietly, "the run succeeded and created nothing" is the wrong failure to make easy.
2. Backfill cannot reach a scheduled flow.ScheduleTrigger hands the flow { event, params: { jobId, flowName, schedule } } — no input channel. IJobService.trigger(name, data) forwards data to a job handler, which is how { from, to } gets in.
3. No retry policy or timeout.ScheduleTrigger calls jobService.schedule(name, schedule, handler) with no options; defineJob threads both.

The product docs settle the shape independently (data-model.md: "the dispatcher can be a plain idempotent job"; duty.object.ts names this file), so this is not a re-litigation of that decision — it is the evidence for why it still holds.

Idempotency: attempt the insert, then ask the data

The happy path is a bare insert. No read-then-write guard — that is a race two overlapping runs lose, and it costs a query on every task every night for a collision that is rare.

The interesting part is the failure path, and it does not classify the error. Measured on 17.2.0, ObjectQL rethrows the raw driver error, so a duplicate arrives as code: 'SQLITE_CONSTRAINT_UNIQUE' here and would be 23505 on Postgres; the platform's dialect-independent predicate isUniqueViolationError lives in @objectstack/types, which an application cannot resolve. Hard-coding one dialect or matching a message are both a consumer growing tolerance for a producer that will not answer.

So on failure it asks the data, which every driver answers the same way: is the row there now?

• Present → the obligation exists exactly once, whoever won the race. Counted as existing. A run that inserts nothing because everything already exists is a successful run.
• Absent → the insert failed for a reason that is not "already dispatched". Re-thrown, so the run fails. That is the half a blanket swallow gets wrong.

The gap this could not close: a job handler has no data reach

Measured: a defineJob handler is invoked with exactly { jobId, data, bundle } — no engine, no service registry, no logger. So the one metadata shape the platform offers for scheduled work cannot, by itself, write a record.

Not worked around silently. runDispatch(engine, …) takes its engine as an argument; bindDispatchEngine is the one named seam; and until a host calls it dulyDispatchrefuses loudly, naming the wiring, rather than reporting a clean night on which nothing was dispatched.

• A defineJob handler is invoked with { jobId, data, bundle } and no data reach, so the platform's only scheduled-work metadata shape cannot read or write a record objectstack#14094 — the handler-context gap (measured probe, suggested one-line direction, additive).
• An application told to rely on a unique index cannot recognise the violation: ObjectQL rethrows the raw driver error and isUniqueViolationError is not reachable from an app objectstack#14095 — an app cannot recognise a uniqueness violation.
• Wire the dispatch job's engine at onEnable — one line, in the file #4 currently owns #42 (this repo) — the one-line onEnable wire. It lands in src/actions/register-handlers.ts, which One-click completion with undo, and skip-with-reason #4 owns and is editing now, so it is split out with Blocked-by: #4 rather than taken here. Until Wire the dispatch job's engine at onEnable — one line, in the file #4 currently owns #42 lands the job does not dispatch at runtime — loudly, by design.

Semantics worth reviewing

• One UTC pass, every zone resolved locally. The question asked per duty is "is this period's task due to exist yet", never "is it midnight here". Pinned: at 2026-08-31T20:00Z an Asia/Shanghai duty gets 2026-09 and an America/Los_Angeles duty gets 2026-08, on the same run.
• Which periods a scheduled run emits. The current period unconditionally — visible_from governs when a task shows up, not whether it exists — plus any later period whose lead window has already opened. The look-ahead is bounded at today + lead_days, which is exact rather than generous.
• Two effective-window tests. Duty-level on today (the scheduled run's selection rule, per the card); period-level on due_date, always. That second one is what stops a backfill inventing obligations that predate the duty, and it is why a backfill of a duty whose window has closed still works.
• The effective window is deliberately not in the SQL filter.effective_from/effective_to are calendar days in the duty's own zone, and "today" is a different day in Auckland and Los Angeles at one instant, so no single predicate is right for every row it matches. The query filters only the two zone-independent facts; the window test lives where the zone is known.
• last_dispatched_period advances, never regresses. Keys of one frequency are fixed-width and zero-padded, so a lexical compare is chronological. A run that created nothing writes nothing — which is also why a second identical run issues zero writes of any kind.
• The stagnation clock is untouched. The dispatcher writes duly_duty and never duly_task. Asserted directly: a spy engine records every update target across two runs at two clocks and duly_task must not appear.
• Backfill input is validated, not guessed.to on its own is refused — it could only mean "since the duty began", and effective_from is nullable, so that window has no floor.
• Paged reads. An unbounded sweep fails by dispatching a prefix of the duties, with no error anywhere.

Tests — and why they run on sqlite

test/dispatch.test.ts, 55 tests, three layers: wiring, the pure planner, and idempotency against a real booted engine.

The engine is sqlite, not memory, and that is the load-bearing choice. Measured: InMemoryDriver.create is a table.push() that stores no constraints, so two identical duly_task inserts both succeed and the table ends with two rows. A dispatcher suite on the memory driver reports idempotency passing while the index providing it was never consulted. One test asserts the index is genuinely enforced, so the suite cannot go green by absence.

Two ablations, each committed first, each confirmed on disk, each restored by a trap:

ablation	on-disk confirmation	result
sqlite → memory driver	removed-literal 1 → 0, injected-literal count 1, git diff --stat non-empty	4 red, including "the index is real on this engine" — the sqlite choice is load-bearing
dispatcher updates an existing duly_task row	anchor 1 → 0, injected engine.update('duly_task' count 1	1 red — exactly the stagnation-clock guard

Both restored clean (git status empty after each). Independent evidence that the suite bites: it caught a real bug during the first run — with lead_days: 0 the look-ahead passed the run's instant as from and midnight-of-today as to, so periodsBetween returned [] and every zero-lead duty silently dispatched nothing. Fixed, and the comment says why.

Acceptance criteria, each with a test: two runs → zero second-pass inserts · two concurrent runs → one task · Shanghai vs Los Angeles on one instant · standing produces nothing in any run · paused produces nothing and un-pausing produces only the current period, not the gap · last_dispatched_period advances and never regresses · a 13-month backfill produces exactly the expected key set and a second inserts nothing.

Files, and one note on scope

src/jobs/dispatch.job.ts, src/jobs/dispatch.plan.ts, src/jobs/index.ts, test/dispatch.test.ts — all inside the declared surface.

One addition outside it, named here rather than buried:src/functions/index.ts, to register the handler in dulyFunctions. A job needs two registrations — the schedule in dulyJobs and the handler in the functions map — and AppPlugin resolves the second as collectBundleFunctions(bundle)[job.handler], logging job handler not found in bundle.functions — skipping on a miss. Without that entry the job is registered, listed, validated, and never executed, with no author-time gate. The file is held by no other round-2 claim, and a test performs the same lookup the runtime performs.

objectstack.config.ts was not touched; the barrels were sufficient.

---

Generated by Claude Code

[os-warren]

Fixes#2

The spine. Active recurring duties become tasks, once per period, forever, without a lock.

Gates green at fe7941a (the merged head, origin/main merged in for #36/#38): pnpm validate ✓ · pnpm typecheck ✓ · pnpm test243 passed (7 files) · pnpm build ✓.

Metadata-first: what is declarative, and what could not be

Declarative: the schedule, its timezone, the retry policy, the timeout, the duty-selection filter, and the identity constraint the whole design rests on (duly_task_dispatch_identity, already on the object).

Imperative: the period arithmetic — calendar maths in a per-row IANA zone, which no filter language expresses — and the insert loop. Two files, so the boundary is a file boundary:

src/jobs/dispatch.plan.ts	Pure. Every scheduling decision. No I/O, no clock, no platform import. Rows in, rows out.
src/jobs/dispatch.job.ts	The defineJob metadata, plus ~40 lines that talk to the engine.

A scheduled flow was the alternative and was measured, not assumed. It is expressible (get_record → script → loop → create_record) and it was rejected on three findings:

1. Its error handling cannot tell a duplicate from a disaster.try_catch and fault edges swallow every failure identically, because the create_record executor collapses the engine error to a string with no code before either can see it. For the one job the product cannot afford to fail quietly, "the run succeeded and created nothing" is the wrong failure to make easy.
2. Backfill cannot reach a scheduled flow.ScheduleTrigger hands the flow { event, params: { jobId, flowName, schedule } } — no input channel. IJobService.trigger(name, data) forwards data to a job handler, which is how { from, to } gets in.
3. No retry policy or timeout.ScheduleTrigger calls jobService.schedule(name, schedule, handler) with no options; defineJob threads both.

The product docs settle the shape independently (data-model.md: "the dispatcher can be a plain idempotent job"; duty.object.ts names this file), so this is not a re-litigation of that decision — it is the evidence for why it still holds.

Idempotency: attempt the insert, then ask the data

The happy path is a bare insert. No read-then-write guard — that is a race two overlapping runs lose, and it costs a query on every task every night for a collision that is rare.

The interesting part is the failure path, and it does not classify the error. Measured on 17.2.0, ObjectQL rethrows the raw driver error, so a duplicate arrives as code: 'SQLITE_CONSTRAINT_UNIQUE' here and would be 23505 on Postgres; the platform's dialect-independent predicate isUniqueViolationError lives in @objectstack/types, which an application cannot resolve. Hard-coding one dialect or matching a message are both a consumer growing tolerance for a producer that will not answer.

So on failure it asks the data, which every driver answers the same way: is the row there now?

• Present → the obligation exists exactly once, whoever won the race. Counted as existing. A run that inserts nothing because everything already exists is a successful run.
• Absent → the insert failed for a reason that is not "already dispatched". Re-thrown, so the run fails. That is the half a blanket swallow gets wrong.

The gap this could not close: a job handler has no data reach

Measured: a defineJob handler is invoked with exactly { jobId, data, bundle } — no engine, no service registry, no logger. So the one metadata shape the platform offers for scheduled work cannot, by itself, write a record.

Not worked around silently. runDispatch(engine, …) takes its engine as an argument; bindDispatchEngine is the one named seam; and until a host calls it dulyDispatchrefuses loudly, naming the wiring, rather than reporting a clean night on which nothing was dispatched.

• A defineJob handler is invoked with { jobId, data, bundle } and no data reach, so the platform's only scheduled-work metadata shape cannot read or write a record objectstack#14094 — the handler-context gap (measured probe, suggested one-line direction, additive).
• An application told to rely on a unique index cannot recognise the violation: ObjectQL rethrows the raw driver error and isUniqueViolationError is not reachable from an app objectstack#14095 — an app cannot recognise a uniqueness violation.
• Wire the dispatch job's engine at onEnable — one line, in the file #4 currently owns #42 (this repo) — the one-line onEnable wire. It lands in src/actions/register-handlers.ts, which One-click completion with undo, and skip-with-reason #4 owns and is editing now, so it is split out with Blocked-by: #4 rather than taken here. Until Wire the dispatch job's engine at onEnable — one line, in the file #4 currently owns #42 lands the job does not dispatch at runtime — loudly, by design.

Semantics worth reviewing

• One UTC pass, every zone resolved locally. The question asked per duty is "is this period's task due to exist yet", never "is it midnight here". Pinned: at 2026-08-31T20:00Z an Asia/Shanghai duty gets 2026-09 and an America/Los_Angeles duty gets 2026-08, on the same run.
• Which periods a scheduled run emits. The current period unconditionally — visible_from governs when a task shows up, not whether it exists — plus any later period whose lead window has already opened. The look-ahead is bounded at today + lead_days, which is exact rather than generous.
• Two effective-window tests. Duty-level on today (the scheduled run's selection rule, per the card); period-level on due_date, always. That second one is what stops a backfill inventing obligations that predate the duty, and it is why a backfill of a duty whose window has closed still works.
• The effective window is deliberately not in the SQL filter.effective_from/effective_to are calendar days in the duty's own zone, and "today" is a different day in Auckland and Los Angeles at one instant, so no single predicate is right for every row it matches. The query filters only the two zone-independent facts; the window test lives where the zone is known.
• last_dispatched_period advances, never regresses. Keys of one frequency are fixed-width and zero-padded, so a lexical compare is chronological. A run that created nothing writes nothing — which is also why a second identical run issues zero writes of any kind.
• The stagnation clock is untouched. The dispatcher writes duly_duty and never duly_task. Asserted directly: a spy engine records every update target across two runs at two clocks and duly_task must not appear.
• Backfill input is validated, not guessed.to on its own is refused — it could only mean "since the duty began", and effective_from is nullable, so that window has no floor.
• Paged reads. An unbounded sweep fails by dispatching a prefix of the duties, with no error anywhere.

Tests — and why they run on sqlite

test/dispatch.test.ts, 55 tests, three layers: wiring, the pure planner, and idempotency against a real booted engine.

The engine is sqlite, not memory, and that is the load-bearing choice. Measured: InMemoryDriver.create is a table.push() that stores no constraints, so two identical duly_task inserts both succeed and the table ends with two rows. A dispatcher suite on the memory driver reports idempotency passing while the index providing it was never consulted. One test asserts the index is genuinely enforced, so the suite cannot go green by absence.

Two ablations, each committed first, each confirmed on disk, each restored by a trap:

ablation	on-disk confirmation	result
sqlite → memory driver	removed-literal 1 → 0, injected-literal count 1, git diff --stat non-empty	4 red, including "the index is real on this engine" — the sqlite choice is load-bearing
dispatcher updates an existing duly_task row	anchor 1 → 0, injected engine.update('duly_task' count 1	1 red — exactly the stagnation-clock guard

Both restored clean (git status empty after each). Independent evidence that the suite bites: it caught a real bug during the first run — with lead_days: 0 the look-ahead passed the run's instant as from and midnight-of-today as to, so periodsBetween returned [] and every zero-lead duty silently dispatched nothing. Fixed, and the comment says why.

Acceptance criteria, each with a test: two runs → zero second-pass inserts · two concurrent runs → one task · Shanghai vs Los Angeles on one instant · standing produces nothing in any run · paused produces nothing and un-pausing produces only the current period, not the gap · last_dispatched_period advances and never regresses · a 13-month backfill produces exactly the expected key set and a second inserts nothing.

Files, and one note on scope

src/jobs/dispatch.job.ts, src/jobs/dispatch.plan.ts, src/jobs/index.ts, test/dispatch.test.ts — all inside the declared surface.

One addition outside it, named here rather than buried:src/functions/index.ts, to register the handler in dulyFunctions. A job needs two registrations — the schedule in dulyJobs and the handler in the functions map — and AppPlugin resolves the second as collectBundleFunctions(bundle)[job.handler], logging job handler not found in bundle.functions — skipping on a miss. Without that entry the job is registered, listed, validated, and never executed, with no author-time gate. The file is held by no other round-2 claim, and a test performs the same lookup the runtime performs.

objectstack.config.ts was not touched; the barrels were sufficient.

---

Generated by Claude Code

[os-warren]

Fixes#2

The spine. Active recurring duties become tasks, once per period, forever, without a lock.

Gates green at fe7941a (the merged head, origin/main merged in for #36/#38): pnpm validate ✓ · pnpm typecheck ✓ · pnpm test243 passed (7 files) · pnpm build ✓.

Metadata-first: what is declarative, and what could not be

Declarative: the schedule, its timezone, the retry policy, the timeout, the duty-selection filter, and the identity constraint the whole design rests on (duly_task_dispatch_identity, already on the object).

Imperative: the period arithmetic — calendar maths in a per-row IANA zone, which no filter language expresses — and the insert loop. Two files, so the boundary is a file boundary:

src/jobs/dispatch.plan.ts	Pure. Every scheduling decision. No I/O, no clock, no platform import. Rows in, rows out.
src/jobs/dispatch.job.ts	The defineJob metadata, plus ~40 lines that talk to the engine.

A scheduled flow was the alternative and was measured, not assumed. It is expressible (get_record → script → loop → create_record) and it was rejected on three findings:

1. Its error handling cannot tell a duplicate from a disaster.try_catch and fault edges swallow every failure identically, because the create_record executor collapses the engine error to a string with no code before either can see it. For the one job the product cannot afford to fail quietly, "the run succeeded and created nothing" is the wrong failure to make easy.
2. Backfill cannot reach a scheduled flow.ScheduleTrigger hands the flow { event, params: { jobId, flowName, schedule } } — no input channel. IJobService.trigger(name, data) forwards data to a job handler, which is how { from, to } gets in.
3. No retry policy or timeout.ScheduleTrigger calls jobService.schedule(name, schedule, handler) with no options; defineJob threads both.

The product docs settle the shape independently (data-model.md: "the dispatcher can be a plain idempotent job"; duty.object.ts names this file), so this is not a re-litigation of that decision — it is the evidence for why it still holds.

Idempotency: attempt the insert, then ask the data

The happy path is a bare insert. No read-then-write guard — that is a race two overlapping runs lose, and it costs a query on every task every night for a collision that is rare.

The interesting part is the failure path, and it does not classify the error. Measured on 17.2.0, ObjectQL rethrows the raw driver error, so a duplicate arrives as code: 'SQLITE_CONSTRAINT_UNIQUE' here and would be 23505 on Postgres; the platform's dialect-independent predicate isUniqueViolationError lives in @objectstack/types, which an application cannot resolve. Hard-coding one dialect or matching a message are both a consumer growing tolerance for a producer that will not answer.

So on failure it asks the data, which every driver answers the same way: is the row there now?

• Present → the obligation exists exactly once, whoever won the race. Counted as existing. A run that inserts nothing because everything already exists is a successful run.
• Absent → the insert failed for a reason that is not "already dispatched". Re-thrown, so the run fails. That is the half a blanket swallow gets wrong.

The gap this could not close: a job handler has no data reach

Measured: a defineJob handler is invoked with exactly { jobId, data, bundle } — no engine, no service registry, no logger. So the one metadata shape the platform offers for scheduled work cannot, by itself, write a record.

Not worked around silently. runDispatch(engine, …) takes its engine as an argument; bindDispatchEngine is the one named seam; and until a host calls it dulyDispatchrefuses loudly, naming the wiring, rather than reporting a clean night on which nothing was dispatched.

• A defineJob handler is invoked with { jobId, data, bundle } and no data reach, so the platform's only scheduled-work metadata shape cannot read or write a record objectstack#14094 — the handler-context gap (measured probe, suggested one-line direction, additive).
• An application told to rely on a unique index cannot recognise the violation: ObjectQL rethrows the raw driver error and isUniqueViolationError is not reachable from an app objectstack#14095 — an app cannot recognise a uniqueness violation.
• Wire the dispatch job's engine at onEnable — one line, in the file #4 currently owns #42 (this repo) — the one-line onEnable wire. It lands in src/actions/register-handlers.ts, which One-click completion with undo, and skip-with-reason #4 owns and is editing now, so it is split out with Blocked-by: #4 rather than taken here. Until Wire the dispatch job's engine at onEnable — one line, in the file #4 currently owns #42 lands the job does not dispatch at runtime — loudly, by design.

Semantics worth reviewing

• One UTC pass, every zone resolved locally. The question asked per duty is "is this period's task due to exist yet", never "is it midnight here". Pinned: at 2026-08-31T20:00Z an Asia/Shanghai duty gets 2026-09 and an America/Los_Angeles duty gets 2026-08, on the same run.
• Which periods a scheduled run emits. The current period unconditionally — visible_from governs when a task shows up, not whether it exists — plus any later period whose lead window has already opened. The look-ahead is bounded at today + lead_days, which is exact rather than generous.
• Two effective-window tests. Duty-level on today (the scheduled run's selection rule, per the card); period-level on due_date, always. That second one is what stops a backfill inventing obligations that predate the duty, and it is why a backfill of a duty whose window has closed still works.
• The effective window is deliberately not in the SQL filter.effective_from/effective_to are calendar days in the duty's own zone, and "today" is a different day in Auckland and Los Angeles at one instant, so no single predicate is right for every row it matches. The query filters only the two zone-independent facts; the window test lives where the zone is known.
• last_dispatched_period advances, never regresses. Keys of one frequency are fixed-width and zero-padded, so a lexical compare is chronological. A run that created nothing writes nothing — which is also why a second identical run issues zero writes of any kind.
• The stagnation clock is untouched. The dispatcher writes duly_duty and never duly_task. Asserted directly: a spy engine records every update target across two runs at two clocks and duly_task must not appear.
• Backfill input is validated, not guessed.to on its own is refused — it could only mean "since the duty began", and effective_from is nullable, so that window has no floor.
• Paged reads. An unbounded sweep fails by dispatching a prefix of the duties, with no error anywhere.

Tests — and why they run on sqlite

test/dispatch.test.ts, 55 tests, three layers: wiring, the pure planner, and idempotency against a real booted engine.

The engine is sqlite, not memory, and that is the load-bearing choice. Measured: InMemoryDriver.create is a table.push() that stores no constraints, so two identical duly_task inserts both succeed and the table ends with two rows. A dispatcher suite on the memory driver reports idempotency passing while the index providing it was never consulted. One test asserts the index is genuinely enforced, so the suite cannot go green by absence.

Two ablations, each committed first, each confirmed on disk, each restored by a trap:

ablation	on-disk confirmation	result
sqlite → memory driver	removed-literal 1 → 0, injected-literal count 1, git diff --stat non-empty	4 red, including "the index is real on this engine" — the sqlite choice is load-bearing
dispatcher updates an existing duly_task row	anchor 1 → 0, injected engine.update('duly_task' count 1	1 red — exactly the stagnation-clock guard

Both restored clean (git status empty after each). Independent evidence that the suite bites: it caught a real bug during the first run — with lead_days: 0 the look-ahead passed the run's instant as from and midnight-of-today as to, so periodsBetween returned [] and every zero-lead duty silently dispatched nothing. Fixed, and the comment says why.

Acceptance criteria, each with a test: two runs → zero second-pass inserts · two concurrent runs → one task · Shanghai vs Los Angeles on one instant · standing produces nothing in any run · paused produces nothing and un-pausing produces only the current period, not the gap · last_dispatched_period advances and never regresses · a 13-month backfill produces exactly the expected key set and a second inserts nothing.

Files, and one note on scope

src/jobs/dispatch.job.ts, src/jobs/dispatch.plan.ts, src/jobs/index.ts, test/dispatch.test.ts — all inside the declared surface.

One addition outside it, named here rather than buried:src/functions/index.ts, to register the handler in dulyFunctions. A job needs two registrations — the schedule in dulyJobs and the handler in the functions map — and AppPlugin resolves the second as collectBundleFunctions(bundle)[job.handler], logging job handler not found in bundle.functions — skipping on a miss. Without that entry the job is registered, listed, validated, and never executed, with no author-time gate. The file is held by no other round-2 claim, and a test performs the same lookup the runtime performs.

objectstack.config.ts was not touched; the barrels were sufficient.

---

Generated by Claude Code

[os-warren]

Fixes#2

The spine. Active recurring duties become tasks, once per period, forever, without a lock.

Gates green at fe7941a (the merged head, origin/main merged in for #36/#38): pnpm validate ✓ · pnpm typecheck ✓ · pnpm test243 passed (7 files) · pnpm build ✓.

Metadata-first: what is declarative, and what could not be

Declarative: the schedule, its timezone, the retry policy, the timeout, the duty-selection filter, and the identity constraint the whole design rests on (duly_task_dispatch_identity, already on the object).

Imperative: the period arithmetic — calendar maths in a per-row IANA zone, which no filter language expresses — and the insert loop. Two files, so the boundary is a file boundary:

src/jobs/dispatch.plan.ts	Pure. Every scheduling decision. No I/O, no clock, no platform import. Rows in, rows out.
src/jobs/dispatch.job.ts	The defineJob metadata, plus ~40 lines that talk to the engine.

A scheduled flow was the alternative and was measured, not assumed. It is expressible (get_record → script → loop → create_record) and it was rejected on three findings:

1. Its error handling cannot tell a duplicate from a disaster.try_catch and fault edges swallow every failure identically, because the create_record executor collapses the engine error to a string with no code before either can see it. For the one job the product cannot afford to fail quietly, "the run succeeded and created nothing" is the wrong failure to make easy.
2. Backfill cannot reach a scheduled flow.ScheduleTrigger hands the flow { event, params: { jobId, flowName, schedule } } — no input channel. IJobService.trigger(name, data) forwards data to a job handler, which is how { from, to } gets in.
3. No retry policy or timeout.ScheduleTrigger calls jobService.schedule(name, schedule, handler) with no options; defineJob threads both.

The product docs settle the shape independently (data-model.md: "the dispatcher can be a plain idempotent job"; duty.object.ts names this file), so this is not a re-litigation of that decision — it is the evidence for why it still holds.

Idempotency: attempt the insert, then ask the data

The happy path is a bare insert. No read-then-write guard — that is a race two overlapping runs lose, and it costs a query on every task every night for a collision that is rare.

The interesting part is the failure path, and it does not classify the error. Measured on 17.2.0, ObjectQL rethrows the raw driver error, so a duplicate arrives as code: 'SQLITE_CONSTRAINT_UNIQUE' here and would be 23505 on Postgres; the platform's dialect-independent predicate isUniqueViolationError lives in @objectstack/types, which an application cannot resolve. Hard-coding one dialect or matching a message are both a consumer growing tolerance for a producer that will not answer.

So on failure it asks the data, which every driver answers the same way: is the row there now?

• Present → the obligation exists exactly once, whoever won the race. Counted as existing. A run that inserts nothing because everything already exists is a successful run.
• Absent → the insert failed for a reason that is not "already dispatched". Re-thrown, so the run fails. That is the half a blanket swallow gets wrong.

The gap this could not close: a job handler has no data reach

Measured: a defineJob handler is invoked with exactly { jobId, data, bundle } — no engine, no service registry, no logger. So the one metadata shape the platform offers for scheduled work cannot, by itself, write a record.

Not worked around silently. runDispatch(engine, …) takes its engine as an argument; bindDispatchEngine is the one named seam; and until a host calls it dulyDispatchrefuses loudly, naming the wiring, rather than reporting a clean night on which nothing was dispatched.

• A defineJob handler is invoked with { jobId, data, bundle } and no data reach, so the platform's only scheduled-work metadata shape cannot read or write a record objectstack#14094 — the handler-context gap (measured probe, suggested one-line direction, additive).
• An application told to rely on a unique index cannot recognise the violation: ObjectQL rethrows the raw driver error and isUniqueViolationError is not reachable from an app objectstack#14095 — an app cannot recognise a uniqueness violation.
• Wire the dispatch job's engine at onEnable — one line, in the file #4 currently owns #42 (this repo) — the one-line onEnable wire. It lands in src/actions/register-handlers.ts, which One-click completion with undo, and skip-with-reason #4 owns and is editing now, so it is split out with Blocked-by: #4 rather than taken here. Until Wire the dispatch job's engine at onEnable — one line, in the file #4 currently owns #42 lands the job does not dispatch at runtime — loudly, by design.

Semantics worth reviewing

• One UTC pass, every zone resolved locally. The question asked per duty is "is this period's task due to exist yet", never "is it midnight here". Pinned: at 2026-08-31T20:00Z an Asia/Shanghai duty gets 2026-09 and an America/Los_Angeles duty gets 2026-08, on the same run.
• Which periods a scheduled run emits. The current period unconditionally — visible_from governs when a task shows up, not whether it exists — plus any later period whose lead window has already opened. The look-ahead is bounded at today + lead_days, which is exact rather than generous.
• Two effective-window tests. Duty-level on today (the scheduled run's selection rule, per the card); period-level on due_date, always. That second one is what stops a backfill inventing obligations that predate the duty, and it is why a backfill of a duty whose window has closed still works.
• The effective window is deliberately not in the SQL filter.effective_from/effective_to are calendar days in the duty's own zone, and "today" is a different day in Auckland and Los Angeles at one instant, so no single predicate is right for every row it matches. The query filters only the two zone-independent facts; the window test lives where the zone is known.
• last_dispatched_period advances, never regresses. Keys of one frequency are fixed-width and zero-padded, so a lexical compare is chronological. A run that created nothing writes nothing — which is also why a second identical run issues zero writes of any kind.
• The stagnation clock is untouched. The dispatcher writes duly_duty and never duly_task. Asserted directly: a spy engine records every update target across two runs at two clocks and duly_task must not appear.
• Backfill input is validated, not guessed.to on its own is refused — it could only mean "since the duty began", and effective_from is nullable, so that window has no floor.
• Paged reads. An unbounded sweep fails by dispatching a prefix of the duties, with no error anywhere.

Tests — and why they run on sqlite

test/dispatch.test.ts, 55 tests, three layers: wiring, the pure planner, and idempotency against a real booted engine.

The engine is sqlite, not memory, and that is the load-bearing choice. Measured: InMemoryDriver.create is a table.push() that stores no constraints, so two identical duly_task inserts both succeed and the table ends with two rows. A dispatcher suite on the memory driver reports idempotency passing while the index providing it was never consulted. One test asserts the index is genuinely enforced, so the suite cannot go green by absence.

Two ablations, each committed first, each confirmed on disk, each restored by a trap:

ablation	on-disk confirmation	result
sqlite → memory driver	removed-literal 1 → 0, injected-literal count 1, git diff --stat non-empty	4 red, including "the index is real on this engine" — the sqlite choice is load-bearing
dispatcher updates an existing duly_task row	anchor 1 → 0, injected engine.update('duly_task' count 1	1 red — exactly the stagnation-clock guard

Both restored clean (git status empty after each). Independent evidence that the suite bites: it caught a real bug during the first run — with lead_days: 0 the look-ahead passed the run's instant as from and midnight-of-today as to, so periodsBetween returned [] and every zero-lead duty silently dispatched nothing. Fixed, and the comment says why.

Acceptance criteria, each with a test: two runs → zero second-pass inserts · two concurrent runs → one task · Shanghai vs Los Angeles on one instant · standing produces nothing in any run · paused produces nothing and un-pausing produces only the current period, not the gap · last_dispatched_period advances and never regresses · a 13-month backfill produces exactly the expected key set and a second inserts nothing.

Files, and one note on scope

src/jobs/dispatch.job.ts, src/jobs/dispatch.plan.ts, src/jobs/index.ts, test/dispatch.test.ts — all inside the declared surface.

One addition outside it, named here rather than buried:src/functions/index.ts, to register the handler in dulyFunctions. A job needs two registrations — the schedule in dulyJobs and the handler in the functions map — and AppPlugin resolves the second as collectBundleFunctions(bundle)[job.handler], logging job handler not found in bundle.functions — skipping on a miss. Without that entry the job is registered, listed, validated, and never executed, with no author-time gate. The file is held by no other round-2 claim, and a test performs the same lookup the runtime performs.

objectstack.config.ts was not touched; the barrels were sufficient.

---

Generated by Claude Code

[os-warren]

Fixes#2

The spine. Active recurring duties become tasks, once per period, forever, without a lock.

Gates green at fe7941a (the merged head, origin/main merged in for #36/#38): pnpm validate ✓ · pnpm typecheck ✓ · pnpm test243 passed (7 files) · pnpm build ✓.

Metadata-first: what is declarative, and what could not be

Declarative: the schedule, its timezone, the retry policy, the timeout, the duty-selection filter, and the identity constraint the whole design rests on (duly_task_dispatch_identity, already on the object).

Imperative: the period arithmetic — calendar maths in a per-row IANA zone, which no filter language expresses — and the insert loop. Two files, so the boundary is a file boundary:

src/jobs/dispatch.plan.ts	Pure. Every scheduling decision. No I/O, no clock, no platform import. Rows in, rows out.
src/jobs/dispatch.job.ts	The defineJob metadata, plus ~40 lines that talk to the engine.

A scheduled flow was the alternative and was measured, not assumed. It is expressible (get_record → script → loop → create_record) and it was rejected on three findings:

1. Its error handling cannot tell a duplicate from a disaster.try_catch and fault edges swallow every failure identically, because the create_record executor collapses the engine error to a string with no code before either can see it. For the one job the product cannot afford to fail quietly, "the run succeeded and created nothing" is the wrong failure to make easy.
2. Backfill cannot reach a scheduled flow.ScheduleTrigger hands the flow { event, params: { jobId, flowName, schedule } } — no input channel. IJobService.trigger(name, data) forwards data to a job handler, which is how { from, to } gets in.
3. No retry policy or timeout.ScheduleTrigger calls jobService.schedule(name, schedule, handler) with no options; defineJob threads both.

The product docs settle the shape independently (data-model.md: "the dispatcher can be a plain idempotent job"; duty.object.ts names this file), so this is not a re-litigation of that decision — it is the evidence for why it still holds.

Idempotency: attempt the insert, then ask the data

The happy path is a bare insert. No read-then-write guard — that is a race two overlapping runs lose, and it costs a query on every task every night for a collision that is rare.

The interesting part is the failure path, and it does not classify the error. Measured on 17.2.0, ObjectQL rethrows the raw driver error, so a duplicate arrives as code: 'SQLITE_CONSTRAINT_UNIQUE' here and would be 23505 on Postgres; the platform's dialect-independent predicate isUniqueViolationError lives in @objectstack/types, which an application cannot resolve. Hard-coding one dialect or matching a message are both a consumer growing tolerance for a producer that will not answer.

So on failure it asks the data, which every driver answers the same way: is the row there now?

• Present → the obligation exists exactly once, whoever won the race. Counted as existing. A run that inserts nothing because everything already exists is a successful run.
• Absent → the insert failed for a reason that is not "already dispatched". Re-thrown, so the run fails. That is the half a blanket swallow gets wrong.

The gap this could not close: a job handler has no data reach

Measured: a defineJob handler is invoked with exactly { jobId, data, bundle } — no engine, no service registry, no logger. So the one metadata shape the platform offers for scheduled work cannot, by itself, write a record.

Not worked around silently. runDispatch(engine, …) takes its engine as an argument; bindDispatchEngine is the one named seam; and until a host calls it dulyDispatchrefuses loudly, naming the wiring, rather than reporting a clean night on which nothing was dispatched.

• A defineJob handler is invoked with { jobId, data, bundle } and no data reach, so the platform's only scheduled-work metadata shape cannot read or write a record objectstack#14094 — the handler-context gap (measured probe, suggested one-line direction, additive).
• An application told to rely on a unique index cannot recognise the violation: ObjectQL rethrows the raw driver error and isUniqueViolationError is not reachable from an app objectstack#14095 — an app cannot recognise a uniqueness violation.
• Wire the dispatch job's engine at onEnable — one line, in the file #4 currently owns #42 (this repo) — the one-line onEnable wire. It lands in src/actions/register-handlers.ts, which One-click completion with undo, and skip-with-reason #4 owns and is editing now, so it is split out with Blocked-by: #4 rather than taken here. Until Wire the dispatch job's engine at onEnable — one line, in the file #4 currently owns #42 lands the job does not dispatch at runtime — loudly, by design.

Semantics worth reviewing

• One UTC pass, every zone resolved locally. The question asked per duty is "is this period's task due to exist yet", never "is it midnight here". Pinned: at 2026-08-31T20:00Z an Asia/Shanghai duty gets 2026-09 and an America/Los_Angeles duty gets 2026-08, on the same run.
• Which periods a scheduled run emits. The current period unconditionally — visible_from governs when a task shows up, not whether it exists — plus any later period whose lead window has already opened. The look-ahead is bounded at today + lead_days, which is exact rather than generous.
• Two effective-window tests. Duty-level on today (the scheduled run's selection rule, per the card); period-level on due_date, always. That second one is what stops a backfill inventing obligations that predate the duty, and it is why a backfill of a duty whose window has closed still works.
• The effective window is deliberately not in the SQL filter.effective_from/effective_to are calendar days in the duty's own zone, and "today" is a different day in Auckland and Los Angeles at one instant, so no single predicate is right for every row it matches. The query filters only the two zone-independent facts; the window test lives where the zone is known.
• last_dispatched_period advances, never regresses. Keys of one frequency are fixed-width and zero-padded, so a lexical compare is chronological. A run that created nothing writes nothing — which is also why a second identical run issues zero writes of any kind.
• The stagnation clock is untouched. The dispatcher writes duly_duty and never duly_task. Asserted directly: a spy engine records every update target across two runs at two clocks and duly_task must not appear.
• Backfill input is validated, not guessed.to on its own is refused — it could only mean "since the duty began", and effective_from is nullable, so that window has no floor.
• Paged reads. An unbounded sweep fails by dispatching a prefix of the duties, with no error anywhere.

Tests — and why they run on sqlite

test/dispatch.test.ts, 55 tests, three layers: wiring, the pure planner, and idempotency against a real booted engine.

The engine is sqlite, not memory, and that is the load-bearing choice. Measured: InMemoryDriver.create is a table.push() that stores no constraints, so two identical duly_task inserts both succeed and the table ends with two rows. A dispatcher suite on the memory driver reports idempotency passing while the index providing it was never consulted. One test asserts the index is genuinely enforced, so the suite cannot go green by absence.

Two ablations, each committed first, each confirmed on disk, each restored by a trap:

ablation	on-disk confirmation	result
sqlite → memory driver	removed-literal 1 → 0, injected-literal count 1, git diff --stat non-empty	4 red, including "the index is real on this engine" — the sqlite choice is load-bearing
dispatcher updates an existing duly_task row	anchor 1 → 0, injected engine.update('duly_task' count 1	1 red — exactly the stagnation-clock guard

Both restored clean (git status empty after each). Independent evidence that the suite bites: it caught a real bug during the first run — with lead_days: 0 the look-ahead passed the run's instant as from and midnight-of-today as to, so periodsBetween returned [] and every zero-lead duty silently dispatched nothing. Fixed, and the comment says why.

Acceptance criteria, each with a test: two runs → zero second-pass inserts · two concurrent runs → one task · Shanghai vs Los Angeles on one instant · standing produces nothing in any run · paused produces nothing and un-pausing produces only the current period, not the gap · last_dispatched_period advances and never regresses · a 13-month backfill produces exactly the expected key set and a second inserts nothing.

Files, and one note on scope

src/jobs/dispatch.job.ts, src/jobs/dispatch.plan.ts, src/jobs/index.ts, test/dispatch.test.ts — all inside the declared surface.

One addition outside it, named here rather than buried:src/functions/index.ts, to register the handler in dulyFunctions. A job needs two registrations — the schedule in dulyJobs and the handler in the functions map — and AppPlugin resolves the second as collectBundleFunctions(bundle)[job.handler], logging job handler not found in bundle.functions — skipping on a miss. Without that entry the job is registered, listed, validated, and never executed, with no author-time gate. The file is held by no other round-2 claim, and a test performs the same lookup the runtime performs.

objectstack.config.ts was not touched; the barrels were sufficient.

---

Generated by Claude Code