primitive-admin 1.0.62 → 1.0.64

package/dist/src/lib/function-bundle.js

@@ -0,0 +1,341 @@
+/**
+ * Building a server function's bundle, in the CLI (#3179, project
+ * `server-functions`).
+ *
+ * The intent decides that the build happens here and never on the server:
+ * `config push` runs esbuild over the authored `entry`, inlines the npm
+ * dependencies, and ships the built bundle next to the authored source bytes
+ * in one envelope. The server verifies the hash and stores the object; it does
+ * not compile anything.
+ *
+ * ── The two import rules ─────────────────────────────────────────────────
+ *
+ * They look contradictory and are not (F-005):
+ *
+ *   - A **filesystem import** — relative or absolute — must stay inside the
+ *     config tree. `entry`, every import it reaches, and every symlink they
+ *     traverse are realpath-resolved and checked against the tree root, so a
+ *     push can never read a file off a developer's disk that the tree does not
+ *     contain.
+ *   - A **bare package specifier** is exempt. It resolves through Node into an
+ *     ancestor `node_modules`, which is outside every config tree by
+ *     construction; esbuild inlines it into the bundle, and it is never
+ *     captured as an authored source (so `config pull` never writes
+ *     `node_modules` content back).
+ *
+ * The exemption follows the specifier, not the path a file happens to sit at.
+ * A resolver plugin records the files a BARE specifier reached (and the files
+ * those reach in turn), so `import "../../node_modules/private/index.js"` — a
+ * relative filesystem import that merely lands in a `node_modules` directory —
+ * is still an escape and still refused. Deciding by path would have let that
+ * one specifier read any file on the disk and upload it.
+ *
+ * `primitive-functions` is the one bare specifier left EXTERNAL: the loader
+ * (#3180) supplies it at invoke time, so baking a copy into every bundle would
+ * pin the SDK version to whenever the function was last pushed.
+ *
+ * ── The retired specifier ────────────────────────────────────────────────
+ *
+ * That module was called `primitive-sdk` until #3209. This file is the one
+ * place in the repo that still writes the old name on purpose: without a
+ * detector, an author who copied an older example gets esbuild's generic
+ * `Could not resolve "primitive-sdk"`, which reads as a missing dependency
+ * rather than a rename. `RETIRED_SDK_MODULE` below is that detector, and
+ * `cli/tests/unit/retired-sdk-name-guard-3209.test.ts` allowlists exactly this
+ * site while proving the name appears nowhere else.
+ *
+ * The refusal is made TWICE, because one mechanism cannot see both halves:
+ *
+ *   - the resolver plugin catches a runtime import, which is the one that
+ *     would otherwise reach the loader and fail there;
+ *   - a scan of the authored source catches the TYPE-ONLY spellings —
+ *     `import type … from`, `export type … from`, and a plain named import
+ *     used only in type position. TypeScript erases all three, and esbuild
+ *     erases them before any resolver callback runs, so the plugin never sees
+ *     a specifier to compare. Those imports build and push silently, leaving
+ *     the stored source teaching an import that no longer exists.
+ *
+ * The scan is anchored at the start of a line so that prose about the retired
+ * name — a `//` comment, a `*` doc-comment line, a string holding an example —
+ * does not refuse a push. Missing an import someone hid mid-line is the safe
+ * direction to be wrong in; refusing a valid push is not.
+ *
+ * ── The canonical envelope encoding ──────────────────────────────────────
+ *
+ * `canonicalFunctionEnvelopeBytes` reproduces `canonicalEnvelopeBytes` in
+ * `src/services/function-bundle-storage.ts` byte for byte. The server hashes
+ * the envelope to decide whether a push is a no-op; the CLI hashes it to decide
+ * whether to make the call at all, and the two answers have to agree or a push
+ * the CLI called unchanged lands as a new version (or worse, the reverse).
+ * `cli/tests/unit/function-bundle-3179.test.ts` pins them against each other.
+ */
+import * as esbuild from "esbuild";
+import { createHash } from "crypto";
+import { existsSync, readFileSync, realpathSync } from "fs";
+import { isAbsolute, relative, resolve, sep } from "path";
+/** The module the loader supplies; never bundled. */
+export const PRIMITIVE_FUNCTIONS_MODULE = "primitive-functions";
+/** What that module was called before #3209. Refused at push, by name. */
+export const RETIRED_SDK_MODULE = "primitive-sdk";
+/** The refusal both detectors report, so an author reads one sentence. */
+const retiredModuleRefusal = () => `the '${RETIRED_SDK_MODULE}' module was renamed: import from ` +
+    `'${PRIMITIVE_FUNCTIONS_MODULE}' instead`;
+/**
+ * Import and export forms naming the retired module, in the type-only
+ * spellings esbuild erases before the resolver plugin can see them (see the
+ * module note). Anchored at the start of a line, and the specifier must be the
+ * WHOLE quoted string, so `primitive-sdk-utils` and `./primitive-sdk.js` are
+ * untouched — the same exact match the plugin makes.
+ */
+const RETIRED_IMPORT_FORMS = [
+    // `import type { X } from "…"`, `export type { X } from "…"`, `export * from
+    // "…"`, and every value spelling in between, on one line.
+    new RegExp(`^[ \\t]*(?:import|export)[ \\t\\w*{},$]*[ \\t]from[ \\t]*(['"])${RETIRED_SDK_MODULE}\\1`, "m"),
+    // The tail of a multi-line named list: `} from "…"`.
+    new RegExp(`^[ \\t]*\\}[ \\t]*from[ \\t]*(['"])${RETIRED_SDK_MODULE}\\1`, "m"),
+    // A bare side-effect import. The plugin catches this one too; it costs
+    // nothing to be sure the scan agrees with it.
+    new RegExp(`^[ \\t]*import[ \\t]*(['"])${RETIRED_SDK_MODULE}\\1`, "m"),
+];
+/** Whether an authored source imports the retired module in any spelling. */
+export function importsRetiredModule(source) {
+    return RETIRED_IMPORT_FORMS.some((pattern) => pattern.test(source));
+}
+/** Matches the server's `FUNCTION_ENVELOPE_SCHEMA_VERSION`. */
+/**
+ * 2 since #3187: the envelope carries the collected query MANIFEST.
+ *
+ * Bumped rather than added quietly, because the encoding the hash is taken
+ * over changed: the manifest is part of config-version identity (D3187-SO-005)
+ * precisely so a manifest change makes a new version and a collector fix can
+ * reach a tree that was pushed before it.
+ */
+export const FUNCTION_ENVELOPE_SCHEMA_VERSION = 2;
+/** A push that cannot proceed: a missing entry, a build error, or an escape. */
+export class FunctionBuildError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "FunctionBuildError";
+    }
+}
+/**
+ * The canonical encoding both sides hash. Fixed key order, sources sorted by
+ * path — see the module note; this must stay identical to the server's.
+ */
+export function canonicalFunctionEnvelopeBytes(envelope) {
+    const canonical = {
+        schemaVersion: envelope.schemaVersion,
+        entry: envelope.entry,
+        toml: envelope.toml,
+        sources: [...envelope.sources]
+            .map((s) => ({ path: s.path, content: s.content }))
+            .sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0)),
+        bundle: envelope.bundle,
+        // #3187 — inside the hash, so a manifest change is a new version.
+        // `null` rather than absent when there is none, so the encoding of a
+        // manifest-less push is stable rather than depending on a missing key.
+        manifest: envelope.manifest ?? null,
+        // #3455 — the twin of the server's rule: the key is emitted ONLY when
+        // there is a schema, so a tree with no `models/models.toml` builds the
+        // same bytes it built before this change and its no-op detection is
+        // intact. `undefined` would be dropped by `JSON.stringify` anyway; the
+        // spread says the rule rather than relying on that.
+        ...(typeof envelope.documentSchema === "string" && envelope.documentSchema
+            ? { documentSchema: envelope.documentSchema }
+            : {}),
+    };
+    return new TextEncoder().encode(JSON.stringify(canonical));
+}
+export function functionEnvelopeHash(envelope) {
+    return createHash("sha256")
+        .update(Buffer.from(canonicalFunctionEnvelopeBytes(envelope)))
+        .digest("hex");
+}
+/** POSIX spelling, so a Windows push stores the same paths a macOS one does. */
+const toPosix = (value) => value.split(sep).join("/");
+/** Whether a tree-relative path names a `node_modules` file. */
+export function isDependencyPath(path) {
+    return path.split("/").includes("node_modules");
+}
+/**
+ * `null` when `candidate` is inside `root`, else the tree-relative-ish spelling
+ * to name in the refusal. Lexical only — the caller realpaths first.
+ */
+function outsideRoot(root, candidate) {
+    const rel = relative(root, candidate);
+    if (rel === "" || (!rel.startsWith("..") && !isAbsolute(rel)))
+        return null;
+    return toPosix(rel);
+}
+function escapeRefusal(what, path) {
+    return new FunctionBuildError(`${what} '${path}' resolves outside the config tree root. ` +
+        "Filesystem imports must stay inside the config tree; npm packages are " +
+        "imported by name and inlined into the bundle.");
+}
+/**
+ * Build one function's bundle and collect its authored sources.
+ *
+ * Throws `FunctionBuildError` — never a raw esbuild error — so `config push`
+ * has one thing to report and nothing is pushed for that function.
+ */
+export async function buildFunctionBundle(options) {
+    const { configDir, entry, functionKey } = options;
+    const treeRoot = realpathSync(resolve(configDir));
+    // 1. The entry, lexically. An escaping entry is refused as an escape even
+    //    when the file it names does not exist — "no such file" would be a
+    //    misleading answer to `entry = "../../etc/passwd"`.
+    const entryAbs = resolve(treeRoot, entry);
+    const entryEscape = outsideRoot(treeRoot, entryAbs);
+    if (entryEscape !== null)
+        throw escapeRefusal("entry", toPosix(entry));
+    if (!existsSync(entryAbs)) {
+        throw new FunctionBuildError(`function '${functionKey}': entry file '${toPosix(entry)}' does not exist`);
+    }
+    // 2. …and after symlinks.
+    const entryReal = realpathSync(entryAbs);
+    if (outsideRoot(treeRoot, entryReal) !== null) {
+        throw escapeRefusal("entry", toPosix(entry));
+    }
+    const entryRelative = toPosix(relative(treeRoot, entryReal));
+    // Which files a BARE specifier reached. Membership — not the presence of a
+    // `node_modules` segment in the path — is what exempts a file from the tree
+    // boundary, so a relative or absolute import can never buy the exemption by
+    // pointing at a `node_modules` directory (see the module note).
+    const dependencyFiles = new Set();
+    const rememberDependency = (path) => {
+        if (!path)
+            return;
+        dependencyFiles.add(path);
+        try {
+            dependencyFiles.add(realpathSync(path));
+        }
+        catch {
+            /* a virtual or already-resolved path; the raw spelling is enough */
+        }
+    };
+    const isDependencyFile = (path) => {
+        if (dependencyFiles.has(path))
+            return true;
+        try {
+            return dependencyFiles.has(realpathSync(path));
+        }
+        catch {
+            return false;
+        }
+    };
+    const importBoundaryPlugin = {
+        name: "primitive-function-import-boundary",
+        setup(build) {
+            build.onResolve({ filter: /.*/ }, async (args) => {
+                // The nested `build.resolve` below re-enters this callback; the marker
+                // is what stops it recursing forever.
+                if (args.pluginData?.primitiveBoundaryResolved)
+                    return null;
+                if (args.kind === "entry-point")
+                    return null;
+                // The retired specifier, refused before esbuild can report it as a
+                // missing package (#3209). An EXACT match only: `primitive-sdk-utils`
+                // is a different package and `./primitive-sdk.ts` is a tree-local file,
+                // and both still resolve normally.
+                if (args.path === RETIRED_SDK_MODULE) {
+                    return { errors: [{ text: retiredModuleRefusal() }] };
+                }
+                const bare = !args.path.startsWith(".") && !isAbsolute(args.path);
+                // A dependency's own relative imports are dependency files too — the
+                // exemption is inherited down the package's internal graph.
+                const fromDependency = !!args.importer && isDependencyFile(args.importer);
+                if (!bare && !fromDependency)
+                    return null;
+                const resolved = await build.resolve(args.path, {
+                    importer: args.importer,
+                    namespace: args.namespace,
+                    resolveDir: args.resolveDir,
+                    kind: args.kind,
+                    pluginData: { primitiveBoundaryResolved: true },
+                });
+                // Let esbuild resolve (and report) it the way it would have; nothing
+                // was recorded, so an unresolvable import stays esbuild's error.
+                if (resolved.errors.length > 0)
+                    return null;
+                if (!resolved.external && resolved.path) {
+                    rememberDependency(resolved.path);
+                }
+                return resolved;
+            });
+        },
+    };
+    let result;
+    try {
+        result = await esbuild.build({
+            entryPoints: [entryRelative],
+            absWorkingDir: treeRoot,
+            bundle: true,
+            write: false,
+            metafile: true,
+            format: "esm",
+            platform: "neutral",
+            target: "es2022",
+            // The loader supplies it; see the module note.
+            external: [PRIMITIVE_FUNCTIONS_MODULE],
+            plugins: [importBoundaryPlugin],
+            logLevel: "silent",
+        });
+    }
+    catch (error) {
+        const messages = Array.isArray(error?.errors)
+            ? error.errors.map((e) => {
+                const where = e?.location?.file
+                    ? toPosix(String(e.location.file))
+                    : toPosix(entry);
+                const line = e?.location?.line ? `:${e.location.line}` : "";
+                return `  ${where}${line}: ${e?.text ?? "build error"}`;
+            })
+            : [`  ${toPosix(entry)}: ${error?.message ?? String(error)}`];
+        throw new FunctionBuildError(`function '${functionKey}' failed to build:\n${messages.join("\n")}`);
+    }
+    const output = result.outputFiles?.[0];
+    if (!output) {
+        throw new FunctionBuildError(`function '${functionKey}': the build produced no output for '${toPosix(entry)}'`);
+    }
+    const bundle = Buffer.from(output.contents);
+    // 3. Every file the build actually read, from the metafile — the honest list,
+    //    rather than a re-parse of the imports. A file a BARE specifier reached is
+    //    an inlined dependency and is dropped; every other input is a filesystem
+    //    import, and one outside the tree is an escape esbuild followed that the
+    //    push refuses.
+    const sources = [];
+    for (const input of Object.keys(result.metafile?.inputs ?? {})) {
+        const path = toPosix(input);
+        const absolute = resolve(treeRoot, input);
+        if (isDependencyFile(absolute))
+            continue;
+        if (path.startsWith("..") || isAbsolute(input)) {
+            throw escapeRefusal("import", path);
+        }
+        if (outsideRoot(treeRoot, realpathSync(absolute)) !== null) {
+            throw escapeRefusal("import", path);
+        }
+        // In-tree `node_modules` reached by a filesystem import: inside the
+        // boundary, so it builds — but `config pull` refuses to write a stored
+        // `node_modules` path, so capturing it would promise a round trip that
+        // cannot be kept.
+        if (isDependencyPath(path))
+            continue;
+        const content = readFileSync(absolute);
+        // The type-only half of the retired-specifier refusal (see the module
+        // note): esbuild erased these imports before the plugin could see them,
+        // so the build succeeded and the source would have been stored as pushed.
+        if (importsRetiredModule(content.toString("utf-8"))) {
+            throw new FunctionBuildError(`function '${functionKey}' failed to build:\n  ${path}: ${retiredModuleRefusal()}`);
+        }
+        sources.push({ path, content });
+    }
+    sources.sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
+    return {
+        entry: entryRelative,
+        bundle,
+        contentHash: createHash("sha256").update(bundle).digest("hex"),
+        sources,
+    };
+}
+//# sourceMappingURL=function-bundle.js.map

package/dist/src/lib/function-bundle.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"function-bundle.js","sourceRoot":"","sources":["../../../src/lib/function-bundle.ts"],"names":[],"mappings":"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"}

package/dist/src/lib/function-collect.d.ts

@@ -0,0 +1,123 @@
+/**
+ * Collecting a function's query manifest at push time (#3187, project
+ * `server-functions` phase 5).
+ *
+ * ── Why the tree has to RUN ──────────────────────────────────────────────
+ *
+ * `defineQuery(name, { models, params, cache, run })` is a registration
+ * helper, and registrations are ordinary code: a name can be computed, a
+ * models list can come from a constant another file exports, a whole set can
+ * be registered in a loop. Static extraction would see none of that. So the
+ * manifest is collected by BUILDING the tree a second time with
+ * `primitive-functions` aliased to a recording stub and executing the result.
+ *
+ * ── Why it runs somewhere else ───────────────────────────────────────────
+ *
+ * D3187-SO-006. A function bundle inlines its tree-local and npm imports, so
+ * "execute the bundle" means "run arbitrary module scope" — with, if it ran
+ * inside the CLI, the developer's environment, credentials, filesystem and
+ * network. That is a large step up from what `config push` did before, which
+ * was to type-erase and bundle the same code without running it.
+ *
+ * So collection runs in a spawned child `node` with:
+ *
+ *   - a SCRUBBED environment: an explicit minimal pass-through, so a token in
+ *     the developer's shell is not readable by a project's module scope;
+ *   - the config tree as the working directory;
+ *   - a hard timeout, killed with `SIGKILL`, so a loop in a tree is a named
+ *     refusal rather than a hung push;
+ *   - its result read back over a structured pipe (a sentinel-framed line on
+ *     stdout), so a tree that prints is not mistaken for a tree that reported.
+ *
+ * What remains is the trust a developer already extends to their own tree by
+ * running its build: this is npm-postinstall-equivalent, and the docs say so.
+ * Full network denial was considered and not taken (Node offers no reliable
+ * in-process cutoff), and so was static extraction (it cannot see computed
+ * registrations).
+ *
+ * ── What the manifest is, and is not ─────────────────────────────────────
+ *
+ * Documentation. Since #3279 function code acts as the system, so the
+ * manifest authorizes nothing anywhere: its one job is telling an operator
+ * what a version registered and what it TOUCHES — the models its code names
+ * and the families it reaches — through `primitive functions get`. That
+ * second half (schema version 2) comes from a STATIC SCAN of the built
+ * bundle: the direct records API names a model in a literal request argument
+ * with neither a registration nor `.model()` (D3279-006), so the run above
+ * cannot see it and the text can. A name the scan cannot resolve — a computed
+ * `modelName`, a `.model(variable)` — is marked `dynamicModels` rather than
+ * dropped, which is the difference between "names none" and "names these,
+ * and possibly more".
+ */
+/** The manifest encoding, versioned with the envelope that carries it. */
+export declare const FUNCTION_MANIFEST_SCHEMA_VERSION = 2;
+/** How long a tree's module scope may run before collection gives up. */
+export declare const COLLECT_TIMEOUT_MS = 20000;
+/** A push that cannot proceed because its manifest could not be collected. */
+export declare class FunctionCollectError extends Error {
+    constructor(message: string);
+}
+export interface CollectedQuery {
+    name: string;
+    /** `query` or `mutation` — which helper registered it. */
+    kind: "query" | "mutation";
+    /** The models the author declared it touches. */
+    models: string[];
+    /** Declared parameters, by name. `$caller` params are marked here. */
+    params: Record<string, {
+        type?: string;
+        caller?: boolean;
+        default?: unknown;
+    }>;
+    /** The declared cache policy, or null when caching is off. */
+    cache: {
+        ttlMs: number;
+    } | null;
+    /** True when every declared parameter binding is `$caller`-scoped. */
+    callerScoped: boolean;
+}
+export interface FunctionManifest {
+    schemaVersion: number;
+    queries: CollectedQuery[];
+    /** Every model the bundle names, deduplicated and sorted (#3279). */
+    models: string[];
+    /** Every `ctx.api.<family>` and ctx-helper family the bundle reaches. */
+    families: string[];
+    /** A model name the scan could not resolve; "and possibly more". */
+    dynamicModels: boolean;
+}
+export declare function scanBundleForManifest(bundle: string): {
+    models: string[];
+    families: string[];
+    dynamicModels: boolean;
+};
+/**
+ * The recording stub the collect build substitutes for
+ * `primitive-functions`.
+ *
+ * It records what was registered and does nothing else: `defineFunction` and
+ * every other export are inert, so a module that calls one at import time
+ * neither fails nor has an effect.
+ */
+export declare const COLLECT_STUB_SOURCE = "\nconst registry = (globalThis.__PRIMITIVE_COLLECT_REGISTRY__ ||= []);\n\n// The default-coercion rule the SDK applies at registration (#3281,\n// D3281-SO-005), spelled here too so a default the declared type cannot\n// coerce is refused at PUSH \u2014 this stub is what push runs \u2014 rather than at\n// the first invocation. The vendored grammar (`coerceParamDefault` in\n// generated-config-surfaces.ts) is the same rule and re-checks the manifest.\nconst SCALAR_TYPES = [\"string\", \"number\", \"boolean\", \"any\"];\nfunction coerceScalar(type, value) {\n  if (type === \"number\") {\n    const n = typeof value === \"number\" ? value : Number(value);\n    if (typeof value === \"boolean\" || value === null || value === \"\" || !Number.isFinite(n)) {\n      return { ok: false, reason: \"must be a number\" };\n    }\n    return { ok: true, value: n };\n  }\n  if (type === \"boolean\") {\n    if (typeof value === \"boolean\") return { ok: true, value };\n    if (value === \"true\") return { ok: true, value: true };\n    if (value === \"false\") return { ok: true, value: false };\n    return { ok: false, reason: \"must be a boolean\" };\n  }\n  if (type === \"string\") {\n    if (typeof value !== \"string\") return { ok: false, reason: \"must be a string\" };\n    return { ok: true, value };\n  }\n  return { ok: true, value };\n}\nfunction coerceDefault(spec, value) {\n  if (spec.type === \"array\") {\n    if (!Array.isArray(value)) return { ok: false, reason: \"must be an array\" };\n    const itemType = spec.items && spec.items.type ? String(spec.items.type) : \"any\";\n    const out = [];\n    for (const element of value) {\n      const coerced = coerceScalar(itemType, element);\n      if (!coerced.ok) return { ok: false, reason: \"every element \" + coerced.reason };\n      out.push(coerced.value);\n    }\n    return { ok: true, value: out };\n  }\n  return coerceScalar(spec.type === undefined ? \"any\" : String(spec.type), value);\n}\n\nfunction record(kind, name, config) {\n  const c = config || {};\n  const params = {};\n  for (const [key, value] of Object.entries(c.params || {})) {\n    const spec = value && typeof value === \"object\" ? value : { type: String(value) };\n    const entry = {};\n    const fail = (message) => {\n      throw new Error(\"'\" + name + \"': parameter '\" + key + \"' \" + message);\n    };\n    if (spec.type !== undefined) entry.type = String(spec.type);\n    if (entry.type === \"array\") {\n      if (spec.items !== undefined && spec.items !== null) {\n        const itemType =\n          spec.items && typeof spec.items === \"object\" ? String(spec.items.type ?? \"\") : \"\";\n        if (!SCALAR_TYPES.includes(itemType)) {\n          fail(\"declares an `items` type outside \" + SCALAR_TYPES.join(\", \") + \".\");\n        }\n        entry.items = { type: itemType };\n      }\n      if (spec.caller === true) fail(\"is an array bound to $caller; `caller` is a scalar binding.\");\n    }\n    if (spec.default !== undefined) {\n      const coerced = coerceDefault(entry, spec.default);\n      if (!coerced.ok) fail(\"has a default that \" + coerced.reason + \".\");\n      entry.default = coerced.value;\n    }\n    if (spec.caller === true || spec === \"$caller\" || spec.type === \"$caller\") {\n      entry.caller = true;\n    }\n    params[String(key)] = entry;\n  }\n  const declaredCaller = Object.values(params).some((p) => p.caller === true);\n  registry.push({\n    kind,\n    name: String(name),\n    models: Array.isArray(c.models) ? c.models.map(String) : [],\n    params,\n    cache:\n      c.cache && typeof c.cache === \"object\" && Number(c.cache.ttlMs) > 0\n        ? { ttlMs: Number(c.cache.ttlMs) }\n        : null,\n    callerScoped: declaredCaller,\n  });\n  return async () => {\n    throw new Error(\n      \"'\" + name + \"' was called during manifest collection; a registration's \" +\n        \"`run` only executes inside a real invocation.\"\n    );\n  };\n}\n\n// The PUBLIC surface, all of it. An ESM import of a name a module does not\n// export is a build error, so a stub missing one export refuses a tree the\n// sandbox would have run \u2014 collection is mandatory, so that is a valid\n// function that cannot be pushed at all (CR3187-007). The constants carry the\n// runtime's own values so a registration computed from one collects the same\n// way it will run.\nexport const SDK_STUB_VERSION = \"collect\";\nexport const MAX_QUERY_CACHE_TTL_MS = 60000;\nexport const PMAP_DEFAULT_CONCURRENCY = 8;\nexport function defineQuery(name, config) { return record(\"query\", name, config); }\nexport function defineMutation(name, config) { return record(\"mutation\", name, config); }\nexport function defineFunction(keyOrHandler, maybeHandler) {\n  // The KEYED form (#3281) returns a wrapper CARRYING its key, exactly as the\n  // baked SDK's does. That is what push reads: the child resolves the callable\n  // the bootstrap would select and compares THAT key to the file's\n  // (D3281-SO-006). The registry entry is the child's report of what the\n  // module scope did; it is not what the check consults, because a keyed\n  // handler an entry merely imports for composition registers here too.\n  if (typeof keyOrHandler === \"string\" || maybeHandler !== undefined) {\n    registry.push({ kind: \"function\", name: String(keyOrHandler) });\n    const wrapped = function (...args) {\n      return maybeHandler(...args);\n    };\n    wrapped.functionKey = String(keyOrHandler);\n    return wrapped;\n  }\n  return keyOrHandler;\n}\nexport function pMap(items, mapper) { return Promise.all((items || []).map(mapper)); }\nexport function ulid() { return \"00000000000000000000000000\"; }\nexport const stepPolicy = new Proxy({}, { get: () => ({}) });\n// #3482 \u2014 the runtime surface, and `assertRuntime` is INERT here on purpose.\n// Collection has no runtime: this child process exists to learn what a tree\n// registers, and there is nothing for an assertion to be about. A stub that\n// threw would refuse exactly the functions the assertion exists for \u2014 and the\n// placement the guide teaches is module scope, which collection runs.\nexport function assertRuntime() {}\nexport class FunctionRuntimeError extends Error {\n  constructor(message, runtime, required) {\n    super(message);\n    this.name = \"FUNCTION_RUNTIME_REFUSED\";\n    this.runtime = runtime;\n    this.required = required;\n  }\n}\nexport default {\n  SDK_STUB_VERSION,\n  defineFunction,\n  defineQuery,\n  defineMutation,\n  pMap,\n  ulid,\n  assertRuntime,\n  FunctionRuntimeError,\n};\n";
+/**
+ * Collect one function's manifest.
+ *
+ * Throws `FunctionCollectError` for every failure — a build error, a module
+ * that throws at import, a loop that outlives the bound, or output that is not
+ * the framed result — because a push whose manifest could not be collected is
+ * refused rather than pushed without one (D3187-SO-005: the manifest is part
+ * of the envelope, so "later" would mean a different version).
+ */
+export declare function collectFunctionManifest(options: {
+    configDir: string;
+    entry: string;
+    functionKey: string;
+    timeoutMs?: number;
+    /**
+     * The BUILT bundle's source, for the static scan (#3279). The collect
+     * bundle below aliases the SDK to a stub and is not what the platform
+     * runs; the real bundle is, and its literals are what the scan reads.
+     */
+    bundle?: string;
+}): Promise<FunctionManifest>;