@smthrs/flow 0.0.0-stage → 1.0.0-rc.3

package/dist/cjs/Fault.d.ts

@@ -0,0 +1,131 @@
+/**
+ * One typed fault for every failure, and the one response table that reads it.
+ *
+ * Each owner of an error union registers its codes here with a class, so a
+ * failure crosses every seam as `{ class, tag }` rather than as prose. The
+ * control plane stamps it on a failed run, the gateway carries it to the
+ * worker, and every surface reads the same record.
+ *
+ * @since 1.0.0
+ */
+import * as Effect from "effect/Effect";
+import * as Schema from "effect/Schema";
+/**
+ * Whose problem a failure is. The first five are the wire registry; `factory`
+ * (the factory's own work failed and a replan may fix it) and `policy` (a cap
+ * stopped it) are the factory's.
+ *
+ * @category models
+ * @since 1.0.0
+ */
+export declare const Class: Schema.Literals<readonly ["user", "wait", "infra", "dependency", "bug", "factory", "policy"]>;
+/**
+ * The decoded form of {@link Class}.
+ *
+ * @category models
+ * @since 1.0.0
+ */
+export type Class = typeof Class.Type;
+/**
+ * What happens next. `very_hard` is a ladder state the worker reaches, not a class.
+ *
+ * @category models
+ * @since 1.0.0
+ */
+export declare const Response: Schema.Literals<readonly ["retry", "backup", "park", "replan", "very_hard", "help", "close", "stop"]>;
+/**
+ * The decoded form of {@link Response}.
+ *
+ * @category models
+ * @since 1.0.0
+ */
+export type Response = typeof Response.Type;
+/**
+ * The record stamped on a failed run. `tag` is `<_tag>/<code>`, or `<_tag>`
+ * for an error without a code.
+ *
+ * @category models
+ * @since 1.0.0
+ */
+export declare const Fault: Schema.Struct<{
+    readonly class: Schema.Literals<readonly ["user", "wait", "infra", "dependency", "bug", "factory", "policy"]>;
+    readonly tag: Schema.String;
+}>;
+/**
+ * The decoded form of {@link Fault}.
+ *
+ * @category models
+ * @since 1.0.0
+ */
+export type Fault = typeof Fault.Type;
+/**
+ * One class per code of an owner's union. `satisfies Rows<Code>` at the owner
+ * makes a new code without a class a compile error.
+ *
+ * @category models
+ * @since 1.0.0
+ */
+export type Rows<Code extends string> = Readonly<Record<Code, Class>>;
+/**
+ * Registers an owner's error tag: one class for the whole tag, or one per
+ * value of its `field` (`code` unless the union names it otherwise). A value
+ * the table does not name is `bug`. Registering a tag again with the same
+ * rows is a no-op (a module loaded twice); with different rows it throws,
+ * because two owners disagreeing about one tag is a defect.
+ *
+ * @category constructors
+ * @since 1.0.0
+ */
+export declare const register: <Code extends string>(tag: string, table: Class | Rows<Code>, field?: string) => void;
+/**
+ * Every tag registered so far. The sweep test reads it.
+ *
+ * @category getters
+ * @since 1.0.0
+ */
+export declare const registered: () => ReadonlySet<string>;
+/**
+ * The fault of a failure. Walks `cause` and answers the innermost registered
+ * tag, because a wrapper names where a failure surfaced and its cause names
+ * why: a harness `model_failed` over a model `quota_exceeded` is a wait. A
+ * failure no owner registered is a `bug`.
+ *
+ * @category constructors
+ * @since 1.0.0
+ */
+export declare const of: (error: unknown) => Fault;
+/**
+ * Retries typed infrastructure failures of an effect the caller can safely repeat.
+ * Preserves its error channel when the bounded transient policy expires.
+ * Defects and interruption propagate without retry.
+ *
+ * @category combinators
+ * @since 1.0.0
+ */
+export declare const retryTransient: <A, E, R>(effect: Effect.Effect<A, E, R>) => Effect.Effect<A, E, R>;
+/**
+ * What the responder knows when it picks a response.
+ *
+ * @category models
+ * @since 1.0.0
+ */
+export interface State {
+    /** The action attempt that just failed. */
+    readonly attempt: number;
+    /** Seats not tried in this frame and not cooling. */
+    readonly seatsLeft: number;
+    /** Quota parks left before the run stops (`QuotaPolicy.defaultMaxParks` less those spent). */
+    readonly parksLeft: number;
+    /** Replans spent: the worker's attempt minus one. */
+    readonly replans: number;
+    /** Whether the item already had its very-hard continuation. */
+    readonly veryHard: boolean;
+}
+/**
+ * The one ladder. A new class does not compile until it has a row.
+ *
+ * @category constructors
+ * @since 1.0.0
+ */
+export declare const respond: (fault: Fault, state: State) => Response;
+//# sourceMappingURL=Fault.d.ts.map

package/dist/cjs/Fault.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Fault.d.ts","sourceRoot":"","sources":["../../src/Fault.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAGH,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AAEvC,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AAIvC;;;;;;;GAOG;AACH,eAAO,MAAM,KAAK,+FAAuF,CAAA;AAEzG;;;;;GAKG;AACH,MAAM,MAAM,KAAK,GAAG,OAAO,KAAK,CAAC,IAAI,CAAA;AAErC;;;;;GAKG;AACH,eAAO,MAAM,QAAQ,uGAA+F,CAAA;AAEpH;;;;;GAKG;AACH,MAAM,MAAM,QAAQ,GAAG,OAAO,QAAQ,CAAC,IAAI,CAAA;AAE3C;;;;;;GAMG;AACH,eAAO,MAAM,KAAK;;;EAAsD,CAAA;AAExE;;;;;GAKG;AACH,MAAM,MAAM,KAAK,GAAG,OAAO,KAAK,CAAC,IAAI,CAAA;AAErC;;;;;;GAMG;AACH,MAAM,MAAM,IAAI,CAAC,IAAI,SAAS,MAAM,IAAI,QAAQ,CAAC,MAAM,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC,CAAA;AA2BrE;;;;;;;;;GASG;AACH,eAAO,MAAM,QAAQ,GAAI,IAAI,SAAS,MAAM,EAAE,KAAK,MAAM,EAAE,OAAO,KAAK,GAAG,IAAI,CAAC,IAAI,CAAC,EAAE,cAAc,KAAG,IAOtG,CAAA;AAOD;;;;;GAKG;AACH,eAAO,MAAM,UAAU,QAAO,WAAW,CAAC,MAAM,CAAyB,CAAA;AAEzE;;;;;;;;GAQG;AACH,eAAO,MAAM,EAAE,GAAI,OAAO,OAAO,KAAG,KAgBnC,CAAA;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,cAAc,GAAI,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,QAAQ,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,KAAG,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAiB1F,CAAA;AAEJ;;;;;GAKG;AACH,MAAM,WAAW,KAAK;IACpB,2CAA2C;IAC3C,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,qDAAqD;IACrD,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,8FAA8F;IAC9F,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,qDAAqD;IACrD,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,+DAA+D;IAC/D,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAA;CAC3B;AAED;;;;;GAKG;AACH,eAAO,MAAM,OAAO,GAAI,OAAO,KAAK,EAAE,OAAO,KAAK,KAAG,QASO,CAAA"}

package/dist/cjs/Fault.js

@@ -0,0 +1,157 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var Fault_exports = {};
+__export(Fault_exports, {
+  Class: () => Class,
+  Fault: () => Fault,
+  Response: () => Response,
+  of: () => of,
+  register: () => register,
+  registered: () => registered,
+  respond: () => respond,
+  retryTransient: () => retryTransient
+});
+module.exports = __toCommonJS(Fault_exports);
+var Clock = __toESM(require("effect/Clock"), 1);
+var Effect = __toESM(require("effect/Effect"), 1);
+var Result = __toESM(require("effect/Result"), 1);
+var Schema = __toESM(require("effect/Schema"), 1);
+var RetryPolicy = __toESM(require("./RetryPolicy.js"), 1);
+const Class = Schema.Literals(["user", "wait", "infra", "dependency", "bug", "factory", "policy"]);
+const Response = Schema.Literals(["retry", "backup", "park", "replan", "very_hard", "help", "close", "stop"]);
+const Fault = Schema.Struct({ class: Class, tag: Schema.String });
+const rows = globalThis[/* @__PURE__ */ Symbol.for("@smthrs/flow/Fault/rows")] ??= /* @__PURE__ */ new Map();
+const same = (left, right) => left.field === right.field && JSON.stringify(left.table) === JSON.stringify(right.table);
+const read = (value, key) => {
+  try {
+    return value[key];
+  } catch {
+    return void 0;
+  }
+};
+const register = (tag, table, field = "code") => {
+  const row = { table, field };
+  const existing = rows.get(tag);
+  if (existing !== void 0 && !same(existing, row)) {
+    throw new Error(`Fault: ${tag} is already registered with different rows`);
+  }
+  rows.set(tag, row);
+};
+const classOf = (row, code) => typeof row.table === "string" ? row.table : code !== void 0 && Object.hasOwn(row.table, code) ? row.table[code] : "bug";
+const registered = () => new Set(rows.keys());
+const of = (error) => {
+  let found = { class: "bug", tag: "unregistered" };
+  let current = error;
+  const seen = /* @__PURE__ */ new Set();
+  for (let depth = 0; depth < 16 && typeof current === "object" && current !== null && !seen.has(current); depth++) {
+    seen.add(current);
+    const tag = RetryPolicy.errorTag(current);
+    const row = tag === void 0 ? void 0 : rows.get(tag);
+    if (row !== void 0) {
+      const value = read(current, row.field);
+      const code = typeof value === "string" ? value : void 0;
+      found = { class: classOf(row, code), tag: code === void 0 ? tag : `${tag}/${code}` };
+    }
+    current = read(current, "cause");
+  }
+  return found;
+};
+const retryTransient = (effect) => Effect.gen(function* () {
+  const start = yield* Clock.currentTimeMillis;
+  let attempt = 1;
+  while (true) {
+    const result = yield* Effect.result(effect);
+    if (Result.isSuccess(result)) return result.success;
+    if (of(result.failure).class !== "infra") return yield* Effect.fail(result.failure);
+    const decision = yield* RetryPolicy.decideEffect(RetryPolicy.transient, {
+      attempt,
+      error: result.failure,
+      elapsedMs: (yield* Clock.currentTimeMillis) - start
+    });
+    if (decision._tag === "GiveUp") return yield* Effect.fail(result.failure);
+    yield* Effect.sleep(decision.delayMs);
+    attempt++;
+  }
+});
+const respond = (fault, state) => ({
+  wait: state.seatsLeft > 0 ? "backup" : state.parksLeft > 0 ? "park" : "stop",
+  dependency: state.seatsLeft > 0 ? "backup" : state.attempt < 3 ? "retry" : "stop",
+  infra: state.attempt < 3 ? "retry" : "park",
+  factory: state.replans < 2 ? "replan" : !state.veryHard ? "very_hard" : "help",
+  user: fault.tag === "coding/Error/declined" ? "close" : "help",
+  policy: "stop",
+  bug: "stop"
+})[fault.class];
+register("@smthrs/flow/InfraInterrupt", "infra");
+register("@smthrs/flow/InfraInterruptRetriesExhausted", "infra");
+register(
+  "@smthrs/flow/HumanTaskFailed",
+  {
+    rejected: "user",
+    timeout: "factory",
+    request_invalid: "bug"
+  }
+);
+register(
+  "@smthrs/flow/HumanAnswerInvalid",
+  {
+    answer_invalid: "user",
+    answer_not_open: "user"
+  }
+);
+register("@smthrs/flow/PollExhausted", "dependency");
+register("@smthrs/flow/RetryAttemptsExhausted", "dependency");
+register("@smthrs/flow/RetryPolicyExpired", "dependency");
+register("@smthrs/flow/AttemptTimedOut", "dependency");
+for (const tag of [
+  "MaxRoundsExceeded",
+  "IrreversibleRetryRequiresIdempotencyKey",
+  "WaitForRequestInvalid",
+  "SleepRequestInvalid",
+  "DurableDeferred/TokenInvalid",
+  "ExecutionIdRequired",
+  "FlowCycleDetected",
+  "CancelRequestFailed",
+  "Action/DuplicateImplementation",
+  "ConcurrentKeylessDispatch",
+  "FlowExecutionNotFound",
+  "ImplementationVersionMismatch",
+  "UncanonicalIdempotencyKey",
+  "InterpreterError"
+]) register(`@smthrs/flow/${tag}`, "bug");
+register("@smthrs/kernel/Unreachable", "infra");
+register("@smthrs/sandbox/RemoteChildProcessSpawner/ProviderError", {
+  unavailable: "infra",
+  timeout: "infra",
+  spawn_error: "bug",
+  not_found: "bug",
+  aborted: "bug",
+  unknown: "bug"
+});
+//# sourceMappingURL=Fault.js.map

package/dist/cjs/Fault.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../src/Fault.ts"],
+  "sourcesContent": ["/**\n * One typed fault for every failure, and the one response table that reads it.\n *\n * Each owner of an error union registers its codes here with a class, so a\n * failure crosses every seam as `{ class, tag }` rather than as prose. The\n * control plane stamps it on a failed run, the gateway carries it to the\n * worker, and every surface reads the same record.\n *\n * @since 1.0.0\n */\n\nimport * as Clock from \"effect/Clock\"\nimport * as Effect from \"effect/Effect\"\nimport * as Result from \"effect/Result\"\nimport * as Schema from \"effect/Schema\"\nimport type { HumanAnswerInvalid, HumanTaskFailed } from \"./HumanTask.ts\"\nimport * as RetryPolicy from \"./RetryPolicy.ts\"\n\n/**\n * Whose problem a failure is. The first five are the wire registry; `factory`\n * (the factory's own work failed and a replan may fix it) and `policy` (a cap\n * stopped it) are the factory's.\n *\n * @category models\n * @since 1.0.0\n */\nexport const Class = Schema.Literals([\"user\", \"wait\", \"infra\", \"dependency\", \"bug\", \"factory\", \"policy\"])\n\n/**\n * The decoded form of {@link Class}.\n *\n * @category models\n * @since 1.0.0\n */\nexport type Class = typeof Class.Type\n\n/**\n * What happens next. `very_hard` is a ladder state the worker reaches, not a class.\n *\n * @category models\n * @since 1.0.0\n */\nexport const Response = Schema.Literals([\"retry\", \"backup\", \"park\", \"replan\", \"very_hard\", \"help\", \"close\", \"stop\"])\n\n/**\n * The decoded form of {@link Response}.\n *\n * @category models\n * @since 1.0.0\n */\nexport type Response = typeof Response.Type\n\n/**\n * The record stamped on a failed run. `tag` is `<_tag>/<code>`, or `<_tag>`\n * for an error without a code.\n *\n * @category models\n * @since 1.0.0\n */\nexport const Fault = Schema.Struct({ class: Class, tag: Schema.String })\n\n/**\n * The decoded form of {@link Fault}.\n *\n * @category models\n * @since 1.0.0\n */\nexport type Fault = typeof Fault.Type\n\n/**\n * One class per code of an owner's union. `satisfies Rows<Code>` at the owner\n * makes a new code without a class a compile error.\n *\n * @category models\n * @since 1.0.0\n */\nexport type Rows<Code extends string> = Readonly<Record<Code, Class>>\n\ninterface Row {\n  readonly table: Class | Readonly<Record<string, Class>>\n  readonly field: string\n}\n\n/*\n * One registry per process, not per module instance: a process that loads\n * both the ESM and the CommonJS build still reads every owner's rows.\n */\nconst rows: Map<string, Row> = ((globalThis as { [key: symbol]: Map<string, Row> | undefined })[\n  Symbol.for(\"@smthrs/flow/Fault/rows\")\n] ??= new Map())\n\nconst same = (left: Row, right: Row): boolean =>\n  left.field === right.field && JSON.stringify(left.table) === JSON.stringify(right.table)\n\n/** Reads a property without running a throwing getter or proxy trap into the caller. */\nconst read = (value: object, key: string): unknown => {\n  try {\n    return (value as Record<string, unknown>)[key]\n  } catch {\n    return undefined\n  }\n}\n\n/**\n * Registers an owner's error tag: one class for the whole tag, or one per\n * value of its `field` (`code` unless the union names it otherwise). A value\n * the table does not name is `bug`. Registering a tag again with the same\n * rows is a no-op (a module loaded twice); with different rows it throws,\n * because two owners disagreeing about one tag is a defect.\n *\n * @category constructors\n * @since 1.0.0\n */\nexport const register = <Code extends string>(tag: string, table: Class | Rows<Code>, field = \"code\"): void => {\n  const row: Row = { table, field }\n  const existing = rows.get(tag)\n  if (existing !== undefined && !same(existing, row)) {\n    throw new Error(`Fault: ${tag} is already registered with different rows`)\n  }\n  rows.set(tag, row)\n}\n\nconst classOf = (row: Row, code: string | undefined): Class =>\n  typeof row.table === \"string\" ? row.table : code !== undefined && Object.hasOwn(row.table, code)\n    ? row.table[code]!\n    : \"bug\"\n\n/**\n * Every tag registered so far. The sweep test reads it.\n *\n * @category getters\n * @since 1.0.0\n */\nexport const registered = (): ReadonlySet<string> => new Set(rows.keys())\n\n/**\n * The fault of a failure. Walks `cause` and answers the innermost registered\n * tag, because a wrapper names where a failure surfaced and its cause names\n * why: a harness `model_failed` over a model `quota_exceeded` is a wait. A\n * failure no owner registered is a `bug`.\n *\n * @category constructors\n * @since 1.0.0\n */\nexport const of = (error: unknown): Fault => {\n  let found: Fault = { class: \"bug\", tag: \"unregistered\" }\n  let current: unknown = error\n  const seen = new Set<unknown>()\n  for (let depth = 0; depth < 16 && typeof current === \"object\" && current !== null && !seen.has(current); depth++) {\n    seen.add(current)\n    const tag = RetryPolicy.errorTag(current)\n    const row = tag === undefined ? undefined : rows.get(tag)\n    if (row !== undefined) {\n      const value = read(current, row.field)\n      const code = typeof value === \"string\" ? value : undefined\n      found = { class: classOf(row, code), tag: code === undefined ? tag! : `${tag}/${code}` }\n    }\n    current = read(current, \"cause\")\n  }\n  return found\n}\n\n/**\n * Retries typed infrastructure failures of an effect the caller can safely repeat.\n * Preserves its error channel when the bounded transient policy expires.\n * Defects and interruption propagate without retry.\n *\n * @category combinators\n * @since 1.0.0\n */\nexport const retryTransient = <A, E, R>(effect: Effect.Effect<A, E, R>): Effect.Effect<A, E, R> =>\n  Effect.gen(function*() {\n    const start = yield* Clock.currentTimeMillis\n    let attempt = 1\n    while (true) {\n      const result = yield* Effect.result(effect)\n      if (Result.isSuccess(result)) return result.success\n      if (of(result.failure).class !== \"infra\") return yield* Effect.fail(result.failure)\n      const decision = yield* RetryPolicy.decideEffect(RetryPolicy.transient, {\n        attempt,\n        error: result.failure,\n        elapsedMs: (yield* Clock.currentTimeMillis) - start\n      })\n      if (decision._tag === \"GiveUp\") return yield* Effect.fail(result.failure)\n      yield* Effect.sleep(decision.delayMs)\n      attempt++\n    }\n  })\n\n/**\n * What the responder knows when it picks a response.\n *\n * @category models\n * @since 1.0.0\n */\nexport interface State {\n  /** The action attempt that just failed. */\n  readonly attempt: number\n  /** Seats not tried in this frame and not cooling. */\n  readonly seatsLeft: number\n  /** Quota parks left before the run stops (`QuotaPolicy.defaultMaxParks` less those spent). */\n  readonly parksLeft: number\n  /** Replans spent: the worker's attempt minus one. */\n  readonly replans: number\n  /** Whether the item already had its very-hard continuation. */\n  readonly veryHard: boolean\n}\n\n/**\n * The one ladder. A new class does not compile until it has a row.\n *\n * @category constructors\n * @since 1.0.0\n */\nexport const respond = (fault: Fault, state: State): Response =>\n  ({\n    wait: state.seatsLeft > 0 ? \"backup\" : state.parksLeft > 0 ? \"park\" : \"stop\",\n    dependency: state.seatsLeft > 0 ? \"backup\" : state.attempt < 3 ? \"retry\" : \"stop\",\n    infra: state.attempt < 3 ? \"retry\" : \"park\",\n    factory: state.replans < 2 ? \"replan\" : !state.veryHard ? \"very_hard\" : \"help\",\n    user: fault.tag === \"coding/Error/declined\" ? \"close\" : \"help\",\n    policy: \"stop\",\n    bug: \"stop\"\n  } as const satisfies Record<Class, Response>)[fault.class]\n\nregister(\"@smthrs/flow/InfraInterrupt\", \"infra\")\nregister(\"@smthrs/flow/InfraInterruptRetriesExhausted\", \"infra\")\nregister(\n  \"@smthrs/flow/HumanTaskFailed\",\n  {\n    rejected: \"user\",\n    timeout: \"factory\",\n    request_invalid: \"bug\"\n  } satisfies Rows<HumanTaskFailed[\"code\"]>\n)\nregister(\n  \"@smthrs/flow/HumanAnswerInvalid\",\n  {\n    answer_invalid: \"user\",\n    answer_not_open: \"user\"\n  } satisfies Rows<HumanAnswerInvalid[\"code\"]>\n)\n// A spent polling or retry budget is the thing polled not answering in time.\nregister(\"@smthrs/flow/PollExhausted\", \"dependency\")\nregister(\"@smthrs/flow/RetryAttemptsExhausted\", \"dependency\")\nregister(\"@smthrs/flow/RetryPolicyExpired\", \"dependency\")\n// An attempt that outlives its bound is the thing it waited on not answering in time.\nregister(\"@smthrs/flow/AttemptTimedOut\", \"dependency\")\n// Invariant refusals: the program, not the person or the platform, is wrong.\nfor (\n  const tag of [\n    \"MaxRoundsExceeded\",\n    \"IrreversibleRetryRequiresIdempotencyKey\",\n    \"WaitForRequestInvalid\",\n    \"SleepRequestInvalid\",\n    \"DurableDeferred/TokenInvalid\",\n    \"ExecutionIdRequired\",\n    \"FlowCycleDetected\",\n    \"CancelRequestFailed\",\n    \"Action/DuplicateImplementation\",\n    \"ConcurrentKeylessDispatch\",\n    \"FlowExecutionNotFound\",\n    \"ImplementationVersionMismatch\",\n    \"UncanonicalIdempotencyKey\",\n    \"InterpreterError\"\n  ]\n) register(`@smthrs/flow/${tag}`, \"bug\")\n\n// Lower host seams do not depend on flow authoring. Register their stable wire\n// tags here so classification does not introduce an upward package dependency.\nregister(\"@smthrs/kernel/Unreachable\", \"infra\")\nregister(\"@smthrs/sandbox/RemoteChildProcessSpawner/ProviderError\", {\n  unavailable: \"infra\",\n  timeout: \"infra\",\n  spawn_error: \"bug\",\n  not_found: \"bug\",\n  aborted: \"bug\",\n  unknown: \"bug\"\n})\n"],
+  "mappings": "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",
+  "names": []
+}

package/dist/cjs/Flow/Annotations.d.ts

@@ -0,0 +1,245 @@
+/**
+ * Execution policies attached to flow definitions through Effect context.
+ *
+ * @since 0.1.0
+ */
+import * as PlanEffects from "@smthrs/plan/Effects";
+import * as PlanPlacement from "@smthrs/plan/Placement";
+import * as Plan from "@smthrs/plan/Plan";
+import * as Context from "effect/Context";
+/**
+ * Declared filesystem effects: the plan node effect contract itself.
+ *
+ * This is `@smthrs/plan`'s `Plan.NodeEffects`, not a copy of it. The two were
+ * field-for-field identical structs in two packages, which meant a change to
+ * one silently stopped `Plan.compile` decoding what this package wrote.
+ *
+ * @category schemas
+ * @since 0.1.0
+ */
+export declare const Effects: import("effect/Schema").Struct<{
+    readonly reads: import("effect/Schema").$Array<import("effect/Schema").Union<readonly [import("effect/Schema").Union<readonly [import("effect/Schema").NonEmptyString, import("effect/Schema").TaggedStruct<"Glob", {
+        readonly include: import("effect/Schema").NonEmptyArray<import("effect/Schema").NonEmptyString>;
+        readonly exclude: import("effect/Schema").optional<import("effect/Schema").$Array<import("effect/Schema").NonEmptyString>>;
+    }>]>, import("effect/Schema").TaggedStruct<"Filegroup", {
+        readonly name: import("effect/Schema").NonEmptyString;
+        readonly entries: import("effect/Schema").$Array<import("effect/Schema").Union<readonly [import("effect/Schema").NonEmptyString, import("effect/Schema").TaggedStruct<"Glob", {
+            readonly include: import("effect/Schema").NonEmptyArray<import("effect/Schema").NonEmptyString>;
+            readonly exclude: import("effect/Schema").optional<import("effect/Schema").$Array<import("effect/Schema").NonEmptyString>>;
+        }>]>>;
+    }>]>>;
+    readonly writes: import("effect/Schema").$Array<import("effect/Schema").Union<readonly [import("effect/Schema").Union<readonly [import("effect/Schema").NonEmptyString, import("effect/Schema").TaggedStruct<"Glob", {
+        readonly include: import("effect/Schema").NonEmptyArray<import("effect/Schema").NonEmptyString>;
+        readonly exclude: import("effect/Schema").optional<import("effect/Schema").$Array<import("effect/Schema").NonEmptyString>>;
+    }>, import("effect/Schema").TaggedStruct<"TreeArtifact", {
+        readonly path: import("effect/Schema").NonEmptyString;
+    }>]>, import("effect/Schema").TaggedStruct<"Filegroup", {
+        readonly name: import("effect/Schema").NonEmptyString;
+        readonly entries: import("effect/Schema").$Array<import("effect/Schema").Union<readonly [import("effect/Schema").NonEmptyString, import("effect/Schema").TaggedStruct<"Glob", {
+            readonly include: import("effect/Schema").NonEmptyArray<import("effect/Schema").NonEmptyString>;
+            readonly exclude: import("effect/Schema").optional<import("effect/Schema").$Array<import("effect/Schema").NonEmptyString>>;
+        }>, import("effect/Schema").TaggedStruct<"TreeArtifact", {
+            readonly path: import("effect/Schema").NonEmptyString;
+        }>]>>;
+    }>]>>;
+    readonly removes: import("effect/Schema").optional<import("effect/Schema").$Array<import("effect/Schema").NonEmptyString>>;
+    readonly boundaryMode: import("effect/Schema").Literals<readonly ["hard", "expected"]>;
+}>;
+/**
+ * The value form of {@link Effects}.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export type Effects = Plan.NodeEffects;
+/**
+ * A directive naming where a node runs, carried unchanged until planning.
+ *
+ * This is `@smthrs/plan`'s `Placement.Placement`, the one typed model. It was
+ * `Schema.Unknown` here while `@smthrs/core` held a four-variant enum of the
+ * same thing, which made every crossing a cast.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export type PlacementDirective = PlanPlacement.Placement;
+/**
+ * Capability ceiling. An omitted annotation inherits; an explicit empty array denies.
+ * The reference default remains an empty metadata projection for catalog readers;
+ * execution distinguishes an absent annotation from an explicitly stored one.
+ *
+ * @category annotations
+ * @since 0.1.0
+ */
+export declare const Capabilities: Context.Reference<readonly string[]>;
+/**
+ * Required annotation key for a flow's declared filesystem effects.
+ *
+ * @category annotations
+ * @since 0.1.0
+ */
+export declare const EffectsDeclaration: Context.Service<{
+    readonly reads: readonly (string | {
+        readonly _tag: "Glob";
+        readonly include: readonly [string, ...string[]];
+        readonly exclude?: readonly string[] | undefined;
+    } | {
+        readonly _tag: "Filegroup";
+        readonly name: string;
+        readonly entries: readonly (string | {
+            readonly _tag: "Glob";
+            readonly include: readonly [string, ...string[]];
+            readonly exclude?: readonly string[] | undefined;
+        })[];
+    })[];
+    readonly writes: readonly (string | {
+        readonly _tag: "Glob";
+        readonly include: readonly [string, ...string[]];
+        readonly exclude?: readonly string[] | undefined;
+    } | {
+        readonly _tag: "TreeArtifact";
+        readonly path: string;
+    } | {
+        readonly _tag: "Filegroup";
+        readonly name: string;
+        readonly entries: readonly (string | {
+            readonly _tag: "Glob";
+            readonly include: readonly [string, ...string[]];
+            readonly exclude?: readonly string[] | undefined;
+        } | {
+            readonly _tag: "TreeArtifact";
+            readonly path: string;
+        })[];
+    })[];
+    readonly boundaryMode: "expected" | "hard";
+    readonly removes?: readonly string[] | undefined;
+}, {
+    readonly reads: readonly (string | {
+        readonly _tag: "Glob";
+        readonly include: readonly [string, ...string[]];
+        readonly exclude?: readonly string[] | undefined;
+    } | {
+        readonly _tag: "Filegroup";
+        readonly name: string;
+        readonly entries: readonly (string | {
+            readonly _tag: "Glob";
+            readonly include: readonly [string, ...string[]];
+            readonly exclude?: readonly string[] | undefined;
+        })[];
+    })[];
+    readonly writes: readonly (string | {
+        readonly _tag: "Glob";
+        readonly include: readonly [string, ...string[]];
+        readonly exclude?: readonly string[] | undefined;
+    } | {
+        readonly _tag: "TreeArtifact";
+        readonly path: string;
+    } | {
+        readonly _tag: "Filegroup";
+        readonly name: string;
+        readonly entries: readonly (string | {
+            readonly _tag: "Glob";
+            readonly include: readonly [string, ...string[]];
+            readonly exclude?: readonly string[] | undefined;
+        } | {
+            readonly _tag: "TreeArtifact";
+            readonly path: string;
+        })[];
+    })[];
+    readonly boundaryMode: "expected" | "hard";
+    readonly removes?: readonly string[] | undefined;
+}>;
+/**
+ * The effect AUTHORITY a flow declares: the ceiling every step spliced beneath
+ * it must stay inside.
+ *
+ * This is the one envelope model, `@smthrs/plan/Effects`, which `@smthrs/core`
+ * re-exports and `@smthrs/patterns` intersects against. It answers a different
+ * question from {@link EffectsDeclaration}: that one says which FILES a node
+ * touches, so a plan can order writers and a sandbox can enforce a boundary at
+ * run time, while this one says how much a flow is ALLOWED to touch, so
+ * {@link module:Graph.build} can refuse a composition that claims more than its
+ * caller granted.
+ *
+ * `Flow.make`'s `effects` option writes it, which is what makes it readable by
+ * a catalog that projects a declaration without importing this module.
+ *
+ * @category annotations
+ * @since 0.1.0
+ */
+export declare const EffectEnvelope: Context.Service<PlanEffects.Declaration, PlanEffects.Declaration>;
+/**
+ * Required annotation key for a flow's schema-encodable placement directive.
+ *
+ * @category annotations
+ * @since 0.1.0
+ */
+export declare const Placement: Context.Service<{
+    readonly _tag: "flows/core/Placement/Local";
+} | {
+    readonly _tag: "flows/core/Placement/Client";
+} | {
+    readonly _tag: "flows/core/Placement/Sandbox";
+    readonly image?: string | undefined | undefined;
+    readonly profile?: string | undefined | undefined;
+    readonly target?: string | undefined | undefined;
+} | {
+    readonly _tag: "flows/core/Placement/Remote";
+    readonly image?: string | undefined | undefined;
+    readonly profile?: string | undefined | undefined;
+    readonly target?: string | undefined | undefined;
+}, {
+    readonly _tag: "flows/core/Placement/Local";
+} | {
+    readonly _tag: "flows/core/Placement/Client";
+} | {
+    readonly _tag: "flows/core/Placement/Sandbox";
+    readonly image?: string | undefined | undefined;
+    readonly profile?: string | undefined | undefined;
+    readonly target?: string | undefined | undefined;
+} | {
+    readonly _tag: "flows/core/Placement/Remote";
+    readonly image?: string | undefined | undefined;
+    readonly profile?: string | undefined | undefined;
+    readonly target?: string | undefined | undefined;
+}>;
+/**
+ * Captures defects for a flow and includes them in the result of the flow or its actions.
+ *
+ * **Details**
+ *
+ * By default, this annotation is set to `true`, meaning defects are captured.
+ *
+ * @category annotations
+ * @since 0.1.0
+ */
+export declare const CaptureDefects: Context.Reference<boolean>;
+/**
+ * Whether a catalog may offer this flow to a model, defaulting to yes.
+ *
+ * It answers a different question from {@link Capabilities}: that one says how
+ * much a flow is allowed to touch, this one says whether a model is shown the
+ * flow at all. A flow whose actions only one host implements is discoverable
+ * everywhere its file is, and teaching it to an agent running somewhere else
+ * offers a call that has no implementation to reach.
+ *
+ * `Flow.make`'s `modelInvocable` option writes it, which is what makes it
+ * readable by a catalog that projects a declaration from source text without
+ * importing this module, exactly as `capabilities` and `effects` are.
+ *
+ * @category annotations
+ * @since 0.1.0
+ */
+export declare const ModelInvocable: Context.Reference<boolean>;
+/**
+ * Marks a flow to suspend when it encounters any error.
+ *
+ * **Details**
+ *
+ * The suspended execution can later be resumed with the flow's `resume` method, for example `MyFlow.resume(executionId)`.
+ *
+ * @category annotations
+ * @since 0.1.0
+ */
+export declare const SuspendOnFailure: Context.Reference<boolean>;
+//# sourceMappingURL=Annotations.d.ts.map

package/dist/cjs/Flow/Annotations.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Annotations.d.ts","sourceRoot":"","sources":["../../../src/Flow/Annotations.ts"],"names":[],"mappings":"AAEA;;;;GAIG;AAEH,OAAO,KAAK,WAAW,MAAM,sBAAsB,CAAA;AACnD,OAAO,KAAK,aAAa,MAAM,wBAAwB,CAAA;AACvD,OAAO,KAAK,IAAI,MAAM,mBAAmB,CAAA;AACzC,OAAO,KAAK,OAAO,MAAM,gBAAgB,CAAA;AAGzC;;;;;;;;;GASG;AACH,eAAO,MAAM,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;EAAmB,CAAA;AAEvC;;;;;GAKG;AACH,MAAM,MAAM,OAAO,GAAG,IAAI,CAAC,WAAW,CAAA;AAEtC;;;;;;;;;GASG;AACH,MAAM,MAAM,kBAAkB,GAAG,aAAa,CAAC,SAAS,CAAA;AAExD;;;;;;;GAOG;AACH,eAAO,MAAM,YAAY,sCAGxB,CAAA;AAED;;;;;GAKG;AACH,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAAmE,CAAA;AAElG;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,cAAc,mEAAuB,CAAA;AAElD;;;;;GAKG;AACH,eAAO,MAAM,SAAS;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAA2B,CAAA;AAEjD;;;;;;;;;GASG;AACH,eAAO,MAAM,cAAc,4BAK1B,CAAA;AAED;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,cAAc,4BAK1B,CAAA;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,gBAAgB,4BAK5B,CAAA"}

package/dist/cjs/Flow/Annotations.js

@@ -0,0 +1,72 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var Annotations_exports = {};
+__export(Annotations_exports, {
+  Capabilities: () => Capabilities,
+  CaptureDefects: () => CaptureDefects,
+  EffectEnvelope: () => EffectEnvelope,
+  Effects: () => Effects,
+  EffectsDeclaration: () => EffectsDeclaration,
+  ModelInvocable: () => ModelInvocable,
+  Placement: () => Placement,
+  SuspendOnFailure: () => SuspendOnFailure
+});
+module.exports = __toCommonJS(Annotations_exports);
+var PlanEffects = __toESM(require("@smthrs/plan/Effects"), 1);
+var PlanPlacement = __toESM(require("@smthrs/plan/Placement"), 1);
+var Plan = __toESM(require("@smthrs/plan/Plan"), 1);
+var Context = __toESM(require("effect/Context"), 1);
+var import_Function = require("effect/Function");
+const Effects = Plan.NodeEffects;
+const Capabilities = Context.Reference(
+  "@smthrs/flow/Flow/Capabilities",
+  { defaultValue: () => [] }
+);
+const EffectsDeclaration = Context.Service("@smthrs/flow/Flow/EffectsDeclaration");
+const EffectEnvelope = PlanEffects.Envelope;
+const Placement = PlanPlacement.Annotation;
+const CaptureDefects = Context.Reference(
+  "@smthrs/flow/Flow/CaptureDefects",
+  {
+    defaultValue: import_Function.constTrue
+  }
+);
+const ModelInvocable = Context.Reference(
+  "@smthrs/flow/Flow/ModelInvocable",
+  {
+    defaultValue: import_Function.constTrue
+  }
+);
+const SuspendOnFailure = Context.Reference(
+  "@smthrs/flow/Flow/SuspendOnFailure",
+  {
+    defaultValue: import_Function.constFalse
+  }
+);
+//# sourceMappingURL=Annotations.js.map