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

package/dist/esm/internal/FileEnumeration.js

@@ -0,0 +1,236 @@
+/**
+ * Workspace-relative file enumeration for glob and tree-artifact expansion.
+ *
+ * The host `glob` is deliberately not consulted. Two divergences make it the
+ * wrong oracle for a declared pattern: the kernel `FileSystem` absolutizes
+ * patterns against the workspace root and returns absolute paths, so a
+ * workspace-relative matcher filters every result out; and Node's matcher
+ * skips dotfiles, which `FileSet.matchesPattern` — and Bazel's glob — cover.
+ * Walking `readDirectory` and filtering through `FileSet` keeps every
+ * expansion byte-identical to the matcher the plan's overlap passes use, in
+ * the one coordinate system declarations are written in.
+ *
+ * @since 0.1.0
+ */
+import * as KernelFileSystem from "@smthrs/kernel/FileSystem";
+import * as FileSet from "@smthrs/plan/FileSet";
+import * as Effect from "effect/Effect";
+import * as Schema from "effect/Schema";
+/** Bounded metadata reads, preserving the input order and typed failures. */
+const metadata = (fs, paths, operation, fallback) => Effect.gen(function* () {
+    const batch = KernelFileSystem.batch(fs);
+    if (batch === undefined) {
+        return yield* Effect.forEach(paths, (path) => fallback(path), {
+            concurrency: KernelFileSystem.fallbackConcurrency
+        });
+    }
+    const values = [];
+    for (let offset = 0; offset < paths.length; offset += batch.maxSize) {
+        const response = yield* batch.execute(paths.slice(offset, offset + batch.maxSize).map((path) => ({ operation, path })));
+        for (const entry of [...response.entries].sort((a, b) => a.index - b.index)) {
+            const value = yield* Effect.fromResult(entry.result);
+            values.push((value.operation === "stat"
+                ? value.info
+                : value.paths));
+        }
+    }
+    return values;
+});
+/**
+ * The default maximum number of directory entries visited by one expansion.
+ *
+ * @since 1.0.0
+ * @category constants
+ */
+export const defaultMaxEntries = 100_000;
+/**
+ * The stable error code returned when enumeration exceeds its safety bound.
+ *
+ * @since 1.0.0
+ * @category errors
+ */
+export const FileEnumerationErrorCode = Schema.Literal("entry_limit_exceeded");
+/**
+ * A workspace enumeration exceeded its configured entry limit.
+ *
+ * @since 1.0.0
+ * @category errors
+ */
+export class FileEnumerationError extends Schema.TaggedError()("@smthrs/engine-store/FileEnumerationError", {
+    code: FileEnumerationErrorCode,
+    message: Schema.String,
+    pattern: Schema.String,
+    limit: Schema.Number,
+    cause: Schema.Unknown
+}) {
+}
+/** @internal */
+const defaultResolve = (path) => path === "" ? "." : path;
+const ignoredDirectoryNames = new Set([".git", ".jj", "node_modules"]);
+const budgetFor = (pattern, options) => ({
+    limit: options.maxEntries ?? defaultMaxEntries,
+    count: 0,
+    pattern
+});
+const explicitIgnoredDirectories = (patterns) => {
+    const explicit = new Set();
+    for (const pattern of patterns) {
+        for (const part of pattern.replaceAll("\\", "/").split("/")) {
+            if (ignoredDirectoryNames.has(part))
+                explicit.add(part);
+        }
+    }
+    return explicit;
+};
+const visit = (budget) => {
+    budget.count += 1;
+    if (budget.count <= budget.limit)
+        return Effect.void;
+    const message = `enumerating pattern ${JSON.stringify(budget.pattern)} exceeded the ${budget.limit}-entry limit`;
+    return Effect.fail(new FileEnumerationError({
+        code: "entry_limit_exceeded",
+        pattern: budget.pattern,
+        limit: budget.limit,
+        message,
+        cause: new RangeError(message)
+    }));
+};
+const enumerateUnder = (fs, dir, resolve, budget, pruneIgnoredDirectories, explicit = new Set()) => Effect.gen(function* () {
+    // A directory that is not there enumerates to nothing, and its own
+    // listing reports that with `NotFound` — so no `exists` probe precedes
+    // it. The probe asked the question the very next call answers anyway, and
+    // on a confined host every host call is one CPython fork
+    // (`@smthrs/platform-node/AtomicFileSystem`), so it doubled the cost of
+    // reaching the walk root. Only the root is probed this way; a subtree
+    // discovered by `stat` inside the walk is read without a net, exactly as
+    // before, so a listing that refuses there still fails the expansion.
+    const root = yield* metadata(fs, [resolve(dir)], "readDirectory", fs.readDirectory).pipe(Effect.map((values) => values[0]), Effect.catchReason("PlatformError", "NotFound", () => Effect.succeed(undefined)));
+    // The absent root is the one case that reports no directories at all: a
+    // tree replay must not be told to prune scaffolding that never existed.
+    if (root === undefined)
+        return { files: [], directories: [] };
+    const files = [];
+    const directories = [dir];
+    const pending = [{ path: dir, entries: [...root].sort(), index: 0 }];
+    const size = KernelFileSystem.batch(fs)?.maxSize ?? KernelFileSystem.fallbackConcurrency;
+    while (pending.length > 0) {
+        const paths = [];
+        // Fill one batch from all queued listings. A tree with one file in each
+        // of many sibling directories must not start one helper per leaf.
+        while (paths.length < size && pending.length > 0) {
+            const current = pending[pending.length - 1];
+            if (current.index === current.entries.length) {
+                pending.pop();
+                continue;
+            }
+            yield* visit(budget);
+            const relative = current.entries[current.index++].replaceAll("\\", "/");
+            paths.push(current.path === "" ? relative : `${current.path}/${relative}`);
+        }
+        const infos = yield* metadata(fs, paths.map(resolve), "stat", fs.stat);
+        const children = [];
+        for (const [index, path] of paths.entries()) {
+            const info = infos[index];
+            if (info.type === "File") {
+                files.push(path);
+                continue;
+            }
+            if (info.type !== "Directory")
+                continue;
+            const name = path.slice(path.lastIndexOf("/") + 1);
+            if (pruneIgnoredDirectories && ignoredDirectoryNames.has(name) && !explicit.has(name))
+                continue;
+            directories.push(path);
+            children.push(path);
+        }
+        const listings = yield* metadata(fs, children.map(resolve), "readDirectory", fs.readDirectory);
+        for (const [index, path] of children.entries()) {
+            pending.push({ path, entries: [...listings[index]].sort(), index: 0 });
+        }
+    }
+    return { files: files.sort(), directories: directories.sort() };
+});
+/**
+ * Every file under `dir` (workspace-relative; `""` for the workspace root),
+ * as sorted workspace-relative paths. A missing directory enumerates to
+ * nothing — a zero-match expansion is legal, so absence is a fact rather than
+ * a failure. This declared-tree walk does not prune `.git`, `.jj`, or
+ * `node_modules`. Those names are part of the tree identity and must be
+ * captured and restored exactly.
+ *
+ * @since 0.1.0
+ * @category accessors
+ */
+export const filesUnder = (fs, dir, options = {}) => Effect.gen(function* () {
+    const resolve = options.resolve ?? defaultResolve;
+    return (yield* enumerateUnder(fs, dir, resolve, budgetFor(dir === "" ? "**" : `${dir}/**`, options), false)).files;
+});
+/**
+ * Every file and every directory under `dir` (workspace-relative, non-empty),
+ * as sorted workspace-relative paths. The directory list includes `dir`
+ * itself, so a tree replay can audit exactly the scaffolding it may have to
+ * prune. A missing directory enumerates to nothing — a tree that matched
+ * nothing is legal, so absence is a fact rather than a failure. This
+ * declared-tree walk does not prune `.git`, `.jj`, or `node_modules` because
+ * replay needs every directory and file that contributes to the tree.
+ *
+ * @since 0.1.0
+ * @category accessors
+ */
+export const entriesUnder = (fs, dir, options = {}) => Effect.gen(function* () {
+    const resolve = options.resolve ?? defaultResolve;
+    return yield* enumerateUnder(fs, dir, resolve, budgetFor(`${dir}/**`, options), false);
+});
+/**
+ * The longest directory prefix of a pattern that contains no wildcard — the
+ * subtree a walk has to visit. `src/**` walks `src`; `*.txt` walks the root.
+ *
+ * @since 0.1.0
+ * @category accessors
+ */
+export const staticPrefix = (pattern) => {
+    const segments = pattern.replaceAll("\\", "/").split("/");
+    const fixed = [];
+    for (const segment of segments.slice(0, -1)) {
+        if (segment.includes("*"))
+            break;
+        fixed.push(segment);
+    }
+    return fixed.join("/");
+};
+/**
+ * Expands one glob against the workspace: walk each include's static prefix,
+ * keep the files `FileSet.matchesGlob` covers. Sorted and deduplicated, so
+ * expansion is deterministic. A glob walk prunes `.git`, `.jj`, and
+ * `node_modules` unless an include sharing that walk prefix names the
+ * directory as a path segment. This keeps a root glob from traversing
+ * repository metadata and dependency trees while preserving an explicitly
+ * declared match after either a fixed or wildcard segment.
+ *
+ * @since 0.1.0
+ * @category accessors
+ */
+export const expandGlob = (fs, glob, options = {}) => Effect.gen(function* () {
+    const resolve = options.resolve ?? defaultResolve;
+    const matched = new Set();
+    const budget = budgetFor("", options);
+    const groups = new Map();
+    for (const include of glob.include) {
+        const prefix = staticPrefix(include);
+        const group = groups.get(prefix);
+        if (group === undefined)
+            groups.set(prefix, [include]);
+        else
+            group.push(include);
+    }
+    for (const [prefix, includes] of groups) {
+        budget.pattern = includes[0];
+        const explicit = explicitIgnoredDirectories(includes);
+        for (const path of (yield* enumerateUnder(fs, prefix, resolve, budget, true, explicit)).files) {
+            if (FileSet.matchesGlob(glob, path))
+                matched.add(path);
+        }
+    }
+    return [...matched].sort();
+});
+//# sourceMappingURL=FileEnumeration.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"FileEnumeration.js","sourceRoot":"","sources":["../../../src/internal/FileEnumeration.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Workspace-relative file enumeration for glob and tree-artifact expansion.\n *\n * The host `glob` is deliberately not consulted. Two divergences make it the\n * wrong oracle for a declared pattern: the kernel `FileSystem` absolutizes\n * patterns against the workspace root and returns absolute paths, so a\n * workspace-relative matcher filters every result out; and Node's matcher\n * skips dotfiles, which `FileSet.matchesPattern` — and Bazel's glob — cover.\n * Walking `readDirectory` and filtering through `FileSet` keeps every\n * expansion byte-identical to the matcher the plan's overlap passes use, in\n * the one coordinate system declarations are written in.\n *\n * @since 0.1.0\n */\n\nimport * as KernelFileSystem from \"@smthrs/kernel/FileSystem\"\nimport * as FileSet from \"@smthrs/plan/FileSet\"\nimport * as Effect from \"effect/Effect\"\nimport type * as FileSystem from \"effect/FileSystem\"\nimport type * as PlatformError from \"effect/PlatformError\"\nimport * as Schema from \"effect/Schema\"\n\n/** Bounded metadata reads, preserving the input order and typed failures. */\nconst metadata = <A>(\n  fs: FileSystem.FileSystem,\n  paths: ReadonlyArray<string>,\n  operation: \"stat\" | \"readDirectory\",\n  fallback: (path: string) => Effect.Effect<A, PlatformError.PlatformError>\n): Effect.Effect<ReadonlyArray<A>, PlatformError.PlatformError> =>\n  Effect.gen(function*() {\n    const batch = KernelFileSystem.batch(fs)\n    if (batch === undefined) {\n      return yield* Effect.forEach(paths, (path) => fallback(path), {\n        concurrency: KernelFileSystem.fallbackConcurrency\n      })\n    }\n    const values: Array<A> = []\n    for (let offset = 0; offset < paths.length; offset += batch.maxSize) {\n      const response = yield* batch.execute(\n        paths.slice(offset, offset + batch.maxSize).map((path) => ({ operation, path }))\n      )\n      for (const entry of [...response.entries].sort((a, b) => a.index - b.index)) {\n        const value = yield* Effect.fromResult(entry.result)\n        values.push(\n          (value.operation === \"stat\"\n            ? value.info\n            : (value as Extract<KernelFileSystem.BatchValue, { readonly paths: unknown }>).paths) as A\n        )\n      }\n    }\n    return values\n  })\n\n/**\n * The default maximum number of directory entries visited by one expansion.\n *\n * @since 1.0.0\n * @category constants\n */\nexport const defaultMaxEntries = 100_000\n\n/**\n * The stable error code returned when enumeration exceeds its safety bound.\n *\n * @since 1.0.0\n * @category errors\n */\nexport const FileEnumerationErrorCode = Schema.Literal(\"entry_limit_exceeded\")\n\n/**\n * The stable error code returned when enumeration exceeds its safety bound.\n *\n * @since 1.0.0\n * @category errors\n */\nexport type FileEnumerationErrorCode = typeof FileEnumerationErrorCode.Type\n\n/**\n * A workspace enumeration exceeded its configured entry limit.\n *\n * @since 1.0.0\n * @category errors\n */\nexport class FileEnumerationError extends Schema.TaggedError<FileEnumerationError>()(\n  \"@smthrs/engine-store/FileEnumerationError\",\n  {\n    code: FileEnumerationErrorCode,\n    message: Schema.String,\n    pattern: Schema.String,\n    limit: Schema.Number,\n    cause: Schema.Unknown\n  }\n) {}\n\n/**\n * How an enumeration talks to a FileSystem that does not speak\n * workspace-relative paths.\n *\n * @since 0.1.0\n * @category models\n */\nexport interface EnumerationOptions {\n  /**\n   * Maps a workspace-relative path (`\"\"` names the workspace root) to the\n   * coordinate the FileSystem expects. Defaults to the identity, with `\"\"`\n   * spelled `\".\"`.\n   */\n  readonly resolve?: (path: string) => string\n  /**\n   * Maximum number of directory entries one expansion may visit. Defaults to\n   * {@link defaultMaxEntries}. Enumeration fails instead of returning a\n   * partial result when the walk exceeds this bound.\n   */\n  readonly maxEntries?: number | undefined\n}\n\n/** @internal */\nconst defaultResolve = (path: string): string => path === \"\" ? \".\" : path\n\nconst ignoredDirectoryNames = new Set([\".git\", \".jj\", \"node_modules\"])\n\ninterface EnumerationBudget {\n  readonly limit: number\n  count: number\n  pattern: string\n}\n\nconst budgetFor = (pattern: string, options: EnumerationOptions): EnumerationBudget => ({\n  limit: options.maxEntries ?? defaultMaxEntries,\n  count: 0,\n  pattern\n})\n\nconst explicitIgnoredDirectories = (patterns: Iterable<string>): ReadonlySet<string> => {\n  const explicit = new Set<string>()\n  for (const pattern of patterns) {\n    for (const part of pattern.replaceAll(\"\\\\\", \"/\").split(\"/\")) {\n      if (ignoredDirectoryNames.has(part)) explicit.add(part)\n    }\n  }\n  return explicit\n}\n\nconst visit = (budget: EnumerationBudget): Effect.Effect<void, FileEnumerationError> => {\n  budget.count += 1\n  if (budget.count <= budget.limit) return Effect.void\n  const message = `enumerating pattern ${JSON.stringify(budget.pattern)} exceeded the ${budget.limit}-entry limit`\n  return Effect.fail(\n    new FileEnumerationError({\n      code: \"entry_limit_exceeded\",\n      pattern: budget.pattern,\n      limit: budget.limit,\n      message,\n      cause: new RangeError(message)\n    })\n  )\n}\n\ninterface EnumeratedEntries {\n  readonly files: ReadonlyArray<string>\n  readonly directories: ReadonlyArray<string>\n}\n\nconst enumerateUnder = (\n  fs: FileSystem.FileSystem,\n  dir: string,\n  resolve: (path: string) => string,\n  budget: EnumerationBudget,\n  pruneIgnoredDirectories: boolean,\n  explicit: ReadonlySet<string> = new Set()\n): Effect.Effect<EnumeratedEntries, PlatformError.PlatformError | FileEnumerationError> =>\n  Effect.gen(function*() {\n    // A directory that is not there enumerates to nothing, and its own\n    // listing reports that with `NotFound` — so no `exists` probe precedes\n    // it. The probe asked the question the very next call answers anyway, and\n    // on a confined host every host call is one CPython fork\n    // (`@smthrs/platform-node/AtomicFileSystem`), so it doubled the cost of\n    // reaching the walk root. Only the root is probed this way; a subtree\n    // discovered by `stat` inside the walk is read without a net, exactly as\n    // before, so a listing that refuses there still fails the expansion.\n    const root = yield* metadata(fs, [resolve(dir)], \"readDirectory\", fs.readDirectory).pipe(\n      Effect.map((values) => values[0]!),\n      Effect.catchReason(\"PlatformError\", \"NotFound\", () => Effect.succeed(undefined))\n    )\n    // The absent root is the one case that reports no directories at all: a\n    // tree replay must not be told to prune scaffolding that never existed.\n    if (root === undefined) return { files: [], directories: [] }\n\n    const files: Array<string> = []\n    const directories: Array<string> = [dir]\n    const pending = [{ path: dir, entries: [...root].sort(), index: 0 }]\n    const size = KernelFileSystem.batch(fs)?.maxSize ?? KernelFileSystem.fallbackConcurrency\n    while (pending.length > 0) {\n      const paths: Array<string> = []\n      // Fill one batch from all queued listings. A tree with one file in each\n      // of many sibling directories must not start one helper per leaf.\n      while (paths.length < size && pending.length > 0) {\n        const current = pending[pending.length - 1]!\n        if (current.index === current.entries.length) {\n          pending.pop()\n          continue\n        }\n        yield* visit(budget)\n        const relative = current.entries[current.index++]!.replaceAll(\"\\\\\", \"/\")\n        paths.push(current.path === \"\" ? relative : `${current.path}/${relative}`)\n      }\n      const infos = yield* metadata(fs, paths.map(resolve), \"stat\", fs.stat)\n      const children: Array<string> = []\n      for (const [index, path] of paths.entries()) {\n        const info = infos[index]!\n        if (info.type === \"File\") {\n          files.push(path)\n          continue\n        }\n        if (info.type !== \"Directory\") continue\n        const name = path.slice(path.lastIndexOf(\"/\") + 1)\n        if (pruneIgnoredDirectories && ignoredDirectoryNames.has(name) && !explicit.has(name)) continue\n        directories.push(path)\n        children.push(path)\n      }\n      const listings = yield* metadata(fs, children.map(resolve), \"readDirectory\", fs.readDirectory)\n      for (const [index, path] of children.entries()) {\n        pending.push({ path, entries: [...listings[index]!].sort(), index: 0 })\n      }\n    }\n    return { files: files.sort(), directories: directories.sort() }\n  })\n\n/**\n * Every file under `dir` (workspace-relative; `\"\"` for the workspace root),\n * as sorted workspace-relative paths. A missing directory enumerates to\n * nothing — a zero-match expansion is legal, so absence is a fact rather than\n * a failure. This declared-tree walk does not prune `.git`, `.jj`, or\n * `node_modules`. Those names are part of the tree identity and must be\n * captured and restored exactly.\n *\n * @since 0.1.0\n * @category accessors\n */\nexport const filesUnder = (\n  fs: FileSystem.FileSystem,\n  dir: string,\n  options: EnumerationOptions = {}\n): Effect.Effect<ReadonlyArray<string>, PlatformError.PlatformError | FileEnumerationError> =>\n  Effect.gen(function*() {\n    const resolve = options.resolve ?? defaultResolve\n    return (yield* enumerateUnder(\n      fs,\n      dir,\n      resolve,\n      budgetFor(dir === \"\" ? \"**\" : `${dir}/**`, options),\n      false\n    )).files\n  })\n\n/**\n * Every file and every directory under `dir` (workspace-relative, non-empty),\n * as sorted workspace-relative paths. The directory list includes `dir`\n * itself, so a tree replay can audit exactly the scaffolding it may have to\n * prune. A missing directory enumerates to nothing — a tree that matched\n * nothing is legal, so absence is a fact rather than a failure. This\n * declared-tree walk does not prune `.git`, `.jj`, or `node_modules` because\n * replay needs every directory and file that contributes to the tree.\n *\n * @since 0.1.0\n * @category accessors\n */\nexport const entriesUnder = (\n  fs: FileSystem.FileSystem,\n  dir: string,\n  options: EnumerationOptions = {}\n): Effect.Effect<\n  { readonly files: ReadonlyArray<string>; readonly directories: ReadonlyArray<string> },\n  PlatformError.PlatformError | FileEnumerationError\n> =>\n  Effect.gen(function*() {\n    const resolve = options.resolve ?? defaultResolve\n    return yield* enumerateUnder(fs, dir, resolve, budgetFor(`${dir}/**`, options), false)\n  })\n\n/**\n * The longest directory prefix of a pattern that contains no wildcard — the\n * subtree a walk has to visit. `src/**` walks `src`; `*.txt` walks the root.\n *\n * @since 0.1.0\n * @category accessors\n */\nexport const staticPrefix = (pattern: string): string => {\n  const segments = pattern.replaceAll(\"\\\\\", \"/\").split(\"/\")\n  const fixed: Array<string> = []\n  for (const segment of segments.slice(0, -1)) {\n    if (segment.includes(\"*\")) break\n    fixed.push(segment)\n  }\n  return fixed.join(\"/\")\n}\n\n/**\n * Expands one glob against the workspace: walk each include's static prefix,\n * keep the files `FileSet.matchesGlob` covers. Sorted and deduplicated, so\n * expansion is deterministic. A glob walk prunes `.git`, `.jj`, and\n * `node_modules` unless an include sharing that walk prefix names the\n * directory as a path segment. This keeps a root glob from traversing\n * repository metadata and dependency trees while preserving an explicitly\n * declared match after either a fixed or wildcard segment.\n *\n * @since 0.1.0\n * @category accessors\n */\nexport const expandGlob = (\n  fs: FileSystem.FileSystem,\n  glob: FileSet.Glob,\n  options: EnumerationOptions = {}\n): Effect.Effect<ReadonlyArray<string>, PlatformError.PlatformError | FileEnumerationError> =>\n  Effect.gen(function*() {\n    const resolve = options.resolve ?? defaultResolve\n    const matched = new Set<string>()\n    const budget = budgetFor(\"\", options)\n    const groups = new Map<string, Array<string>>()\n    for (const include of glob.include) {\n      const prefix = staticPrefix(include)\n      const group = groups.get(prefix)\n      if (group === undefined) groups.set(prefix, [include])\n      else group.push(include)\n    }\n    for (const [prefix, includes] of groups) {\n      budget.pattern = includes[0]!\n      const explicit = explicitIgnoredDirectories(includes)\n      for (const path of (yield* enumerateUnder(fs, prefix, resolve, budget, true, explicit)).files) {\n        if (FileSet.matchesGlob(glob, path)) matched.add(path)\n      }\n    }\n    return [...matched].sort()\n  })\n"]}

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

@@ -0,0 +1,80 @@
+/**
+ * Value predicates a host can answer without running the value's own code.
+ *
+ * Projecting a settlement the flow's codec rejected must not execute user
+ * code. A `Proxy` runs its handler on every reflective read, and the point of
+ * `./ExitEncoding.ts` is to describe the value a round is already failing on,
+ * not to hand that value another turn on the terminal-transition path. Node
+ * answers the question from an internal slot, through `node:util/types`. No
+ * ECMAScript operation does: virtualization is transparent by design, so a
+ * proxy and its target are indistinguishable to portable code.
+ *
+ * Binding `node:util/types` with a static import states that answer as a
+ * build-time dependency, and that is wrong twice. `@smthrs/engine-store` is a
+ * browser entry point in the release policy and in
+ * `scripts/browser-contract.mjs`, so the import fails `pnpm run browser`; and
+ * it claims a capability every host has, which is false. This module reads the
+ * predicates off the host instead, the way `../OwnerIdentity.ts` reads a
+ * process id: `process.getBuiltinModule` when the host offers it, portable
+ * fallbacks when it does not. Node and Bun both take the first path, so on the
+ * runtimes the durable engine supports the behavior is exactly what the static
+ * import gave. A browser takes the second, where proxy detection does not
+ * exist and this module says so rather than pretending.
+ *
+ * The lookup grants no authority, which is why it is resolved here rather than
+ * routed through a `HostServices` port. The whole surface of
+ * `node:util/types` is predicates over values already in hand: no filesystem,
+ * no process, no clock, no randomness. A port exists to keep nondeterminism
+ * and I/O out of a composition, and a pure type test is neither.
+ *
+ * @since 1.0.0
+ */
+/**
+ * The part of a host this module reads.
+ *
+ * `process.getBuiltinModule` is the synchronous built-in accessor Node has
+ * exposed since 22.3 and Bun since 1.2. It is typed structurally rather than
+ * imported from `@types/node` so the module carries no Node binding at all.
+ *
+ * @since 1.0.0
+ * @category models
+ */
+export interface BuiltinSource {
+    readonly getBuiltinModule?: ((id: string) => unknown) | undefined;
+}
+/**
+ * The predicates a projection needs.
+ *
+ * @since 1.0.0
+ * @category models
+ */
+export interface Reflection {
+    /** Whether reading this object would run a proxy handler. */
+    readonly isProxy: (value: object) => boolean;
+    /** Whether this value carries the error internal slot, in any realm. */
+    readonly isNativeError: (value: unknown) => boolean;
+}
+/**
+ * Builds the reflection one host can supply.
+ *
+ * Each predicate is taken only when the host names it as a function, so a host
+ * that grows a partial `node:util/types` shim keeps the portable answer for
+ * whatever it left out. Both are read as plain functions of their argument,
+ * which is what Node and Bun export.
+ *
+ * @since 1.0.0
+ * @category constructors
+ */
+export declare const make: (source: BuiltinSource | undefined) => Reflection;
+/**
+ * The reflection this process runs with.
+ *
+ * Read off `globalThis` rather than through a bare `process` reference, so a
+ * browser bundle sees `undefined` here and falls through to the portable
+ * predicates.
+ *
+ * @since 1.0.0
+ * @category constants
+ */
+export declare const host: Reflection;
+//# sourceMappingURL=HostReflection.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"HostReflection.d.ts","sourceRoot":"","sources":["../../../src/internal/HostReflection.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH;;;;;;;;;GASG;AACH,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,gBAAgB,CAAC,EAAE,CAAC,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,GAAG,SAAS,CAAA;CAClE;AAED;;;;;GAKG;AACH,MAAM,WAAW,UAAU;IACzB,6DAA6D;IAC7D,QAAQ,CAAC,OAAO,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,OAAO,CAAA;IAC5C,wEAAwE;IACxE,QAAQ,CAAC,aAAa,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,OAAO,CAAA;CACpD;AAyCD;;;;;;;;;;GAUG;AACH,eAAO,MAAM,IAAI,GAAI,QAAQ,aAAa,GAAG,SAAS,KAAG,UAMxD,CAAA;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,IAAI,EAAE,UAA+E,CAAA"}

package/dist/esm/internal/HostReflection.js

@@ -0,0 +1,98 @@
+/**
+ * Value predicates a host can answer without running the value's own code.
+ *
+ * Projecting a settlement the flow's codec rejected must not execute user
+ * code. A `Proxy` runs its handler on every reflective read, and the point of
+ * `./ExitEncoding.ts` is to describe the value a round is already failing on,
+ * not to hand that value another turn on the terminal-transition path. Node
+ * answers the question from an internal slot, through `node:util/types`. No
+ * ECMAScript operation does: virtualization is transparent by design, so a
+ * proxy and its target are indistinguishable to portable code.
+ *
+ * Binding `node:util/types` with a static import states that answer as a
+ * build-time dependency, and that is wrong twice. `@smthrs/engine-store` is a
+ * browser entry point in the release policy and in
+ * `scripts/browser-contract.mjs`, so the import fails `pnpm run browser`; and
+ * it claims a capability every host has, which is false. This module reads the
+ * predicates off the host instead, the way `../OwnerIdentity.ts` reads a
+ * process id: `process.getBuiltinModule` when the host offers it, portable
+ * fallbacks when it does not. Node and Bun both take the first path, so on the
+ * runtimes the durable engine supports the behavior is exactly what the static
+ * import gave. A browser takes the second, where proxy detection does not
+ * exist and this module says so rather than pretending.
+ *
+ * The lookup grants no authority, which is why it is resolved here rather than
+ * routed through a `HostServices` port. The whole surface of
+ * `node:util/types` is predicates over values already in hand: no filesystem,
+ * no process, no clock, no randomness. A port exists to keep nondeterminism
+ * and I/O out of a composition, and a pure type test is neither.
+ *
+ * @since 1.0.0
+ */
+/**
+ * The stance of a host that cannot detect a proxy.
+ *
+ * Answering no leaves the projection on its ordinary defenses: own-data reads
+ * only, a `seen` set, a depth bound, and a `try` that turns any refusal into
+ * `[unrepresentable]`. A trap can still run there, which is the state every
+ * host was in before proxy detection existed. The alternative, answering yes
+ * for every object, would erase every diagnostic projection in a browser to
+ * buy protection against a case no browser has produced.
+ */
+const undetectableProxy = () => false;
+/**
+ * The portable native-error test.
+ *
+ * `Object.prototype.toString` reports `[object Error]` for a value carrying
+ * the error internal slot, including one built in another realm, which is the
+ * property this predicate is used for. It reads `Symbol.toStringTag`, so a
+ * value that defines that symbol as a getter can run code; every caller runs
+ * it inside the `try` that answers `[unrepresentable]`.
+ */
+const taggedNativeError = (value) => Object.prototype.toString.call(value) === "[object Error]";
+/**
+ * The predicate module a host offers, when it offers one.
+ *
+ * A host that implements the accessor but rejects the id must degrade rather
+ * than raise: this module is imported by the path that exists so a terminal
+ * write can never fail.
+ */
+const builtinTypes = (source) => {
+    try {
+        const types = source?.getBuiltinModule?.("node:util/types");
+        return typeof types === "object" && types !== null ? types : undefined;
+    }
+    catch {
+        return undefined;
+    }
+};
+/**
+ * Builds the reflection one host can supply.
+ *
+ * Each predicate is taken only when the host names it as a function, so a host
+ * that grows a partial `node:util/types` shim keeps the portable answer for
+ * whatever it left out. Both are read as plain functions of their argument,
+ * which is what Node and Bun export.
+ *
+ * @since 1.0.0
+ * @category constructors
+ */
+export const make = (source) => {
+    const types = builtinTypes(source);
+    return {
+        isProxy: typeof types?.isProxy === "function" ? types.isProxy : undetectableProxy,
+        isNativeError: typeof types?.isNativeError === "function" ? types.isNativeError : taggedNativeError
+    };
+};
+/**
+ * The reflection this process runs with.
+ *
+ * Read off `globalThis` rather than through a bare `process` reference, so a
+ * browser bundle sees `undefined` here and falls through to the portable
+ * predicates.
+ *
+ * @since 1.0.0
+ * @category constants
+ */
+export const host = make(globalThis.process);
+//# sourceMappingURL=HostReflection.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"HostReflection.js","sourceRoot":"","sources":["../../../src/internal/HostReflection.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AA6BH;;;;;;;;;GASG;AACH,MAAM,iBAAiB,GAAG,GAAY,EAAE,CAAC,KAAK,CAAA;AAE9C;;;;;;;;GAQG;AACH,MAAM,iBAAiB,GAAG,CAAC,KAAc,EAAW,EAAE,CAAC,MAAM,CAAC,SAAS,CAAC,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,gBAAgB,CAAA;AAEjH;;;;;;GAMG;AACH,MAAM,YAAY,GAAG,CAAC,MAAiC,EAAmC,EAAE;IAC1F,IAAI,CAAC;QACH,MAAM,KAAK,GAAG,MAAM,EAAE,gBAAgB,EAAE,CAAC,iBAAiB,CAAC,CAAA;QAC3D,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAA;IACxE,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,SAAS,CAAA;IAClB,CAAC;AACH,CAAC,CAAA;AAED;;;;;;;;;;GAUG;AACH,MAAM,CAAC,MAAM,IAAI,GAAG,CAAC,MAAiC,EAAc,EAAE;IACpE,MAAM,KAAK,GAAG,YAAY,CAAC,MAAM,CAAC,CAAA;IAClC,OAAO;QACL,OAAO,EAAE,OAAO,KAAK,EAAE,OAAO,KAAK,UAAU,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,iBAAiB;QACjF,aAAa,EAAE,OAAO,KAAK,EAAE,aAAa,KAAK,UAAU,CAAC,CAAC,CAAC,KAAK,CAAC,aAAa,CAAC,CAAC,CAAC,iBAAiB;KACpG,CAAA;AACH,CAAC,CAAA;AAED;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,IAAI,GAAe,IAAI,CAAE,UAAmD,CAAC,OAAO,CAAC,CAAA","sourcesContent":["/**\n * Value predicates a host can answer without running the value's own code.\n *\n * Projecting a settlement the flow's codec rejected must not execute user\n * code. A `Proxy` runs its handler on every reflective read, and the point of\n * `./ExitEncoding.ts` is to describe the value a round is already failing on,\n * not to hand that value another turn on the terminal-transition path. Node\n * answers the question from an internal slot, through `node:util/types`. No\n * ECMAScript operation does: virtualization is transparent by design, so a\n * proxy and its target are indistinguishable to portable code.\n *\n * Binding `node:util/types` with a static import states that answer as a\n * build-time dependency, and that is wrong twice. `@smthrs/engine-store` is a\n * browser entry point in the release policy and in\n * `scripts/browser-contract.mjs`, so the import fails `pnpm run browser`; and\n * it claims a capability every host has, which is false. This module reads the\n * predicates off the host instead, the way `../OwnerIdentity.ts` reads a\n * process id: `process.getBuiltinModule` when the host offers it, portable\n * fallbacks when it does not. Node and Bun both take the first path, so on the\n * runtimes the durable engine supports the behavior is exactly what the static\n * import gave. A browser takes the second, where proxy detection does not\n * exist and this module says so rather than pretending.\n *\n * The lookup grants no authority, which is why it is resolved here rather than\n * routed through a `HostServices` port. The whole surface of\n * `node:util/types` is predicates over values already in hand: no filesystem,\n * no process, no clock, no randomness. A port exists to keep nondeterminism\n * and I/O out of a composition, and a pure type test is neither.\n *\n * @since 1.0.0\n */\n\n/**\n * The part of a host this module reads.\n *\n * `process.getBuiltinModule` is the synchronous built-in accessor Node has\n * exposed since 22.3 and Bun since 1.2. It is typed structurally rather than\n * imported from `@types/node` so the module carries no Node binding at all.\n *\n * @since 1.0.0\n * @category models\n */\nexport interface BuiltinSource {\n  readonly getBuiltinModule?: ((id: string) => unknown) | undefined\n}\n\n/**\n * The predicates a projection needs.\n *\n * @since 1.0.0\n * @category models\n */\nexport interface Reflection {\n  /** Whether reading this object would run a proxy handler. */\n  readonly isProxy: (value: object) => boolean\n  /** Whether this value carries the error internal slot, in any realm. */\n  readonly isNativeError: (value: unknown) => boolean\n}\n\n/**\n * The stance of a host that cannot detect a proxy.\n *\n * Answering no leaves the projection on its ordinary defenses: own-data reads\n * only, a `seen` set, a depth bound, and a `try` that turns any refusal into\n * `[unrepresentable]`. A trap can still run there, which is the state every\n * host was in before proxy detection existed. The alternative, answering yes\n * for every object, would erase every diagnostic projection in a browser to\n * buy protection against a case no browser has produced.\n */\nconst undetectableProxy = (): boolean => false\n\n/**\n * The portable native-error test.\n *\n * `Object.prototype.toString` reports `[object Error]` for a value carrying\n * the error internal slot, including one built in another realm, which is the\n * property this predicate is used for. It reads `Symbol.toStringTag`, so a\n * value that defines that symbol as a getter can run code; every caller runs\n * it inside the `try` that answers `[unrepresentable]`.\n */\nconst taggedNativeError = (value: unknown): boolean => Object.prototype.toString.call(value) === \"[object Error]\"\n\n/**\n * The predicate module a host offers, when it offers one.\n *\n * A host that implements the accessor but rejects the id must degrade rather\n * than raise: this module is imported by the path that exists so a terminal\n * write can never fail.\n */\nconst builtinTypes = (source: BuiltinSource | undefined): Partial<Reflection> | undefined => {\n  try {\n    const types = source?.getBuiltinModule?.(\"node:util/types\")\n    return typeof types === \"object\" && types !== null ? types : undefined\n  } catch {\n    return undefined\n  }\n}\n\n/**\n * Builds the reflection one host can supply.\n *\n * Each predicate is taken only when the host names it as a function, so a host\n * that grows a partial `node:util/types` shim keeps the portable answer for\n * whatever it left out. Both are read as plain functions of their argument,\n * which is what Node and Bun export.\n *\n * @since 1.0.0\n * @category constructors\n */\nexport const make = (source: BuiltinSource | undefined): Reflection => {\n  const types = builtinTypes(source)\n  return {\n    isProxy: typeof types?.isProxy === \"function\" ? types.isProxy : undetectableProxy,\n    isNativeError: typeof types?.isNativeError === \"function\" ? types.isNativeError : taggedNativeError\n  }\n}\n\n/**\n * The reflection this process runs with.\n *\n * Read off `globalThis` rather than through a bare `process` reference, so a\n * browser bundle sees `undefined` here and falls through to the portable\n * predicates.\n *\n * @since 1.0.0\n * @category constants\n */\nexport const host: Reflection = make((globalThis as { readonly process?: BuiltinSource }).process)\n"]}