@relayflows/sdk 2.0.16 → 2.0.18

package/src/cloud-schedule.ts

@@ -0,0 +1,175 @@
+import { cronGrid, everyToMs, parseCron, type ScheduleTriggerSource } from '@relayflows/surface';
+import { CloudFlowError, cloudFetch, cloudRequest, isCloudRecord, type CloudConnectionOptions } from './cloud-http.js';
+import { cloudSubmissionBody, prepareCloudSubmission, type CloudFlowSource } from './cloud-run.js';
+import type { JsonValue } from './json-value.js';
+
+/**
+ * Hosted schedules. `POST /api/v1/workflows/schedules` stores a workflow
+ * request and relaycron fires it on the cron; each fire replays the stored
+ * request through the same `/workflows/run` admission a `flows run --cloud`
+ * takes. So a schedule sends exactly what a run sends — `prepareCloudSubmission`
+ * — wrapped in the schedule envelope. Nothing runs at schedule time.
+ */
+
+export interface ScheduleInCloudInput {
+  flow: CloudFlowSource;
+  /** Five-field cron. Exactly one of `cron` or `every`, or neither to use the flow's declared `schedule.*`. */
+  cron?: string;
+  /** Fixed interval such as `5m`; lowered to a cron the server accepts. */
+  every?: string;
+  /** IANA zone the cron is evaluated in; default UTC. */
+  tz?: string;
+  /** Authored input, as `flows run --cloud --input`. */
+  input?: JsonValue;
+  /** Defaults to the flow's declared name. */
+  name?: string;
+}
+
+export interface CloudSchedule {
+  id: string;
+  name: string;
+  cronExpression: string;
+  timezone: string;
+  status: string;
+  createdAt?: string;
+  lastTriggeredAt?: string;
+  lastTriggeredRunId?: string;
+  lastTriggerStatus?: string;
+}
+
+const SCHEDULE_ID = /^[A-Za-z0-9_-]{1,128}$/u;
+
+/** `every("5m")` as a cron the server accepts; only intervals cron can express exactly. */
+export function everyToCron(every: string): string {
+  const ms = everyToMs(every);
+  const minutes = ms / 60_000;
+  if (Number.isInteger(minutes) && minutes >= 1 && minutes < 60 && 60 % minutes === 0) return `*/${minutes} * * * *`;
+  if (minutes === 60) return '0 * * * *';
+  const hours = ms / 3_600_000;
+  if (Number.isInteger(hours) && hours > 1 && hours < 24 && 24 % hours === 0) return `0 */${hours} * * *`;
+  if (hours === 24) return '0 0 * * *';
+  throw new CloudFlowError('invalid_input',
+    `--every ${every} has no exact cron: use a divisor of an hour (1m-30m), 1h, a divisor of a day (2h-12h), or 1d; or give --cron.`);
+}
+
+/** The cron a declared `schedule.*` source means on Cloud. */
+export function declaredScheduleCron(source: ScheduleTriggerSource): { cron: string; tz?: string } {
+  if (source.cron !== undefined) return { cron: source.cron, ...(source.tz === undefined ? {} : { tz: source.tz }) };
+  const minutes = (source.intervalMs ?? 0) / 60_000;
+  const every = Number.isInteger(minutes) ? `${minutes}m` : `${Math.round((source.intervalMs ?? 0) / 1000)}s`;
+  return { cron: everyToCron(every) };
+}
+
+function assertTimeZone(tz: string): string {
+  try {
+    new Intl.DateTimeFormat('en-US', { timeZone: tz });
+  } catch {
+    throw new CloudFlowError('invalid_input', `--tz ${JSON.stringify(tz)} is not a known IANA zone.`);
+  }
+  return tz;
+}
+
+/**
+ * The argument checks `scheduleInCloud` makes before it reads the flow, so a
+ * caller can refuse a bad cron, interval or zone before any side effect (the
+ * CLI connects integrations in between). Declared-schedule resolution needs
+ * the flow and stays in `scheduleInCloud`.
+ */
+export function validateScheduleArgs(input: Pick<ScheduleInCloudInput, 'cron' | 'every' | 'tz'>): void {
+  if (input.cron !== undefined && input.every !== undefined) {
+    throw new CloudFlowError('invalid_input', 'Give --cron or --every, not both.');
+  }
+  if (input.cron !== undefined) {
+    try { parseCron(input.cron); } catch (error) {
+      throw new CloudFlowError('invalid_input', `--cron: ${error instanceof Error ? error.message : String(error)}`);
+    }
+  }
+  if (input.every !== undefined) everyToCron(input.every);
+  if (input.tz !== undefined) assertTimeZone(input.tz);
+}
+
+export async function scheduleInCloud(
+  input: ScheduleInCloudInput, options: CloudConnectionOptions = {},
+): Promise<CloudSchedule> {
+  validateScheduleArgs(input);
+  const submission = await prepareCloudSubmission(input.flow, {
+    ...(Object.prototype.hasOwnProperty.call(input, 'input') ? { input: input.input } : {}),
+    ...(options.signal === undefined ? {} : { signal: options.signal }),
+  });
+  let cron: string;
+  let tz = input.tz;
+  if (input.cron !== undefined) {
+    try { parseCron(input.cron); } catch (error) {
+      throw new CloudFlowError('invalid_input', `--cron: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    cron = input.cron.trim();
+  } else if (input.every !== undefined) {
+    cron = everyToCron(input.every);
+  } else {
+    if (submission.schedules.length !== 1) {
+      throw new CloudFlowError('invalid_input', submission.schedules.length === 0
+        ? 'The flow declares no schedule.* handler; give --cron or --every.'
+        : 'The flow declares several schedules; say which with --cron or --every.');
+    }
+    const declared = declaredScheduleCron(submission.schedules[0]!);
+    cron = declared.cron;
+    tz ??= declared.tz;
+  }
+  const timezone = tz === undefined ? 'UTC' : assertTimeZone(tz);
+  const name = (input.name ?? submission.name).trim();
+  if (!name) throw new CloudFlowError('invalid_input', 'Schedule name must not be empty.');
+  options.signal?.throwIfAborted();
+  const result = await cloudFetch('/api/v1/workflows/schedules', options, {
+    method: 'POST', detail: true,
+    body: JSON.stringify({
+      name,
+      schedule_type: 'cron',
+      cron_expression: cron,
+      timezone,
+      workflowRequest: cloudSubmissionBody(submission),
+    }),
+  });
+  const record = isCloudRecord(result) && isCloudRecord(result.schedule) ? result.schedule : undefined;
+  if (record === undefined) throw new CloudFlowError('invalid_response', 'Cloud did not return a schedule.');
+  return toCloudSchedule(record);
+}
+
+function toCloudSchedule(row: Record<string, unknown>): CloudSchedule {
+  if (typeof row.id !== 'string' || !SCHEDULE_ID.test(row.id) || typeof row.name !== 'string') {
+    throw new CloudFlowError('invalid_response', 'Cloud returned a malformed schedule.');
+  }
+  const optional = (key: string): Record<string, string> =>
+    typeof row[key] === 'string' ? { [key]: row[key] as string } : {};
+  return {
+    id: row.id, name: row.name,
+    cronExpression: typeof row.cronExpression === 'string' ? row.cronExpression : '',
+    timezone: typeof row.timezone === 'string' ? row.timezone : 'UTC',
+    status: typeof row.status === 'string' ? row.status : 'unknown',
+    ...optional('createdAt'), ...optional('lastTriggeredAt'), ...optional('lastTriggeredRunId'), ...optional('lastTriggerStatus'),
+  };
+}
+
+export async function listCloudSchedules(options: CloudConnectionOptions = {}): Promise<CloudSchedule[]> {
+  const payload = await cloudRequest('/api/v1/workflows/schedules', options);
+  if (!isCloudRecord(payload) || !Array.isArray(payload.schedules)) {
+    throw new CloudFlowError('invalid_response', 'Cloud did not return a schedules list.');
+  }
+  return payload.schedules.map(row => {
+    if (!isCloudRecord(row)) throw new CloudFlowError('invalid_response', 'Cloud returned a malformed schedule row.');
+    return toCloudSchedule(row);
+  });
+}
+
+export async function unscheduleInCloud(scheduleId: string, options: CloudConnectionOptions = {}): Promise<void> {
+  if (!SCHEDULE_ID.test(scheduleId)) throw new CloudFlowError('invalid_input', `"${scheduleId}" is not a schedule id.`);
+  const result = await cloudFetch(`/api/v1/workflows/schedules/${encodeURIComponent(scheduleId)}`, options,
+    { method: 'DELETE', detail: true });
+  if (!isCloudRecord(result) || result.deleted !== true) {
+    throw new CloudFlowError('invalid_response', 'Cloud did not confirm the deletion.');
+  }
+}
+
+/** Exposed for previews: the tick grid a UTC cron amounts to, if it is exactly one. */
+export function cronIntervalMs(cron: string): number | undefined {
+  return cronGrid(parseCron(cron))?.intervalMs;
+}

package/src/failure-kinds.ts

@@ -111,6 +111,10 @@ export const RUN_FAILURE_KINDS = [
   'run_parked',
   'run_declined',
   'run_unavailable',
+  /** A predicate `.gate(fn)` judged false; the verdict is journaled as `<step>.gate`. */
+  'gate_failed',
+  /** `flows answer` named a wait the run is not asking: unknown, or already answered. */
+  'human_wait_unknown',
 ] as const;
 
 /**

package/src/flow-requirements.ts

@@ -0,0 +1,201 @@
+import { helperProviders } from '@relayflows/surface/runtime';
+import type { TriggerSource } from '@relayflows/surface';
+import { providerDeclaration } from './provider-trigger-contract.js';
+import type { FlowSpec } from './spec.js';
+import { helperCall } from './yaml-helpers.js';
+
+/**
+ * What a flow needs from the workspace it deploys into, read from inert
+ * declarations only: the header, the trigger sources, and the text of the
+ * body. Nothing here executes a body or opens a socket, so the same answer is
+ * available to `flows check`, to the hosted verbs before they submit, and to
+ * Cloud's deploy wizard from the source alone.
+ *
+ * Helper use is recognised exactly as `preflightHelpers` recognises it — a
+ * `tools.<namespace>: true` flag or a `f.<namespace>` reference in the body —
+ * so a flow that preflight would refuse for a missing mount is a flow whose
+ * integration this module names. Coding-agent harnesses come from the `cli:`
+ * each `f.agent`/`f.llm` call declares, else the project default, else Cloud's
+ * default (`claude`): the same precedence `resolveCli` applies at run time.
+ */
+
+export const FLOW_HARNESSES = ['claude', 'codex', 'gemini'] as const;
+export type FlowHarness = (typeof FLOW_HARNESSES)[number];
+
+export interface FlowIntegrationRequirement {
+  /** Cloud integration provider id (`slack`, `github`, `linear`, …). */
+  provider: string;
+  /** `tools`: a header declaration; `source`: a trigger or deploy target; `helper`: body use without a flag, or a YAML helper step. */
+  from: 'tools' | 'source' | 'helper';
+  /** The declaration that requires it, as a reader would name it: `tools.slack`, `--on github`, `f.slack`. */
+  detail: string;
+}
+
+export interface FlowHarnessRequirement {
+  harness: FlowHarness;
+  /** `agent "review"`, `llm step`, `step "draft"`, or `default`. */
+  detail: string;
+}
+
+export interface FlowRequirements {
+  integrations: FlowIntegrationRequirement[];
+  harnesses: FlowHarness[];
+  /** One entry per harness, naming the first declaration that needs it. */
+  harnessUses: FlowHarnessRequirement[];
+  /** MCP servers `tools.mcp` names; the workspace must declare each in `flows.json`. */
+  mcp: string[];
+}
+
+export interface FlowRequirementsContext {
+  /** Trigger sources the deployment listens on (`--on`, or the wizard's chosen sources). */
+  sources?: readonly { provider: string }[];
+  /** Set when the deployment targets a repository: every launched run needs GitHub. */
+  repository?: boolean | { owner: string; name: string };
+  /** The nearest `flows.json` `cli`, when one applies. */
+  projectCli?: string;
+}
+
+/** The inert subset of an authored definition this module reads. */
+export interface RequirementsFlowDefinition {
+  readonly header?: { readonly tools?: Readonly<Record<string, unknown>> };
+  readonly body?: Function;
+  readonly handlers?: readonly { readonly trigger: TriggerSource }[];
+}
+
+export function flowRequirements(
+  flow: RequirementsFlowDefinition | FlowSpec,
+  context: FlowRequirementsContext = {},
+): FlowRequirements {
+  const integrations = new Map<string, FlowIntegrationRequirement>();
+  const harnessUses = new Map<FlowHarness, FlowHarnessRequirement>();
+  const mcp = new Set<string>();
+  const declare = (requirement: FlowIntegrationRequirement): void => {
+    if (!integrations.has(requirement.provider)) integrations.set(requirement.provider, requirement);
+  };
+  const need = (harness: FlowHarness | undefined, detail: string): void => {
+    if (harness !== undefined && !harnessUses.has(harness)) harnessUses.set(harness, { harness, detail });
+  };
+  const fallback = harnessFromCli(context.projectCli) ?? 'claude';
+
+  if (isCompiledSpec(flow)) {
+    for (const step of flow.steps) {
+      // Preflight owns shape refusals; a malformed step is simply not a worker step here.
+      if (typeof step !== 'object' || step === null || (step.type !== 'llm' && step.type !== 'agent')) continue;
+      // A YAML helper step (`slack: { post: … }`) compiles to an agent step
+      // carrying a helper envelope: it needs the provider's mount, not a harness.
+      const helper = step.type === 'agent' ? compiledHelper(step) : undefined;
+      if (helper !== undefined) {
+        declare({ provider: helper, from: 'helper', detail: `step "${step.id}"` });
+        continue;
+      }
+      const named = step.type === 'agent' && step.agent !== undefined ? flow.agents?.[step.agent]?.cli : undefined;
+      const cli = step.cli ?? named ?? flow.cli;
+      need(cli === undefined ? fallback : harnessFromCli(cli), `step "${step.id}"`);
+    }
+  } else {
+    const tools = flow.header?.tools ?? {};
+    for (const { provider, namespace } of helperProviders) {
+      if (tools[namespace] === true) declare({ provider, from: 'tools', detail: `tools.${namespace}` });
+    }
+    for (const entry of stringList(tools['relayfile'])) {
+      const provider = entry.split('/')[0]?.trim();
+      if (provider) declare({ provider, from: 'tools', detail: 'tools.relayfile' });
+    }
+    for (const server of stringList(tools['mcp'])) mcp.add(server);
+    for (const handler of flow.handlers ?? []) {
+      const declaration = providerDeclaration(handler.trigger);
+      if (declaration !== undefined) {
+        declare({ provider: declaration.provider, from: 'source', detail: `on ${declaration.provider} ${declaration.type}` });
+      }
+    }
+    // Only the default body is scanned for helper and worker calls: hosted
+    // deployments and schedules dispatch the default body with the trigger's
+    // payload as input, and handler bodies are not dispatched yet (flows #301).
+    // A handler's *trigger* is still a requirement — it is what wakes the flow.
+    const text = typeof flow.body === 'function' ? Function.prototype.toString.call(flow.body) : '';
+    const root = contextParameter(text);
+    if (root !== undefined) {
+      for (const { provider, namespace } of helperProviders) {
+        if (helperReference(root, namespace).test(text)) declare({ provider, from: 'helper', detail: `f.${namespace}` });
+      }
+      for (const use of workerCalls(root, text)) need(use.cli === undefined ? fallback : harnessFromCli(use.cli), use.detail);
+    }
+  }
+
+  for (const source of context.sources ?? []) {
+    declare({ provider: source.provider, from: 'source', detail: `--on ${source.provider}` });
+  }
+  if (context.repository) declare({ provider: 'github', from: 'source', detail: 'deploy target' });
+
+  const uses = [...harnessUses.values()];
+  return {
+    integrations: [...integrations.values()],
+    harnesses: uses.map(use => use.harness),
+    harnessUses: uses,
+    mcp: [...mcp],
+  };
+}
+
+/** `slack (tools.slack), github (deploy target), claude (agent "review")` — the `REQUIRES` line's body. */
+export function describeFlowRequirements(requirements: FlowRequirements): string {
+  return [
+    ...requirements.integrations.map(integration => `${integration.provider} (${integration.detail})`),
+    ...requirements.harnessUses.map(use => `${use.harness} (${use.detail})`),
+    ...requirements.mcp.map(server => `mcp ${server} (tools.mcp)`),
+  ].join(', ');
+}
+
+/** `claude`, `/opt/bin/codex`, `gemini.exe` → the Cloud harness; anything else is not one. */
+export function harnessFromCli(cli: string | undefined): FlowHarness | undefined {
+  if (cli === undefined) return undefined;
+  const base = cli.trim().split(/[\\/]/u).pop()?.replace(/\.(?:exe|cmd|bat)$/iu, '').toLowerCase();
+  return (FLOW_HARNESSES as readonly string[]).includes(base ?? '') ? base as FlowHarness : undefined;
+}
+
+/** The provider of a compiled YAML helper step, or undefined for an ordinary agent step or a malformed envelope. */
+function compiledHelper(step: Parameters<typeof helperCall>[0]): string | undefined {
+  try {
+    return helperCall(step)?.provider;
+  } catch {
+    return undefined;
+  }
+}
+
+function isCompiledSpec(flow: RequirementsFlowDefinition | FlowSpec): flow is FlowSpec {
+  return Array.isArray((flow as FlowSpec).steps) && typeof (flow as FlowSpec).version === 'string';
+}
+
+function stringList(value: unknown): string[] {
+  return Array.isArray(value) ? value.filter((entry): entry is string => typeof entry === 'string') : [];
+}
+
+/** The body's first parameter (`f` in `async (f, input) => …`), escaped for a pattern. */
+function contextParameter(body: string): string | undefined {
+  const parameter = body.match(/^(?:async\s+)?(?:function(?:\s+[\w$]+)?\s*)?(?:\(\s*([\w$]+)|([\w$]+)\s*=>)/u);
+  return (parameter?.[1] ?? parameter?.[2])?.replace(/[.*+?^${}()|[\]\\]/gu, '\\$&');
+}
+
+/** Same recognition as `preflightHelpers`: `f.slack`, `f .slack`, `f["slack"]`. */
+function helperReference(root: string, namespace: string): RegExp {
+  return new RegExp(`(?:^|[^\\w$.])${root}\\s*(?:\\.\\s*${namespace}\\b|\\[\\s*['"]${namespace}['"]\\s*\\])`, 'u');
+}
+
+interface WorkerCall { detail: string; cli?: string }
+
+/**
+ * Each `f.agent(name, { cli })` / `f.llm(prompt, { cli })` call and the CLI it
+ * declares. The options object is read only up to the next worker call, so a
+ * `cli:` belongs to the call it follows; a call without one takes the default.
+ */
+function workerCalls(root: string, body: string): WorkerCall[] {
+  const call = new RegExp(`(?:^|[^\\w$.])${root}\\s*\\.\\s*(agent|llm)\\s*\\(\\s*(?:(['"\`])([^'"\`]*)\\2)?`, 'gu');
+  const starts = [...body.matchAll(call)];
+  return starts.map((match, index) => {
+    const slice = body.slice(match.index! + match[0].length, starts[index + 1]?.index ?? body.length);
+    const cli = slice.match(/(?:^|[^\w$])cli\s*:\s*(['"`])([^'"`]*)\1/u)?.[2];
+    const detail = match[1] === 'agent'
+      ? (match[3] ? `agent ${JSON.stringify(match[3])}` : 'agent step')
+      : 'llm step';
+    return { detail, ...(cli === undefined ? {} : { cli }) };
+  });
+}

package/src/index.ts

@@ -67,10 +67,23 @@ export {
   downloadCloudPatch, applyCloudPatch, packWorkingTree, patchedPaths, MAX_SYNC_BYTES,
   type CloudPatch, type PackedTree,
 } from './cloud-sync.js';
+export {
+  scheduleInCloud, listCloudSchedules, unscheduleInCloud, everyToCron, declaredScheduleCron,
+  type ScheduleInCloudInput, type CloudSchedule,
+} from './cloud-schedule.js';
+export { prepareCloudSubmission, cloudSubmissionBody, type CloudSubmission } from './cloud-run.js';
 export {
   deployToCloud, listCloudDeployments, undeployFromCloud, parseRepository, parseTriggerSource, FLOW_TRIGGER_PROVIDERS,
   type DeployToCloudInput, type CloudDeployment, type CloudDeploymentSummary, type FlowTriggerSource, type FlowTriggerProvider,
 } from './cloud-deploy.js';
+export {
+  ensureIntegrationsConnected, integrationConnected, providerLabel,
+  type ConnectPrompt, type EnsureConnectionsOptions, type ConnectionsOutcome,
+} from './cloud-connect.js';
+export {
+  flowRequirements, describeFlowRequirements, harnessFromCli, FLOW_HARNESSES,
+  type FlowRequirements, type FlowRequirementsContext, type FlowIntegrationRequirement, type FlowHarnessRequirement, type FlowHarness,
+} from './flow-requirements.js';
 
 export { canonicalize, specHash } from './canonical.js';
 export {
@@ -233,3 +246,4 @@ export { createFlow, type CreateFlowOptions, type CreatedFlow } from './create-f
 
 export { renderProgress, type ProgressEvent } from './progress.js';
 export { webhookTriggerSpec } from './trigger-executor.js';
+export { scheduleTriggerSpec, scheduleLowering, SCHEDULE_EXECUTOR, type ScheduleLowering } from './schedule-trigger.js';

package/src/journal-client.ts

@@ -386,6 +386,26 @@ export class JournalClient extends EventEmitter {
   }
 
   /** Satisfy `wait.event`; a human response arrives here too. */
+  /**
+   * Park the dispatched attempt this connection holds on a human question.
+   * Releases the lease; the caller must not heartbeat or complete afterwards.
+   */
+  stepWait(
+    runId: string,
+    stepId: string,
+    attempt: number,
+    idempotencyKey: string,
+    wait: { wait_id: string; prompt: string; requested_of: string; options?: string[]; timeout_at_ms?: number },
+  ): Promise<VerbContract['step.wait']['result']> {
+    return this.request('step.wait', {
+      run_id: runId,
+      step_id: stepId,
+      attempt,
+      idempotency_key: idempotencyKey,
+      ...wait,
+    });
+  }
+
   eventEmit(runId: string, eventKey: string, payload: unknown): Promise<VerbContract['event.emit']['result']> {
     return this.request('event.emit', { run_id: runId, event_key: eventKey, payload });
   }

package/src/named-gate-lowering.ts

@@ -60,6 +60,15 @@ export function lowerNamedGates(steps: readonly StepSpec[]): StepSpec[] {
 }
 
 function gateCommand(gate: NamedDataGate, deterministic: boolean): string {
+  if (gate.type === 'artifact_exists') {
+    // The whole output envelope is bound; the verdict is whether the worker's
+    // journaled `artifacts` list names the path. Nothing on disk is consulted,
+    // so the journal alone reproduces the verdict on replay and resume.
+    return `node -e ${quote(`const input=JSON.parse(process.env.FLOWS_INPUT);
+const output=input.output;
+const artifacts=output!==null&&typeof output==='object'&&Array.isArray(output.artifacts)?output.artifacts:[];
+process.exit(artifacts.includes(${JSON.stringify(gate.path)})?0:1);`)}`;
+  }
   const path = gate.type === 'subprocess_gate' ? gate.from_output
     : gate.type === 'word_count_bounds' ? undefined : gate.in_output_at;
   // Only compiler-owned code is serialized. Author strings are JSON literals;

package/src/named-gates.ts

@@ -2,7 +2,7 @@ import { RE2JS } from 're2js';
 import type { NamedDataGate, VerificationSpec } from './spec.js';
 
 export const NAMED_GATE_FAILURE_KINDS = [
-  'unknown_gate_kind', 'gate_pattern_invalid', 'gate_command_missing', 'gate_bound_invalid',
+  'unknown_gate_kind', 'gate_pattern_invalid', 'gate_command_missing', 'gate_bound_invalid', 'gate_path_invalid',
 ] as const;
 export type NamedGateFailureKind = typeof NAMED_GATE_FAILURE_KINDS[number];
 
@@ -11,6 +11,7 @@ export const NAMED_GATE_KEYS: Record<NamedDataGate['type'], readonly string[]> =
   subprocess_gate: ['type', 'command', 'from_output'],
   word_count_bounds: ['type', 'min', 'max'],
   regex_match: ['type', 'pattern', 'in_output_at', 'flags'],
+  artifact_exists: ['type', 'path'],
 };
 
 export function isNamedGate(gate: VerificationSpec | undefined): gate is NamedDataGate {
@@ -45,6 +46,15 @@ export function namedGateErrors(gate: Record<string, unknown>, input: unknown, a
         errors.push(`${at}.command: gate_command_missing: expected a non-empty shell command`);
       }
       break;
+    case 'artifact_exists': {
+      const path = gate.path;
+      const segments = typeof path === 'string' ? path.split('/') : [];
+      if (typeof path !== 'string' || !path.trim() || path.includes('\0') || path.startsWith('/')
+        || path !== path.trim() || segments.some(segment => segment === '' || segment === '.' || segment === '..')) {
+        errors.push(`${at}.path: gate_path_invalid: expected a relative POSIX path without empty, "." or ".." segments`);
+      }
+      break;
+    }
     case 'word_count_bounds': {
       const { min, max } = gate;
       if ([min, max].some(n => n !== undefined && (!Number.isSafeInteger(n) || (n as number) < 0))