@tiangong-lca/cli 0.1.0 → 0.1.2

package/dist/src/lib/batch/item-projection.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"item-projection.js","sourceRoot":"","sources":["../../../../src/lib/batch/item-projection.ts"],"names":[],"mappings":"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","sourcesContent":["import {\n  MAX_NODE_TIMER_DELAY_MS,\n  assertBatchContractMatches,\n  createBatchItemContract,\n  isRecord,\n  parseBatchItemContract,\n  parseItemIdentity,\n} from './canonical-contracts.js';\nimport {\n  BatchContractError,\n  BatchItemIdentityDriftError,\n  BatchItemProjectionDriftError,\n  BatchItemResourceDriftError,\n  BatchItemResumeContractError,\n  BatchMutationRetryError,\n} from './errors.js';\nimport { failedResult } from './scheduler-runtime.js';\nimport { MAX_BATCH_CONCURRENCY } from './types.js';\nimport type {\n  BatchClock,\n  BatchContract,\n  BatchItemContract,\n  BatchItemFailedResult,\n  BatchJsonValue,\n  BatchResumeItem,\n  BatchResumeState,\n  RunBoundedBatchOptions,\n} from './types.js';\n\nexport function validateBatchOptions<\n  TInput,\n  TOutput,\n  TIdentity extends BatchJsonValue,\n  TExclusiveKey extends string,\n>(options: RunBoundedBatchOptions<TInput, TOutput, TIdentity, TExclusiveKey>): void {\n  if (\n    !Number.isSafeInteger(options.maxConcurrency) ||\n    options.maxConcurrency < 1 ||\n    options.maxConcurrency > MAX_BATCH_CONCURRENCY\n  ) {\n    throw new BatchContractError(\n      `Batch maxConcurrency must be a safe integer from 1 to ${MAX_BATCH_CONCURRENCY}.`,\n    );\n  }\n  if (options.mode !== 'read' && options.mode !== 'mutation') {\n    throw new BatchContractError('Batch mode must be read or mutation.');\n  }\n  if (options.mode === 'mutation' && options.retry) {\n    throw new BatchMutationRetryError();\n  }\n  if (\n    options.retry &&\n    (!Number.isSafeInteger(options.retry.maxAttempts) ||\n      options.retry.maxAttempts < 1 ||\n      !Number.isSafeInteger(options.retry.maxDelayMs) ||\n      options.retry.maxDelayMs < 0 ||\n      options.retry.maxDelayMs > MAX_NODE_TIMER_DELAY_MS)\n  ) {\n    throw new BatchContractError(\n      `Batch retry maxAttempts must be positive and maxDelayMs must be a non-negative safe integer no greater than the maximum supported timer delay (${MAX_NODE_TIMER_DELAY_MS} ms).`,\n    );\n  }\n}\n\nexport function validateResume<TOutput, TIdentity extends BatchJsonValue>(\n  resume: BatchResumeState<TOutput, TIdentity> | undefined,\n  contract: BatchContract<TIdentity>,\n  itemIds: readonly string[],\n): Map<string, BatchResumeItem<TOutput>> {\n  const result = new Map<string, BatchResumeItem<TOutput>>();\n  if (!resume) return result;\n  assertBatchContractMatches<TIdentity>(contract, resume.contract);\n  const currentIds = new Set(itemIds);\n  for (const item of resume.items) {\n    let itemContract: BatchItemContract;\n    try {\n      itemContract = parseBatchItemContract(item);\n    } catch (error) {\n      throw new BatchContractError('Batch resume contains an invalid item contract.', {\n        cause: error,\n      });\n    }\n    if (\n      !isRecord(item) ||\n      !currentIds.has(itemContract.item_id) ||\n      !Number.isSafeInteger(item.attempts) ||\n      Number(item.attempts) < 1 ||\n      !['attempted', 'completed'].includes(String(item.state))\n    ) {\n      throw new BatchContractError('Batch resume contains an invalid or foreign item.');\n    }\n    if (result.has(itemContract.item_id)) {\n      throw new BatchContractError('Batch resume item identities must be unique.');\n    }\n    if (item.state === 'completed') {\n      if (!['succeeded', 'recovered'].includes(String(item.outcome))) {\n        throw new BatchContractError('Completed batch resume items require a successful outcome.');\n      }\n      result.set(\n        itemContract.item_id,\n        Object.freeze({\n          ...itemContract,\n          state: 'completed',\n          outcome: item.outcome,\n          value: item.value,\n          attempts: Number(item.attempts),\n        }),\n      );\n    } else {\n      result.set(\n        itemContract.item_id,\n        Object.freeze({\n          ...itemContract,\n          state: 'attempted',\n          attempts: Number(item.attempts),\n        }),\n      );\n    }\n  }\n  return result;\n}\n\nexport function projectBatchItemContract<\n  TInput,\n  TOutput,\n  TIdentity extends BatchJsonValue,\n  TExclusiveKey extends string,\n>(\n  options: RunBoundedBatchOptions<TInput, TOutput, TIdentity, TExclusiveKey>,\n  item: TInput,\n  index: number,\n  itemId: string,\n): BatchItemContract {\n  return createBatchItemContract({\n    item_id: itemId,\n    content: options.projectItemContent(item, index),\n    policy: options.projectItemPolicy(item, index),\n  });\n}\n\nexport function itemIdentityMatches<\n  TInput,\n  TOutput,\n  TIdentity extends BatchJsonValue,\n  TExclusiveKey extends string,\n>(\n  options: RunBoundedBatchOptions<TInput, TOutput, TIdentity, TExclusiveKey>,\n  item: TInput,\n  index: number,\n  expectedItemId: string,\n): boolean {\n  try {\n    const projected = options.getItemIdentity(item, index);\n    return parseItemIdentity(projected, index) === expectedItemId;\n  } catch {\n    return false;\n  }\n}\n\nexport function identityDriftFailure<TInput, TOutput>(\n  item: TInput,\n  itemContract: BatchItemContract,\n  exclusiveKey: string | null,\n  index: number,\n  resumeItem: BatchResumeItem<TOutput> | undefined,\n  clock: BatchClock,\n): BatchItemFailedResult<TInput> {\n  return failedResult(\n    item,\n    itemContract,\n    index,\n    resumeItem?.attempts ?? 0,\n    resumeItem !== undefined,\n    resumeItem !== undefined,\n    clock,\n    new BatchItemIdentityDriftError(itemContract.item_id),\n    exclusiveKey,\n  );\n}\n\nexport function projectExclusiveKey<\n  TInput,\n  TOutput,\n  TIdentity extends BatchJsonValue,\n  TExclusiveKey extends string,\n>(\n  options: RunBoundedBatchOptions<TInput, TOutput, TIdentity, TExclusiveKey>,\n  item: TInput,\n  index: number,\n  itemContract: BatchItemContract,\n): TExclusiveKey | null {\n  if (!options.getExclusiveKey) return null;\n  const value = options.getExclusiveKey({\n    item,\n    item_id: itemContract.item_id,\n    item_contract: itemContract,\n    input_index: index,\n  });\n  if (value === null || value === undefined) return null;\n  if (typeof value !== 'string' || value.length === 0 || /[\\0\\r\\n]/u.test(value)) {\n    throw new BatchContractError(\n      'Batch exclusive resource keys must be non-empty single-line strings.',\n    );\n  }\n  return value;\n}\n\nexport function projectionDriftFailure<TInput, TOutput>(\n  item: TInput,\n  itemContract: BatchItemContract,\n  exclusiveKey: string | null,\n  index: number,\n  resumeItem: BatchResumeItem<TOutput> | undefined,\n  clock: BatchClock,\n): BatchItemFailedResult<TInput> {\n  return failedResult(\n    item,\n    itemContract,\n    index,\n    resumeItem?.attempts ?? 0,\n    resumeItem !== undefined,\n    resumeItem !== undefined,\n    clock,\n    new BatchItemProjectionDriftError(itemContract.item_id),\n    exclusiveKey,\n  );\n}\n\nexport function resourceDriftFailure<TInput, TOutput>(\n  item: TInput,\n  itemContract: BatchItemContract,\n  exclusiveKey: string | null,\n  index: number,\n  resumeItem: BatchResumeItem<TOutput> | undefined,\n  clock: BatchClock,\n): BatchItemFailedResult<TInput> {\n  return failedResult(\n    item,\n    itemContract,\n    index,\n    resumeItem?.attempts ?? 0,\n    resumeItem !== undefined,\n    resumeItem !== undefined,\n    clock,\n    new BatchItemResourceDriftError(itemContract.item_id),\n    exclusiveKey,\n  );\n}\n\nexport function resumeContractFailure<TInput>(\n  item: TInput,\n  itemContract: BatchItemContract,\n  exclusiveKey: string | null,\n  index: number,\n  attempts: number,\n  clock: BatchClock,\n): BatchItemFailedResult<TInput> {\n  return failedResult(\n    item,\n    itemContract,\n    index,\n    attempts,\n    true,\n    true,\n    clock,\n    new BatchItemResumeContractError(itemContract.item_id),\n    exclusiveKey,\n  );\n}\n"]}

package/dist/src/lib/batch/run-lock.d.ts

@@ -0,0 +1,4 @@
+import type { BatchJsonValue, BatchRunLockOptions, BatchRunLockReceipt } from './types.js';
+export declare function batchRunLockStatePath(runPath: string): string;
+export declare function batchRunLockPath(runPath: string): string;
+export declare function withBatchRunLock<T, TIdentity extends BatchJsonValue>(options: BatchRunLockOptions<TIdentity>, task: (receipt: BatchRunLockReceipt) => Promise<T> | T): Promise<T>;

package/dist/src/lib/batch/run-lock.js

@@ -0,0 +1,155 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+import path from 'node:path';
+import { StateLockTimeoutError, lockPathForState, withStateFileLock } from '../state-lock.js';
+import { assertBatchTimerDelaySupported, parseBatchRunLockToken, parseBatchRunPath, sha256BatchJson, } from './canonical-contracts.js';
+import { BatchRunLockIdentityConflictError, BatchRunLockTimeoutError } from './errors.js';
+const DEFAULT_BATCH_RUN_LOCK_TIMEOUT_MS = 300_000;
+const ACTIVE_BATCH_RUN_LOCKS = new Map();
+const BATCH_RUN_LOCK_CONTEXT = new AsyncLocalStorage();
+export function batchRunLockStatePath(runPath) {
+    return path.join(parseBatchRunPath(runPath), '.tiangong-lca-batch-run.state');
+}
+export function batchRunLockPath(runPath) {
+    return lockPathForState(batchRunLockStatePath(runPath));
+}
+export async function withBatchRunLock(options, task) {
+    const runPath = parseBatchRunPath(options.runPath);
+    const reason = parseBatchRunLockToken(options.reason, 'reason');
+    assertBatchTimerDelaySupported(options.timeoutMs, 'timeoutMs');
+    assertBatchTimerDelaySupported(options.pollMs, 'pollMs');
+    const identitySha256 = sha256BatchJson(options.identity);
+    const statePath = batchRunLockStatePath(runPath);
+    const lockPath = lockPathForState(statePath);
+    const receipt = Object.freeze({
+        run_path: runPath,
+        state_path: statePath,
+        lock_path: lockPath,
+        identity_sha256: identitySha256,
+    });
+    const active = ACTIVE_BATCH_RUN_LOCKS.get(statePath);
+    if (active) {
+        if (active.identitySha256 !== identitySha256) {
+            throw new BatchRunLockIdentityConflictError({
+                runPath,
+                activeIdentitySha256: active.identitySha256,
+                requestedIdentitySha256: identitySha256,
+            });
+        }
+        const parentScope = BATCH_RUN_LOCK_CONTEXT.getStore()?.get(statePath);
+        if (parentScope?.active && parentScope.owner === active) {
+            return runBatchRunLockScope(statePath, active, task);
+        }
+        await waitForActiveBatchRunLock(active, options, runPath, lockPath, identitySha256);
+        return withBatchRunLock(options, task);
+    }
+    let physicalOwner;
+    try {
+        const result = await withStateFileLock(statePath, {
+            reason: `batch-run:${identitySha256}:${reason}`,
+            metadata: {
+                batch_identity_sha256: identitySha256,
+                batch_run_path: runPath,
+            },
+            stalePolicy: 'same-host-pid',
+            ...(options.timeoutMs === undefined ? {} : { timeoutMs: options.timeoutMs }),
+            ...(options.pollMs === undefined ? {} : { pollMs: options.pollMs }),
+            ...(options.sleep === undefined ? {} : { sleep: options.sleep }),
+        }, async () => {
+            const owner = createActiveBatchRunLock(identitySha256, receipt);
+            physicalOwner = owner;
+            ACTIVE_BATCH_RUN_LOCKS.set(statePath, owner);
+            try {
+                return await runBatchRunLockScope(statePath, owner, task);
+            }
+            finally {
+                await owner.drained;
+            }
+        });
+        return result;
+    }
+    catch (error) {
+        if (!(error instanceof StateLockTimeoutError))
+            throw error;
+        const details = error.details;
+        throw new BatchRunLockTimeoutError({
+            runPath,
+            lockPath,
+            identitySha256,
+            waitedMs: details.waitedMs,
+            owner: details.owner ? Object.freeze({ ...details.owner }) : null,
+        });
+    }
+    finally {
+        if (physicalOwner) {
+            ACTIVE_BATCH_RUN_LOCKS.delete(statePath);
+            physicalOwner.release();
+        }
+    }
+}
+function createActiveBatchRunLock(identitySha256, receipt) {
+    let drain = () => undefined;
+    const drained = new Promise((resolve) => {
+        drain = resolve;
+    });
+    let release = () => undefined;
+    const released = new Promise((resolve) => {
+        release = resolve;
+    });
+    return {
+        scopeDepth: 0,
+        identitySha256,
+        receipt,
+        drained,
+        drain,
+        released,
+        release,
+    };
+}
+async function runBatchRunLockScope(statePath, owner, task) {
+    const scope = { active: true, owner };
+    owner.scopeDepth += 1;
+    const context = new Map(BATCH_RUN_LOCK_CONTEXT.getStore() ?? []);
+    context.set(statePath, scope);
+    try {
+        return await BATCH_RUN_LOCK_CONTEXT.run(context, () => task(owner.receipt));
+    }
+    finally {
+        scope.active = false;
+        owner.scopeDepth -= 1;
+        if (owner.scopeDepth === 0)
+            owner.drain();
+    }
+}
+async function waitForActiveBatchRunLock(active, options, runPath, lockPath, identitySha256) {
+    const timeoutMs = Math.max(options.timeoutMs ?? DEFAULT_BATCH_RUN_LOCK_TIMEOUT_MS, 0);
+    if (timeoutMs === 0) {
+        throw new BatchRunLockTimeoutError({
+            runPath,
+            lockPath,
+            identitySha256,
+            waitedMs: 0,
+            owner: null,
+        });
+    }
+    const startedAt = Date.now();
+    let timer;
+    try {
+        await Promise.race([
+            active.released,
+            new Promise((_resolve, reject) => {
+                timer = setTimeout(() => reject(new BatchRunLockTimeoutError({
+                    runPath,
+                    lockPath,
+                    identitySha256,
+                    waitedMs: Date.now() - startedAt,
+                    owner: null,
+                })), timeoutMs);
+            }),
+        ]);
+    }
+    finally {
+        if (timer)
+            clearTimeout(timer);
+    }
+}
+//# sourceMappingURL=run-lock.js.map

package/dist/src/lib/batch/run-lock.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-lock.js","sourceRoot":"","sources":["../../../../src/lib/batch/run-lock.ts"],"names":[],"mappings":"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","sourcesContent":["import { AsyncLocalStorage } from 'node:async_hooks';\nimport path from 'node:path';\n\nimport { StateLockTimeoutError, lockPathForState, withStateFileLock } from '../state-lock.js';\nimport {\n  assertBatchTimerDelaySupported,\n  parseBatchRunLockToken,\n  parseBatchRunPath,\n  sha256BatchJson,\n} from './canonical-contracts.js';\nimport { BatchRunLockIdentityConflictError, BatchRunLockTimeoutError } from './errors.js';\nimport type { BatchJsonValue, BatchRunLockOptions, BatchRunLockReceipt } from './types.js';\n\nconst DEFAULT_BATCH_RUN_LOCK_TIMEOUT_MS = 300_000;\n\ntype ActiveBatchRunLock = {\n  scopeDepth: number;\n  identitySha256: string;\n  receipt: BatchRunLockReceipt;\n  drained: Promise<void>;\n  drain: () => void;\n  released: Promise<void>;\n  release: () => void;\n};\n\ntype BatchRunLockScope = {\n  active: boolean;\n  owner: ActiveBatchRunLock;\n};\n\nconst ACTIVE_BATCH_RUN_LOCKS = new Map<string, ActiveBatchRunLock>();\nconst BATCH_RUN_LOCK_CONTEXT = new AsyncLocalStorage<ReadonlyMap<string, BatchRunLockScope>>();\n\nexport function batchRunLockStatePath(runPath: string): string {\n  return path.join(parseBatchRunPath(runPath), '.tiangong-lca-batch-run.state');\n}\n\nexport function batchRunLockPath(runPath: string): string {\n  return lockPathForState(batchRunLockStatePath(runPath));\n}\n\nexport async function withBatchRunLock<T, TIdentity extends BatchJsonValue>(\n  options: BatchRunLockOptions<TIdentity>,\n  task: (receipt: BatchRunLockReceipt) => Promise<T> | T,\n): Promise<T> {\n  const runPath = parseBatchRunPath(options.runPath);\n  const reason = parseBatchRunLockToken(options.reason, 'reason');\n  assertBatchTimerDelaySupported(options.timeoutMs, 'timeoutMs');\n  assertBatchTimerDelaySupported(options.pollMs, 'pollMs');\n  const identitySha256 = sha256BatchJson(options.identity);\n  const statePath = batchRunLockStatePath(runPath);\n  const lockPath = lockPathForState(statePath);\n  const receipt = Object.freeze({\n    run_path: runPath,\n    state_path: statePath,\n    lock_path: lockPath,\n    identity_sha256: identitySha256,\n  });\n  const active = ACTIVE_BATCH_RUN_LOCKS.get(statePath);\n  if (active) {\n    if (active.identitySha256 !== identitySha256) {\n      throw new BatchRunLockIdentityConflictError({\n        runPath,\n        activeIdentitySha256: active.identitySha256,\n        requestedIdentitySha256: identitySha256,\n      });\n    }\n    const parentScope = BATCH_RUN_LOCK_CONTEXT.getStore()?.get(statePath);\n    if (parentScope?.active && parentScope.owner === active) {\n      return runBatchRunLockScope(statePath, active, task);\n    }\n    await waitForActiveBatchRunLock(active, options, runPath, lockPath, identitySha256);\n    return withBatchRunLock(options, task);\n  }\n\n  let physicalOwner: ActiveBatchRunLock | undefined;\n  try {\n    const result = await withStateFileLock(\n      statePath,\n      {\n        reason: `batch-run:${identitySha256}:${reason}`,\n        metadata: {\n          batch_identity_sha256: identitySha256,\n          batch_run_path: runPath,\n        },\n        stalePolicy: 'same-host-pid',\n        ...(options.timeoutMs === undefined ? {} : { timeoutMs: options.timeoutMs }),\n        ...(options.pollMs === undefined ? {} : { pollMs: options.pollMs }),\n        ...(options.sleep === undefined ? {} : { sleep: options.sleep }),\n      },\n      async () => {\n        const owner = createActiveBatchRunLock(identitySha256, receipt);\n        physicalOwner = owner;\n        ACTIVE_BATCH_RUN_LOCKS.set(statePath, owner);\n        try {\n          return await runBatchRunLockScope(statePath, owner, task);\n        } finally {\n          await owner.drained;\n        }\n      },\n    );\n    return result;\n  } catch (error) {\n    if (!(error instanceof StateLockTimeoutError)) throw error;\n    const details = error.details as {\n      waitedMs: number;\n      owner: Record<string, unknown> | null;\n    };\n    throw new BatchRunLockTimeoutError({\n      runPath,\n      lockPath,\n      identitySha256,\n      waitedMs: details.waitedMs,\n      owner: details.owner ? Object.freeze({ ...details.owner }) : null,\n    });\n  } finally {\n    if (physicalOwner) {\n      ACTIVE_BATCH_RUN_LOCKS.delete(statePath);\n      physicalOwner.release();\n    }\n  }\n}\n\nfunction createActiveBatchRunLock(\n  identitySha256: string,\n  receipt: BatchRunLockReceipt,\n): ActiveBatchRunLock {\n  let drain: () => void = () => undefined;\n  const drained = new Promise<void>((resolve) => {\n    drain = resolve;\n  });\n  let release: () => void = () => undefined;\n  const released = new Promise<void>((resolve) => {\n    release = resolve;\n  });\n  return {\n    scopeDepth: 0,\n    identitySha256,\n    receipt,\n    drained,\n    drain,\n    released,\n    release,\n  };\n}\n\nasync function runBatchRunLockScope<T>(\n  statePath: string,\n  owner: ActiveBatchRunLock,\n  task: (receipt: BatchRunLockReceipt) => Promise<T> | T,\n): Promise<T> {\n  const scope: BatchRunLockScope = { active: true, owner };\n  owner.scopeDepth += 1;\n  const context = new Map(BATCH_RUN_LOCK_CONTEXT.getStore() ?? []);\n  context.set(statePath, scope);\n  try {\n    return await BATCH_RUN_LOCK_CONTEXT.run(context, () => task(owner.receipt));\n  } finally {\n    scope.active = false;\n    owner.scopeDepth -= 1;\n    if (owner.scopeDepth === 0) owner.drain();\n  }\n}\n\nasync function waitForActiveBatchRunLock<TIdentity extends BatchJsonValue>(\n  active: { released: Promise<void> },\n  options: BatchRunLockOptions<TIdentity>,\n  runPath: string,\n  lockPath: string,\n  identitySha256: string,\n): Promise<void> {\n  const timeoutMs = Math.max(options.timeoutMs ?? DEFAULT_BATCH_RUN_LOCK_TIMEOUT_MS, 0);\n  if (timeoutMs === 0) {\n    throw new BatchRunLockTimeoutError({\n      runPath,\n      lockPath,\n      identitySha256,\n      waitedMs: 0,\n      owner: null,\n    });\n  }\n  const startedAt = Date.now();\n  let timer: ReturnType<typeof setTimeout> | undefined;\n  try {\n    await Promise.race([\n      active.released,\n      new Promise<never>((_resolve, reject) => {\n        timer = setTimeout(\n          () =>\n            reject(\n              new BatchRunLockTimeoutError({\n                runPath,\n                lockPath,\n                identitySha256,\n                waitedMs: Date.now() - startedAt,\n                owner: null,\n              }),\n            ),\n          timeoutMs,\n        );\n      }),\n    ]);\n  } finally {\n    if (timer) clearTimeout(timer);\n  }\n}\n"]}

package/dist/src/lib/batch/scheduler-runtime.d.ts

@@ -0,0 +1,29 @@
+import type { BatchClock, BatchEvent, BatchEventType, BatchItemContract, BatchItemFailedResult, BatchItemResult } from './types.js';
+export declare class MinReadyIndexHeap {
+    private readonly values;
+    push(value: number): void;
+    pop(): number | undefined;
+}
+export type EventEmitter = ReturnType<typeof createEventEmitter>;
+export declare function createEventEmitter(clock: BatchClock, sink: ((event: BatchEvent) => void | Promise<void>) | undefined): {
+    events: Readonly<{
+        sequence: number;
+        timestamp_ms: number;
+        type: BatchEventType;
+        item_id?: string;
+        input_index?: number;
+        attempt?: number;
+        delay_ms?: number;
+        status?: import("./types.js").BatchItemResultStatus | import("./types.js").BatchStatus;
+        source?: import("./types.js").BatchRecoverySource;
+        exclusive_key?: string;
+    }>[];
+    emit: (type: BatchEventType, details?: Omit<BatchEvent, 'sequence' | 'timestamp_ms' | 'type'>) => Promise<void>;
+    settled: () => Promise<void>;
+};
+export declare function readClock(clock: BatchClock): number;
+export declare function createAsyncLock(onError: (error: unknown) => void): <T>(operation: () => Promise<T>) => Promise<T>;
+export declare function inputOrderedResults<TInput, TOutput>(results: Map<number, BatchItemResult<TInput, TOutput>>): BatchItemResult<TInput, TOutput>[];
+export declare function failedResult<TInput>(item: TInput, itemContract: BatchItemContract, inputIndex: number, attempts: number, attemptConsumed: boolean, resumed: boolean, clock: BatchClock, error: unknown, exclusiveKey?: string | null): BatchItemFailedResult<TInput>;
+export declare function freezeResult<T extends BatchItemResult<unknown, unknown>>(value: T): T;
+export declare function defaultBatchSleep(milliseconds: number): Promise<void>;

package/dist/src/lib/batch/scheduler-runtime.js

@@ -0,0 +1,114 @@
+import { BatchContractError } from './errors.js';
+export class MinReadyIndexHeap {
+    values = [];
+    push(value) {
+        this.values.push(value);
+        let child = this.values.length - 1;
+        while (child > 0) {
+            const parent = Math.floor((child - 1) / 2);
+            if (this.values[parent] <= this.values[child])
+                break;
+            [this.values[parent], this.values[child]] = [this.values[child], this.values[parent]];
+            child = parent;
+        }
+    }
+    pop() {
+        if (this.values.length === 0)
+            return undefined;
+        const minimum = this.values[0];
+        const last = this.values.pop();
+        if (this.values.length === 0)
+            return minimum;
+        this.values[0] = last;
+        let parent = 0;
+        while (true) {
+            const left = parent * 2 + 1;
+            if (left >= this.values.length)
+                break;
+            const right = left + 1;
+            const smallest = right < this.values.length && this.values[right] < this.values[left] ? right : left;
+            if (this.values[parent] <= this.values[smallest])
+                break;
+            [this.values[parent], this.values[smallest]] = [this.values[smallest], this.values[parent]];
+            parent = smallest;
+        }
+        return minimum;
+    }
+}
+export function createEventEmitter(clock, sink) {
+    const events = [];
+    let sequence = 0;
+    let lastTimestamp = Number.NEGATIVE_INFINITY;
+    let tail = Promise.resolve();
+    return {
+        events,
+        emit: async (type, details = {}) => {
+            const timestamp = Math.max(lastTimestamp, readClock(clock));
+            lastTimestamp = timestamp;
+            const event = Object.freeze({
+                sequence: (sequence += 1),
+                timestamp_ms: timestamp,
+                type,
+                ...details,
+            });
+            events.push(event);
+            const delivery = tail.then(() => sink?.(event));
+            tail = delivery.then(() => undefined, () => undefined);
+            await delivery;
+        },
+        settled: () => tail,
+    };
+}
+export function readClock(clock) {
+    const value = clock.now();
+    if (!Number.isFinite(value)) {
+        throw new BatchContractError('Batch clock must return a finite millisecond value.');
+    }
+    return value;
+}
+export function createAsyncLock(onError) {
+    let tail = Promise.resolve();
+    return async (operation) => {
+        const previous = tail;
+        let release = () => undefined;
+        tail = new Promise((resolve) => {
+            release = resolve;
+        });
+        await previous;
+        try {
+            return await operation();
+        }
+        catch (error) {
+            onError(error);
+            throw error;
+        }
+        finally {
+            release();
+        }
+    };
+}
+export function inputOrderedResults(results) {
+    return [...results.entries()].sort(([left], [right]) => left - right).map(([, result]) => result);
+}
+export function failedResult(item, itemContract, inputIndex, attempts, attemptConsumed, resumed, clock, error, exclusiveKey = null) {
+    return freezeResult({
+        item,
+        item_id: itemContract.item_id,
+        item_contract: itemContract,
+        exclusive_key: exclusiveKey,
+        input_index: inputIndex,
+        attempts,
+        attempt_consumed: attemptConsumed,
+        resumed,
+        completed_at_ms: readClock(clock),
+        status: 'failed',
+        error,
+    });
+}
+export function freezeResult(value) {
+    return Object.freeze(value);
+}
+export function defaultBatchSleep(milliseconds) {
+    return new Promise((resolve) => setTimeout(resolve, milliseconds));
+}
+//# sourceMappingURL=scheduler-runtime.js.map

package/dist/src/lib/batch/scheduler-runtime.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scheduler-runtime.js","sourceRoot":"","sources":["../../../../src/lib/batch/scheduler-runtime.ts"],"names":[],"mappings":"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","sourcesContent":["import { BatchContractError } from './errors.js';\nimport type {\n  BatchClock,\n  BatchEvent,\n  BatchEventType,\n  BatchItemContract,\n  BatchItemFailedResult,\n  BatchItemResult,\n} from './types.js';\n\nexport class MinReadyIndexHeap {\n  private readonly values: number[] = [];\n\n  push(value: number): void {\n    this.values.push(value);\n    let child = this.values.length - 1;\n    while (child > 0) {\n      const parent = Math.floor((child - 1) / 2);\n      if (this.values[parent]! <= this.values[child]!) break;\n      [this.values[parent], this.values[child]] = [this.values[child]!, this.values[parent]!];\n      child = parent;\n    }\n  }\n\n  pop(): number | undefined {\n    if (this.values.length === 0) return undefined;\n    const minimum = this.values[0]!;\n    const last = this.values.pop()!;\n    if (this.values.length === 0) return minimum;\n    this.values[0] = last;\n    let parent = 0;\n    while (true) {\n      const left = parent * 2 + 1;\n      if (left >= this.values.length) break;\n      const right = left + 1;\n      const smallest =\n        right < this.values.length && this.values[right]! < this.values[left]! ? right : left;\n      if (this.values[parent]! <= this.values[smallest]!) break;\n      [this.values[parent], this.values[smallest]] = [this.values[smallest]!, this.values[parent]!];\n      parent = smallest;\n    }\n    return minimum;\n  }\n}\n\nexport type EventEmitter = ReturnType<typeof createEventEmitter>;\n\nexport function createEventEmitter(\n  clock: BatchClock,\n  sink: ((event: BatchEvent) => void | Promise<void>) | undefined,\n) {\n  const events: BatchEvent[] = [];\n  let sequence = 0;\n  let lastTimestamp = Number.NEGATIVE_INFINITY;\n  let tail = Promise.resolve();\n  return {\n    events,\n    emit: async (\n      type: BatchEventType,\n      details: Omit<BatchEvent, 'sequence' | 'timestamp_ms' | 'type'> = {},\n    ) => {\n      const timestamp = Math.max(lastTimestamp, readClock(clock));\n      lastTimestamp = timestamp;\n      const event = Object.freeze({\n        sequence: (sequence += 1),\n        timestamp_ms: timestamp,\n        type,\n        ...details,\n      }) as BatchEvent;\n      events.push(event);\n      const delivery = tail.then(() => sink?.(event));\n      tail = delivery.then(\n        () => undefined,\n        () => undefined,\n      );\n      await delivery;\n    },\n    settled: () => tail,\n  };\n}\n\nexport function readClock(clock: BatchClock): number {\n  const value = clock.now();\n  if (!Number.isFinite(value)) {\n    throw new BatchContractError('Batch clock must return a finite millisecond value.');\n  }\n  return value;\n}\n\nexport function createAsyncLock(onError: (error: unknown) => void) {\n  let tail = Promise.resolve();\n  return async <T>(operation: () => Promise<T>): Promise<T> => {\n    const previous = tail;\n    let release: () => void = () => undefined;\n    tail = new Promise<void>((resolve) => {\n      release = resolve;\n    });\n    await previous;\n    try {\n      return await operation();\n    } catch (error) {\n      onError(error);\n      throw error;\n    } finally {\n      release();\n    }\n  };\n}\n\nexport function inputOrderedResults<TInput, TOutput>(\n  results: Map<number, BatchItemResult<TInput, TOutput>>,\n): BatchItemResult<TInput, TOutput>[] {\n  return [...results.entries()].sort(([left], [right]) => left - right).map(([, result]) => result);\n}\n\nexport function failedResult<TInput>(\n  item: TInput,\n  itemContract: BatchItemContract,\n  inputIndex: number,\n  attempts: number,\n  attemptConsumed: boolean,\n  resumed: boolean,\n  clock: BatchClock,\n  error: unknown,\n  exclusiveKey: string | null = null,\n): BatchItemFailedResult<TInput> {\n  return freezeResult({\n    item,\n    item_id: itemContract.item_id,\n    item_contract: itemContract,\n    exclusive_key: exclusiveKey,\n    input_index: inputIndex,\n    attempts,\n    attempt_consumed: attemptConsumed,\n    resumed,\n    completed_at_ms: readClock(clock),\n    status: 'failed',\n    error,\n  });\n}\n\nexport function freezeResult<T extends BatchItemResult<unknown, unknown>>(value: T): T {\n  return Object.freeze(value);\n}\n\nexport function defaultBatchSleep(milliseconds: number): Promise<void> {\n  return new Promise((resolve) => setTimeout(resolve, milliseconds));\n}\n"]}

package/dist/src/lib/batch/types.d.ts

@@ -0,0 +1,183 @@
+export declare const MAX_BATCH_CONCURRENCY: 64;
+export type BatchJsonPrimitive = boolean | null | number | string;
+export type BatchJsonValue = BatchJsonPrimitive | BatchJsonValue[] | BatchJsonObject;
+export type BatchJsonObject = {
+    [key: string]: BatchJsonValue;
+};
+export type BatchContract<TIdentity extends BatchJsonValue = BatchJsonValue> = {
+    identity: TIdentity;
+    content_sha256: string;
+    policy_sha256: string;
+};
+export type BatchItemContract = Readonly<{
+    item_id: string;
+    content_sha256: string;
+    policy_sha256: string;
+}>;
+export type CreateBatchItemContractOptions = Readonly<{
+    item_id: string;
+    content: BatchJsonValue;
+    policy: BatchJsonValue;
+}>;
+export type CreateBatchContractOptions<TIdentity extends BatchJsonValue> = {
+    identity: TIdentity;
+    content: BatchJsonValue;
+    policy: BatchJsonValue;
+};
+export type BatchMode = 'mutation' | 'read';
+export type BatchStatus = 'completed' | 'paused' | 'stopped';
+export type BatchItemSuccessStatus = 'recovered' | 'succeeded';
+export type BatchEventType = 'attempt_failed' | 'attempt_started' | 'attempt_succeeded' | 'batch_completed' | 'batch_paused' | 'batch_started' | 'batch_stopped' | 'item_claimed' | 'item_completed' | 'item_identity_drift' | 'item_projection_drift' | 'item_resource_acquired' | 'item_resource_drift' | 'item_resource_queued' | 'item_resource_released' | 'item_resume_rejected' | 'item_resumed' | 'recovery_failed' | 'recovery_started' | 'recovery_succeeded' | 'retry_scheduled';
+export type BatchEvent = Readonly<{
+    sequence: number;
+    timestamp_ms: number;
+    type: BatchEventType;
+    item_id?: string;
+    input_index?: number;
+    attempt?: number;
+    delay_ms?: number;
+    status?: BatchItemResultStatus | BatchStatus;
+    source?: BatchRecoverySource;
+    exclusive_key?: string;
+}>;
+type BatchItemResultCommon<TInput> = Readonly<{
+    item: TInput;
+    item_id: string;
+    item_contract: BatchItemContract;
+    exclusive_key: string | null;
+    input_index: number;
+    attempts: number;
+    attempt_consumed: boolean;
+    resumed: boolean;
+    completed_at_ms: number;
+}>;
+export type BatchItemSucceededResult<TInput, TOutput> = BatchItemResultCommon<TInput> & Readonly<{
+    status: BatchItemSuccessStatus;
+    value: TOutput;
+}>;
+export type BatchItemFailedResult<TInput> = BatchItemResultCommon<TInput> & Readonly<{
+    status: 'failed';
+    error: unknown;
+}>;
+export type BatchItemResultStatus = BatchItemSuccessStatus | 'failed';
+export type BatchItemResult<TInput, TOutput> = BatchItemFailedResult<TInput> | BatchItemSucceededResult<TInput, TOutput>;
+export type BatchRunResult<TInput, TOutput, TIdentity extends BatchJsonValue = BatchJsonValue> = Readonly<{
+    contract: BatchContract<TIdentity>;
+    status: BatchStatus;
+    claim_order: readonly string[];
+    completion_order: readonly string[];
+    results_input_order: readonly BatchItemResult<TInput, TOutput>[];
+    results_completion_order: readonly BatchItemResult<TInput, TOutput>[];
+    unclaimed_item_ids: readonly string[];
+    events: readonly BatchEvent[];
+}>;
+export type BatchExecutionContext<TInput, TExclusiveKey extends string = string> = Readonly<{
+    item: TInput;
+    item_id: string;
+    item_contract: BatchItemContract;
+    exclusive_key: TExclusiveKey | null;
+    input_index: number;
+    attempt: number;
+    mode: BatchMode;
+}>;
+export type BatchRetryContext<TInput, TExclusiveKey extends string = string> = BatchExecutionContext<TInput, TExclusiveKey> & Readonly<{
+    error: unknown;
+}>;
+export type BatchRetryPolicy<TInput, TExclusiveKey extends string = string> = Readonly<{
+    maxAttempts: number;
+    maxDelayMs: number;
+    shouldRetry: (context: BatchRetryContext<TInput, TExclusiveKey>) => boolean | Promise<boolean>;
+    delayMs: (context: BatchRetryContext<TInput, TExclusiveKey>) => number | Promise<number>;
+}>;
+export type BatchRecoverySource = 'execution_error' | 'resume_incomplete';
+export type BatchMutationRecoveryContext<TInput, TExclusiveKey extends string = string> = Readonly<{
+    item: TInput;
+    item_id: string;
+    item_contract: BatchItemContract;
+    exclusive_key: TExclusiveKey | null;
+    input_index: number;
+    attempts: number;
+    error: unknown;
+    source: BatchRecoverySource;
+}>;
+export type BatchMutationRecoveryResult<TOutput> = Readonly<{
+    status: 'recovered';
+    value: TOutput;
+}> | Readonly<{
+    status: 'unresolved';
+    error?: unknown;
+}>;
+export type BatchCompletedResumeItem<TOutput> = BatchItemContract & Readonly<{
+    state: 'completed';
+    outcome: BatchItemSuccessStatus;
+    value: TOutput;
+    attempts: number;
+}>;
+export type BatchAttemptedResumeItem = BatchItemContract & Readonly<{
+    state: 'attempted';
+    attempts: number;
+}>;
+export type BatchResumeItem<TOutput> = BatchAttemptedResumeItem | BatchCompletedResumeItem<TOutput>;
+export type BatchResumeState<TOutput, TIdentity extends BatchJsonValue = BatchJsonValue> = Readonly<{
+    contract: BatchContract<TIdentity>;
+    items: readonly BatchResumeItem<TOutput>[];
+}>;
+export type BatchPauseContext<TInput, TOutput> = Readonly<{
+    item: TInput;
+    item_id: string;
+    item_contract: BatchItemContract;
+    exclusive_key: string | null;
+    input_index: number;
+    claimed_count: number;
+    results_input_order: readonly BatchItemResult<TInput, TOutput>[];
+}>;
+export type BatchStopContext<TInput, TOutput> = Readonly<{
+    last_result: BatchItemResult<TInput, TOutput>;
+    claimed_count: number;
+    results_input_order: readonly BatchItemResult<TInput, TOutput>[];
+    results_completion_order: readonly BatchItemResult<TInput, TOutput>[];
+}>;
+export type BatchClock = Readonly<{
+    now: () => number;
+}>;
+export type BatchSleep = (milliseconds: number) => Promise<void>;
+export type BatchRunLockOptions<TIdentity extends BatchJsonValue> = Readonly<{
+    runPath: string;
+    identity: TIdentity;
+    reason: string;
+    timeoutMs?: number;
+    pollMs?: number;
+    sleep?: BatchSleep;
+}>;
+export type BatchRunLockReceipt = Readonly<{
+    run_path: string;
+    state_path: string;
+    lock_path: string;
+    identity_sha256: string;
+}>;
+export type BatchExclusiveKeyContext<TInput> = Readonly<{
+    item: TInput;
+    item_id: string;
+    item_contract: BatchItemContract;
+    input_index: number;
+}>;
+export type RunBoundedBatchOptions<TInput, TOutput, TIdentity extends BatchJsonValue, TExclusiveKey extends string = string> = Readonly<{
+    contract: BatchContract<TIdentity>;
+    items: readonly TInput[];
+    getItemIdentity: (item: TInput, inputIndex: number) => string;
+    projectItemContent: (item: TInput, inputIndex: number) => BatchJsonValue;
+    projectItemPolicy: (item: TInput, inputIndex: number) => BatchJsonValue;
+    getExclusiveKey?: (context: BatchExclusiveKeyContext<TInput>) => TExclusiveKey | null | undefined;
+    mode: BatchMode;
+    maxConcurrency: number;
+    execute: (context: BatchExecutionContext<TInput, TExclusiveKey>) => TOutput | Promise<TOutput>;
+    retry?: BatchRetryPolicy<TInput, TExclusiveKey>;
+    recoverMutation?: (context: BatchMutationRecoveryContext<TInput, TExclusiveKey>) => BatchMutationRecoveryResult<TOutput> | Promise<BatchMutationRecoveryResult<TOutput>>;
+    resume?: BatchResumeState<TOutput, TIdentity>;
+    shouldPauseBeforeClaim?: (context: BatchPauseContext<TInput, TOutput>) => boolean | Promise<boolean>;
+    shouldStop?: (context: BatchStopContext<TInput, TOutput>) => boolean | Promise<boolean>;
+    eventSink?: (event: BatchEvent) => void | Promise<void>;
+    clock?: BatchClock;
+    sleep?: BatchSleep;
+}>;
+export {};

package/dist/src/lib/batch/types.js

@@ -0,0 +1,2 @@
+export const MAX_BATCH_CONCURRENCY = 64;
+//# sourceMappingURL=types.js.map

package/dist/src/lib/batch/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../../src/lib/batch/types.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,qBAAqB,GAAG,EAAW,CAAC","sourcesContent":["export const MAX_BATCH_CONCURRENCY = 64 as const;\n\nexport type BatchJsonPrimitive = boolean | null | number | string;\nexport type BatchJsonValue = BatchJsonPrimitive | BatchJsonValue[] | BatchJsonObject;\nexport type BatchJsonObject = { [key: string]: BatchJsonValue };\n\nexport type BatchContract<TIdentity extends BatchJsonValue = BatchJsonValue> = {\n  identity: TIdentity;\n  content_sha256: string;\n  policy_sha256: string;\n};\n\nexport type BatchItemContract = Readonly<{\n  item_id: string;\n  content_sha256: string;\n  policy_sha256: string;\n}>;\n\nexport type CreateBatchItemContractOptions = Readonly<{\n  item_id: string;\n  content: BatchJsonValue;\n  policy: BatchJsonValue;\n}>;\n\nexport type CreateBatchContractOptions<TIdentity extends BatchJsonValue> = {\n  identity: TIdentity;\n  content: BatchJsonValue;\n  policy: BatchJsonValue;\n};\n\nexport type BatchMode = 'mutation' | 'read';\nexport type BatchStatus = 'completed' | 'paused' | 'stopped';\nexport type BatchItemSuccessStatus = 'recovered' | 'succeeded';\n\nexport type BatchEventType =\n  | 'attempt_failed'\n  | 'attempt_started'\n  | 'attempt_succeeded'\n  | 'batch_completed'\n  | 'batch_paused'\n  | 'batch_started'\n  | 'batch_stopped'\n  | 'item_claimed'\n  | 'item_completed'\n  | 'item_identity_drift'\n  | 'item_projection_drift'\n  | 'item_resource_acquired'\n  | 'item_resource_drift'\n  | 'item_resource_queued'\n  | 'item_resource_released'\n  | 'item_resume_rejected'\n  | 'item_resumed'\n  | 'recovery_failed'\n  | 'recovery_started'\n  | 'recovery_succeeded'\n  | 'retry_scheduled';\n\nexport type BatchEvent = Readonly<{\n  sequence: number;\n  timestamp_ms: number;\n  type: BatchEventType;\n  item_id?: string;\n  input_index?: number;\n  attempt?: number;\n  delay_ms?: number;\n  status?: BatchItemResultStatus | BatchStatus;\n  source?: BatchRecoverySource;\n  exclusive_key?: string;\n}>;\n\ntype BatchItemResultCommon<TInput> = Readonly<{\n  item: TInput;\n  item_id: string;\n  item_contract: BatchItemContract;\n  exclusive_key: string | null;\n  input_index: number;\n  attempts: number;\n  attempt_consumed: boolean;\n  resumed: boolean;\n  completed_at_ms: number;\n}>;\n\nexport type BatchItemSucceededResult<TInput, TOutput> = BatchItemResultCommon<TInput> &\n  Readonly<{\n    status: BatchItemSuccessStatus;\n    value: TOutput;\n  }>;\n\nexport type BatchItemFailedResult<TInput> = BatchItemResultCommon<TInput> &\n  Readonly<{\n    status: 'failed';\n    error: unknown;\n  }>;\n\nexport type BatchItemResultStatus = BatchItemSuccessStatus | 'failed';\nexport type BatchItemResult<TInput, TOutput> =\n  | BatchItemFailedResult<TInput>\n  | BatchItemSucceededResult<TInput, TOutput>;\n\nexport type BatchRunResult<\n  TInput,\n  TOutput,\n  TIdentity extends BatchJsonValue = BatchJsonValue,\n> = Readonly<{\n  contract: BatchContract<TIdentity>;\n  status: BatchStatus;\n  claim_order: readonly string[];\n  completion_order: readonly string[];\n  results_input_order: readonly BatchItemResult<TInput, TOutput>[];\n  results_completion_order: readonly BatchItemResult<TInput, TOutput>[];\n  unclaimed_item_ids: readonly string[];\n  events: readonly BatchEvent[];\n}>;\n\nexport type BatchExecutionContext<TInput, TExclusiveKey extends string = string> = Readonly<{\n  item: TInput;\n  item_id: string;\n  item_contract: BatchItemContract;\n  exclusive_key: TExclusiveKey | null;\n  input_index: number;\n  attempt: number;\n  mode: BatchMode;\n}>;\n\nexport type BatchRetryContext<\n  TInput,\n  TExclusiveKey extends string = string,\n> = BatchExecutionContext<TInput, TExclusiveKey> &\n  Readonly<{\n    error: unknown;\n  }>;\n\nexport type BatchRetryPolicy<TInput, TExclusiveKey extends string = string> = Readonly<{\n  maxAttempts: number;\n  maxDelayMs: number;\n  shouldRetry: (context: BatchRetryContext<TInput, TExclusiveKey>) => boolean | Promise<boolean>;\n  delayMs: (context: BatchRetryContext<TInput, TExclusiveKey>) => number | Promise<number>;\n}>;\n\nexport type BatchRecoverySource = 'execution_error' | 'resume_incomplete';\n\nexport type BatchMutationRecoveryContext<TInput, TExclusiveKey extends string = string> = Readonly<{\n  item: TInput;\n  item_id: string;\n  item_contract: BatchItemContract;\n  exclusive_key: TExclusiveKey | null;\n  input_index: number;\n  attempts: number;\n  error: unknown;\n  source: BatchRecoverySource;\n}>;\n\nexport type BatchMutationRecoveryResult<TOutput> =\n  | Readonly<{ status: 'recovered'; value: TOutput }>\n  | Readonly<{ status: 'unresolved'; error?: unknown }>;\n\nexport type BatchCompletedResumeItem<TOutput> = BatchItemContract &\n  Readonly<{\n    state: 'completed';\n    outcome: BatchItemSuccessStatus;\n    value: TOutput;\n    attempts: number;\n  }>;\n\nexport type BatchAttemptedResumeItem = BatchItemContract &\n  Readonly<{\n    state: 'attempted';\n    attempts: number;\n  }>;\n\nexport type BatchResumeItem<TOutput> = BatchAttemptedResumeItem | BatchCompletedResumeItem<TOutput>;\n\nexport type BatchResumeState<\n  TOutput,\n  TIdentity extends BatchJsonValue = BatchJsonValue,\n> = Readonly<{\n  contract: BatchContract<TIdentity>;\n  items: readonly BatchResumeItem<TOutput>[];\n}>;\n\nexport type BatchPauseContext<TInput, TOutput> = Readonly<{\n  item: TInput;\n  item_id: string;\n  item_contract: BatchItemContract;\n  exclusive_key: string | null;\n  input_index: number;\n  claimed_count: number;\n  results_input_order: readonly BatchItemResult<TInput, TOutput>[];\n}>;\n\nexport type BatchStopContext<TInput, TOutput> = Readonly<{\n  last_result: BatchItemResult<TInput, TOutput>;\n  claimed_count: number;\n  results_input_order: readonly BatchItemResult<TInput, TOutput>[];\n  results_completion_order: readonly BatchItemResult<TInput, TOutput>[];\n}>;\n\nexport type BatchClock = Readonly<{ now: () => number }>;\nexport type BatchSleep = (milliseconds: number) => Promise<void>;\n\nexport type BatchRunLockOptions<TIdentity extends BatchJsonValue> = Readonly<{\n  runPath: string;\n  identity: TIdentity;\n  reason: string;\n  timeoutMs?: number;\n  pollMs?: number;\n  sleep?: BatchSleep;\n}>;\n\nexport type BatchRunLockReceipt = Readonly<{\n  run_path: string;\n  state_path: string;\n  lock_path: string;\n  identity_sha256: string;\n}>;\n\nexport type BatchExclusiveKeyContext<TInput> = Readonly<{\n  item: TInput;\n  item_id: string;\n  item_contract: BatchItemContract;\n  input_index: number;\n}>;\n\nexport type RunBoundedBatchOptions<\n  TInput,\n  TOutput,\n  TIdentity extends BatchJsonValue,\n  TExclusiveKey extends string = string,\n> = Readonly<{\n  contract: BatchContract<TIdentity>;\n  items: readonly TInput[];\n  getItemIdentity: (item: TInput, inputIndex: number) => string;\n  projectItemContent: (item: TInput, inputIndex: number) => BatchJsonValue;\n  projectItemPolicy: (item: TInput, inputIndex: number) => BatchJsonValue;\n  getExclusiveKey?: (context: BatchExclusiveKeyContext<TInput>) => TExclusiveKey | null | undefined;\n  mode: BatchMode;\n  maxConcurrency: number;\n  execute: (context: BatchExecutionContext<TInput, TExclusiveKey>) => TOutput | Promise<TOutput>;\n  retry?: BatchRetryPolicy<TInput, TExclusiveKey>;\n  recoverMutation?: (\n    context: BatchMutationRecoveryContext<TInput, TExclusiveKey>,\n  ) => BatchMutationRecoveryResult<TOutput> | Promise<BatchMutationRecoveryResult<TOutput>>;\n  resume?: BatchResumeState<TOutput, TIdentity>;\n  shouldPauseBeforeClaim?: (\n    context: BatchPauseContext<TInput, TOutput>,\n  ) => boolean | Promise<boolean>;\n  shouldStop?: (context: BatchStopContext<TInput, TOutput>) => boolean | Promise<boolean>;\n  eventSink?: (event: BatchEvent) => void | Promise<void>;\n  clock?: BatchClock;\n  sleep?: BatchSleep;\n}>;\n"]}

package/dist/src/lib/dataset-author.d.ts

@@ -0,0 +1,39 @@
+import { runDatasetContract, type DatasetContractReport } from './dataset-contract.js';
+import { parseUnstructuredDocument } from './unstructured.js';
+import type { FetchLike } from './http.js';
+export type DatasetAuthorReport = {
+    schema_version: 1;
+    status: 'evidence_ready';
+    generated_at_utc: string;
+    input_path: string;
+    target_types: string[];
+    files: {
+        source_extract: string;
+        authoring_report: string;
+    };
+    context_packs: Array<{
+        type: string;
+        report: DatasetContractReport;
+    }>;
+    next_actions: string[];
+};
+export type RunDatasetAuthorOptions = {
+    inputPath: string;
+    targetTypes: string | string[] | undefined;
+    outDir: string | null | undefined;
+    prompt?: string | undefined;
+    provider?: string | undefined;
+    model?: string | undefined;
+    timeoutMs?: number | undefined;
+    env: NodeJS.ProcessEnv;
+    fetchImpl: FetchLike;
+    now?: Date | undefined;
+    parseImpl?: typeof parseUnstructuredDocument | undefined;
+    contractImpl?: typeof runDatasetContract | undefined;
+};
+export declare function runDatasetAuthor(options: RunDatasetAuthorOptions): Promise<DatasetAuthorReport>;
+declare function normalizeTargetTypes(value: string | string[] | undefined): string[];
+export declare const __testInternals: {
+    normalizeTargetTypes: typeof normalizeTargetTypes;
+};
+export {};