@coreplane/switchboard 1.19.2 → 1.200.0

package/dist/assets/deploy/cloudflare-resident/wrangler.template.jsonc

@@ -110,6 +110,18 @@
   // this Worker's script (`<script>-cache`), so two installations on one
   // account never share one — and BACKUP_BUCKET_NAME must say the same name.
   "r2_buckets": [{ "binding": "BACKUP_BUCKET", "bucket_name": "{{script}}-cache" }],
+  // The refresh cycle as a Workflow instance (docs/reference/specs/resident-repos.md
+  // item 7): `ResidentRefresh` in worker.ts runs one cycle — fetch, install,
+  // build, snapshot — as steps the engine retries and records, calling the
+  // resident's own step methods. The watchdog cron below creates one instance
+  // per resident whose row says `lifecycle: workflow` (the admin `/debug`
+  // `lifecycle` op flips a resident; the default is the alarm chain, so nothing
+  // here changes a resident until it is flagged). Workflow names are unique per
+  // account, so the name follows this Worker's script (`<script>-refresh`) the
+  // way the bucket does — two installations on one account never share one,
+  // and the costs page attributes the Workflow's steps to this Worker by that
+  // exact name (src/core/costs.ts).
+  "workflows": [{ "name": "{{script}}-refresh", "binding": "RESIDENT_REFRESH", "class_name": "ResidentRefresh" }],
   // Watchdog cadence: every 10 minutes, strictly BELOW the container
   // sleep window (SLEEP_AFTER = "20m" in worker.ts) so a healthy resident is
   // re-warmed before the platform can ever sleep it. Invariant: watchdog/alarm

package/dist/assets/deploy/cloudflare-sandbox/package.json

@@ -6,7 +6,7 @@
     "node": ">=22"
   },
   "scripts": {
-    "check:image": "docker build --quiet .",
+    "check:image": "docker build .",
     "deploy": "node ../bin/build-stamp.mjs",
     "typecheck": "tsc --noEmit -p tsconfig.json",
     "verify": "npm --prefix ../.. run --silent deploy:gen && npm run typecheck",

package/dist/assets/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "switchboard",
-  "version": "1.19.2",
+  "version": "1.200.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "switchboard",
-      "version": "1.19.2",
+      "version": "1.200.0",
       "license": "Apache-2.0",
       "workspaces": [
         "web",
@@ -3757,9 +3757,8 @@
     "docs": {
       "name": "switchboard-docs-site",
       "devDependencies": {
-        "@fontsource-variable/bricolage-grotesque": "^5.3.0",
-        "@fontsource-variable/geist": "^5.3.0",
-        "@fontsource-variable/geist-mono": "^5.3.0",
+        "@fontsource-variable/instrument-sans": "^5.3.0",
+        "@fontsource-variable/jetbrains-mono": "^5.3.0",
         "mermaid": "^11.4.1",
         "vitepress": "^1.6.4",
         "vitepress-plugin-mermaid": "^2.0.17"
@@ -5049,30 +5048,20 @@
         }
       }
     },
-    "node_modules/@fontsource-variable/bricolage-grotesque": {
+    "node_modules/@fontsource-variable/instrument-sans": {
       "version": "5.3.0",
-      "resolved": "https://registry.npmjs.org/@fontsource-variable/bricolage-grotesque/-/bricolage-grotesque-5.3.0.tgz",
-      "integrity": "sha512-TLi9Q4hJjS2UvoTMRSS2nHu6c4R56lAw60NR9QYtVRCHn0XtsFpiEhNffZ8Glsoxu6wEEwLKBP8lb94J52PNBA==",
+      "resolved": "https://registry.npmjs.org/@fontsource-variable/instrument-sans/-/instrument-sans-5.3.0.tgz",
+      "integrity": "sha512-u4gKbDBTNFGkg997tfQn3eHOhHuquWUFTRT/rwzuKtrxX5P2ekfs2x+LgBPP4P32+cC+vUwF1Cr+IdRoPQbrGw==",
       "dev": true,
       "license": "OFL-1.1",
       "funding": {
         "url": "https://github.com/sponsors/ayuhito"
       }
     },
-    "node_modules/@fontsource-variable/geist": {
+    "node_modules/@fontsource-variable/jetbrains-mono": {
       "version": "5.3.0",
-      "resolved": "https://registry.npmjs.org/@fontsource-variable/geist/-/geist-5.3.0.tgz",
-      "integrity": "sha512-j0m+vLQuG5XAYoHtGCVu0spvlGreR3EzpECUVzkFmI1mTVnAO38l/NEPDCFgZ177JxzYJCLSmTQibIiYPilGrA==",
-      "dev": true,
-      "license": "OFL-1.1",
-      "funding": {
-        "url": "https://github.com/sponsors/ayuhito"
-      }
-    },
-    "node_modules/@fontsource-variable/geist-mono": {
-      "version": "5.3.0",
-      "resolved": "https://registry.npmjs.org/@fontsource-variable/geist-mono/-/geist-mono-5.3.0.tgz",
-      "integrity": "sha512-vBbuwDEo9AkrqADMXOrlAR3DFcJi4/JxeuU43FoiQERnNwsfXNnvxvReZG02cQKmyk4DZkZdBZX3oTDvy2zBAw==",
+      "resolved": "https://registry.npmjs.org/@fontsource-variable/jetbrains-mono/-/jetbrains-mono-5.3.0.tgz",
+      "integrity": "sha512-F32xpS2NsGYoQi2ADSkKTgpJj7ozajsGgDJ8woTnqjmIB+dxDIqImjl4pXZVEExu8UFZ2ndhmX18EBS/hdz3Lw==",
       "dev": true,
       "license": "OFL-1.1",
       "funding": {
@@ -18340,7 +18329,7 @@
     },
     "packages/switchboard": {
       "name": "@coreplane/switchboard",
-      "version": "1.19.2",
+      "version": "1.200.0",
       "license": "Apache-2.0",
       "dependencies": {
         "@anthropic-ai/sdk": "^0.124.0",

package/dist/assets/package.json

@@ -1,6 +1,6 @@
 {
   "name": "switchboard",
-  "version": "1.19.2",
+  "version": "1.200.0",
   "private": true,
   "description": "Mention it in Slack and an agent reviews the PR, ships the fix, or answers the question — on the model you choose, with its tools running where you decide.",
   "license": "Apache-2.0",

package/dist/assets/project.json

@@ -145,7 +145,7 @@
     },
     "specs:coverage": {
       "does": "Maps a change's paths to the specs whose `Code`/`Tests` headers cover them, then lists changed source paths no spec covers.",
-      "when": "`-- --changed origin/main...HEAD` before review; `-- --require` fails on an uncovered path (warn-only today); `-- --json` for machines."
+      "when": "`-- --changed origin/main...HEAD [--test-guard]` before review; `-- --require` fails on an uncovered path; `-- --json` for machines."
     },
     "decisions:check": {
       "does": "Every record under `docs/decisions/` and `docs/plans/` carries a valid `status`, a superseded one names what replaced it, and an accepted record's body is unchanged against `origin/main`.",

package/dist/assets/source.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.19.2",
-  "commit": "7f323b1a2a517f0fad2cb942dfd8cd29ab12f458",
-  "builtAt": "2026-09-10T23:17:28.992Z"
+  "version": "1.200.0",
+  "commit": "8b8223d7c3299d642d813eb6796f796d2491b856",
+  "builtAt": "2026-09-11T19:47:20.673Z"
 }

package/dist/assets/src/core/schedules.ts

@@ -67,7 +67,8 @@ export type ScheduleAction =
   | RunAction
   /** Bot shim: GET the container's /healthz — starts it if stopped, renews its activity timeout. */
   | { type: "healthz" }
-  /** Resident Worker: one watchdog pass over every resident (re-arm dead refresh chains, time out stuck onboarding). */
+  /** Resident Worker: one watchdog pass over every resident (re-arm dead refresh chains, time out stuck
+   *  onboarding, create the refresh instance for residents on the Workflow lifecycle). */
   | { type: "watchdog" };
 
 export interface ScheduleDef {
@@ -115,7 +116,7 @@ export const SCHEDULES: readonly ScheduleDef[] = [
     cron: "*/10 * * * *",
     worker: "resident",
     description:
-      "Resident watchdog: re-arm dead refresh alarm chains (marking degraded(alarm-missed)) and time out stuck onboarding. Cadence must stay shorter than the resident SLEEP_AFTER (20m). Not a run.",
+      "Resident watchdog: re-arm dead refresh alarm chains (marking degraded(alarm-missed)), time out stuck onboarding, and create the refresh Workflow instance for residents whose lifecycle is `workflow`. Cadence must stay shorter than the resident SLEEP_AFTER (20m). Not a run.",
     action: { type: "watchdog" },
   },
 ];
@@ -375,6 +376,10 @@ export interface WatchdogSummary {
     action?: unknown;
     error?: string;
     disk?: unknown;
+    /** `alarm` or `workflow`: which scheduler drives this resident's refresh cycle. */
+    lifecycle?: unknown;
+    /** What the pass did about the resident's refresh Workflow instance (`workflow` residents only). */
+    instance?: unknown;
   }>;
 }
 

package/dist/assets/src/core/trace/attrs.ts

@@ -89,6 +89,9 @@ export interface AttrDomain {
   // the Workers' own roots (item 25): resident.watchdog, state.alarm
   residents: number;
   swept: number;
+  /** resident.refresh as a Workflow instance: the engine's instance id, an
+   *  identifier by the platform's own rule (never a repository name). */
+  instanceId: string;
 }
 
 export type SpanAttrKey = keyof AttrDomain;
@@ -109,6 +112,8 @@ const IDENTIFIER_KEYS: ReadonlySet<SpanAttrKey> = new Set<SpanAttrKey>([
   "model",
 ]);
 const IDENTIFIER_RE = /^[A-Za-z0-9_./:@+-]{1,64}$/;
+/** A Workflow instance id: the platform's rule (`^[a-zA-Z0-9_][a-zA-Z0-9-_]*$`, at most 100). */
+const INSTANCE_ID_RE = /^[a-zA-Z0-9_][a-zA-Z0-9-_]{0,99}$/;
 
 /** Validate one attrs bag: known keys, value in domain, identifiers sanitized.
  *  Returns the offending keys (empty when valid); emitters and tests use it,
@@ -125,6 +130,7 @@ export function invalidAttrKeys(attrs: SpanAttrs): string[] {
     if (expected === "string") {
       if (typeof value !== "string") bad.push(key);
       else if (IDENTIFIER_KEYS.has(key as SpanAttrKey) && !IDENTIFIER_RE.test(value)) bad.push(key);
+      else if (key === "instanceId" && !INSTANCE_ID_RE.test(value)) bad.push(key);
     } else if (typeof value !== expected) {
       bad.push(key);
     } else if (typeof value === "number" && !Number.isFinite(value)) {
@@ -198,6 +204,7 @@ const ATTR_TYPE: Record<SpanAttrKey, "string" | "number" | "boolean"> = {
   abandonedRuns: "number",
   residents: "number",
   swept: "number",
+  instanceId: "string",
 };
 
 export const ATTR_KEYS: readonly SpanAttrKey[] = Object.keys(ATTR_TYPE) as SpanAttrKey[];

package/dist/assets/src/execution/residentDepsStore.ts

@@ -71,6 +71,22 @@ export function depsStagingPath(key: string, attempt: string, storeDir: string =
   return `${storeDir}/.staging-${key}-${attempt}`;
 }
 
+/** Both private dirs of one attempt: what a taker sweeps when it finds the
+ *  attempt's holder dead (its lease names the scratch tree; the staging dir
+ *  is the same attempt's, so the finished node_modules a dead commit script
+ *  was moving does not outlive it either). */
+export function depsAttemptPaths(key: string, attempt: string, storeDir: string = DEPS_STORE_DIR): string[] {
+  return [depsScratchPath(attempt, storeDir), depsStagingPath(key, attempt, storeDir)];
+}
+
+/** The attempt a scratch path was minted for, or undefined for any other path. */
+export function depsAttemptOfScratchPath(path: string, storeDir: string = DEPS_STORE_DIR): string | undefined {
+  const prefix = `${storeDir}/.scratch-`;
+  if (!path.startsWith(prefix)) return undefined;
+  const attempt = path.slice(prefix.length);
+  return attempt && !attempt.includes("/") ? attempt : undefined;
+}
+
 export type DepsMaterializationPlan =
   { action: "hit" } | { action: "join" } | { action: "restore" } | { action: "install" };
 

package/dist/assets/src/execution/residentIncarnation.ts

@@ -0,0 +1,134 @@
+/** The resident's incarnation id and the durable leases judged against it
+ *  (docs/reference/specs/resident-repos.md item 22), kept pure and
+ *  dependency-free so it is unit-testable from src/ and imported by the
+ *  resident Worker like residentRefresh — the tested code IS the shipped code.
+ *
+ *  Background: the mirror mutex was a promise chain in the Durable Object's
+ *  memory, and so were the facts the watchdog read to tell a cycle in flight
+ *  from a marker orphaned by a dead one (`refreshing` with nothing running).
+ *  An isolate swap — a Worker deploy, a platform restart — drops both: the
+ *  chain resolves as if nothing were held while the holder's process keeps
+ *  writing into the tree, and the in-flight counters read zero the instant a
+ *  cycle is killed, so the watchdog could only guess from a timestamp.
+ *
+ *  Shape: an **incarnation id** is minted each time the object starts in a
+ *  fresh isolate or its container runtime is replaced under it; nothing that
+ *  incarnation held survives its end. A **lease** is a keyed document
+ *  `{holder, incarnation, expiresAt, step}`: who holds what, from which
+ *  incarnation, until when. One predicate judges every lease — dead when its
+ *  incarnation is not the current one, or its expiry has passed — so a
+ *  holder killed by a swap is taken over without waiting, and the expiry (the
+ *  step's own budget) stays as the backstop for a holder that hung without a
+ *  swap. The mirror mutex is one lease; the per-key dependency install is
+ *  another; the in-flight row holds the two the watchdog reads. */
+
+/** The mirror mutex row. */
+export const MIRROR_MUTEX_KEY = "resident:mirrorMutex";
+/** One key per in-flight fact the watchdog reads (the refresh cycle, the
+ *  hydration), never one shared row: two chains inside one object interleave
+ *  at any await, so a read-modify-write of a shared row can lose the other
+ *  chain's write. A key per fact is a plain put and a plain delete. */
+export const IN_FLIGHT_KEY_PREFIX = "resident:inFlight:";
+export function inFlightKey(kind: keyof InFlightRow): string {
+  return `${IN_FLIGHT_KEY_PREFIX}${kind}`;
+}
+/** One lease per lockfile key while its store entry is being produced. */
+export const DEPS_LEASE_KEY_PREFIX = "resident:depsLease:";
+
+/** A `refreshing`/`restoring` marker older than this with nothing running is
+ *  an orphan from an interrupted cycle; the watchdog normalizes it. Comfortably
+ *  above the longest legitimate cycle. A hydration's lease expires here too:
+ *  no restore approaches it (the hydrate's own cap is 25 minutes). */
+export const STALE_MIDFLIGHT_MS = 30 * 60_000;
+
+/** How long a refresh cycle's in-flight lease lives. Every step in a cycle is
+ *  budgeted and the budgets sum below this, so a lease still held past it is
+ *  a hung call into a container that was replaced under it — the one state the
+ *  in-memory counter could never expose, because it stayed non-zero for as
+ *  long as the promise never settled. Above the stale bound on purpose: a
+ *  cycle that is merely slow must never read as dead. */
+export const REFRESH_CYCLE_LEASE_MS = 2 * STALE_MIDFLIGHT_MS;
+
+export interface Lease {
+  /** Unique per take (`<incarnation>:<sequence>`); what a release compares. */
+  holder: string;
+  incarnation: string;
+  /** When the holder's budget ends. A lease past it is dead whoever holds it. */
+  expiresAt: number;
+  /** The engine step the holder runs, for the operator's eyes. */
+  step: string;
+  /** The directory the holder's command writes into, when it has one: a taker
+   *  that finds this lease dead sweeps the tree before it starts. */
+  tree?: string;
+}
+
+/** A random id per isolate start; the caller may pass its own source. */
+export function mintIncarnationId(random: () => string = () => crypto.randomUUID()): string {
+  return random();
+}
+
+/** Dead when the holder's incarnation is gone or its budget has passed. */
+export function leaseIsDead(lease: Lease, now: number, incarnation: string): boolean {
+  return lease.incarnation !== incarnation || lease.expiresAt < now;
+}
+
+export type MutexDecision =
+  /** Write `row`; `dead` is the lease taken over, if any (its tree may need a sweep). */
+  | { action: "take"; why: "free" | "holder-incarnation-gone" | "holder-expired"; row: Lease; dead: Lease | undefined }
+  /** A live holder of this incarnation: wait, at most `remainingMs`, then read again. */
+  | { action: "wait"; row: Lease; remainingMs: number };
+
+/** Decide over the stored row whether `holder` may take the mutex now. Pure:
+ *  the caller writes the returned row. */
+export function takeMutex(
+  row: Lease | undefined,
+  now: number,
+  incarnation: string,
+  budgetMs: number,
+  step: string,
+  holder: string,
+  tree?: string,
+): MutexDecision {
+  const next: Lease = { holder, incarnation, expiresAt: now + budgetMs, step, ...(tree ? { tree } : {}) };
+  if (!row) return { action: "take", why: "free", row: next, dead: undefined };
+  if (row.incarnation !== incarnation) return { action: "take", why: "holder-incarnation-gone", row: next, dead: row };
+  if (row.expiresAt < now) return { action: "take", why: "holder-expired", row: next, dead: row };
+  return { action: "wait", row, remainingMs: row.expiresAt - now };
+}
+
+/** A holder releases only the row it took: a row another holder took over
+ *  (this one was judged dead meanwhile) is left in place. */
+export function releaseMutex(
+  row: Lease | undefined,
+  holder: string,
+): { released: true; row: undefined } | { released: false; row: Lease | undefined } {
+  if (row && row.holder === holder) return { released: true, row: undefined };
+  return { released: false, row };
+}
+
+export interface InFlightRow {
+  refresh: Lease | null;
+  hydration: Lease | null;
+}
+
+/** Assemble the row from the two documents `inFlightKey` names. */
+export function inFlightRow(refresh: Lease | null | undefined, hydration: Lease | null | undefined): InFlightRow {
+  return { refresh: refresh ?? null, hydration: hydration ?? null };
+}
+
+/** Which in-flight facts are alive for the current incarnation right now. */
+export function liveInFlight(
+  row: InFlightRow | undefined,
+  now: number,
+  incarnation: string,
+): { refresh: boolean; hydration: boolean } {
+  const live = (lease: Lease | null | undefined) => lease != null && !leaseIsDead(lease, now, incarnation);
+  return { refresh: live(row?.refresh), hydration: live(row?.hydration) };
+}
+
+const LOCKFILE_KEY_RE = /^[0-9a-f]{64}$/;
+
+export function depsLeaseKey(key: string): string {
+  if (!LOCKFILE_KEY_RE.test(key)) throw new Error(`deps lease: not a lockfile key: ${JSON.stringify(key)}`);
+  return `${DEPS_LEASE_KEY_PREFIX}${key}`;
+}

package/dist/assets/src/execution/residentInstanceId.ts

@@ -0,0 +1,177 @@
+/** The refresh cycle as a cron-created Workflow instance — the id scheme, the
+ *  per-resident lifecycle flag and the cron's decision to create one
+ *  (docs/reference/specs/resident-repos.md item 7), kept pure and
+ *  dependency-free so it is unit-testable from src/ and imported by the
+ *  resident Worker like residentRefresh — the tested code IS the shipped code.
+ *
+ *  Background: the refresh cycle is driven by a self-rearming alarm chain,
+ *  and every failure between two re-arms ends the chain silently; a watchdog
+ *  guesses from a timestamp. A Cloudflare Workflow instance is the durable
+ *  fact the chain lacks: the engine records that a sequence is in progress
+ *  and which step it reached, retries a failed step on a policy, and shows a
+ *  failed instance by name. The port runs behind a per-resident flag,
+ *  `lifecycle: alarm | workflow`, default `alarm`: one resident can run its
+ *  cycles as instances while the fleet keeps the chain, and the two
+ *  schedulers never both drive a cycle for the same resident.
+ *
+ *  Shape: a cycle is one SHORT instance, not a loop — the resident Worker's
+ *  existing ten-minute cron creates one per eligible resident with a
+ *  deterministic id per resident and ten-minute bucket, so a second firing in
+ *  the same bucket is refused as a duplicate id and cycles stay serialized
+ *  per resident the way the chain serialized them. (A perpetual instance
+ *  that slept between cycles was rejected by arithmetic: five steps every
+ *  600 s reaches the engine's 10,000-step instance cap in about two weeks.) */
+
+import { STALE_MIDFLIGHT_MS } from "./residentIncarnation.js";
+import { nextRefreshDelayS } from "./residentRefresh.js";
+import type { ResidentLifecycleState } from "./residentState.js";
+
+// -- the flag ----------------------------------------------------------------
+
+/** Which scheduler drives a resident's refresh cycle. */
+export type ResidentLifecycle = "alarm" | "workflow";
+
+/** The alarm chain is the default; a row without the field reads as `alarm`. */
+export const DEFAULT_LIFECYCLE: ResidentLifecycle = "alarm";
+
+export function parseLifecycle(value: unknown): ResidentLifecycle | undefined {
+  return value === "alarm" || value === "workflow" ? value : undefined;
+}
+
+/** What a stored row means: the two words, else the default. */
+export function lifecycleOf(stored: unknown): ResidentLifecycle {
+  return parseLifecycle(stored) ?? DEFAULT_LIFECYCLE;
+}
+
+// -- the id ------------------------------------------------------------------
+
+/** One bucket per cron firing: the resident cron fires every ten minutes. */
+export const REFRESH_BUCKET_MS = 10 * 60_000;
+
+/** The platform's instance id rule (Workflows limits: "Instance ID: 100
+ *  characters", pattern `^[a-zA-Z0-9_][a-zA-Z0-9-_]*$`). */
+export const INSTANCE_ID_MAX_LENGTH = 100;
+export const INSTANCE_ID_PATTERN = /^[a-zA-Z0-9_][a-zA-Z0-9-_]*$/;
+
+const ID_PREFIX = "refresh_";
+const HASH_LENGTH = 8;
+
+export function refreshBucket(atMs: number): number {
+  return Math.floor(atMs / REFRESH_BUCKET_MS);
+}
+
+/** Owner and name lower-cased, every character outside `[A-Za-z0-9_-]` mapped
+ *  to `-`, joined by `-` (the `/` between them is one such character). */
+export function instanceSlug(owner: string, name: string): string {
+  return `${owner}/${name}`.toLowerCase().replace(/[^a-z0-9_-]/g, "-");
+}
+
+/** FNV-1a over the slug, as 8 hex digits: enough to tell two long names apart
+ *  once the id has to be truncated, and pure (no async digest). */
+function shortHash(text: string): string {
+  let h = 0x811c9dc5;
+  for (let i = 0; i < text.length; i++) {
+    h ^= text.charCodeAt(i);
+    h = Math.imul(h, 0x01000193) >>> 0;
+  }
+  return h.toString(16).padStart(HASH_LENGTH, "0");
+}
+
+/** `refresh_<slug>_<bucket>`; when that would exceed the platform's length
+ *  the slug is cut and a short hash of the whole slug is inserted before the
+ *  bucket, so the id stays deterministic, legal and distinct per resident. */
+export function refreshInstanceId(owner: string, name: string, atMs: number): string {
+  const slug = instanceSlug(owner, name);
+  const bucket = String(refreshBucket(atMs));
+  const plain = `${ID_PREFIX}${slug}_${bucket}`;
+  if (plain.length <= INSTANCE_ID_MAX_LENGTH) return plain;
+  const hash = shortHash(slug);
+  const keep = INSTANCE_ID_MAX_LENGTH - (ID_PREFIX.length + 1 + hash.length + 1 + bucket.length);
+  return `${ID_PREFIX}${slug.slice(0, keep)}_${hash}_${bucket}`;
+}
+
+// -- the cron's decision -----------------------------------------------------
+
+/** What the cron reads about one resident before creating its instance. */
+export interface RefreshRow {
+  lifecycle: ResidentLifecycle;
+  state: ResidentLifecycleState;
+  /** When the state last changed (epoch ms); null when the row never recorded one. */
+  updatedAt: number | null;
+  /** Set while the resident is idle (epoch ms), the way the facts record it. */
+  idleSince: number | null;
+  /** When the cron last created an instance for this resident (epoch ms). */
+  lastInstanceAt: number | null;
+  /** Whether the instance the row last recorded is still alive in the engine
+   *  (queued, running, paused or waiting), read from the engine's own status.
+   *  A step between retry attempts holds no lease and writes no state, so the
+   *  marker's age alone would call a live cycle stale; the engine knows. */
+  instanceRunning: boolean;
+}
+
+export interface RefreshCadence {
+  /** The awake cadence (the alarm's REFRESH_INTERVAL_S). */
+  intervalS: number;
+  /** The idle cadence (the alarm's IDLE_REFRESH_INTERVAL_S). */
+  idleIntervalS: number;
+}
+
+export type InstanceDecision =
+  | { create: true; why: "due" }
+  | { create: false; why: "alarm-lifecycle" | "not-serving" | "mid-cycle" | "not-due" | "running" };
+
+/** Create an instance only for a `workflow` row that is serving, is not in a
+ *  live cycle (a `refreshing` marker younger than the stale bound; an older
+ *  one is an orphan the next cycle normalizes, exactly as the watchdog
+ *  judges it), and whose cadence has elapsed since the last instance —
+ *  counted in whole buckets so cron jitter never skips a due bucket: the
+ *  awake cadence is one bucket, the idle cadence the row records is
+ *  `nextRefreshDelayS`'s idle interval in buckets. */
+export function shouldCreateRefreshInstance(row: RefreshRow, nowMs: number, cadence: RefreshCadence): InstanceDecision {
+  if (row.lifecycle !== "workflow") return { create: false, why: "alarm-lifecycle" };
+  if (row.state === "onboarding" || row.state === "down") return { create: false, why: "not-serving" };
+  if (row.instanceRunning) return { create: false, why: "running" };
+  if (row.state === "refreshing" && row.updatedAt !== null && nowMs - row.updatedAt <= STALE_MIDFLIGHT_MS) {
+    return { create: false, why: "mid-cycle" };
+  }
+  if (row.lastInstanceAt !== null) {
+    const delayS = nextRefreshDelayS({
+      outcome: row.idleSince !== null ? "idle" : "normal",
+      intervalS: cadence.intervalS,
+      idleIntervalS: cadence.idleIntervalS,
+    });
+    const dueBuckets = Math.max(1, Math.ceil((delayS * 1000) / REFRESH_BUCKET_MS));
+    if (refreshBucket(nowMs) - refreshBucket(row.lastInstanceAt) < dueBuckets) return { create: false, why: "not-due" };
+  }
+  return { create: true, why: "due" };
+}
+
+// -- the step policy ----------------------------------------------------------
+
+/** Every step's retry policy: six attempts, thirty seconds apart, doubling.
+ *  The delays between attempts sum to 930 s, about 15.5 minutes — longer than
+ *  the 3 to 10 minutes a resident Worker rollover takes to settle, so a deploy
+ *  mid-cycle costs the cycle retries inside one step, never a failed instance. */
+export const REFRESH_STEP_RETRIES = { limit: 6, delay: "30 seconds", backoff: "exponential" } as const;
+
+/** The sum of the delays between `limit` attempts under the policy: the
+ *  window a step keeps retrying inside. `delay` is the "<n> seconds" form the
+ *  engine accepts. */
+export function retryWindowMs(policy: { limit: number; delay: string; backoff: "exponential" | "constant" }): number {
+  const m = /^(\d+) seconds?$/.exec(policy.delay);
+  if (!m) throw new Error(`retry delay must be "<n> seconds", got ${JSON.stringify(policy.delay)}`);
+  const first = Number(m[1]) * 1000;
+  let total = 0;
+  for (let i = 0; i < policy.limit - 1; i++) total += policy.backoff === "exponential" ? first * 2 ** i : first;
+  return total;
+}
+
+/** The engine's ceiling on a step's configurable timeout ("30 minutes or
+ *  less"); a step budget is the DO method's own, and never above this. */
+export const STEP_TIMEOUT_MAX_MS = 30 * 60_000;
+
+/** A step's timeout in ms: the method's budget, capped at the platform's. */
+export function stepTimeoutMs(budgetMs: number): number {
+  if (!(budgetMs > 0)) throw new Error(`step budget must be positive, got ${budgetMs}`);
+  return Math.min(budgetMs, STEP_TIMEOUT_MAX_MS);
+}