feat(trigger-schedule): a scheduled run whose due time passed while no kernel was ticking is recorded as missed, never replayed - #26485

📓 Docs Drift Check

This PR changes 3 package(s): @objectstack/service-automation, @objectstack/service-job, @objectstack/trigger-schedule, touching 40 documentable anchor(s). ⚠️ 3 changed file(s) yielded no anchor (packages/services/service-automation/src/index.ts, packages/services/service-job/src/index.ts, packages/triggers/trigger-schedule/src/index.ts), so the pages documenting them are NOT COVERED by this run — this is not a clean bill of health for those files.

2 hand-written doc(s) NAME something this change touched and may need an implementation-accuracy re-verification:

• content/docs/automation/flows.mdx (via flowName (symbol, a field of interface MissedScheduledRun; a field of interface MissedScheduledRunInput))
• content/docs/automation/jobs.mdx (via flowName (symbol, a field of interface MissedScheduledRun; a field of interface MissedScheduledRunInput))

⛔ 5 release-owned page(s) also name something this change touched. These are read-only:

• content/docs/releases/v16.mdx (via AutomationEngine (symbol, a top-level class))
• content/docs/releases/v17/17-0.mdx (via AutomationEngine (symbol, a top-level class), flowName (symbol, a field of interface MissedScheduledRun; a field of interface MissedScheduledRunInput))
• content/docs/releases/v17/17-5.mdx (via flowName (symbol, a field of interface MissedScheduledRun; a field of interface MissedScheduledRunInput), timed_out (literal, a string literal in SysAutomationRun; a string literal in TERMINAL_RUN_STATUSES; a string literal in lifecycle))
• content/docs/releases/v17/17-6.mdx (via AutomationEngine (symbol, a top-level class))
• content/docs/releases/v18/18-0.mdx (via flowName (symbol, a field of interface MissedScheduledRun; a field of interface MissedScheduledRunInput))

content/docs/releases/ is RELEASE-OWNED (AGENTS.md "Documentation Guardrails"): release
notes are written centrally at release time, and a code PR that edits them is the exact PR
that guardrail exists to stop. They are still audited — read-only. If one of them is actually
wrong, file an issue or open a dedicated docs-only PR; do not edit it here.

# while this PR is open — GitHub drops the merge commit once it closes
git fetch origin 2054eb0a6e884a0824a559f9e2f190c92ddaa023 && git checkout 2054eb0a6e884a0824a559f9e2f190c92ddaa023
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin d0a7e748a933a7fb549c38c3105c1c49f5935dec 1bff9c7e9fc201d2593133e1c14ac19cf185b704 && git checkout -B drift-repro d0a7e748a933a7fb549c38c3105c1c49f5935dec && git merge --no-ff 1bff9c7e9fc201d2593133e1c14ac19cf185b704

node scripts/docs-audit/affected-docs.mjs --json d0a7e748a933a7fb549c38c3105c1c49f5935dec

Advisory only, and a precision-first one (#9192): a page is listed because it names a
symbol, wire route or SDK method this diff touched — not because it mentions a changed
package. Each row says which anchor put it there, so a wrong row is reportable rather than
merely annoying. To re-verify, run the docs-accuracy-audit workflow scoped to these files:
node scripts/docs-audit/affected-docs.mjs d0a7e748a933a7fb549c38c3105c1c49f5935dec → pass the list as
args.docs, on the commit named under Which tree this was computed on.

Contract review

Served-tier: TIER_DEFAULT
Head-sha: 1bff9c7e9fc201d2593133e1c14ac19cf185b704
Local-runs: none

Inputs read: card #25235 (body and all 11 comments: claim 6353512245, ruling 6353729816 letter A, hold 6354378101, spec answer 6355021401, unlock 6392088171, claim 6433183891, os-dev-report 6434107183); PR #26485 body, its 15-file list, and the net diff origin/main...1bff9c7e (15 files, +1381/−13; merge base 68901b0383); the head's check-runs at 2026-10-27T05:05Z. Face: record-recognisers --paths over the file list decides no face (no published schema, no governed path), so the changeset's Clause-②: yes (widening) line owes the declaration face, TIER_DEFAULT — the tier this record is served at.

① Derived judgments

Every accept-set and public-surface change the diff implies, each judged against the ruling (6353729816, items 2–9) and the cited code at the head:

1. Stored vocabulary widens by one member. sys_automation_run.status Field.select options gain missed (7 → 8 members), the retention onlyWhen set gains missed, and TERMINAL_RUN_STATUSES gains missed (engine.ts:1671) — the three sites the engine's own docblock says widen together, widened in the same change as the one producer. Right. The value is already the spec's: ExecutionStatus carries 'missed' appended last at packages/spec/src/automation/execution.zod.ts:53 (PR feat(spec): ExecutionStatus gains missed, a scheduled due time that passed while no kernel was ticking #25363, card spec: ExecutionStatus gains missed (a scheduled flow's due time that passed while no kernel was ticking, recorded once, never replayed) — child of #25235, ruling 6353729816 #25325), so the stored column aligns to the protocol rather than widening past it (Prime Directive 12 holds; ADR-0078 condition met). isTerminalRunStatus (engine.ts:1677) reads the list, and the store's row gate (suspended-run-store.ts:145, :841, :860) reads that predicate, so a missed row is written and listed as history with no fourth copy. plugin-approvals RUN_STATUS_LIVENESS already carries missed: 'terminal' on main (approval-service.ts:572) and is typed satisfies Record of ExecutionStatus to RunLiveness — untouched, right. No exact-list pin outside the diff enumerates the old five (grepped the head's tests).
2. Wire surface widens by construction, not by edit. listRuns(name, { status }) and GET …/runs?status= read the spec enum (automation-api.zod.ts:692, runtime/src/domains/automation.ts:3829 parseEnumParam('status', …, ExecutionStatus.options)); the diff holds no packages/runtime/** or packages/spec/** path. Right (ruling item 9).
3. @objectstack/service-automation public surface, all additive. AutomationEngine.recordMissedRun(missed) answering a MissedRunOutcome promise and AutomationEngine.missedRunLimit() answering number | null (new public methods); FlowTrigger.release?(flowName) (optional member — an existing implementer compiles unchanged); SuspendedRunStore.maxTerminalRunsPerFlow?: number (optional readonly; the two store classes turn a private readonly field public, same name and value); barrel types MissedScheduledRun, MissedRunOutcome; TerminalRunStatus widens. missedRunId() is exported from engine.ts but the barrel exports by name (index.ts:4, :85–92) and does not re-export it — consistent with the PR body's surface list, which omits it. Right, widening only; nothing accepted before is refused.
4. @objectstack/service-job: DbJobAdapter.readArming(name) answering a JobArming | null promise (public method, adapter-local like setReplayGuard, ⛔ not on IJobService — as claimed and ruled); barrel type JobArming. A read that throws rejects, never answers "inactive" (pinned). Right.
5. @objectstack/trigger-schedule: ScheduleTrigger.release(flowName) public; JobServiceSurface.readArming?, ScheduleDispatchLedger.recordMissedRun?, ScheduleDispatchLedger.missedRunLimit? optional structural members; barrel types JobArmingReading, MissedScheduledRunInput; new module missed-due-times.ts (dueTimesInSilence, DROPPED_DUE_TIME_COUNT_CEILING, not barrel-exported). Right, widening only.
6. The one existing-behaviour change: a refusal on purpose disarms by name. start()'s three refusals (policy off, no schedule descriptor, missing organization) call release() instead of stop(), and the engine's scheduled-work policy gate (engine.ts:3692–3706) calls trigger.release?.() on every pass since that gate returns before start() is reached. release() cancels the job named flow-schedule: plus the flow name through the job service whether or not this process bound it; DbJobAdapter.cancel → setActive(name, false) (db-job-adapter.ts:321, :702). Right — this is exactly ruling item 6's fix, inside the claimed surface, with no sys_job column, platform-objects or spec change; pinned both ways (OFF kernel between two ON kernels: zero rows; evicted ON kernel: one row per due time).
7. Gap bounds, as ruled (item 5c). Start = firstInstant(updated_at, last_run_at, created_at); at the head both upsertJobRow (:663) and bumpJob (:743) write updated_at: now, so updated_at is the newest instant a kernel touched the job, ≥ last_run_at, = bind time before any fire — the ruling's bound or tighter. End = this kernel's first BIND for the flow (ruling text says first tick; hold 6354378101 records why the due-time set is identical for cron and interval, and dueTimesInSilence is pinned to answer only instants that are the start of their own tick window, the ledger key). Read once per flow per kernel (armingRead), issued synchronously BEFORE schedule() rewrites the row; a late read can only lose a missed entry, never invent one. Right.
8. Ledger verdict and the no-ledger skip (items 5c–d). A due time is recorded only when the row is active AND store.read(dispatchKey) answers no claim; the key is scheduleDispatchKey(flow, computeTickWindow(armedSchedule, due)), the same function the handler claims with (schedule-trigger.ts:828). missedRunLimit() answers null when flowDispatchStore is null or has no read — the same condition under which dispatch-claims.ts:82 says "IN-PROCESS ONLY" — and the trigger then warns once naming the flow and records nothing; a ledger read that throws answers unverifiable, nothing recorded. ⛔ Never inferred from an absent claim. Right.
9. One row per (flow, due time) (item 5a). missedRunId = run_missed_ + flow name + _ + due-time epoch ms; the store prefixes run_ again (HISTORY_PREFIX + runId), so the durable id reads run_run_missed_… — deterministic and unique per (flow, due time), the two-replica pin holds one row. Cosmetic double prefix, not a contract point.
10. Row shape (items 2, 5f). startedAt = due time, completedAt = detection, steps: [], trigger.type = 'schedule', organizationId from the flow's declared organization; durationMs is never set, recordLog (run-history.ts) passes entry.durationMs through, and the store writes duration_ms: record.durationMs ?? null — absent, as the spec TSDoc says; no error, no refusalMessage. Right.
11. The bound (item 5e). Per flow per detection, the newest maxTerminalRunsPerFlow due times as the store was configured (default 100), read through missedRunLimit(), no second literal for the record bound; oldest dropped first; one warn naming the flow, the count and the earliest dropped due time. Two readings beside the ruling's text, both judged right: (a) when the store declares no cap or 0 (cap disabled), the engine's existing maxLogSize (default 1000, engine.ts:834) is the bound rather than "unbounded" — an existing bound reused, not a new one; (b) DROPPED_DUE_TIME_COUNT_CEILING = 1_000 is a new literal, but it bounds the WALK that counts dropped due times for the warn line (the line then says "at least 1000"), never what is recorded; the earliest dropped instant stays exact. Neither widens or narrows the ruled record bound.
12. No replay (item 5b). Nothing is dispatched for a missed due time; d.ran stays at its prior count in every two-kernel case; the next due time runs normally. cloud#1288 untouched. Right.
13. Nothing else in the diff touches packages/spec/**, packages/platform-objects/**, packages/runtime/**, packages/client, a gate or a script (item 9) — verified on the 15-path file list.

② Semver level

Changeset .changeset/25235-missed-scheduled-run.md: @objectstack/trigger-schedule, @objectstack/service-automation, @objectstack/service-job, each patch — one per touched published package, the three packages the diff moves. Clause-②: yes (widening) and Metadata-protocol: none, line-initial, in both the changeset body and the PR body, identical. Matches what the diff publishes: every change above is additive (new methods, optional interface members, barrel types, one more stored option); nothing an author writes changes (no spec key, no accepted value, no metadata type — Metadata-protocol: none is right), and nothing accepted before is refused (no (narrowing) arm, no !, no BREAKING banner, right). Level per AGENTS.md Post-Task Checklist 3: "none takes patch; a non-protocol change, widening or breaking, ships patch" — patch ×3 is the prescribed level (ruling item 4 says the same). Title feat(trigger-schedule): …, no !. Check Changeset on the head: success.

Clause-②: line judged right: the claim 6433183891 declared no and asked for the measurement on the diff; the dev measured yes (widening) and recorded the deviation in the os-dev-report. The diff adds public surface on three published packages and one stored status option a reader can receive and filter on, so yes (widening) is the true reading (the first claim 6353512245 and the ruling read it the same way). That line alone is what owes this declaration-face review.

③ Boundary flags

open_questions: [] — none to answer.

Dev flags (out_of_scope_findings in 6434107183, and the PR's acceptance notes), each answered or escalated:

1. Two replicas ticking at once — a replica that binds in the gap between a due time and the ticking replica's ledger claim records that due time missed while the other runs it. Read in the code: real, sub-second, bounded by the ledger check that is the ruling's own verdict source; single-kernel hosted environments (cloud#3149's case) cannot hit it. Same shape at one kernel: a due time exactly at the bind second is recorded by recordSilence and may also be fired by the new kernel — the missed row and a completed row for one due time. Answered: not a contract breach, carried in the PR's acceptance notes; nothing to escalate under this ruling. A reader who wants it closed gets a card of its own.
2. Console reader (ruling item 8). The dev read ui/packages/app-shell/src/views/metadata-admin/previews/FlowRunsPanel.tsx at the head (exists in this repo; STATUS_META maps five statuses, statusMeta() falls back to the raw string with a clock icon), so missed renders as the label missed with no duration — pass-through, as timed_out and refused already are. Answered for ui/. ⛔ Item 8's own instruction is a grep of ../objectui at the pinned .objectui-sha by domain:server seat 1 at ACCEPT; that read is the seat's, not this record's, and a closed map there is one domain:ui card with Blocked-by: objectstack-ai/objectstack#25235. Escalated to the seat at ACCEPT (as the dev's carrier line says).
3. Ruling item 5(g), maintainer question — whether missed rows take a bound tighter than the store's per-flow cap so real history survives a long outage. This PR uses the store's cap, as ruled; one word sets a smaller bound and missedRunLimit() is the one place to read it. Escalated to the maintainer, not blocking, exactly as the ruling flagged it.

Reviewer's own flags, none blocking:

4. Release on every policy-OFF pass. With scheduled work off (the default state of every deployment) and a job service present, each arm pass of a scheduled flow now issues one sys_job find (+ an update when a row is active) per flow. setActive returns on no row and the cron adapter's cancel of an unknown job is a no-op, so there is no warn noise; cost is one read per flow per bind pass. Inside the ruled fix; noted.
5. Heterogeneous policies on a shared sys_job table — a policy-OFF replica now flips a row an ON replica armed to inactive. Nothing in the fire path reads active (only readArming does, at the head), so the ON replica keeps ticking; the next kernel then reads "not armed" and loses a missed entry — the loss direction, never an invention. Noted.
6. Check-runs on the head at review time (2026-10-27T05:05Z): 28 completed/success (Check Changeset, Governed Surface Queue Guard, both single-writer and same-issue claim guards, "The card this PR closes must claim this branch", Lint · ESLint, Type Check · source/consumer/workspace/debt ledger, Build Core, Lint & Repo Gates, TypeScript Type Check, Test Core 8/8, Dogfood Regression Gate, Plan Test Core shards, filter, Auto Label, Check PR Size, Flag docs affected, Part-of guard, the scoped lint lanes); 11 completed/skipped (UI, docs, dogfood shards, temporal, opt-in harnesses — none claims a path of this diff); 7 still running: Test Core (1/8) through (7/8). No check-run has failed. The gate verdicts that have concluded are PASS; the seven shards still in progress are recorded as such and are the merge queue's to finish — this record does not claim them.
7. PR is a draft. Ready-for-review is the seat's stroke after the shards land; not a contract point.

Implemented-by: claude/project-thread-qvefhq
Reviewed-by: fable subagent of session_01R1q2xdtYgU6FKrZ7LgjPCC

VERDICT: PASS

席位核对 · ACCEPT · domain:server seat 1 · os-project-manager · session_01R1q2xdtYgU6FKrZ7LgjPCC · 2026-10-27T05:15Z

Head 1bff9c7e9f, report 6434107183 (on #25235), claim 6433183891. Contract review 6434279139 on this head: TIER_DEFAULT, owed by the Clause-②: yes (widening) declaration, PASS.

Generated by Claude Code