@wrenai/genbi 0.0.4 → 0.0.5

package/dist-server/harness/compile/compose-profile.js

@@ -1,27 +1,44 @@
-import { cp, readFile, writeFile } from "node:fs/promises";
+import { cp, mkdir, readFile, writeFile } from "node:fs/promises";
 import path from "node:path";
 import { PathTraversalError } from "../exec/index.js";
+import { generatePreparedContext } from "./context-loader.js";
 import { InvalidProfileShapeError } from "./errors.js";
 /**
- * Copies `profileSource` into `destDir`, then rewrites its context binding's `project:` field to
- * point at `userProject` (absolute path) instead of the profile's own fixture binding. Returns the
- * composed profile's directory (safe to pass straight to `warble compile`).
+ * Copies `profileSource` into `destDir` and rebinds its context to `userProject`, producing a
+ * composed profile directory that is safe to pass straight to `warble compile`.
+ *
+ * The profile's context binding is a **prepared** binding (`kind: prepared`): Warble does not read
+ * the user's semantic layer itself, it reads a JSON *document* that WrenAI's own generator
+ * (`wren-context-loader`) produces. So rebinding is two writes, not one:
+ *
+ * 1. Run the generator over `userProject` and write its document over the profile's committed
+ *    fixture document, at the path the binding's `document:` field already names.
+ * 2. Rewrite the binding's `project:` line to `userProject` (absolute).
+ *
+ * `project:` stays the layer's **identity** and never becomes the document path. That exact
+ * substitution shipped once in Warble and put the filename into every compiled prompt, telling the
+ * agent it was working on a project called `context.json`; Warble now guards against it, and this
+ * side must not hand it a binding that tries.
+ *
+ * Because the generated document is written *to the path the binding already declares*, `document:`
+ * needs no rewriting at all — the composed binding differs from the committed one only in
+ * `project:`. Note that `document:` (like `project:`) resolves relative to the **Warble project
+ * root** (the composed directory), not relative to the binding file that declares it.
  *
  * The binding file to rewrite is *not* hardcoded to `context/binding.yml` — it's read from the
  * copied `profile.yml`'s own `context: project: <path>` pointer (the documented Warble mechanism:
  * "profile mounts context via `context: project: <path-to-binding.yml>`"), so this works for any
- * profile following that shape, not just `genbi-default`. The resolved binding path is confined to
- * the composed directory: a `../`-laden pointer that escapes it is a loud {@link PathTraversalError}
- * (reusing the exec module's shared traversal error rather than reading/overwriting an arbitrary
- * host file).
+ * profile following that shape, not just `genbi-default`. Both the binding path and the resolved
+ * document path are confined to the composed directory: a `../`-laden pointer that escapes it is a
+ * loud {@link PathTraversalError} (reusing the exec module's shared traversal error rather than
+ * reading/overwriting an arbitrary host file).
  *
- * Both `profile.yml` and the binding file are small, flat YAML where only a single scalar matters
- * here — regex extraction/rewrite is used deliberately instead of pulling in a full YAML parser
- * dependency for that. Both the pointer lookup and the `project:` rewrite assert *exactly one*
- * match and loud-fail on zero or multiple (a duplicate top-level `project:` would otherwise leave a
- * stale line that last-key-wins YAML parsing could silently bind to the wrong project). If a Warble
- * profile ever grows a more elaborate `context:` block (e.g. multiple context sources), this needs
- * revisiting.
+ * Both `profile.yml` and the binding file are small, flat YAML where only a few scalars matter here
+ * — regex extraction/rewrite is used deliberately instead of pulling in a full YAML parser
+ * dependency for that. Every lookup asserts *exactly one* match and loud-fails on zero or multiple
+ * (a duplicate top-level `project:` would otherwise leave a stale line that last-key-wins YAML
+ * parsing could silently bind to the wrong project). If a Warble profile ever grows a more
+ * elaborate `context:` block (e.g. multiple context sources), this needs revisiting.
  */
 export async function composeUserProfile(options) {
     const profileSourceAbs = path.resolve(options.profileSource);
@@ -33,21 +50,26 @@ export async function composeUserProfile(options) {
     const bindingRelPath = extractContextBindingPath(profileYamlText, profileYamlPath);
     const bindingPath = resolveWithinComposedDir(composedDir, bindingRelPath);
     const bindingText = await readFile(bindingPath, "utf-8");
+    assertPreparedBindingKind(bindingText, bindingPath);
+    const documentRelPath = extractBindingDocumentPath(bindingText, bindingPath);
+    const documentPath = resolveWithinComposedDir(composedDir, documentRelPath);
+    await mkdir(path.dirname(documentPath), { recursive: true });
+    await generatePreparedContext(options.contextLoaderBin, userProjectAbs, documentPath);
     const rewritten = rewriteContextBindingProject(bindingText, userProjectAbs, bindingPath);
     await writeFile(bindingPath, rewritten, "utf-8");
     return composedDir;
 }
 /**
- * Resolves `bindingRelPath` against `composedDir` and rejects anything that escapes it. Mirrors the
+ * Resolves `relPath` against `composedDir` and rejects anything that escapes it. Mirrors the
  * containment check `harness/exec/local.ts`'s (private) `resolveWithinScope` performs, reusing its
  * exported {@link PathTraversalError} — kept as a local check here so the fix stays within this
  * module rather than widening the exec module's public surface.
  */
-function resolveWithinComposedDir(composedDir, bindingRelPath) {
-    const targetAbs = path.resolve(composedDir, bindingRelPath);
+function resolveWithinComposedDir(composedDir, relPath) {
+    const targetAbs = path.resolve(composedDir, relPath);
     const relative = path.relative(composedDir, targetAbs);
     if (relative.startsWith("..") || path.isAbsolute(relative)) {
-        throw new PathTraversalError(bindingRelPath, composedDir);
+        throw new PathTraversalError(relPath, composedDir);
     }
     return targetAbs;
 }
@@ -71,6 +93,50 @@ export function extractContextBindingPath(profileYamlText, sourcePath) {
     }
     return unquoted;
 }
+/**
+ * Asserts the binding declares exactly one top-level `kind: prepared`.
+ *
+ * A **missing** `kind:` is rejected rather than tolerated. Omitting it selects Warble's serde
+ * default (`wren_project`), i.e. Warble's own built-in MDL adapter — so a binding without the line
+ * would compile perfectly well while quietly ignoring the document this function's caller just
+ * generated. Since Warble emits neither `kind` nor `document` into the IR, that divergence is
+ * invisible in the compiled artifact; the only place it can be caught is here.
+ */
+export function assertPreparedBindingKind(bindingText, sourcePath) {
+    const matches = [...bindingText.matchAll(/^kind:[ \t]*(\S+)[ \t]*$/gm)];
+    if (matches.length === 0) {
+        throw new InvalidProfileShapeError(`"${sourcePath}" declares no top-level "kind:" — a context binding rebound to a user project must ` +
+            `declare "kind: prepared" (omitting it selects Warble's built-in "wren_project" adapter, which ` +
+            `would silently ignore the generated prepared-context document)`);
+    }
+    if (matches.length > 1) {
+        throw new InvalidProfileShapeError(`"${sourcePath}" has ${matches.length} top-level "kind:" fields — expected exactly one (ambiguous binding)`);
+    }
+    const kind = stripSurroundingQuotes(matches[0]?.[1] ?? "");
+    if (kind !== "prepared") {
+        throw new InvalidProfileShapeError(`"${sourcePath}" declares "kind: ${kind}" — a context binding rebound to a user project must declare ` +
+            `"kind: prepared"`);
+    }
+}
+/**
+ * Extracts the single top-level `document: <path>` field naming where the prepared-context document
+ * lives, relative to the Warble project root (NOT to the binding file's own directory).
+ */
+export function extractBindingDocumentPath(bindingText, sourcePath) {
+    const matches = [...bindingText.matchAll(/^document:[ \t]*(\S+)[ \t]*$/gm)];
+    if (matches.length === 0) {
+        throw new InvalidProfileShapeError(`"${sourcePath}" has no top-level "document:" field — a "kind: prepared" binding must name the ` +
+            `prepared-context document it reads`);
+    }
+    if (matches.length > 1) {
+        throw new InvalidProfileShapeError(`"${sourcePath}" has ${matches.length} top-level "document:" fields — expected exactly one (ambiguous binding)`);
+    }
+    const unquoted = stripSurroundingQuotes(matches[0]?.[1] ?? "");
+    if (unquoted.length === 0) {
+        throw new InvalidProfileShapeError(`"${sourcePath}" has an empty "document:" field`);
+    }
+    return unquoted;
+}
 /**
  * Replaces the single top-level `project:` line in a context-binding YAML's text, preserving
  * surrounding comments. Asserts exactly one top-level `project:` — a second one would survive the

package/dist-server/harness/compile/context-loader.d.ts

@@ -0,0 +1,56 @@
+export interface ResolvedContextLoader {
+    readonly bin: string;
+    readonly kind: "explicit" | "in-repo" | "package";
+    /** Package resolution is already digest-verified. Development modes use the binary hash below. */
+    readonly verifiedIdentity?: string;
+}
+/**
+ * Resolves the `wren-context-loader` binary — the generator that renders a wren project as the
+ * prepared-context document a `kind: prepared` binding reads.
+ *
+ * Three deterministic tiers, then a loud failure:
+ *
+ * 1. `explicit`, else the `WREN_HARNESS_CONTEXT_LOADER_BIN` environment variable. Either must
+ *    exist on disk; neither falls through to a search.
+ * 2. This repo's own build of the generator crate, found by walking up from this package looking
+ *    for `core/wren-context-loader/target/{release,debug}/wren-context-loader`. `release` wins
+ *    when both exist, so a stale `debug` build never shadows a deliberate release build.
+ * 3. The verified package-local binary from the exact `@wrenai/context-loader` dependency. Its
+ *    install record must match package version and target, name the canonical binary, and pass a
+ *    fresh SHA-256 check. Resolution never downloads at runtime.
+ *
+ * There is deliberately **no** `PATH` tier and — more importantly — **no fallback to the old
+ * `wren_project` binding**. A fallback would make the extraction unverifiable: a compiled IR is
+ * byte-identical whichever path produced it (Warble emits neither `kind` nor `document` into the
+ * IR), so a silent degrade would be undetectable from the artifact alone. Failing loudly is the
+ * only way the caller can know which path ran.
+ *
+ * Throws {@link ContextLoaderNotFoundError} with the accumulated attempts when neither tier works.
+ */
+export declare function resolveContextLoader(explicit?: string): ResolvedContextLoader;
+/** Backward-compatible path-only API for callers that do not need cache provenance. */
+export declare function resolveContextLoaderBinary(explicit?: string): string;
+/** Stable cache identity: resolver kind plus either a verified package tuple or the dev binary's bytes. */
+export declare function getContextLoaderIdentity(resolved: ResolvedContextLoader): string;
+/** Validates a package-local installation record without resolving it from the host environment. */
+export declare function readVerifiedContextLoaderPackage(packageRoot: string, target?: string): ResolvedContextLoader | undefined;
+/**
+ * Runs the generator over `projectDir`, writing the prepared-context document to `outPath`.
+ *
+ * An *unreadable* project is not an error here: the generator writes `parseable: false` with the
+ * assembly error attached and exits 0, because "this layer could not be assembled" is a fact about
+ * the project that Warble's `mdl_parseable` precondition exists to report. Only a genuinely
+ * unusable invocation (a path that is not a directory, an unwritable output) exits non-zero, and
+ * that surfaces as {@link ContextLoaderFailedError}.
+ *
+ * Shells with `execFile` (argv array, no shell interpolation), matching the convention `runWarble`
+ * and `harness/exec/local.ts` already use.
+ */
+export declare function generatePreparedContext(bin: string, projectDir: string, outPath: string, signal?: AbortSignal): Promise<void>;
+/**
+ * Runs the generator over `projectDir` writing both the prepared-context document (`outPath`) and
+ * the **capability catalog** (`catalogPath`): the authored, descriptive, SQL-free slice of the
+ * project that `buildCapabilityCard` renders for a planner outside the data zone. One process,
+ * one read of the project, so the two documents can never describe different states of it.
+ */
+export declare function generatePreparedContextAndCatalog(bin: string, projectDir: string, outPath: string, catalogPath: string, signal?: AbortSignal): Promise<void>;

package/dist-server/harness/compile/context-loader.js

@@ -0,0 +1,237 @@
+import { execFile } from "node:child_process";
+import { existsSync, lstatSync, readFileSync, realpathSync, statSync } from "node:fs";
+import { createHash } from "node:crypto";
+import { fileURLToPath } from "node:url";
+import path from "node:path";
+import { ContextLoaderFailedError, ContextLoaderNotFoundError } from "./errors.js";
+import { resolveInstalledPackageRoot } from "../npm-package-resolve.js";
+/** Environment override for {@link resolveContextLoaderBinary}, named like the other `WREN_HARNESS_*` binary overrides. */
+const CONTEXT_LOADER_BIN_ENV = "WREN_HARNESS_CONTEXT_LOADER_BIN";
+/** The generator's crate-relative build outputs, most-preferred first. */
+const IN_REPO_BUILD_PATHS = [
+    ["core", "wren-context-loader", "target", "release", "wren-context-loader"],
+    ["core", "wren-context-loader", "target", "debug", "wren-context-loader"],
+];
+/**
+ * A generous ceiling for a step that reads a semantic layer off local disk and writes one JSON
+ * document — guards against a hang, not meant to ever fire in normal operation.
+ */
+const CONTEXT_LOADER_TIMEOUT_MS = 60 * 1000;
+const CONTEXT_LOADER_PACKAGE = "@wrenai/context-loader";
+const CANONICAL_PACKAGE_BINARY = path.join("bin", "wren-context-loader");
+/**
+ * Resolves the `wren-context-loader` binary — the generator that renders a wren project as the
+ * prepared-context document a `kind: prepared` binding reads.
+ *
+ * Three deterministic tiers, then a loud failure:
+ *
+ * 1. `explicit`, else the `WREN_HARNESS_CONTEXT_LOADER_BIN` environment variable. Either must
+ *    exist on disk; neither falls through to a search.
+ * 2. This repo's own build of the generator crate, found by walking up from this package looking
+ *    for `core/wren-context-loader/target/{release,debug}/wren-context-loader`. `release` wins
+ *    when both exist, so a stale `debug` build never shadows a deliberate release build.
+ * 3. The verified package-local binary from the exact `@wrenai/context-loader` dependency. Its
+ *    install record must match package version and target, name the canonical binary, and pass a
+ *    fresh SHA-256 check. Resolution never downloads at runtime.
+ *
+ * There is deliberately **no** `PATH` tier and — more importantly — **no fallback to the old
+ * `wren_project` binding**. A fallback would make the extraction unverifiable: a compiled IR is
+ * byte-identical whichever path produced it (Warble emits neither `kind` nor `document` into the
+ * IR), so a silent degrade would be undetectable from the artifact alone. Failing loudly is the
+ * only way the caller can know which path ran.
+ *
+ * Throws {@link ContextLoaderNotFoundError} with the accumulated attempts when neither tier works.
+ */
+export function resolveContextLoader(explicit) {
+    const override = explicit ?? process.env[CONTEXT_LOADER_BIN_ENV];
+    if (override !== undefined && override.length > 0) {
+        if (!existsSync(override)) {
+            const source = explicit !== undefined ? `explicit contextLoaderBin` : CONTEXT_LOADER_BIN_ENV;
+            throw new ContextLoaderNotFoundError([`${source} "${override}" does not exist`]);
+        }
+        return { bin: override, kind: "explicit" };
+    }
+    const inRepo = findInRepoBuild();
+    if (inRepo !== undefined)
+        return { bin: inRepo, kind: "in-repo" };
+    const packaged = resolveVerifiedPackageBinary();
+    if (packaged !== undefined)
+        return packaged;
+    throw new ContextLoaderNotFoundError([
+        `${CONTEXT_LOADER_BIN_ENV} is not set`,
+        `no in-repo build found (searched ancestors of this package for ` +
+            IN_REPO_BUILD_PATHS.map((segments) => `"${path.join(...segments)}"`).join(" and ") +
+            `) — ${CONTEXT_LOADER_PACKAGE} is not installed with a verified ${targetForCurrentPlatform()} binary`,
+    ]);
+}
+/** Backward-compatible path-only API for callers that do not need cache provenance. */
+export function resolveContextLoaderBinary(explicit) {
+    return resolveContextLoader(explicit).bin;
+}
+/** Stable cache identity: resolver kind plus either a verified package tuple or the dev binary's bytes. */
+export function getContextLoaderIdentity(resolved) {
+    if (resolved.verifiedIdentity !== undefined)
+        return resolved.verifiedIdentity;
+    return `${resolved.kind}:${createHash("sha256").update(readFileSync(resolved.bin)).digest("hex")}`;
+}
+function resolveVerifiedPackageBinary() {
+    const packageRoot = resolveInstalledPackageRoot(CONTEXT_LOADER_PACKAGE);
+    if (packageRoot === undefined)
+        return undefined;
+    return readVerifiedContextLoaderPackage(packageRoot);
+}
+/** Validates a package-local installation record without resolving it from the host environment. */
+export function readVerifiedContextLoaderPackage(packageRoot, target = targetForCurrentPlatform()) {
+    try {
+        const root = physicalPackageRoot(packageRoot);
+        if (root === undefined)
+            return undefined;
+        const packageJson = readVerifiedJson(root, "package.json");
+        const manifest = readVerifiedJson(root, "artifacts.json");
+        const state = readVerifiedJson(root, "install-state.json");
+        if (packageJson === undefined || manifest === undefined || state === undefined)
+            return undefined;
+        const artifacts = typeof manifest.artifacts === "object" && manifest.artifacts !== null ? manifest.artifacts : undefined;
+        const artifact = artifacts?.[target];
+        const bin = physicalRegularFile(root, CANONICAL_PACKAGE_BINARY);
+        if (packageJson.name !== CONTEXT_LOADER_PACKAGE ||
+            typeof packageJson.version !== "string" ||
+            manifest.schema !== 1 ||
+            manifest.package !== CONTEXT_LOADER_PACKAGE ||
+            manifest.version !== packageJson.version ||
+            !isArtifact(artifact) ||
+            state.package !== CONTEXT_LOADER_PACKAGE ||
+            state.version !== packageJson.version ||
+            state.target !== target ||
+            state.binaryPath !== CANONICAL_PACKAGE_BINARY ||
+            state.archiveSha256 !== artifact.archiveSha256 ||
+            state.binarySha256 !== artifact.binarySha256 ||
+            bin === undefined ||
+            createHash("sha256").update(readFileSync(bin)).digest("hex") !== artifact.binarySha256) {
+            return undefined;
+        }
+        return { bin, kind: "package", verifiedIdentity: `package:${CONTEXT_LOADER_PACKAGE}@${packageJson.version}:${target}:${artifact.binarySha256}` };
+    }
+    catch {
+        return undefined;
+    }
+}
+function readVerifiedJson(root, relativePath) {
+    const file = physicalRegularFile(root, relativePath);
+    if (file === undefined)
+        return undefined;
+    try {
+        const value = JSON.parse(readFileSync(file, "utf8"));
+        return typeof value === "object" && value !== null ? value : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function isSha256(value) {
+    return typeof value === "string" && /^[a-f0-9]{64}$/u.test(value);
+}
+function isArtifact(value) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    const artifact = value;
+    return (typeof artifact.url === "string" &&
+        artifact.url.startsWith("https://") &&
+        isSha256(artifact.archiveSha256) &&
+        isSha256(artifact.binarySha256) &&
+        typeof artifact.binaryPath === "string" &&
+        !artifact.binaryPath.includes("..") &&
+        !path.isAbsolute(artifact.binaryPath));
+}
+/** Returns a package-owned physical root; package-root symlinks are never trusted. */
+function physicalPackageRoot(packageRoot) {
+    try {
+        if (!lstatSync(packageRoot).isDirectory())
+            return undefined;
+        return realpathSync(packageRoot);
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Refuses final-file links and any ancestor link that resolves outside the physical package root. */
+function physicalRegularFile(root, relativePath) {
+    const lexical = path.resolve(root, relativePath);
+    if (!lexical.startsWith(`${root}${path.sep}`))
+        return undefined;
+    try {
+        if (!lstatSync(lexical).isFile())
+            return undefined;
+        const physical = realpathSync(lexical);
+        return physical.startsWith(`${root}${path.sep}`) && statSync(physical).isFile() ? physical : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function targetForCurrentPlatform() {
+    return `${process.platform}-${process.arch}`;
+}
+/**
+ * Walks up from this package's own directory (`harness/compile/` in source, `dist/compile/` once
+ * built — either way two levels below the package root), returning the first existing generator
+ * build. Mirrors the ancestor walk `resolveWarbleBinary`'s sibling-checkout tier uses, so this
+ * works from the main checkout or from a git worktree nested several levels under it.
+ */
+function findInRepoBuild() {
+    let dir = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "..");
+    const maxDepth = 10;
+    for (let i = 0; i < maxDepth; i += 1) {
+        for (const segments of IN_REPO_BUILD_PATHS) {
+            const candidate = path.join(dir, ...segments);
+            if (existsSync(candidate))
+                return candidate;
+        }
+        const parent = path.dirname(dir);
+        if (parent === dir)
+            break; // reached filesystem root
+        dir = parent;
+    }
+    return undefined;
+}
+/**
+ * Runs the generator over `projectDir`, writing the prepared-context document to `outPath`.
+ *
+ * An *unreadable* project is not an error here: the generator writes `parseable: false` with the
+ * assembly error attached and exits 0, because "this layer could not be assembled" is a fact about
+ * the project that Warble's `mdl_parseable` precondition exists to report. Only a genuinely
+ * unusable invocation (a path that is not a directory, an unwritable output) exits non-zero, and
+ * that surfaces as {@link ContextLoaderFailedError}.
+ *
+ * Shells with `execFile` (argv array, no shell interpolation), matching the convention `runWarble`
+ * and `harness/exec/local.ts` already use.
+ */
+export function generatePreparedContext(bin, projectDir, outPath, signal) {
+    return runContextLoader(bin, [projectDir, "-o", outPath], signal);
+}
+/**
+ * Runs the generator over `projectDir` writing both the prepared-context document (`outPath`) and
+ * the **capability catalog** (`catalogPath`): the authored, descriptive, SQL-free slice of the
+ * project that `buildCapabilityCard` renders for a planner outside the data zone. One process,
+ * one read of the project, so the two documents can never describe different states of it.
+ */
+export function generatePreparedContextAndCatalog(bin, projectDir, outPath, catalogPath, signal) {
+    return runContextLoader(bin, [projectDir, "-o", outPath, "--catalog-out", catalogPath], signal);
+}
+function runContextLoader(bin, args, signal) {
+    return new Promise((resolve, reject) => {
+        execFile(bin, args, { maxBuffer: 32 * 1024 * 1024, timeout: CONTEXT_LOADER_TIMEOUT_MS, ...(signal ? { signal } : {}) }, (error, stdout, stderr) => {
+            if (error) {
+                const exitCode = typeof error.code === "number" ? error.code : 1;
+                const clarifiedStderr = stderr.length > 0
+                    ? stderr
+                    : error.killed === true
+                        ? `wren-context-loader timed out after ${CONTEXT_LOADER_TIMEOUT_MS}ms`
+                        : stderr;
+                reject(new ContextLoaderFailedError(bin, args, exitCode, clarifiedStderr, stdout));
+                return;
+            }
+            resolve();
+        });
+    });
+}

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

@@ -16,6 +16,25 @@ export declare class WarbleCommandFailedError extends Error {
     readonly stdout: string;
     constructor(command: string, args: readonly string[], exitCode: number, stderr: string, stdout?: string);
 }
+/**
+ * Thrown by {@link resolveContextLoaderBinary} (see `./context-loader.js`) when the
+ * `wren-context-loader` generator can be found neither via an explicit override nor as an in-repo
+ * build. Deliberately loud, and deliberately *not* recoverable by falling back to the old
+ * `wren_project` binding: Warble emits neither `kind` nor `document` into the IR, so a silent
+ * degrade to the built-in MDL adapter would be invisible in the compiled artifact.
+ */
+export declare class ContextLoaderNotFoundError extends Error {
+    constructor(attempts: readonly string[]);
+}
+/** Thrown when the `wren-context-loader` subprocess exits non-zero. */
+export declare class ContextLoaderFailedError extends Error {
+    readonly command: string;
+    readonly args: readonly string[];
+    readonly exitCode: number;
+    readonly stderr: string;
+    readonly stdout: string;
+    constructor(command: string, args: readonly string[], exitCode: number, stderr: string, stdout?: string);
+}
 /** Thrown when a Warble profile directory doesn't have the expected `profile.yml` / context-binding shape. */
 export declare class InvalidProfileShapeError extends Error {
     constructor(message: string);

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

@@ -32,6 +32,41 @@ export class WarbleCommandFailedError extends Error {
         this.name = "WarbleCommandFailedError";
     }
 }
+/**
+ * Thrown by {@link resolveContextLoaderBinary} (see `./context-loader.js`) when the
+ * `wren-context-loader` generator can be found neither via an explicit override nor as an in-repo
+ * build. Deliberately loud, and deliberately *not* recoverable by falling back to the old
+ * `wren_project` binding: Warble emits neither `kind` nor `document` into the IR, so a silent
+ * degrade to the built-in MDL adapter would be invisible in the compiled artifact.
+ */
+export class ContextLoaderNotFoundError extends Error {
+    constructor(attempts) {
+        super(`could not resolve the "wren-context-loader" binary:\n` +
+            attempts.map((attempt) => `  - ${attempt}`).join("\n") +
+            `\nfix: install the exact @wrenai/context-loader package, build it in-repo from the repository root ` +
+            `("cargo build --release --manifest-path core/wren-context-loader/Cargo.toml") ` +
+            `or point WREN_HARNESS_CONTEXT_LOADER_BIN at an existing build.`);
+        this.name = "ContextLoaderNotFoundError";
+    }
+}
+/** Thrown when the `wren-context-loader` subprocess exits non-zero. */
+export class ContextLoaderFailedError extends Error {
+    command;
+    args;
+    exitCode;
+    stderr;
+    stdout;
+    constructor(command, args, exitCode, stderr, stdout = "") {
+        const diagnostics = [stderr.trim(), stdout.trim()].filter((chunk) => chunk.length > 0).join("\n");
+        super(`"${command} ${args.join(" ")}" exited ${exitCode}:\n${diagnostics || "(no output)"}`);
+        this.command = command;
+        this.args = args;
+        this.exitCode = exitCode;
+        this.stderr = stderr;
+        this.stdout = stdout;
+        this.name = "ContextLoaderFailedError";
+    }
+}
 /** Thrown when a Warble profile directory doesn't have the expected `profile.yml` / context-binding shape. */
 export class InvalidProfileShapeError extends Error {
     constructor(message) {

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

@@ -1,8 +1,9 @@
 export { createFileSystemCompileCache, createInMemoryCompileCache, resolveDefaultCacheDir } from "./cache.js";
-export { composeUserProfile, extractContextBindingPath, rewriteContextBindingProject } from "./compose-profile.js";
-export { InvalidProfileShapeError, WarbleBinaryNotFoundError, WarbleCommandFailedError, } from "./errors.js";
+export { assertPreparedBindingKind, composeUserProfile, extractBindingDocumentPath, extractContextBindingPath, rewriteContextBindingProject, } from "./compose-profile.js";
+export { generatePreparedContext, generatePreparedContextAndCatalog, resolveContextLoaderBinary } from "./context-loader.js";
+export { ContextLoaderFailedError, ContextLoaderNotFoundError, InvalidProfileShapeError, WarbleBinaryNotFoundError, WarbleCommandFailedError, } from "./errors.js";
 export { hashDirectory, hashFiles } from "./fingerprint.js";
 export { compileProfile, compileRawProfile, runWarble } from "./pipeline.js";
 export { resolveHubDir, resolveWarbleBinary } from "./resolve-binary.js";
 export type { CompileCache, CompileCacheEntry, CompileCacheKey, CompileMode, CompileProfileOptions, CompileProfileResult, CompileRawProfileOptions, } from "./types.js";
-export { getWarbleIdentity } from "./warble-identity.js";
+export { getBinaryIdentity, getWarbleIdentity } from "./warble-identity.js";

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

@@ -1,7 +1,8 @@
 export { createFileSystemCompileCache, createInMemoryCompileCache, resolveDefaultCacheDir } from "./cache.js";
-export { composeUserProfile, extractContextBindingPath, rewriteContextBindingProject } from "./compose-profile.js";
-export { InvalidProfileShapeError, WarbleBinaryNotFoundError, WarbleCommandFailedError, } from "./errors.js";
+export { assertPreparedBindingKind, composeUserProfile, extractBindingDocumentPath, extractContextBindingPath, rewriteContextBindingProject, } from "./compose-profile.js";
+export { generatePreparedContext, generatePreparedContextAndCatalog, resolveContextLoaderBinary } from "./context-loader.js";
+export { ContextLoaderFailedError, ContextLoaderNotFoundError, InvalidProfileShapeError, WarbleBinaryNotFoundError, WarbleCommandFailedError, } from "./errors.js";
 export { hashDirectory, hashFiles } from "./fingerprint.js";
 export { compileProfile, compileRawProfile, runWarble } from "./pipeline.js";
 export { resolveHubDir, resolveWarbleBinary } from "./resolve-binary.js";
-export { getWarbleIdentity } from "./warble-identity.js";
+export { getBinaryIdentity, getWarbleIdentity } from "./warble-identity.js";

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

@@ -12,6 +12,13 @@ export declare const DEFAULT_WREN_PROVIDER_PATH: string;
  * mode — additionally `warble dispatch --target vercel` for the vercel bundle this package's
  * `runAgent()` consumes.
  *
+ * The rebind runs WrenAI's own `wren-context-loader` generator over `userProject` and binds its
+ * output as a `kind: prepared` document, so Warble reads a projection WrenAI produced rather than
+ * introspecting the semantic layer itself. Resolving that generator loud-fails
+ * ({@link ContextLoaderNotFoundError}) — there is no fallback to Warble's built-in `wren_project`
+ * adapter, because the compiled IR is byte-identical either way and a silent degrade would be
+ * undetectable from the artifact.
+ *
  * 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
@@ -26,13 +33,14 @@ export declare const DEFAULT_WREN_PROVIDER_PATH: string;
  * 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.
+ * provider-fragment content hash x warble binary identity x `wren-context-loader` binary identity x
+ * resolved Hub root) — see `./cache.js` — so an unchanged profile/context/providers/compiler/
+ * generator/Hub tuple returns the previous artifact instead of recompiling. Folding in the
+ * provider-fragment hash, warble identity, generator 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`, rebuilding
+ * the generator, 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