@workglow/task-graph 0.2.36 → 0.3.0

package/dist/cache/CacheJanitor.d.ts

@@ -0,0 +1,27 @@
+/**
+ * @license
+ * Copyright 2026 Steven Roussey <sroussey@gmail.com>
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { TaskOutputRepository } from "../storage/TaskOutputRepository";
+export interface CacheJanitorOptions {
+    privateBacking: TaskOutputRepository;
+}
+/**
+ * Periodic cleanup helper for run-private cache entries left behind by runs
+ * that crashed and were never restarted.
+ *
+ * Run-private rows are namespaced by `RunPrivateCacheRepo` with the taskType
+ * prefix `__run:`. This janitor sweeps those rows when they are older than
+ * `olderThanMs`. Entries lacking the prefix (deterministic cache, shared tier)
+ * are not touched.
+ *
+ * Apps schedule the sweep themselves (cron, periodic worker, on startup) —
+ * libs does not run it automatically.
+ */
+export declare class CacheJanitor {
+    private readonly privateBacking;
+    constructor({ privateBacking }: CacheJanitorOptions);
+    sweepStaleRunPrivate(olderThanMs: number): Promise<void>;
+}
+//# sourceMappingURL=CacheJanitor.d.ts.map

package/dist/cache/CacheJanitor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CacheJanitor.d.ts","sourceRoot":"","sources":["../../src/cache/CacheJanitor.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,iCAAiC,CAAC;AAE5E,MAAM,WAAW,mBAAmB;IAClC,cAAc,EAAE,oBAAoB,CAAC;CACtC;AAED;;;;;;;;;;;GAWG;AACH,qBAAa,YAAY;IACvB,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAuB;IAEtD,YAAY,EAAE,cAAc,EAAE,EAAE,mBAAmB,EAElD;IAEK,oBAAoB,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAE7D;CACF"}

package/dist/cache/CachePolicy.d.ts

@@ -0,0 +1,16 @@
+/**
+ * @license
+ * Copyright 2026 Steven Roussey <sroussey@gmail.com>
+ * SPDX-License-Identifier: Apache-2.0
+ */
+export type CachePolicy = {
+    kind: "deterministic";
+} | {
+    kind: "private";
+} | {
+    kind: "none";
+};
+export declare const DEFAULT_CACHE_POLICY: CachePolicy;
+export declare function isPolicyCached(policy: CachePolicy): boolean;
+export declare function isPolicyPrivate(policy: CachePolicy): boolean;
+//# sourceMappingURL=CachePolicy.d.ts.map

package/dist/cache/CachePolicy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CachePolicy.d.ts","sourceRoot":"","sources":["../../src/cache/CachePolicy.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,MAAM,MAAM,WAAW,GAAG;IAAE,IAAI,EAAE,eAAe,CAAA;CAAE,GAAG;IAAE,IAAI,EAAE,SAAS,CAAA;CAAE,GAAG;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC;AAE7F,eAAO,MAAM,oBAAoB,EAAE,WAAuC,CAAC;AAE3E,wBAAgB,cAAc,CAAC,MAAM,EAAE,WAAW,GAAG,OAAO,CAE3D;AAED,wBAAgB,eAAe,CAAC,MAAM,EAAE,WAAW,GAAG,OAAO,CAE5D"}

package/dist/cache/CacheRegistry.d.ts

@@ -0,0 +1,30 @@
+/**
+ * @license
+ * Copyright 2026 Steven Roussey <sroussey@gmail.com>
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { TaskOutputRepository } from "../storage/TaskOutputRepository";
+/**
+ * Two-slot registry of task output repositories selected by `CachePolicy.kind`.
+ *
+ * - `deterministic` — shared cache for tasks whose outputs are determined entirely
+ *   by their inputs. Same inputs → same outputs, safe to share across runs and
+ *   (in app deployments like builder) across projects.
+ * - `private` — per-run cache for tasks producing non-deterministic outputs worth
+ *   keeping (e.g., image generation without a seed). Namespaced by `runId` so
+ *   two runs of the same workflow do not see each other's data.
+ *
+ * Both slots are optional. When a slot is unset, caching for matching tasks is
+ * a silent no-op — the task still runs correctly, just uncached.
+ */
+export interface CacheRegistry {
+    deterministic?: TaskOutputRepository;
+    private?: TaskOutputRepository;
+}
+export declare const CACHE_REGISTRY: import("@workglow/util").ServiceToken<CacheRegistry>;
+export declare class DefaultCacheRegistry implements CacheRegistry {
+    deterministic?: TaskOutputRepository;
+    private?: TaskOutputRepository;
+    constructor(init?: Partial<CacheRegistry>);
+}
+//# sourceMappingURL=CacheRegistry.d.ts.map

package/dist/cache/CacheRegistry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CacheRegistry.d.ts","sourceRoot":"","sources":["../../src/cache/CacheRegistry.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,iCAAiC,CAAC;AAE5E;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,aAAa;IAC5B,aAAa,CAAC,EAAE,oBAAoB,CAAC;IACrC,OAAO,CAAC,EAAE,oBAAoB,CAAC;CAChC;AAED,eAAO,MAAM,cAAc,sDAA+D,CAAC;AAE3F,qBAAa,oBAAqB,YAAW,aAAa;IACjD,aAAa,CAAC,EAAE,oBAAoB,CAAC;IACrC,OAAO,CAAC,EAAE,oBAAoB,CAAC;IAEtC,YAAY,IAAI,GAAE,OAAO,CAAC,aAAa,CAAM,EAG5C;CACF"}

package/dist/cache/RunPrivateCacheRepo.d.ts

@@ -0,0 +1,56 @@
+/**
+ * @license
+ * Copyright 2026 Steven Roussey <sroussey@gmail.com>
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { TaskOutputRepository } from "../storage/TaskOutputRepository";
+import type { TaskInput, TaskOutput } from "../task/TaskTypes";
+export interface RunPrivateCacheRepoOptions {
+    backing: TaskOutputRepository;
+    runId: string;
+}
+/**
+ * Wraps a TaskOutputRepository so that all entries are namespaced by `runId`.
+ *
+ * Namespacing happens at the `taskType` axis: rows are stored as
+ * `__run:${runId}::${taskType}` in the backing store. The input fingerprint is
+ * unchanged, so deterministic-style keying still works.
+ *
+ * - Two wrappers with the same `runId` (e.g., a restart after a crash) see each
+ *   other's writes via the backing store — that's the restart-survival contract.
+ * - Two wrappers with different `runId`s see only their own entries.
+ */
+export declare class RunPrivateCacheRepo extends TaskOutputRepository {
+    private readonly backing;
+    private readonly runId;
+    constructor({ backing, runId }: RunPrivateCacheRepoOptions);
+    private ns;
+    saveOutput(taskType: string, inputs: TaskInput, output: TaskOutput, createdAt?: Date): Promise<void>;
+    getOutput(taskType: string, inputs: TaskInput): Promise<TaskOutput | undefined>;
+    /**
+     * Override of `TaskOutputRepository.clear()` that only deletes entries
+     * namespaced under THIS wrapper's `runId`. Entries from other runs are not
+     * touched. Use the backing repository directly if you need a global clear.
+     */
+    clear(): Promise<void>;
+    /**
+     * Delete every entry written through this wrapper's `runId`. Called by the
+     * graph runner after a successful run, and by the janitor for stale runs.
+     * Requires the backing repository to implement `deleteByTaskTypePrefix`.
+     */
+    clearRun(): Promise<void>;
+    /**
+     * Returns the count of entries namespaced under THIS wrapper's `runId`.
+     * Consistent with `saveOutput`/`getOutput`/`clear()` being run-scoped.
+     */
+    size(): Promise<number>;
+    /**
+     * Override of `TaskOutputRepository.clearOlderThan()` scoped to THIS
+     * wrapper's `runId`. Without the scope override, the wrapper would
+     * accidentally prune the entire backing store (including deterministic
+     * cache entries and other runs' private rows).
+     */
+    clearOlderThan(olderThanInMs: number): Promise<void>;
+    isDurable(): boolean;
+}
+//# sourceMappingURL=RunPrivateCacheRepo.d.ts.map

package/dist/cache/RunPrivateCacheRepo.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"RunPrivateCacheRepo.d.ts","sourceRoot":"","sources":["../../src/cache/RunPrivateCacheRepo.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,oBAAoB,EAAE,MAAM,iCAAiC,CAAC;AACvE,OAAO,KAAK,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAE/D,MAAM,WAAW,0BAA0B;IACzC,OAAO,EAAE,oBAAoB,CAAC;IAC9B,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;;;;;;;;;GAUG;AACH,qBAAa,mBAAoB,SAAQ,oBAAoB;IAC3D,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAuB;IAC/C,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAS;IAE/B,YAAY,EAAE,OAAO,EAAE,KAAK,EAAE,EAAE,0BAA0B,EAIzD;IAED,OAAO,CAAC,EAAE;IAIG,UAAU,CACrB,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,SAAS,EACjB,MAAM,EAAE,UAAU,EAClB,SAAS,CAAC,EAAE,IAAI,GACf,OAAO,CAAC,IAAI,CAAC,CAEf;IAEY,SAAS,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,GAAG,OAAO,CAAC,UAAU,GAAG,SAAS,CAAC,CAE3F;IAED;;;;OAIG;IACU,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAElC;IAED;;;;OAIG;IACU,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC,CAErC;IAED;;;OAGG;IACU,IAAI,IAAI,OAAO,CAAC,MAAM,CAAC,CAEnC;IAED;;;;;OAKG;IACU,cAAc,CAAC,aAAa,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAEhE;IAEM,SAAS,IAAI,OAAO,CAE1B;CACF"}

package/dist/cache/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * @license
+ * Copyright 2026 Steven Roussey <sroussey@gmail.com>
+ * SPDX-License-Identifier: Apache-2.0
+ */
+export * from "./CacheJanitor";
+export * from "./CachePolicy";
+export * from "./CacheRegistry";
+export * from "./RunPrivateCacheRepo";
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/cache/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,cAAc,gBAAgB,CAAC;AAC/B,cAAc,eAAe,CAAC;AAC9B,cAAc,iBAAiB,CAAC;AAChC,cAAc,uBAAuB,CAAC"}

package/dist/common.d.ts

@@ -31,6 +31,7 @@ export * from "./task-graph/TransformRegistry";
 export * from "./task-graph/TransformTypes";
 export * from "./task-graph/transforms";
 export * from "./task-graph/autoConnect";
+export * from "./cache";
 export * from "./task/CacheCoordinator";
 export * from "./task/StreamProcessor";
 export * from "./task/TaskRunContext";

package/dist/common.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"common.d.ts","sourceRoot":"","sources":["../src/common.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH,cAAc,uBAAuB,CAAC;AACtC,cAAc,6BAA6B,CAAC;AAE5C,cAAc,oCAAoC,CAAC;AACnD,cAAc,iCAAiC,CAAC;AAChD,cAAc,+BAA+B,CAAC;AAC9C,cAAc,yBAAyB,CAAC;AACxC,cAAc,wBAAwB,CAAC;AACvC,cAAc,8BAA8B,CAAC;AAC7C,cAAc,+BAA+B,CAAC;AAC9C,cAAc,yBAAyB,CAAC;AACxC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,yBAAyB,CAAC;AACxC,cAAc,8BAA8B,CAAC;AAE7C,cAAc,0BAA0B,CAAC;AACzC,cAAc,kCAAkC,CAAC;AACjD,cAAc,wBAAwB,CAAC;AACvC,cAAc,iCAAiC,CAAC;AAChD,cAAc,uBAAuB,CAAC;AACtC,cAAc,8BAA8B,CAAC;AAC7C,cAAc,mCAAmC,CAAC;AAClD,cAAc,kCAAkC,CAAC;AACjD,cAAc,gCAAgC,CAAC;AAC/C,cAAc,2BAA2B,CAAC;AAC1C,cAAc,iCAAiC,CAAC;AAEhD,cAAc,gCAAgC,CAAC;AAC/C,cAAc,6BAA6B,CAAC;AAC5C,cAAc,yBAAyB,CAAC;AACxC,cAAc,0BAA0B,CAAC;AAEzC,cAAc,yBAAyB,CAAC;AACxC,cAAc,wBAAwB,CAAC;AACvC,cAAc,uBAAuB,CAAC;AACtC,cAAc,QAAQ,CAAC;AAEvB,cAAc,+BAA+B,CAAC;AAC9C,cAAc,sCAAsC,CAAC;AACrD,cAAc,gCAAgC,CAAC;AAC/C,cAAc,uCAAuC,CAAC;AACtD,OAAO,EACL,iBAAiB,EACjB,YAAY,EACZ,wBAAwB,GACzB,MAAM,6BAA6B,CAAC;AACrC,YAAY,EAAE,SAAS,EAAE,MAAM,6BAA6B,CAAC"}
+{"version":3,"file":"common.d.ts","sourceRoot":"","sources":["../src/common.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH,cAAc,uBAAuB,CAAC;AACtC,cAAc,6BAA6B,CAAC;AAE5C,cAAc,oCAAoC,CAAC;AACnD,cAAc,iCAAiC,CAAC;AAChD,cAAc,+BAA+B,CAAC;AAC9C,cAAc,yBAAyB,CAAC;AACxC,cAAc,wBAAwB,CAAC;AACvC,cAAc,8BAA8B,CAAC;AAC7C,cAAc,+BAA+B,CAAC;AAC9C,cAAc,yBAAyB,CAAC;AACxC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,yBAAyB,CAAC;AACxC,cAAc,8BAA8B,CAAC;AAE7C,cAAc,0BAA0B,CAAC;AACzC,cAAc,kCAAkC,CAAC;AACjD,cAAc,wBAAwB,CAAC;AACvC,cAAc,iCAAiC,CAAC;AAChD,cAAc,uBAAuB,CAAC;AACtC,cAAc,8BAA8B,CAAC;AAC7C,cAAc,mCAAmC,CAAC;AAClD,cAAc,kCAAkC,CAAC;AACjD,cAAc,gCAAgC,CAAC;AAC/C,cAAc,2BAA2B,CAAC;AAC1C,cAAc,iCAAiC,CAAC;AAEhD,cAAc,gCAAgC,CAAC;AAC/C,cAAc,6BAA6B,CAAC;AAC5C,cAAc,yBAAyB,CAAC;AACxC,cAAc,0BAA0B,CAAC;AAEzC,cAAc,SAAS,CAAC;AACxB,cAAc,yBAAyB,CAAC;AACxC,cAAc,wBAAwB,CAAC;AACvC,cAAc,uBAAuB,CAAC;AACtC,cAAc,QAAQ,CAAC;AAEvB,cAAc,+BAA+B,CAAC;AAC9C,cAAc,sCAAsC,CAAC;AACrD,cAAc,gCAAgC,CAAC;AAC/C,cAAc,uCAAuC,CAAC;AACtD,OAAO,EACL,iBAAiB,EACjB,YAAY,EACZ,wBAAwB,GACzB,MAAM,6BAA6B,CAAC;AACrC,YAAY,EAAE,SAAS,EAAE,MAAM,6BAA6B,CAAC"}