@smthrs/engine-store 0.0.0-stage → 1.0.0-rc.4

package/dist/esm/internal/ExitEncoding.js

@@ -0,0 +1,361 @@
+/**
+ * Encoding a round's settlement so a terminal transition can never be lost.
+ *
+ * A run row leaves `running` only when the driver has bytes to write into
+ * `state_json`, and those bytes come from the flow's OWN codec:
+ * `Flow.Result({ success: flow.successSchema, error: flow.errorSchema })`.
+ * A flow that declares `Schema.Unknown` for either channel — which is what
+ * `@smthrs/agent`'s `agent/run` declares, because an agent run carries
+ * whatever its body failed with — encodes that channel through `Schema.Json`,
+ * and `Schema.Json` rejects every class instance: `SchemaAST.isJson` walks the
+ * prototype chain and refuses anything that is not a plain object or an array.
+ * Every `Data.TaggedError` in this repository is therefore unencodable through
+ * such a flow, `HarnessError` and `ModelError` included.
+ *
+ * Guarding the terminal transition with `Effect.orDie` around that encode made
+ * an unencodable failure fatal for the drain instead of terminal for the run.
+ * The release validation caught the whole chain: `engine-store: coordinated
+ * drain failed for run-1 SchemaError: Expected JSON value at
+ * ["exit"]["cause"][0]["error"]`, `engine.db` `flows_runs` left at `running`
+ * with a dead owner pid while `control.db` said `failed`, and 86 seconds later
+ * the next process's stale-running sweep stole the row, opened a second turn,
+ * and billed the provider seat again for a run the control plane had closed.
+ *
+ * So the encode fails CLOSED here rather than open. The ordinary path is the
+ * flow's own codec, unchanged. When that codec rejects the value, the result
+ * is still written — as a JSON projection of what could not be encoded (tag,
+ * code, message, a stack summary, and nested causes) inside a `Die` reason —
+ * and the caller is told, through {@link EncodedResult.note}, that it must
+ * settle the run `failed`. A settled run is never re-executed, which is the
+ * durability promise the release policy states as one terminal write.
+ *
+ * The projection is built as plain JSON rather than re-encoded through a
+ * schema, so nothing in this module can raise. Its top-level object carries no
+ * `message` key on purpose: `Schema.Defect` revives any JSON object that has a
+ * string `message` as an `Error`, and a projection has to come back out of the
+ * row as the structured record it went in as.
+ *
+ * @since 0.1.0
+ */
+import { Flow } from "@smthrs/flow";
+import { Redaction } from "@smthrs/journal";
+import * as Effect from "effect/Effect";
+import * as Exit from "effect/Exit";
+import * as Schema from "effect/Schema";
+import * as HostReflection from "./HostReflection.js";
+/**
+ * Proxy and native-error detection, taken from the host that can answer them.
+ *
+ * `./HostReflection.ts` states why these are host predicates rather than a
+ * `node:util/types` import: the module has to bundle for a browser, and only
+ * some hosts can name a proxy at all.
+ */
+const { isNativeError, isProxy } = HostReflection.host;
+/**
+ * The `_tag` every projection carries, so a reader of `state_json` can tell a
+ * projected settlement from an encoded one without guessing.
+ *
+ * @since 0.1.0
+ * @category constants
+ */
+export const projectionTag = "flows/engine-store/UnencodableResult";
+/**
+ * How many `cause` links a value projection follows before it stops.
+ *
+ * A provider failure nests two or three deep (`HarnessError` over
+ * `ModelError` over the transport error); the bound exists so a self-linking
+ * cause chain cannot make the projection unbounded.
+ *
+ * @since 0.1.0
+ * @category constants
+ */
+export const maxCauseDepth = 4;
+/**
+ * How many leading stack lines a value projection keeps.
+ *
+ * @since 0.1.0
+ * @category constants
+ */
+export const maxStackLines = 4;
+/**
+ * How many characters any single projected string keeps.
+ *
+ * @since 0.1.0
+ * @category constants
+ */
+export const maxTextLength = 1024;
+/**
+ * Maximum cause reasons retained by the terminal fallback.
+ *
+ * @category constants
+ * @since 1.0.0
+ */
+export const maxReasonCount = 32;
+/**
+ * Maximum serialized bytes retained by one fallback projection.
+ *
+ * @category constants
+ * @since 1.0.0
+ */
+export const maxProjectionBytes = 64 * 1024;
+const truncate = (value, limit) => value.length <= limit ? value : `${value.slice(0, limit)}…`;
+/**
+ * Bounds one projected message or stack after the journal's redaction rules.
+ *
+ * The projection is observability text in `flows_runs.state_json`, and a git or
+ * HTTP failure message embeds its remote URL, credentials included. Redaction
+ * runs before truncation so a cut cannot leave half a credential the rules no
+ * longer match.
+ */
+const redactedText = (value) => truncate(Redaction.redact(value), maxTextLength);
+/**
+ * Renders any value as a bounded string without raising.
+ *
+ * `JSON.stringify` answers `undefined` for a function, a symbol, and
+ * `undefined` itself, and throws on a circular structure; both are answered
+ * with a shape marker rather than propagated, because this module runs on the
+ * path that must never fail.
+ */
+const text = (value) => {
+    switch (typeof value) {
+        case "string":
+            return JSON.stringify(value);
+        case "number":
+            return Number.isFinite(value) ? `${value}` : `[number]`;
+        case "boolean":
+            return value ? "true" : "false";
+        case "bigint":
+            return `[bigint]`;
+        case "undefined":
+        case "symbol":
+        case "function":
+            return `[${typeof value}]`;
+        case "object":
+            return value === null ? "null" : Array.isArray(value) ? "[array]" : "[object]";
+    }
+};
+const minimalValue = () => ({ type: "object", message: "[unrepresentable]" });
+/** Reads only an own data property; accessors are deliberately inert. */
+const ownData = (value, name) => {
+    const descriptor = Object.getOwnPropertyDescriptor(value, name);
+    return descriptor !== undefined && "value" in descriptor ? descriptor.value : undefined;
+};
+// Effect exits store their value/cause in one own data slot. Pinning the two
+// library prototypes lets projection read that slot without invoking the
+// public `value` / `cause` accessors or trusting a lookalike object.
+const successExitPrototype = Object.getPrototypeOf(Exit.succeed(undefined));
+const failureExitPrototype = Object.getPrototypeOf(Exit.fail(undefined));
+const exitArguments = "~effect/Effect/args";
+/**
+ * Projects one value — a typed error, a defect, a success value, a handoff
+ * payload — into JSON.
+ *
+ * @since 0.1.0
+ * @category conversions
+ */
+export const projectValue = (value, depth = 0, seen = new WeakSet()) => {
+    if (value === null || typeof value !== "object") {
+        return {
+            type: value === null ? "null" : typeof value,
+            message: redactedText(text(value))
+        };
+    }
+    // Generic Proxy introspection is observable user code. A host that can name
+    // a proxy from its internal slot rejects it without invoking a trap.
+    if (isProxy(value) || seen.has(value))
+        return minimalValue();
+    seen.add(value);
+    try {
+        const message = ownData(value, "message");
+        const tag = ownData(value, "_tag");
+        const code = ownData(value, "code");
+        const stack = ownData(value, "stack");
+        const cause = ownData(value, "cause");
+        const projection = {
+            type: typeof tag === "string" && tag.length > 0
+                ? truncate(tag, maxTextLength)
+                : isNativeError(value)
+                    ? "Error"
+                    : Array.isArray(value)
+                        ? "Array"
+                        : "object",
+            message: redactedText(typeof message === "string" ? message : text(value))
+        };
+        if (typeof tag === "string")
+            projection.tag = truncate(tag, maxTextLength);
+        if (typeof code === "string")
+            projection.code = truncate(code, maxTextLength);
+        // Native Error stacks are commonly accessors. They remain deliberately
+        // unread; only an already-materialized own data string is retained.
+        if (typeof stack === "string") {
+            projection.stack = redactedText(stack.split("\n").slice(0, maxStackLines).join("\n"));
+        }
+        if (cause !== undefined && depth < maxCauseDepth) {
+            projection.cause = projectValue(cause, depth + 1, seen);
+        }
+        return projection;
+    }
+    catch {
+        return minimalValue();
+    }
+};
+const projectReason = (reason) => {
+    if (isProxy(reason))
+        return { _tag: "Die", error: minimalValue() };
+    try {
+        const tag = ownData(reason, "_tag");
+        if (tag === "Fail")
+            return { _tag: "Fail", error: projectValue(ownData(reason, "error")) };
+        if (tag === "Die")
+            return { _tag: "Die", error: projectValue(ownData(reason, "defect")) };
+        const fiberId = ownData(reason, "fiberId");
+        return typeof fiberId === "number" ? { _tag: "Interrupt", fiberId } : { _tag: "Interrupt" };
+    }
+    catch {
+        return { _tag: "Die", error: minimalValue() };
+    }
+};
+/**
+ * Projects every reason of a cause, in order. An absent cause — a
+ * `Flow.Suspended` that carries none — projects to no reasons.
+ *
+ * @since 0.1.0
+ * @category conversions
+ */
+export const projectCause = (cause) => {
+    if (cause === undefined)
+        return [];
+    if (isProxy(cause))
+        return [{ _tag: "Die", error: minimalValue() }];
+    try {
+        const reasons = ownData(cause, "reasons");
+        if (!Array.isArray(reasons) || isProxy(reasons)) {
+            return [{ _tag: "Die", error: minimalValue() }];
+        }
+        const projected = reasons.slice(0, maxReasonCount).map(projectReason);
+        if (reasons.length > maxReasonCount) {
+            projected.push({
+                _tag: "Die",
+                error: { type: "truncated", message: `[${reasons.length - maxReasonCount} reasons omitted]` }
+            });
+        }
+        return projected;
+    }
+    catch {
+        return [{ _tag: "Die", error: minimalValue() }];
+    }
+};
+const minimalResult = (note) => ({
+    _tag: projectionTag,
+    result: "Complete",
+    note,
+    reasons: [{ _tag: "Die", error: minimalValue() }],
+    value: null
+});
+const withinBudget = (projection) => {
+    try {
+        return new TextEncoder().encode(JSON.stringify(projection)).length <= maxProjectionBytes
+            ? projection
+            : minimalResult("the rejected settlement exceeded the diagnostic projection bound");
+    }
+    catch {
+        return minimalResult("the rejected settlement could not be projected");
+    }
+};
+/**
+ * Projects a settlement the flow's codec rejected.
+ *
+ * @since 0.1.0
+ * @category conversions
+ */
+export const projectResult = (result, note) => {
+    note = truncate(note, maxTextLength);
+    if (isProxy(result))
+        return minimalResult(note);
+    try {
+        const tag = ownData(result, "_tag");
+        if (tag === "Suspended") {
+            return withinBudget({
+                _tag: projectionTag,
+                result: "Suspended",
+                note,
+                reasons: projectCause(ownData(result, "cause")),
+                value: null
+            });
+        }
+        if (tag === "Handoff") {
+            return withinBudget({
+                _tag: projectionTag,
+                result: "Handoff",
+                note,
+                reasons: [],
+                value: projectValue(ownData(result, "payload"))
+            });
+        }
+        const exit = ownData(result, "exit");
+        if (typeof exit !== "object" || exit === null || isProxy(exit))
+            return minimalResult(note);
+        const prototype = Object.getPrototypeOf(exit);
+        const argument = ownData(exit, exitArguments);
+        if (prototype !== successExitPrototype && prototype !== failureExitPrototype)
+            return minimalResult(note);
+        return withinBudget(prototype === successExitPrototype
+            ? {
+                _tag: projectionTag,
+                result: "Complete",
+                note,
+                reasons: [],
+                value: projectValue(argument)
+            }
+            : {
+                _tag: projectionTag,
+                result: "Complete",
+                note,
+                reasons: projectCause(argument),
+                value: null
+            });
+    }
+    catch {
+        return minimalResult(note);
+    }
+};
+/**
+ * The encoded settlement written in place of one the codec rejected.
+ *
+ * A `Handoff` keeps its own shape, because its round settles `completed` with
+ * a successor already created and the lineage has to stay readable. Everything
+ * else becomes a failed `Complete`: a settlement whose bytes the codec refuses
+ * is not resumable and not answerable, so the only honest durable record is
+ * that the round failed, with the projection as its defect.
+ */
+const degrade = (result, projection) => {
+    try {
+        if (!isProxy(result) && ownData(result, "_tag") === "Handoff") {
+            const flow = ownData(result, "flow");
+            if (typeof flow === "string")
+                return { _tag: "Handoff", flow, payload: projection, capabilityCeilings: [[]] };
+        }
+    }
+    catch {
+        // The terminal Complete below is the fail-closed representation.
+    }
+    return { _tag: "Complete", exit: { _tag: "Failure", cause: [{ _tag: "Die", defect: projection }] } };
+};
+/**
+ * Encodes a round's settlement through the flow's own codec, and — when that
+ * codec rejects it — through a JSON projection instead.
+ *
+ * The returned effect has no error channel and dies for nothing: a caller on
+ * the terminal-transition path can always write the row it holds.
+ *
+ * @since 0.1.0
+ * @category conversions
+ */
+export const encode = (flow, result) => Schema.encodeEffect(Schema.toCodecJson(Flow.Result({
+    success: flow.successSchema,
+    error: flow.errorSchema
+})))(result).pipe(Effect.map((encoded) => ({ encoded, note: undefined })), Effect.catchCause((_cause) => {
+    const note = "the flow result codec rejected the settlement";
+    return Effect.as(Effect.logWarning(`engine-store: the settlement of ${flow._tag} could not be encoded through its own codec; persisting a JSON projection so the run still settles`), { encoded: degrade(result, projectResult(result, note)), note });
+}));
+//# sourceMappingURL=ExitEncoding.js.map

package/dist/esm/internal/ExitEncoding.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ExitEncoding.js","sourceRoot":"","sources":["../../../src/internal/ExitEncoding.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Encoding a round's settlement so a terminal transition can never be lost.\n *\n * A run row leaves `running` only when the driver has bytes to write into\n * `state_json`, and those bytes come from the flow's OWN codec:\n * `Flow.Result({ success: flow.successSchema, error: flow.errorSchema })`.\n * A flow that declares `Schema.Unknown` for either channel — which is what\n * `@smthrs/agent`'s `agent/run` declares, because an agent run carries\n * whatever its body failed with — encodes that channel through `Schema.Json`,\n * and `Schema.Json` rejects every class instance: `SchemaAST.isJson` walks the\n * prototype chain and refuses anything that is not a plain object or an array.\n * Every `Data.TaggedError` in this repository is therefore unencodable through\n * such a flow, `HarnessError` and `ModelError` included.\n *\n * Guarding the terminal transition with `Effect.orDie` around that encode made\n * an unencodable failure fatal for the drain instead of terminal for the run.\n * The release validation caught the whole chain: `engine-store: coordinated\n * drain failed for run-1 SchemaError: Expected JSON value at\n * [\"exit\"][\"cause\"][0][\"error\"]`, `engine.db` `flows_runs` left at `running`\n * with a dead owner pid while `control.db` said `failed`, and 86 seconds later\n * the next process's stale-running sweep stole the row, opened a second turn,\n * and billed the provider seat again for a run the control plane had closed.\n *\n * So the encode fails CLOSED here rather than open. The ordinary path is the\n * flow's own codec, unchanged. When that codec rejects the value, the result\n * is still written — as a JSON projection of what could not be encoded (tag,\n * code, message, a stack summary, and nested causes) inside a `Die` reason —\n * and the caller is told, through {@link EncodedResult.note}, that it must\n * settle the run `failed`. A settled run is never re-executed, which is the\n * durability promise the release policy states as one terminal write.\n *\n * The projection is built as plain JSON rather than re-encoded through a\n * schema, so nothing in this module can raise. Its top-level object carries no\n * `message` key on purpose: `Schema.Defect` revives any JSON object that has a\n * string `message` as an `Error`, and a projection has to come back out of the\n * row as the structured record it went in as.\n *\n * @since 0.1.0\n */\n\nimport { Flow } from \"@smthrs/flow\"\nimport { Redaction } from \"@smthrs/journal\"\nimport type * as Cause from \"effect/Cause\"\nimport * as Effect from \"effect/Effect\"\nimport * as Exit from \"effect/Exit\"\nimport * as Schema from \"effect/Schema\"\nimport * as HostReflection from \"./HostReflection.ts\"\n\n/**\n * Proxy and native-error detection, taken from the host that can answer them.\n *\n * `./HostReflection.ts` states why these are host predicates rather than a\n * `node:util/types` import: the module has to bundle for a browser, and only\n * some hosts can name a proxy at all.\n */\nconst { isNativeError, isProxy } = HostReflection.host\n\n/**\n * The `_tag` every projection carries, so a reader of `state_json` can tell a\n * projected settlement from an encoded one without guessing.\n *\n * @since 0.1.0\n * @category constants\n */\nexport const projectionTag = \"flows/engine-store/UnencodableResult\"\n\n/**\n * How many `cause` links a value projection follows before it stops.\n *\n * A provider failure nests two or three deep (`HarnessError` over\n * `ModelError` over the transport error); the bound exists so a self-linking\n * cause chain cannot make the projection unbounded.\n *\n * @since 0.1.0\n * @category constants\n */\nexport const maxCauseDepth = 4\n\n/**\n * How many leading stack lines a value projection keeps.\n *\n * @since 0.1.0\n * @category constants\n */\nexport const maxStackLines = 4\n\n/**\n * How many characters any single projected string keeps.\n *\n * @since 0.1.0\n * @category constants\n */\nexport const maxTextLength = 1024\n\n/**\n * Maximum cause reasons retained by the terminal fallback.\n *\n * @category constants\n * @since 1.0.0\n */\nexport const maxReasonCount = 32\n\n/**\n * Maximum serialized bytes retained by one fallback projection.\n *\n * @category constants\n * @since 1.0.0\n */\nexport const maxProjectionBytes = 64 * 1024\n\n/**\n * A JSON-safe summary of one unencodable value.\n *\n * `type` is the constructor name for an object and the `typeof` for anything\n * else, so `ModelError` and `\"boom\"` are distinguishable in the row.\n *\n * @since 0.1.0\n * @category models\n */\nexport interface ValueProjection {\n  readonly type: string\n  readonly message: string\n  readonly tag?: string\n  readonly code?: string\n  readonly stack?: string\n  readonly cause?: ValueProjection\n}\n\n/**\n * A JSON-safe summary of one `Cause` reason.\n *\n * @since 0.1.0\n * @category models\n */\nexport interface ReasonProjection {\n  readonly _tag: \"Fail\" | \"Die\" | \"Interrupt\"\n  readonly error?: ValueProjection\n  readonly fiberId?: number\n}\n\n/**\n * The record written in place of a settlement the flow's codec rejected.\n *\n * @since 0.1.0\n * @category models\n */\nexport interface ResultProjection {\n  readonly _tag: typeof projectionTag\n  readonly result: \"Complete\" | \"Suspended\" | \"Handoff\"\n  readonly note: string\n  readonly reasons: ReadonlyArray<ReasonProjection>\n  readonly value: ValueProjection | null\n}\n\n/**\n * What {@link encode} produces: the bytes to persist, and — only when the\n * flow's codec rejected the settlement — the note describing why.\n *\n * A present `note` is an instruction to the caller, not decoration: the run\n * must reach a terminal `failed` row, because the alternative is the row this\n * lane exists to abolish, a `running` row whose owner is gone.\n *\n * @since 0.1.0\n * @category models\n */\nexport interface EncodedResult {\n  readonly encoded: unknown\n  readonly note: string | undefined\n}\n\nconst truncate = (value: string, limit: number): string => value.length <= limit ? value : `${value.slice(0, limit)}…`\n\n/**\n * Bounds one projected message or stack after the journal's redaction rules.\n *\n * The projection is observability text in `flows_runs.state_json`, and a git or\n * HTTP failure message embeds its remote URL, credentials included. Redaction\n * runs before truncation so a cut cannot leave half a credential the rules no\n * longer match.\n */\nconst redactedText = (value: string): string => truncate(Redaction.redact(value) as string, maxTextLength)\n\n/**\n * Renders any value as a bounded string without raising.\n *\n * `JSON.stringify` answers `undefined` for a function, a symbol, and\n * `undefined` itself, and throws on a circular structure; both are answered\n * with a shape marker rather than propagated, because this module runs on the\n * path that must never fail.\n */\nconst text = (value: unknown): string => {\n  switch (typeof value) {\n    case \"string\":\n      return JSON.stringify(value)\n    case \"number\":\n      return Number.isFinite(value) ? `${value}` : `[number]`\n    case \"boolean\":\n      return value ? \"true\" : \"false\"\n    case \"bigint\":\n      return `[bigint]`\n    case \"undefined\":\n    case \"symbol\":\n    case \"function\":\n      return `[${typeof value}]`\n    case \"object\":\n      return value === null ? \"null\" : Array.isArray(value) ? \"[array]\" : \"[object]\"\n  }\n}\n\nconst minimalValue = (): ValueProjection => ({ type: \"object\", message: \"[unrepresentable]\" })\n\n/** Reads only an own data property; accessors are deliberately inert. */\nconst ownData = (value: object, name: PropertyKey): unknown => {\n  const descriptor = Object.getOwnPropertyDescriptor(value, name)\n  return descriptor !== undefined && \"value\" in descriptor ? descriptor.value : undefined\n}\n\n// Effect exits store their value/cause in one own data slot. Pinning the two\n// library prototypes lets projection read that slot without invoking the\n// public `value` / `cause` accessors or trusting a lookalike object.\nconst successExitPrototype = Object.getPrototypeOf(Exit.succeed(undefined))\nconst failureExitPrototype = Object.getPrototypeOf(Exit.fail(undefined))\nconst exitArguments = \"~effect/Effect/args\"\n\n/**\n * Projects one value — a typed error, a defect, a success value, a handoff\n * payload — into JSON.\n *\n * @since 0.1.0\n * @category conversions\n */\nexport const projectValue = (value: unknown, depth = 0, seen = new WeakSet<object>()): ValueProjection => {\n  if (value === null || typeof value !== \"object\") {\n    return {\n      type: value === null ? \"null\" : typeof value,\n      message: redactedText(text(value))\n    }\n  }\n  // Generic Proxy introspection is observable user code. A host that can name\n  // a proxy from its internal slot rejects it without invoking a trap.\n  if (isProxy(value) || seen.has(value)) return minimalValue()\n  seen.add(value)\n  try {\n    const message = ownData(value, \"message\")\n    const tag = ownData(value, \"_tag\")\n    const code = ownData(value, \"code\")\n    const stack = ownData(value, \"stack\")\n    const cause = ownData(value, \"cause\")\n    const projection: {\n      type: string\n      message: string\n      tag?: string\n      code?: string\n      stack?: string\n      cause?: ValueProjection\n    } = {\n      type: typeof tag === \"string\" && tag.length > 0\n        ? truncate(tag, maxTextLength)\n        : isNativeError(value)\n        ? \"Error\"\n        : Array.isArray(value)\n        ? \"Array\"\n        : \"object\",\n      message: redactedText(typeof message === \"string\" ? message : text(value))\n    }\n    if (typeof tag === \"string\") projection.tag = truncate(tag, maxTextLength)\n    if (typeof code === \"string\") projection.code = truncate(code, maxTextLength)\n    // Native Error stacks are commonly accessors. They remain deliberately\n    // unread; only an already-materialized own data string is retained.\n    if (typeof stack === \"string\") {\n      projection.stack = redactedText(stack.split(\"\\n\").slice(0, maxStackLines).join(\"\\n\"))\n    }\n    if (cause !== undefined && depth < maxCauseDepth) {\n      projection.cause = projectValue(cause, depth + 1, seen)\n    }\n    return projection\n  } catch {\n    return minimalValue()\n  }\n}\n\nconst projectReason = (reason: Cause.Reason<unknown>): ReasonProjection => {\n  if (isProxy(reason)) return { _tag: \"Die\", error: minimalValue() }\n  try {\n    const tag = ownData(reason, \"_tag\")\n    if (tag === \"Fail\") return { _tag: \"Fail\", error: projectValue(ownData(reason, \"error\")) }\n    if (tag === \"Die\") return { _tag: \"Die\", error: projectValue(ownData(reason, \"defect\")) }\n    const fiberId = ownData(reason, \"fiberId\")\n    return typeof fiberId === \"number\" ? { _tag: \"Interrupt\", fiberId } : { _tag: \"Interrupt\" }\n  } catch {\n    return { _tag: \"Die\", error: minimalValue() }\n  }\n}\n\n/**\n * Projects every reason of a cause, in order. An absent cause — a\n * `Flow.Suspended` that carries none — projects to no reasons.\n *\n * @since 0.1.0\n * @category conversions\n */\nexport const projectCause = (\n  cause: Cause.Cause<unknown> | undefined\n): ReadonlyArray<ReasonProjection> => {\n  if (cause === undefined) return []\n  if (isProxy(cause)) return [{ _tag: \"Die\", error: minimalValue() }]\n  try {\n    const reasons = ownData(cause, \"reasons\")\n    if (!Array.isArray(reasons) || isProxy(reasons)) {\n      return [{ _tag: \"Die\", error: minimalValue() }]\n    }\n    const projected = reasons.slice(0, maxReasonCount).map(projectReason)\n    if (reasons.length > maxReasonCount) {\n      projected.push({\n        _tag: \"Die\",\n        error: { type: \"truncated\", message: `[${reasons.length - maxReasonCount} reasons omitted]` }\n      })\n    }\n    return projected\n  } catch {\n    return [{ _tag: \"Die\", error: minimalValue() }]\n  }\n}\n\nconst minimalResult = (note: string): ResultProjection => ({\n  _tag: projectionTag,\n  result: \"Complete\",\n  note,\n  reasons: [{ _tag: \"Die\", error: minimalValue() }],\n  value: null\n})\n\nconst withinBudget = (projection: ResultProjection): ResultProjection => {\n  try {\n    return new TextEncoder().encode(JSON.stringify(projection)).length <= maxProjectionBytes\n      ? projection\n      : minimalResult(\"the rejected settlement exceeded the diagnostic projection bound\")\n  } catch {\n    return minimalResult(\"the rejected settlement could not be projected\")\n  }\n}\n\n/**\n * Projects a settlement the flow's codec rejected.\n *\n * @since 0.1.0\n * @category conversions\n */\nexport const projectResult = (\n  result: Flow.Result<unknown, unknown>,\n  note: string\n): ResultProjection => {\n  note = truncate(note, maxTextLength)\n  if (isProxy(result)) return minimalResult(note)\n  try {\n    const tag = ownData(result, \"_tag\")\n    if (tag === \"Suspended\") {\n      return withinBudget({\n        _tag: projectionTag,\n        result: \"Suspended\",\n        note,\n        reasons: projectCause(ownData(result, \"cause\") as Cause.Cause<unknown> | undefined),\n        value: null\n      })\n    }\n    if (tag === \"Handoff\") {\n      return withinBudget({\n        _tag: projectionTag,\n        result: \"Handoff\",\n        note,\n        reasons: [],\n        value: projectValue(ownData(result, \"payload\"))\n      })\n    }\n    const exit = ownData(result, \"exit\")\n    if (typeof exit !== \"object\" || exit === null || isProxy(exit)) return minimalResult(note)\n    const prototype = Object.getPrototypeOf(exit)\n    const argument = ownData(exit, exitArguments)\n    if (prototype !== successExitPrototype && prototype !== failureExitPrototype) return minimalResult(note)\n    return withinBudget(\n      prototype === successExitPrototype\n        ? {\n          _tag: projectionTag,\n          result: \"Complete\",\n          note,\n          reasons: [],\n          value: projectValue(argument)\n        }\n        : {\n          _tag: projectionTag,\n          result: \"Complete\",\n          note,\n          reasons: projectCause(argument as Cause.Cause<unknown> | undefined),\n          value: null\n        }\n    )\n  } catch {\n    return minimalResult(note)\n  }\n}\n\n/**\n * The encoded settlement written in place of one the codec rejected.\n *\n * A `Handoff` keeps its own shape, because its round settles `completed` with\n * a successor already created and the lineage has to stay readable. Everything\n * else becomes a failed `Complete`: a settlement whose bytes the codec refuses\n * is not resumable and not answerable, so the only honest durable record is\n * that the round failed, with the projection as its defect.\n */\nconst degrade = (result: Flow.Result<unknown, unknown>, projection: ResultProjection): unknown => {\n  try {\n    if (!isProxy(result) && ownData(result, \"_tag\") === \"Handoff\") {\n      const flow = ownData(result, \"flow\")\n      if (typeof flow === \"string\") return { _tag: \"Handoff\", flow, payload: projection, capabilityCeilings: [[]] }\n    }\n  } catch {\n    // The terminal Complete below is the fail-closed representation.\n  }\n  return { _tag: \"Complete\", exit: { _tag: \"Failure\", cause: [{ _tag: \"Die\", defect: projection }] } }\n}\n\n/**\n * Encodes a round's settlement through the flow's own codec, and — when that\n * codec rejects it — through a JSON projection instead.\n *\n * The returned effect has no error channel and dies for nothing: a caller on\n * the terminal-transition path can always write the row it holds.\n *\n * @since 0.1.0\n * @category conversions\n */\nexport const encode = (\n  flow: Flow.Any,\n  result: Flow.Result<unknown, unknown>\n): Effect.Effect<EncodedResult> =>\n  Schema.encodeEffect(\n    Schema.toCodecJson(Flow.Result({\n      success: flow.successSchema,\n      error: flow.errorSchema\n    }))\n  )(result).pipe(\n    Effect.map((encoded): EncodedResult => ({ encoded, note: undefined })),\n    Effect.catchCause((_cause) => {\n      const note = \"the flow result codec rejected the settlement\"\n      return Effect.as(\n        Effect.logWarning(\n          `engine-store: the settlement of ${flow._tag} could not be encoded through its own codec; persisting a JSON projection so the run still settles`\n        ),\n        { encoded: degrade(result, projectResult(result, note)), note } satisfies EncodedResult\n      )\n    })\n  ) as Effect.Effect<EncodedResult>\n"]}

package/dist/esm/internal/FileBoundarySnapshot.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Immutable snapshots of filesystem declarations crossing an async boundary.
+ *
+ * @since 1.0.0
+ */
+import type { FileBoundary } from "@smthrs/flow/FileBoundary";
+/**
+ * Copies and freezes every mutable member of a boundary declaration.
+ *
+ * @category constructors
+ * @since 1.0.0
+ */
+export declare const make: (boundary: FileBoundary) => FileBoundary;
+//# sourceMappingURL=FileBoundarySnapshot.d.ts.map

package/dist/esm/internal/FileBoundarySnapshot.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"FileBoundarySnapshot.d.ts","sourceRoot":"","sources":["../../../src/internal/FileBoundarySnapshot.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAA;AAY7D;;;;;GAKG;AACH,eAAO,MAAM,IAAI,GAAI,UAAU,YAAY,KAAG,YAc1C,CAAA"}

package/dist/esm/internal/FileBoundarySnapshot.js

@@ -0,0 +1,29 @@
+/**
+ * Immutable snapshots of filesystem declarations crossing an async boundary.
+ *
+ * @since 1.0.0
+ */
+import * as FileSet from "@smthrs/plan/FileSet";
+const freeze = (values) => Object.freeze([...values]);
+const glob = (entry) => Object.freeze({
+    _tag: "Glob",
+    include: freeze(entry.include),
+    ...(entry.exclude === undefined ? {} : { exclude: freeze(entry.exclude) })
+});
+/**
+ * Copies and freezes every mutable member of a boundary declaration.
+ *
+ * @category constructors
+ * @since 1.0.0
+ */
+export const make = (boundary) => Object.freeze({
+    readSet: freeze(boundary.readSet.map((entry) => FileSet.isGlob(entry) ? glob(entry) : Object.freeze({ path: entry.path, digest: entry.digest }))),
+    writeSet: freeze(boundary.writeSet.map((entry) => typeof entry === "string"
+        ? entry
+        : FileSet.isGlob(entry)
+            ? glob(entry)
+            : Object.freeze({ _tag: "TreeArtifact", path: entry.path }))),
+    ...(boundary.removes === undefined ? {} : { removes: freeze(boundary.removes) }),
+    boundaryMode: boundary.boundaryMode
+});
+//# sourceMappingURL=FileBoundarySnapshot.js.map

package/dist/esm/internal/FileBoundarySnapshot.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"FileBoundarySnapshot.js","sourceRoot":"","sources":["../../../src/internal/FileBoundarySnapshot.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,KAAK,OAAO,MAAM,sBAAsB,CAAA;AAE/C,MAAM,MAAM,GAAG,CAAI,MAAwB,EAAoB,EAAE,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,GAAG,MAAM,CAAC,CAAC,CAAA;AAE5F,MAAM,IAAI,GAAG,CAAC,KAAmB,EAAgB,EAAE,CACjD,MAAM,CAAC,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM;IACZ,OAAO,EAAE,MAAM,CAAC,KAAK,CAAC,OAAO,CAA4B;IACzD,GAAG,CAAC,KAAK,CAAC,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,MAAM,CAAC,KAAK,CAAC,OAAO,CAAC,EAAE,CAAC;CAC3E,CAAC,CAAA;AAEJ;;;;;GAKG;AACH,MAAM,CAAC,MAAM,IAAI,GAAG,CAAC,QAAsB,EAAgB,EAAE,CAC3D,MAAM,CAAC,MAAM,CAAC;IACZ,OAAO,EAAE,MAAM,CAAC,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAC7C,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,CAAC,MAAM,EAAE,CAAC,CAChG,CAAC;IACF,QAAQ,EAAE,MAAM,CAAC,QAAQ,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAC/C,OAAO,KAAK,KAAK,QAAQ;QACvB,CAAC,CAAC,KAAK;QACP,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC;YACvB,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC;YACb,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,IAAI,EAAE,cAAuB,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE,CAAC,CACvE,CAAC;IACF,GAAG,CAAC,QAAQ,CAAC,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,MAAM,CAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC;IAChF,YAAY,EAAE,QAAQ,CAAC,YAAY;CACpC,CAAC,CAAA","sourcesContent":["/**\n * Immutable snapshots of filesystem declarations crossing an async boundary.\n *\n * @since 1.0.0\n */\n\nimport type { FileBoundary } from \"@smthrs/flow/FileBoundary\"\nimport * as FileSet from \"@smthrs/plan/FileSet\"\n\nconst freeze = <A>(values: ReadonlyArray<A>): ReadonlyArray<A> => Object.freeze([...values])\n\nconst glob = (entry: FileSet.Glob): FileSet.Glob =>\n  Object.freeze({\n    _tag: \"Glob\",\n    include: freeze(entry.include) as FileSet.Glob[\"include\"],\n    ...(entry.exclude === undefined ? {} : { exclude: freeze(entry.exclude) })\n  })\n\n/**\n * Copies and freezes every mutable member of a boundary declaration.\n *\n * @category constructors\n * @since 1.0.0\n */\nexport const make = (boundary: FileBoundary): FileBoundary =>\n  Object.freeze({\n    readSet: freeze(boundary.readSet.map((entry) =>\n      FileSet.isGlob(entry) ? glob(entry) : Object.freeze({ path: entry.path, digest: entry.digest })\n    )),\n    writeSet: freeze(boundary.writeSet.map((entry) =>\n      typeof entry === \"string\"\n        ? entry\n        : FileSet.isGlob(entry)\n        ? glob(entry)\n        : Object.freeze({ _tag: \"TreeArtifact\" as const, path: entry.path })\n    )),\n    ...(boundary.removes === undefined ? {} : { removes: freeze(boundary.removes) }),\n    boundaryMode: boundary.boundaryMode\n  })\n"]}

package/dist/esm/internal/FileEnumeration.d.ts

@@ -0,0 +1,127 @@
+/**
+ * Workspace-relative file enumeration for glob and tree-artifact expansion.
+ *
+ * The host `glob` is deliberately not consulted. Two divergences make it the
+ * wrong oracle for a declared pattern: the kernel `FileSystem` absolutizes
+ * patterns against the workspace root and returns absolute paths, so a
+ * workspace-relative matcher filters every result out; and Node's matcher
+ * skips dotfiles, which `FileSet.matchesPattern` — and Bazel's glob — cover.
+ * Walking `readDirectory` and filtering through `FileSet` keeps every
+ * expansion byte-identical to the matcher the plan's overlap passes use, in
+ * the one coordinate system declarations are written in.
+ *
+ * @since 0.1.0
+ */
+import * as FileSet from "@smthrs/plan/FileSet";
+import * as Effect from "effect/Effect";
+import type * as FileSystem from "effect/FileSystem";
+import type * as PlatformError from "effect/PlatformError";
+import * as Schema from "effect/Schema";
+/**
+ * The default maximum number of directory entries visited by one expansion.
+ *
+ * @since 1.0.0
+ * @category constants
+ */
+export declare const defaultMaxEntries = 100000;
+/**
+ * The stable error code returned when enumeration exceeds its safety bound.
+ *
+ * @since 1.0.0
+ * @category errors
+ */
+export declare const FileEnumerationErrorCode: Schema.Literal<"entry_limit_exceeded">;
+/**
+ * The stable error code returned when enumeration exceeds its safety bound.
+ *
+ * @since 1.0.0
+ * @category errors
+ */
+export type FileEnumerationErrorCode = typeof FileEnumerationErrorCode.Type;
+declare const FileEnumerationError_base: Schema.Class<FileEnumerationError, Schema.TaggedStruct<"@smthrs/engine-store/FileEnumerationError", {
+    readonly code: Schema.Literal<"entry_limit_exceeded">;
+    readonly message: Schema.String;
+    readonly pattern: Schema.String;
+    readonly limit: Schema.Number;
+    readonly cause: Schema.Unknown;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * A workspace enumeration exceeded its configured entry limit.
+ *
+ * @since 1.0.0
+ * @category errors
+ */
+export declare class FileEnumerationError extends FileEnumerationError_base {
+}
+/**
+ * How an enumeration talks to a FileSystem that does not speak
+ * workspace-relative paths.
+ *
+ * @since 0.1.0
+ * @category models
+ */
+export interface EnumerationOptions {
+    /**
+     * Maps a workspace-relative path (`""` names the workspace root) to the
+     * coordinate the FileSystem expects. Defaults to the identity, with `""`
+     * spelled `"."`.
+     */
+    readonly resolve?: (path: string) => string;
+    /**
+     * Maximum number of directory entries one expansion may visit. Defaults to
+     * {@link defaultMaxEntries}. Enumeration fails instead of returning a
+     * partial result when the walk exceeds this bound.
+     */
+    readonly maxEntries?: number | undefined;
+}
+/**
+ * Every file under `dir` (workspace-relative; `""` for the workspace root),
+ * as sorted workspace-relative paths. A missing directory enumerates to
+ * nothing — a zero-match expansion is legal, so absence is a fact rather than
+ * a failure. This declared-tree walk does not prune `.git`, `.jj`, or
+ * `node_modules`. Those names are part of the tree identity and must be
+ * captured and restored exactly.
+ *
+ * @since 0.1.0
+ * @category accessors
+ */
+export declare const filesUnder: (fs: FileSystem.FileSystem, dir: string, options?: EnumerationOptions) => Effect.Effect<ReadonlyArray<string>, PlatformError.PlatformError | FileEnumerationError>;
+/**
+ * Every file and every directory under `dir` (workspace-relative, non-empty),
+ * as sorted workspace-relative paths. The directory list includes `dir`
+ * itself, so a tree replay can audit exactly the scaffolding it may have to
+ * prune. A missing directory enumerates to nothing — a tree that matched
+ * nothing is legal, so absence is a fact rather than a failure. This
+ * declared-tree walk does not prune `.git`, `.jj`, or `node_modules` because
+ * replay needs every directory and file that contributes to the tree.
+ *
+ * @since 0.1.0
+ * @category accessors
+ */
+export declare const entriesUnder: (fs: FileSystem.FileSystem, dir: string, options?: EnumerationOptions) => Effect.Effect<{
+    readonly files: ReadonlyArray<string>;
+    readonly directories: ReadonlyArray<string>;
+}, PlatformError.PlatformError | FileEnumerationError>;
+/**
+ * The longest directory prefix of a pattern that contains no wildcard — the
+ * subtree a walk has to visit. `src/**` walks `src`; `*.txt` walks the root.
+ *
+ * @since 0.1.0
+ * @category accessors
+ */
+export declare const staticPrefix: (pattern: string) => string;
+/**
+ * Expands one glob against the workspace: walk each include's static prefix,
+ * keep the files `FileSet.matchesGlob` covers. Sorted and deduplicated, so
+ * expansion is deterministic. A glob walk prunes `.git`, `.jj`, and
+ * `node_modules` unless an include sharing that walk prefix names the
+ * directory as a path segment. This keeps a root glob from traversing
+ * repository metadata and dependency trees while preserving an explicitly
+ * declared match after either a fixed or wildcard segment.
+ *
+ * @since 0.1.0
+ * @category accessors
+ */
+export declare const expandGlob: (fs: FileSystem.FileSystem, glob: FileSet.Glob, options?: EnumerationOptions) => Effect.Effect<ReadonlyArray<string>, PlatformError.PlatformError | FileEnumerationError>;
+export {};
+//# sourceMappingURL=FileEnumeration.d.ts.map

package/dist/esm/internal/FileEnumeration.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"FileEnumeration.d.ts","sourceRoot":"","sources":["../../../src/internal/FileEnumeration.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAGH,OAAO,KAAK,OAAO,MAAM,sBAAsB,CAAA;AAC/C,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AACvC,OAAO,KAAK,KAAK,UAAU,MAAM,mBAAmB,CAAA;AACpD,OAAO,KAAK,KAAK,aAAa,MAAM,sBAAsB,CAAA;AAC1D,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AAiCvC;;;;;GAKG;AACH,eAAO,MAAM,iBAAiB,SAAU,CAAA;AAExC;;;;;GAKG;AACH,eAAO,MAAM,wBAAwB,wCAAyC,CAAA;AAE9E;;;;;GAKG;AACH,MAAM,MAAM,wBAAwB,GAAG,OAAO,wBAAwB,CAAC,IAAI,CAAA;;;;;;;;AAE3E;;;;;GAKG;AACH,qBAAa,oBAAqB,SAAQ,yBASzC;CAAG;AAEJ;;;;;;GAMG;AACH,MAAM,WAAW,kBAAkB;IACjC;;;;OAIG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,CAAA;IAC3C;;;;OAIG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;CACzC;AAkHD;;;;;;;;;;GAUG;AACH,eAAO,MAAM,UAAU,GACrB,IAAI,UAAU,CAAC,UAAU,EACzB,KAAK,MAAM,EACX,UAAS,kBAAuB,KAC/B,MAAM,CAAC,MAAM,CAAC,aAAa,CAAC,MAAM,CAAC,EAAE,aAAa,CAAC,aAAa,GAAG,oBAAoB,CAUtF,CAAA;AAEJ;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,YAAY,GACvB,IAAI,UAAU,CAAC,UAAU,EACzB,KAAK,MAAM,EACX,UAAS,kBAAuB,KAC/B,MAAM,CAAC,MAAM,CACd;IAAE,QAAQ,CAAC,KAAK,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IAAC,QAAQ,CAAC,WAAW,EAAE,aAAa,CAAC,MAAM,CAAC,CAAA;CAAE,EACtF,aAAa,CAAC,aAAa,GAAG,oBAAoB,CAKhD,CAAA;AAEJ;;;;;;GAMG;AACH,eAAO,MAAM,YAAY,GAAI,SAAS,MAAM,KAAG,MAQ9C,CAAA;AAED;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,UAAU,GACrB,IAAI,UAAU,CAAC,UAAU,EACzB,MAAM,OAAO,CAAC,IAAI,EAClB,UAAS,kBAAuB,KAC/B,MAAM,CAAC,MAAM,CAAC,aAAa,CAAC,MAAM,CAAC,EAAE,aAAa,CAAC,aAAa,GAAG,oBAAoB,CAoBtF,CAAA"}