@relayflows/sdk 2.0.16 → 2.0.17

package/src/cloud-http.ts

@@ -12,6 +12,15 @@ export interface CloudConnectionOptions {
   requestTimeoutMs?: number;
 }
 
+/** A refusal Cloud answered as JSON: only these fields are ever read. */
+export interface CloudRefusal {
+  code: string;
+  error: string;
+  /** Version-only descriptions, when a route names what it wanted vs. got. */
+  expected?: { packageName?: string; version?: string };
+  received?: { packageName?: string; version?: string };
+}
+
 export class CloudFlowError extends Error {
   constructor(
     readonly code: 'configuration' | 'unsupported_source' | 'invalid_input' | 'invalid_response' | 'http_error'
@@ -19,6 +28,7 @@ export class CloudFlowError extends Error {
       | 'patch_conflict',
     message: string,
     readonly status?: number,
+    readonly refusal?: CloudRefusal,
   ) {
     super(message);
     this.name = 'CloudFlowError';
@@ -175,10 +185,20 @@ export async function cloudFetch(
   }
   if (!response.ok) {
     // Do not echo server response bodies: they may contain credentials or source.
-    const refusal = init.detail ? await structuredRefusal(response) : undefined;
+    // Reading the body is itself a transport step: a cancellation or timeout
+    // there keeps its own classification instead of becoming an http_error.
+    let refusal: CloudRefusal | undefined;
+    if (init.detail) {
+      try {
+        refusal = await structuredRefusal(response);
+      } catch (error) {
+        options.signal?.throwIfAborted();
+        throw transportError(deadline.aborted ? deadline.reason : error);
+      }
+    }
     throw new CloudFlowError('http_error', refusal === undefined
       ? `Cloud request failed with HTTP ${response.status}.`
-      : `Cloud refused (${refusal.code}): ${refusal.error}`, response.status);
+      : `Cloud refused (${refusal.code}): ${refusal.error}`, response.status, refusal);
   }
   try {
     return await response.json();
@@ -189,12 +209,36 @@ export async function cloudFetch(
   }
 }
 
-async function structuredRefusal(response: Response): Promise<{ code: string; error: string } | undefined> {
+const REFUSAL_CODE = /^[a-z0-9_]{1,64}$/u;
+
+/**
+ * Routes answer either `{ code, error }` or a bare `{ error: "<code>" }`;
+ * both are read, and an optional `expected`/`received` pair is reduced to
+ * package name and version. Nothing else in the body is looked at.
+ */
+async function structuredRefusal(response: Response): Promise<CloudRefusal | undefined> {
   let body: unknown;
-  try { body = await response.json(); } catch { return undefined; }
-  if (!isCloudRecord(body) || typeof body.code !== 'string' || typeof body.error !== 'string') return undefined;
-  if (!/^[a-z0-9_]{1,64}$/u.test(body.code) || body.error.length > 500) return undefined;
-  return { code: body.code, error: body.error };
+  try {
+    body = await response.json();
+  } catch (error) {
+    // Only a body that is not JSON is "no structured refusal"; an aborted or
+    // timed-out read is a transport failure and propagates.
+    if (error instanceof SyntaxError) return undefined;
+    throw error;
+  }
+  if (!isCloudRecord(body) || typeof body.error !== 'string' || body.error.length > 500) return undefined;
+  const code = typeof body.code === 'string' ? body.code : body.error;
+  if (!REFUSAL_CODE.test(code)) return undefined;
+  const versionOnly = (value: unknown): CloudRefusal['expected'] => {
+    if (!isCloudRecord(value)) return undefined;
+    const out: { packageName?: string; version?: string } = {};
+    if (typeof value.packageName === 'string' && value.packageName.length <= 100) out.packageName = value.packageName;
+    if (typeof value.version === 'string' && /^[0-9A-Za-z.+-]{1,64}$/u.test(value.version)) out.version = value.version;
+    return out;
+  };
+  const expected = versionOnly(body.expected);
+  const received = versionOnly(body.received);
+  return { code, error: body.error, ...(expected ? { expected } : {}), ...(received ? { received } : {}) };
 }
 
 // Defensive path-segment constraint; accepting a new server ID format needs an SDK change.

package/src/cloud-run.ts

@@ -1,4 +1,4 @@
-import { RUN_COMPLETION_REASONS } from '@relayflows/surface';
+import { RUN_COMPLETION_REASONS, type ScheduleTriggerSource } from '@relayflows/surface';
 import type { RunCompletionReason } from './protocol.js';
 import { readFile } from 'node:fs/promises';
 import { createHash } from 'node:crypto';
@@ -10,7 +10,7 @@ import type { FlowSpec } from './spec.js';
 import { snapshotJsonValue, type JsonValue } from './json-value.js';
 import { loadAuthoredFlow, type SurfaceModuleAuthority } from './authored-flow-loader.js';
 import {
-  CloudFlowError, cloudConnection, cloudRequest, cloudRunId, isCloudRecord,
+  CloudFlowError, cloudConnection, cloudFetch, cloudRequest, cloudRunId, isCloudRecord,
   type CloudConnectionOptions,
 } from './cloud-http.js';
 import { packWorkingTree, prepareCloudSync, uploadCloudCode } from './cloud-sync.js';
@@ -53,6 +53,17 @@ export interface CloudAuthoredAuthority {
   readonly byteLength: number;
   readonly surface: SurfaceModuleAuthority;
 }
+/** The request-body fields a submission contributes; identical for a run and a schedule. */
+export function cloudSubmissionBody(submission: CloudSubmission): Record<string, unknown> {
+  return {
+    workflow: submission.workflow,
+    fileType: submission.fileType,
+    relayflowVersion: 'v2',
+    ...(submission.authoredAuthority === undefined ? {} : { authoredAuthority: submission.authoredAuthority }),
+    ...(submission.inputPresent ? { inputs: submission.inputs } : {}),
+  };
+}
+
 export type CloudRunState =
   | { runId: string; status: 'pending' | 'launching' | 'running' }
   | { runId: string; status: 'completed' | 'failed' | 'cancelled'; completionReason: RunCompletionReason };
@@ -62,13 +73,31 @@ export type CloudRunState =
  * happens here; Cloud owns provisioning and the Rust engine owns execution.
  * Returns acceptance, not completion. No local daemon, CLI probe, or node up.
  */
-export async function runInCloud(
+/**
+ * What a Cloud submission carries, before any request: the exact source or
+ * canonical spec, the pinned authority for authored source, the input, and a
+ * local correlation hash. Shared by `runInCloud` and `scheduleInCloud`, so a
+ * schedule stores exactly what a run would send.
+ */
+export interface CloudSubmission {
+  readonly workflow: string;
+  readonly fileType: 'yaml' | 'ts';
+  readonly authoredAuthority?: CloudAuthoredAuthority;
+  readonly inputs?: JsonValue;
+  readonly inputPresent: boolean;
+  readonly specHash: string;
+  /** The authored flow's declared name, or the spec name. */
+  readonly name: string;
+  /** Authored `schedule.*` handlers, for `flows schedule` to pick up. */
+  readonly schedules: readonly ScheduleTriggerSource[];
+}
+
+export async function prepareCloudSubmission(
   flow: CloudFlowSource,
-  options: RunInCloudOptions = {},
-): Promise<CloudRunReceipt> {
-  const { baseUrl } = cloudConnection(options);
+  options: { input?: JsonValue; signal?: AbortSignal } = {},
+): Promise<CloudSubmission> {
   let spec: FlowSpec | undefined;
-  let authored: { source: string; authority: CloudAuthoredAuthority } | undefined;
+  let authored: { source: string; authority: CloudAuthoredAuthority; name: string; schedules: ScheduleTriggerSource[] } | undefined;
   const inputPresent = Object.prototype.hasOwnProperty.call(options, 'input');
   let authoredInput: JsonValue | undefined;
   try {
@@ -80,14 +109,27 @@ export async function runInCloud(
         if (!bytes.length || Buffer.from(source, 'utf8').compare(bytes) !== 0) {
           throw new CloudFlowError('invalid_input', 'Authored source must be nonempty, lossless UTF-8.');
         }
-        const loaded = await loadAuthoredFlow(flow.path);
-        loaded.getDefinition(loaded.handle);
+        let loaded: Awaited<ReturnType<typeof loadAuthoredFlow>>;
+        let definition: ReturnType<typeof loaded.getDefinition>;
+        try {
+          loaded = await loadAuthoredFlow(flow.path);
+          definition = loaded.getDefinition(loaded.handle);
+        } catch (error) {
+          // An authored source that does not load is an authoring problem, and
+          // the most common one is `@relayflows/surface` not being resolvable
+          // from the flow's directory. Name it; do not call it a spec problem.
+          throw new CloudFlowError('unsupported_source',
+            `${flow.path} is not a loadable authored flow: ${error instanceof Error ? error.message : String(error)}. `
+            + 'Run `flows check` on it from the same directory.');
+        }
         if (loaded.graph.length !== 1) {
           throw new CloudFlowError('unsupported_source',
             'Cloud authored submission currently accepts one self-contained .flow.ts source without use dependencies.');
         }
         authored = {
           source,
+          name: definition.name,
+          schedules: definition.handlers.flatMap(h => h.trigger.kind === 'schedule' ? [h.trigger] : []),
           authority: Object.freeze({
             schemaVersion: 1,
             sourceSha256: createHash('sha256').update(bytes).digest('hex'),
@@ -130,12 +172,32 @@ export async function runInCloud(
     throw new CloudFlowError('invalid_input', 'Cannot read or compile the declarative flow. Check the file path and YAML/JSON spec.');
   }
   options.signal?.throwIfAborted();
-  const hash = authored === undefined
-    ? specHash(toKernelSpec(spec!))
-    : createHash('sha256').update(canonicalize({
-        authority: authored.authority,
-        input: authoredInput,
-      })).digest('hex');
+  if (authored === undefined) {
+    const kernel = toKernelSpec(spec!);
+    // JSON is a YAML subset. Sending canonical data preserves the exact spec
+    // while using the server's existing YAML-to-config admission path.
+    return { workflow: canonicalize(spec), fileType: 'yaml', inputPresent: false, specHash: specHash(kernel),
+      name: spec!.name ?? "flow", schedules: [] };
+  }
+  return {
+    workflow: authored.source, fileType: 'ts', authoredAuthority: authored.authority,
+    inputs: authoredInput, inputPresent: true, name: authored.name, schedules: authored.schedules,
+    specHash: createHash('sha256').update(canonicalize({ authority: authored.authority, input: authoredInput })).digest('hex'),
+  };
+}
+
+/**
+ * Submit a declarative flow to Cloud's pinned v2 runtime. Compilation only
+ * happens here; Cloud owns provisioning and the Rust engine owns execution.
+ * Returns acceptance, not completion. No local daemon, CLI probe, or node up.
+ */
+export async function runInCloud(
+  flow: CloudFlowSource,
+  options: RunInCloudOptions = {},
+): Promise<CloudRunReceipt> {
+  const { baseUrl } = cloudConnection(options);
+  const submission = await prepareCloudSubmission(flow, options);
+  const hash = submission.specHash;
   // Sync before submission: `prepare` reserves the run ID and the upload lands
   // under it, so the run request below names code Cloud already holds. A
   // refused backend or failed upload therefore never leaves a launched run
@@ -156,17 +218,28 @@ export async function runInCloud(
   }
   options.signal?.throwIfAborted();
   options.onSubmit?.();
-  const result = await cloudRequest('/api/v1/workflows/run', options, {
-    // JSON is a YAML subset. Sending canonical data preserves the exact spec
-    // while using the server's existing YAML-to-config admission path.
-    workflow: authored?.source ?? canonicalize(spec),
-    fileType: authored === undefined ? 'yaml' : 'ts',
-    relayflowVersion: 'v2',
-    ...(authored === undefined ? {} : { authoredAuthority: authored.authority }),
-    ...(authored === undefined ? {} : { inputs: authoredInput }),
-    ...(options.workspaceId === undefined ? {} : { workspaceId: options.workspaceId }),
-    ...(synced === undefined ? {} : { runId: synced.runId, s3CodeKey: synced.codeKey }),
-  });
+  let result: unknown;
+  try {
+    result = await cloudFetch('/api/v1/workflows/run', options, { method: 'POST', detail: true, body: JSON.stringify({
+      ...cloudSubmissionBody(submission),
+      ...(options.workspaceId === undefined ? {} : { workspaceId: options.workspaceId }),
+      ...(synced === undefined ? {} : { runId: synced.runId, s3CodeKey: synced.codeKey }),
+    }) });
+  } catch (error) {
+    // Cloud accepts exactly one authored Surface (the one its sandbox runs).
+    // A CLI on another release is refused with this code; say which side is
+    // which instead of leaving the user with a bare 400 (flows#461).
+    if (error instanceof CloudFlowError && submission.authoredAuthority !== undefined
+      && error.refusal?.code === 'relayflow_v2_authored_authority_invalid') {
+      const expected = error.refusal.expected?.version;
+      throw new CloudFlowError('unsupported_source',
+        `Cloud refused this authored flow's Surface: it runs @relayflows/surface ${expected ?? '(version not reported)'} `
+        + `and this CLI authored against ${submission.authoredAuthority.surface.version}. `
+        + 'Install the matching relayflows release, or deploy the flow with `flows deploy`, which uses Cloud\'s own Surface.',
+        error.status, error.refusal);
+    }
+    throw error;
+  }
   if (!isCloudRecord(result) || (result.status !== 'pending' && result.status !== 'running')) {
     throw new CloudFlowError('invalid_response', 'Cloud did not return an accepted run.');
   }

package/src/cloud-schedule.ts

@@ -0,0 +1,158 @@
+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;
+}
+
+export async function scheduleInCloud(
+  input: ScheduleInCloudInput, options: CloudConnectionOptions = {},
+): Promise<CloudSchedule> {
+  if (input.cron !== undefined && input.every !== undefined) {
+    throw new CloudFlowError('invalid_input', 'Give --cron or --every, not both.');
+  }
+  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,8 @@ 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',
 ] as const;
 
 /**

package/src/index.ts

@@ -67,6 +67,11 @@ 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,
@@ -233,3 +238,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/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))