@wrenai/genbi 0.0.1

package/dist-server/harness/compile/pipeline.js

@@ -0,0 +1,176 @@
+import { execFile } from "node:child_process";
+import { mkdtemp, rm } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { createFileSystemCompileCache } from "./cache.js";
+import { composeUserProfile } from "./compose-profile.js";
+import { WarbleCommandFailedError } from "./errors.js";
+import { hashDirectory, hashFiles } from "./fingerprint.js";
+import { resolveHubDir, resolveWarbleBinary } from "./resolve-binary.js";
+import { getWarbleIdentity } from "./warble-identity.js";
+/** Fixed `providerFragmentHash` for `"native"` mode, which never reads `--provider` fragments at all. */
+const NATIVE_MODE_PROVIDER_HASH = "native:no-providers";
+/**
+ * This package's bundled wren capability-provider fragment (`providers/wren.provider.yaml`) — the
+ * default `--provider` for in-process dispatch, matching how `fixtures/genbi-default.native.bundle.json`
+ * was produced (see `test/e2e-wren-native.test.ts`'s comment).
+ */
+export const DEFAULT_WREN_PROVIDER_PATH = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "..", "providers", "wren.provider.yaml");
+// guardrail-enforcement fix: a hung `warble compile`/`dispatch` invocation
+// previously blocked forever. 2 minutes is a generous ceiling for a local
+// compile/dispatch step that normally finishes in seconds; guards against a
+// hang, not meant to ever fire in normal operation.
+const WARBLE_COMMAND_TIMEOUT_MS = 2 * 60 * 1000;
+/**
+ * Compiles a Warble profile bound to a specific user's wren project (the per-user compile
+ * pipeline): composes a copy of `profileSource` with its context binding rebound to `userProject`
+ * (see `composeUserProfile`), shells out to `warble compile` for the IR, and — in `"agnostic"`
+ * mode — additionally `warble dispatch --target vercel` for the vercel bundle this package's
+ * `runAgent()` consumes.
+ *
+ * A cache hit (see below) never *executes* `warble`, but by default DOES need to resolve + read
+ * the binary — its content hash and the Hub root derived from its location are both cache-key
+ * inputs (see `warbleIdentity` and `hubDir` below), so a hit can't be trusted without knowing which
+ * binary is current and which component library it reads. Pass both `options.warbleIdentity` and
+ * `options.hubDir` explicitly to skip touching the binary at all even on a hit.
+ *
+ * Deliberately shells via plain `node:child_process` (`execFile`, no shell) rather than this
+ * package's `ExecutionEnv` seam (`harness/exec/`): `ExecutionEnv` gates *runtime* native-tool side
+ * effects against a bundle's guardrail-derived `EnforcementPolicy` (read-only / write-scope /
+ * egress) — there is no bundle or agent yet at this point, compiling happens before any of that
+ * exists, so synthesizing a policy for it would be a semantic mismatch, not a reuse. This mirrors
+ * the same no-shell, structured-result `execFile` convention `harness/exec/local.ts` already uses.
+ *
+ * Results are cached on (profile content hash x user-context fingerprint x mode x resolved
+ * provider-fragment content hash x warble binary identity x resolved Hub root) — see `./cache.js` —
+ * so an unchanged profile/context/providers/compiler/Hub tuple returns the previous artifact
+ * instead of recompiling. Folding in the provider-fragment hash, warble identity and Hub root
+ * (rather than just profile+context+mode) matters: otherwise a custom `options.providers` and this
+ * package's default fragment collide on the same key, and editing a provider fragment, rebuilding
+ * `warble`, or compiling against a different component library would keep serving a stale artifact
+ * forever, since there's no TTL/eviction.
+ *
+ * The `warble` invocations run inside a temporary scratch directory (the composed profile + raw
+ * compiler output). When the cache relocates the artifacts to a durable home outside that scratch
+ * dir — as the default persistent {@link createFileSystemCompileCache} does — the scratch dir is
+ * removed and the durable cache paths are returned. When the cache does NOT relocate them (e.g. a
+ * non-persistent in-memory cache that just stores the paths), the scratch dir is retained so the
+ * returned paths stay valid. Either way the returned `irPath`/`bundlePath` are always readable, and
+ * a caller-supplied `workDir` is never deleted.
+ */
+export async function compileProfile(options) {
+    return compileProfileSource(options, await hashDirectory(path.resolve(options.userProject)), (workDir) => composeUserProfile({
+        profileSource: options.profileSource,
+        userProject: options.userProject,
+        destDir: workDir,
+    }));
+}
+/**
+ * Compiles a profile's authored context without composing it against a bound
+ * project. The fixed context fingerprint keeps raw-profile artifacts distinct
+ * from every user-project-bound compile while `profileHash` still invalidates
+ * the entry whenever the source profile changes.
+ */
+export async function compileRawProfile(options) {
+    return compileProfileSource(options, "raw-profile-context", async () => path.resolve(options.profileSource));
+}
+async function compileProfileSource(options, contextFingerprint, prepareProfile) {
+    const cache = options.cache ?? createFileSystemCompileCache();
+    const profileHash = await hashDirectory(path.resolve(options.profileSource));
+    const providerPaths = options.providers ?? [DEFAULT_WREN_PROVIDER_PATH];
+    const providerFragmentHash = options.mode === "agnostic" ? await hashFiles(providerPaths) : NATIVE_MODE_PROVIDER_HASH;
+    // Resolving `warble` is memoized here so it happens at most once per call no matter how many of
+    // the two spots below need it (identity computation, and — on a miss — actually running it).
+    let resolvedWarbleBin;
+    const ensureWarbleBin = async () => {
+        if (resolvedWarbleBin === undefined) {
+            resolvedWarbleBin = await resolveWarbleBinary(options.warbleBin);
+        }
+        return resolvedWarbleBin;
+    };
+    // Without an explicit `options.warbleIdentity`, computing the key requires resolving the binary
+    // even for what would otherwise be a cache hit — the whole point of folding warble's identity in
+    // is to invalidate a hit whose binary has since been rebuilt, which is unknowable without
+    // checking. A caller who wants the old "no warble touched at all on a hit" property back can get
+    // it by passing `warbleIdentity` explicitly (see `CompileProfileOptions.warbleIdentity`).
+    const warbleIdentity = options.warbleIdentity ?? (await getWarbleIdentity(await ensureWarbleBin()));
+    // Derived from the resolved binary, never configured on its own, so the compiler and the Hub it
+    // reads always come from the same warble (see `resolveHubDir`). That means it shares
+    // `warbleIdentity`'s caveat: without an explicit `options.hubDir` the key can't be computed
+    // without resolving the binary. `undefined` here means no `--hub-dir` is passed at all and
+    // warble's compiled-in default applies — today's behaviour, preserved.
+    const hubDir = options.hubDir ?? resolveHubDir(await ensureWarbleBin());
+    const cacheKey = { profileHash, contextFingerprint, mode: options.mode, providerFragmentHash, warbleIdentity, hubDir };
+    const cached = await cache.get(cacheKey);
+    if (cached !== undefined) {
+        return { ...cached, cacheHit: true, ...(resolvedWarbleBin !== undefined ? { warbleBin: resolvedWarbleBin } : {}) };
+    }
+    const warbleBin = await ensureWarbleBin();
+    const callerSuppliedWorkDir = options.workDir !== undefined;
+    const workDir = options.workDir ?? (await mkdtemp(path.join(os.tmpdir(), "wren-harness-compile-")));
+    // Only ever remove a scratch dir we created ourselves; refine to `false` if the cache leaves the
+    // artifacts inside it (removing them would invalidate the returned paths).
+    let removeWorkDir = !callerSuppliedWorkDir;
+    try {
+        const compiledProfile = await prepareProfile(workDir);
+        const irPath = path.join(workDir, "ir.json");
+        // `--hub-dir` reached the compiler in July 2026, well before the IR version this harness
+        // requires, so any binary new enough to satisfy that contract accepts the flag. A binary
+        // older than both was already unsupported — but it used to say so as an IR version
+        // mismatch, and now clap rejects the argument first. The configuration is no more broken
+        // than before; only the message got less helpful, which is worth knowing when one appears.
+        const hubDirArgs = hubDir !== undefined ? ["--hub-dir", hubDir] : [];
+        await runWarble(warbleBin, ["compile", compiledProfile, "-o", irPath, ...hubDirArgs]);
+        let bundlePath;
+        if (options.mode === "agnostic") {
+            const bundleOutDir = path.join(workDir, "bundle");
+            const providerArgs = providerPaths.flatMap((provider) => ["--provider", provider]);
+            await runWarble(warbleBin, ["dispatch", "--target", "vercel", ...providerArgs, irPath, "--out", bundleOutDir]);
+            bundlePath = path.join(bundleOutDir, "bundle.json");
+        }
+        const freshEntry = { irPath, ...(bundlePath !== undefined ? { bundlePath } : {}) };
+        await cache.set(cacheKey, freshEntry);
+        // Prefer the cache's persisted paths; if the cache relocated the IR out of the scratch dir the
+        // scratch dir is pure garbage now and safe to delete, otherwise keep it so paths stay valid.
+        const persisted = (await cache.get(cacheKey)) ?? freshEntry;
+        if (persisted.irPath === freshEntry.irPath) {
+            removeWorkDir = false;
+        }
+        return { ...persisted, cacheHit: false, warbleBin };
+    }
+    finally {
+        if (removeWorkDir) {
+            await rm(workDir, { recursive: true, force: true });
+        }
+    }
+}
+/**
+ * Shells a `warble` subcommand (no shell interpolation — `execFile`, argv
+ * array only). Exported for `InProcessSetupRunner` (`harness/setup/runner.ts`),
+ * which dispatches the pre-committed `genbi-setup/ir.golden.json` straight to
+ * `warble dispatch --target vercel`, bypassing `compileProfile`'s
+ * `composeUserProfile` rewrite entirely (there is no user project to bind
+ * context against at setup time — see that runner's doc comment). Reusing
+ * this rather than duplicating an `execFile` wrapper keeps the two callers'
+ * timeout/max-buffer/error-shaping behavior identical.
+ */
+export function runWarble(bin, args) {
+    return new Promise((resolve, reject) => {
+        execFile(bin, [...args], { maxBuffer: 32 * 1024 * 1024, timeout: WARBLE_COMMAND_TIMEOUT_MS }, (error, stdout, stderr) => {
+            if (error) {
+                const exitCode = typeof error.code === "number" ? error.code : 1;
+                const clarifiedStderr = stderr.length > 0
+                    ? stderr
+                    : error.killed === true
+                        ? `warble subprocess timed out after ${WARBLE_COMMAND_TIMEOUT_MS}ms`
+                        : error.code === "ERR_CHILD_PROCESS_STDIO_MAXBUFFER"
+                            ? "warble subprocess exceeded the 32 MiB output buffer"
+                            : stderr;
+                reject(new WarbleCommandFailedError(bin, args, exitCode, clarifiedStderr, stdout));
+                return;
+            }
+            resolve({ stdout, stderr });
+        });
+    });
+}

package/dist-server/harness/compile/resolve-binary.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Resolves the `warble` binary in four tiers, in order:
+ *
+ * 1. `explicit` — if given, it must exist on disk (no PATH lookup, no fallback).
+ * 2. The pinned `@warble/cli` npm package this workspace depends on (see
+ *    `resolveInstalledPackageBin`) — deterministic regardless of `PATH` contents or how the
+ *    process was launched, so the reviewable version in `package.json` always wins.
+ * 3. `PATH` — a bare `"warble"` that `warble --help` succeeds against. NOT `--version`: the warble
+ *    CLI has no `--version` flag (clap rejects it with exit 2 — the same fact
+ *    `test/compile-warble-identity.test.ts` notes for a different reason), so probing with it made
+ *    this tier fail for a binary that was on `PATH` and working, silently pushing every caller past
+ *    it. `warble --help` exits 0 and is what the sibling `warble-agent-sdk` probe already uses.
+ *    Kept as a fallback for a standalone install (e.g. `cargo install warble-cli`) on a machine
+ *    that hasn't run `pnpm install` against this package's pinned dependency.
+ * 4. A sibling `warble` repo's release build, gated behind the explicit
+ *    `WREN_HARNESS_ALLOW_WARBLE_SIBLING_CHECKOUT=1` development-mode opt-in (see
+ *    `isWarbleSiblingCheckoutDevModeEnabled`) — this walks up from this package's own install
+ *    location looking for a `warble/target/release/warble` next to an ancestor directory, so it
+ *    works whether the caller runs from the main checkout or from a git worktree nested several
+ *    levels under it. Off by default: now that the pinned `@warble/cli` package is tier 2, this
+ *    tier exists only for someone deliberately developing GenBI against an unreleased, uninstalled
+ *    Warble checkout, and must not silently win over the pinned package.
+ *
+ * Throws {@link WarbleBinaryNotFoundError} (loud-fail, no silent degrade) if none of the four work.
+ */
+export declare function resolveWarbleBinary(explicit?: string): Promise<string>;
+/**
+ * Resolves the Hub component-library root to pass as `warble compile --hub-dir`, derived from the
+ * **already-resolved** `warble` binary rather than configured on its own.
+ *
+ * warble bakes its default Hub path in at *build* time (its own doc says the Hub is known at
+ * compile time and never discovered by walking the filesystem at run time), so a binary built
+ * inside a warble checkout still finds its own Hub with no flag at all. That stops being true the
+ * moment the compiler is not a checkout-local build — installed from a release, found on `PATH`,
+ * built in CI, or a checkout that has since moved — and the failure is silent: components resolve
+ * against the wrong library, or against none. Naming the root turns that into a loud "component
+ * not found in any configured source".
+ *
+ * Deriving it from the binary is the whole point. The compiler and the Hub it reads must come from
+ * the same warble version; an independently configured Hub root can silently pair a new library
+ * with an old compiler, which is the same class of mismatch `CompileCacheKey.warbleIdentity`
+ * exists to catch.
+ *
+ * Two tiers, then give up:
+ *
+ * 1. The binary's own checkout — a `<root>/target/release/warble` puts the Hub at
+ *    `<root>/hub/components`. Skipped for a bare `"warble"` resolved off `PATH`, which names no
+ *    directory to walk up from.
+ * 2. A sibling `warble` checkout's `hub/components`, via the same ancestor walk tier 3 of
+ *    {@link resolveWarbleBinary} uses.
+ *
+ * Returns `undefined` when neither resolves; callers then pass no `--hub-dir` at all, leaving
+ * today's compiled-in default in charge rather than pointing warble at a directory we guessed.
+ */
+export declare function resolveHubDir(warbleBin: string): string | undefined;

package/dist-server/harness/compile/resolve-binary.js

@@ -0,0 +1,133 @@
+import { execFile } from "node:child_process";
+import { existsSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import path from "node:path";
+import { WarbleBinaryNotFoundError } from "./errors.js";
+import { isWarbleSiblingCheckoutDevModeEnabled, resolveInstalledPackageBin } from "../npm-package-resolve.js";
+/**
+ * Resolves the `warble` binary in four tiers, in order:
+ *
+ * 1. `explicit` — if given, it must exist on disk (no PATH lookup, no fallback).
+ * 2. The pinned `@warble/cli` npm package this workspace depends on (see
+ *    `resolveInstalledPackageBin`) — deterministic regardless of `PATH` contents or how the
+ *    process was launched, so the reviewable version in `package.json` always wins.
+ * 3. `PATH` — a bare `"warble"` that `warble --help` succeeds against. NOT `--version`: the warble
+ *    CLI has no `--version` flag (clap rejects it with exit 2 — the same fact
+ *    `test/compile-warble-identity.test.ts` notes for a different reason), so probing with it made
+ *    this tier fail for a binary that was on `PATH` and working, silently pushing every caller past
+ *    it. `warble --help` exits 0 and is what the sibling `warble-agent-sdk` probe already uses.
+ *    Kept as a fallback for a standalone install (e.g. `cargo install warble-cli`) on a machine
+ *    that hasn't run `pnpm install` against this package's pinned dependency.
+ * 4. A sibling `warble` repo's release build, gated behind the explicit
+ *    `WREN_HARNESS_ALLOW_WARBLE_SIBLING_CHECKOUT=1` development-mode opt-in (see
+ *    `isWarbleSiblingCheckoutDevModeEnabled`) — this walks up from this package's own install
+ *    location looking for a `warble/target/release/warble` next to an ancestor directory, so it
+ *    works whether the caller runs from the main checkout or from a git worktree nested several
+ *    levels under it. Off by default: now that the pinned `@warble/cli` package is tier 2, this
+ *    tier exists only for someone deliberately developing GenBI against an unreleased, uninstalled
+ *    Warble checkout, and must not silently win over the pinned package.
+ *
+ * Throws {@link WarbleBinaryNotFoundError} (loud-fail, no silent degrade) if none of the four work.
+ */
+export async function resolveWarbleBinary(explicit) {
+    if (explicit !== undefined) {
+        if (!existsSync(explicit)) {
+            throw new WarbleBinaryNotFoundError([`explicit warbleBin "${explicit}" does not exist`]);
+        }
+        return explicit;
+    }
+    const attempts = [];
+    const packageBin = resolveInstalledPackageBin("@warble/cli", "warble");
+    if (packageBin !== undefined) {
+        return packageBin;
+    }
+    attempts.push(`"@warble/cli" is not installed (or declares no "warble" bin) in this workspace`);
+    if (await isExecutableOnPath("warble")) {
+        return "warble";
+    }
+    attempts.push(`not found on PATH (tried running "warble --help")`);
+    if (isWarbleSiblingCheckoutDevModeEnabled()) {
+        const sibling = findSiblingReleaseBuild();
+        if (sibling !== undefined) {
+            return sibling;
+        }
+        attempts.push(`no sibling "warble" repo release build found (searched ancestors of this package for ` +
+            `"<ancestor's parent>/warble/target/release/warble")`);
+    }
+    else {
+        attempts.push(`sibling "warble" checkout dev mode is disabled (set WREN_HARNESS_ALLOW_WARBLE_SIBLING_CHECKOUT=1 to enable it)`);
+    }
+    throw new WarbleBinaryNotFoundError(attempts);
+}
+function isExecutableOnPath(bin) {
+    return new Promise((resolve) => {
+        // Callback overload (no options): output is buffered and discarded — we only care whether the
+        // process launched and exited 0. `warble --help` output is tiny, so no maxBuffer concern.
+        execFile(bin, ["--help"], (error) => resolve(!error));
+    });
+}
+/**
+ * Resolves the Hub component-library root to pass as `warble compile --hub-dir`, derived from the
+ * **already-resolved** `warble` binary rather than configured on its own.
+ *
+ * warble bakes its default Hub path in at *build* time (its own doc says the Hub is known at
+ * compile time and never discovered by walking the filesystem at run time), so a binary built
+ * inside a warble checkout still finds its own Hub with no flag at all. That stops being true the
+ * moment the compiler is not a checkout-local build — installed from a release, found on `PATH`,
+ * built in CI, or a checkout that has since moved — and the failure is silent: components resolve
+ * against the wrong library, or against none. Naming the root turns that into a loud "component
+ * not found in any configured source".
+ *
+ * Deriving it from the binary is the whole point. The compiler and the Hub it reads must come from
+ * the same warble version; an independently configured Hub root can silently pair a new library
+ * with an old compiler, which is the same class of mismatch `CompileCacheKey.warbleIdentity`
+ * exists to catch.
+ *
+ * Two tiers, then give up:
+ *
+ * 1. The binary's own checkout — a `<root>/target/release/warble` puts the Hub at
+ *    `<root>/hub/components`. Skipped for a bare `"warble"` resolved off `PATH`, which names no
+ *    directory to walk up from.
+ * 2. A sibling `warble` checkout's `hub/components`, via the same ancestor walk tier 3 of
+ *    {@link resolveWarbleBinary} uses.
+ *
+ * Returns `undefined` when neither resolves; callers then pass no `--hub-dir` at all, leaving
+ * today's compiled-in default in charge rather than pointing warble at a directory we guessed.
+ */
+export function resolveHubDir(warbleBin) {
+    // `path.dirname("warble") === "."` is exactly the bare-PATH case: resolving `..` against the
+    // process cwd would name some unrelated ancestor, so only a binary that names a directory
+    // gets tier 1.
+    if (path.dirname(warbleBin) !== ".") {
+        const candidate = path.resolve(warbleBin, "..", "..", "..", "hub", "components");
+        if (existsSync(candidate))
+            return candidate;
+    }
+    return findSiblingWarbleEntry("hub", "components");
+}
+/**
+ * Walks up from this package's own directory (`harness/compile/` in source, `dist/compile/` once
+ * built — either way two levels below the package root) looking for a `warble` directory sibling
+ * to each ancestor, returning `.../warble/target/release/warble` the first time it exists.
+ */
+function findSiblingReleaseBuild() {
+    return findSiblingWarbleEntry("target", "release", "warble");
+}
+/**
+ * The shared ancestor walk behind both sibling lookups above: for each ancestor of this package,
+ * test `<ancestor's parent>/warble/<...segments>` and return the first that exists.
+ */
+function findSiblingWarbleEntry(...segments) {
+    let dir = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "..");
+    const maxDepth = 10;
+    for (let i = 0; i < maxDepth; i += 1) {
+        const parent = path.dirname(dir);
+        const candidate = path.join(parent, "warble", ...segments);
+        if (existsSync(candidate))
+            return candidate;
+        if (parent === dir)
+            break; // reached filesystem root
+        dir = parent;
+    }
+    return undefined;
+}

package/dist-server/harness/compile/types.d.ts

@@ -0,0 +1,107 @@
+/**
+ * Which back-end a compiled IR is realized for.
+ *
+ * - `"agnostic"` — in-process: the compiled IR is additionally dispatched to a **vercel bundle**
+ *   (`warble dispatch --target vercel`), the format this package's `runAgent()` consumes.
+ * - `"native"` — dispatched: IR only. Dispatching to a file-based target (`claude-code:*`) produces
+ *   agent files on disk, not something this harness loads/runs — out of scope for this package.
+ */
+export type CompileMode = "agnostic" | "native";
+export interface CompileCacheKey {
+    /** Content fingerprint of the source profile directory (profile.yml + components + fixture binding). */
+    readonly profileHash: string;
+    /** Content fingerprint of the user's wren project directory (the per-user context binding). */
+    readonly contextFingerprint: string;
+    readonly mode: CompileMode;
+    /**
+     * Content hash of the resolved `--provider` fragment file(s) actually used for `"agnostic"` mode's
+     * vercel dispatch (order-sensitive — see `hashFiles`), so a custom `options.providers` and this
+     * package's default fragment never collide on the same key. Fixed sentinel for `"native"` mode,
+     * which never reads providers at all.
+     */
+    readonly providerFragmentHash: string;
+    /**
+     * Content identity of the resolved `warble` binary (see `getWarbleIdentity`) — folds the compiler
+     * itself into the key so rebuilding/replacing the binary invalidates entries it previously
+     * compiled, instead of silently serving an artifact built by a now-stale `warble`.
+     */
+    readonly warbleIdentity: string;
+    /**
+     * The Hub component-library root passed to `warble compile --hub-dir` (see `resolveHubDir`), or
+     * `undefined` when none could be derived and the compile therefore ran against warble's own
+     * compiled-in default. Two compiles that differ only by Hub root read different component
+     * libraries and must not share a cached artifact — the same reason `warbleIdentity` is here.
+     */
+    readonly hubDir: string | undefined;
+}
+export interface CompileCacheEntry {
+    readonly irPath: string;
+    readonly bundlePath?: string;
+}
+/**
+ * Pluggable cache seam, keyed on (profile content hash x user-context fingerprint x mode) — see
+ * `./fingerprint.js`. `get` returns `undefined` on a miss (including a "hit" whose files were
+ * since deleted from disk); `set` persists an entry produced by a fresh compile so a later `get`
+ * with the same key can skip recompiling.
+ */
+export interface CompileCache {
+    get(key: CompileCacheKey): Promise<CompileCacheEntry | undefined>;
+    set(key: CompileCacheKey, entry: CompileCacheEntry): Promise<void>;
+}
+export interface CompileProfileOptions {
+    /** Directory of the source Warble profile (profile.yml + components/ + context/binding.yml), e.g. `genbi-default`. */
+    readonly profileSource: string;
+    /** Directory of the per-user wren project (MDL + Knowledge) the profile's context binding is rebound to. */
+    readonly userProject: string;
+    readonly mode: CompileMode;
+    /** Explicit path to the `warble` binary. See `resolveWarbleBinary` for the full resolution order when omitted. */
+    readonly warbleBin?: string;
+    /**
+     * `--provider` fragment paths for the in-process vercel dispatch (ignored in `"native"` mode).
+     * Defaults to this package's bundled `providers/wren.provider.yaml` (the wren capability-provider
+     * fragment already used to produce `fixtures/genbi-default.native.bundle.json`). Pass `[]`
+     * explicitly to dispatch with no provider fragments at all.
+     */
+    readonly providers?: readonly string[];
+    readonly cache?: CompileCache;
+    /** Base scratch directory for the composed profile + compiler output. Defaults to a fresh `os.tmpdir()` mkdtemp. */
+    readonly workDir?: string;
+    /**
+     * Precomputed identity for the resolved `warble` binary (see `CompileCacheKey.warbleIdentity`).
+     * When omitted, `compileProfile` resolves `warbleBin` and computes it via `getWarbleIdentity` —
+     * which, for a cache MISS, it would need to do anyway to run the compile, but for what would
+     * otherwise be a cache HIT this means resolving the binary even though nothing gets executed.
+     * Pass this explicitly (e.g. computed once at process startup, or stubbed in a test) to make a
+     * hit skip touching the binary at all.
+     */
+    readonly warbleIdentity?: string;
+    /**
+     * Explicit Hub component-library root for `warble compile --hub-dir`. When omitted it is derived
+     * from the resolved `warble` binary (see `resolveHubDir`) so the compiler and its Hub always come
+     * from the same warble version — prefer that over setting this. Like `warbleIdentity`, this also
+     * doubles as an escape hatch: because the derived value is a cache-key input, computing the key
+     * without it has to resolve the binary even for what would otherwise be a cache hit. Pass both to
+     * make a hit touch the binary not at all.
+     */
+    readonly hubDir?: string;
+}
+/**
+ * Compiles a profile exactly as authored, without rebinding its context to a
+ * user project. Bootstrap profiles intentionally use this path because their
+ * context is part of the profile source rather than a completed Setup result.
+ */
+export type CompileRawProfileOptions = Omit<CompileProfileOptions, "userProject">;
+export interface CompileProfileResult {
+    readonly irPath: string;
+    readonly bundlePath?: string;
+    /** `true` when the result came from the cache without invoking `warble` at all. */
+    readonly cacheHit: boolean;
+    /**
+     * The resolved `warble` binary path used for this call, when resolution actually happened —
+     * lets a caller that hits a downstream `BundleCompatError` name which on-disk checkout produced
+     * the bundle (see `loadBundleWithProvenance`, `harness/bundle/loader.ts`). `undefined` only in
+     * the one case where resolution is skippable: a cache hit with an explicit
+     * `options.warbleIdentity` (see that option's doc comment) never touches the binary at all.
+     */
+    readonly warbleBin?: string;
+}

package/dist-server/harness/compile/types.js

@@ -0,0 +1 @@
+export {};

package/dist-server/harness/compile/warble-identity.d.ts

@@ -0,0 +1,12 @@
+/**
+ * A content identity for the resolved `warble` binary at `binPath`, folded into the compile cache
+ * key (see `CompileCacheKey.warbleIdentity`) so rebuilding/replacing the binary a cache slot was
+ * compiled with invalidates it, instead of silently serving an artifact built by a now-stale
+ * `warble`.
+ *
+ * Hashes the binary's file *content* rather than shelling out to `warble --version`: the real
+ * `warble` CLI has no `--version` flag (its `clap`-based parser rejects it, exit code 2), and
+ * content hashing needs no subprocess at all — so under the default (no `options.warbleIdentity`
+ * override), a cache hit still never *executes* warble, only resolves + reads its file.
+ */
+export declare function getWarbleIdentity(binPath: string): Promise<string>;

package/dist-server/harness/compile/warble-identity.js

@@ -0,0 +1,33 @@
+import { createHash } from "node:crypto";
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+/**
+ * Per-process memoization keyed by resolved absolute binary path: computing the identity means
+ * reading the (multi-MB) binary's full contents, so within one process a given resolved path is
+ * hashed at most once no matter how many `compileProfile` calls reuse it.
+ */
+const identityCache = new Map();
+/**
+ * A content identity for the resolved `warble` binary at `binPath`, folded into the compile cache
+ * key (see `CompileCacheKey.warbleIdentity`) so rebuilding/replacing the binary a cache slot was
+ * compiled with invalidates it, instead of silently serving an artifact built by a now-stale
+ * `warble`.
+ *
+ * Hashes the binary's file *content* rather than shelling out to `warble --version`: the real
+ * `warble` CLI has no `--version` flag (its `clap`-based parser rejects it, exit code 2), and
+ * content hashing needs no subprocess at all — so under the default (no `options.warbleIdentity`
+ * override), a cache hit still never *executes* warble, only resolves + reads its file.
+ */
+export async function getWarbleIdentity(binPath) {
+    const resolved = path.resolve(binPath);
+    let cached = identityCache.get(resolved);
+    if (cached === undefined) {
+        cached = hashFile(resolved);
+        identityCache.set(resolved, cached);
+    }
+    return cached;
+}
+async function hashFile(filePath) {
+    const content = await readFile(filePath);
+    return createHash("sha256").update(content).digest("hex");
+}

package/dist-server/harness/compliance/gate.d.ts

@@ -0,0 +1,35 @@
+import type { AuthChoice } from "../auth/index.js";
+import type { ComplianceResult, Deployment } from "./types.js";
+/** Thrown when `enforceCompliance` rejects an `AuthChoice`/`Deployment` combination. Never thrown silently-downgraded — callers must handle it (route reject -> caller picks a different mode). */
+export declare class ComplianceError extends Error {
+    constructor(message: string);
+}
+/**
+ * Warning surfaced whenever `subscription` auth is used for `personal`
+ * deployment. Wording aligned with LangChain's own subscription-auth
+ * disclaimer: this is your personal subscription, it may violate the
+ * provider's Terms of Service (that risk is yours), the consumer backend
+ * and its policies are volatile and may change or break without notice,
+ * and this is for personal, single-operator use only — never multi-user or
+ * hosted. Not legal advice; verify against the provider's current ToS
+ * before relying on this.
+ */
+export declare const SUBSCRIPTION_TOS_WARNING: string;
+/**
+ * The compliance gate: a pure decision over an already-resolved
+ * `AuthChoice` and the operator-declared `deployment` context, meant to be
+ * called at the route()/onboarding seam *before* any back-end runs.
+ *
+ * - `subscription` + `hosted` -> throws {@link ComplianceError}. Personal
+ *   subscription auth used behind a shared/multi-tenant/always-on server is
+ *   account sharing, which the ToS warning below cannot excuse — there is
+ *   no silent downgrade to another mode; the caller must pick `api-key` or
+ *   `gateway` explicitly.
+ * - `subscription` + `personal` (the default) -> allowed, returning the
+ *   ToS warning the caller must surface before running.
+ * - `api-key` / `local` / `gateway` -> always allowed, no warning (only
+ *   `subscription` auth carries the ToS exposure this gate is about).
+ */
+export declare function enforceCompliance(authChoice: AuthChoice, options?: {
+    readonly deployment?: Deployment;
+}): ComplianceResult;

package/dist-server/harness/compliance/gate.js

@@ -0,0 +1,48 @@
+/** Thrown when `enforceCompliance` rejects an `AuthChoice`/`Deployment` combination. Never thrown silently-downgraded — callers must handle it (route reject -> caller picks a different mode). */
+export class ComplianceError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "ComplianceError";
+    }
+}
+/**
+ * Warning surfaced whenever `subscription` auth is used for `personal`
+ * deployment. Wording aligned with LangChain's own subscription-auth
+ * disclaimer: this is your personal subscription, it may violate the
+ * provider's Terms of Service (that risk is yours), the consumer backend
+ * and its policies are volatile and may change or break without notice,
+ * and this is for personal, single-operator use only — never multi-user or
+ * hosted. Not legal advice; verify against the provider's current ToS
+ * before relying on this.
+ */
+export const SUBSCRIPTION_TOS_WARNING = "using your personal subscription to authenticate may violate the provider's Terms of Service " +
+    "(that's your responsibility); the consumer backend and its policies are volatile and may change " +
+    "or break at any time; this is for personal, single-operator use only, never multi-user or hosted; " +
+    "verify against the provider's current ToS before relying on this — this is not legal advice.";
+/**
+ * The compliance gate: a pure decision over an already-resolved
+ * `AuthChoice` and the operator-declared `deployment` context, meant to be
+ * called at the route()/onboarding seam *before* any back-end runs.
+ *
+ * - `subscription` + `hosted` -> throws {@link ComplianceError}. Personal
+ *   subscription auth used behind a shared/multi-tenant/always-on server is
+ *   account sharing, which the ToS warning below cannot excuse — there is
+ *   no silent downgrade to another mode; the caller must pick `api-key` or
+ *   `gateway` explicitly.
+ * - `subscription` + `personal` (the default) -> allowed, returning the
+ *   ToS warning the caller must surface before running.
+ * - `api-key` / `local` / `gateway` -> always allowed, no warning (only
+ *   `subscription` auth carries the ToS exposure this gate is about).
+ */
+export function enforceCompliance(authChoice, options = {}) {
+    const deployment = options.deployment ?? "personal";
+    if (authChoice.mode !== "subscription") {
+        return { authChoice, warnings: [] };
+    }
+    if (deployment === "hosted") {
+        throw new ComplianceError("compliance: subscription auth is personal-use only and cannot serve a hosted " +
+            "(multi-tenant / shared / always-on-server) deployment — this is account sharing, which " +
+            "violates the provider's ToS; use --mode api-key or --mode gateway for hosted deployments.");
+    }
+    return { authChoice, warnings: [SUBSCRIPTION_TOS_WARNING] };
+}

package/dist-server/harness/compliance/index.d.ts

@@ -0,0 +1,2 @@
+export { ComplianceError, enforceCompliance, SUBSCRIPTION_TOS_WARNING } from "./gate.js";
+export type { ComplianceResult, Deployment } from "./types.js";

package/dist-server/harness/compliance/index.js

@@ -0,0 +1 @@
+export { ComplianceError, enforceCompliance, SUBSCRIPTION_TOS_WARNING } from "./gate.js";

package/dist-server/harness/compliance/types.d.ts

@@ -0,0 +1,16 @@
+import type { AuthChoice } from "../auth/index.js";
+/**
+ * The deployment context a compliance decision turns on. The harness has no
+ * way to self-detect multi-tenancy — whether it's serving one person on
+ * their own machine or sitting behind a shared, always-on endpoint is a
+ * fact only the operator knows — so it's taken as an explicit input rather
+ * than inferred. `"hosted"` means multi-tenant, shared, or always-on-server
+ * use; `"personal"` (the default) means a single operator on their own
+ * machine.
+ */
+export type Deployment = "personal" | "hosted";
+/** The gate's non-throwing outcome: the `AuthChoice` passed through, plus any warnings the caller must surface before a back-end runs. */
+export interface ComplianceResult {
+    readonly authChoice: AuthChoice;
+    readonly warnings: readonly string[];
+}

package/dist-server/harness/compliance/types.js

@@ -0,0 +1 @@
+export {};