@loomwork/plugin-content 0.0.0-stage → 0.1.0

package/dist/derive.d.ts

@@ -0,0 +1,9 @@
+import type { StepDefinition } from "@loomwork/core";
+/**
+ * Build the {@link ContentResolvingEventStore} `externalize` map from step definitions: every
+ * field marked `externalized()` in a step's `outputSchema` becomes a `STEP_COMPLETED` dot-path
+ * `output.<path>`. Paths are unioned + O(n) de-duplicated across steps; an empty map when
+ * nothing is marked (zero-overhead unwired path, G2).
+ */
+export declare function externalizePathsFromSteps(steps: readonly Pick<StepDefinition, "outputSchema">[]): Record<string, string[]>;
+//# sourceMappingURL=derive.d.ts.map

package/dist/derive.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"derive.d.ts","sourceRoot":"","sources":["../src/derive.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAarD;;;;;GAKG;AACH,wBAAgB,yBAAyB,CAGvC,KAAK,EAAE,SAAS,IAAI,CAAC,cAAc,EAAE,cAAc,CAAC,EAAE,GACrD,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAe1B"}

package/dist/derive.js

@@ -0,0 +1,40 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.externalizePathsFromSteps = externalizePathsFromSteps;
+const classify_1 = require("@loomwork/classify");
+// ── ADR 0046 — derive the externalize map from `externalized()` marks ──────────
+//
+// Mark a field once — `doc: externalized(z.object({...}))` — and derive the
+// ContentResolvingEventStore `externalize` map, instead of hand-authoring
+// `{ STEP_COMPLETED: ["output.doc"] }`. Mirrors `sensitivePathsFromSteps` (crypto): a step's
+// output is stored under `output.*` in STEP_COMPLETED, so an externalized output field
+// contributes `STEP_COMPLETED → "output.<path>"`.
+/** The STEP_COMPLETED payload nests a step's output under this key. */
+const OUTPUT_PREFIX = "output";
+/**
+ * Build the {@link ContentResolvingEventStore} `externalize` map from step definitions: every
+ * field marked `externalized()` in a step's `outputSchema` becomes a `STEP_COMPLETED` dot-path
+ * `output.<path>`. Paths are unioned + O(n) de-duplicated across steps; an empty map when
+ * nothing is marked (zero-overhead unwired path, G2).
+ */
+function externalizePathsFromSteps(
+// Only the output schema is read; Pick drops the invariant handler field so concrete
+// `StepDefinition<In, Out>` values pass without a cast.
+steps) {
+    const seen = new Set();
+    const stepCompleted = [];
+    for (const step of steps) {
+        const schema = step.outputSchema;
+        if (schema === undefined)
+            continue;
+        for (const path of (0, classify_1.externalizedPaths)(schema)) {
+            const dotted = `${OUTPUT_PREFIX}.${path}`;
+            if (!seen.has(dotted)) {
+                seen.add(dotted);
+                stepCompleted.push(dotted);
+            }
+        }
+    }
+    return stepCompleted.length > 0 ? { STEP_COMPLETED: stepCompleted } : {};
+}
+//# sourceMappingURL=derive.js.map

package/dist/derive.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"derive.js","sourceRoot":"","sources":["../src/derive.ts"],"names":[],"mappings":";;AAoBA,8DAmBC;AAvCD,iDAAuD;AAGvD,kFAAkF;AAClF,EAAE;AACF,4EAA4E;AAC5E,0EAA0E;AAC1E,6FAA6F;AAC7F,uFAAuF;AACvF,kDAAkD;AAElD,uEAAuE;AACvE,MAAM,aAAa,GAAG,QAAQ,CAAC;AAE/B;;;;;GAKG;AACH,SAAgB,yBAAyB;AACvC,qFAAqF;AACrF,wDAAwD;AACxD,KAAsD;IAEtD,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;IAC/B,MAAM,aAAa,GAAa,EAAE,CAAC;IACnC,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,MAAM,MAAM,GAAG,IAAI,CAAC,YAAY,CAAC;QACjC,IAAI,MAAM,KAAK,SAAS;YAAE,SAAS;QACnC,KAAK,MAAM,IAAI,IAAI,IAAA,4BAAiB,EAAC,MAAM,CAAC,EAAE,CAAC;YAC7C,MAAM,MAAM,GAAG,GAAG,aAAa,IAAI,IAAI,EAAE,CAAC;YAC1C,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC;gBACtB,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;gBACjB,aAAa,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;YAC7B,CAAC;QACH,CAAC;IACH,CAAC;IACD,OAAO,aAAa,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,cAAc,EAAE,aAAa,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;AAC3E,CAAC"}

package/dist/errors.d.ts

@@ -0,0 +1,6 @@
+export declare class ContentMissingError extends Error {
+    readonly contentAddress: string;
+    readonly executionId?: string | undefined;
+    constructor(contentAddress: string, executionId?: string | undefined);
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAMA,qBAAa,mBAAoB,SAAQ,KAAK;IAE1C,QAAQ,CAAC,cAAc,EAAE,MAAM;IAC/B,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM;gBADpB,cAAc,EAAE,MAAM,EACtB,WAAW,CAAC,EAAE,MAAM,YAAA;CAShC"}

package/dist/errors.js

@@ -0,0 +1,20 @@
+"use strict";
+// ── ADR 0046 — loud on absence (the generalized PAYLOAD_SHREDDED contract) ─────
+//
+// A fold that needs an externalized value whose bytes were erased (or never stored) must fail
+// LOUDLY — never silently substitute a default and diverge (G1). This mirrors the crypto
+// plugin's `PayloadShreddedError`: the value is gone, so replay of it cannot proceed.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ContentMissingError = void 0;
+class ContentMissingError extends Error {
+    contentAddress;
+    executionId;
+    constructor(contentAddress, executionId) {
+        super(`externalized content "${contentAddress}"${executionId ? ` (execution "${executionId}")` : ""} is missing: the bytes were erased or never stored, so replay cannot restore this value`);
+        this.contentAddress = contentAddress;
+        this.executionId = executionId;
+        this.name = "ContentMissingError";
+    }
+}
+exports.ContentMissingError = ContentMissingError;
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":";AAAA,kFAAkF;AAClF,EAAE;AACF,8FAA8F;AAC9F,yFAAyF;AACzF,sFAAsF;;;AAEtF,MAAa,mBAAoB,SAAQ,KAAK;IAEjC;IACA;IAFX,YACW,cAAsB,EACtB,WAAoB;QAE7B,KAAK,CACH,yBAAyB,cAAc,IACrC,WAAW,CAAC,CAAC,CAAC,gBAAgB,WAAW,IAAI,CAAC,CAAC,CAAC,EAClD,yFAAyF,CAC1F,CAAC;QAPO,mBAAc,GAAd,cAAc,CAAQ;QACtB,gBAAW,GAAX,WAAW,CAAS;QAO7B,IAAI,CAAC,IAAI,GAAG,qBAAqB,CAAC;IACpC,CAAC;CACF;AAZD,kDAYC"}

package/dist/executionEnd.d.ts

@@ -0,0 +1,22 @@
+import type { EventEnvelope } from "@loomwork/core";
+/**
+ * ADR 0146 - when did this execution END, as far as the live log can tell? The `at` of its newest
+ * kernel terminal event, or `undefined` when it has not ended: no terminal event, or it was RE-OPENED
+ * after its newest one (`resumeAs` appends EXECUTION_RESUMED to a terminal execution; a later
+ * EXECUTION_SUSPENDED / EXECUTION_STARTED likewise means live). `undefined` makes the sweep fall back
+ * to the citation clock, so every uncertainty can only age a ref LATER or equal, never earlier.
+ *
+ * The terminal set is the one `@loomwork/workflow-runtime`'s `terminalEndedAt` uses (and the replay VM's
+ * `isKernelWritten` check for EXECUTION_CONTINUED); it is duplicated, not imported, so this package
+ * takes no dependency on workflow-runtime. `gc.endClock.test.ts` (l) pins it against the ReplayVM.
+ * Scans from the tail in sequence order (not timestamp order), usually stopping within a few events.
+ */
+export declare function terminalEndOf(events: readonly EventEnvelope[]): number | undefined;
+/**
+ * ADR 0146 - was this execution RE-OPENED after a terminal event? True iff its tail is live
+ * (`terminalEndOf` returns `undefined` because a RESUMED / SUSPENDED / STARTED follows) AND a terminal
+ * event (the same set as `terminalEndOf`) precedes that live tail. A run that never ended is false.
+ * A terminal event with a non-finite timestamp still counts as an end here (the log shows it ended).
+ */
+export declare function wasReopened(events: readonly EventEnvelope[]): boolean;
+//# sourceMappingURL=executionEnd.d.ts.map

package/dist/executionEnd.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"executionEnd.d.ts","sourceRoot":"","sources":["../src/executionEnd.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAOpD;;;;;;;;;;;GAWG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,SAAS,aAAa,EAAE,GAAG,MAAM,GAAG,SAAS,CAiBlF;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,SAAS,aAAa,EAAE,GAAG,OAAO,CAmBrE"}

package/dist/executionEnd.js

@@ -0,0 +1,66 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.terminalEndOf = terminalEndOf;
+exports.wasReopened = wasReopened;
+// A terminal timestamp that is not a finite number (NaN, a string from an imported log or a 3P store,
+// +-Infinity, null) is not comparable: treat the execution as not ended so the citation clock applies.
+const finiteOrUndefined = (t) => typeof t === "number" && Number.isFinite(t) ? t : undefined;
+/**
+ * ADR 0146 - when did this execution END, as far as the live log can tell? The `at` of its newest
+ * kernel terminal event, or `undefined` when it has not ended: no terminal event, or it was RE-OPENED
+ * after its newest one (`resumeAs` appends EXECUTION_RESUMED to a terminal execution; a later
+ * EXECUTION_SUSPENDED / EXECUTION_STARTED likewise means live). `undefined` makes the sweep fall back
+ * to the citation clock, so every uncertainty can only age a ref LATER or equal, never earlier.
+ *
+ * The terminal set is the one `@loomwork/workflow-runtime`'s `terminalEndedAt` uses (and the replay VM's
+ * `isKernelWritten` check for EXECUTION_CONTINUED); it is duplicated, not imported, so this package
+ * takes no dependency on workflow-runtime. `gc.endClock.test.ts` (l) pins it against the ReplayVM.
+ * Scans from the tail in sequence order (not timestamp order), usually stopping within a few events.
+ */
+function terminalEndOf(events) {
+    for (let i = events.length - 1; i >= 0; i--) {
+        const e = events[i];
+        switch (e.eventType) {
+            case "EXECUTION_RESUMED":
+            case "EXECUTION_SUSPENDED":
+            case "EXECUTION_STARTED":
+                return undefined;
+            case "EXECUTION_COMPLETED":
+            case "EXECUTION_FAILED":
+            case "EXECUTION_CANCELLED":
+                return finiteOrUndefined(e.timestamp);
+            case "EXECUTION_CONTINUED":
+                if (e.metadata?.kernel === true)
+                    return finiteOrUndefined(e.timestamp);
+        }
+    }
+    return undefined;
+}
+/**
+ * ADR 0146 - was this execution RE-OPENED after a terminal event? True iff its tail is live
+ * (`terminalEndOf` returns `undefined` because a RESUMED / SUSPENDED / STARTED follows) AND a terminal
+ * event (the same set as `terminalEndOf`) precedes that live tail. A run that never ended is false.
+ * A terminal event with a non-finite timestamp still counts as an end here (the log shows it ended).
+ */
+function wasReopened(events) {
+    let live = false;
+    for (let i = events.length - 1; i >= 0; i--) {
+        const e = events[i];
+        switch (e.eventType) {
+            case "EXECUTION_RESUMED":
+            case "EXECUTION_SUSPENDED":
+            case "EXECUTION_STARTED":
+                live = true;
+                break;
+            case "EXECUTION_COMPLETED":
+            case "EXECUTION_FAILED":
+            case "EXECUTION_CANCELLED":
+                return live;
+            case "EXECUTION_CONTINUED":
+                if (e.metadata?.kernel === true)
+                    return live;
+        }
+    }
+    return false;
+}
+//# sourceMappingURL=executionEnd.js.map

package/dist/executionEnd.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"executionEnd.js","sourceRoot":"","sources":["../src/executionEnd.ts"],"names":[],"mappings":";;AAmBA,sCAiBC;AAQD,kCAmBC;AA7DD,sGAAsG;AACtG,uGAAuG;AACvG,MAAM,iBAAiB,GAAG,CAAC,CAAU,EAAsB,EAAE,CAC3D,OAAO,CAAC,KAAK,QAAQ,IAAI,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;AAE9D;;;;;;;;;;;GAWG;AACH,SAAgB,aAAa,CAAC,MAAgC;IAC5D,KAAK,IAAI,CAAC,GAAG,MAAM,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;QAC5C,MAAM,CAAC,GAAG,MAAM,CAAC,CAAC,CAAkB,CAAC;QACrC,QAAQ,CAAC,CAAC,SAAS,EAAE,CAAC;YACpB,KAAK,mBAAmB,CAAC;YACzB,KAAK,qBAAqB,CAAC;YAC3B,KAAK,mBAAmB;gBACtB,OAAO,SAAS,CAAC;YACnB,KAAK,qBAAqB,CAAC;YAC3B,KAAK,kBAAkB,CAAC;YACxB,KAAK,qBAAqB;gBACxB,OAAO,iBAAiB,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC;YACxC,KAAK,qBAAqB;gBACxB,IAAI,CAAC,CAAC,QAAQ,EAAE,MAAM,KAAK,IAAI;oBAAE,OAAO,iBAAiB,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC;QAC3E,CAAC;IACH,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC;AAED;;;;;GAKG;AACH,SAAgB,WAAW,CAAC,MAAgC;IAC1D,IAAI,IAAI,GAAG,KAAK,CAAC;IACjB,KAAK,IAAI,CAAC,GAAG,MAAM,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;QAC5C,MAAM,CAAC,GAAG,MAAM,CAAC,CAAC,CAAkB,CAAC;QACrC,QAAQ,CAAC,CAAC,SAAS,EAAE,CAAC;YACpB,KAAK,mBAAmB,CAAC;YACzB,KAAK,qBAAqB,CAAC;YAC3B,KAAK,mBAAmB;gBACtB,IAAI,GAAG,IAAI,CAAC;gBACZ,MAAM;YACR,KAAK,qBAAqB,CAAC;YAC3B,KAAK,kBAAkB,CAAC;YACxB,KAAK,qBAAqB;gBACxB,OAAO,IAAI,CAAC;YACd,KAAK,qBAAqB;gBACxB,IAAI,CAAC,CAAC,QAAQ,EAAE,MAAM,KAAK,IAAI;oBAAE,OAAO,IAAI,CAAC;QACjD,CAAC;IACH,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC"}