@relayflows/surface 2.0.16 → 2.0.17

package/dist/triggers.d.ts

@@ -1,3 +1,4 @@
+import type { ScheduleTriggerSource } from "./schedule.js";
 export type WebhookValue = null | boolean | number | string | readonly WebhookValue[] | {
     readonly [key: string]: WebhookValue;
 };
@@ -5,11 +6,13 @@ export type WebhookValue = null | boolean | number | string | readonly WebhookVa
 export type WebhookFilter = {
     readonly [key: string]: WebhookValue;
 };
-export interface TriggerSource {
+export interface WebhookTriggerSource {
     readonly kind: "webhook";
     readonly name: string;
     readonly filter?: WebhookFilter;
 }
+/** A webhook inbox subscription, or a `schedule.*` tick subscription. */
+export type TriggerSource = WebhookTriggerSource | ScheduleTriggerSource;
 /** Plain, immutable data. Constructing a source opens no receiver. */
-export declare function webhook(name: string, filter?: WebhookFilter): TriggerSource;
+export declare function webhook(name: string, filter?: WebhookFilter): WebhookTriggerSource;
 //# sourceMappingURL=triggers.d.ts.map

package/dist/triggers.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"triggers.d.ts","sourceRoot":"","sources":["../src/triggers.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,YAAY,GAAG,IAAI,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,GACvD,SAAS,YAAY,EAAE,GAAG;IAAE,QAAQ,EAAE,GAAG,EAAE,MAAM,GAAG,YAAY,CAAA;CAAE,CAAC;AAEvE,sEAAsE;AACtE,MAAM,MAAM,aAAa,GAAG;IAAE,QAAQ,EAAE,GAAG,EAAE,MAAM,GAAG,YAAY,CAAA;CAAE,CAAC;AAErE,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IACzB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,CAAC,EAAE,aAAa,CAAC;CACjC;AAED,sEAAsE;AACtE,wBAAgB,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,aAAa,GAAG,aAAa,CAS3E"}
+{"version":3,"file":"triggers.d.ts","sourceRoot":"","sources":["../src/triggers.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,eAAe,CAAC;AAE3D,MAAM,MAAM,YAAY,GAAG,IAAI,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,GACvD,SAAS,YAAY,EAAE,GAAG;IAAE,QAAQ,EAAE,GAAG,EAAE,MAAM,GAAG,YAAY,CAAA;CAAE,CAAC;AAEvE,sEAAsE;AACtE,MAAM,MAAM,aAAa,GAAG;IAAE,QAAQ,EAAE,GAAG,EAAE,MAAM,GAAG,YAAY,CAAA;CAAE,CAAC;AAErE,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IACzB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,CAAC,EAAE,aAAa,CAAC;CACjC;AAED,yEAAyE;AACzE,MAAM,MAAM,aAAa,GAAG,oBAAoB,GAAG,qBAAqB,CAAC;AAEzE,sEAAsE;AACtE,wBAAgB,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,aAAa,GAAG,oBAAoB,CASlF"}

package/dist/triggers.js.map

@@ -1 +1 @@
-{"version":3,"file":"triggers.js","sourceRoot":"","sources":["../src/triggers.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"triggers.js","sourceRoot":"","sources":["../src/triggers.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@relayflows/surface",
-  "version": "2.0.16",
+  "version": "2.0.17",
   "description": "TypeScript authoring surface for Relayflows.",
   "type": "module",
   "main": "./dist/index.js",

package/src/context.ts

@@ -6,12 +6,30 @@ import type { Step } from "./step.js";
 
 export interface AgentResult {
   summary: string;
+  /**
+   * Files the agent created or changed under its working directory,
+   * cwd-relative POSIX paths, sorted — as journaled by the worker that spawned
+   * the CLI on the step's `step.completed`, never re-measured later. Empty
+   * for the relay transport (the agent ran elsewhere) and for an agent whose
+   * final message is a JSON object (that object is the output, unmodified).
+   */
   artifacts: string[];
 }
 
+/** Per-step declarations: validated and recorded, not currently enforced (gate 8 / #442).
+ * Separate from flow-wide FlowHeader.workspace / tools.fs scopes.
+ */
+export interface PermissionsSpec {
+  fileGlobs?: string[];
+  networkAllowlist?: string[];
+  accessPreset?: 'readonly' | 'readwrite';
+}
+
 export interface AgentOptions {
   task: string;
   workspace?: string;
+  /** Validated declaration only; not currently enforced (gate 8 / #442). */
+  permissions?: PermissionsSpec;
   cli?: string;
   model?: string;
   /** Working directory for the CLI subprocess; defaults to the flow-runner's cwd. */

package/src/flow.ts

@@ -3,6 +3,7 @@ import type { Helpers } from "./helpers/index.js";
 type HelperTools = Partial<Record<keyof Helpers, boolean>>;
 import type { Ctx } from "./context.js";
 import { webhook, type TriggerSource } from "./triggers.js";
+import { schedule } from "./schedule.js";
 
 /** Optional escalation header; the empty header is the common case. */
 export interface FlowHeader {
@@ -91,9 +92,22 @@ function makeHandle(definition: AuthoredFlowDefinition): FlowHandle {
     value: <Event>(trigger: TriggerSource, body: FlowBody<Event>): TriggeredFlowHandle => {
       if (typeof body !== "function") throw new TypeError("trigger handler requires a body");
       assertHeaderObject(trigger, "trigger");
-      assertKnownKeys(trigger, ["kind", "name", "filter"], "trigger");
-      if (trigger.kind !== "webhook") throw new TypeError("unsupported trigger kind");
-      const source = webhook(trigger.name, trigger.filter);
+      let source: TriggerSource;
+      if (trigger.kind === "schedule") {
+        assertKnownKeys(trigger, ["kind", "name", "cron", "tz", "intervalMs", "epochMs"], "trigger");
+        // Re-derive from the declaration rather than trusting the object: the
+        // parsed form is what the SDK lowers, so it must be one this module made.
+        source = trigger.cron !== undefined
+          ? schedule.cron(trigger.cron, trigger.tz === undefined ? {} : { tz: trigger.tz })
+          : schedule.every(`${Math.round((trigger.intervalMs ?? 0) / 1000)}s`);
+        if (source.intervalMs !== trigger.intervalMs || source.epochMs !== trigger.epochMs) {
+          throw new TypeError("schedule trigger grid does not match its declaration");
+        }
+      } else {
+        assertKnownKeys(trigger, ["kind", "name", "filter"], "trigger");
+        if (trigger.kind !== "webhook") throw new TypeError("unsupported trigger kind");
+        source = webhook(trigger.name, trigger.filter);
+      }
       return makeHandle(Object.freeze({
         ...definition,
         handlers: Object.freeze([...definition.handlers, Object.freeze({ trigger: source, body: body as FlowBody })]),

package/src/index.ts

@@ -7,7 +7,7 @@ export type {
   WorkerSummary,
   CloudHelper,
 } from "./cloud.js";
-export type { AgentOptions, AgentResult, LlmOptions, Ctx } from "./context.js";
+export type { AgentOptions, AgentResult, PermissionsSpec, LlmOptions, Ctx } from "./context.js";
 export {
   COMPLETION_REASONS,
   RUN_COMPLETION_REASONS,
@@ -41,7 +41,11 @@ export {
 } from "./slack.js";
 export type { Helpers } from "./helpers/index.js";
 export type { MemoryHelper, MemoryFinding, MemoryRecallOptions, HistoryEntry, TrajectoryEntry } from "./memory.js";
-export { webhook, type TriggerSource, type WebhookFilter, type WebhookValue } from "./triggers.js";
+export { webhook, type TriggerSource, type WebhookTriggerSource, type WebhookFilter, type WebhookValue } from "./triggers.js";
+export {
+  schedule, scheduleIdFor, parseCron, cronGrid, cronFixedIntervalMs, cronMaxGapMs, everyToMs,
+  type ScheduleTriggerSource, type ScheduleCronOptions, type CronFields, type CronGrid,
+} from "./schedule.js";
 export * from "./triggers/index.js";
 export type { ProviderTriggerSource } from "./provider-trigger.js";
 export type { PluginMethod, PluginPrimitive } from './plugin-contract.js';

package/src/provider-trigger.ts

@@ -1,7 +1,7 @@
-import { webhook, type TriggerSource, type WebhookFilter } from "./triggers.js";
+import { webhook, type WebhookTriggerSource, type WebhookFilter } from "./triggers.js";
 
 /** A provider inbox subscription over an envelope's type and payload. */
-export interface ProviderTriggerSource<Provider extends string, Event extends string> extends TriggerSource {
+export interface ProviderTriggerSource<Provider extends string, Event extends string> extends WebhookTriggerSource {
   readonly name: Provider;
   readonly filter: WebhookFilter & { readonly provider: Provider; readonly type: Event };
 }

package/src/schedule.ts

@@ -0,0 +1,282 @@
+/**
+ * Schedule triggers. Hand-written, unlike the provider namespaces under
+ * `triggers/`, because a schedule is not a provider event: there is no inbox
+ * and no upstream mapping to generate from. A schedule is an event source —
+ * locally the `flows tick` runner, on Cloud a relaycron cron — that submits
+ * `flows.tick` events, and this namespace declares which ticks a flow wants.
+ *
+ * Constructing a source opens nothing. The SDK lowers it to the same
+ * `flows.tick` subscription `testdata/tick-heartbeat.flow.yaml` writes by
+ * hand (`scheduleTriggerSpec`), and `flows schedule` sends the cron to Cloud.
+ */
+
+export interface ScheduleTriggerSource {
+  readonly kind: "schedule";
+  /** Fixed: every schedule is delivered as a `flows.tick` event. */
+  readonly name: "flows.tick";
+  /** A 5-field cron expression, when declared with `schedule.cron`. */
+  readonly cron?: string;
+  /** IANA zone for `cron`; defaults to UTC. */
+  readonly tz?: string;
+  /** Fixed interval in milliseconds, when declared with `schedule.every` or when `cron` is exactly a tick grid. */
+  readonly intervalMs?: number;
+  /** Phase of that grid: the first fire is `epochMs` past the Unix epoch; present exactly when `intervalMs` is. */
+  readonly epochMs?: number;
+}
+
+export interface ScheduleCronOptions {
+  readonly tz?: string;
+}
+
+const EVERY = /^(\d+)(s|m|h|d)$/u;
+const UNIT_MS = { s: 1_000, m: 60_000, h: 3_600_000, d: 86_400_000 } as const;
+
+/** `every("5m")` — a fixed interval. Units: s, m, h, d. Minimum one second. */
+export function everyToMs(value: string): number {
+  const match = typeof value === "string" ? EVERY.exec(value.trim()) : null;
+  if (!match) throw new TypeError(`schedule.every expects <n><s|m|h|d>, got ${JSON.stringify(value)}`);
+  const ms = Number(match[1]) * UNIT_MS[match[2] as keyof typeof UNIT_MS];
+  if (!Number.isSafeInteger(ms) || ms < 1_000) throw new TypeError("schedule.every must be at least 1s");
+  return ms;
+}
+
+export interface CronFields {
+  readonly minute: string;
+  readonly hour: string;
+  readonly dayOfMonth: string;
+  readonly month: string;
+  readonly dayOfWeek: string;
+}
+
+const FIELD_RANGES = [[0, 59], [0, 23], [1, 31], [1, 12], [0, 7]] as const;
+const NAMES: Record<number, readonly string[]> = {
+  3: ["jan", "feb", "mar", "apr", "may", "jun", "jul", "aug", "sep", "oct", "nov", "dec"],
+  4: ["sun", "mon", "tue", "wed", "thu", "fri", "sat"],
+};
+
+/**
+ * Standard five-field cron. Accepts `*`, values, ranges, lists and `/step`,
+ * plus month and weekday names; refuses anything outside each field's range.
+ * Validation, not evaluation — the schedule's clock is the runner's.
+ */
+export function parseCron(expression: string): CronFields {
+  const fields = typeof expression === "string" ? expression.trim().split(/\s+/u) : [];
+  if (fields.length !== 5) {
+    throw new TypeError(`cron expression must have five fields (minute hour day-of-month month day-of-week), got ${JSON.stringify(expression)}`);
+  }
+  fields.forEach((field, index) => {
+    const [low, high] = FIELD_RANGES[index]!;
+    for (const part of field.split(",")) {
+      const pieces = part.split("/");
+      if (pieces.length > 2 || part.length === 0) throw new TypeError(`cron field ${index + 1}: invalid ${JSON.stringify(part)}`);
+      const [range, step] = pieces;
+      if (step !== undefined && (!/^\d+$/u.test(step) || Number(step) < 1)) {
+        throw new TypeError(`cron field ${index + 1}: invalid step in ${JSON.stringify(part)}`);
+      }
+      if (range === "*") continue;
+      const bounds = range!.split("-");
+      if (bounds.length > 2) throw new TypeError(`cron field ${index + 1}: invalid range ${JSON.stringify(part)}`);
+      for (const bound of bounds) {
+        // Month names are 1-based (jan = 1); weekday names are 0-based (sun = 0).
+        const named = NAMES[index]?.indexOf(bound.toLowerCase());
+        const value = /^\d+$/u.test(bound) ? Number(bound)
+          : named === undefined || named === -1 ? undefined : named + (index === 3 ? 1 : 0);
+        if (value === undefined || value < low || value > high) {
+          throw new TypeError(`cron field ${index + 1}: ${JSON.stringify(bound)} is outside ${low}-${high}`);
+        }
+      }
+    }
+  });
+  return Object.freeze({
+    minute: fields[0]!, hour: fields[1]!, dayOfMonth: fields[2]!, month: fields[3]!, dayOfWeek: fields[4]!,
+  });
+}
+
+/** A tick grid that reproduces a cron exactly: fire every `intervalMs`, phase-aligned at `epochMs` past the Unix epoch. */
+export interface CronGrid {
+  readonly intervalMs: number;
+  readonly epochMs: number;
+}
+
+// The tick grid a cron expression amounts to, when one reproduces it exactly.
+// The tick source fires at epochMs + k*intervalMs, so a cron is representable
+// only when its period divides the next field's cycle (every N minutes with
+// 60 % N == 0, every N hours with 24 % N == 0) and its phase is a single
+// fixed value in the finer fields. `*/7 * * * *` is not (cron restarts the
+// minute count each hour, a grid does not); `15 * * * *` is, with a 15-minute
+// phase. Anything with day, month or weekday constraints, lists or ranges is
+// not a grid — only a cron-aware runner (Cloud's relaycron) can drive it.
+// Time zones: a grid is anchored in UTC, so only UTC schedules qualify; an
+// offset zone would shift the phase and a DST zone would move it twice a year.
+export function cronGrid(fields: CronFields, tz?: string): CronGrid | undefined {
+  const { minute, hour, dayOfMonth, month, dayOfWeek } = fields;
+  if (dayOfMonth !== "*" || month !== "*" || dayOfWeek !== "*") return undefined;
+  if (tz !== undefined && tz !== "UTC" && tz !== "Etc/UTC") return undefined;
+  const every = (field: string, cycle: number): number | undefined => {
+    if (field === "*") return 1;
+    const match = /^\*\/(\d+)$/u.exec(field);
+    if (!match) return undefined;
+    const step = Number(match[1]);
+    return step >= 1 && cycle % step === 0 ? step : undefined;
+  };
+  const fixed = (field: string): number | undefined => (/^\d+$/u.test(field) ? Number(field) : undefined);
+  const minuteStep = every(minute, 60);
+  if (minuteStep !== undefined && hour === "*") return { intervalMs: minuteStep * UNIT_MS.m, epochMs: 0 };
+  const minutePhase = fixed(minute);
+  const hourStep = every(hour, 24);
+  if (minutePhase !== undefined && hourStep !== undefined) {
+    return { intervalMs: hourStep * UNIT_MS.h, epochMs: minutePhase * UNIT_MS.m };
+  }
+  const hourPhase = fixed(hour);
+  if (minutePhase !== undefined && hourPhase !== undefined) {
+    return { intervalMs: UNIT_MS.d, epochMs: hourPhase * UNIT_MS.h + minutePhase * UNIT_MS.m };
+  }
+  return undefined;
+}
+
+/** The fixed interval of a cron, when `cronGrid` finds one. Kept for callers that only need the period. */
+export function cronFixedIntervalMs(fields: CronFields, tz?: string): number | undefined {
+  return cronGrid(fields, tz)?.intervalMs;
+}
+
+function cronFieldMatches(field: string, value: number, index: number): boolean {
+  const [low, high] = FIELD_RANGES[index]!;
+  const named = (bound: string): number => {
+    if (/^\d+$/u.test(bound)) return Number(bound);
+    return NAMES[index]!.indexOf(bound.toLowerCase()) + (index === 3 ? 1 : 0);
+  };
+  return field.split(",").some((part) => {
+    const [range, step] = part.split("/");
+    const stride = step === undefined ? 1 : Number(step);
+    let from: number;
+    let to: number;
+    // `N/step` runs from N to the field's maximum — for weekdays that is 7,
+    // so `1/2` reaches Sunday-as-7 and the normalisation below applies.
+    if (range === "*") { from = low; to = index === 4 ? 6 : high; }
+    else {
+      const bounds = range!.split("-").map(named);
+      from = bounds[0]!;
+      to = bounds.length === 2 ? bounds[1]! : step === undefined ? bounds[0]! : high;
+    }
+    // Weekday 7 is Sunday, as 0 is. A lone `7` or a range ending in 7 is
+    // tested against Sunday-as-0 as well, so a stride counted from the
+    // range start still lands on it: `1-7/2` fires Mon, Wed, Fri, Sun.
+    if (index === 4 && to === 7) {
+      if (from === 7) return value === 0;
+      if (value === 0 && (7 - from) % stride === 0) return true;
+      to = 6;
+    }
+    return value >= from && value <= to && (value - from) % stride === 0;
+  });
+}
+
+/**
+ * The longest gap between consecutive fires over two calendar years (one of
+ * them leap), in milliseconds — a cron's natural quiet period. Evaluated on
+ * the UTC calendar minute by minute; a zone offset does not change gap
+ * lengths, and a DST shift changes one gap by at most an hour, which the
+ * callers' multiple absorbs. An expression that fires at most once in the
+ * span reports the whole span. Returns undefined when it never fires.
+ */
+export function cronMaxGapMs(fields: CronFields): number | undefined {
+  const start = Date.UTC(2024, 0, 1);
+  const end = Date.UTC(2026, 0, 1);
+  let previous: number | undefined;
+  let first: number | undefined;
+  let maxGap = 0;
+  for (let t = start; t < end; t += UNIT_MS.m) {
+    const d = new Date(t);
+    const dom = fields.dayOfMonth === "*";
+    const dow = fields.dayOfWeek === "*";
+    const dayMatches = dom && dow
+      ? true
+      // POSIX: when both day fields are restricted, either matching fires.
+      : dom !== dow
+        ? (dom ? cronFieldMatches(fields.dayOfWeek, d.getUTCDay(), 4) : cronFieldMatches(fields.dayOfMonth, d.getUTCDate(), 2))
+        : cronFieldMatches(fields.dayOfMonth, d.getUTCDate(), 2) || cronFieldMatches(fields.dayOfWeek, d.getUTCDay(), 4);
+    if (!dayMatches || !cronFieldMatches(fields.month, d.getUTCMonth() + 1, 3)
+      || !cronFieldMatches(fields.hour, d.getUTCHours(), 1) || !cronFieldMatches(fields.minute, d.getUTCMinutes(), 0)) continue;
+    if (previous !== undefined) maxGap = Math.max(maxGap, t - previous);
+    else first = t;
+    previous = t;
+  }
+  if (first === undefined || previous === undefined) return undefined;
+  return maxGap > 0 ? maxGap : end - start;
+}
+
+function assertTimeZone(tz: string): string {
+  if (typeof tz !== "string" || tz.trim().length === 0) throw new TypeError("schedule tz must be an IANA zone name");
+  try {
+    new Intl.DateTimeFormat("en-US", { timeZone: tz });
+  } catch {
+    throw new TypeError(`schedule tz ${JSON.stringify(tz)} is not a known IANA zone`);
+  }
+  return tz;
+}
+
+export const schedule = Object.freeze({
+  /** A five-field cron, evaluated in `tz` (default UTC). */
+  cron(expression: string, options: ScheduleCronOptions = {}): ScheduleTriggerSource {
+    const fields = parseCron(expression);
+    const tz = options.tz === undefined ? undefined : assertTimeZone(options.tz);
+    const grid = cronGrid(fields, tz);
+    return Object.freeze({
+      kind: "schedule", name: "flows.tick",
+      cron: expression.trim().split(/\s+/u).join(" "),
+      ...(tz === undefined ? {} : { tz }),
+      ...(grid === undefined ? {} : { intervalMs: grid.intervalMs, epochMs: grid.epochMs }),
+    });
+  },
+  /** A fixed interval: `every("5m")`, `every("2h")`. Units s, m, h, d. */
+  every(interval: string): ScheduleTriggerSource {
+    return Object.freeze({ kind: "schedule", name: "flows.tick", intervalMs: everyToMs(interval), epochMs: 0 });
+  },
+});
+
+/** UTF-8 code units of a string, without TextEncoder: this package compiles against no DOM or Node lib. */
+function utf8Bytes(text: string): number[] {
+  const bytes: number[] = [];
+  for (const char of text) {
+    const cp = char.codePointAt(0)!;
+    if (cp < 0x80) bytes.push(cp);
+    else if (cp < 0x800) bytes.push(0xc0 | (cp >> 6), 0x80 | (cp & 0x3f));
+    else if (cp < 0x10000) bytes.push(0xe0 | (cp >> 12), 0x80 | ((cp >> 6) & 0x3f), 0x80 | (cp & 0x3f));
+    else bytes.push(0xf0 | (cp >> 18), 0x80 | ((cp >> 12) & 0x3f), 0x80 | ((cp >> 6) & 0x3f), 0x80 | (cp & 0x3f));
+  }
+  return bytes;
+}
+
+/** 64-bit FNV-1a over UTF-8, as 16 hex characters. Dependency-free; not a security hash, an identity. */
+function fnv1a64(text: string): string {
+  let hi = 0xcbf29ce4, lo = 0x84222325;
+  for (const byte of utf8Bytes(text)) {
+    lo ^= byte;
+    // (hi:lo) * 0x100000001b3 mod 2^64, in 16-bit limbs to stay exact in doubles.
+    const l0 = lo & 0xffff, l1 = lo >>> 16, h0 = hi & 0xffff, h1 = hi >>> 16;
+    let a = l0 * 0x01b3;
+    let b = l1 * 0x01b3 + (a >>> 16);
+    let c = h0 * 0x01b3 + (b >>> 16) + l0;
+    let d = h1 * 0x01b3 + (c >>> 16) + l1;
+    lo = ((b & 0xffff) << 16 | (a & 0xffff)) >>> 0;
+    hi = ((d & 0xffff) << 16 | (c & 0xffff)) >>> 0;
+  }
+  return hi.toString(16).padStart(8, "0") + lo.toString(16).padStart(8, "0");
+}
+
+/**
+ * The `schedule_id` a flow's schedule subscribes to. Deterministic from the
+ * flow name and the declaration, so the local runner, `flows check` and the
+ * journal all name the same slot stream without a registry — and injective:
+ * a readable slug for humans, plus a hash of the exact declaration so
+ * `1-5` and `1,5`, or two zones, or two long names sharing a prefix, never
+ * share a stream (the kernel dispatches an event to its first matching
+ * subscription only).
+ */
+export function scheduleIdFor(flowName: string, source: ScheduleTriggerSource): string {
+  const canonical = JSON.stringify([flowName, source.cron ?? null, source.tz ?? null, source.intervalMs ?? null, source.epochMs ?? null]);
+  const spec = source.cron !== undefined
+    ? `cron-${source.cron}${source.tz === undefined ? "" : `-${source.tz}`}`
+    : `every-${source.intervalMs}ms`;
+  const slug = `${flowName}-${spec}`.toLowerCase().replace(/[^a-z0-9]+/gu, "-").replace(/^-|-$/gu, "").slice(0, 96);
+  return `${slug}-${fnv1a64(canonical)}`;
+}

package/src/step.ts

@@ -8,11 +8,14 @@ export interface Step<T> extends PromiseLike<T> {
    */
   gate(config: NamedGate): Step<T>;
   /**
-   * Predicate gates cannot be journaled — the JavaScript closure would not
-   * survive replay — so the executor refuses this branch with
-   * `unsupported_gate`. Use a `NamedGate` config-object gate above, or the
-   * declarative `verification:` field on the compiled step spec, when you
-   * need journal-honest verification.
+   * Predicate gate: author code, run once by the runtime after the step
+   * completes, on the value the journal handed back. The closure itself is
+   * never serialized; its VERDICT is journaled as a lowered `<step>.gate`
+   * deterministic step that succeeds or fails, so resume and replay read the
+   * recorded verdict and never re-run the function. A false verdict fails the
+   * run as `gate_failed`, carrying `because`. `flows check` cannot prove a
+   * predicate (docs/SURFACE.md §6); use a `NamedGate` when the check must be
+   * inspectable before execution. One `.gate()` per step.
    */
   gate(predicate: (value: T) => boolean, because?: string): Step<T>;
 }
@@ -27,7 +30,20 @@ export type NamedGate =
   | ReferencesInputNamedGate
   | SubprocessNamedGate
   | WordCountBoundsNamedGate
-  | RegexMatchNamedGate;
+  | RegexMatchNamedGate
+  | ArtifactExistsNamedGate;
+
+/**
+ * Passes when the step's journaled `artifacts` lists `path` — a file the
+ * agent's worker measured as created or changed under its working directory.
+ * The check reads the journal, so replay and resume see the verdict that was
+ * recorded, never a fresh look at the disk.
+ */
+export interface ArtifactExistsNamedGate {
+  type: 'artifact_exists';
+  /** Working-directory-relative POSIX path, e.g. `review/security.md`. */
+  path: string;
+}
 
 export interface ReferencesInputNamedGate {
   type: 'references_input';

package/src/triggers/PROVIDERS.md

@@ -0,0 +1,56 @@
+<!-- GENERATED by scripts/generate-triggers.mjs — do not edit. -->
+# Provider trigger namespaces
+
+47 providers, 570 events. `mapping` rows come from the adapter's `webhooks:` block (payload-aware signatures); `catalog` rows come from `KNOWN_TRIGGER_CATALOG` (`supportedEvents()`) only. Every provider also includes its catalog events, so the count is what ingress delivers.
+
+| Provider | Namespace | Events | Source | Registry-only events |
+|---|---|---:|---|---|
+| `airtable` | `airtable` | 9 | catalog |  |
+| `asana` | `asana` | 17 | catalog |  |
+| `azure-blob` | `azure_blob` | 3 | mapping |  |
+| `box` | `box` | 3 | mapping |  |
+| `calendly` | `calendly` | 12 | catalog |  |
+| `clickup` | `clickup` | 12 | catalog |  |
+| `cloudflare` | `cloudflare` | 8 | mapping |  |
+| `confluence` | `confluence` | 6 | catalog |  |
+| `daytona` | `daytona` | 7 | mapping |  |
+| `docker-hub` | `docker_hub` | 1 | catalog |  |
+| `dropbox` | `dropbox` | 1 | mapping |  |
+| `fathom` | `fathom` | 1 | mapping |  |
+| `gcp` | `gcp` | 9 | mapping |  |
+| `gcs` | `gcs` | 3 | mapping |  |
+| `github` | `github` | 26 | mapping |  |
+| `gitlab` | `gitlab` | 53 | mapping |  |
+| `gmail` | `gmail` | 3 | mapping |  |
+| `google-calendar` | `google_calendar` | 3 | catalog |  |
+| `google-drive` | `google_drive` | 3 | mapping |  |
+| `granola` | `granola` | 4 | mapping |  |
+| `hubspot` | `hubspot` | 20 | catalog |  |
+| `intercom` | `intercom` | 18 | catalog |  |
+| `jira` | `jira` | 12 | catalog |  |
+| `linear` | `linear` | 33 | catalog |  |
+| `mailgun` | `mailgun` | 15 | catalog |  |
+| `mixpanel` | `mixpanel` | 12 | catalog |  |
+| `neon` | `neon` | 5 | mapping |  |
+| `notion` | `notion` | 13 | mapping |  |
+| `onedrive` | `onedrive` | 3 | mapping |  |
+| `pipedrive` | `pipedrive` | 14 | catalog |  |
+| `postgres` | `postgres` | 3 | mapping |  |
+| `posthog` | `posthog` | 2 | mapping |  |
+| `ramp` | `ramp` | 47 | mapping |  |
+| `recall` | `recall` | 3 | mapping |  |
+| `redis` | `redis` | 3 | mapping |  |
+| `s3` | `s3` | 3 | mapping |  |
+| `salesforce` | `salesforce` | 22 | catalog |  |
+| `segment` | `segment` | 12 | catalog |  |
+| `sendgrid` | `sendgrid` | 17 | catalog |  |
+| `sharepoint` | `sharepoint` | 3 | mapping |  |
+| `shopify` | `shopify` | 24 | catalog |  |
+| `shortcut` | `shortcut` | 6 | mapping |  |
+| `slack` | `slack` | 21 | mapping | `reaction.added` |
+| `stripe` | `stripe` | 21 | catalog |  |
+| `teams` | `teams` | 20 | catalog |  |
+| `telegram` | `telegram` | 25 | catalog |  |
+| `zendesk` | `zendesk` | 9 | catalog |  |
+
+Registry-only events share an identifier with another event of the same provider; subscribe with `webhook(provider, { provider, type })`.

package/src/triggers/README.md

@@ -9,8 +9,25 @@ export default flow('triage')
   .on(github.pull_request('opened'), async (f, event) => { f.done('success'); });
 ```
 
+Every provider a relayfile adapter can deliver has a namespace — 47 today,
+570 events; see [PROVIDERS.md](PROVIDERS.md) (generated) for the full table.
+Hyphenated providers become identifiers: `azure-blob` → `azure_blob`,
+`google-drive` → `google_drive`; the inbox name and event type keep the
+upstream spelling, so `azure_blob.file_created()` lowers to
+`{ provider: 'azure-blob', type: 'file.created' }`. Namespaces come from two
+sources: an adapter's `webhooks:` mapping block, which carries payload shape
+(`github.pull_request(action?)` takes an action because the mapping extracts
+one), and the trigger catalog (`@relayfile/adapter-core/triggers`, every adapter's
+`supportedEvents()`), which is the full set an adapter delivers and yields the
+plain `(filter?)` signature. The two are unioned per provider: a mapping
+covers payload shape for some events, never the whole set (gitlab maps 8 of
+53). Where two upstream names share an identifier (`reaction.added` and
+`reaction_added`), the mapping-declared one owns the method and the other
+stays subscribable via `webhook(provider, { provider, type })`; PROVIDERS.md
+lists them.
+
 Provider namespaces also export from `@relayflows/surface/triggers` and
-`@relayflows/surface/triggers/slack` (or `/github`). Declarations are immutable
+`@relayflows/surface/triggers/slack` (or `/github`, `/notion`, …). Declarations are immutable
 webhook sources: their executor/inbox name is the provider, and their filter
 matches the provider, event type, and requested payload fields. Register those
 provider names in `flows.json`'s `executors` array for preflight.
@@ -32,9 +49,21 @@ filter names that same provider, and the filter pins an event type.
 `slack.reaction(emoji)` subscribes to `reaction_added`. Arguments match provider
 values exactly: use the channel ID and reaction name from the incoming event.
 `github.pull_request(action)` filters `payload.action`; omitting the action
-accepts every pull request event. Upstream mappings do not declare action enums,
-so the action parameter is a string. Other generated methods accept an optional
-recursive payload filter, for example `github.push({ ref: 'refs/heads/main' })`.
+accepts every pull request event. GitHub (and some other providers) appear in
+two spellings because two ingresses deliver them: the aggregate event with the
+action in the payload (`pull_request` + `payload.action`) is what a raw GitHub
+delivery and this package's `POST /providers/github` receiver carry, while the
+action-qualified name (`pull_request.opened`) is what relayfile's Cloud
+ingress normalizes to and what the adapter catalog lists. Subscribe in the
+spelling of the ingress that will deliver to you; action-qualified methods
+take only a payload filter, never a second action. Upstream mappings do not declare action enums,
+so the action parameter is a string. `github.check_run(action)` (a CI check
+finished: `completed`, with `check_run.conclusion` in the payload) and
+`github.issue_comment(action)` (a comment on an issue or pull-request
+conversation: `created`, `edited`, `deleted`) take an action the same way — the
+two events a PR reviewer needs for merge-on-green and comment-driven directives.
+Other generated methods accept an optional recursive payload filter, for
+example `github.push({ ref: 'refs/heads/main' })`.
 
 The receiver accepts `POST /providers/slack` with this JSON:
 
@@ -72,9 +101,55 @@ Each provider inbox still binds one RunSpec. This extends E's declaration and
 inbox contract; deploying TypeScript handler bodies remains the separate #301
 binding step.
 
+## Schedules
+
+`schedule` is hand-written, not generated: a schedule is not a provider event.
+
+```ts
+import { flow, schedule } from '@relayflows/surface';
+
+export default flow('nightly')
+  .on(schedule.cron('0 9 * * 1-5', { tz: 'Europe/Oslo' }), async (f) => { f.done('success'); })
+  .on(schedule.every('5m'), async (f) => { f.done('success'); });
+```
+
+`schedule.cron` validates a standard five-field expression (values, ranges,
+lists, `/step`, month and weekday names) and an IANA `tz`; `schedule.every`
+takes `<n><s|m|h|d>`, at least one second. Both are inert data. The SDK lowers
+a declaration to the `flows.tick` subscription `testdata/tick-heartbeat.flow.yaml`
+writes by hand — event type `flows.tick`, pattern `schedule_id`, the tick
+dedupe key, and a three-slot silence budget — with a deterministic
+`schedule_id` from the flow name and the declaration (`scheduleIdFor`).
+`flows check` prints each one:
+
+```
+SCHEDULE handler 0 every 300000ms -> flows.tick schedule_id nightly-every-300000ms-33a704f768702f7d [local: flows tick start --schedule-id nightly-every-300000ms-33a704f768702f7d --interval-ms 300000 --epoch-ms 0]
+SCHEDULE handler 1 cron "0 9 * * 1-5" tz Europe/Oslo -> flows.tick schedule_id nightly-cron-0-9-1-5-europe-oslo-41f5a267fd758564 [Cloud only: ...]
+```
+
+The id is a readable slug plus a hash of the exact declaration, so `1-5` and
+`1,5`, two zones, or two long names never share a tick stream (the kernel
+dispatches an event to its first matching subscription only).
+
+Locally the tick runner fires at `epoch + k·interval`, so it drives a cron
+only when that grid reproduces it **exactly**: `every(...)`; `*/N * * * *`
+with `N` dividing 60; `M */N * * *` with `N` dividing 24 (phase `M`
+minutes); `M H * * *` daily (phase `H:M`) — all in UTC. `*/7 * * * *` is not
+a grid (cron restarts the count each hour, a grid drifts), nor is anything
+with day, month or weekday constraints, lists, ranges, or a non-UTC zone.
+Those are reported as Cloud-only rather than approximated; `flows schedule`
+registers them on Cloud's cron-aware runner. Every schedule declares its own
+silence budget — three intervals for a grid, three times the cron's longest
+quiet period otherwise (`cronMaxGapMs`) — so a weekday-morning cron is not
+journaled stale on Monday at 09:05 by the kernel's five-minute default.
+Schedules need no `flows.json` executor entry: the tick source ships with
+the CLI.
+
 Generation requires the SDK's development dependencies. The default input is
-the mapping YAML shipped in the pinned `@relayfile/adapter-core` dependency
-(currently Slack and GitHub). A checkout supplies additional providers:
+the pinned `@relayfile/adapter-core` dependency: its `mappings/` fallbacks,
+its `mappings/adapters/` bundle (every adapter's own mapping, adapter-core
+≥ 0.5.26), and its trigger catalog. A checkout supplies the same three from
+source:
 
 ```sh
 node scripts/generate-triggers.mjs
@@ -83,6 +158,7 @@ node scripts/generate-triggers.mjs --adapters-dir /path/to/relayfile-adapters
 ```
 
 The generator reads `packages/core/mappings/*.mapping.yaml`, then each adapter's
-`packages/<adapter>/*.mapping.yaml`; adapter-local mappings take precedence.
-Only adapters with a nonempty `webhooks:` section produce modules. It never
+`packages/<adapter>/*.mapping.yaml` (adapter-local mappings take precedence),
+then `packages/core/src/triggers/catalog.generated.json` for providers with no
+`webhooks:` block. Only providers with at least one event produce modules. It never
 imports or executes adapter code. Rebuild the surface and SDK after regeneration.