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

package/dist/esm/internal/BoundedJson.js

@@ -0,0 +1,107 @@
+/**
+ * Human-task diagnostics over the shared inert JSON boundary.
+ * @since 1.0.0
+ */
+import * as BoundedJson from "@smthrs/canonical/BoundedJson";
+/** Encoded JSON bytes, without allocating an encoded copy.
+ * @private
+ * @since 1.0.0
+ */
+export const encodedStringBytes = BoundedJson.encodedStringBytes;
+/** Whether text is well-formed and fits its encoded byte budget.
+ * @private
+ * @since 1.0.0
+ */
+export const textFits = (value, maximum) => encodedStringBytes(value, maximum) !== undefined;
+/** Admits a detached snapshot and gives failures a bounded field path.
+ * @private
+ * @since 1.0.0
+ */
+export const admit = (input, limits) => {
+    const result = BoundedJson.admit(input, limits);
+    if (result.ok)
+        return { ok: true, value: result.value };
+    const at = result.path.length === 0
+        ? "the value"
+        : `"${result.path.map((segment) => scalarPrefix(segment, 64)).join(".")}"`;
+    const complaint = result.code === "string"
+        ? `is not well-formed text within ${limits.maxStringBytes} encoded bytes`
+        : result.code === "nodes"
+            ? `makes the value too large to check: it contains more than ${limits.maxNodes} JSON values`
+            : result.complaint;
+    return { ok: false, complaint: `${at} ${complaint}.` };
+};
+/**
+ * Returns a Unicode-scalar-safe bounded prefix.
+ *
+ * @private
+ * @since 1.0.0
+ */
+export function scalarPrefix(value, maximumCodeUnits) {
+    let output = "";
+    for (let index = 0; index < value.length;) {
+        const unit = value.charCodeAt(index);
+        let next;
+        let width = 1;
+        if (unit >= 0xd800 && unit <= 0xdbff) {
+            const low = value.charCodeAt(index + 1);
+            if (low >= 0xdc00 && low <= 0xdfff) {
+                next = value.slice(index, index + 2);
+                width = 2;
+            }
+            else {
+                next = "\ufffd";
+            }
+        }
+        else if (unit >= 0xdc00 && unit <= 0xdfff) {
+            next = "\ufffd";
+        }
+        else {
+            next = value[index];
+        }
+        if (output.length + next.length > maximumCodeUnits)
+            break;
+        output += next;
+        index += width;
+    }
+    return output;
+}
+/**
+ * Renders an untrusted value without invoking its code or allocating from its full size.
+ *
+ * @private
+ * @since 1.0.0
+ */
+export const render = (value, maximumCodeUnits) => {
+    if (typeof value === "string") {
+        const prefix = scalarPrefix(value, Math.max(0, maximumCodeUnits - 2));
+        const quoted = JSON.stringify(prefix);
+        return prefix.length < value.length
+            ? `${quoted} [${value.length - prefix.length} characters dropped]`
+            : quoted;
+    }
+    if (typeof value === "bigint")
+        return scalarPrefix(`${value}n`, maximumCodeUnits);
+    if (typeof value === "symbol")
+        return "[symbol]";
+    if (typeof value === "function")
+        return "[function]";
+    if (value === undefined)
+        return "[undefined]";
+    const admitted = admit(value, {
+        maxNodes: 64,
+        maxDepth: 6,
+        maxBytes: Math.max(64, maximumCodeUnits * 4),
+        maxStringBytes: Math.max(64, maximumCodeUnits * 4),
+        maxKeyBytes: Math.max(32, maximumCodeUnits * 2),
+        maxMembers: 32
+    });
+    if (!admitted.ok)
+        return scalarPrefix(`[${admitted.complaint}]`, maximumCodeUnits);
+    const rendered = JSON.stringify(admitted.value);
+    const prefix = scalarPrefix(rendered, maximumCodeUnits);
+    return prefix.length < rendered.length
+        ? `${prefix} [${rendered.length - prefix.length} characters dropped]`
+        : prefix;
+};
+//# sourceMappingURL=BoundedJson.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"BoundedJson.js","sourceRoot":"","sources":["../../../src/internal/BoundedJson.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Human-task diagnostics over the shared inert JSON boundary.\n * @since 1.0.0\n */\n\nimport * as BoundedJson from \"@smthrs/canonical/BoundedJson\"\n\n/** Resource limits for one human-task value.\n * @private\n * @since 1.0.0\n */\nexport type Limits = Required<Omit<BoundedJson.Limits, \"maxTotalMembers\">>\n\n/** Encoded JSON bytes, without allocating an encoded copy.\n * @private\n * @since 1.0.0\n */\nexport const encodedStringBytes = BoundedJson.encodedStringBytes\n\n/** Whether text is well-formed and fits its encoded byte budget.\n * @private\n * @since 1.0.0\n */\nexport const textFits = (value: string, maximum: number): boolean => encodedStringBytes(value, maximum) !== undefined\n\n/** Admits a detached snapshot and gives failures a bounded field path.\n * @private\n * @since 1.0.0\n */\nexport const admit = (input: unknown, limits: Limits) => {\n  const result = BoundedJson.admit(input, limits)\n  if (result.ok) return { ok: true as const, value: result.value }\n  const at = result.path.length === 0\n    ? \"the value\"\n    : `\"${result.path.map((segment) => scalarPrefix(segment, 64)).join(\".\")}\"`\n  const complaint = result.code === \"string\"\n    ? `is not well-formed text within ${limits.maxStringBytes} encoded bytes`\n    : result.code === \"nodes\"\n    ? `makes the value too large to check: it contains more than ${limits.maxNodes} JSON values`\n    : result.complaint\n  return { ok: false as const, complaint: `${at} ${complaint}.` }\n}\n\n/**\n * Returns a Unicode-scalar-safe bounded prefix.\n *\n * @private\n * @since 1.0.0\n */\nexport function scalarPrefix(value: string, maximumCodeUnits: number): string {\n  let output = \"\"\n  for (let index = 0; index < value.length;) {\n    const unit = value.charCodeAt(index)\n    let next: string\n    let width = 1\n    if (unit >= 0xd800 && unit <= 0xdbff) {\n      const low = value.charCodeAt(index + 1)\n      if (low >= 0xdc00 && low <= 0xdfff) {\n        next = value.slice(index, index + 2)\n        width = 2\n      } else {\n        next = \"\\ufffd\"\n      }\n    } else if (unit >= 0xdc00 && unit <= 0xdfff) {\n      next = \"\\ufffd\"\n    } else {\n      next = value[index]!\n    }\n    if (output.length + next.length > maximumCodeUnits) break\n    output += next\n    index += width\n  }\n  return output\n}\n\n/**\n * Renders an untrusted value without invoking its code or allocating from its full size.\n *\n * @private\n * @since 1.0.0\n */\nexport const render = (value: unknown, maximumCodeUnits: number): string => {\n  if (typeof value === \"string\") {\n    const prefix = scalarPrefix(value, Math.max(0, maximumCodeUnits - 2))\n    const quoted = JSON.stringify(prefix)\n    return prefix.length < value.length\n      ? `${quoted} [${value.length - prefix.length} characters dropped]`\n      : quoted\n  }\n  if (typeof value === \"bigint\") return scalarPrefix(`${value}n`, maximumCodeUnits)\n  if (typeof value === \"symbol\") return \"[symbol]\"\n  if (typeof value === \"function\") return \"[function]\"\n  if (value === undefined) return \"[undefined]\"\n\n  const admitted = admit(value, {\n    maxNodes: 64,\n    maxDepth: 6,\n    maxBytes: Math.max(64, maximumCodeUnits * 4),\n    maxStringBytes: Math.max(64, maximumCodeUnits * 4),\n    maxKeyBytes: Math.max(32, maximumCodeUnits * 2),\n    maxMembers: 32\n  })\n  if (!admitted.ok) return scalarPrefix(`[${admitted.complaint}]`, maximumCodeUnits)\n  const rendered = JSON.stringify(admitted.value)\n  const prefix = scalarPrefix(rendered, maximumCodeUnits)\n  return prefix.length < rendered.length\n    ? `${prefix} [${rendered.length - prefix.length} characters dropped]`\n    : prefix\n}\n"]}

package/dist/esm/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/esm/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/esm/internal/DeclarationSite.js

@@ -0,0 +1,196 @@
+/**
+ * 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 own property a declaration carries its source position on. @private */
+const TypeId = "~@smthrs/flow/DeclaredAt";
+/**
+ * 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 const isFrameworkPath = (path) => {
+    if (!isFilePath(path))
+        return true;
+    const separated = path.replaceAll("\\", "/");
+    return separated.includes("/node_modules/") || /\/packages\/smithers\/.*\/src\//.test(separated);
+};
+/** Whether a frame path names a file on disk rather than a runtime module. @private */
+const isFilePath = (path) => path.startsWith("/") || /^[A-Za-z]:[\\/]/.test(path);
+/** The `path:line:column` text of one stack frame, in either engine's spelling. @private */
+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) : undefined;
+};
+/** A `file://` url reported as a frame path, as an ordinary path. @private */
+const normalize = (path) => path.startsWith("file://") ? decodeURIComponent(path.slice("file://".length)) : path;
+/**
+ * Where bytes a host evaluated from one file were read from. @private
+ *
+ * Keyed by the file that was evaluated, which a loader makes unique per load.
+ */
+const sourcesKey = Symbol.for("@smthrs/flow/DeclaredAt/sources/v1");
+const globals = globalThis;
+const sources = globals[sourcesKey] ??= new Map();
+/**
+ * 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 const evaluatedFrom = (evaluated, entry) => {
+    sources.set(normalize(evaluated), normalize(entry));
+};
+/**
+ * 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 const parseFrame = (frame) => {
+    const text = location(frame);
+    if (text === undefined)
+        return undefined;
+    const position = /^(.*):(\d+):(\d+)$/.exec(text);
+    if (position === null)
+        return undefined;
+    const line = Number(position[2]);
+    // A frame naming a file a host evaluated measured bytes into reports the
+    // entry those bytes were read from; every other frame reports itself.
+    const path = normalize(position[1]);
+    return { path: sources.get(path) ?? path, line };
+};
+/**
+ * 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 const parseStack = (stack) => {
+    if (stack === undefined)
+        return undefined;
+    try {
+        for (const frame of stack.split("\n")) {
+            const parsed = parseFrame(frame);
+            if (parsed !== undefined && !isFrameworkPath(parsed.path))
+                return parsed;
+        }
+        return undefined;
+    }
+    catch {
+        return undefined;
+    }
+};
+/**
+ * Where the caller of the function calling this was written.
+ *
+ * @since 1.0.0
+ * @category constructors
+ */
+export const capture = () => parseStack(new Error().stack);
+/**
+ * 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 const annotate = (value, site) => {
+    // A declaration annotated twice keeps the FIRST site. The property is
+    // non-configurable, so a second `defineProperty` would throw rather than
+    // overwrite, and a copy that carries its own site has already recorded it.
+    if (site === undefined || Object.getOwnPropertyDescriptor(value, TypeId) !== undefined)
+        return value;
+    Object.defineProperty(value, TypeId, {
+        configurable: false,
+        enumerable: false,
+        value: site,
+        writable: false
+    });
+    return value;
+};
+/**
+ * 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 const declaredAt = (value) => {
+    if (Object(value) !== value)
+        return undefined;
+    const descriptor = Object.getOwnPropertyDescriptor(value, TypeId);
+    return descriptor === undefined ? undefined : descriptor.value;
+};
+//# sourceMappingURL=DeclarationSite.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"DeclarationSite.js","sourceRoot":"","sources":["../../../src/internal/DeclarationSite.ts"],"names":[],"mappings":"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","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 — 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 — which walks enumerable keys —\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 — 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 — Bun and Safari — 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 — a malformed percent\n * escape in a `file://` url — 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"]}

package/dist/esm/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/esm/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/esm/internal/Declarations.js

@@ -0,0 +1,43 @@
+/**
+ * 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";
+import { Capabilities, EffectEnvelope, ModelInvocable } from "../Flow/Annotations.js";
+/**
+ * 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 const lowerDeclarations = (options) => {
+    let annotations = options.annotations ?? Context.empty();
+    if (options.capabilities !== undefined) {
+        annotations = Context.add(annotations, Capabilities, options.capabilities);
+    }
+    if (options.effects !== undefined) {
+        annotations = Context.add(annotations, EffectEnvelope, Effects.make(options.effects));
+    }
+    if (options.modelInvocable !== undefined) {
+        annotations = Context.add(annotations, ModelInvocable, options.modelInvocable);
+    }
+    return annotations;
+};
+//# sourceMappingURL=Declarations.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"Declarations.js","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;AACzC,OAAO,EAAE,YAAY,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAA;AAErF;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC,OAKjC,EAA0B,EAAE;IAC3B,IAAI,WAAW,GAAG,OAAO,CAAC,WAAW,IAAI,OAAO,CAAC,KAAK,EAAE,CAAA;IACxD,IAAI,OAAO,CAAC,YAAY,KAAK,SAAS,EAAE,CAAC;QACvC,WAAW,GAAG,OAAO,CAAC,GAAG,CAAC,WAAW,EAAE,YAAY,EAAE,OAAO,CAAC,YAAY,CAAC,CAAA;IAC5E,CAAC;IACD,IAAI,OAAO,CAAC,OAAO,KAAK,SAAS,EAAE,CAAC;QAClC,WAAW,GAAG,OAAO,CAAC,GAAG,CAAC,WAAW,EAAE,cAAc,EAAE,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,CAAA;IACvF,CAAC;IACD,IAAI,OAAO,CAAC,cAAc,KAAK,SAAS,EAAE,CAAC;QACzC,WAAW,GAAG,OAAO,CAAC,GAAG,CAAC,WAAW,EAAE,cAAc,EAAE,OAAO,CAAC,cAAc,CAAC,CAAA;IAChF,CAAC;IACD,OAAO,WAAW,CAAA;AACpB,CAAC,CAAA","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"]}

package/dist/esm/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/esm/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/esm/internal/ExecutionMiddleware.js

@@ -0,0 +1,13 @@
+/**
+ * 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";
+/** Flow-owned wrapper retained across interpreter registrations.
+ * @private
+ * @since 1.0.0
+ */
+export const ExecutionMiddleware = Context.Reference("@smthrs/flow/internal/ExecutionMiddleware", { defaultValue: () => undefined });
+//# sourceMappingURL=ExecutionMiddleware.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ExecutionMiddleware.js","sourceRoot":"","sources":["../../../src/internal/ExecutionMiddleware.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,OAAO,MAAM,gBAAgB,CAAA;AAczC;;;GAGG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,OAAO,CAAC,SAAS,CAClD,2CAA2C,EAC3C,EAAE,YAAY,EAAE,GAAG,EAAE,CAAC,SAAS,EAAE,CAClC,CAAA","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"]}