@obversa/runtime 0.1.0

package/dist/engines/fallback.d.ts

@@ -0,0 +1,35 @@
+/**
+ * A fallback chain over engine instances, tried in declared order.
+ *
+ * Default triggers are auth, billing, missing CLI, unavailable model,
+ * invalid configuration and quota. An engine that reports one of these is
+ * skipped for the rest of this chain's lifetime. Rate limits and transient
+ * failures propagate to the caller. An explicit `on` set replaces the
+ * defaults.
+ *
+ * Aborts never fall back. If every engine fails, the final engine error is
+ * thrown. A subsequent call with every engine skipped reports no live engine.
+ */
+import type { Engine } from './engine.js';
+import { type EngineFailureKind } from './failure.js';
+export interface FallbackInfo {
+    /** The lane that just died. */
+    from: string;
+    /** The lane the call is moving to, when one is left. */
+    to?: string;
+    failure: EngineFailureKind;
+    error: unknown;
+}
+export interface FallbackOptions {
+    /** Failure kinds that trigger fallback. Default: `LANE_DEAD_FAILURES`. */
+    on?: Iterable<EngineFailureKind>;
+    /** Observe each reroute (log it, count it, surface it). */
+    onFallback?: (info: FallbackInfo) => void;
+}
+/**
+ * Build a fallback chain over ready-made `Engine`s, tried in order.
+ *
+ * ```ts
+ * await run(job, { engine: fallbackEngine([claude, codex]) });
+ */
+export declare function fallbackEngine(engines: readonly [Engine, ...Engine[]], options?: FallbackOptions): Engine;

package/dist/engines/message-map.d.ts

@@ -0,0 +1 @@
+export { mapMessage, newAccumulator, type Accumulator, } from '@obversa/core/claude-stream-json';

package/dist/engines/mock.d.ts

@@ -0,0 +1 @@
+export { MockEngine, mockVerdict, type MockResponder, } from '@obversa/core/testing';

package/dist/engines/preflight.d.ts

@@ -0,0 +1,36 @@
+/** One bounded live call through the selected engine, with validated evidence. */
+import { type AgentResult, type AttemptMetadata, type Engine, type EngineIncompleteResultEvidence, type EngineSelectionRecord, type UsageReceipt } from './engine.js';
+import { type EngineFailureKind } from './failure.js';
+export interface PreflightResult {
+    engine: string;
+    model?: string;
+    ok: boolean;
+    /** Set when the probe failed, using the live engine-failure vocabulary. */
+    failure?: EngineFailureKind;
+    /** One line of evidence: the reply, or the error message. */
+    detail: string;
+    latencyMs: number;
+    usage?: UsageReceipt;
+    effective?: EngineSelectionRecord;
+    evidence?: {
+        readonly kind: 'complete';
+        readonly result: Omit<AgentResult, 'raw'>;
+    } | {
+        readonly kind: 'incomplete';
+        readonly result: Omit<EngineIncompleteResultEvidence, 'raw'>;
+    };
+}
+export interface PreflightOptions {
+    model?: string;
+    /** Hard limit on waiting for the probe. Default 60s. */
+    timeoutMs?: number;
+    signal?: AbortSignal;
+    cwd?: string;
+    attempt?: AttemptMetadata;
+}
+/** Probe one engine with a tiny live turn. Failures are returned, not thrown. */
+export declare function preflightEngine(engine: Engine, opts?: PreflightOptions): Promise<PreflightResult>;
+/** Probe several engines concurrently (they are independent lanes). */
+export declare function preflight(engines: readonly Engine[], opts?: PreflightOptions): Promise<PreflightResult[]>;
+/** One line per lane, for terminals and logs. */
+export declare function formatPreflight(result: PreflightResult): string;

package/dist/env/command.d.ts

@@ -0,0 +1,50 @@
+/**
+ * `commandEnvironment` — a generic, CLI-driven Environment. Every IaC tool
+ * (sst, terraform, pulumi, cloudformation-via-aws-cli) has the same shape: a
+ * command to deploy a stage, a command to read its outputs, a command to tear it
+ * down. This factory captures that shape. The consumer supplies the concrete
+ * command configuration.
+ *
+ * It drives the CLIs through the bounded process helper, so it stays in
+ * the Obversa package as an opt-in subpath without coupling
+ * the core to any deploy tool. An SDK-bound adapter (e.g. @aws-sdk) adds a real
+ * dependency and belongs in a separate package or the consumer instead.
+ *
+ * The consumer supplies the tool-specific bits: how a stage name is derived, the
+ * argv for each phase, and `map` (which parsed output is the URL and how the
+ * outputs become the env vars the gate reads). The factory stays tool-agnostic.
+ */
+import type { Workspace } from '../core/types.js';
+import type { Environment } from './environment.js';
+/** A command to run: a binary and its args. */
+export interface Cmd {
+    cmd: string;
+    args?: string[];
+}
+export interface CommandEnvConfig {
+    /** Adapter name (surfaced in errors). Default 'command'. */
+    name?: string;
+    /** Working dir for the commands. Default: the workspace dir (the worktree). */
+    cwd?: (ws: Workspace) => string;
+    /** Stage/stack/workspace identity. Default: a slug of the workspace branch. */
+    stage?: (ws: Workspace) => string;
+    /** Argv to deploy the stage. */
+    deploy: (stage: string, ws: Workspace) => Cmd;
+    /** Argv to read outputs as JSON on stdout. Optional (no URL/env if omitted). */
+    outputs?: (stage: string, ws: Workspace) => Cmd;
+    /** Argv to tear the stage down. */
+    destroy: (stage: string, ws: Workspace) => Cmd;
+    /**
+     * Turn the outputs into the handle's `url` + `env`, normalising the tool's
+     * specific shape. `outputs` is the best-effort JSON parse (for
+     * terraform/pulumi/sst); `raw` is the verbatim stdout (for tools whose output
+     * is not JSON, e.g. `docker compose port` prints `0.0.0.0:49153`).
+     */
+    map?: (outputs: Record<string, unknown>, stage: string, raw: string) => {
+        url?: string;
+        env?: Record<string, string>;
+    };
+    /** Per-command timeout (ms). */
+    timeoutMs?: number;
+}
+export declare function commandEnvironment(config: CommandEnvConfig): Environment;

package/dist/env/command.js

@@ -0,0 +1,65 @@
+import { runRuntimeProcess, processText } from '../chunk-NIBHM5I5.js';
+
+// src/env/command.ts
+function stageSlug(s) {
+  return (s ?? "main").replace(/[^A-Za-z0-9._-]+/g, "-").replace(/(^-+|-+$)/g, "") || "main";
+}
+function parseJson(s) {
+  try {
+    const v = JSON.parse(s);
+    return v && typeof v === "object" && !Array.isArray(v) ? v : {};
+  } catch {
+    return {};
+  }
+}
+function commandEnvironment(config) {
+  const name = config.name ?? "command";
+  const stageOf = config.stage ?? ((ws) => stageSlug(ws.branch));
+  const cwdOf = config.cwd ?? ((ws) => ws.dir);
+  return {
+    name,
+    async up(ws, signal) {
+      const stage = stageOf(ws);
+      const cwd = cwdOf(ws);
+      const exec = async (c, phase) => {
+        const r = await runRuntimeProcess({
+          executable: c.cmd,
+          args: c.args ?? [],
+          cwd,
+          timeoutMs: config.timeoutMs,
+          signal
+        });
+        if (r.exitCode !== 0) {
+          const stderr = processText(r.stderr);
+          const stdout = processText(r.stdout);
+          const detail = (stderr || stdout).slice(0, 500);
+          throw new Error(
+            `${name} ${phase} failed for stage "${stage}" (exit ${r.exitCode}): ${detail}`.trim()
+          );
+        }
+        return processText(r.stdout).replace(/\r?\n$/u, "");
+      };
+      await exec(config.deploy(stage, ws), "deploy");
+      const raw = config.outputs ? await exec(config.outputs(stage, ws), "outputs") : "";
+      const mapped = config.map?.(parseJson(raw), stage, raw) ?? {};
+      return {
+        url: mapped.url,
+        env: mapped.env ?? {},
+        async down(sig) {
+          const d = config.destroy(stage, ws);
+          await runRuntimeProcess({
+            executable: d.cmd,
+            args: d.args ?? [],
+            cwd,
+            timeoutMs: config.timeoutMs,
+            signal: sig
+          });
+        }
+      };
+    }
+  };
+}
+
+export { commandEnvironment };
+//# sourceMappingURL=command.js.map
+//# sourceMappingURL=command.js.map

package/dist/env/command.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/env/command.ts"],"names":[],"mappings":";;;AAwDA,SAAS,UAAU,CAAA,EAA+B;AAChD,EAAA,OAAA,CACG,CAAA,IAAK,QAAQ,OAAA,CAAQ,mBAAA,EAAqB,GAAG,CAAA,CAAE,OAAA,CAAQ,YAAA,EAAc,EAAE,CAAA,IACxE,MAAA;AAEJ;AAEA,SAAS,UAAU,CAAA,EAAoC;AACrD,EAAA,IAAI;AACF,IAAA,MAAM,CAAA,GAAa,IAAA,CAAK,KAAA,CAAM,CAAC,CAAA;AAC/B,IAAA,OAAO,CAAA,IAAK,OAAO,CAAA,KAAM,QAAA,IAAY,CAAC,MAAM,OAAA,CAAQ,CAAC,CAAA,GAChD,CAAA,GACD,EAAC;AAAA,EACP,CAAA,CAAA,MAAQ;AACN,IAAA,OAAO,EAAC;AAAA,EACV;AACF;AAEO,SAAS,mBAAmB,MAAA,EAAuC;AACxE,EAAA,MAAM,IAAA,GAAO,OAAO,IAAA,IAAQ,SAAA;AAC5B,EAAA,MAAM,UAAU,MAAA,CAAO,KAAA,KAAU,CAAC,EAAA,KAAkB,SAAA,CAAU,GAAG,MAAM,CAAA,CAAA;AACvE,EAAA,MAAM,KAAA,GAAQ,MAAA,CAAO,GAAA,KAAQ,CAAC,OAAkB,EAAA,CAAG,GAAA,CAAA;AAEnD,EAAA,OAAO;AAAA,IACL,IAAA;AAAA,IACA,MAAM,EAAA,CAAG,EAAA,EAAe,MAAA,EAAyC;AAC/D,MAAA,MAAM,KAAA,GAAQ,QAAQ,EAAE,CAAA;AACxB,MAAA,MAAM,GAAA,GAAM,MAAM,EAAE,CAAA;AAEpB,MAAA,MAAM,IAAA,GAAO,OAAO,CAAA,EAAQ,KAAA,KAAmC;AAC7D,QAAA,MAAM,CAAA,GAAI,MAAM,iBAAA,CAAkB;AAAA,UAChC,YAAY,CAAA,CAAE,GAAA;AAAA,UACd,IAAA,EAAM,CAAA,CAAE,IAAA,IAAQ,EAAC;AAAA,UACjB,GAAA;AAAA,UACA,WAAW,MAAA,CAAO,SAAA;AAAA,UAClB;AAAA,SACD,CAAA;AACD,QAAA,IAAI,CAAA,CAAE,aAAa,CAAA,EAAG;AACpB,UAAA,MAAM,MAAA,GAAS,WAAA,CAAY,CAAA,CAAE,MAAM,CAAA;AACnC,UAAA,MAAM,MAAA,GAAS,WAAA,CAAY,CAAA,CAAE,MAAM,CAAA;AACnC,UAAA,MAAM,MAAA,GAAA,CAAU,MAAA,IAAU,MAAA,EAAQ,KAAA,CAAM,GAAG,GAAG,CAAA;AAC9C,UAAA,MAAM,IAAI,KAAA;AAAA,YACR,CAAA,EAAG,IAAI,CAAA,CAAA,EAAI,KAAK,CAAA,mBAAA,EAAsB,KAAK,CAAA,QAAA,EAAW,CAAA,CAAE,QAAQ,CAAA,GAAA,EAAM,MAAM,CAAA,CAAA,CAAG,IAAA;AAAK,WACtF;AAAA,QACF;AACA,QAAA,OAAO,YAAY,CAAA,CAAE,MAAM,CAAA,CAAE,OAAA,CAAQ,WAAW,EAAE,CAAA;AAAA,MACpD,CAAA;AAEA,MAAA,MAAM,KAAK,MAAA,CAAO,MAAA,CAAO,KAAA,EAAO,EAAE,GAAG,QAAQ,CAAA;AAC7C,MAAA,MAAM,GAAA,GAAM,MAAA,CAAO,OAAA,GACf,MAAM,IAAA,CAAK,MAAA,CAAO,OAAA,CAAQ,KAAA,EAAO,EAAE,CAAA,EAAG,SAAS,CAAA,GAC/C,EAAA;AACJ,MAAA,MAAM,MAAA,GAAS,OAAO,GAAA,GAAM,SAAA,CAAU,GAAG,CAAA,EAAG,KAAA,EAAO,GAAG,CAAA,IAAK,EAAC;AAE5D,MAAA,OAAO;AAAA,QACL,KAAK,MAAA,CAAO,GAAA;AAAA,QACZ,GAAA,EAAK,MAAA,CAAO,GAAA,IAAO,EAAC;AAAA,QACpB,MAAM,KAAK,GAAA,EAAiC;AAC1C,UAAA,MAAM,CAAA,GAAI,MAAA,CAAO,OAAA,CAAQ,KAAA,EAAO,EAAE,CAAA;AAClC,UAAA,MAAM,iBAAA,CAAkB;AAAA,YACtB,YAAY,CAAA,CAAE,GAAA;AAAA,YACd,IAAA,EAAM,CAAA,CAAE,IAAA,IAAQ,EAAC;AAAA,YACjB,GAAA;AAAA,YACA,WAAW,MAAA,CAAO,SAAA;AAAA,YAClB,MAAA,EAAQ;AAAA,WACT,CAAA;AAAA,QACH;AAAA,OACF;AAAA,IACF;AAAA,GACF;AACF","file":"command.js","sourcesContent":["/**\n * `commandEnvironment` — a generic, CLI-driven Environment. Every IaC tool\n * (sst, terraform, pulumi, cloudformation-via-aws-cli) has the same shape: a\n * command to deploy a stage, a command to read its outputs, a command to tear it\n * down. This factory captures that shape. The consumer supplies the concrete\n * command configuration.\n *\n * It drives the CLIs through the bounded process helper, so it stays in\n * the Obversa package as an opt-in subpath without coupling\n * the core to any deploy tool. An SDK-bound adapter (e.g. @aws-sdk) adds a real\n * dependency and belongs in a separate package or the consumer instead.\n *\n * The consumer supplies the tool-specific bits: how a stage name is derived, the\n * argv for each phase, and `map` (which parsed output is the URL and how the\n * outputs become the env vars the gate reads). The factory stays tool-agnostic.\n */\n\nimport type { Workspace } from '../core/types.js';\nimport type { Environment, EnvHandle } from './environment.js';\nimport { processText, runRuntimeProcess } from '../core/process.js';\n\n/** A command to run: a binary and its args. */\nexport interface Cmd {\n  cmd: string;\n  args?: string[];\n}\n\nexport interface CommandEnvConfig {\n  /** Adapter name (surfaced in errors). Default 'command'. */\n  name?: string;\n  /** Working dir for the commands. Default: the workspace dir (the worktree). */\n  cwd?: (ws: Workspace) => string;\n  /** Stage/stack/workspace identity. Default: a slug of the workspace branch. */\n  stage?: (ws: Workspace) => string;\n  /** Argv to deploy the stage. */\n  deploy: (stage: string, ws: Workspace) => Cmd;\n  /** Argv to read outputs as JSON on stdout. Optional (no URL/env if omitted). */\n  outputs?: (stage: string, ws: Workspace) => Cmd;\n  /** Argv to tear the stage down. */\n  destroy: (stage: string, ws: Workspace) => Cmd;\n  /**\n   * Turn the outputs into the handle's `url` + `env`, normalising the tool's\n   * specific shape. `outputs` is the best-effort JSON parse (for\n   * terraform/pulumi/sst); `raw` is the verbatim stdout (for tools whose output\n   * is not JSON, e.g. `docker compose port` prints `0.0.0.0:49153`).\n   */\n  map?: (\n    outputs: Record<string, unknown>,\n    stage: string,\n    raw: string,\n  ) => { url?: string; env?: Record<string, string> };\n  /** Per-command timeout (ms). */\n  timeoutMs?: number;\n}\n\n/** Slug a branch into a stage-safe identity. */\nfunction stageSlug(s: string | undefined): string {\n  return (\n    (s ?? 'main').replace(/[^A-Za-z0-9._-]+/g, '-').replace(/(^-+|-+$)/g, '') ||\n    'main'\n  );\n}\n\nfunction parseJson(s: string): Record<string, unknown> {\n  try {\n    const v: unknown = JSON.parse(s);\n    return v && typeof v === 'object' && !Array.isArray(v)\n      ? (v as Record<string, unknown>)\n      : {};\n  } catch {\n    return {};\n  }\n}\n\nexport function commandEnvironment(config: CommandEnvConfig): Environment {\n  const name = config.name ?? 'command';\n  const stageOf = config.stage ?? ((ws: Workspace) => stageSlug(ws.branch));\n  const cwdOf = config.cwd ?? ((ws: Workspace) => ws.dir);\n\n  return {\n    name,\n    async up(ws: Workspace, signal: AbortSignal): Promise<EnvHandle> {\n      const stage = stageOf(ws);\n      const cwd = cwdOf(ws);\n\n      const exec = async (c: Cmd, phase: string): Promise<string> => {\n        const r = await runRuntimeProcess({\n          executable: c.cmd,\n          args: c.args ?? [],\n          cwd,\n          timeoutMs: config.timeoutMs,\n          signal,\n        });\n        if (r.exitCode !== 0) {\n          const stderr = processText(r.stderr);\n          const stdout = processText(r.stdout);\n          const detail = (stderr || stdout).slice(0, 500);\n          throw new Error(\n            `${name} ${phase} failed for stage \"${stage}\" (exit ${r.exitCode}): ${detail}`.trim(),\n          );\n        }\n        return processText(r.stdout).replace(/\\r?\\n$/u, '');\n      };\n\n      await exec(config.deploy(stage, ws), 'deploy');\n      const raw = config.outputs\n        ? await exec(config.outputs(stage, ws), 'outputs')\n        : '';\n      const mapped = config.map?.(parseJson(raw), stage, raw) ?? {};\n\n      return {\n        url: mapped.url,\n        env: mapped.env ?? {},\n        async down(sig: AbortSignal): Promise<void> {\n          const d = config.destroy(stage, ws);\n          await runRuntimeProcess({\n            executable: d.cmd,\n            args: d.args ?? [],\n            cwd,\n            timeoutMs: config.timeoutMs,\n            signal: sig,\n          });\n        },\n      };\n    },\n  };\n}\n"]}

package/dist/env/environment.d.ts

@@ -0,0 +1,4 @@
+import type { Environment } from '@obversa/api';
+export type { Environment, EnvHandle, EnvironmentWorkspace } from '@obversa/api';
+/** Duck-type guard: a ready-made `Environment` rather than something else. */
+export declare function isEnvironment(value: unknown): value is Environment;

package/dist/env/mock.d.ts

@@ -0,0 +1,24 @@
+/**
+ * A scripted, offline environment, mirroring `MockEngine`. It simulates a deploy
+ * (hands back a URL + env vars, counts up/down) with no network, so the
+ * lifecycle binding and gate integration run the same code paths in tests as a
+ * real sst/Vercel adapter would.
+ */
+import type { Workspace } from '../core/types.js';
+import type { Environment, EnvHandle } from './environment.js';
+export interface MockEnvOptions {
+    /** The URL to hand back. A function derives it from the workspace (branch). */
+    url?: string | ((ws: Workspace) => string);
+    /** Extra env vars to inject alongside `BASE_URL`. */
+    env?: Record<string, string>;
+    onUp?: (ws: Workspace) => void;
+    onDown?: () => void;
+}
+export declare class MockEnvironment implements Environment {
+    private readonly opts;
+    readonly name = "mock-env";
+    upCount: number;
+    downCount: number;
+    constructor(opts?: MockEnvOptions);
+    up(workspace: Workspace): Promise<EnvHandle>;
+}

package/dist/events/conformance.d.ts

@@ -0,0 +1 @@
+export { runEventStoreConformance, assertEventStoreConformance, type EventStoreConformanceOptions, type EventStoreConformanceFactory, type EventStoreConformanceFailure, type EventStoreConformanceReport, } from '@obversa/api/testing';

package/dist/events/envelope.d.ts

@@ -0,0 +1 @@
+export { validateDomainEventId, validateNewDomainEvent, validateDomainEventEnvelope, type DomainEventId, type EventStreamId, type StorageNamespace, type StreamRevision, type EventStreamRef, type NewDomainEvent, type DomainEventEnvelope, } from '@obversa/api';

package/dist/events/jsonl-store.d.ts

@@ -0,0 +1,8 @@
+import { type EventStore } from './store.js';
+export interface LocalEventStoreOptions {
+    readonly root: string;
+    readonly maxEventPayloadBytes?: number;
+    readonly maxAppendBatchBytes?: number;
+    readonly knownSecrets?: readonly string[];
+}
+export declare function createLocalEventStore(options: LocalEventStoreOptions): EventStore;

package/dist/events/store.d.ts

@@ -0,0 +1 @@
+export { validateStorageId, validateEventStreamRef, validateStreamRevision, validateDomainEventBatch, findKnownSecretInEvents, type DomainEventBatch, type EventStore, } from '@obversa/api';

package/dist/graph/commands.d.ts

@@ -0,0 +1,5 @@
+import type { GraphKernel } from './kernel.js';
+import type { GraphCommand } from '@obversa/api';
+export { type DispatchGraphCommand, type PauseGraphCommand, type CompleteGraphCommand, type FailGraphCommand, type GraphCommand } from '@obversa/api';
+/** Validate one pure graph decision before the runtime can act on it. */
+export declare function validateGraphCommands(commands: readonly GraphCommand[], kernel: GraphKernel): readonly GraphCommand[];

package/dist/graph/conformance.d.ts

@@ -0,0 +1,32 @@
+import type { GraphDefinition } from './kernel.js';
+import type { GraphCommand } from './commands.js';
+import { type GraphBounds, type GraphRequirements, type PlanResolution } from './plan.js';
+import { type GraphEvent, type GraphType } from './type.js';
+import { type JsonValue } from './value.js';
+export interface GraphTypeConformanceFixture<Definition extends GraphDefinition = GraphDefinition, State extends JsonValue = JsonValue, Event extends GraphEvent = GraphEvent, Requirements extends GraphRequirements = GraphRequirements> {
+    readonly graphType: GraphType<Definition, State, Event, Requirements>;
+    readonly definition: Definition;
+    readonly events: readonly Event[];
+    readonly invalidDefinitions: readonly [Definition, ...Definition[]];
+    readonly planResolution: PlanResolution;
+    readonly expected: {
+        /** Initial state followed by the state after each event prefix. */
+        readonly states: readonly [State, ...State[]];
+        /** Ordered decision at the initial state and after each event prefix. */
+        readonly commands: readonly [readonly GraphCommand[], ...(readonly GraphCommand[])[]];
+        readonly bounds: GraphBounds;
+    };
+}
+export interface GraphTypeConformanceFailure {
+    readonly case: string;
+    readonly message: string;
+}
+export interface GraphTypeConformanceReport {
+    readonly ok: boolean;
+    readonly cases: number;
+    readonly failures: readonly GraphTypeConformanceFailure[];
+}
+/** Run the framework-free behavioral checks for an outside graph type. */
+export declare function runGraphTypeConformance<Definition extends GraphDefinition, State extends JsonValue, Event extends GraphEvent, Requirements extends GraphRequirements>(fixture: GraphTypeConformanceFixture<Definition, State, Event, Requirements>): GraphTypeConformanceReport;
+/** Throw one readable error when an outside graph type breaks the contract. */
+export declare function assertGraphTypeConformance<Definition extends GraphDefinition, State extends JsonValue, Event extends GraphEvent, Requirements extends GraphRequirements>(fixture: GraphTypeConformanceFixture<Definition, State, Event, Requirements>): void;

package/dist/graph/kernel.d.ts

@@ -0,0 +1,5 @@
+export { GraphValidationError } from './value.js';
+export type { GraphValidationIssue } from './value.js';
+import type { GraphDefinition, GraphKernel } from '@obversa/api';
+export type { GraphId, NodeId, EdgeId, GraphNode, GraphEdge, GraphDefinition, CompiledGraphDefinition, GraphKernel } from '@obversa/api';
+export declare function createGraphKernel<Definition extends GraphDefinition>(definition: Definition): GraphKernel<Definition>;

package/dist/graph/plan.d.ts

@@ -0,0 +1 @@
+export { type PermissionDescriptor, type ExecutionLaneDescription, type GraphPhaseDescription, type GraphNodeDescription, type GraphEdgeDescription, type PlanBound, type GraphBounds, type GraphPolicyDescription, type GraphRequirements, type GraphDescriptionInput, type GraphDescription, type GraphPackageIdentity, type GraphPackageAdmission, type ExecutionLaneResolution, type RunPreflightPolicy, type PlanResolution, type ResolvedExecutionLane, type ResolvedPlan, type ResolvedPlanSnapshot, validateResolvedPlan, validateGraphDescription, resolveGraphPlan, type ExecutionTarget, } from '@obversa/api';

package/dist/graph/type.d.ts

@@ -0,0 +1,7 @@
+import { type GraphDefinition } from './kernel.js';
+import { type GraphRequirements } from './plan.js';
+import { type JsonValue } from './value.js';
+import type { GraphEvent, CompiledGraphType, GraphType } from '@obversa/api';
+export { type GraphEvent, type GraphEngineIdentity, type EngineAttemptRecordedPayload, type GraphBindings, type GraphTypeCompilation, type CompiledGraphType, type GraphType } from '@obversa/api';
+/** Validate a definition, then compile its trusted graph-type implementation. */
+export declare function compileGraph<Definition extends GraphDefinition, State extends JsonValue, Event extends GraphEvent, Requirements extends GraphRequirements>(graphType: GraphType<Definition, State, Event, Requirements>, definition: Definition): CompiledGraphType<Definition, State, Event, Requirements>;

package/dist/graph/value.d.ts

@@ -0,0 +1 @@
+export { GraphValidationError, type GraphValidationIssue, type RunBrief, JsonValueError, canonicalJson, cloneFrozenJson, digestJson, type JsonObject, type JsonPrimitive, type JsonValue, type Sha256Digest, } from '@obversa/api';

package/dist/graph-types/dag.d.ts

@@ -0,0 +1,137 @@
+/**
+ * The DAG graph type (roadmap D6): dependency graphs, sequences, parallel
+ * work, and readable pipelines on the common graph contract.
+ *
+ * One node is one DAG node; edges are dependencies (source must finish
+ * before target runs). Required, optional, and finalizer kinds carry the
+ * legacy failure policy: a required node failing blocks its dependents and
+ * fails the run; an optional failure neither fails the run nor blocks
+ * dependents; a completed node whose result carries `skipped: true` counts
+ * as an expected skip, which is neutral and never blocks (the legacy unmet
+ * `when` gate). With `stopOnError`, the first required failure stops
+ * scheduling anything not already in flight; independent branches continue
+ * without it. Finalizers run after everything else settles, on failure as
+ * on success, and can never turn a failed run green.
+ *
+ * This is the pure form only: definition validation (including cycle
+ * detection through the pinned `toposort`), state reduction, decisions,
+ * bounds, and the plan description. Job execution, isolation, kickbacks,
+ * and the sequence/parallel/pipeline authoring helpers are the runtime
+ * owner's; this file only folds the standard node events and decides what
+ * can run next.
+ *
+ * Event vocabulary (all JSON, the executor's standard node events, recorded
+ * into the durable `graph:` namespace):
+ * - `node-dispatched` — a node attempt started at a position
+ * - `node-completed`  — a node attempt finished; a result carrying
+ *   `skipped: true` is an expected skip
+ * - `node-failed`     — a node attempt failed with a typed code
+ * - `node-paused`     — a node attempt paused; the DAG waits
+ * - `node-resumed`    — a paused node continues its attempt
+ *
+ * A dispatch, completion, or failure counts only for the node's attempt
+ * currently in flight at that exact position; a stale event from an earlier
+ * attempt is ignored. Positions are minted as `dag/${node}/${attempt}` where
+ * the attempt number is the count of recorded dispatches for that node, so
+ * every retry takes a fresh position. Retry is graph policy, declared as a
+ * per-node cap: decide offers a fresh dispatch for a failed required node
+ * while the cap allows, stopOnError suppresses retries as it stops
+ * scheduling, and the DAG fails a node only once its cap is exhausted. A
+ * late result for a superseded attempt is ignored.
+ *
+ * A paused node pauses the whole DAG, as the legacy scheduler does. The form
+ * first waits for every other attempt in the recorded batch to settle, then
+ * returns the pause command. A resumed node continues the same attempt.
+ *
+ * Each decision waits for every recorded attempt to settle, then dispatches
+ * one ready batch that fits the global and keyed limits in declaration order.
+ * Positions stay unique across the run; the form never re-emits a dispatch
+ * for an attempt already recorded in the folded event history. Each dispatch
+ * carries the named results of its direct predecessors. Completion returns
+ * every completed node result by node name.
+ */
+import type { GraphDefinition, NodeId } from '../graph/kernel.js';
+import type { GraphEvent, GraphType } from '../graph/type.js';
+import { type JsonObject, type JsonValue } from '../graph/value.js';
+export type DagNodeKind = 'required' | 'optional' | 'finalizer';
+type DagExecutionTargetData = {
+    readonly adapter: string;
+    readonly provider: string;
+    readonly modelFamily: string;
+    readonly model: string;
+    readonly tools: readonly string[];
+};
+type DagExecutionLaneData = {
+    readonly id: string;
+    readonly requested: DagExecutionTargetData;
+    readonly knownSubstitutions: readonly DagExecutionTargetData[];
+};
+export type DagNodeData = JsonObject & {
+    readonly kind: DagNodeKind;
+    /** Concurrency key; nodes sharing a key share its declared limit. */
+    readonly key: string | null;
+    /** Engine lane for this node; omit it for a data-only node. */
+    readonly lane?: DagExecutionLaneData;
+};
+export interface DagEdgeData extends JsonObject {
+}
+export interface DagData extends JsonObject {
+    /** Max node attempts running at once. The legacy default is 4. */
+    readonly globalConcurrency: number;
+    /** Per-key attempt caps; every node key must appear here. */
+    readonly keyedConcurrency: Readonly<Record<string, number>>;
+    /** When true, the first required failure stops scheduling anything not in flight. */
+    readonly stopOnError: boolean;
+    /** Retries offered per failed required node before the DAG fails. */
+    readonly retryCapPerNode: number;
+}
+export type DagDefinition = GraphDefinition<DagNodeData, DagEdgeData, DagData>;
+export interface NodeDispatchedPayload extends JsonObject {
+    readonly nodeId: NodeId;
+    readonly position: string;
+}
+export interface NodeCompletedPayload extends JsonObject {
+    readonly nodeId: NodeId;
+    readonly position: string;
+    readonly result: JsonValue;
+}
+export interface NodeFailedPayload extends JsonObject {
+    readonly nodeId: NodeId;
+    readonly position: string;
+    readonly code: string;
+}
+export interface NodePausedPayload extends JsonObject {
+    readonly nodeId: NodeId;
+    readonly position: string;
+    readonly reason: string;
+    readonly request: JsonValue;
+}
+export interface NodeResumedPayload extends JsonObject {
+    readonly nodeId: NodeId;
+    readonly position: string;
+}
+export type DagEvent = GraphEvent<'node-dispatched', NodeDispatchedPayload> | GraphEvent<'node-completed', NodeCompletedPayload> | GraphEvent<'node-failed', NodeFailedPayload> | GraphEvent<'node-paused', NodePausedPayload> | GraphEvent<'node-resumed', NodeResumedPayload>;
+export type DagNodeStatus = 'pending' | 'in-flight' | 'paused' | 'passed' | 'skipped' | 'failed';
+export interface DagNodeState extends JsonObject {
+    readonly status: DagNodeStatus;
+    /** Recorded dispatch count; the source of fresh attempt positions. */
+    readonly attempts: number;
+    /** The in-flight attempt position, or null. */
+    readonly inFlight: string | null;
+    /** The reason supplied by a paused attempt, or null. */
+    readonly pauseReason: string | null;
+    /** The completed payload, or null before a successful completion. */
+    readonly result: JsonValue;
+}
+export interface DagStatus extends JsonObject {
+    readonly nodes: Readonly<Record<NodeId, DagNodeState>>;
+}
+export type DagRequirements = {
+    readonly memory: 'unused';
+};
+/**
+ * The DAG graph type. Pure data operations only: no file, model, process,
+ * clock, or storage services (the D2 contract).
+ */
+export declare const dag: GraphType<DagDefinition, DagStatus, DagEvent, DagRequirements>;
+export {};