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

package/dist/cjs/internal/DeclarationSite.d.ts

@@ -0,0 +1,135 @@
+/**
+ * Where a declaration was written: the author's file and the line it starts
+ * on.
+ *
+ * A digest says what a step IS; it cannot say where to read it. A monitor that
+ * offers to show the code behind a node needs the file and line the
+ * declaration was authored at, so the declaration carries it from the moment
+ * it is made — captured from an `Error` stack, which is the only place a
+ * JavaScript runtime keeps it.
+ *
+ * Two properties make this safe to carry. It is stored as a NON-ENUMERABLE
+ * own property, so canonical serialization — which walks enumerable keys —
+ * cannot see it, and a declaration's key material is byte-identical with and
+ * without it. And every parse is defensive: an engine whose stack format this
+ * module does not recognize yields `undefined`, never a throw and never a
+ * guessed location.
+ *
+ * Frames inside the framework are skipped, because the frame that matters is
+ * the AUTHOR's: `Action.make` is called from this package, and the interesting
+ * line is the one that called it.
+ *
+ * @since 1.0.0
+ */
+/**
+ * The file and line a declaration was written at.
+ *
+ * `path` is the path the runtime reported, which is absolute in every engine
+ * this repository runs on. A journal writer makes it repo-relative before it
+ * records it, and omits it when it cannot: an absolute home directory is not
+ * a fact a durable record may carry.
+ *
+ * @since 1.0.0
+ * @category models
+ */
+export interface DeclaredAt {
+    readonly path: string;
+    readonly line: number;
+}
+/**
+ * Whether a frame belongs to the framework or the runtime rather than to an
+ * author.
+ *
+ * Three shapes are not an author's. Anything under a `node_modules` directory,
+ * which is how a published `@smthrs/*` package is loaded. Anything under a
+ * `packages/smithers/**\/src` directory, which is how this repository loads the
+ * same code from source. And anything that does not name a file at all: a
+ * declaration made inside the framework is reached through the module loader,
+ * so the first frame under it is a runtime internal such as
+ * `node:internal/process/task_queues`, which is a real frame and a false
+ * author. A test, an example, and a workspace's own flow file are absolute
+ * paths under none of those, so they are what a capture reports.
+ *
+ * Windows spells those same two directories with backslashes, so separators
+ * are read as one before matching: a framework frame taken for an author's
+ * would name this package's own `make.js` as the site every node of that run
+ * was declared at.
+ *
+ * @since 1.0.0
+ * @category predicates
+ */
+export declare const isFrameworkPath: (path: string) => boolean;
+/**
+ * States that a file this runtime is about to evaluate holds bytes read from
+ * another, so declarations inside it report the file an author can open.
+ *
+ * A host that verifies a flow's source has to evaluate THE BYTES IT MEASURED,
+ * and the only way to evaluate bytes in this runtime is to write them
+ * somewhere and import that path. `@smthrs/registry` `Executable` writes them
+ * as a scratch sibling of the entry and removes it as soon as the load is
+ * over, so without this every declaration in an agent-authored flow reports a
+ * path nothing holds — a Code tab that can never be opened (D-068).
+ *
+ * The loader states this BEFORE the import, because a declaration's site is
+ * captured while the module is evaluated and is never rewritten afterwards.
+ * One entry is kept per load: a scratch path is unique and gone, so no later
+ * file can take a stale entry's name.
+ *
+ * @since 1.0.0
+ * @category constructors
+ */
+export declare const evaluatedFrom: (evaluated: string, entry: string) => void;
+/**
+ * The position one stack frame names, in the V8 and JavaScriptCore spellings.
+ *
+ * V8 writes `    at name (/path/file.ts:12:5)` and, for a top-level frame,
+ * `    at /path/file.ts:12:5`. JavaScriptCore — Bun and Safari — writes
+ * `name@/path/file.ts:12:5` and `@/path/file.ts:12:5`. Anything else is
+ * unparseable and reports nothing.
+ *
+ * @since 1.0.0
+ * @category parsers
+ */
+export declare const parseFrame: (frame: string) => DeclaredAt | undefined;
+/**
+ * The first author frame of a captured stack.
+ *
+ * The header line every V8 stack starts with parses as nothing, so it needs no
+ * special case. A decoding failure inside a frame path — a malformed percent
+ * escape in a `file://` url — is an unparseable stack rather than a throw,
+ * which is the whole contract of this module: provenance is a nicety, and a
+ * nicety may never take a declaration down with it.
+ *
+ * @since 1.0.0
+ * @category parsers
+ */
+export declare const parseStack: (stack: string | undefined) => DeclaredAt | undefined;
+/**
+ * Where the caller of the function calling this was written.
+ *
+ * @since 1.0.0
+ * @category constructors
+ */
+export declare const capture: () => DeclaredAt | undefined;
+/**
+ * Carries a source position on a declaration without adding a field to it.
+ *
+ * The property is non-enumerable and non-writable, so it cannot reach a
+ * canonical serialization, a digest, or a structural clone, and a later caller
+ * cannot rewrite one declaration's provenance to another's.
+ *
+ * @since 1.0.0
+ * @category constructors
+ */
+export declare const annotate: <A extends object>(value: A, site: DeclaredAt | undefined) => A;
+/**
+ * The source position a value carries, when it carries one.
+ *
+ * Read through an own data descriptor, so neither a prototype nor an accessor
+ * on a foreign value can answer for it.
+ *
+ * @since 1.0.0
+ * @category accessors
+ */
+export declare const declaredAt: (value: unknown) => DeclaredAt | undefined;
+//# sourceMappingURL=DeclarationSite.d.ts.map

package/dist/cjs/internal/DeclarationSite.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"DeclarationSite.d.ts","sourceRoot":"","sources":["../../../src/internal/DeclarationSite.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAKH;;;;;;;;;;GAUG;AACH,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CACtB;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,eAAO,MAAM,eAAe,GAAI,MAAM,MAAM,KAAG,OAI9C,CAAA;AA4BD;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,aAAa,GAAI,WAAW,MAAM,EAAE,OAAO,MAAM,KAAG,IAEhE,CAAA;AAED;;;;;;;;;;GAUG;AACH,eAAO,MAAM,UAAU,GAAI,OAAO,MAAM,KAAG,UAAU,GAAG,SAUvD,CAAA;AAED;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,UAAU,GAAI,OAAO,MAAM,GAAG,SAAS,KAAG,UAAU,GAAG,SAWnE,CAAA;AAED;;;;;GAKG;AACH,eAAO,MAAM,OAAO,QAAO,UAAU,GAAG,SAA0C,CAAA;AAElF;;;;;;;;;GASG;AACH,eAAO,MAAM,QAAQ,GAAI,CAAC,SAAS,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,UAAU,GAAG,SAAS,KAAG,CAYnF,CAAA;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,UAAU,GAAI,OAAO,OAAO,KAAG,UAAU,GAAG,SAIxD,CAAA"}

package/dist/cjs/internal/DeclarationSite.js

@@ -0,0 +1,89 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+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 __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var DeclarationSite_exports = {};
+__export(DeclarationSite_exports, {
+  annotate: () => annotate,
+  capture: () => capture,
+  declaredAt: () => declaredAt,
+  evaluatedFrom: () => evaluatedFrom,
+  isFrameworkPath: () => isFrameworkPath,
+  parseFrame: () => parseFrame,
+  parseStack: () => parseStack
+});
+module.exports = __toCommonJS(DeclarationSite_exports);
+const TypeId = "~@smthrs/flow/DeclaredAt";
+const isFrameworkPath = (path) => {
+  if (!isFilePath(path)) return true;
+  const separated = path.replaceAll("\\", "/");
+  return separated.includes("/node_modules/") || /\/packages\/smithers\/.*\/src\//.test(separated);
+};
+const isFilePath = (path) => path.startsWith("/") || /^[A-Za-z]:[\\/]/.test(path);
+const location = (frame) => {
+  const parenthesized = /\(([^()]*)\)\s*$/.exec(frame);
+  if (parenthesized !== null) return parenthesized[1];
+  const trimmed = frame.trim();
+  const at = trimmed.lastIndexOf("@");
+  if (at >= 0) return trimmed.slice(at + 1);
+  return trimmed.startsWith("at ") ? trimmed.slice(3) : void 0;
+};
+const normalize = (path) => path.startsWith("file://") ? decodeURIComponent(path.slice("file://".length)) : path;
+const sourcesKey = /* @__PURE__ */ Symbol.for("@smthrs/flow/DeclaredAt/sources/v1");
+const globals = globalThis;
+const sources = globals[sourcesKey] ??= /* @__PURE__ */ new Map();
+const evaluatedFrom = (evaluated, entry) => {
+  sources.set(normalize(evaluated), normalize(entry));
+};
+const parseFrame = (frame) => {
+  const text = location(frame);
+  if (text === void 0) return void 0;
+  const position = /^(.*):(\d+):(\d+)$/.exec(text);
+  if (position === null) return void 0;
+  const line = Number(position[2]);
+  const path = normalize(position[1]);
+  return { path: sources.get(path) ?? path, line };
+};
+const parseStack = (stack) => {
+  if (stack === void 0) return void 0;
+  try {
+    for (const frame of stack.split("\n")) {
+      const parsed = parseFrame(frame);
+      if (parsed !== void 0 && !isFrameworkPath(parsed.path)) return parsed;
+    }
+    return void 0;
+  } catch {
+    return void 0;
+  }
+};
+const capture = () => parseStack(new Error().stack);
+const annotate = (value, site) => {
+  if (site === void 0 || Object.getOwnPropertyDescriptor(value, TypeId) !== void 0) return value;
+  Object.defineProperty(value, TypeId, {
+    configurable: false,
+    enumerable: false,
+    value: site,
+    writable: false
+  });
+  return value;
+};
+const declaredAt = (value) => {
+  if (Object(value) !== value) return void 0;
+  const descriptor = Object.getOwnPropertyDescriptor(value, TypeId);
+  return descriptor === void 0 ? void 0 : descriptor.value;
+};
+//# sourceMappingURL=DeclarationSite.js.map

package/dist/cjs/internal/DeclarationSite.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../src/internal/DeclarationSite.ts"],
+  "sourcesContent": ["/**\n * Where a declaration was written: the author's file and the line it starts\n * on.\n *\n * A digest says what a step IS; it cannot say where to read it. A monitor that\n * offers to show the code behind a node needs the file and line the\n * declaration was authored at, so the declaration carries it from the moment\n * it is made \u2014 captured from an `Error` stack, which is the only place a\n * JavaScript runtime keeps it.\n *\n * Two properties make this safe to carry. It is stored as a NON-ENUMERABLE\n * own property, so canonical serialization \u2014 which walks enumerable keys \u2014\n * cannot see it, and a declaration's key material is byte-identical with and\n * without it. And every parse is defensive: an engine whose stack format this\n * module does not recognize yields `undefined`, never a throw and never a\n * guessed location.\n *\n * Frames inside the framework are skipped, because the frame that matters is\n * the AUTHOR's: `Action.make` is called from this package, and the interesting\n * line is the one that called it.\n *\n * @since 1.0.0\n */\n\n/** The own property a declaration carries its source position on. @private */\nconst TypeId = \"~@smthrs/flow/DeclaredAt\"\n\n/**\n * The file and line a declaration was written at.\n *\n * `path` is the path the runtime reported, which is absolute in every engine\n * this repository runs on. A journal writer makes it repo-relative before it\n * records it, and omits it when it cannot: an absolute home directory is not\n * a fact a durable record may carry.\n *\n * @since 1.0.0\n * @category models\n */\nexport interface DeclaredAt {\n  readonly path: string\n  readonly line: number\n}\n\n/**\n * Whether a frame belongs to the framework or the runtime rather than to an\n * author.\n *\n * Three shapes are not an author's. Anything under a `node_modules` directory,\n * which is how a published `@smthrs/*` package is loaded. Anything under a\n * `packages/smithers/**\\/src` directory, which is how this repository loads the\n * same code from source. And anything that does not name a file at all: a\n * declaration made inside the framework is reached through the module loader,\n * so the first frame under it is a runtime internal such as\n * `node:internal/process/task_queues`, which is a real frame and a false\n * author. A test, an example, and a workspace's own flow file are absolute\n * paths under none of those, so they are what a capture reports.\n *\n * Windows spells those same two directories with backslashes, so separators\n * are read as one before matching: a framework frame taken for an author's\n * would name this package's own `make.js` as the site every node of that run\n * was declared at.\n *\n * @since 1.0.0\n * @category predicates\n */\nexport const isFrameworkPath = (path: string): boolean => {\n  if (!isFilePath(path)) return true\n  const separated = path.replaceAll(\"\\\\\", \"/\")\n  return separated.includes(\"/node_modules/\") || /\\/packages\\/smithers\\/.*\\/src\\//.test(separated)\n}\n\n/** Whether a frame path names a file on disk rather than a runtime module. @private */\nconst isFilePath = (path: string): boolean => path.startsWith(\"/\") || /^[A-Za-z]:[\\\\/]/.test(path)\n\n/** The `path:line:column` text of one stack frame, in either engine's spelling. @private */\nconst location = (frame: string): string | undefined => {\n  const parenthesized = /\\(([^()]*)\\)\\s*$/.exec(frame)\n  if (parenthesized !== null) return parenthesized[1]\n  const trimmed = frame.trim()\n  const at = trimmed.lastIndexOf(\"@\")\n  if (at >= 0) return trimmed.slice(at + 1)\n  return trimmed.startsWith(\"at \") ? trimmed.slice(3) : undefined\n}\n\n/** A `file://` url reported as a frame path, as an ordinary path. @private */\nconst normalize = (path: string): string =>\n  path.startsWith(\"file://\") ? decodeURIComponent(path.slice(\"file://\".length)) : path\n\n/**\n * Where bytes a host evaluated from one file were read from. @private\n *\n * Keyed by the file that was evaluated, which a loader makes unique per load.\n */\nconst sourcesKey = Symbol.for(\"@smthrs/flow/DeclaredAt/sources/v1\")\nconst globals = globalThis as typeof globalThis & { [sourcesKey]?: Map<string, string> }\nconst sources = globals[sourcesKey] ??= new Map<string, string>()\n\n/**\n * States that a file this runtime is about to evaluate holds bytes read from\n * another, so declarations inside it report the file an author can open.\n *\n * A host that verifies a flow's source has to evaluate THE BYTES IT MEASURED,\n * and the only way to evaluate bytes in this runtime is to write them\n * somewhere and import that path. `@smthrs/registry` `Executable` writes them\n * as a scratch sibling of the entry and removes it as soon as the load is\n * over, so without this every declaration in an agent-authored flow reports a\n * path nothing holds \u2014 a Code tab that can never be opened (D-068).\n *\n * The loader states this BEFORE the import, because a declaration's site is\n * captured while the module is evaluated and is never rewritten afterwards.\n * One entry is kept per load: a scratch path is unique and gone, so no later\n * file can take a stale entry's name.\n *\n * @since 1.0.0\n * @category constructors\n */\nexport const evaluatedFrom = (evaluated: string, entry: string): void => {\n  sources.set(normalize(evaluated), normalize(entry))\n}\n\n/**\n * The position one stack frame names, in the V8 and JavaScriptCore spellings.\n *\n * V8 writes `    at name (/path/file.ts:12:5)` and, for a top-level frame,\n * `    at /path/file.ts:12:5`. JavaScriptCore \u2014 Bun and Safari \u2014 writes\n * `name@/path/file.ts:12:5` and `@/path/file.ts:12:5`. Anything else is\n * unparseable and reports nothing.\n *\n * @since 1.0.0\n * @category parsers\n */\nexport const parseFrame = (frame: string): DeclaredAt | undefined => {\n  const text = location(frame)\n  if (text === undefined) return undefined\n  const position = /^(.*):(\\d+):(\\d+)$/.exec(text)\n  if (position === null) return undefined\n  const line = Number(position[2])\n  // A frame naming a file a host evaluated measured bytes into reports the\n  // entry those bytes were read from; every other frame reports itself.\n  const path = normalize(position[1]!)\n  return { path: sources.get(path) ?? path, line }\n}\n\n/**\n * The first author frame of a captured stack.\n *\n * The header line every V8 stack starts with parses as nothing, so it needs no\n * special case. A decoding failure inside a frame path \u2014 a malformed percent\n * escape in a `file://` url \u2014 is an unparseable stack rather than a throw,\n * which is the whole contract of this module: provenance is a nicety, and a\n * nicety may never take a declaration down with it.\n *\n * @since 1.0.0\n * @category parsers\n */\nexport const parseStack = (stack: string | undefined): DeclaredAt | undefined => {\n  if (stack === undefined) return undefined\n  try {\n    for (const frame of stack.split(\"\\n\")) {\n      const parsed = parseFrame(frame)\n      if (parsed !== undefined && !isFrameworkPath(parsed.path)) return parsed\n    }\n    return undefined\n  } catch {\n    return undefined\n  }\n}\n\n/**\n * Where the caller of the function calling this was written.\n *\n * @since 1.0.0\n * @category constructors\n */\nexport const capture = (): DeclaredAt | undefined => parseStack(new Error().stack)\n\n/**\n * Carries a source position on a declaration without adding a field to it.\n *\n * The property is non-enumerable and non-writable, so it cannot reach a\n * canonical serialization, a digest, or a structural clone, and a later caller\n * cannot rewrite one declaration's provenance to another's.\n *\n * @since 1.0.0\n * @category constructors\n */\nexport const annotate = <A extends object>(value: A, site: DeclaredAt | undefined): A => {\n  // A declaration annotated twice keeps the FIRST site. The property is\n  // non-configurable, so a second `defineProperty` would throw rather than\n  // overwrite, and a copy that carries its own site has already recorded it.\n  if (site === undefined || Object.getOwnPropertyDescriptor(value, TypeId) !== undefined) return value\n  Object.defineProperty(value, TypeId, {\n    configurable: false,\n    enumerable: false,\n    value: site,\n    writable: false\n  })\n  return value\n}\n\n/**\n * The source position a value carries, when it carries one.\n *\n * Read through an own data descriptor, so neither a prototype nor an accessor\n * on a foreign value can answer for it.\n *\n * @since 1.0.0\n * @category accessors\n */\nexport const declaredAt = (value: unknown): DeclaredAt | undefined => {\n  if (Object(value) !== value) return undefined\n  const descriptor = Object.getOwnPropertyDescriptor(value, TypeId)\n  return descriptor === undefined ? undefined : descriptor.value as DeclaredAt | undefined\n}\n"],
+  "mappings": ";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAyBA,MAAM,SAAS;AAwCR,MAAM,kBAAkB,CAAC,SAA0B;AACxD,MAAI,CAAC,WAAW,IAAI,EAAG,QAAO;AAC9B,QAAM,YAAY,KAAK,WAAW,MAAM,GAAG;AAC3C,SAAO,UAAU,SAAS,gBAAgB,KAAK,kCAAkC,KAAK,SAAS;AACjG;AAGA,MAAM,aAAa,CAAC,SAA0B,KAAK,WAAW,GAAG,KAAK,kBAAkB,KAAK,IAAI;AAGjG,MAAM,WAAW,CAAC,UAAsC;AACtD,QAAM,gBAAgB,mBAAmB,KAAK,KAAK;AACnD,MAAI,kBAAkB,KAAM,QAAO,cAAc,CAAC;AAClD,QAAM,UAAU,MAAM,KAAK;AAC3B,QAAM,KAAK,QAAQ,YAAY,GAAG;AAClC,MAAI,MAAM,EAAG,QAAO,QAAQ,MAAM,KAAK,CAAC;AACxC,SAAO,QAAQ,WAAW,KAAK,IAAI,QAAQ,MAAM,CAAC,IAAI;AACxD;AAGA,MAAM,YAAY,CAAC,SACjB,KAAK,WAAW,SAAS,IAAI,mBAAmB,KAAK,MAAM,UAAU,MAAM,CAAC,IAAI;AAOlF,MAAM,aAAa,uBAAO,IAAI,oCAAoC;AAClE,MAAM,UAAU;AAChB,MAAM,UAAU,QAAQ,UAAU,MAAM,oBAAI,IAAoB;AAqBzD,MAAM,gBAAgB,CAAC,WAAmB,UAAwB;AACvE,UAAQ,IAAI,UAAU,SAAS,GAAG,UAAU,KAAK,CAAC;AACpD;AAaO,MAAM,aAAa,CAAC,UAA0C;AACnE,QAAM,OAAO,SAAS,KAAK;AAC3B,MAAI,SAAS,OAAW,QAAO;AAC/B,QAAM,WAAW,qBAAqB,KAAK,IAAI;AAC/C,MAAI,aAAa,KAAM,QAAO;AAC9B,QAAM,OAAO,OAAO,SAAS,CAAC,CAAC;AAG/B,QAAM,OAAO,UAAU,SAAS,CAAC,CAAE;AACnC,SAAO,EAAE,MAAM,QAAQ,IAAI,IAAI,KAAK,MAAM,KAAK;AACjD;AAcO,MAAM,aAAa,CAAC,UAAsD;AAC/E,MAAI,UAAU,OAAW,QAAO;AAChC,MAAI;AACF,eAAW,SAAS,MAAM,MAAM,IAAI,GAAG;AACrC,YAAM,SAAS,WAAW,KAAK;AAC/B,UAAI,WAAW,UAAa,CAAC,gBAAgB,OAAO,IAAI,EAAG,QAAO;AAAA,IACpE;AACA,WAAO;AAAA,EACT,QAAQ;AACN,WAAO;AAAA,EACT;AACF;AAQO,MAAM,UAAU,MAA8B,WAAW,IAAI,MAAM,EAAE,KAAK;AAY1E,MAAM,WAAW,CAAmB,OAAU,SAAoC;AAIvF,MAAI,SAAS,UAAa,OAAO,yBAAyB,OAAO,MAAM,MAAM,OAAW,QAAO;AAC/F,SAAO,eAAe,OAAO,QAAQ;AAAA,IACnC,cAAc;AAAA,IACd,YAAY;AAAA,IACZ,OAAO;AAAA,IACP,UAAU;AAAA,EACZ,CAAC;AACD,SAAO;AACT;AAWO,MAAM,aAAa,CAAC,UAA2C;AACpE,MAAI,OAAO,KAAK,MAAM,MAAO,QAAO;AACpC,QAAM,aAAa,OAAO,yBAAyB,OAAO,MAAM;AAChE,SAAO,eAAe,SAAY,SAAY,WAAW;AAC3D;",
+  "names": []
+}

package/dist/cjs/internal/Declarations.d.ts

@@ -0,0 +1,35 @@
+/**
+ * The lowering every declaration in this package shares: literal
+ * `capabilities`, `effects` and `modelInvocable` become entries in the
+ * annotation bag readers already consult.
+ *
+ * Both literals exist so a CATALOG can project them from source text without
+ * importing the module, so this is the only place either spelling is turned
+ * into a value. A flow or an action that declares `capabilities` and one that
+ * annotates {@link module:Flow/Annotations.Capabilities} are the same
+ * declaration to {@link module:Graph.build}, and the same holds for `effects`
+ * and {@link module:Flow/Annotations.EffectEnvelope}.
+ *
+ * It lives here, below both constructors, because a flow and an action lower
+ * the same two literals and a second copy would let one gain a field the other
+ * kept ignoring.
+ *
+ * @since 0.1.0
+ * @private
+ */
+import * as Effects from "@smthrs/plan/Effects";
+import * as Context from "effect/Context";
+/**
+ * Lowers the literal declarations a constructor call carries into the
+ * annotation bag, leaving every annotation the caller already supplied.
+ *
+ * @since 0.1.0
+ * @private
+ */
+export declare const lowerDeclarations: (options: {
+    readonly capabilities?: ReadonlyArray<string> | undefined;
+    readonly effects?: Effects.MakeOptions | undefined;
+    readonly modelInvocable?: boolean | undefined;
+    readonly annotations?: Context.Context<never> | undefined;
+}) => Context.Context<never>;
+//# sourceMappingURL=Declarations.d.ts.map

package/dist/cjs/internal/Declarations.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Declarations.d.ts","sourceRoot":"","sources":["../../../src/internal/Declarations.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,KAAK,OAAO,MAAM,sBAAsB,CAAA;AAC/C,OAAO,KAAK,OAAO,MAAM,gBAAgB,CAAA;AAGzC;;;;;;GAMG;AACH,eAAO,MAAM,iBAAiB,GAAI,SAAS;IACzC,QAAQ,CAAC,YAAY,CAAC,EAAE,aAAa,CAAC,MAAM,CAAC,GAAG,SAAS,CAAA;IACzD,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC,WAAW,GAAG,SAAS,CAAA;IAClD,QAAQ,CAAC,cAAc,CAAC,EAAE,OAAO,GAAG,SAAS,CAAA;IAC7C,QAAQ,CAAC,WAAW,CAAC,EAAE,OAAO,CAAC,OAAO,CAAC,KAAK,CAAC,GAAG,SAAS,CAAA;CAC1D,KAAG,OAAO,CAAC,OAAO,CAAC,KAAK,CAYxB,CAAA"}

package/dist/cjs/internal/Declarations.js

@@ -0,0 +1,50 @@
+"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 Declarations_exports = {};
+__export(Declarations_exports, {
+  lowerDeclarations: () => lowerDeclarations
+});
+module.exports = __toCommonJS(Declarations_exports);
+var Effects = __toESM(require("@smthrs/plan/Effects"), 1);
+var Context = __toESM(require("effect/Context"), 1);
+var import_Annotations = require("../Flow/Annotations.js");
+const lowerDeclarations = (options) => {
+  let annotations = options.annotations ?? Context.empty();
+  if (options.capabilities !== void 0) {
+    annotations = Context.add(annotations, import_Annotations.Capabilities, options.capabilities);
+  }
+  if (options.effects !== void 0) {
+    annotations = Context.add(annotations, import_Annotations.EffectEnvelope, Effects.make(options.effects));
+  }
+  if (options.modelInvocable !== void 0) {
+    annotations = Context.add(annotations, import_Annotations.ModelInvocable, options.modelInvocable);
+  }
+  return annotations;
+};
+//# sourceMappingURL=Declarations.js.map

package/dist/cjs/internal/Declarations.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../src/internal/Declarations.ts"],
+  "sourcesContent": ["/**\n * The lowering every declaration in this package shares: literal\n * `capabilities`, `effects` and `modelInvocable` become entries in the\n * annotation bag readers already consult.\n *\n * Both literals exist so a CATALOG can project them from source text without\n * importing the module, so this is the only place either spelling is turned\n * into a value. A flow or an action that declares `capabilities` and one that\n * annotates {@link module:Flow/Annotations.Capabilities} are the same\n * declaration to {@link module:Graph.build}, and the same holds for `effects`\n * and {@link module:Flow/Annotations.EffectEnvelope}.\n *\n * It lives here, below both constructors, because a flow and an action lower\n * the same two literals and a second copy would let one gain a field the other\n * kept ignoring.\n *\n * @since 0.1.0\n * @private\n */\n\nimport * as Effects from \"@smthrs/plan/Effects\"\nimport * as Context from \"effect/Context\"\nimport { Capabilities, EffectEnvelope, ModelInvocable } from \"../Flow/Annotations.ts\"\n\n/**\n * Lowers the literal declarations a constructor call carries into the\n * annotation bag, leaving every annotation the caller already supplied.\n *\n * @since 0.1.0\n * @private\n */\nexport const lowerDeclarations = (options: {\n  readonly capabilities?: ReadonlyArray<string> | undefined\n  readonly effects?: Effects.MakeOptions | undefined\n  readonly modelInvocable?: boolean | undefined\n  readonly annotations?: Context.Context<never> | undefined\n}): Context.Context<never> => {\n  let annotations = options.annotations ?? Context.empty()\n  if (options.capabilities !== undefined) {\n    annotations = Context.add(annotations, Capabilities, options.capabilities)\n  }\n  if (options.effects !== undefined) {\n    annotations = Context.add(annotations, EffectEnvelope, Effects.make(options.effects))\n  }\n  if (options.modelInvocable !== undefined) {\n    annotations = Context.add(annotations, ModelInvocable, options.modelInvocable)\n  }\n  return annotations\n}\n"],
+  "mappings": ";;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAoBA,cAAyB;AACzB,cAAyB;AACzB,yBAA6D;AAStD,MAAM,oBAAoB,CAAC,YAKJ;AAC5B,MAAI,cAAc,QAAQ,eAAe,QAAQ,MAAM;AACvD,MAAI,QAAQ,iBAAiB,QAAW;AACtC,kBAAc,QAAQ,IAAI,aAAa,iCAAc,QAAQ,YAAY;AAAA,EAC3E;AACA,MAAI,QAAQ,YAAY,QAAW;AACjC,kBAAc,QAAQ,IAAI,aAAa,mCAAgB,QAAQ,KAAK,QAAQ,OAAO,CAAC;AAAA,EACtF;AACA,MAAI,QAAQ,mBAAmB,QAAW;AACxC,kBAAc,QAAQ,IAAI,aAAa,mCAAgB,QAAQ,cAAc;AAAA,EAC/E;AACA,SAAO;AACT;",
+  "names": []
+}

package/dist/cjs/internal/ExecutionMiddleware.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Internal interpreter seam for authoring combinators that retain execution
+ * scope state around the ordinary body. No graph or runtime decision lives here.
+ *
+ * @since 1.0.0
+ */
+import * as Context from "effect/Context";
+import type * as Effect from "effect/Effect";
+/** Internal execution wrapper.
+ * @private
+ * @since 1.0.0
+ */
+export interface ExecutionMiddleware {
+    readonly wrap: (payload: unknown, body: Effect.Effect<unknown, unknown, unknown>) => Effect.Effect<unknown, unknown, unknown>;
+}
+/** Flow-owned wrapper retained across interpreter registrations.
+ * @private
+ * @since 1.0.0
+ */
+export declare const ExecutionMiddleware: Context.Reference<ExecutionMiddleware | undefined>;
+//# sourceMappingURL=ExecutionMiddleware.d.ts.map

package/dist/cjs/internal/ExecutionMiddleware.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ExecutionMiddleware.d.ts","sourceRoot":"","sources":["../../../src/internal/ExecutionMiddleware.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,OAAO,MAAM,gBAAgB,CAAA;AACzC,OAAO,KAAK,KAAK,MAAM,MAAM,eAAe,CAAA;AAE5C;;;GAGG;AACH,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,IAAI,EAAE,CACb,OAAO,EAAE,OAAO,EAChB,IAAI,EAAE,MAAM,CAAC,MAAM,CAAC,OAAO,EAAE,OAAO,EAAE,OAAO,CAAC,KAC3C,MAAM,CAAC,MAAM,CAAC,OAAO,EAAE,OAAO,EAAE,OAAO,CAAC,CAAA;CAC9C;AAED;;;GAGG;AACH,eAAO,MAAM,mBAAmB,oDAG/B,CAAA"}

package/dist/cjs/internal/ExecutionMiddleware.js

@@ -0,0 +1,39 @@
+"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 ExecutionMiddleware_exports = {};
+__export(ExecutionMiddleware_exports, {
+  ExecutionMiddleware: () => ExecutionMiddleware
+});
+module.exports = __toCommonJS(ExecutionMiddleware_exports);
+var Context = __toESM(require("effect/Context"), 1);
+const ExecutionMiddleware = Context.Reference(
+  "@smthrs/flow/internal/ExecutionMiddleware",
+  { defaultValue: () => void 0 }
+);
+//# sourceMappingURL=ExecutionMiddleware.js.map

package/dist/cjs/internal/ExecutionMiddleware.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../src/internal/ExecutionMiddleware.ts"],
+  "sourcesContent": ["/**\n * Internal interpreter seam for authoring combinators that retain execution\n * scope state around the ordinary body. No graph or runtime decision lives here.\n *\n * @since 1.0.0\n */\n\nimport * as Context from \"effect/Context\"\nimport type * as Effect from \"effect/Effect\"\n\n/** Internal execution wrapper.\n * @private\n * @since 1.0.0\n */\nexport interface ExecutionMiddleware {\n  readonly wrap: (\n    payload: unknown,\n    body: Effect.Effect<unknown, unknown, unknown>\n  ) => Effect.Effect<unknown, unknown, unknown>\n}\n\n/** Flow-owned wrapper retained across interpreter registrations.\n * @private\n * @since 1.0.0\n */\nexport const ExecutionMiddleware = Context.Reference<ExecutionMiddleware | undefined>(\n  \"@smthrs/flow/internal/ExecutionMiddleware\",\n  { defaultValue: () => undefined }\n)\n"],
+  "mappings": ";;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAOA,cAAyB;AAkBlB,MAAM,sBAAsB,QAAQ;AAAA,EACzC;AAAA,EACA,EAAE,cAAc,MAAM,OAAU;AAClC;",
+  "names": []
+}

package/dist/cjs/internal/JsonSchemaSubset.d.ts

@@ -0,0 +1,133 @@
+/**
+ * The bounded JSON Schema subset a human-task answer is checked against.
+ *
+ * `HumanTask` asks a person for a value and refuses one that does not fit the
+ * question. The fit for a `json` question is decided here: a schema is kept
+ * inside a deliberately small subset, an answer is checked against it under
+ * the same size bounds every human-task value is admitted under, and every
+ * rejection is rendered within one diagnostic budget. `HumanTask` re-exports
+ * the limits and the two public entry points; this file is the mechanism.
+ *
+ * @since 1.0.0
+ */
+import * as BoundedJson from "./BoundedJson.ts";
+/**
+ * The deepest supported JSON Schema path, counting the root as depth zero.
+ *
+ * @private
+ * @since 1.0.0
+ */
+export declare const maxSchemaDepth = 32;
+/**
+ * The most schema objects one human-task request may contain.
+ *
+ * @private
+ * @since 1.0.0
+ */
+export declare const maxSchemaNodes = 512;
+/**
+ * The most JSON values embedded across schema keywords such as `enum`.
+ *
+ * @private
+ * @since 1.0.0
+ */
+export declare const maxSchemaValueNodes = 10000;
+/**
+ * The deepest JSON value embedded in a schema, including enum members.
+ *
+ * @private
+ * @since 1.0.0
+ */
+export declare const maxSchemaValueDepth = 64;
+/**
+ * The most JSON values one answer validation may visit.
+ *
+ * @private
+ * @since 1.0.0
+ */
+export declare const maxAnswerNodes = 10000;
+/**
+ * The largest encoded JSON answer that can enter the durable store.
+ *
+ * @private
+ * @since 1.0.0
+ */
+export declare const maxAnswerBytes: number;
+/**
+ * The largest encoded JSON Schema carried by one question.
+ *
+ * @private
+ * @since 1.0.0
+ */
+export declare const maxSchemaBytes: number;
+/**
+ * The deepest admitted answer tree.
+ *
+ * @private
+ * @since 1.0.0
+ */
+export declare const maxAnswerDepth = 64;
+/**
+ * The largest encoded string value admitted in a request or answer.
+ *
+ * @private
+ * @since 1.0.0
+ */
+export declare const maxJsonStringBytes: number;
+/**
+ * The largest encoded object key admitted in a request or answer.
+ *
+ * @private
+ * @since 1.0.0
+ */
+export declare const maxJsonKeyBytes: number;
+/**
+ * The most members admitted in one JSON array or object.
+ *
+ * @private
+ * @since 1.0.0
+ */
+export declare const maxJsonMembers = 10000;
+/**
+ * The most caller-supplied characters retained in one rendered diagnostic.
+ *
+ * @private
+ * @since 1.0.0
+ */
+export declare const maxDiagnosticChars = 512;
+/** Truncates a caller-supplied diagnostic while stating exactly what was dropped.
+ * @private
+ * @since 1.0.0
+ */
+export declare const truncateDiagnostic: (rendered: string) => string;
+/** Renders one JSON value for a bounded rejection message.
+ * @private
+ * @since 1.0.0
+ */
+export declare const renderDiagnostic: (value: unknown) => string;
+/** The bounds one answer is admitted under.
+ * @private
+ * @since 1.0.0
+ */
+export declare const answerLimits: BoundedJson.Limits;
+/** The bounds one schema is admitted under, enum members included.
+ * @private
+ * @since 1.0.0
+ */
+export declare const schemaLimits: BoundedJson.Limits;
+/** Checks schema validity and snapshots both inputs before walking them together.
+ * @private
+ * @since 1.0.0
+ */
+export declare const check: (value: unknown, schema: unknown) => string | undefined;
+/**
+ * Checks that a JSON Schema stays inside the bounded subset, at every depth.
+ *
+ * Returns the first reason the schema is out of bounds, or `undefined` when the
+ * whole tree is inside it.
+ *
+ * @private
+ * @since 1.0.0
+ */
+export declare const validateSchema: (schema: unknown, path: ReadonlyArray<string>) => string | undefined;
+//# sourceMappingURL=JsonSchemaSubset.d.ts.map

package/dist/cjs/internal/JsonSchemaSubset.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"JsonSchemaSubset.d.ts","sourceRoot":"","sources":["../../../src/internal/JsonSchemaSubset.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,WAAW,MAAM,kBAAkB,CAAA;AAE/C;;;;;GAKG;AACH,eAAO,MAAM,cAAc,KAAK,CAAA;AAEhC;;;;;GAKG;AACH,eAAO,MAAM,cAAc,MAAM,CAAA;AAEjC;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB,QAAS,CAAA;AAEzC;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB,KAAK,CAAA;AAErC;;;;;GAKG;AACH,eAAO,MAAM,cAAc,QAAS,CAAA;AAEpC;;;;;GAKG;AACH,eAAO,MAAM,cAAc,QAAa,CAAA;AAExC;;;;;GAKG;AACH,eAAO,MAAM,cAAc,QAAa,CAAA;AAExC;;;;;GAKG;AACH,eAAO,MAAM,cAAc,KAAK,CAAA;AAEhC;;;;;GAKG;AACH,eAAO,MAAM,kBAAkB,QAAa,CAAA;AAE5C;;;;;GAKG;AACH,eAAO,MAAM,eAAe,QAAW,CAAA;AAEvC;;;;;GAKG;AACH,eAAO,MAAM,cAAc,QAAS,CAAA;AAEpC;;;;;GAKG;AACH,eAAO,MAAM,kBAAkB,MAAM,CAAA;AAiBrC;;;GAGG;AACH,eAAO,MAAM,kBAAkB,GAAI,UAAU,MAAM,KAAG,MAKrD,CAAA;AAED;;;GAGG;AACH,eAAO,MAAM,gBAAgB,GAAI,OAAO,OAAO,KAAG,MAAuD,CAAA;AA8CzG;;;GAGG;AACH,eAAO,MAAM,YAAY,EAAE,WAAW,CAAC,MAOtC,CAAA;AAED;;;GAGG;AACH,eAAO,MAAM,YAAY,EAAE,WAAW,CAAC,MAOtC,CAAA;AAsFD;;;GAGG;AACH,eAAO,MAAM,KAAK,GAAI,OAAO,OAAO,EAAE,QAAQ,OAAO,KAAG,MAAM,GAAG,SAQhE,CAAA;AAiED;;;;;;;;GAQG;AACH,eAAO,MAAM,cAAc,GACzB,QAAQ,OAAO,EACf,MAAM,aAAa,CAAC,MAAM,CAAC,KAC1B,MAAM,GAAG,SAKX,CAAA"}