@jarenjs/flow 0.75.0 → 0.83.3

package/README.md

@@ -1,5 +1,7 @@
 # @jarenjs/flow
 
+Complete ingestion and durable domain runs reuse the existing workflow engine and injected persistence/job fences. See the [combined adoption recipe](../../docs/ADOPTION-EVIDENCE.md) for restart and no-op proofs; real provider read-back and operator reconciliation remain host responsibilities.
+
 Executable JSON workflows: flat FSMs, statecharts, DAGs, and a composition
 compiler that combines long-lived control with concurrent work regions.
 The **jaren-fsm 0.1 format**
@@ -345,3 +347,10 @@ Every subpath a consumer can import, derived from the manifest by
 Unit tests live in `test/flow/` at the repository root
 (`npm run test:flow`). See the repository [README](../../README.md) for
 the full suite documentation.
+
+Bounded provider ingestion composes the workflow engine with injected page and
+transaction capabilities. `createIngestion` resumes source/version/partition
+checkpoints and publishes only complete coverage; see the
+[ingestion contract](docs/WORKFLOW-FORMAT.md#complete-provider-ingestion).
+Run-scoped `resources` reach tasks separately from JSON checkpoints and drain
+before release.

package/dist/types/dag.d.ts

@@ -47,6 +47,7 @@ export type CompiledDag = {
         onNode?: (record: DagNodeRecord) => void;
         runId?: string;
         drainOnAbort?: boolean;
+        resources?: unknown;
     }) => Promise<any>;
 };
 /**
@@ -56,8 +57,8 @@ export type CompiledDag = {
  * registry resolution — `run` only executes closures.
  *
  * @param {any} doc - the jaren-dag document
- * @param {{ tasks?: Record<string, ((props: { with: any, input: any }, signal: AbortSignal) => any)
- *     | { run: (props: { with: any, input: any }, signal: AbortSignal) => any, version?: string,
+ * @param {{ tasks?: Record<string, ((props: { with: any, input: any }, signal: AbortSignal, resources?: any) => any)
+ *     | { run: (props: { with: any, input: any }, signal: AbortSignal, resources?: any) => any, version?: string,
  *         taskVersions?: Record<string, string> }>,
  *   checkpoint?: DagCheckpointStore, revision?: string }} [options]
  * @returns {CompiledDag}
@@ -70,11 +71,11 @@ export declare function compileDag(doc: any, options?: {
     tasks?: Record<string, ((props: {
         with: any;
         input: any;
-    }, signal: AbortSignal) => any) | {
+    }, signal: AbortSignal, resources?: any) => any) | {
         run: (props: {
             with: any;
             input: any;
-        }, signal: AbortSignal) => any;
+        }, signal: AbortSignal, resources?: any) => any;
         version?: string;
         taskVersions?: Record<string, string>;
     }>;

package/dist/types/effects.d.ts

@@ -0,0 +1,25 @@
+/**
+ * The provider executor is single-attempt for this composition. Its dispatch
+ * hook persists intent after scheduling/authority checks and before transport.
+ * Every ambiguous result stays unresolved; read-back/operator reconciliation is
+ * explicit. A new worker may inspect the record but cannot blindly resend it.
+ * @param {{ store: any, executor: any, authorize: Function, classify: Function }} options
+ */
+export declare function createExternalEffects(options: {
+    store: any;
+    executor: any;
+    authorize: Function;
+    classify: Function;
+}): Readonly<{
+    run: (id: string, resources: {
+        lease: any;
+        signal?: AbortSignal;
+    }) => Promise<any>;
+    /** Existing queue worker binding. Unresolved/refused operations pause in the
+     * queue's cancelled state, which can be explicitly requeued for reconciliation.
+     * They must not become completed jobs whose identity cannot be claimed again.
+     * @param {{ operationId: string }} payload @param {any} context */
+    handler(payload: {
+        operationId: string;
+    }, context: any): Promise<any>;
+}>;

package/dist/types/index.d.ts

@@ -9,6 +9,7 @@ export { fsmToApp, fsmStateSchema } from './app.js';
 export { compileDag } from './dag.js';
 export { compileStatechart, createStatechartSession } from './statechart.js';
 export { lowerWorkflow, compileWorkflow } from './workflow.js';
+export { createIngestion } from './ingest.js';
 export { snapshotFsm, resumeFsmSession, createDurableFsmSession } from './persist.js';
 export { FlowCompileError, FlowRuntimeError, FLOW_CODES } from './errors.js';
 export type StatechartState = import('./statechart.js').StatechartState;
@@ -27,3 +28,5 @@ export type CompiledWorkflow = import('./workflow.js').CompiledWorkflow;
 /** @typedef {import('./workflow.js').WorkflowStore} WorkflowStore */
 /** @typedef {import('./workflow.js').WorkflowResult} WorkflowResult */
 /** @typedef {import('./workflow.js').CompiledWorkflow} CompiledWorkflow */
+export { createExternalEffects } from './effects.js';
+export { createDomainRun } from './runs.js';

package/dist/types/ingest.d.ts

@@ -0,0 +1,48 @@
+export type IngestionPlan = {
+    source: string;
+    version: string;
+    generation: string;
+    partitions: string[];
+    input: any;
+    policyRevision: string;
+    consistency: 'snapshot' | 'revision';
+};
+/**
+ * @typedef {{ source: string, version: string, generation: string,
+ * partitions: string[], input: any, policyRevision: string,
+ * consistency: 'snapshot' | 'revision' }} IngestionPlan
+ */
+/**
+ * Compose the existing workflow engine with bounded provider pages and atomic
+ * staging. source(plan, phase) proves either a stable source snapshot or a
+ * monotonic source revision. Local generation numbers are never that proof.
+ * @param {{ provider: { pages: (input: any, context: any) => AsyncIterable<any> },
+ * store: { begin: Function, stage: Function, invalidate: Function, publish: Function },
+ * source: (plan: IngestionPlan, phase: string) => any,
+ * maxPartitions?: number, maxPages?: number, maxRows?: number, maxBytes?: number }} options
+ */
+export declare function createIngestion(options: {
+    provider: {
+        pages: (input: any, context: any) => AsyncIterable<any>;
+    };
+    store: {
+        begin: Function;
+        stage: Function;
+        invalidate: Function;
+        publish: Function;
+    };
+    source: (plan: IngestionPlan, phase: string) => any;
+    maxPartitions?: number;
+    maxPages?: number;
+    maxRows?: number;
+    maxBytes?: number;
+}): Readonly<{
+    /** @param {IngestionPlan} plan
+     * @param {{ executor: any, authority?: any, signal?: AbortSignal, deadline?: number }} resources */
+    run(plan: IngestionPlan, resources: {
+        executor: any;
+        authority?: any;
+        signal?: AbortSignal;
+        deadline?: number;
+    }): Promise<any>;
+}>;

package/dist/types/runs.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Bind one compiled workflow to mapped run/checkpoint persistence. Leases are
+ * the existing queue's capabilities; resources stay private and release only
+ * after tasks drain and final cancellation/failure observation is persisted.
+ * @param {any} document @param {{ store: any, schemaVersion: string, tasks?: any }} options
+ */
+export declare function createDomainRun(document: any, options: {
+    store: any;
+    schemaVersion: string;
+    tasks?: any;
+}): Readonly<{
+    /** @param {string} id @param {any} input @param {{ lease: any, signal?: AbortSignal, release?: Function, event?: any, [key: string]: any }} resources */
+    run(id: string, input: any, resources: {
+        lease: any;
+        signal?: AbortSignal;
+        release?: Function;
+        event?: any;
+        [key: string]: any;
+    }): Promise<import("./workflow.js").WorkflowResult>;
+    /** Cancellation authority is checked by the host's command. Navigation must
+     * detach observation, not call this method. Remote workers see durable intent
+     * at the next checkpoint; local workers abort and drain before this resolves.
+     * @param {string} id @param {number} revision @param {{ actor: string, reason: string }} evidence */
+    cancel(id: string, revision: number, evidence: {
+        actor: string;
+        reason: string;
+    }): Promise<any>;
+}>;

package/dist/types/workflow.d.ts

@@ -73,6 +73,7 @@ export type WorkflowRunOptions = {
     snapshot?: any;
     expectedGeneration?: number;
     signal?: AbortSignal;
+    resources?: unknown;
     now?: number;
     event?: {
         type: string;
@@ -83,7 +84,7 @@ export type WorkflowRunOptions = {
 /** @typedef {{ load: (runId: string) => WorkflowSnapshot | null | Promise<WorkflowSnapshot | null>,
  * save: (runId: string, snapshot: WorkflowSnapshot, expectedGeneration: number) => boolean | Promise<boolean> }} WorkflowStore */
 /** @typedef {{ runId: string, snapshot?: any, expectedGeneration?: number,
- * signal?: AbortSignal, now?: number, event?: {type: string, payload?: any},
+ * signal?: AbortSignal, resources?: unknown, now?: number, event?: {type: string, payload?: any},
  * onTrace?: (record: any) => void }} WorkflowRunOptions */
 /** Compile once; each run owns its control and checkpoint records.
  * Store save MUST atomically compare expectedGeneration (0 means absent).

package/docs/WORKFLOW-FORMAT.md

@@ -258,3 +258,95 @@ review/retry, plus general task/choice/loop/nesting/wait, failure/resume,
 checkpoint reuse, generation races, changed identities, cancellation and
 schema/compiler agreement. Streaming input, graphical editing, action-document
 awaiting and domain orchestration projections are separate contracts.
+
+## Complete provider ingestion
+
+`createIngestion({provider,store,source,maxPartitions?,maxPages?,maxRows?,maxBytes?})`
+compiles one workflow over injected capabilities. It imports no provider or
+persistence package. `provider.pages(input,context)` supplies bounded pages;
+`store.begin/stage/invalidate/publish` supplies atomic persistence. The public
+implementations are `compileProvider` from `@jarenjs/contract/provider` and
+`createDbIngestionStore` from `@jarenjs/linq/db`.
+
+```js
+import { createIngestion } from '@jarenjs/flow';
+
+const ingestion = createIngestion({ provider, store,
+  source: async (plan, phase) => readSourceEvidence(plan, phase),
+  maxPartitions: 8, maxPages: 32, maxRows: 4096, maxBytes: 1048576,
+});
+const result = await ingestion.run({
+  source: 'inventory/test', version: 'source-snapshot-1', generation: 'pull-1',
+  partitions: ['north', 'south'], input: {}, policyRevision: 'policy-1',
+  consistency: 'snapshot',
+}, { executor: providerRun, authority: providerRun, signal: providerRun.signal });
+```
+
+A plan has a source identity, source version, local generation, unique requested
+partitions, JSON input and reconciliation policy revision. `consistency` is
+`snapshot` (an upstream stable snapshot) or `revision` (an upstream monotonic
+revision which changes with every relevant source mutation). The injected source
+check returns `{version,consistency}` at start, after each page and before
+publication. It must report actual upstream evidence, not echo local generation
+numbers. Each page's version must match. A changed source invalidates staging;
+a host may start a fresh generation after obtaining fresh source evidence.
+
+The iterator resumes each unfinished partition from its committed continuation.
+It waits for a page to commit before requesting another. No network request
+holds a database transaction. Default aggregate limits are 64 partitions, 64
+pages, 65536 rows and 16777216 bytes; counts include prior committed pages on
+resume. The descriptor's page limits additionally bound an individual iterator.
+An interrupted pull retains staging; failed/partial partitions never publish a
+complete pointer. Pages reporting partial errors retain their exact raw wire
+text and cannot complete a partition. Source-invalid pages within limits remain
+inspectable but cannot certify completion.
+
+Publication checks source and optional current authority again. For private
+runs pass the same `withProviderRun` capability as executor and authority;
+its publication gate suppresses callbacks after cancellation or revocation.
+Returning `unchanged` requires matching source version, input, requested
+partitions, consistency and policy revision, and produces zero fact writes or
+revisions without requesting another page. A new source or policy revision
+stages a new generation. The store owns transactional recovery; application
+policy owns reconciliation, retention and downstream cutover.
+
+DAG and workflow run options accept `resources` separately from JSON input.
+Task handlers receive `(props, signal, resources)`; resources never participate
+in checkpoint serialization, replay identity or trace output. A resource-bearing
+run drains tasks on abort before settling so the caller can release its lease.
+Tasks must return JSON results and keep resource handles out of their output.
+
+## Domain run and external-effect adoption
+
+`createExternalEffects({ store, executor, authorize, classify })` composes the
+existing workflow engine with a mapped effect store and the public provider
+executor. `run(operationId, { lease, signal? })` reads the reviewed plan,
+reauthorizes resume and dispatch, and persists sending intent from the executor's
+`beforeDispatch` hook. This runs after scheduler admission, immediately before
+transport. A private one-attempt budget prevents executor retries from escaping
+the durable per-leg budget. Only validated successful provider responses passed
+through the host's `classify(response, plannedLeg)` become confirmed/rejected
+public evidence. Timeout, abort, disconnect, invalid response or lost settlement
+remain unresolved. Restart recovers stale sending intent without resending it.
+Read-back and operator decisions use the store's explicit `reconcile` method.
+Register `effects.handler` with the existing queue worker to pause unresolved or
+refused operations in the queue's cancelled state. Explicit requeue/claim then
+provides a fresh reconciliation fence; confirmed operations complete normally.
+
+`createDomainRun(document, { store, schemaVersion, tasks })` compiles the existing
+workflow once and binds its checkpoint CAS to application run records.
+`run(id, input, { lease, signal?, event?, release?, ...resources })` preserves the
+application run ID. `lease` may be a capability or a function returning the
+worker's current renewed lease. Checkpoint provenance includes the canonical
+workflow/schema identity and the engine's input/task-version identity.
+
+`cancel(id, observedRevision, { actor, reason })` records explicit cancellation
+intent, stops local task admission, signals and drains local workers, and waits
+for their final observation and resource release. Remote workers see the durable
+cancellation at the next checkpoint/admission boundary; a remote cancel request
+may therefore return pending intent rather than completed cancellation. The
+requesting contract must authorize the actor. A signal alone also requires
+workers to drain; failed/cancelled observations use fixed public statuses without
+raw exception messages. Attaching an observer is independent of starting/cancelling
+a run. Reset is a separate, explicitly guarded store operation and cannot erase
+business receipts or unresolved effects.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@jarenjs/flow",
   "private": false,
-  "version": "0.75.0",
+  "version": "0.83.3",
   "type": "module",
   "main": "./src/index.js",
   "types": "./dist/types/index.d.ts",
@@ -49,7 +49,7 @@
     "prepack": "npm run build:types"
   },
   "dependencies": {
-    "@jarenjs/core": "^0.75.0",
-    "@jarenjs/json": "^0.75.0"
+    "@jarenjs/core": "^0.83.3",
+    "@jarenjs/json": "^0.83.3"
   }
 }

package/src/dag.js

@@ -71,7 +71,7 @@ function compileEmbedded(compile, embedded, docPath) {
  *   declared task identity this workflow depends on, keyed by node id and
  *   SORTED (§7.8); a nested workflow's map composes under its node's
  *   path. Empty when no node declares a version.
- * @property {(input?: any, opts?: { signal?: AbortSignal, onNode?: (record: DagNodeRecord) => void, runId?: string, drainOnAbort?: boolean }) => Promise<any>} run -
+ * @property {(input?: any, opts?: { signal?: AbortSignal, onNode?: (record: DagNodeRecord) => void, runId?: string, drainOnAbort?: boolean, resources?: unknown }) => Promise<any>} run -
  *   Execute the graph for one input (`undefined` reads as `null`).
  */
 
@@ -121,8 +121,8 @@ function normalizeTaskEntry(entry, name) {
  * registry resolution — `run` only executes closures.
  *
  * @param {any} doc - the jaren-dag document
- * @param {{ tasks?: Record<string, ((props: { with: any, input: any }, signal: AbortSignal) => any)
- *     | { run: (props: { with: any, input: any }, signal: AbortSignal) => any, version?: string,
+ * @param {{ tasks?: Record<string, ((props: { with: any, input: any }, signal: AbortSignal, resources?: any) => any)
+ *     | { run: (props: { with: any, input: any }, signal: AbortSignal, resources?: any) => any, version?: string,
  *         taskVersions?: Record<string, string> }>,
  *   checkpoint?: DagCheckpointStore, revision?: string }} [options]
  * @returns {CompiledDag}
@@ -413,7 +413,7 @@ export function compileDag(doc, options) {
       throw new TypeError(
         'run: a checkpointed dag needs a non-empty string "runId" to persist under');
     }
-    return execute(input === undefined ? null : input, signal, onNode, runId, opts?.drainOnAbort === true);
+    return execute(input === undefined ? null : input, signal, onNode, runId, opts?.drainOnAbort === true || opts?.resources !== undefined, opts?.resources);
   }
 
   /**
@@ -422,8 +422,9 @@ export function compileDag(doc, options) {
    * @param {((record: DagNodeRecord) => void)|undefined} onNode
    * @param {string|undefined} runId
    * @param {boolean} drainOnAbort
+   * @param {unknown} resources - host-private, never part of input/checkpoint identity
    */
-  async function execute(runInput, signal, onNode, runId, drainOnAbort) {
+  async function execute(runInput, signal, onNode, runId, drainOnAbort, resources) {
     const controller = new AbortController();
     /** @type {FlowRuntimeError|null} */
     let failure = null;
@@ -566,7 +567,7 @@ export function compileDag(doc, options) {
               with: node.with === null ? null : node.with(scope) ?? null,
               input: scope,
             };
-            value = (await node.handler(props, controller.signal)) ?? null;
+            value = (await node.handler(props, controller.signal, resources)) ?? null;
             break;
           }
           default: value = null; break;

package/src/effects.js

@@ -0,0 +1,77 @@
+//@ts-check
+/** External effects orchestrate existing workflows, provider admission and fenced storage. */
+import { deepFreeze } from '@jarenjs/core/object';
+import { compileWorkflow } from './workflow.js';
+
+/**
+ * The provider executor is single-attempt for this composition. Its dispatch
+ * hook persists intent after scheduling/authority checks and before transport.
+ * Every ambiguous result stays unresolved; read-back/operator reconciliation is
+ * explicit. A new worker may inspect the record but cannot blindly resend it.
+ * @param {{ store: any, executor: any, authorize: Function, classify: Function }} options
+ */
+export function createExternalEffects(options) {
+  if (!options || typeof options.executor?.execute !== 'function' || typeof options.authorize !== 'function'
+    || typeof options.classify !== 'function' || ['get', 'begin', 'settle', 'recover'].some((name) => typeof options.store?.[name] !== 'function'))
+    throw new TypeError('external effects need a fenced store, provider executor, authorization and evidence classifier');
+  const { store, executor, authorize, classify } = options;
+  const workflow = compileWorkflow({ $workflow: '0.2', revision: 'external-effects/1', initial: 'send', states: {
+    send: { work: { task: 'send', version: '1' }, then: 'done' }, done: { final: true },
+  } }, { tasks: { send: { version: '1', run: async ({ input }, signal, resources) => {
+    const lease = () => typeof resources.lease === 'function' ? resources.lease() : resources.lease;
+    let record = await store.get(input.id);
+    if (await authorize(deepFreeze(record.plan), 'resume', resources) !== true) return { state: 'refused', reason: 'unauthorized' };
+    record = (await store.recover(record.id, record.revision, lease())).record;
+    deepFreeze(record.plan);
+    for (const planned of record.plan.legs) {
+      const leg = record.legs.find((value) => value.id === planned.id);
+      if (leg.state === 'confirmed' || leg.state === 'rejected') continue;
+      if (signal.aborted) return { state: 'cancelled', revision: record.revision };
+      if (leg.state === 'unresolved') return { state: 'unresolved', revision: record.revision, leg: leg.id };
+      let started = false, used = 0;
+      const budget = { safety: planned.request.safety, get used() { return used; }, get remaining() { return 1 - used; }, take: () => used++ === 0 };
+      let response;
+      try {
+        response = await executor.execute(planned.request, { signal, budget, beforeDispatch: async () => {
+          if (started || await authorize(deepFreeze(record.plan), 'dispatch', resources) !== true) return false;
+          const intent = await store.begin(record.id, planned.id, record.revision, lease());
+          if (intent.state !== 'sending' || intent.writes !== 1) return false;
+          record = intent.record;
+          started = true;
+          return true;
+        } });
+      }
+      catch { response = { state: 'unresolved' }; }
+      if (!started) return { state: 'refused', reason: 'not-admitted', revision: record.revision };
+      let outcome = { state: 'unresolved', evidence: { reason: 'unconfirmed' } };
+      if (!signal.aborted && response.state === 'ok') {
+        try {
+          const observed = await classify(response, planned);
+          if (observed && ['confirmed', 'rejected'].includes(observed.state) && Object.hasOwn(observed, 'evidence')) outcome = observed;
+        }
+        catch { /* malformed or unvalidated remote evidence remains unresolved */ }
+      }
+      record = (await store.settle(record.id, planned.id, record.revision, lease(), outcome)).record;
+      if (outcome.state === 'unresolved') return { state: 'unresolved', revision: record.revision, leg: planned.id };
+    }
+    return { state: 'complete', revision: record.revision, legs: record.legs.map(({ id, state }) => ({ id, state })) };
+  } } } });
+  /** @param {string} id @param {{ lease: any, signal?: AbortSignal }} resources */
+  async function run(id, resources) {
+    const result = await workflow.run({ id }, { runId: id, resources, signal: resources.signal });
+    return result.result;
+  }
+  return Object.freeze({
+    run,
+    /** Existing queue worker binding. Unresolved/refused operations pause in the
+     * queue's cancelled state, which can be explicitly requeued for reconciliation.
+     * They must not become completed jobs whose identity cannot be claimed again.
+     * @param {{ operationId: string }} payload @param {any} context */
+    async handler(payload, context) {
+      if (typeof context?.pause !== 'function') throw new TypeError('external handler needs a job worker pause capability');
+      const result = await run(payload.operationId, context);
+      if (result.state !== 'complete') await context.pause();
+      return result;
+    },
+  });
+}

package/src/index.js

@@ -11,6 +11,7 @@ export { fsmToApp, fsmStateSchema } from './app.js';
 export { compileDag } from './dag.js';
 export { compileStatechart, createStatechartSession } from './statechart.js';
 export { lowerWorkflow, compileWorkflow } from './workflow.js';
+export { createIngestion } from './ingest.js';
 export { snapshotFsm, resumeFsmSession, createDurableFsmSession } from './persist.js';
 export { FlowCompileError, FlowRuntimeError, FLOW_CODES } from './errors.js';
 
@@ -22,3 +23,5 @@ export { FlowCompileError, FlowRuntimeError, FLOW_CODES } from './errors.js';
 /** @typedef {import('./workflow.js').WorkflowStore} WorkflowStore */
 /** @typedef {import('./workflow.js').WorkflowResult} WorkflowResult */
 /** @typedef {import('./workflow.js').CompiledWorkflow} CompiledWorkflow */
+export { createExternalEffects } from './effects.js';
+export { createDomainRun } from './runs.js';

package/src/ingest.js

@@ -0,0 +1,104 @@
+//@ts-check
+/** Resumable complete ingestion over injected provider and transaction stores. */
+import { canonicalizeJson } from '@jarenjs/json/canonical';
+import { compileWorkflow } from './workflow.js';
+
+/**
+ * @typedef {{ source: string, version: string, generation: string,
+ * partitions: string[], input: any, policyRevision: string,
+ * consistency: 'snapshot' | 'revision' }} IngestionPlan
+ */
+
+/**
+ * Compose the existing workflow engine with bounded provider pages and atomic
+ * staging. source(plan, phase) proves either a stable source snapshot or a
+ * monotonic source revision. Local generation numbers are never that proof.
+ * @param {{ provider: { pages: (input: any, context: any) => AsyncIterable<any> },
+ * store: { begin: Function, stage: Function, invalidate: Function, publish: Function },
+ * source: (plan: IngestionPlan, phase: string) => any,
+ * maxPartitions?: number, maxPages?: number, maxRows?: number, maxBytes?: number }} options
+ */
+export function createIngestion(options) {
+  if (!options || typeof options.provider?.pages !== 'function' || typeof options.source !== 'function'
+    || ['begin', 'stage', 'invalidate', 'publish'].some((name) => typeof options.store?.[name] !== 'function'))
+    throw new TypeError('ingestion needs provider pages, source evidence and an atomic staging store');
+  const { provider, store, source, maxPartitions = 64, maxPages = 64, maxRows = 65536, maxBytes = 16777216 } = options;
+  for (const value of [maxPartitions, maxPages, maxRows, maxBytes]) if (!Number.isSafeInteger(value) || value < 1) throw new TypeError('ingestion limits must be positive finite integers');
+  const workflow = compileWorkflow({ $workflow: '0.2', revision: 'ingestion/1', initial: 'pull', states: {
+    pull: { work: { task: 'ingest', version: '1' }, then: 'done' }, done: { final: true },
+  } }, { tasks: { ingest: { version: '1', run: async ({ input: plan }, signal, resources) => {
+    const incomplete = (reason) => ({ state: 'incomplete', reason, changes: 0, writes: 0, revisions: 0 });
+    const proof = async (phase) => {
+      const evidence = await source(plan, phase);
+      return !signal.aborted && evidence?.version === plan.version && evidence.consistency === plan.consistency
+        ? { version: evidence.version, consistency: evidence.consistency } : null;
+    };
+    let evidence = await proof('start');
+    if (!evidence) return incomplete('source-changed');
+    if (resources.authority && !await resources.authority.check()) return incomplete('authority-changed');
+    const begun = await store.begin(plan);
+    if (begun.state !== 'staging') return begun;
+    let checkpoint = begun.checkpoint;
+    for (const partition of plan.partitions) {
+      const saved = checkpoint.partitions.find((part) => part.id === partition);
+      if (saved.complete) continue;
+      let complete = false;
+      const pages = provider.pages(plan.input, { executor: resources.executor, signal, partition,
+        sourceVersion: plan.version, cursor: saved.cursor, deadline: resources.deadline });
+      try {
+        for await (const page of pages) {
+          if (signal.aborted) return incomplete('cancelled');
+          if (page.state !== 'page') {
+            if (page.state !== 'complete') return incomplete(page.reason);
+            complete = true;
+            continue;
+          }
+          // Network has settled before entering stage's transaction. The exact
+          // raw wire text remains beside compiled observations in that commit.
+          evidence = await proof('page');
+          if (!evidence || page.version !== plan.version) {
+            if (checkpoint.pages + 1 <= maxPages && checkpoint.rows + page.rows.length <= maxRows && checkpoint.bytes + page.bytes <= maxBytes)
+              await store.stage(plan, partition, { ...page, complete: false, reason: 'source-changed' });
+            await store.invalidate(plan, 'source-changed');
+            return incomplete('source-changed');
+          }
+          if (checkpoint.pages + 1 > maxPages || checkpoint.rows + page.rows.length > maxRows || checkpoint.bytes + page.bytes > maxBytes)
+            return incomplete('ingestion-limit');
+          if (resources.authority && !await resources.authority.check()) return incomplete('authority-changed');
+          const staged = await store.stage(plan, partition, page);
+          if (staged.state !== 'staged') return incomplete(staged.reason);
+          checkpoint = staged.checkpoint;
+          if (page.reason !== null) return incomplete(page.reason);
+        }
+      }
+      catch {
+        if (signal.aborted) return incomplete('cancelled');
+        return incomplete('interrupted');
+      }
+      if (!complete) return incomplete('missing-completion');
+    }
+    evidence = await proof('publish');
+    if (!evidence) { await store.invalidate(plan, 'source-changed'); return incomplete('source-changed'); }
+    if (signal.aborted) return incomplete('cancelled');
+    return resources.authority
+      ? resources.authority.publish(evidence, (proof) => store.publish(plan, proof, { signal }))
+      : store.publish(plan, evidence, { signal });
+  } } } });
+  return Object.freeze({
+    /** @param {IngestionPlan} plan
+     * @param {{ executor: any, authority?: any, signal?: AbortSignal, deadline?: number }} resources */
+    async run(plan, resources) {
+      if (!plan || ['source', 'version', 'generation', 'policyRevision'].some((name) => typeof plan[name] !== 'string' || !plan[name])
+        || !['snapshot', 'revision'].includes(plan.consistency) || !Array.isArray(plan.partitions)
+        || !plan.partitions.length || plan.partitions.length > maxPartitions
+        || plan.partitions.some((partition) => typeof partition !== 'string' || !partition)
+        || new Set(plan.partitions).size !== plan.partitions.length || !Object.hasOwn(plan, 'input')
+        || Object.keys(plan).some((name) => !['source', 'version', 'generation', 'partitions', 'input', 'policyRevision', 'consistency'].includes(name)))
+        throw new TypeError('ingestion plan needs source/version/generation, unique bounded partitions, input, policyRevision and consistency');
+      const input = JSON.parse(canonicalizeJson(plan));
+      const result = await workflow.run(input, { runId: canonicalizeJson([plan.source, plan.generation]), resources,
+        signal: resources.signal });
+      return result.result;
+    },
+  });
+}

package/src/runs.js

@@ -0,0 +1,68 @@
+//@ts-check
+/** Adopt application run records without adding an orchestration engine. */
+import { canonicalizeJson } from '@jarenjs/json/canonical';
+import { compileWorkflow } from './workflow.js';
+
+/**
+ * Bind one compiled workflow to mapped run/checkpoint persistence. Leases are
+ * the existing queue's capabilities; resources stay private and release only
+ * after tasks drain and final cancellation/failure observation is persisted.
+ * @param {any} document @param {{ store: any, schemaVersion: string, tasks?: any }} options
+ */
+export function createDomainRun(document, options) {
+  if (!options?.store || typeof options.schemaVersion !== 'string' || !options.schemaVersion
+    || ['attach', 'load', 'save', 'get', 'finish', 'requestCancel'].some((name) => typeof options.store[name] !== 'function'))
+    throw new TypeError('domain run needs a mapped run store and schemaVersion');
+  const { store, schemaVersion } = options;
+  const workflowIdentity = canonicalizeJson(document);
+  const active = new Map();
+  const bound = (id) => {
+    const attempt = active.get(id);
+    if (!attempt) throw new TypeError('run has no active attempt');
+    return attempt;
+  };
+  const workflow = compileWorkflow(document, { tasks: options.tasks, store: {
+    load: (id) => { const attempt = bound(id); return store.load(id, attempt.identity, attempt.lease()); },
+    save: (id, snapshot, expected) => store.save(id, snapshot, expected, bound(id).lease()),
+  } });
+  return Object.freeze({
+    /** @param {string} id @param {any} input @param {{ lease: any, signal?: AbortSignal, release?: Function, event?: any, [key: string]: any }} resources */
+    async run(id, input, resources) {
+      if (active.has(id)) throw new TypeError('domain run is already active in this runner');
+      const lease = () => typeof resources.lease === 'function' ? resources.lease() : resources.lease;
+      const identity = { id, jobId: lease()?.jobId, workflow: workflowIdentity, schemaVersion };
+      const controller = new AbortController();
+      const signal = resources.signal ? AbortSignal.any([controller.signal, resources.signal]) : controller.signal;
+      const drained = Promise.withResolvers();
+      const attempt = { identity, lease, controller, drained: drained.promise };
+      active.set(id, attempt);
+      let attached = false;
+      try {
+        await store.attach(identity, lease()); attached = true;
+        return await workflow.run(input, { runId: id, signal, resources, event: resources.event });
+      }
+      catch (error) {
+        if (attached) {
+          const record = await store.get(id);
+          await store.finish(id, record.cancelRequested || signal.aborted ? 'cancelled' : 'failed', lease());
+        }
+        throw error;
+      }
+      finally {
+        active.delete(id);
+        try { await resources.release?.(); }
+        finally { drained.resolve(undefined); }
+      }
+    },
+    /** Cancellation authority is checked by the host's command. Navigation must
+     * detach observation, not call this method. Remote workers see durable intent
+     * at the next checkpoint; local workers abort and drain before this resolves.
+     * @param {string} id @param {number} revision @param {{ actor: string, reason: string }} evidence */
+    async cancel(id, revision, evidence) {
+      await store.requestCancel(id, revision, evidence);
+      const attempt = active.get(id);
+      if (attempt) { attempt.controller.abort(); await attempt.drained; }
+      return store.get(id);
+    },
+  });
+}

package/src/workflow.js

@@ -173,7 +173,7 @@ export function lowerWorkflow(document) {
 /** @typedef {{ load: (runId: string) => WorkflowSnapshot | null | Promise<WorkflowSnapshot | null>,
  * save: (runId: string, snapshot: WorkflowSnapshot, expectedGeneration: number) => boolean | Promise<boolean> }} WorkflowStore */
 /** @typedef {{ runId: string, snapshot?: any, expectedGeneration?: number,
- * signal?: AbortSignal, now?: number, event?: {type: string, payload?: any},
+ * signal?: AbortSignal, resources?: unknown, now?: number, event?: {type: string, payload?: any},
  * onTrace?: (record: any) => void }} WorkflowRunOptions */
 /** Compile once; each run owns its control and checkpoint records.
  * Store save MUST atomically compare expectedGeneration (0 means absent).
@@ -407,9 +407,14 @@ export function compileWorkflow(document, options = {}) {
           let result;
           let error = null;
           try {
-            result = Object.hasOwn(pending, 'result') ? pending.result
-              : await wait(dags.get(id).run(clone(pending.input), { runId: key, signal: controller.signal,
-                onNode: (record) => observe({ type: 'node', state: id, activation: pending.visit, ...record }) }));
+            if (Object.hasOwn(pending, 'result')) result = pending.result;
+            else {
+              const task = dags.get(id).run(clone(pending.input), { runId: key, signal: controller.signal,
+                resources: opts.resources,
+                onNode: (record) => observe({ type: 'node', state: id, activation: pending.visit, ...record }) });
+              // A private resource lease outlives every worker that received it.
+              result = opts.resources === undefined ? await wait(task) : await task;
+            }
           }
           catch (err) {
             if (spec.catch === undefined || err?.code !== 'JF2006') throw err;