@wrenai/genbi 0.0.1

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

@@ -0,0 +1,23 @@
+import type { CompileCache } from "./types.js";
+/**
+ * The default cache root, rooted under the *current user's* home rather than a world-shared
+ * fixed path like `os.tmpdir()` — on a multi-user host, a predictable shared tmpdir path lets
+ * another local account pre-create the dir and plant a slot for a computable cache key.
+ * Respects `XDG_CACHE_HOME` when set, matching the XDG base-dir convention.
+ */
+export declare function resolveDefaultCacheDir(): string;
+/**
+ * The v1 {@link CompileCache} backend: one subdirectory per cache key under `cacheDir`, each
+ * holding a copy of `ir.json` and (in-process only) `bundle/bundle.json`. `get` treats a slot whose
+ * `ir.json` has since been deleted as a miss rather than throwing, so an external cleanup of
+ * `cacheDir` degrades to "just recompile" instead of a hard failure.
+ *
+ * No TTL/eviction and no crash-consistency guarantee on `set` (a process killed mid-copy can leave
+ * a partial slot that a later `get` may treat as a hit) — both are deferred; simple/documented per
+ * the task's scope guidance rather than a production-grade cache.
+ */
+export declare function createFileSystemCompileCache(options?: {
+    readonly cacheDir?: string;
+}): CompileCache;
+/** A non-persistent {@link CompileCache} for tests/short-lived processes — no filesystem I/O. */
+export declare function createInMemoryCompileCache(): CompileCache;

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

@@ -0,0 +1,109 @@
+import { createHash } from "node:crypto";
+import { chmodSync, existsSync, mkdirSync } from "node:fs";
+import { cp, mkdir, stat } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+/**
+ * Deterministic on-disk slot name for a cache key — order-independent, one directory per (profile,
+ * context, mode, provider-fragment-hash, warble-identity, hub-dir). An absent `hubDir` (no
+ * `--hub-dir` passed, so warble's compiled-in default applied) hashes as the empty string, which is
+ * a distinct value from any real root rather than an alias for one.
+ */
+function keyDigest(key) {
+    return createHash("sha256")
+        .update(`${key.profileHash}:${key.contextFingerprint}:${key.mode}:${key.providerFragmentHash}:${key.warbleIdentity}:${key.hubDir ?? ""}`)
+        .digest("hex");
+}
+/**
+ * The default cache root, rooted under the *current user's* home rather than a world-shared
+ * fixed path like `os.tmpdir()` — on a multi-user host, a predictable shared tmpdir path lets
+ * another local account pre-create the dir and plant a slot for a computable cache key.
+ * Respects `XDG_CACHE_HOME` when set, matching the XDG base-dir convention.
+ */
+export function resolveDefaultCacheDir() {
+    const xdgCacheHome = process.env.XDG_CACHE_HOME;
+    const base = xdgCacheHome !== undefined && xdgCacheHome.trim().length > 0 ? xdgCacheHome : path.join(os.homedir(), ".cache");
+    return path.join(base, "wren-harness", "compile");
+}
+/**
+ * Creates the default cache dir (if missing) restricted to the owner (`0700`) so another local
+ * account can't read or even traverse into it. `mkdirSync`'s `mode` is subject to the process
+ * umask, so `chmodSync` afterwards guarantees `0700` regardless of umask or a looser pre-existing
+ * mode. Only applied to the *default* dir — an explicit `cacheDir` override is left exactly as
+ * the caller passed it (see `createFileSystemCompileCache`).
+ */
+function createSecureDefaultCacheDir() {
+    const dir = resolveDefaultCacheDir();
+    mkdirSync(dir, { recursive: true, mode: 0o700 });
+    if (process.platform !== "win32") {
+        chmodSync(dir, 0o700);
+    }
+    return dir;
+}
+/**
+ * Defense in depth against a planted slot (see `resolveDefaultCacheDir`'s doc comment above): if a slot directory exists but isn't
+ * owned by the current process's uid, treat it as untrustworthy and miss rather than trusting its
+ * contents. A slot that doesn't exist at all (the common miss case) is NOT a security decision —
+ * `stat` failing for any reason falls through to `true` so the normal `existsSync(irPath)` miss
+ * path below still runs. Windows has no POSIX uid model, so this is skipped there.
+ */
+async function isOwnedByCurrentUser(slot) {
+    if (process.platform === "win32")
+        return true;
+    const uid = process.getuid?.();
+    if (uid === undefined)
+        return true;
+    try {
+        const stats = await stat(slot);
+        return stats.uid === uid;
+    }
+    catch {
+        return true;
+    }
+}
+/**
+ * The v1 {@link CompileCache} backend: one subdirectory per cache key under `cacheDir`, each
+ * holding a copy of `ir.json` and (in-process only) `bundle/bundle.json`. `get` treats a slot whose
+ * `ir.json` has since been deleted as a miss rather than throwing, so an external cleanup of
+ * `cacheDir` degrades to "just recompile" instead of a hard failure.
+ *
+ * No TTL/eviction and no crash-consistency guarantee on `set` (a process killed mid-copy can leave
+ * a partial slot that a later `get` may treat as a hit) — both are deferred; simple/documented per
+ * the task's scope guidance rather than a production-grade cache.
+ */
+export function createFileSystemCompileCache(options) {
+    const cacheDir = options?.cacheDir ?? createSecureDefaultCacheDir();
+    return {
+        async get(key) {
+            const slot = path.join(cacheDir, keyDigest(key));
+            if (!(await isOwnedByCurrentUser(slot)))
+                return undefined;
+            const irPath = path.join(slot, "ir.json");
+            if (!existsSync(irPath))
+                return undefined;
+            const bundlePath = path.join(slot, "bundle", "bundle.json");
+            return { irPath, ...(existsSync(bundlePath) ? { bundlePath } : {}) };
+        },
+        async set(key, entry) {
+            const slot = path.join(cacheDir, keyDigest(key));
+            await mkdir(slot, { recursive: true });
+            await cp(entry.irPath, path.join(slot, "ir.json"));
+            if (entry.bundlePath !== undefined) {
+                await mkdir(path.join(slot, "bundle"), { recursive: true });
+                await cp(entry.bundlePath, path.join(slot, "bundle", "bundle.json"));
+            }
+        },
+    };
+}
+/** A non-persistent {@link CompileCache} for tests/short-lived processes — no filesystem I/O. */
+export function createInMemoryCompileCache() {
+    const store = new Map();
+    return {
+        async get(key) {
+            return store.get(keyDigest(key));
+        },
+        async set(key, entry) {
+            store.set(keyDigest(key), entry);
+        },
+    };
+}

package/dist-server/harness/compile/compose-profile.d.ts

@@ -0,0 +1,34 @@
+/**
+ * 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`).
+ *
+ * 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).
+ *
+ * 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.
+ */
+export declare function composeUserProfile(options: {
+    readonly profileSource: string;
+    readonly userProject: string;
+    readonly destDir: string;
+}): Promise<string>;
+/** Extracts the single `context: project: <path>` pointer from a profile.yml's text. */
+export declare function extractContextBindingPath(profileYamlText: string, sourcePath: string): string;
+/**
+ * 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
+ * rewrite as a stale line and could win under last-key-wins YAML parsing (silent misbind).
+ */
+export declare function rewriteContextBindingProject(bindingText: string, newProjectPath: string, sourcePath: string): string;

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

@@ -0,0 +1,95 @@
+import { cp, readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { PathTraversalError } from "../exec/index.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`).
+ *
+ * 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).
+ *
+ * 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.
+ */
+export async function composeUserProfile(options) {
+    const profileSourceAbs = path.resolve(options.profileSource);
+    const userProjectAbs = path.resolve(options.userProject);
+    const composedDir = path.join(options.destDir, "profile");
+    await cp(profileSourceAbs, composedDir, { recursive: true });
+    const profileYamlPath = path.join(composedDir, "profile.yml");
+    const profileYamlText = await readFile(profileYamlPath, "utf-8");
+    const bindingRelPath = extractContextBindingPath(profileYamlText, profileYamlPath);
+    const bindingPath = resolveWithinComposedDir(composedDir, bindingRelPath);
+    const bindingText = await readFile(bindingPath, "utf-8");
+    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
+ * 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);
+    const relative = path.relative(composedDir, targetAbs);
+    if (relative.startsWith("..") || path.isAbsolute(relative)) {
+        throw new PathTraversalError(bindingRelPath, composedDir);
+    }
+    return targetAbs;
+}
+/** Extracts the single `context: project: <path>` pointer from a profile.yml's text. */
+export function extractContextBindingPath(profileYamlText, sourcePath) {
+    const pattern = /^context:[ \t]*\r?\n[ \t]+project:[ \t]*(\S+)[ \t]*$/gm;
+    const matches = [...profileYamlText.matchAll(pattern)];
+    if (matches.length === 0) {
+        throw new InvalidProfileShapeError(`"${sourcePath}" has no "context:\\n  project: <path>" block — cannot locate its context binding file`);
+    }
+    if (matches.length > 1) {
+        throw new InvalidProfileShapeError(`"${sourcePath}" has ${matches.length} "context:\\n  project:" blocks — expected exactly one`);
+    }
+    const captured = matches[0]?.[1];
+    if (captured === undefined) {
+        throw new InvalidProfileShapeError(`"${sourcePath}" has a malformed "context: project:" pointer`);
+    }
+    const unquoted = stripSurroundingQuotes(captured);
+    if (unquoted.length === 0) {
+        throw new InvalidProfileShapeError(`"${sourcePath}" has an empty "context: project:" pointer`);
+    }
+    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
+ * rewrite as a stale line and could win under last-key-wins YAML parsing (silent misbind).
+ */
+export function rewriteContextBindingProject(bindingText, newProjectPath, sourcePath) {
+    const pattern = /^project:[ \t]*.*$/gm;
+    const matches = [...bindingText.matchAll(pattern)];
+    if (matches.length === 0) {
+        throw new InvalidProfileShapeError(`"${sourcePath}" has no top-level "project:" field to rewrite`);
+    }
+    if (matches.length > 1) {
+        throw new InvalidProfileShapeError(`"${sourcePath}" has ${matches.length} top-level "project:" fields — expected exactly one (ambiguous binding)`);
+    }
+    // Function replacement so a project path containing `$` isn't interpreted as a replacement token.
+    return bindingText.replace(/^project:[ \t]*.*$/m, () => `project: ${newProjectPath}`);
+}
+/** Strips a single matching pair of surrounding single/double quotes, if present. */
+function stripSurroundingQuotes(value) {
+    const match = value.match(/^(['"])(.*)\1$/);
+    return match?.[2] ?? value;
+}

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

@@ -0,0 +1,22 @@
+/**
+ * Thrown by {@link resolveWarbleBinary} (see `./resolve-binary.js`) when no `warble` binary can be
+ * found via any of its four resolution tiers (explicit arg, installed `@warble/cli` package,
+ * `PATH`, opt-in sibling repo release build). Deliberately loud — this pipeline never silently
+ * degrades to "skip compiling".
+ */
+export declare class WarbleBinaryNotFoundError extends Error {
+    constructor(attempts: readonly string[]);
+}
+/** Thrown when a `warble` subprocess (compile or dispatch) exits non-zero. */
+export declare class WarbleCommandFailedError 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

@@ -0,0 +1,41 @@
+/**
+ * Thrown by {@link resolveWarbleBinary} (see `./resolve-binary.js`) when no `warble` binary can be
+ * found via any of its four resolution tiers (explicit arg, installed `@warble/cli` package,
+ * `PATH`, opt-in sibling repo release build). Deliberately loud — this pipeline never silently
+ * degrades to "skip compiling".
+ */
+export class WarbleBinaryNotFoundError extends Error {
+    constructor(attempts) {
+        super(`could not resolve a "warble" binary:\n` +
+            attempts.map((attempt) => `  - ${attempt}`).join("\n") +
+            `\nfix: pass "warbleBin" explicitly, run "pnpm install" so "@warble/cli" is installed, or ` +
+            `put "warble" on PATH.`);
+        this.name = "WarbleBinaryNotFoundError";
+    }
+}
+/** Thrown when a `warble` subprocess (compile or dispatch) exits non-zero. */
+export class WarbleCommandFailedError extends Error {
+    command;
+    args;
+    exitCode;
+    stderr;
+    stdout;
+    constructor(command, args, exitCode, stderr, stdout = "") {
+        // warble reports diagnostics on stderr, but capture stdout too so nothing useful is dropped.
+        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 = "WarbleCommandFailedError";
+    }
+}
+/** Thrown when a Warble profile directory doesn't have the expected `profile.yml` / context-binding shape. */
+export class InvalidProfileShapeError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "InvalidProfileShapeError";
+    }
+}

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

@@ -0,0 +1,22 @@
+/**
+ * A content fingerprint for a directory tree: every included file's relative path plus a sha256 of
+ * its *contents*, combined into a single sha256. This is the identity {@link CompileCache} keys on
+ * for both the source profile and the user's wren project.
+ *
+ * Content (not size+mtime) is hashed deliberately: mtimes are unreliable (a fresh `git checkout`
+ * normalizes them) and same-size edits (e.g. a column rename) collide on size — either would yield
+ * a false cache HIT and silently serve a stale bundle, defeating the point of binding each user to
+ * THEIR current semantic layer. Bulk data files are skipped (see {@link EXCLUDED_DATA_SUFFIXES}).
+ * Symlinks are followed (via `stat`, not the `readdir` dirent type) so a symlinked semantic-layer
+ * file is hashed rather than silently skipped; broken symlinks are ignored.
+ */
+export declare function hashDirectory(rootDir: string): Promise<string>;
+/**
+ * A content fingerprint for an ordered list of individual files (e.g. `--provider` fragment
+ * paths) — order-sensitive, since dispatch merges multiple provider fragments and `[a, b]` can
+ * compile to a different artifact than `[b, a]`. Path strings themselves are NOT part of the
+ * hash — only each file's content — so a fragment copied to a different path with identical
+ * bytes doesn't cause an unnecessary cache miss. An empty list hashes deterministically too, so
+ * passing `[]` (no providers) is distinguishable from any non-empty set, including the default.
+ */
+export declare function hashFiles(filePaths: readonly string[]): Promise<string>;

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

@@ -0,0 +1,84 @@
+import { createHash } from "node:crypto";
+import { readFile, readdir, stat } from "node:fs/promises";
+import path from "node:path";
+/** Directories never worth fingerprinting: VCS metadata, package installs, prior compiler output. */
+const IGNORED_DIR_NAMES = new Set([".git", "node_modules", ".warble"]);
+/**
+ * Bulk data files excluded from the fingerprint: their bytes are NOT compiled into the IR/bundle
+ * (the context binding is a *path* to a wren project; row data is read at query time, not compile
+ * time), so a data-only change doesn't invalidate the compiled artifact. Everything that DOES feed
+ * the compiled artifact — profile.yml, components, and the user project's semantic-layer defs
+ * (`wren_project.yml`, `mdl` under `target/`, `cubes.yml`, `relationships.yml`, `instructions.md`,
+ * `models/`, `views/`) — is content-hashed. When in doubt a file is included, not excluded.
+ */
+const EXCLUDED_DATA_SUFFIXES = [".duckdb", ".duckdb.wal", ".wal", ".parquet", ".sqlite", ".db"];
+/**
+ * A content fingerprint for a directory tree: every included file's relative path plus a sha256 of
+ * its *contents*, combined into a single sha256. This is the identity {@link CompileCache} keys on
+ * for both the source profile and the user's wren project.
+ *
+ * Content (not size+mtime) is hashed deliberately: mtimes are unreliable (a fresh `git checkout`
+ * normalizes them) and same-size edits (e.g. a column rename) collide on size — either would yield
+ * a false cache HIT and silently serve a stale bundle, defeating the point of binding each user to
+ * THEIR current semantic layer. Bulk data files are skipped (see {@link EXCLUDED_DATA_SUFFIXES}).
+ * Symlinks are followed (via `stat`, not the `readdir` dirent type) so a symlinked semantic-layer
+ * file is hashed rather than silently skipped; broken symlinks are ignored.
+ */
+export async function hashDirectory(rootDir) {
+    const entries = [];
+    await walk(rootDir, rootDir, entries);
+    entries.sort();
+    const hash = createHash("sha256");
+    for (const entry of entries)
+        hash.update(entry).update("\n");
+    return hash.digest("hex");
+}
+async function walk(rootDir, dir, out) {
+    const dirents = await readdir(dir, { withFileTypes: true });
+    for (const dirent of dirents) {
+        const fullPath = path.join(dir, dirent.name);
+        // `stat` follows symlinks, so a symlink is classified by its target (not skipped the way the
+        // `readdir` dirent's isDirectory()/isFile() would). A broken symlink / TOCTOU race throws → skip.
+        let stats;
+        try {
+            stats = await stat(fullPath);
+        }
+        catch {
+            continue;
+        }
+        if (stats.isDirectory()) {
+            if (IGNORED_DIR_NAMES.has(dirent.name))
+                continue;
+            await walk(rootDir, fullPath, out);
+            continue;
+        }
+        if (!stats.isFile())
+            continue;
+        if (isExcludedDataFile(dirent.name))
+            continue;
+        const content = await readFile(fullPath);
+        const fileHash = createHash("sha256").update(content).digest("hex");
+        const relPath = path.relative(rootDir, fullPath);
+        out.push(`${relPath}:${fileHash}`);
+    }
+}
+function isExcludedDataFile(name) {
+    const lower = name.toLowerCase();
+    return EXCLUDED_DATA_SUFFIXES.some((suffix) => lower.endsWith(suffix));
+}
+/**
+ * A content fingerprint for an ordered list of individual files (e.g. `--provider` fragment
+ * paths) — order-sensitive, since dispatch merges multiple provider fragments and `[a, b]` can
+ * compile to a different artifact than `[b, a]`. Path strings themselves are NOT part of the
+ * hash — only each file's content — so a fragment copied to a different path with identical
+ * bytes doesn't cause an unnecessary cache miss. An empty list hashes deterministically too, so
+ * passing `[]` (no providers) is distinguishable from any non-empty set, including the default.
+ */
+export async function hashFiles(filePaths) {
+    const hash = createHash("sha256");
+    for (const filePath of filePaths) {
+        const content = await readFile(path.resolve(filePath));
+        hash.update(createHash("sha256").update(content).digest("hex")).update("\n");
+    }
+    return hash.digest("hex");
+}

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

@@ -0,0 +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 { 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";

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

@@ -0,0 +1,7 @@
+export { createFileSystemCompileCache, createInMemoryCompileCache, resolveDefaultCacheDir } from "./cache.js";
+export { composeUserProfile, extractContextBindingPath, rewriteContextBindingProject } from "./compose-profile.js";
+export { 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";

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

@@ -0,0 +1,66 @@
+import type { CompileProfileOptions, CompileProfileResult, CompileRawProfileOptions } from "./types.js";
+/**
+ * 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 declare const DEFAULT_WREN_PROVIDER_PATH: string;
+/**
+ * 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 declare function compileProfile(options: CompileProfileOptions): Promise<CompileProfileResult>;
+/**
+ * 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 declare function compileRawProfile(options: CompileRawProfileOptions): Promise<CompileProfileResult>;
+/**
+ * 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 declare function runWarble(bin: string, args: readonly string[]): Promise<{
+    stdout: string;
+    stderr: string;
+}>;