@provos/ironcurtain 0.11.0 → 0.12.0

package/dist/workflow/types.d.ts

@@ -45,6 +45,8 @@ export declare function resolveWorkflowSkillsOptions(skills: readonly string[] |
  * See `docs/designs/workflow-session-identity.md` §2.4 / §6.
  */
 export declare const DEFAULT_CONTAINER_SCOPE = "primary";
+/** Reserved deterministic result verdict emitted when a declared result file cannot be read or parsed. */
+export declare const DETERMINISTIC_RESULT_ERROR_VERDICT = "result_file_error";
 /**
  * Unique identifier for a workflow instance. Branded to prevent accidental
  * mixing with other string identifiers.
@@ -57,6 +59,13 @@ export declare function createWorkflowId(): WorkflowId;
 export interface WorkflowDefinition {
     readonly name: string;
     readonly description: string;
+    /**
+     * When true, the workflow is omitted from the web UI — both the start
+     * picker and the active/past-run tables. The CLI `workflow list` still
+     * shows it. Use for smoke-test / fixture workflows that should remain
+     * runnable from the CLI without cluttering the UI. Default: false.
+     */
+    readonly hidden?: boolean;
     readonly initial: string;
     readonly states: Record<string, WorkflowStateDefinition>;
     readonly settings?: WorkflowSettings;
@@ -70,8 +79,8 @@ export interface WorkflowSettings {
     readonly maxRounds?: number;
     /** Git repository path for worktree management. */
     readonly gitRepoPath?: string;
-    /** Max parallel agent sessions. Default: 3. */
-    readonly maxParallelism?: number;
+    /** Number of synchronous evolve workers. Default: 1. */
+    readonly workers?: number;
     /**
      * Optional system prompt text appended to the base system prompt
      * for ALL agent states in this workflow. Use for workspace
@@ -107,11 +116,40 @@ export interface WorkflowSettings {
      * Ignored for builtin workflows (no Docker infrastructure to share).
      */
     readonly sharedContainer?: boolean;
+    /**
+     * When true, aborted shared-container workflow stops snapshot each live
+     * container's writable layer so resume can recreate the scope from the
+     * recorded immutable image digest. Default: false.
+     */
+    readonly snapshotOnStop?: boolean;
 }
 /**
  * State definition. Discriminated on `type`.
  */
 export type WorkflowStateDefinition = AgentStateDefinition | HumanGateStateDefinition | DeterministicStateDefinition | TerminalStateDefinition;
+export interface FanOutDefinition {
+    /**
+     * Lane multiplicity. `'workers'` defers to `settings.workers`; the
+     * `number` branch is a per-state override for workflows that want a
+     * fixed-width segment independent of the global worker count.
+     */
+    readonly count: 'workers' | number;
+    /**
+     * Join discipline. Only barrier joins are supported today (every lane
+     * must complete before the segment exits); async joins are a future,
+     * deliberately reviewed extension.
+     */
+    readonly join: 'barrier';
+}
+export interface LaneResourceRequest {
+    readonly cpu?: number;
+    readonly mem?: string;
+    readonly gpu?: number;
+}
+export interface StateScheduleDefinition {
+    readonly pool: 'eval' | 'agent';
+    readonly resources?: LaneResourceRequest;
+}
 export interface AgentStateDefinition {
     readonly type: 'agent';
     readonly description: string;
@@ -133,8 +171,25 @@ export interface AgentStateDefinition {
     readonly outputs: readonly string[];
     /** Transitions evaluated in order; first match wins. */
     readonly transitions: readonly AgentTransitionDefinition[];
-    /** When true, each parallel instance gets a dedicated git worktree. */
+    /**
+     * Legacy field from the old per-instance parallel model (one git
+     * worktree per parallel instance). Unused on the `workers`/lane path —
+     * native fan-out lanes are scheduled by the pump, not by per-state
+     * worktree opt-in. Retained for backward compatibility with existing
+     * manifests; do not wire new behavior to it.
+     */
     readonly worktree?: boolean;
+    /**
+     * Marks this state as a member of a parent fan-out segment. Parent fan-out
+     * states factor these members into child round machines at runtime.
+     */
+    readonly fanOutMember?: boolean;
+    /** Fan-out topology metadata for a parent segment driver state. */
+    readonly fanOut?: FanOutDefinition;
+    /** Ordered fan-out segment member state IDs. */
+    readonly segment?: readonly string[];
+    /** Scheduling metadata for lane-local execution. Schema-only until Phase 8. */
+    readonly schedule?: StateScheduleDefinition;
     /**
      * When false, re-invocations of this state resume the previous agent
      * session via --continue, receiving an abbreviated re-visit prompt.
@@ -217,6 +272,34 @@ export interface DeterministicStateDefinition {
      * Never a shell string -- per CLAUDE.md safe coding rules.
      */
     readonly run: readonly (readonly string[])[];
+    /**
+     * When true, execute the command arrays inside the workflow's shared
+     * Docker container via docker exec instead of on the host.
+     */
+    readonly container?: boolean;
+    /**
+     * Shared-container scope to exec into when `container` is true. Defaults
+     * to DEFAULT_CONTAINER_SCOPE.
+     */
+    readonly containerScope?: string;
+    /**
+     * Per-command timeout in milliseconds for deterministic execution.
+     * Undefined uses the runner default.
+     */
+    readonly timeoutMs?: number;
+    /**
+     * Workspace-relative JSON result file written by a containerized helper.
+     * Container-only; see validate.ts for path and routing constraints.
+     */
+    readonly resultFile?: string;
+    /** Fan-out topology metadata for a parent segment driver state. */
+    readonly fanOut?: FanOutDefinition;
+    /** Ordered fan-out segment member state IDs. */
+    readonly segment?: readonly string[];
+    /** Marks this state as a member of a parent fan-out segment. */
+    readonly fanOutMember?: boolean;
+    /** Scheduling metadata for lane-local execution. Schema-only until Phase 8. */
+    readonly schedule?: StateScheduleDefinition;
     readonly transitions: readonly AgentTransitionDefinition[];
 }
 export interface TerminalStateDefinition {
@@ -341,31 +424,38 @@ export type WorkflowEvent = {
     readonly prompt?: string;
 } | {
     readonly type: 'HUMAN_ABORT';
-} | {
-    readonly type: 'PARALLEL_ALL_COMPLETED';
-    readonly results: readonly ParallelSlotResult[];
-} | {
-    readonly type: 'PARALLEL_SLOT_FAILED';
-    readonly key: string;
-    readonly error: string;
-} | {
-    readonly type: 'MERGE_SUCCEEDED';
-} | {
-    readonly type: 'MERGE_CONFLICT';
-    readonly conflictDetails: string;
 };
+export interface WorkflowLanePreparedResult {
+    readonly passed: boolean;
+    readonly testCount?: number;
+    readonly errors?: string;
+    readonly verdict?: string;
+    readonly payload?: Record<string, unknown>;
+}
+export interface WorkflowLaneContext {
+    readonly id: number;
+    /** Container-absolute lane scratch directory, e.g. /workspace/.evolve_runs/main/current/lane_0. */
+    readonly dir: string;
+    /** Workspace-relative lane scratch directory, e.g. .evolve_runs/main/current/lane_0. */
+    readonly relativeDir: string;
+    /** Deterministic results prepared by the fan-out barrier before the child actor starts. */
+    readonly preparedResults?: Readonly<Record<string, WorkflowLanePreparedResult>>;
+}
 export interface WorkflowContext {
     readonly taskDescription: string;
+    readonly lane?: WorkflowLaneContext;
     readonly artifacts: Record<string, string>;
     readonly round: number;
     readonly maxRounds: number;
     /** Per-role output hash for stall detection. */
     readonly previousOutputHashes: Record<string, string>;
     readonly previousTestCount: number | null;
+    readonly lastDeterministicResult?: {
+        readonly verdict?: string;
+        readonly payload?: Record<string, unknown>;
+    };
     readonly humanPrompt: string | null;
     readonly reviewHistory: readonly string[];
-    readonly parallelResults: Record<string, ParallelSlotResult>;
-    readonly worktreeBranches: readonly string[];
     readonly totalTokens: number;
     readonly lastError: string | null;
     /**
@@ -427,12 +517,6 @@ export interface AgentSlot {
 export interface WorkflowResult {
     readonly finalArtifacts: Record<string, string>;
 }
-export interface ParallelSlotResult {
-    readonly key: string;
-    readonly status: 'success' | 'failed';
-    readonly error?: string;
-    readonly worktreeBranch?: string;
-}
 export interface HumanGateRequest {
     readonly gateId: string;
     readonly workflowId: string;
@@ -480,6 +564,18 @@ export interface WorkflowCheckpoint {
      * from `definitionPath`'s package dir).
      */
     readonly workflowSkillsDir?: string;
+    /**
+     * Per-run staged copy of the workflow package's `scripts/` tree (when
+     * the package shipped one). Mounted read-only at /workflow-scripts for
+     * shared-container deterministic states.
+     */
+    readonly workflowScriptsDir?: string;
+    /**
+     * Per-containerScope Docker image snapshots captured at an aborted stop.
+     * `image` is the immutable sha256 image id and is the source of truth;
+     * `tag` is cosmetic only.
+     */
+    readonly containerSnapshots?: Readonly<Record<string, ContainerSnapshotRef>>;
     /**
      * Terminal-phase status, populated only when the workflow has reached a terminal
      * phase (completed / aborted / failed / waiting_human). Absent for mid-run
@@ -487,6 +583,10 @@ export interface WorkflowCheckpoint {
      */
     readonly finalStatus?: WorkflowStatus;
 }
+export interface ContainerSnapshotRef {
+    readonly image: string;
+    readonly tag?: string;
+}
 export interface TransitionRecord {
     readonly from: string;
     readonly to: string;

package/dist/workflow/types.js

@@ -53,6 +53,8 @@ export function resolveWorkflowSkillsOptions(skills, skillsDir) {
  * See `docs/designs/workflow-session-identity.md` §2.4 / §6.
  */
 export const DEFAULT_CONTAINER_SCOPE = 'primary';
+/** Reserved deterministic result verdict emitted when a declared result file cannot be read or parsed. */
+export const DETERMINISTIC_RESULT_ERROR_VERDICT = 'result_file_error';
 /** Creates a new unique WorkflowId. */
 export function createWorkflowId() {
     return randomUUID();

package/dist/workflow/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/workflow/types.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAGzC,8EAA8E;AAC9E,YAAY;AACZ,8EAA8E;AAE9E;;;GAGG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG,WAAW,CAAC;AAEjD;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,QAAQ,CAAC;AAEvC;;;;GAIG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,MAAM,CAAC;AAElC;;;;;;;GAOG;AACH,MAAM,UAAU,4BAA4B,CAC1C,MAA0D,EAC1D,SAA6B;IAM7B,IAAI,MAAM,KAAK,WAAW;QAAE,OAAO,EAAE,gBAAgB,EAAE,IAAI,EAAE,CAAC;IAC9D,MAAM,MAAM,GAA8D,EAAE,CAAC;IAC7E,IAAI,SAAS,KAAK,SAAS;QAAE,MAAM,CAAC,SAAS,GAAG,SAAS,CAAC;IAC1D,IAAI,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC;QAAE,MAAM,CAAC,WAAW,GAAG,IAAI,GAAG,CAAC,MAAM,CAAC,CAAC;IAChE,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAAG,SAAS,CAAC;AAYjD,uCAAuC;AACvC,MAAM,UAAU,gBAAgB;IAC9B,OAAO,UAAU,EAAgB,CAAC;AACpC,CAAC;AAoQD,8EAA8E;AAC9E,eAAe;AACf,8EAA8E;AAE9E,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC,MAAM,EAAE,QAAQ,EAAE,KAAK,CAAU,CAAC;AAgCpE,yEAAyE;AACzE,MAAM,CAAC,MAAM,mBAAmB,GAAG;IACjC,WAAW;IACX,SAAS;IACT,YAAY;IACZ,YAAY;IACZ,WAAW;IACX,OAAO;CAC0C,CAAC;AA+HpD,MAAM,UAAU,qBAAqB,CAAC,IAAsB;IAC1D,OAAO;QACL,MAAM,EAAE,IAAI,CAAC,MAAM;QACnB,UAAU,EAAE,IAAI,CAAC,UAAU;QAC3B,SAAS,EAAE,IAAI,CAAC,SAAS;QACzB,cAAc,EAAE,IAAI,CAAC,cAAc;QACnC,kBAAkB,EAAE,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,kBAAkB,CAAC,IAAI,EAAE,CAAC;QAC9D,OAAO,EAAE,IAAI,CAAC,OAAO;KACtB,CAAC;AACJ,CAAC"}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/workflow/types.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAGzC,8EAA8E;AAC9E,YAAY;AACZ,8EAA8E;AAE9E;;;GAGG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG,WAAW,CAAC;AAEjD;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,QAAQ,CAAC;AAEvC;;;;GAIG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,MAAM,CAAC;AAElC;;;;;;;GAOG;AACH,MAAM,UAAU,4BAA4B,CAC1C,MAA0D,EAC1D,SAA6B;IAM7B,IAAI,MAAM,KAAK,WAAW;QAAE,OAAO,EAAE,gBAAgB,EAAE,IAAI,EAAE,CAAC;IAC9D,MAAM,MAAM,GAA8D,EAAE,CAAC;IAC7E,IAAI,SAAS,KAAK,SAAS;QAAE,MAAM,CAAC,SAAS,GAAG,SAAS,CAAC;IAC1D,IAAI,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC;QAAE,MAAM,CAAC,WAAW,GAAG,IAAI,GAAG,CAAC,MAAM,CAAC,CAAC;IAChE,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAAG,SAAS,CAAC;AAEjD,0GAA0G;AAC1G,MAAM,CAAC,MAAM,kCAAkC,GAAG,mBAAmB,CAAC;AAYtE,uCAAuC;AACvC,MAAM,UAAU,gBAAgB;IAC9B,OAAO,UAAU,EAAgB,CAAC;AACpC,CAAC;AAwVD,8EAA8E;AAC9E,eAAe;AACf,8EAA8E;AAE9E,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC,MAAM,EAAE,QAAQ,EAAE,KAAK,CAAU,CAAC;AAgCpE,yEAAyE;AACzE,MAAM,CAAC,MAAM,mBAAmB,GAAG;IACjC,WAAW;IACX,SAAS;IACT,YAAY;IACZ,YAAY;IACZ,WAAW;IACX,OAAO;CAC0C,CAAC;AAyIpD,MAAM,UAAU,qBAAqB,CAAC,IAAsB;IAC1D,OAAO;QACL,MAAM,EAAE,IAAI,CAAC,MAAM;QACnB,UAAU,EAAE,IAAI,CAAC,UAAU;QAC3B,SAAS,EAAE,IAAI,CAAC,SAAS;QACzB,cAAc,EAAE,IAAI,CAAC,cAAc;QACnC,kBAAkB,EAAE,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,kBAAkB,CAAC,IAAI,EAAE,CAAC;QAC9D,OAAO,EAAE,IAAI,CAAC,OAAO;KACtB,CAAC;AACJ,CAAC"}

package/dist/workflow/validate.d.ts

@@ -1,8 +1,29 @@
-import type { WorkflowDefinition, WorkflowStateDefinition } from './types.js';
+import type { WorkflowDefinition, WorkflowStateDefinition, AgentTransitionDefinition } from './types.js';
 export declare class WorkflowValidationError extends Error {
     readonly issues: readonly string[];
     constructor(issues: readonly string[]);
 }
+/**
+ * The two state types that run an ordered `transitions` list with
+ * agent-style `guard`/`when` routing (agent + deterministic). Human-gate
+ * transitions use a different (event-keyed) shape, so they are excluded.
+ */
+export type ExecutableState = Extract<WorkflowStateDefinition, {
+    readonly type: 'agent' | 'deterministic';
+}>;
+/**
+ * True for {@link ExecutableState}s. Narrows the union so call sites can
+ * read `state.transitions` / `state.segment` without re-spelling the
+ * `Extract<...>` longhand.
+ */
+export declare function isExecutableState(state: WorkflowStateDefinition): state is ExecutableState;
+export declare function collectTransitionTargets(state: WorkflowStateDefinition): string[];
+/**
+ * True if any transition routes on a `when: { verdict: ... }` clause. Shared by
+ * the container-only validation rule (`validateContainerScopes`) and the WF012
+ * lint (which requires such states to declare a `resultFile`).
+ */
+export declare function usesVerdictEdges(transitions: readonly AgentTransitionDefinition[]): boolean;
 /**
  * Parses a workflow input artifact reference. A trailing `?` marks the
  * input as optional — the consumer may skip it if the artifact isn't
@@ -14,6 +35,7 @@ export declare function parseArtifactRef(ref: string): {
 };
 export declare function collectOutputArtifacts(states: Record<string, WorkflowStateDefinition>): Set<string>;
 export declare function findReachableStates(initial: string, states: Record<string, WorkflowStateDefinition>): Set<string>;
+export declare function isSafeWorkspaceRelativePath(path: string): boolean;
 /**
  * One issue produced by {@link iterateSkillRefIssues}. Surface code
  * (validate vs lint) formats the user-facing wording.