condukt 0.1.0

package/dist/src/types.d.ts

@@ -0,0 +1,201 @@
+/**
+ * Flow framework type system — generic, zero domain imports.
+ *
+ * Three primitives: agent(), deterministic(), gate()
+ * One combinator: verify()
+ * One composition: FlowGraph + run()
+ */
+import type { ExecutionEvent, OutputEvent } from './events';
+declare const __brand: unique symbol;
+type Brand<T, B extends string> = T & {
+    readonly [__brand]: B;
+};
+/** Branded execution identifier. Create: `'my-id' as ExecutionId` */
+export type ExecutionId = Brand<string, 'ExecutionId'>;
+/**
+ * The fundamental callable unit.
+ * Receives NodeInput (composition data) + ExecutionContext (runtime services).
+ * Returns a routing action + optional artifact.
+ */
+export type NodeFn = (input: NodeInput, ctx: ExecutionContext) => Promise<NodeOutput>;
+/** What every node receives — composition-defined, framework-opaque. */
+export interface NodeInput {
+    readonly dir: string;
+    readonly params: Readonly<Record<string, unknown>>;
+    readonly artifactPaths: Readonly<Record<string, string>>;
+    readonly retryContext?: RetryContext;
+}
+/** What every node returns — the scheduler handles event emission from this. */
+export interface NodeOutput {
+    readonly action: string;
+    readonly artifact?: string;
+    readonly metadata?: Record<string, unknown>;
+}
+/** Populated on retry: prior output + check feedback + user override. */
+export interface RetryContext {
+    readonly priorOutput: string | null;
+    readonly feedback: string;
+    readonly override?: string;
+}
+/** Runtime services injected by the scheduler — not shared mutable state. */
+export interface ExecutionContext {
+    readonly executionId: string;
+    readonly nodeId: string;
+    readonly runtime: AgentRuntime;
+    readonly emitOutput: (event: OutputEvent) => void;
+    readonly signal: AbortSignal;
+}
+/** A complete flow graph: nodes + edges + start. */
+export interface FlowGraph {
+    readonly nodes: Readonly<Record<string, NodeEntry>>;
+    readonly edges: Readonly<Record<string, Readonly<Record<string, string>>>>;
+    readonly start: readonly string[];
+}
+/** A node in the flow graph. */
+export interface NodeEntry {
+    readonly fn: NodeFn;
+    readonly displayName: string;
+    readonly nodeType: 'agent' | 'deterministic' | 'gate' | 'verify';
+    readonly output?: string;
+    readonly reads?: readonly string[];
+    readonly model?: string;
+    readonly timeout?: number;
+}
+export interface RunOptions {
+    readonly executionId: string;
+    readonly dir: string;
+    readonly params: Readonly<Record<string, unknown>>;
+    readonly runtime: AgentRuntime;
+    readonly emitState: (event: ExecutionEvent) => Promise<void>;
+    readonly emitOutput: (event: OutputEvent) => void;
+    readonly signal: AbortSignal;
+    readonly resumeFrom?: ResumeState;
+    /** PARITY-1: RetryContext for specific nodes (nodeId → RetryContext). */
+    readonly retryContexts?: Readonly<Record<string, RetryContext>>;
+}
+export interface RunResult {
+    readonly completed: boolean;
+    readonly durationMs: number;
+}
+export interface ResumeState {
+    readonly completedNodes: Map<string, {
+        action: string;
+        finishedAt: number;
+    }>;
+    readonly firedEdges: Map<string, Set<string>>;
+    readonly nodeStatuses: Map<string, string>;
+}
+export interface AgentRuntime {
+    createSession(config: SessionConfig): Promise<AgentSession>;
+    isAvailable(): Promise<boolean>;
+    readonly name: string;
+}
+export interface SessionConfig {
+    readonly model: string;
+    readonly cwd: string;
+    readonly addDirs: readonly string[];
+    readonly timeout: number;
+    readonly heartbeatTimeout: number;
+}
+export interface AgentSession {
+    readonly pid: number | null;
+    send(prompt: string): void;
+    on(event: 'text', handler: (text: string) => void): void;
+    on(event: 'tool_start', handler: (tool: string, input: string) => void): void;
+    on(event: 'tool_complete', handler: (tool: string, output: string) => void): void;
+    on(event: 'idle', handler: () => void): void;
+    on(event: 'error', handler: (err: Error) => void): void;
+    abort(): Promise<void>;
+}
+export type PromptOutput = string | {
+    system: string;
+    user: string;
+};
+export interface ToolRef {
+    readonly id: string;
+    readonly displayName: string;
+}
+export interface AgentConfig {
+    readonly objective: string;
+    readonly tools: readonly ToolRef[];
+    readonly output?: string;
+    readonly reads?: readonly string[];
+    readonly model?: string;
+    readonly isolation?: boolean;
+    readonly timeout?: number;
+    readonly heartbeatTimeout?: number;
+    /** Override session cwd. Default: input.dir. Use for running in repo dir while artifacts go to input.dir. */
+    readonly cwdResolver?: (input: NodeInput) => string;
+    readonly setup?: (input: NodeInput) => void | Promise<void>;
+    readonly teardown?: (input: NodeInput) => void | Promise<void>;
+    readonly promptBuilder: (input: NodeInput) => PromptOutput;
+    readonly actionParser?: (artifactContent: string) => string;
+    readonly completionIndicators?: readonly string[];
+}
+export interface ExecutionProjection {
+    readonly id: string;
+    readonly flowId: string;
+    readonly status: 'pending' | 'running' | 'completed' | 'failed' | 'stopped' | 'crashed';
+    readonly params: Record<string, unknown>;
+    readonly graph: {
+        readonly nodes: ReadonlyArray<ProjectionNode>;
+        readonly edges: ReadonlyArray<ProjectionEdge>;
+        readonly activeNodes: readonly string[];
+        readonly completedPath: readonly string[];
+    };
+    readonly totalCost: number;
+    readonly startedAt?: number;
+    readonly finishedAt?: number;
+    readonly metadata: Record<string, unknown>;
+}
+export interface ProjectionNode {
+    readonly id: string;
+    readonly displayName: string;
+    readonly nodeType: string;
+    readonly model?: string;
+    readonly status: string;
+    readonly action?: string;
+    readonly startedAt?: number;
+    readonly finishedAt?: number;
+    readonly elapsedMs?: number;
+    readonly attempt: number;
+    readonly error?: string;
+    readonly output?: string;
+    readonly gateData?: Record<string, unknown>;
+}
+export interface ProjectionEdge {
+    readonly source: string;
+    readonly action: string;
+    readonly target: string;
+    readonly state: 'default' | 'taken' | 'not_taken';
+}
+export interface OutputPage {
+    readonly lines: readonly string[];
+    readonly offset: number;
+    readonly total: number;
+    readonly hasMore: boolean;
+}
+export interface StorageEngine {
+    appendEvent(execId: string, event: ExecutionEvent): void;
+    readEvents(execId: string): ExecutionEvent[];
+    writeProjection(execId: string, projection: ExecutionProjection): void;
+    readProjection(execId: string): ExecutionProjection | null;
+    writeArtifact(execId: string, nodeId: string, name: string, content: string): void;
+    readArtifact(execId: string, nodeId: string, name: string): string | null;
+    appendOutput(execId: string, nodeId: string, line: string): void;
+    readOutput(execId: string, nodeId: string, offset?: number, limit?: number): OutputPage;
+    closeOutput(execId: string, nodeId: string): void;
+    delete(execId: string): boolean;
+    listExecutionIds(): string[];
+}
+/** Type-safe params access: `getParams<MyParams>(projection)` (CR2) */
+export declare function getParams<T>(projection: ExecutionProjection): T;
+export declare class FlowAbortedError extends Error {
+    constructor(reason?: string);
+}
+export declare class FlowValidationError extends Error {
+    readonly issues: readonly string[];
+    constructor(issues: readonly string[]);
+}
+export {};
+//# sourceMappingURL=types.d.ts.map

package/dist/src/types.d.ts.map

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

package/dist/src/types.js

@@ -0,0 +1,38 @@
+"use strict";
+/**
+ * Flow framework type system — generic, zero domain imports.
+ *
+ * Three primitives: agent(), deterministic(), gate()
+ * One combinator: verify()
+ * One composition: FlowGraph + run()
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FlowValidationError = exports.FlowAbortedError = void 0;
+exports.getParams = getParams;
+// ---------------------------------------------------------------------------
+// Utilities
+// ---------------------------------------------------------------------------
+/** Type-safe params access: `getParams<MyParams>(projection)` (CR2) */
+function getParams(projection) {
+    return projection.params;
+}
+// ---------------------------------------------------------------------------
+// Errors
+// ---------------------------------------------------------------------------
+class FlowAbortedError extends Error {
+    constructor(reason = 'Flow aborted') {
+        super(reason);
+        this.name = 'FlowAbortedError';
+    }
+}
+exports.FlowAbortedError = FlowAbortedError;
+class FlowValidationError extends Error {
+    issues;
+    constructor(issues) {
+        super(`Flow validation failed:\n${issues.map(i => `  - ${i}`).join('\n')}`);
+        this.issues = issues;
+        this.name = 'FlowValidationError';
+    }
+}
+exports.FlowValidationError = FlowValidationError;
+//# sourceMappingURL=types.js.map

package/dist/src/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/types.ts"],"names":[],"mappings":";AAAA;;;;;;GAMG;;;AA8OH,8BAEC;AAPD,8EAA8E;AAC9E,YAAY;AACZ,8EAA8E;AAE9E,uEAAuE;AACvE,SAAgB,SAAS,CAAI,UAA+B;IAC1D,OAAO,UAAU,CAAC,MAAW,CAAC;AAChC,CAAC;AAED,8EAA8E;AAC9E,SAAS;AACT,8EAA8E;AAE9E,MAAa,gBAAiB,SAAQ,KAAK;IACzC,YAAY,SAAiB,cAAc;QACzC,KAAK,CAAC,MAAM,CAAC,CAAC;QACd,IAAI,CAAC,IAAI,GAAG,kBAAkB,CAAC;IACjC,CAAC;CACF;AALD,4CAKC;AAED,MAAa,mBAAoB,SAAQ,KAAK;IACvB;IAArB,YAAqB,MAAyB;QAC5C,KAAK,CAAC,4BAA4B,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QADzD,WAAM,GAAN,MAAM,CAAmB;QAE5C,IAAI,CAAC,IAAI,GAAG,qBAAqB,CAAC;IACpC,CAAC;CACF;AALD,kDAKC"}

package/dist/src/verify.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Verify combinator — wraps a producer NodeFn with a check loop.
+ *
+ * On each iteration:
+ * 1. Call the producer to generate output
+ * 2. Run all checks against the output
+ * 3. If all pass → return the producer's output
+ * 4. If any fail → build feedback, inject RetryContext, retry
+ * 5. If max iterations reached → return { action: 'fail' }
+ *
+ * The verify combinator is itself a NodeFn. From the scheduler's perspective,
+ * it's one node that may take multiple internal iterations.
+ */
+import type { NodeFn } from './types';
+export interface VerifyCheck {
+    readonly name: string;
+    readonly fn: (dir: string, artifactContent: string | undefined) => Promise<CheckResult>;
+}
+export interface CheckResult {
+    readonly passed: boolean;
+    readonly feedback: string;
+}
+export interface VerifyConfig {
+    readonly checks: readonly VerifyCheck[];
+    readonly maxIterations?: number;
+}
+/**
+ * Creates a VerifyCheck from a predicate function.
+ *
+ * @param name - Display name for the check
+ * @param predicate - Function that examines artifact content and returns true/false
+ * @param failureMessage - Message to include in feedback when check fails
+ */
+export declare function property(name: string, predicate: (content: string) => boolean, failureMessage: string): VerifyCheck;
+/**
+ * Wraps a producer NodeFn with iterative verification.
+ *
+ * The returned NodeFn:
+ * 1. Calls the producer (which may be an agent, deterministic, etc.)
+ * 2. Runs all checks against the producer's output
+ * 3. If all checks pass → returns the producer's NodeOutput
+ * 4. If any check fails → injects RetryContext with feedback, calls producer again
+ * 5. After maxIterations failures → returns { action: 'fail' }
+ *
+ * Each iteration emits metadata events with check results for observability.
+ *
+ * @param producer - The NodeFn to wrap (e.g., an agent node)
+ * @param config - Checks to run and max iterations
+ */
+export declare function verify(producer: NodeFn, config: VerifyConfig): NodeFn;
+//# sourceMappingURL=verify.d.ts.map

package/dist/src/verify.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"verify.d.ts","sourceRoot":"","sources":["../../src/verify.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EACV,MAAM,EAIP,MAAM,SAAS,CAAC;AAMjB,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,EAAE,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,eAAe,EAAE,MAAM,GAAG,SAAS,KAAK,OAAO,CAAC,WAAW,CAAC,CAAC;CACzF;AAED,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,MAAM,EAAE,SAAS,WAAW,EAAE,CAAC;IACxC,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;CACjC;AAMD;;;;;;GAMG;AACH,wBAAgB,QAAQ,CACtB,IAAI,EAAE,MAAM,EACZ,SAAS,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,OAAO,EACvC,cAAc,EAAE,MAAM,GACrB,WAAW,CAcb;AAMD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,MAAM,CACpB,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,YAAY,GACnB,MAAM,CA4ER"}

package/dist/src/verify.js

@@ -0,0 +1,126 @@
+"use strict";
+/**
+ * Verify combinator — wraps a producer NodeFn with a check loop.
+ *
+ * On each iteration:
+ * 1. Call the producer to generate output
+ * 2. Run all checks against the output
+ * 3. If all pass → return the producer's output
+ * 4. If any fail → build feedback, inject RetryContext, retry
+ * 5. If max iterations reached → return { action: 'fail' }
+ *
+ * The verify combinator is itself a NodeFn. From the scheduler's perspective,
+ * it's one node that may take multiple internal iterations.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.property = property;
+exports.verify = verify;
+// ---------------------------------------------------------------------------
+// property() — convenience factory for common check patterns
+// ---------------------------------------------------------------------------
+/**
+ * Creates a VerifyCheck from a predicate function.
+ *
+ * @param name - Display name for the check
+ * @param predicate - Function that examines artifact content and returns true/false
+ * @param failureMessage - Message to include in feedback when check fails
+ */
+function property(name, predicate, failureMessage) {
+    return {
+        name,
+        fn: async (_dir, artifactContent) => {
+            if (artifactContent == null || artifactContent.trim() === '') {
+                return { passed: false, feedback: `${name}: No artifact content to verify` };
+            }
+            const passed = predicate(artifactContent);
+            return {
+                passed,
+                feedback: passed ? `${name}: passed` : `${name}: ${failureMessage}`,
+            };
+        },
+    };
+}
+// ---------------------------------------------------------------------------
+// verify() — the combinator
+// ---------------------------------------------------------------------------
+/**
+ * Wraps a producer NodeFn with iterative verification.
+ *
+ * The returned NodeFn:
+ * 1. Calls the producer (which may be an agent, deterministic, etc.)
+ * 2. Runs all checks against the producer's output
+ * 3. If all checks pass → returns the producer's NodeOutput
+ * 4. If any check fails → injects RetryContext with feedback, calls producer again
+ * 5. After maxIterations failures → returns { action: 'fail' }
+ *
+ * Each iteration emits metadata events with check results for observability.
+ *
+ * @param producer - The NodeFn to wrap (e.g., an agent node)
+ * @param config - Checks to run and max iterations
+ */
+function verify(producer, config) {
+    const maxIterations = config.maxIterations ?? 3;
+    return async (input, ctx) => {
+        let currentInput = input;
+        for (let iteration = 1; iteration <= maxIterations; iteration++) {
+            // Run the producer
+            const output = await producer(currentInput, ctx);
+            // Run all checks
+            const checkResults = await Promise.all(config.checks.map(async (check) => {
+                try {
+                    return await check.fn(input.dir, output.artifact);
+                }
+                catch (err) {
+                    return {
+                        passed: false,
+                        feedback: `${check.name}: check error — ${err instanceof Error ? err.message : String(err)}`,
+                    };
+                }
+            }));
+            const allPassed = checkResults.every((r) => r.passed);
+            // Emit check results as metadata for observability
+            const metadataOutput = {
+                action: output.action,
+                artifact: output.artifact,
+                metadata: {
+                    ...(output.metadata ?? {}),
+                    _verifyIteration: iteration,
+                    _verifyMaxIterations: maxIterations,
+                    _verifyChecks: checkResults.map((r, i) => ({
+                        name: config.checks[i].name,
+                        passed: r.passed,
+                        feedback: r.feedback,
+                    })),
+                },
+            };
+            if (allPassed) {
+                return metadataOutput;
+            }
+            // Last iteration — fail
+            if (iteration === maxIterations) {
+                return {
+                    action: 'fail',
+                    artifact: output.artifact,
+                    metadata: metadataOutput.metadata,
+                };
+            }
+            // Build feedback for retry
+            const failedChecks = checkResults
+                .filter((r) => !r.passed)
+                .map((r) => r.feedback);
+            const feedbackStr = `Verification failed (attempt ${iteration}/${maxIterations}):\n${failedChecks.map((f) => `  - ${f}`).join('\n')}`;
+            // Retry with RetryContext
+            currentInput = {
+                ...input,
+                retryContext: {
+                    priorOutput: output.artifact ?? null,
+                    feedback: feedbackStr,
+                    override: currentInput.retryContext?.override,
+                },
+            };
+        }
+        // Should not reach here, but TypeScript needs it
+        return { action: 'fail' };
+    };
+}
+//# sourceMappingURL=verify.js.map

package/dist/src/verify.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"verify.js","sourceRoot":"","sources":["../../src/verify.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;GAYG;;AAuCH,4BAkBC;AAqBD,wBA+EC;AAjID,8EAA8E;AAC9E,6DAA6D;AAC7D,8EAA8E;AAE9E;;;;;;GAMG;AACH,SAAgB,QAAQ,CACtB,IAAY,EACZ,SAAuC,EACvC,cAAsB;IAEtB,OAAO;QACL,IAAI;QACJ,EAAE,EAAE,KAAK,EAAE,IAAY,EAAE,eAAmC,EAAwB,EAAE;YACpF,IAAI,eAAe,IAAI,IAAI,IAAI,eAAe,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC;gBAC7D,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,QAAQ,EAAE,GAAG,IAAI,iCAAiC,EAAE,CAAC;YAC/E,CAAC;YACD,MAAM,MAAM,GAAG,SAAS,CAAC,eAAe,CAAC,CAAC;YAC1C,OAAO;gBACL,MAAM;gBACN,QAAQ,EAAE,MAAM,CAAC,CAAC,CAAC,GAAG,IAAI,UAAU,CAAC,CAAC,CAAC,GAAG,IAAI,KAAK,cAAc,EAAE;aACpE,CAAC;QACJ,CAAC;KACF,CAAC;AACJ,CAAC;AAED,8EAA8E;AAC9E,4BAA4B;AAC5B,8EAA8E;AAE9E;;;;;;;;;;;;;;GAcG;AACH,SAAgB,MAAM,CACpB,QAAgB,EAChB,MAAoB;IAEpB,MAAM,aAAa,GAAG,MAAM,CAAC,aAAa,IAAI,CAAC,CAAC;IAEhD,OAAO,KAAK,EAAE,KAAgB,EAAE,GAAqB,EAAuB,EAAE;QAC5E,IAAI,YAAY,GAAG,KAAK,CAAC;QAEzB,KAAK,IAAI,SAAS,GAAG,CAAC,EAAE,SAAS,IAAI,aAAa,EAAE,SAAS,EAAE,EAAE,CAAC;YAChE,mBAAmB;YACnB,MAAM,MAAM,GAAG,MAAM,QAAQ,CAAC,YAAY,EAAE,GAAG,CAAC,CAAC;YAEjD,iBAAiB;YACjB,MAAM,YAAY,GAAG,MAAM,OAAO,CAAC,GAAG,CACpC,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC,KAAK,EAAE,KAAK,EAAE,EAAE;gBAChC,IAAI,CAAC;oBACH,OAAO,MAAM,KAAK,CAAC,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,MAAM,CAAC,QAAQ,CAAC,CAAC;gBACpD,CAAC;gBAAC,OAAO,GAAG,EAAE,CAAC;oBACb,OAAO;wBACL,MAAM,EAAE,KAAK;wBACb,QAAQ,EAAE,GAAG,KAAK,CAAC,IAAI,mBAAmB,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE;qBAC7F,CAAC;gBACJ,CAAC;YACH,CAAC,CAAC,CACH,CAAC;YAEF,MAAM,SAAS,GAAG,YAAY,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC;YAEtD,mDAAmD;YACnD,MAAM,cAAc,GAAe;gBACjC,MAAM,EAAE,MAAM,CAAC,MAAM;gBACrB,QAAQ,EAAE,MAAM,CAAC,QAAQ;gBACzB,QAAQ,EAAE;oBACR,GAAG,CAAC,MAAM,CAAC,QAAQ,IAAI,EAAE,CAAC;oBAC1B,gBAAgB,EAAE,SAAS;oBAC3B,oBAAoB,EAAE,aAAa;oBACnC,aAAa,EAAE,YAAY,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC;wBACzC,IAAI,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,IAAI;wBAC3B,MAAM,EAAE,CAAC,CAAC,MAAM;wBAChB,QAAQ,EAAE,CAAC,CAAC,QAAQ;qBACrB,CAAC,CAAC;iBACJ;aACF,CAAC;YAEF,IAAI,SAAS,EAAE,CAAC;gBACd,OAAO,cAAc,CAAC;YACxB,CAAC;YAED,wBAAwB;YACxB,IAAI,SAAS,KAAK,aAAa,EAAE,CAAC;gBAChC,OAAO;oBACL,MAAM,EAAE,MAAM;oBACd,QAAQ,EAAE,MAAM,CAAC,QAAQ;oBACzB,QAAQ,EAAE,cAAc,CAAC,QAAQ;iBAClC,CAAC;YACJ,CAAC;YAED,2BAA2B;YAC3B,MAAM,YAAY,GAAG,YAAY;iBAC9B,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC;iBACxB,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC;YAE1B,MAAM,WAAW,GAAG,gCAAgC,SAAS,IAAI,aAAa,OAAO,YAAY,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;YAEtI,0BAA0B;YAC1B,YAAY,GAAG;gBACb,GAAG,KAAK;gBACR,YAAY,EAAE;oBACZ,WAAW,EAAE,MAAM,CAAC,QAAQ,IAAI,IAAI;oBACpC,QAAQ,EAAE,WAAW;oBACrB,QAAQ,EAAE,YAAY,CAAC,YAAY,EAAE,QAAQ;iBAC9C;aACF,CAAC;QACJ,CAAC;QAED,iDAAiD;QACjD,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC;IAC5B,CAAC,CAAC;AACJ,CAAC"}

package/dist/state/index.d.ts

@@ -0,0 +1,5 @@
+export { reduce, createEmptyProjection, replayEvents } from './reducer';
+export { FileStorage } from './storage';
+export { MemoryStorage } from './storage-memory';
+export { StateRuntime } from './state-runtime';
+//# sourceMappingURL=index.d.ts.map

package/dist/state/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../state/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,qBAAqB,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AACxE,OAAO,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AACxC,OAAO,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AACjD,OAAO,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC"}

package/dist/state/index.js

@@ -0,0 +1,14 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.StateRuntime = exports.MemoryStorage = exports.FileStorage = exports.replayEvents = exports.createEmptyProjection = exports.reduce = void 0;
+var reducer_1 = require("./reducer");
+Object.defineProperty(exports, "reduce", { enumerable: true, get: function () { return reducer_1.reduce; } });
+Object.defineProperty(exports, "createEmptyProjection", { enumerable: true, get: function () { return reducer_1.createEmptyProjection; } });
+Object.defineProperty(exports, "replayEvents", { enumerable: true, get: function () { return reducer_1.replayEvents; } });
+var storage_1 = require("./storage");
+Object.defineProperty(exports, "FileStorage", { enumerable: true, get: function () { return storage_1.FileStorage; } });
+var storage_memory_1 = require("./storage-memory");
+Object.defineProperty(exports, "MemoryStorage", { enumerable: true, get: function () { return storage_memory_1.MemoryStorage; } });
+var state_runtime_1 = require("./state-runtime");
+Object.defineProperty(exports, "StateRuntime", { enumerable: true, get: function () { return state_runtime_1.StateRuntime; } });
+//# sourceMappingURL=index.js.map

package/dist/state/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../state/index.ts"],"names":[],"mappings":";;;AAAA,qCAAwE;AAA/D,iGAAA,MAAM,OAAA;AAAE,gHAAA,qBAAqB,OAAA;AAAE,uGAAA,YAAY,OAAA;AACpD,qCAAwC;AAA/B,sGAAA,WAAW,OAAA;AACpB,mDAAiD;AAAxC,+GAAA,aAAa,OAAA;AACtB,iDAA+C;AAAtC,6GAAA,YAAY,OAAA"}

package/dist/state/reducer.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Pure projection reducer — folds ExecutionEvents into ExecutionProjection.
+ *
+ * Zero I/O. Exhaustive switch with `never` default. All updates are immutable.
+ */
+import type { ExecutionProjection } from '../src/types';
+import type { ExecutionEvent } from '../src/events';
+export declare function createEmptyProjection(id: string, flowId?: string): ExecutionProjection;
+export declare function reduce(state: ExecutionProjection, event: ExecutionEvent): ExecutionProjection;
+export declare function replayEvents(id: string, events: readonly ExecutionEvent[]): ExecutionProjection;
+//# sourceMappingURL=reducer.d.ts.map

package/dist/state/reducer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reducer.d.ts","sourceRoot":"","sources":["../../state/reducer.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EACV,mBAAmB,EAGpB,MAAM,cAAc,CAAC;AACtB,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAMpD,wBAAgB,qBAAqB,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,mBAAmB,CAetF;AA+CD,wBAAgB,MAAM,CACpB,KAAK,EAAE,mBAAmB,EAC1B,KAAK,EAAE,cAAc,GACpB,mBAAmB,CA2KrB;AAMD,wBAAgB,YAAY,CAC1B,EAAE,EAAE,MAAM,EACV,MAAM,EAAE,SAAS,cAAc,EAAE,GAChC,mBAAmB,CAKrB"}