fix(sdk): lower trigger keys to the kernel dialect, and add a scheduled trigger

[kjgbot]

This PR is two things, and the first is a repair

1. It fixes a P0 on main: the SDK compiler does not lower trigger keys, so every event-triggered flow is rejected by the kernel.

sdk/src/compile.ts:203 on origin/main is a straight spread with no case conversion:

...(flow.triggers?.length ? { triggers: flow.triggers } : {}),

The authoring dialect is camelCase (hn-monitor.flow.yaml declares eventType, dedupeKeyTemplate). The kernel's TriggerSpec is snake_case under #[serde(deny_unknown_fields)]. So the supported SDK authoring path produces a spec the kernel refuses outright:

$ relayflowd --data-dir $D run $D/sdk-compiled.json
Error: parse run spec /tmp/tickproof.3ndq/sdk-compiled.json

Caused by:
    malformed run spec: unknown field `dedupeKeyTemplate`, expected one of `id`, `executor`, `event_type`, `pattern`, `dedupe_key_template`, `stale_after_ms`

$ relayflowd --data-dir $D2 run testdata/event-triggered-flow.spec.canonical.json
{"run_id":"01M1KJGFDKCYS08H53QQ39Z1E3","status":"parked","completion_reason":null,"completed_steps":0}

Both shipped gate-2 proactive workloads — hn-monitor and dir-watcher — were unauthorable through the supported SDK path. RFC-0001's gate 2 "done when" is hn-monitor running as a relayflow in production; the path to author it terminated at the kernel.

It stayed hidden because the committed *.spec.canonical.json fixtures are snake_case and correct, while spec-parity.test.ts only exercised the four hello-* fixtures, none of which has a trigger. No test ever compiled a triggered flow and compared it to a fixture.

The decisive proof the fix is right — the fixtures were correct all along, the compiler was not:

event-triggered-flow.yaml MATCHES committed fixture
hn-monitor.flow.yaml      MATCHES committed fixture

The fixed compiler reproduces the pre-existing snake_case fixtures byte-for-byte. spec-parity.test.ts now pins all three (plus the new tick fixture) so it cannot silently regress.

This was found only because the brief required generating fixtures through the SDK compiler rather than by hand.

2. It adds the missing primitive: a relayflow can be scheduled.

---

Deployment limit — read this before merging

No CLI runner ships in this PR. emitDueTicks is a pure function of (schedule, cursor, now); the timer that calls it is the caller's. Consequently agent-relay cloud schedules will still report "No workflow schedules found" after this merges. The primitive is proven, not deployed. Do not merge this believing the drive loop is now durable — it is not, yet.

---

The scheduled trigger

A relayflow could not be scheduled. grep -rniE "cron|schedule|interval|timer" over sdk/src/spec.ts and sdk/src/compile.ts returned nothing; every shipped trigger was fed by a poller reacting to something external.

RFC-0001 had already decided the shape, so this follows the decision rather than making one:

• gate 2 "proves: triggers are entry conditions, not schedulers";
• the first dogfood run, 2026-08-27: "a cron trigger reported succeeded into a void with no worker enrolled" — a scheduler inside the kernel is exactly what produced that;
• "the trigger plane is liveness-checked … because a flow that is never triggered is silently zero — Native's silent-death problem."

So a schedule is an event source, not a kernel feature. There is no cron: field on the spec and no Rust changed. sdk/src/tick-source.ts sits beside hn-poller.ts and dir-watcher-poller.ts, submits flows.tick through the same event.submit path, and inherits — rather than reimplements — the kernel's dedupe claim and its liveness sweep.

The slot grid

slot(t)           = floor((t - epochMs) / intervalMs)
scheduledForMs(n) = epochMs + n * intervalMs

A slot is an interval of the grid, not the moment a poller happened to wake. scheduledForMs is a pure function of the grid, so one scheduled instant has one identity no matter when — or how many times — a poller notices it.

Duplicates and skips are separate mechanisms

Neither covers for the other, and that split is the design.

Duplicates → the dedupe key. Derived from (schedule_id, scheduled_for_ms) via dedupeKeyTemplate — the grid instant, never emitted_at_ms (which is carried in the payload for observability and deliberately excluded). The kernel's existing (flow_key, subscription_id, dedupe_key) claim then covers a double-fire, a re-delivery, two racing pollers, and a poller restart with a lost cursor — with no new kernel machinery. Restart-idempotency belongs to the key, not to the cursor.

Skips → the cursor. emitDueTicks emits every slot between the last emitted and now, so a sleeping poller backfills rather than silently dropping slots. The cursor advances only after a successful submit (pollDirectoryOnce's seen discipline), so a journal failure mid-backfill leaves the rest due. Slots beyond maxCatchUp are returned in skippedSlots, not dropped — a week-long outage recovers to the current slot instead of wedging, and the skip cannot be silent.

Liveness

The kernel already had the RFC's full trigger-liveness plane (kernel/relayflowd/src/server/liveness.rs): RelayCron single-winner bucket claim, detect_stale → journal → latch ordering, CAS-guarded latch, stale_after reconciliation. What was missing was the authoring half — staleAfterMs was unauthorable through the SDK, so every flow silently inherited the 5-minute engine default, a decision no author made. It is now declarable and bounds-checked against the same i64 limit TriggerSpec::effective_stale_after_ms enforces.

Observed against a real daemon:

relayflowd: subscription.stale flow="b356ed31...79b" sub="every-minute" event_type="flows.tick" last_event_at_ms=1788437770130 stale_after_ms=1000 detected_at_ms=1788437791447

subscription.registered {"effective_stale_after_ms":1000,"event_type":"flows.tick","executor":"agent-worker","subscription_id":"every-minute"}
subscription.matched    {"event_key":"flows.tick:heartbeat-1m:1764000000000",...}
subscription.stale      {"detected_at_ms":1788437791447,...,"stale_after_ms":1000,"subscription_id":"every-minute"}

effective_stale_after_ms: 1000 is the flow's declared budget, not the 5-minute default — which proves staleAfterMs survives the authoring → kernel lowering.

---

The worked example, run for real

testdata/tick-heartbeat.flow.yaml + .spec.canonical.json + .spec.sha256, following hn-monitor and dir-watcher exactly. Both fixtures generated through compileYamlToCanonicalJson / compileAndHash — never by hand. spec_hash = 0c3d089f0075c53442c5c2241ada734af5e450a2b558c16030aaf1d1e29127ff.

Poller asleep across slots 29400001–29400003, wakes 17s into 29400004; then a second poller re-delivers 29400004 with a lost cursor:

emittedSlots: [29400001,29400002,29400003,29400004]
skippedSlots: []
  slot 29400001 -> matched=true deduped=false run=01M1KK6XV9M5DMJQH3V7HPK8AJ
  slot 29400002 -> matched=true deduped=false run=01M1KK6XVJT7CMM7T5H5SZSXYA
  slot 29400003 -> matched=true deduped=false run=01M1KK6XVR8TTFQ7JH5KKEG7V3
  slot 29400004 -> matched=true deduped=false run=01M1KK6XVYTT6N791BWEX8D1FH
replay of slot 29400004: matched=true deduped=true run=null
run 01M1KK6XV9M5DMJQH3V7HPK8AJ slot 29400001: reason=success output={"lag_ms":197000,"schedule_id":"heartbeat-1m","scheduled_for_ms":1764000060000,"slot":29400001}
run 01M1KK6XVJT7CMM7T5H5SZSXYA slot 29400002: reason=success output={"lag_ms":137000,"schedule_id":"heartbeat-1m","scheduled_for_ms":1764000120000,"slot":29400002}
run 01M1KK6XVR8TTFQ7JH5KKEG7V3 slot 29400003: reason=success output={"lag_ms":77000,"schedule_id":"heartbeat-1m","scheduled_for_ms":1764000180000,"slot":29400003}
run 01M1KK6XVYTT6N791BWEX8D1FH slot 29400004: reason=success output={"lag_ms":17000,"schedule_id":"heartbeat-1m","scheduled_for_ms":1764000240000,"slot":29400004}

Four missed slots → four distinct successful runs, each reporting its own grid instant and lag. The re-delivery → zero.

---

Gates

Baseline measured on this worktree before any edit, at origin/main 990093b. RELAYFLOWD_BIN pinned for every SDK run to this worktree's own build (~/.relayflows-toolchain/target/173824371/debug/relayflowd), because locateRelayflowd otherwise picks the newest daemon by mtime across every worktree's target tree.

Gate	Baseline 990093b	Head
tsc --noEmit	exit 0	exit 0
tsc -p tsconfig.tests.json	exit 0	exit 0
vitest run	370 passed, 3 skipped, 0 failed	408 passed, 3 skipped, 0 failed
cargo test --workspace	100 passed, 0 failed	100 passed, 0 failed

The first baseline attempt reported 12 failures — an artifact of skipping test:prep (no sdk/dist, no kernel build, no chmod on testdata/preflight/*-cli). After the documented prep the baseline is clean, and that clean run is what is compared.

Per-file accounting (set-diff, not counts):

+6  sdk/tests/live-kernel.test.ts  (21 -> 27)
+6  sdk/tests/spec-parity.test.ts  (15 -> 21)
+6  sdk/tests/validate.test.ts     (36 -> 42)
+20 sdk/tests/tick-source.test.ts  (0 -> 20)
    total 373 -> 411

Full-name set-diff: 38 test names added, 0 removed, 0 renamed. git diff --stat sdk/tests/live-kernel.test.ts is 200 ++++ with zero deletions — pure insertion, no existing case touched. Kernel: diff of the sorted test … ok line set between baseline and head is empty (identical test set), consistent with no Rust changing.

Do not trust green CI here. flows CI runs only linux-x64-artifact and packed-consumer — neither the kernel nor the SDK suite. Everything above is local output.

---

Mutation verification

Both mutations: reverted the specific behaviour, ran the specific tests, captured the failure, restored byte-for-byte (sha256(tick-source.ts) = 3edce9029eb6e679ad539b413e2d0251bf3f0cd4a6848b5eea7c00fdc8e87b5e before and after both), re-ran, captured the pass.

M1 — dedupe key from wall clock instead of the scheduled instant (scheduled_for_ms: scheduledFor → nowMs; ticks still fire, only the bound is removed):

× two emissions of one scheduled instant claim the same key, so one run
  → expected 'flows.tick:heartbeat-1m:6000001' to be 'flows.tick:heartbeat-1m:6000000'
× a poller RESTART that loses its cursor re-emits the slot but does not re-run it
  → expected 'flows.tick:heartbeat-1m:6005000' to be 'flows.tick:heartbeat-1m:6000000'
× TWO ticks for ONE scheduled instant produce exactly ONE run
  → the kernel spawned a second run for one scheduled instant: expected { deduped: false, matched: true, …(2) } to match object { matched: true, deduped: true, …(1) }
Tests  3 failed | 1 passed | 43 skipped (47)

The third line is the one that matters: a real relayflowd spawned a second run for one scheduled instant. Restored → Tests 4 passed | 43 skipped.

M2 — backfill removed (emit only the current slot):

× backfills every slot a sleeping poller passed over           → expected [ 104 ] to deeply equal [ 101, 102, 103, 104 ]
× a backfilled tick carries its own lag ...                    → expected [ +0 ] to deeply equal [ 120000, 60000, +0 ]
× does NOT advance past a slot whose submit failed ...         → promise resolved "{ emittedSlots: [ 104 ], …(2) }" instead of rejecting
× reports slots dropped by the catch-up bound ...              → expected [ 110 ] to deeply equal [ 108, 109, 110 ]
× reports each skipped slot exactly once ...                   → expected [] to deeply equal [ 101, 102, 103, 104 ]
× caps at DEFAULT_MAX_CATCH_UP ...                             → expected [ 500 ] to have a length of 60 but got 1
× emits nothing when the current slot has already been emitted → expected [ 100 ] to deeply equal []
× emits nothing when the clock moves backwards ...             → expected [ 90 ] to deeply equal []
× a MISSED interval is backfilled into its own run ...         → expected [ 29400004 ] to deeply equal [ 29400001, 29400002, 29400003, …(1) ]
Tests  9 failed | 38 passed (47)

Restored → Tests 47 passed (47).

The tests pin bounds, not mechanisms. Deliberately not written: "a tick fired" — that passes under M1 and would have shipped a schedule that double-runs every slot. What is pinned instead: two ticks for one instant → one run (live kernel); a restart re-emitting a slot → no second run (live kernel); successive slots are not deduped away (the mirror test, without which a constant key would pass everything above and the flow would run once, ever); four missed slots → four distinct runs; a failed submit does not advance the cursor; over-budget slots are reported, exactly once; a tick for a different schedule_id does not wake the flow; the journal carries the declared budget.

---

Honest gaps

1. Provisioned-but-never-fired liveness is still undetected. A schedule whose source never submits a single tick has no subscriptions row and no event_dedupe row, so the sweep sees nothing. This is the kernel's own documented "Known gap" (server/liveness.rs), predates this PR, and closing it requires pre-registering spec triggers at spec-observation time — a kernel change, which this PR is scoped out of. A tick source that dies after firing at least once is detected; one that never starts is not.
2. Nothing restarts a dead schedule. Detection is journaled and logged; the sweep does not re-provision, page, or escalate. The observable hook is left; the action is not built.
3. No CLI runner ships (see the deployment limit above).
4. Daemon restart mid-backfill is unverified. The unit test covers a failed submit mid-backfill with a fake sink; I did not kill a live daemon between two slots of one backfill. The dedupe claim is durable in SQLite so I expect it to hold — I did not observe it and am not claiming it.
5. Cross-host clock skew beyond one interval is unverified. Two pollers on the same grid dedupe correctly (proved), but hosts whose clocks disagree by more than one interval land in different slots and would produce two runs. Real, unaddressed.
6. maxCatchUp = 60 is not empirically justified — chosen as an hour of one-minute slots.

Full design, all literal command output, and the reproduction script: ops/reviews/20260903-scheduled-trigger-design.md.

---

Review focus

sdk/src/compile.ts is the file at the centre of two silent-revert traps in this lane. The path that distinguishes acceptance from lowering is compileYaml + toKernelSpec — validateSpec has always accepted the trigger fields; toKernelSpec was the half that never lowered them.

Baseline was measured at 990093b; main has since moved to 512723c (#138). Not rebased — leaving that call to the lead.

Do not merge. An independent signoff is being commissioned at this exact head.

🤖 Generated with Claude Code

https://claude.ai/code/session_01FtQSAcGDta5VH9xiZFT4sR

[coderabbitai]

Warning

Review limit reached

Next included review available in 59 minutes.

Check out review usage here.

View limit details

Limit details: You’ve used the included review currently available.

Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available.
You're only billed for reviews past your plan's rate limits ($0.25/file).

Learn how review limits work.

Review configuration:

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Free

Run ID: 8b7d7f0c-5251-4705-b5b3-433de60d7014

📥 Commits

Reviewing files that changed from the base of the PR and between 512723c and ad4b431.

📒 Files selected for processing (14)

• ops/reviews/20260903-scheduled-trigger-design.md
• sdk/src/compile.ts
• sdk/src/index.ts
• sdk/src/spec.ts
• sdk/src/tick-source.ts
• sdk/src/validate.ts
• sdk/tests/live-kernel.test.ts
• sdk/tests/spec-parity.test.ts
• sdk/tests/tick-source.test.ts
• sdk/tests/validate.test.ts
• testdata/preflight/tick-slot-report-cli
• testdata/tick-heartbeat.flow.yaml
• testdata/tick-heartbeat.spec.canonical.json
• testdata/tick-heartbeat.spec.sha256

---

Note

🎁 Summarized by CodeRabbit Free

Your organization is on the Free plan. CodeRabbit will generate a high-level summary and a walkthrough for each pull request. For a comprehensive line-by-line review, please upgrade your subscription to CodeRabbit Essentials by visiting https://app.coderabbit.ai/settings/billing.

_{Comment @coderabbitai help to get the list of available commands.}

[kjgbot]

P2-1, P2-2, P3 fixed at ad4b431

Signoff was REVIEW_PASSED with no P0/P1; these were fixed at the lead's gate because all three reproduce the exact failure class this PR exists to address — RFC-0001's "a flow that is never triggered is silently zero". Red captured first for all three, then mutation-verified.

P2-1 — a skip could vanish when the same poll failed

The cursor was advanced past skippedSlots before the emit loop, so a submit failure discarded the returned result — the only place a skipped slot is ever recorded, since it never reaches the kernel — while the cursor had already moved past the evidence. Red:

× leaves the skipped slots re-derivable when the FIRST submit fails
  → cursor advanced past slots that never reached the kernel: expected 107 to be 100
× carries the skipped slots on the error when a later submit fails
  → the failing submit did not throw: The instanceof assertion needs a constructor but undefined was given.

The pre-advance is gone and a failure now throws TickEmitError carrying emittedSlots, outcomes, skippedSlots. Three paths account for a skip and none drops it: a submit succeeds → the result carries it; a submit throws → the error carries it; nothing was submitted → the cursor never moved and the next poll re-derives the identical due range. This was flagged as becoming P1 once the CLI runner lands and required as its prerequisite — that prerequisite is now met.

P2-2 — a NaN grid made a schedule permanently, silently zero

epochMs/nowMs were unvalidated while intervalMs was; the asymmetry was the bug. Red (8 cases):

× refuses epochMs = NaN       → promise resolved "{ emittedSlots: [], outcomes: [], …(1) }" instead of rejecting
× refuses epochMs = Infinity  → ... but got 'Invalid array length'
× refuses nowMs = -1          → promise resolved "{ emittedSlots: [ -1 ], …(2) }" instead of rejecting

Both now go through requireNonNegativeInteger; Number.isInteger is false for NaN and both infinities, so one check covers all three.

P3 — the i64 literal admitted exactly the value the kernel refuses

9_223_372_036_854_775_807 rounds up to 2^63 in a double, so value > MAX_STALE_AFTER_MS admitted i64::MAX + 1. Red: rejects staleAfterMs 9223372036854776000 → expected true to be false. Bound is now Number.MAX_SAFE_INTEGER — above 2^53 a JS number cannot name a specific integer, so a larger budget could not cross the boundary faithfully even if the kernel took it (2^53 ms ≈ 285,000 years).

Mutation verification

Pre-mutation sha256: tick-source.ts a0f2d1e4874bf164a0cd657028c89636ebf2d4adf4977f55f7441e795b0dd3ad, validate.ts 9986dc54c79476d1355cbfadcf83c6356ffe6d476ca4ef8286c23c6ba6cf4876. Both restored to those exact hashes.

Mutation	Reverted	Result
M3	re-add the cursor pre-advance	1 failed — expected 107 to be 100
M3b	throw cause instead of TickEmitError	1 failed — not an instance of TickEmitError
M4	drop both requireNonNegativeInteger calls	8 failed
M5	restore the i64 literal bound	2 failed — expected true to be false

M3 and M3b failing one test each, different tests, shows the two halves of the P2-1 fix are independently load-bearing rather than one mechanism counted twice.

Gates at ad4b431

Gate	Baseline 990093b	969ed44	ad4b431
tsc --noEmit	0	0	0
tsc -p tsconfig.tests.json	0	0	0
vitest run	370p/3s/0f	408p/3s/0f	423p/3s/0f
cargo test --workspace	100 passed	100 passed	100 passed, identical test set

Per-file since 969ed44: tick-source.test.ts +13 (20→33), validate.test.ts +2 (42→44). +15 names, 0 removed.

Fixtures untouched. git diff --stat testdata/ is empty and spec_hash is unchanged at 0c3d089f0075c53442c5c2241ada734af5e450a2b558c16030aaf1d1e29127ff — these fixes are behavioural and validation-side only, so the compiled dialect is byte-identical to the signed-off head.

Two corrections to my own disclosures

The signoff verified two things I declined to claim, and I was being harder on myself than the evidence required:

• Daemon SIGKILL mid-backfill — verified on the reviewer's live harness: dedupe survives, 3 slots → 3 journals. Recorded as the reviewer's evidence, not mine.
• Cross-host clock skew — my suspicion that it duplicates runs was wrong. Skew shifts when a slot fires, not how many times, because a slot's identity is a property of the grid and not of either host's clock.

Both corrected in ops/reviews/20260903-scheduled-trigger-design.md rather than deleted, since the original claims are in the description above.

The deployment limit stated in the description is unchanged: no CLI runner ships, so agent-relay cloud schedules will still be empty after merge. The primitive is proven, not deployed.

[kjgbot]

Merging — basis at ad4b4312

Independent signoff REVIEW_PASSED at 969ed44, plus three fixes I required beyond the reviewer's bar. Recording why.

The P0 was confirmed independently, not inherited. The reviewer built the base compiler from a clean git archive 990093b, fed its hn-monitor output to a real daemon, and got malformed run spec: unknown field 'dedupeKeyTemplate'. Both shipped gate-2 workloads were genuinely unauthorable through the supported path. The fixed compiler reproduces all three committed triggered-flow fixtures byte-for-byte and changes none; toKernelTrigger/kernelTriggerToAuthoring are exact inverses over all six fields; unknown fields fail closed in both dialects. Reverting the fix to the raw spread fails 6 tests including all three fixture-parity tests and the spec_hash pin — so the guard is a bound, not a mechanism that merely runs.

Three fixes required after the PASS. The reviewer ranked these P2 on sound reasoning — nothing consumes skippedSlots yet — and also noted the first "becomes P1 the moment the CLI runner lands". Since they must be fixed before the runner regardless, and since both reproduced the exact failure this PR exists to prevent (RFC-0001: "a flow that is never triggered is silently zero"), I held the merge for them:

• A submit failure in a poll that also skipped slots advanced the cursor past them before the throw discarded the result — 7 due slots lost with no report anywhere, contradicting the module's own guarantee. Now three paths account for a skip and none drops it: success carries it in the result, failure carries it on TickEmitError, and nothing-submitted leaves the cursor unmoved so the next poll re-derives the identical due range. Red reproduced the reviewer's shape verbatim: cursor advanced past slots that never reached the kernel: expected 107 to be 100.
• NaN/Infinity/negative/non-integer epochMs/nowMs were unvalidated, unlike intervalMs, making a schedule permanently and silently zero. Now guarded by requireNonNegativeInteger; red showed the silent zero verbatim.
• The staleAfterMs i64 literal rounded up to 2^63, admitting exactly the one value the kernel refuses. Bound is now Number.MAX_SAFE_INTEGER.

Mutation-verified with both files restored to their exact pre-mutation sha256. M3 and M3b fail one test each, and different tests — the two halves of the skip fix are independently load-bearing rather than one mechanism counted twice.

The compiled dialect is byte-identical to the signed-off head: git diff --stat testdata/ is empty and spec_hash is still 0c3d089f…. The delta from 969ed44 is 6 files, +313/−28, confined to the three items plus the report.

Read this before assuming anything changed operationally: no CLI runner ships. agent-relay cloud schedules will still report "No workflow schedules found" after this merges. The primitive is proven, not deployed. This does not make the drive loop durable.

Remaining gaps, carried in the PR body: provisioned-but-never-fired liveness is still undetected (the kernel's own documented gap); nothing restarts a dead schedule; daemon restart mid-backfill and cross-host clock skew were verified by the reviewer and are better than the author claimed — dedupe survives a SIGKILL mid-backfill, and skew shifts when a slot fires, not how many times, because a slot's identity is a property of the grid rather than of either host's clock.

Squash-merging under the checklist: independent signoff PASSED, the three required fixes landed and mutation-verified, CI green at the exact head, base clean, no unresolved feedback, no unpushed WIP.

🤖 Generated with Claude Code

https://claude.ai/code/session_01FtQSAcGDta5VH9xiZFT4sR