@foldrun/core 1.2.0 → 1.4.0

package/dist/src/scan.js

@@ -28,6 +28,8 @@
 import crypto from "node:crypto";
 import matter from "gray-matter";
 import { refNames } from "./refs.js";
+import { resolveNetwork } from "./network.js";
+import { frontmatterProblems, schemaKindOf } from "./frontmatter-schema.js";
 export const OWASP_URL = "https://genai.owasp.org/resource/owasp-top-10-for-agentic-applications-for-2026";
 export const SCAN_RULES = [
     {
@@ -74,7 +76,8 @@ export const SCAN_RULES = [
         level: "warn",
         title: "Reads untrusted content, holds private data and can send it out",
         help: "An agent with all three can be told — by any page it reads — to send what it holds anywhere it can reach. " +
-            "Take one leg away: narrow `network:` to the sites it needs, split the reading and the sending into two agents, " +
+            "Take one leg away: take it off the open network (`network: { level: trusted, allow: [the sites it needs] }` — a bare list only adds sites, " +
+            "and an agent that reads the web stays open), split the reading and the sending into two agents, " +
             "or guard its calls with a `hooks:` gate. An approval (`!`) on every outward step is the other answer.",
         owasp: ["ASI01", "ASI02", "ASI03"],
     },
@@ -118,9 +121,32 @@ export const SCAN_RULES = [
         id: "config/unknown-field",
         category: "config",
         level: "warn",
-        title: "A frontmatter field foldrun does not read — likely a typo",
+        title: "A frontmatter field foldrun does not read here",
         help: "A misspelt field is not an error to YAML, so it is silently ignored: `tolls: [web]` leaves the agent with no tools. " +
-            "Use the field the message suggests.",
+            "A near-miss names the field it meant; a field read in another kind of file says where it belongs (warnings). " +
+            "A field like nothing foldrun reads is a note, since another tool may own it.",
+    },
+    {
+        id: "config/wrong-type",
+        category: "config",
+        level: "warn",
+        title: "A frontmatter field holding the wrong kind of value",
+        help: "A list where one name was meant, a map where a word was meant: the runtime does not read it. The message says what the field takes.",
+    },
+    {
+        id: "config/invalid-value",
+        category: "config",
+        level: "warn",
+        title: "A frontmatter value that does nothing",
+        help: "`effort: extreme`, `size: giant`, `trigger: sometimes`, a cron the scheduler cannot read: each is ignored or falls back, " +
+            "so the agent or flow quietly does something else. The message lists what the field takes.",
+    },
+    {
+        id: "config/missing-field",
+        category: "config",
+        level: "warn",
+        title: "A required frontmatter field is missing",
+        help: "A skill with no description is never loaded: the model chooses skills by their descriptions.",
     },
     {
         id: "check/ignore-needs-reason",
@@ -272,6 +298,41 @@ function credentialLike(value) {
 export function redactSecret(secret) {
     return secret.length <= 8 ? "****" : `${secret.slice(0, 4)}…${secret.slice(-2)}`;
 }
+/** Every credential in a piece of text, as [value, what]. One reading for
+ *  the secret rule and for any other rule that quotes the line. */
+function credentialsIn(line) {
+    const out = [];
+    const seen = new Set();
+    const add = (v, what) => {
+        if (!seen.has(v)) {
+            seen.add(v);
+            out.push([v, what]);
+        }
+    };
+    for (const [re, what] of SECRET_SHAPES) {
+        if (what === "a private key")
+            continue; // a header names a key; it is not one
+        for (const m of line.matchAll(re)) {
+            if (!PLACEHOLDER.test(m[0]) && entropy(m[0]) >= 3)
+                add(m[0], what);
+        }
+    }
+    for (const m of line.matchAll(ASSIGNED))
+        if (credentialLike(m[2]))
+            add(m[2], `\`${m[1]}\` with a literal value`);
+    for (const m of line.matchAll(BEARER))
+        if (credentialLike(m[1]))
+            add(m[1], "a bearer token");
+    return out;
+}
+/** The text with every credential in it redacted — for a finding that
+ *  quotes source, so no message ever carries a key whole. */
+export function redactText(text) {
+    let out = text;
+    for (const [v] of credentialsIn(text).sort((a, b) => b[0].length - a[0].length))
+        out = out.split(v).join(redactSecret(v));
+    return out;
+}
 function scanSecrets(file, lines, push) {
     for (let i = 0; i < lines.length; i++) {
         const line = lines[i];
@@ -351,13 +412,13 @@ function scanContent(file, lines, push) {
             const kind = HIDDEN_NAMES.find(([re]) => re.test(line))?.[1] ?? "invisible characters";
             const n = line.match(HIDDEN)?.length ?? 0;
             const tagged = /\uDB40[\uDC00-\uDC7F]/.test(line) ? ` that read as: "${decodeTags(line).slice(0, 80)}"` : "";
-            push("content/hidden-unicode", file.path, i + 1, line, `${n} ${kind}${tagged} — invisible to a reviewer, read by the model`);
+            push("content/hidden-unicode", file.path, i + 1, line, `${n} ${kind}${redactText(tagged)} — invisible to a reviewer, read by the model`);
         }
         // An instruction quoted inside a fence is an example of one, not one.
         if (data && !fenced) {
             const m = INJECTION.find((re) => re.test(line));
             if (m)
-                push("content/injection-phrase", file.path, i + 1, line, `"${line.trim().slice(0, 90)}" — agents read this file as data, and this line reads as an order`);
+                push("content/injection-phrase", file.path, i + 1, line, `"${redactText(line.trim()).slice(0, 90)}" — agents read this file as data, and this line reads as an order`);
         }
         if (md) {
             for (const b of line.matchAll(BLOB)) {
@@ -422,28 +483,6 @@ function unpinned(pkg) {
     return !/[=<>~!]/.test(s) && !/.@./.test(s.replace(/^@/, "x"));
 }
 // ── frontmatter ────────────────────────────────────────────────────────────
-/** What foldrun reads in an agent's frontmatter — the fields documented in
- *  agents.md, the Claude Code subagent fields an import carries, and the
- *  older spellings check already teaches about. Used only to suggest the
- *  field a typo meant: an unknown key that is nothing like any of these is
- *  left alone, since another tool may own it. */
-const AGENT_FIELDS = [
-    "name", "description", "model", "effort", "size", "tools", "disallowedTools", "skills", "hooks", "scripts",
-    "apis", "mcpServers", "agents", "subagents", "secrets", "limits", "network", "provider", "permissionMode",
-    "runtime", "ask", "web", "budget", "timezone", "language", "region", "currency", "units", "schedule", "color",
-    "memory", "foldrun_version", "use", "kind", "type", "notify", "triggers", "inputs", "outputs",
-];
-const FLOW_FIELDS = [
-    "name", "description", "trigger", "schedule", "timezone", "language", "region", "currency", "units", "model",
-    "effort", "overlap", "priority", "throttle", "debounce", "sla", "catchup", "pause_when", "disable_after",
-    "approvers", "approve_within", "notify", "at", "every", "budget", "limits", "size", "hooks", "inputs",
-    "webhook", "signing_secret", "signature", "idempotency", "filter", "after", "tags", "network", "secrets",
-];
-const TOOL_FIELDS = [
-    "name", "description", "transport", "type", "base", "methods", "headers", "query", "auth", "run", "args",
-    "command", "url", "env", "outward", "runtime", "secrets", "network", "timeout", "spec", "operations", "body",
-    "oauth", "limits", "input", "output", "schema", "kind",
-];
 function editDistance(a, b) {
     const d = Array.from({ length: a.length + 1 }, (_, i) => [i, ...Array(b.length).fill(0)]);
     for (let j = 1; j <= b.length; j++)
@@ -502,15 +541,13 @@ function docKind(p) {
 }
 // ── agents: what one can reach, taken together ─────────────────────────────
 const WRITE_METHODS = /\b(?:POST|PUT|PATCH|DELETE)\b/i;
-function scanAgents(agents, outward, toolDefs, push) {
+function scanAgents(agents, outward, toolDefs, push, networks) {
     const byName = new Map(agents.map((a) => [a.name, a]));
     for (const a of agents) {
         const d = a.data;
         const tools = refNames(d.tools);
         const denied = new Set(refNames(d.disallowedTools));
         const has = (t) => tools.includes(t) && !denied.has(t);
-        const network = d.network;
-        const netLevel = typeof network === "string" ? network : Array.isArray(network) ? "list" : network && typeof network === "object" ? "list" : null;
         // Untrusted: it reads the open web. (A webhook body is the other source;
         // that is a flow's trigger, and the flow-level rule is a later one.)
         const readsWeb = has("web") || tools.some((t) => /browse|fetch|scrape|crawl/i.test(t) && has(t));
@@ -519,16 +556,18 @@ function scanAgents(agents, outward, toolDefs, push) {
         const apis = Array.isArray(d.apis) ? d.apis : [];
         const mcp = d.mcpServers && typeof d.mcpServers === "object" ? Object.keys(d.mcpServers) : [];
         const privateLeg = [...secrets.map((s) => `secret ${s}`), ...apis.map((x) => `api ${x?.name ?? "?"}`), ...mcp.map((m) => `MCP ${m}`)];
-        // Out: a sandbox open to every site (an agent that reads the web is open
-        // unless it says otherwise), a tool marked outward, or an API it may write to.
-        const openNet = netLevel === "open" || (readsWeb && netLevel === null);
+        // Out: a sandbox open to every site, a tool marked outward, or an API it
+        // may write to. The level is the runtime's own resolution — agent, then
+        // workspace, then account, and open by default for an agent that reads
+        // the web; a bare list of sites adds to a level, it does not set one.
+        const openNet = resolveNetwork({ account: networks.account, workspace: networks.workspace, agent: d.network, readsWeb }).level === "open";
         const outwardTools = tools.filter((t) => outward.has(t) && !denied.has(t));
         const writeApis = apis.filter((x) => WRITE_METHODS.test(JSON.stringify(x?.methods ?? x?.method ?? "")));
         const outLeg = [...(openNet ? ["an open network"] : []), ...outwardTools.map((t) => `outward tool ${t}`), ...writeApis.map((x) => `writes to api ${x?.name ?? "?"}`)];
         const gated = refNames(d.hooks).length > 0 || d.permissionMode === "plan";
         if (readsWeb && privateLeg.length && outLeg.length && !gated) {
             push("security/lethal-trifecta", a.file, a.line, `trifecta ${a.name}`, `${a.name} reads the web, holds ${privateLeg.slice(0, 3).join(", ")}${privateLeg.length > 3 ? ", …" : ""} and can reach ${outLeg.slice(0, 2).join(" and ")} — ` +
-                `a page it reads can tell it where to send what it holds. Narrow network:, split it, or add a hooks: gate`);
+                `a page it reads can tell it where to send what it holds. Take it off the open network (network: { level: trusted, allow: [...] }), split it, or add a hooks: gate`);
         }
         // Sub-agents declaring tools the parent lacks.
         for (const s of refNames(d.subagents)) {
@@ -621,7 +660,7 @@ export function scanFiles(files, options = {}) {
     const findings = [];
     const seen = new Set();
     const ignoresByFile = new Map();
-    const push = (rule, file, line, text, message) => {
+    const push = (rule, file, line, text, message, level) => {
         if (!enabled(rule))
             return;
         const ig = ignoresByFile.get(file);
@@ -631,7 +670,7 @@ export function scanFiles(files, options = {}) {
         if (seen.has(key))
             return;
         seen.add(key);
-        findings.push({ rule, level: scanRule(rule)?.level ?? "warn", file, ...(line ? { line } : {}), message, fingerprint: findingFingerprint(rule, file, text) });
+        findings.push({ rule, level: level ?? scanRule(rule)?.level ?? "warn", file, ...(line ? { line } : {}), message, fingerprint: findingFingerprint(rule, file, text) });
     };
     const outward = new Set(options.outwardTools ?? []);
     const agents = [];
@@ -642,18 +681,23 @@ export function scanFiles(files, options = {}) {
         scanSecrets(f, lines, push);
         scanContent(f, lines, push);
         scanSupplyChain(f, lines, push);
-        const kind = docKind(f.path);
-        if (!kind)
-            continue;
-        const data = frontOf(f.content);
+        const schema = schemaKindOf(f.path);
+        // A skill with no frontmatter at all is the clearest one that never
+        // loads: read it as empty, so its required fields are reported.
+        const data = schema || docKind(f.path) ? (frontOf(f.content) ?? (schema === "skill" && !/^\uFEFF?---\r?\n/.test(f.content) ? {} : null)) : null;
         if (!data)
             continue;
-        const known = kind === "agent" ? AGENT_FIELDS : kind === "flow" ? FLOW_FIELDS : TOOL_FIELDS;
-        for (const key of Object.keys(data)) {
-            const near = nearestField(key, known);
-            if (near && near !== key)
-                push("config/unknown-field", f.path, keyLine(lines, key), `field ${key}`, `\`${key}:\` is not a field foldrun reads — did you mean \`${near}:\`? As written it is ignored`);
+        if (schema) {
+            for (const p of frontmatterProblems(schema, data, nearestField)) {
+                // Fingerprint the key's own line, not the parsed value: a YAML alias
+                // can make the value circular, and JSON of it would throw.
+                const at = keyLine(lines, p.key);
+                push(p.rule, f.path, at, `${p.rule} ${at ? lines[at - 1] : p.key}`, p.message, p.level);
+            }
         }
+        const kind = docKind(f.path);
+        if (!kind)
+            continue;
         if (kind === "agent") {
             const rel = f.path.replace(/^library\//, "");
             const name = /^agents\/([^/]+)\//.exec(rel)?.[1] ?? rel.replace(/^.*\/|\.md$/g, "");
@@ -666,7 +710,8 @@ export function scanFiles(files, options = {}) {
             toolDefs.set(f.path, { data, lines });
         }
     }
-    scanAgents(agents, outward, toolDefs, push);
+    const workspaceMd = files.find((f) => f.path === "AGENTS.md");
+    scanAgents(agents, outward, toolDefs, push, { account: options.accountNetwork, workspace: workspaceMd ? frontOf(workspaceMd.content)?.network : undefined });
     return findings.sort((a, b) => a.file.localeCompare(b.file) || (a.line ?? 0) - (b.line ?? 0) || a.rule.localeCompare(b.rule));
 }
 /**
@@ -698,7 +743,9 @@ export function applyBaseline(findings, baseline) {
     const b = baseline;
     if (!b || b.version !== 1 || !Array.isArray(b.findings))
         return { kept: findings, baselined: 0 };
-    const known = new Set(b.findings.map((f) => `${f.rule}\0${f.file}\0${f.fingerprint}`));
+    // An entry that is not {rule, file, fingerprint} hides nothing.
+    const entries = b.findings.filter((f) => !!f && typeof f === "object" && typeof f.rule === "string" && typeof f.file === "string" && typeof f.fingerprint === "string");
+    const known = new Set(entries.map((f) => `${f.rule}\0${f.file}\0${f.fingerprint}`));
     const kept = findings.filter((f) => !known.has(`${f.rule}\0${f.file}\0${f.fingerprint}`));
     return { kept, baselined: findings.length - kept.length };
 }

package/dist/src/store.d.ts

@@ -1,3 +1,4 @@
+import { EFFORT_LEVELS, FLOW_TRIGGERS } from "./frontmatter-fields.ts";
 import type { BrowserPodOutcome } from "./browser-pod.ts";
 import { singleWorkspace } from "./paths.ts";
 import type { TestEffect } from "./test-mode.ts";
@@ -354,7 +355,7 @@ export type Tier = keyof typeof MODEL_TIERS;
  *  `model:` does — one vocabulary, not two. */
 export declare function resolveTier(value: unknown): Tier | null;
 export declare function resolveModel(value: unknown): string;
-export declare const EFFORT_LEVELS: readonly ["low", "medium", "high", "xhigh", "max"];
+export { EFFORT_LEVELS } from "./frontmatter-fields.ts";
 export type Effort = (typeof EFFORT_LEVELS)[number];
 /**
  * `null` for both "not set" and "not a level we know" — unlike a model, the
@@ -607,7 +608,7 @@ export interface FlowInfo {
     frontProblems: string[];
     steps: FlowStep[];
 }
-export declare const FLOW_TRIGGERS: readonly ["manual", "schedule", "webhook", "email", "flow", "once", "watch", "storage"];
+export { FLOW_TRIGGERS } from "./frontmatter-fields.ts";
 export type FlowTrigger = (typeof FLOW_TRIGGERS)[number];
 export interface AgentAssets {
     skills: string[];
@@ -615,6 +616,12 @@ export interface AgentAssets {
 }
 export declare function agentAssets(tenant: string, workspace: string, agent: string): AgentAssets;
 export declare function listAgents(tenant: string, workspace: string): AgentInfo[];
+/** The option keys a step actually has. An indented `word: rest` that is
+ *  NOT one of these is a line of the instruction — "Warning: do not
+ *  publish" is prose that happens to contain a colon, and it used to be
+ *  swallowed as an unknown option, silently, along with any typo of a real
+ *  key. The consistency suite reads this list against the docs. */
+export declare const STEP_OPTION_KEYS: ReadonlySet<string>;
 /** The most fan-out instances `parallel:` may run at once — the fan-out's
  *  own hard cap, since more slots than items is no cap. */
 export declare const PARALLEL_CAP = 20;

package/dist/src/store.js

@@ -20,6 +20,7 @@
 //
 // An account is a named directory (per OKF: tenancy is a hosting concern).
 import { expandPlatformVars } from "./host-env.js";
+import { FLOW_TRIGGERS } from "./frontmatter-fields.js";
 import fs from "node:fs";
 import path from "node:path";
 import { recordRevision, registerTreeReader } from "./history.js";
@@ -899,7 +900,7 @@ export function resolveModel(value) {
 // model is which brain, effort is how long it thinks before answering. The
 // five levels are the SDK's own union — we neither invent our own scale nor
 // narrow theirs, so a level added upstream is one line here.
-export const EFFORT_LEVELS = ["low", "medium", "high", "xhigh", "max"];
+export { EFFORT_LEVELS } from "./frontmatter-fields.js";
 const EFFORT_ALIASES = {
     low: "low",
     min: "low",
@@ -1020,7 +1021,8 @@ export function parseApis(raw) {
     }
     return out;
 }
-export const FLOW_TRIGGERS = ["manual", "schedule", "webhook", "email", "flow", "once", "watch", "storage"];
+// The list lives with every other frontmatter field (frontmatter-fields.ts).
+export { FLOW_TRIGGERS } from "./frontmatter-fields.js";
 export function agentAssets(tenant, workspace, agent) {
     const base = path.join(workspaceDir(tenant, workspace), "agents", agent);
     const nameOf = (file, fallback) => {
@@ -1177,7 +1179,7 @@ const OPTION_RE = /^(\s+)([a-z_-]+):(.*)$/;
  *  publish" is prose that happens to contain a colon, and it used to be
  *  swallowed as an unknown option, silently, along with any typo of a real
  *  key. The consistency suite reads this list against the docs. */
-const STEP_OPTION_KEYS = new Set([
+export const STEP_OPTION_KEYS = new Set([
     "approve", "ask", "case", "delegate", "each", "effort", "else", "limits", "loop", "max", "max_turns", "model",
     "on-fail", "onfail", "output", "parallel", "preview", "retry", "schema", "timeout", "until", "verify", "wait", "when",
 ]);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@foldrun/core",
-  "version": "1.2.0",
+  "version": "1.4.0",
   "description": "Agents are just folders. The format, the runner, the checks.",
   "license": "SEE LICENSE IN LICENSE",
   "type": "module",

package/src/completions.ts

@@ -10,6 +10,7 @@
 // renders them.
 
 import { PROVIDERS } from "./providers.ts";
+import { FRONTMATTER, type SchemaKind } from "./frontmatter-fields.ts";
 
 export interface Vocabulary {
   agents: string[];
@@ -207,8 +208,6 @@ const FIELDS: Record<string, Completion[]> = {
     { label: "trigger", insert: "trigger: manual" },
     { label: "schedule", insert: "schedule: \"0 6 * * MON\"" },
     { label: "timezone", insert: "timezone: Australia/Sydney" },
-    { label: "language", insert: "language: en-AU" },
-    { label: "region", insert: "region: au", hint: "currency, units, calendar, weekend and text direction follow" },
     { label: "model", insert: "model: fast", hint: "every step, unless the step says" },
     { label: "effort", insert: "effort: high", hint: "every step, unless the step says" },
   ],
@@ -264,6 +263,27 @@ export function fileKind(path: string): FileKind {
   return "note";
 }
 
+/** Which frontmatter schema a completion kind offers. */
+const SCHEMA_OF: Partial<Record<FileKind, SchemaKind>> = { agent: "agent", flow: "flow", tool: "tool", skill: "skill", evalFile: "eval" };
+
+/**
+ * The fields to offer at the start of a frontmatter line: the hand-written
+ * snippets above where a field has one, then every other field the schema
+ * says this kind of file takes — so a field added to frontmatter-fields.ts is
+ * offered here with no second edit, and a snippet for a field the runtime no
+ * longer reads is dropped. AGENTS.md takes its own set, not an agent's.
+ */
+function fieldsFor(path: string, kind: FileKind): Completion[] {
+  const agentsMd = /(^|\/)AGENTS\.md$/.test(path) || path === "project.md";
+  const schema = agentsMd ? FRONTMATTER["agents-md"] : SCHEMA_OF[kind] ? FRONTMATTER[SCHEMA_OF[kind]!] : null;
+  if (!schema) return FIELDS[kind];
+  const offered = schema.filter((f) => !f.legacy);
+  const keys = new Set(offered.map((f) => f.key));
+  const curated = FIELDS[kind].filter((c) => keys.has(c.label.split(".")[0]!));
+  const have = new Set(curated.map((c) => c.label.split(".")[0]));
+  return [...curated, ...offered.filter((f) => !have.has(f.key)).map((f) => ({ label: f.key, insert: `${f.key}: `, hint: f.help }))];
+}
+
 /**
  * Does [[ ]] in this file get expanded into a path, or stay literal?
  *
@@ -654,9 +674,9 @@ export function completionsAt(
   //    this kind of file. This is where you learn the format by writing it.
   const fmEnd = text.indexOf("\n---", text.indexOf("---") + 3);
   const inFrontmatter = text.startsWith("---") && (fmEnd === -1 || cursor <= fmEnd);
-  if (inFrontmatter && /^[a-zA-Z_]*$/.test(line)) {
+  if (inFrontmatter && /^[a-zA-Z_][a-zA-Z_-]*$|^$/.test(line)) {
     const from = cursor - line.length;
-    return { from, query: line, items: filter(FIELDS[kind], line), title: `${kind} fields` };
+    return { from, query: line, items: filter(fieldsFor(path, kind), line), title: `${kind} fields` };
   }
 
   return null;

package/src/cron.ts

@@ -0,0 +1,120 @@
+// Cron: the one reading of a flow's `schedule:`.
+//
+// Moved here from the platform's scheduler so `foldrun check`, the deploy and
+// the scheduler ask the same function whether a schedule is one — a cron the
+// scheduler cannot parse used to be skipped silently, and nothing earlier
+// said so. The scheduler imports this; the expansion is unchanged.
+
+
+export const NAMED: Record<string, string> = {
+  "@hourly": "0 * * * *",
+  "@daily": "0 0 * * *",
+  "@midnight": "0 0 * * *",
+  "@weekly": "0 0 * * 0",
+  "@monthly": "0 0 1 * *",
+};
+
+export const DOW_NAMES = ["sun", "mon", "tue", "wed", "thu", "fri", "sat"];
+const MONTH_NAMES = ["jan", "feb", "mar", "apr", "may", "jun", "jul", "aug", "sep", "oct", "nov", "dec"];
+
+// Expand one cron field ("*", "*/15", "1-5", "mon,fri", "3") to a value set.
+function expandField(field: string, min: number, max: number, names?: string[]): Set<number> | null {
+  const out = new Set<number>();
+  for (const part of field.split(",")) {
+    const [rangePart, stepPart] = part.split("/");
+    const step = stepPart ? Number(stepPart) : 1;
+    if (!Number.isInteger(step) || step < 1) return null;
+
+    let lo = min;
+    let hi = max;
+    if (rangePart !== "*") {
+      const bounds = rangePart.split("-");
+      const parse = (raw: string): number | null => {
+        const token = raw.trim().toLowerCase();
+        if (names) {
+          // A name counts from the field's own minimum: SUN is 0 on the
+          // weekday field, JAN is 1 on the month field. Indexed from zero,
+          // JAN read as 0 (refused — the flow never fired) and FEB…DEC as
+          // the month before.
+          const idx = names.indexOf(token);
+          if (idx !== -1) return min + idx;
+        }
+        const n = Number(token);
+        return Number.isInteger(n) ? n : null;
+      };
+      const a = parse(bounds[0]);
+      if (a === null) return null;
+      lo = a;
+      if (bounds.length > 1) {
+        const b = parse(bounds[1]);
+        if (b === null) return null;
+        hi = b;
+      } else {
+        hi = stepPart ? max : a; // "5" → just 5; "5/10" → 5,15,25...
+      }
+    }
+    if (lo < min || hi > max || lo > hi) return null;
+    for (let v = lo; v <= hi; v += step) out.add(v);
+  }
+  return out;
+}
+
+export interface Cron {
+  minute: Set<number>;
+  hour: Set<number>;
+  dom: Set<number>;
+  month: Set<number>;
+  dow: Set<number>;
+  domRestricted: boolean;
+  dowRestricted: boolean;
+  /** Neither minute nor hour is a wildcard: a job at a time of day, which
+   *  is what the DST rules in cronMatches apply to (as in Vixie cron). */
+  fixedTime: boolean;
+}
+
+/** `@daily` → its five fields; anything else as written. An own-property
+ *  lookup, so `schedule: constructor` is a bad cron, not a crash. */
+function expand(expr: string): string {
+  const key = expr.trim().toLowerCase();
+  return (Object.hasOwn(NAMED, key) ? NAMED[key]! : expr).trim();
+}
+
+export function parseCron(expr: string): Cron | null {
+  if (typeof expr !== "string") return null;
+  const normalized = expand(expr);
+  const fields = normalized.split(/\s+/);
+  if (fields.length !== 5) return null;
+  const [mi, ho, dm, mo, dw] = fields;
+
+  const minute = expandField(mi, 0, 59);
+  const hour = expandField(ho, 0, 23);
+  const dom = expandField(dm, 1, 31);
+  const month = expandField(mo, 1, 12, MONTH_NAMES);
+  const dowRaw = expandField(dw, 0, 7, DOW_NAMES);
+  if (!minute || !hour || !dom || !month || !dowRaw) return null;
+
+  // cron allows both 0 and 7 for Sunday.
+  const dowSet = new Set([...dowRaw].map((d) => (d === 7 ? 0 : d)));
+
+  return {
+    minute,
+    hour,
+    dom,
+    month,
+    dow: dowSet,
+    domRestricted: dm.trim() !== "*",
+    dowRestricted: dw.trim() !== "*",
+    fixedTime: !mi.startsWith("*") && !ho.startsWith("*"),
+  };
+}
+
+
+/** Why `schedule:` is not a cron the scheduler can run, or null when it is. */
+export function cronProblem(expr: unknown): string | null {
+  if (typeof expr !== "string" || !expr.trim()) return "schedule: is a cron expression — five fields, or @hourly, @daily, @weekly, @monthly";
+  if (parseCron(expr)) return null;
+  const fields = expand(expr).split(/\s+/).length;
+  return fields !== 5
+    ? `schedule: "${expr}" has ${fields} field${fields === 1 ? "" : "s"}; cron has five — minute hour day-of-month month day-of-week ("0 9 * * MON"), or @hourly, @daily, @weekly, @monthly. As written the flow never fires`
+    : `schedule: "${expr}" is not a cron the scheduler can read — a field is out of range or not a number (minute 0-59, hour 0-23, day 1-31, month 1-12, weekday 0-7 or sun-sat). As written the flow never fires`;
+}