@hunterzhu/pulse-runtime 0.1.0

package/dist/core/types.js

@@ -0,0 +1,109 @@
+export function provenanceRefId(ref) { return typeof ref === 'string' ? ref : ref.ref; }
+export function provenanceRefKind(ref) { return typeof ref === 'string' ? 'legacy' : ref.kind; }
+/**
+ * Park a cancel proposal without dropping a wait/control_error that already occupies
+ * `pendingResumeInput`. The parked proposals are promoted the next time the slot is free.
+ */
+const MAX_CONTROL_PROPOSALS = 32;
+function appendControlProposals(existing, extra) {
+    if ((existing?.length ?? 0) >= MAX_CONTROL_PROPOSALS)
+        return existing ?? [];
+    return [...(existing ?? []), ...extra].slice(0, MAX_CONTROL_PROPOSALS);
+}
+export function enqueueControlProposal(lane, proposal) {
+    if (lane.pendingResumeInput === undefined || lane.pendingResumeInput.type === 'control_proposal') {
+        const existing = lane.pendingResumeInput?.type === 'control_proposal' ? lane.pendingResumeInput.proposals : [];
+        lane.pendingResumeInput = { type: 'control_proposal', proposals: appendControlProposals(existing, [proposal]) };
+        return;
+    }
+    lane.pendingControlProposals = appendControlProposals(lane.pendingControlProposals, [proposal]);
+}
+/** Replace the resume slot. Existing control_proposal inputs are parked, then promoted if the slot ends up empty. */
+export function replaceResumeInput(lane, input) {
+    if (lane.pendingResumeInput?.type === 'control_proposal' && input?.type !== 'control_proposal') {
+        lane.pendingControlProposals = appendControlProposals(lane.pendingControlProposals, lane.pendingResumeInput.proposals);
+    }
+    if (input === undefined)
+        delete lane.pendingResumeInput;
+    else
+        lane.pendingResumeInput = input;
+    if (lane.pendingResumeInput === undefined && (lane.pendingControlProposals?.length ?? 0) > 0) {
+        lane.pendingResumeInput = { type: 'control_proposal', proposals: lane.pendingControlProposals };
+        delete lane.pendingControlProposals;
+    }
+}
+export function globalContextRef(agentId, version) { return `global:${agentId}:${version}`; }
+export function laneContextRef(laneId, version) { return `lane:${laneId}:${version}`; }
+export function parseContextSnapshotRef(ref) {
+    const parts = ref.split(':');
+    if (parts[0] === 'global' && parts.length === 3 && parts[1] !== undefined && parts[2] !== undefined && /^\d+$/.test(parts[2]))
+        return { kind: 'global', agentId: parts[1], version: Number(parts[2]) };
+    if (parts[0] === 'global' && parts.length === 2 && parts[1] !== undefined && /^\d+$/.test(parts[1]))
+        return { kind: 'global', version: Number(parts[1]) };
+    if (parts[0] === 'lane' && parts.length === 3 && parts[1] !== undefined && parts[2] !== undefined && /^\d+$/.test(parts[2]))
+        return { kind: 'lane', laneId: parts[1], version: Number(parts[2]) };
+    return undefined;
+}
+export function privacyForContextSnapshot(state, lane, ref) {
+    const parsed = parseContextSnapshotRef(ref);
+    if (!parsed)
+        return undefined;
+    if (parsed.kind === 'global') {
+        const agent = state.agents.get(lane.agentId);
+        if (!agent || (parsed.agentId !== undefined && parsed.agentId !== agent.id) || !agent.globalVersions.has(parsed.version))
+            return undefined;
+        return structuredClone(agent.globalPrivacy?.get(parsed.version) ?? { privacy: 'public' });
+    }
+    if (parsed.laneId !== lane.id || parsed.version !== lane.context.version)
+        return undefined;
+    return { privacy: lane.context.privacy ?? 'public', ...(lane.context.privacyTaints === undefined ? {} : { privacyTaints: structuredClone(lane.context.privacyTaints) }) };
+}
+export function privacyMetadataForDerivedRef(state, lane, ref) {
+    const id = provenanceRefId(ref);
+    const kind = provenanceRefKind(ref);
+    const result = kind === 'artifact' ? undefined : state.results.get(id);
+    if (result)
+        return { privacy: result.privacy, ...(result.privacyTaints === undefined ? {} : { privacyTaints: structuredClone(result.privacyTaints) }) };
+    const artifact = kind === 'result' ? undefined : state.artifacts.get(id);
+    if (artifact && (artifact.agentId === undefined || artifact.agentId === lane.agentId))
+        return { privacy: artifact.privacy, ...(artifact.privacyTaints === undefined ? {} : { privacyTaints: structuredClone(artifact.privacyTaints) }) };
+    return typeof ref === 'string' ? privacyForContextSnapshot(state, lane, ref) : undefined;
+}
+export function privacyTaintsForDerivedRefs(state, lane, refs) {
+    const output = [];
+    const seen = new Set();
+    for (const ref of refs)
+        for (const taint of privacyMetadataForDerivedRef(state, lane, ref)?.privacyTaints ?? []) {
+            const value = { path: [provenanceRefId(ref), ...taint.path], privacy: taint.privacy };
+            const key = JSON.stringify(value);
+            if (!seen.has(key)) {
+                seen.add(key);
+                output.push(value);
+            }
+        }
+    return output;
+}
+export function createRuntimeState(maxTotalLanes = 64, options = {}) {
+    return { now: 0, agents: new Map(), lanes: new Map(), effects: new Map(), waits: new Map(), results: new Map(), artifacts: new Map(), toolCallCorrelations: new Map(), mergeProposals: new Map(), events: [], nextIds: { agent: 1, lane: 1, effect: 1, wait: 1, result: 1, artifact: 1, proposal: 1, event: 1 }, maxTotalLanes, maxQueuedEffects: options.maxQueuedEffects ?? 256, maxRunning: { llm: 4, tool: 16, agent: 4, none: Number.POSITIVE_INFINITY, ...(options.maxRunning ?? {}) }, forkAffinity: options.forkAffinity ?? 'advise', historySoftTokens: options.historySoftTokens ?? 8_000, historyHardTokens: options.historyHardTokens ?? 16_000, maxResultSummaryBytes: options.maxResultSummaryBytes ?? 4_096, trustedSanitizerIds: new Set(options.trustedSanitizerIds ?? []) };
+}
+export function privacyRank(label) { return label === 'public' ? 0 : label === 'cloud_allowed' ? 1 : 2; }
+export function strictestPrivacy(labels) { return labels.reduce((current, next) => privacyRank(next) > privacyRank(current) ? next : current, 'public'); }
+export function isSideEffectful(policy) { return policy === 'write' || policy === 'external'; }
+export function privacyTaintPrivacy(taints) { return strictestPrivacy((taints ?? []).map((taint) => taint.privacy)); }
+export function effectivePrivacy(base, taints) { return strictestPrivacy([base, privacyTaintPrivacy(taints)]); }
+export function validatePrivacyTaints(value) {
+    if (value === undefined)
+        return undefined;
+    const paths = new Set();
+    for (const taint of value) {
+        if (!taint || !Array.isArray(taint.path) || taint.path.length === 0 || taint.path.some((part) => typeof part !== 'string' || part.length === 0))
+            return 'INVALID_PRIVACY_TAINT';
+        const key = JSON.stringify(taint.path);
+        if (paths.has(key))
+            return 'DUPLICATE_PRIVACY_TAINT';
+        paths.add(key);
+        if (taint.privacy !== 'public' && taint.privacy !== 'cloud_allowed' && taint.privacy !== 'local_only')
+            return 'INVALID_PRIVACY_TAINT';
+    }
+    return undefined;
+}

package/dist/dependencies/graph.d.ts

@@ -0,0 +1,25 @@
+import type { TargetRef } from '../core/types.js';
+export interface DependencyEdge {
+    from: TargetRef;
+    to: TargetRef;
+    kind: 'wait' | 'ownership';
+}
+export declare class DependencyGraph {
+    private readonly edges;
+    private readonly reverse;
+    add(from: TargetRef, to: TargetRef, kind?: DependencyEdge['kind']): void;
+    remove(from: TargetRef, to: TargetRef): void;
+    hasCycle(): boolean;
+    stronglyConnectedComponents(): string[][];
+}
+export declare class WaitingIndex {
+    private readonly waits;
+    add(target: TargetRef, waitId: string): void;
+    remove(target: TargetRef, waitId: string): void;
+    waitingOn(target: TargetRef): string[];
+}
+export declare function detectDependencyCycle(edges: Array<{
+    from: TargetRef;
+    to: TargetRef;
+    kind?: 'wait' | 'ownership';
+}>): boolean;

package/dist/dependencies/graph.js

@@ -0,0 +1,92 @@
+export class DependencyGraph {
+    edges = new Map();
+    reverse = new Map();
+    add(from, to, kind = 'wait') {
+        if (kind === 'ownership')
+            return;
+        const source = `${from.kind}:${from.id}`;
+        const target = `${to.kind}:${to.id}`;
+        if (!this.edges.has(source))
+            this.edges.set(source, new Set());
+        if (!this.reverse.has(target))
+            this.reverse.set(target, new Set());
+        this.edges.get(source).add(target);
+        this.reverse.get(target).add(source);
+    }
+    remove(from, to) {
+        this.edges.get(`${from.kind}:${from.id}`)?.delete(`${to.kind}:${to.id}`);
+        this.reverse.get(`${to.kind}:${to.id}`)?.delete(`${from.kind}:${from.id}`);
+    }
+    hasCycle() {
+        const visited = new Set();
+        const active = new Set();
+        const visit = (node) => {
+            if (active.has(node))
+                return true;
+            if (visited.has(node))
+                return false;
+            visited.add(node);
+            active.add(node);
+            for (const child of this.edges.get(node) ?? [])
+                if (visit(child))
+                    return true;
+            active.delete(node);
+            return false;
+        };
+        return [...this.edges.keys()].some(visit);
+    }
+    stronglyConnectedComponents() {
+        let index = 0;
+        const indices = new Map();
+        const low = new Map();
+        const stack = [];
+        const onStack = new Set();
+        const components = [];
+        const visit = (node) => {
+            indices.set(node, index);
+            low.set(node, index);
+            index++;
+            stack.push(node);
+            onStack.add(node);
+            for (const child of this.edges.get(node) ?? []) {
+                if (!indices.has(child)) {
+                    visit(child);
+                    low.set(node, Math.min(low.get(node), low.get(child)));
+                }
+                else if (onStack.has(child))
+                    low.set(node, Math.min(low.get(node), indices.get(child)));
+            }
+            if (low.get(node) === indices.get(node)) {
+                const component = [];
+                let popped = '';
+                do {
+                    popped = stack.pop();
+                    onStack.delete(popped);
+                    component.push(popped);
+                } while (popped !== node);
+                components.push(component);
+            }
+        };
+        for (const node of new Set([...this.edges.keys(), ...this.reverse.keys()]))
+            if (!indices.has(node))
+                visit(node);
+        return components;
+    }
+}
+export class WaitingIndex {
+    waits = new Map();
+    add(target, waitId) {
+        const key = `${target.kind}:${target.id}`;
+        if (!this.waits.has(key))
+            this.waits.set(key, new Set());
+        this.waits.get(key).add(waitId);
+    }
+    remove(target, waitId) { this.waits.get(`${target.kind}:${target.id}`)?.delete(waitId); }
+    waitingOn(target) { return [...(this.waits.get(`${target.kind}:${target.id}`) ?? [])]; }
+}
+export function detectDependencyCycle(edges) {
+    const graph = new DependencyGraph();
+    for (const edge of edges)
+        graph.add(edge.from, edge.to, edge.kind ?? 'wait');
+    return graph.hasCycle();
+}

package/dist/dependencies/index.d.ts

@@ -0,0 +1 @@
+export * from './graph.js';

package/dist/dependencies/index.js

@@ -0,0 +1 @@
+export * from './graph.js';

package/dist/dsl/context-proxy.d.ts

@@ -0,0 +1,20 @@
+import type { JsonValue } from '../core/types.js';
+export interface DraftChanges {
+    value: JsonValue;
+    ops: Array<{
+        op: 'set';
+        path: string[];
+        value: JsonValue;
+    } | {
+        op: 'append';
+        path: string[];
+        value: JsonValue;
+    } | {
+        op: 'remove';
+        path: string[];
+    }>;
+}
+export declare function createDraftProxy<T extends Record<string, unknown>>(initial: T): {
+    draft: T;
+    changes(): DraftChanges;
+};

package/dist/dsl/context-proxy.js

@@ -0,0 +1,64 @@
+import { isUnsafePathSegment } from '../context/builder.js';
+/**
+ * Property names that would address the prototype chain are refused up front.
+ * Model-derived keys (e.g. `draft.byUser[modelOutput.id]`) must never be able to
+ * reach `Object.prototype`, neither in-process nor through the recorded ops.
+ */
+function assertSafeKey(property) {
+    if (isUnsafePathSegment(property))
+        throw Object.assign(new Error(`UNSAFE_CONTEXT_PATH:${property}`), { code: 'UNSAFE_CONTEXT_PATH', retryable: false });
+}
+export function createDraftProxy(initial) {
+    const value = structuredClone(initial);
+    const ops = [];
+    const proxies = new WeakMap();
+    const wrap = (target, basePath) => {
+        const existing = proxies.get(target);
+        if (existing)
+            return existing;
+        const proxy = new Proxy(target, {
+            get(current, property, receiver) {
+                if (Array.isArray(current) && typeof property === 'string') {
+                    if (property === 'push')
+                        return (...items) => { for (const item of items) {
+                            current.push(structuredClone(item));
+                            ops.push({ op: 'append', path: basePath, value: structuredClone(item) });
+                        } ; return current.length; };
+                    if (property === 'splice')
+                        return (start, deleteCount, ...items) => { const result = Array.prototype.splice.call(current, start, deleteCount ?? current.length - start, ...items.map((item) => structuredClone(item))); ops.push({ op: 'set', path: basePath, value: structuredClone(current) }); return result; };
+                    if (property === 'sort')
+                        return (compareFn) => { Array.prototype.sort.call(current, compareFn); ops.push({ op: 'set', path: basePath, value: structuredClone(current) }); return current; };
+                }
+                if (typeof property === 'string' && isUnsafePathSegment(property))
+                    return undefined;
+                const next = Reflect.get(current, property, receiver);
+                return typeof property === 'string' && next !== null && typeof next === 'object' ? wrap(next, [...basePath, property]) : next;
+            },
+            set(current, property, next, receiver) {
+                if (typeof property === 'string') {
+                    assertSafeKey(property);
+                    if (Array.isArray(current) && (/^\d+$/.test(property) || property === 'length')) {
+                        const result = Reflect.set(current, property, next, receiver);
+                        if (property !== 'length')
+                            ops.push({ op: 'set', path: basePath, value: structuredClone(current) });
+                        return result;
+                    }
+                    ops.push({ op: 'set', path: [...basePath, property], value: structuredClone(next) });
+                }
+                return Reflect.set(current, property, next, receiver);
+            },
+            deleteProperty(current, property) {
+                if (typeof property === 'string')
+                    assertSafeKey(property);
+                const result = Reflect.deleteProperty(current, property);
+                if (typeof property === 'string')
+                    ops.push(Array.isArray(current) && /^\d+$/.test(property) ? { op: 'set', path: basePath, value: structuredClone(current) } : { op: 'remove', path: [...basePath, property] });
+                return result;
+            },
+        });
+        proxies.set(target, proxy);
+        return proxy;
+    };
+    const draft = wrap(value, []);
+    return { draft, changes: () => ({ value: value, ops: [...ops] }) };
+}

package/dist/dsl/index.d.ts

@@ -0,0 +1,4 @@
+export * from './program.js';
+export * from './templates.js';
+export * from './session.js';
+export * from './context-proxy.js';

package/dist/dsl/index.js

@@ -0,0 +1,4 @@
+export * from './program.js';
+export * from './templates.js';
+export * from './session.js';
+export * from './context-proxy.js';

package/dist/dsl/program.d.ts

@@ -0,0 +1,314 @@
+import { z, type ZodTypeAny } from 'zod';
+import type { LaneProgram } from '../scheduler/runtime.js';
+import type { ContextDelta, JsonValue, LaneRecord, ResultRef, ProvenanceRef, RuntimeAction, ResumeInput, ProgressWatchdogState, ContextOp, LaneId, PrivacyLabel, RuntimeError, MergeProposal, ResourceLockSpec, Outcome, WaitResolution } from '../core/types.js';
+import type { ProgramRef } from './templates.js';
+export type NextStepTarget<TState = unknown> = string | {
+    step: string;
+} | {
+    complete: {
+        value?: JsonValue;
+        privacy?: PrivacyLabel;
+        children?: 'reject_if_active' | 'cancel' | 'await';
+    };
+} | {
+    fail: {
+        code: string;
+        message: string;
+        retryable?: boolean;
+        details?: JsonValue;
+        privacy?: PrivacyLabel;
+        derivedFrom?: ProvenanceRef[];
+    };
+};
+export type ScalarProjection<T> = T extends string | number | boolean | null ? T : T extends readonly unknown[] ? never : T extends object ? {
+    [K in keyof T]: T[K] extends string | number | boolean | null ? T[K] : never;
+} : never;
+export interface InstructionView<TState> {
+    goal: string;
+    state: ScalarProjection<TState>;
+}
+export interface StepInputs {
+    results?: ResultRef[];
+    findings?: ResultRef[];
+    artifacts?: string[];
+    events?: string[];
+}
+export interface HistoryCompactionOptions {
+    summarizeTask: string;
+    keepRecentRounds: number;
+}
+export interface HistoryRecordMeta {
+    seq: number;
+    hash: string;
+    effectId?: string;
+    resultRefs: ResultRef[];
+    resultSelection?: Array<{
+        ref: ResultRef;
+        rule: string;
+        hash: string;
+    }>;
+    result?: ResultRef;
+    findings?: ResultRef[];
+    privacy: PrivacyLabel;
+    privacyTaints?: import('../core/types.js').PrivacyTaint[];
+}
+export interface ResultMeta {
+    ref: ResultRef;
+    privacy: PrivacyLabel;
+    derivedFrom: ProvenanceRef[];
+    sizeBytes: number;
+    hash: string;
+    producer: {
+        kind: 'lane' | 'effect';
+        id: string;
+    };
+    summary?: JsonValue;
+}
+export interface StepContext<TState = JsonValue> {
+    lane: Readonly<LaneRecord>;
+    goal: string;
+    global: Readonly<JsonValue>;
+    globalVersion: number;
+    laneState: Readonly<TState>;
+    history: ReadonlyArray<HistoryRecordMeta>;
+    now: number;
+    watchdog?: ProgressWatchdogState;
+    resumeInput?: ResumeInput;
+    results: {
+        meta(ref: ResultRef): ResultMeta | undefined;
+        summary(ref: ResultRef): JsonValue | undefined;
+    };
+    mergeProposals: ReadonlyArray<MergeProposal>;
+    mutateLane(mutator: (draft: TState) => void): void;
+    proposeGlobal(delta: {
+        ops: ContextOp[] | ((draft: Record<string, JsonValue>) => void);
+        privacy?: PrivacyLabel;
+    }): void;
+    commitGlobal(delta: {
+        ops: ContextOp[] | ((draft: Record<string, JsonValue>) => void);
+        privacy?: PrivacyLabel;
+        adoptImmediately?: boolean;
+    }): void;
+    adoptContext(version: number | 'latest'): void;
+    cancelLane(target: LaneId, reason: 'SUPERSEDED' | 'USER_REQUESTED' | 'POLICY'): void;
+    proposeCancel(target: LaneId, reason: 'SUPERSEDED' | 'POLICY'): void;
+    trace(message: string | {
+        kind: string;
+        data?: JsonValue;
+    }): void;
+}
+export interface ForkProposalLane {
+    goal: string;
+    program: ProgramRef;
+    priority?: number;
+    contextVersion?: 'parent' | 'latest' | number;
+    affinityKey?: string;
+    resources?: ResourceLockSpec[];
+    inputResultRefs?: ResultRef[];
+    dependsOn?: Array<{
+        sibling: string;
+        condition: 'success' | 'settled';
+    }>;
+}
+export interface ForkProposal {
+    lanes: Record<string, ForkProposalLane>;
+}
+export interface ForkJoinOptions {
+    condition?: 'success' | 'settled';
+    onUnsatisfied?: 'fail_lane' | 'resume_with_error';
+    onCancelled?: 'unsatisfied' | 'ignore';
+}
+type Handler = (ctx: StepContext<any>) => {
+    actions?: RuntimeAction[];
+    next: NextStepTarget;
+    contextDelta?: ContextDelta | undefined;
+    adoptCommittedContext?: boolean;
+    locals?: JsonValue;
+};
+export interface LaneProgramDefinition extends LaneProgram {
+    id: string;
+    version: string;
+    system?: string;
+    toolSet?: string;
+    entry: string;
+    steps: string[];
+    debugSources?: string[];
+}
+type ErrorBoundaryHandler<TState> = (error: RuntimeError, ctx: StepContext<TState>) => NextStepTarget<TState> | {
+    fail: RuntimeError;
+};
+interface AffinityAdviceGroup {
+    keys: string[];
+    signals: string[];
+}
+export declare class StepBuilder<TState = JsonValue> {
+    readonly config: {
+        id: string;
+        version: string;
+        system?: string;
+        toolSet?: string;
+        state?: z.ZodType<TState>;
+        historyCompaction?: HistoryCompactionOptions;
+    };
+    readonly handlers: Map<string, Handler>;
+    /**
+     * History compaction is a macro boundary concern. Internal handlers such as
+     * `:submit`, `:decode`, `:join`, and `:resume` must consume the pending
+     * Wait input before the next compaction check can run.
+     */
+    private readonly compactionBoundaries;
+    private boundaryHandler?;
+    constructor(config: {
+        id: string;
+        version: string;
+        system?: string;
+        toolSet?: string;
+        state?: z.ZodType<TState>;
+        historyCompaction?: HistoryCompactionOptions;
+    });
+    addStep(name: string, handler: Handler): this;
+    onErrorBoundary(handler: ErrorBoundaryHandler<TState>): this;
+    addStructuredLLMStep<TOutput extends ZodTypeAny>(name: string, options: {
+        task: string;
+        instruction: string | ((view: InstructionView<TState>) => string);
+        schema: TOutput;
+        inputs?: (ctx: StepContext<TState>) => StepInputs;
+        requirements?: Record<string, JsonValue>;
+        executionPolicy?: {
+            duplicateExecutionPolicy: 'allow' | 'forbid';
+            maxUnknownAttempts: number;
+        };
+        retryPolicy?: {
+            maxAttempts: number;
+            initialBackoffMs: number;
+            maxBackoffMs: number;
+            jitter: boolean;
+        };
+        selfCorrect?: {
+            maxRounds: 0 | 1;
+        };
+        onSuccess: (data: z.infer<TOutput>, ctx: StepContext<TState>) => NextStepTarget<TState>;
+        onError?: (error: RuntimeError, ctx: StepContext<TState>) => NextStepTarget<TState>;
+    }): this;
+    addReActLoopStep(name: string, options: {
+        task?: string;
+        instruction: string | ((view: InstructionView<TState>) => string);
+        inputs?: (ctx: StepContext<TState>) => StepInputs;
+        toolAllow?: string[];
+        maxTurns?: number;
+        outputSchema?: ZodTypeAny;
+        requirements?: Record<string, JsonValue>;
+        toolApproval?: {
+            prompt: string | ((calls: JsonValue, ctx: StepContext<TState>) => string);
+            onDenied?: (reason: string, ctx: StepContext<TState>) => NextStepTarget<TState>;
+        };
+        onFinish: ((resultRef: ResultRef, ctx: StepContext<TState>) => NextStepTarget<TState>) | {
+            text: (resultRef: ResultRef, ctx: StepContext<TState>) => NextStepTarget<TState>;
+            structured?: {
+                schema: ZodTypeAny;
+                onParsed: (data: unknown, ctx: StepContext<TState>) => NextStepTarget<TState>;
+            };
+        };
+        onMaxTurns?: (ctx: StepContext<TState>) => NextStepTarget<TState>;
+        onError?: (error: RuntimeError, ctx: StepContext<TState>) => NextStepTarget<TState>;
+    }): this;
+    addParallelStep(name: string, options: {
+        lanes: Record<string, ForkProposalLane & {
+            dependsOn?: ForkProposalLane['dependsOn'] | Array<{
+                key: string;
+                target: {
+                    local: string;
+                } | {
+                    kind: 'lane' | 'effect';
+                    id: string;
+                };
+                condition: 'success' | 'settled';
+            }>;
+        }>;
+        join?: ForkJoinOptions;
+        condition?: 'success' | 'settled';
+        mode?: 'all' | 'any' | 'quorum';
+        quorum?: number;
+        deadlineAt?: number;
+        affinity?: 'collapse' | 'ack';
+        next?: NextStepTarget;
+        onJoin?: (outcomes: Record<string, Outcome>, ctx: StepContext<TState>) => NextStepTarget;
+    }): this;
+    addDynamicForkStep(name: string, options: {
+        proposal?: (ctx: StepContext<TState>) => ForkProposal;
+        lanes?: (ctx: StepContext<TState>) => Record<string, ForkProposalLane>;
+        join?: ForkJoinOptions;
+        condition?: 'success' | 'settled';
+        mode?: 'all' | 'any' | 'quorum';
+        quorum?: number;
+        deadlineAt?: number;
+        affinity?: 'collapse' | 'ack' | ((groups: AffinityAdviceGroup[], ctx: StepContext<TState>) => 'collapse' | 'ack');
+        next?: NextStepTarget;
+        onJoin?: (outcomes: Map<string, Outcome>, ctx: StepContext<TState>) => NextStepTarget;
+    }): this;
+    addMergeStep(name: string, options: {
+        task?: string;
+        next?: NextStepTarget;
+        sources?: {
+            proposals?: 'joined' | LaneId[];
+            outcomes?: 'joined' | LaneId[];
+        };
+        instruction?: string | ((ctx: StepContext<TState>) => string);
+        schema?: ZodTypeAny;
+        onSynthesized?: (value: unknown, ctx: StepContext<TState>) => NextStepTarget;
+        onError?: (error: RuntimeError, ctx: StepContext<TState>) => NextStepTarget;
+    }): this;
+    addWaitStep(name: string, spec: {
+        dependencies: Array<{
+            key: string;
+            target: {
+                kind: 'lane' | 'effect';
+                id: string;
+            };
+            condition: 'success' | 'settled';
+        }>;
+        mode?: 'all' | 'any' | 'quorum';
+        quorum?: number;
+        deadlineAt?: number;
+        next: NextStepTarget;
+    } | {
+        targets: (ctx: StepContext<TState>) => Array<{
+            key: string;
+            target: {
+                kind: 'lane' | 'effect';
+                id: string;
+            };
+            condition: 'success' | 'settled';
+        }>;
+        mode?: 'all' | 'any' | 'quorum';
+        quorum?: number;
+        timeoutMs?: number;
+        onResolved: (resolution: WaitResolution, ctx: StepContext<TState>) => NextStepTarget<TState>;
+        onUnsatisfied?: (resolution: WaitResolution, ctx: StepContext<TState>) => NextStepTarget<TState>;
+    }): this;
+    addHumanStep<TOutput extends ZodTypeAny>(name: string, options: {
+        prompt: string | ((view: InstructionView<TState>) => string);
+        inputs?: (ctx: StepContext<TState>) => StepInputs;
+        schema: TOutput;
+        onReply: (reply: z.infer<TOutput>, ctx: StepContext<TState>) => NextStepTarget;
+        onTimeout?: (ctx: StepContext<TState>) => NextStepTarget;
+        timeoutMs?: number;
+    }): this;
+    addTimerStep(name: string, options: {
+        delayMs: number | ((ctx: StepContext<TState>) => number);
+        onFire: (ctx: StepContext<TState>) => NextStepTarget;
+    }): this;
+    build(entry?: string): LaneProgramDefinition;
+}
+export declare function defineLaneProgram<TState = JsonValue>(config: {
+    id: string;
+    version: string;
+    system?: string;
+    toolSet?: string;
+    state?: z.ZodType<TState>;
+    historyCompaction?: HistoryCompactionOptions;
+}, define: (builder: StepBuilder<TState>) => void): LaneProgramDefinition;
+/** Run a synchronous Step inside the development-only impurity boundary. */
+export declare function withPureStepGuard<T>(callback: () => T): T;
+export declare function assertProgramPure(program: LaneProgramDefinition | LaneProgram): void;
+export {};