mrplex 0.0.1

package/dist/embed/backfill.js

@@ -0,0 +1,33 @@
+/**
+ * Backfill: re-chunk + re-embed current versions missing chunks
+ * (design §5.3, m4-plan WS3).
+ *
+ *   1. Walk the repo's live versions.
+ *   2. For any without chunks (any model), enqueue.
+ *   3. Drain the backlog synchronously with a live worker.
+ *
+ * Deliberately does NOT delete stale chunks — the worker's
+ * chunks_upsert handles that on the re-embed. And deliberately does
+ * NOT re-embed versions that already have chunks — call `mrplex embed
+ * backfill --force` (future) to swap models. For v1, model changes go
+ * through: (a) point the hook at the new model, (b) delete the repo's
+ * chunks manually, (c) run backfill.
+ */
+export async function backfillRepo(storage, repoSlug, worker, onProgress) {
+    const repo = await storage.repos_by_slug(repoSlug);
+    if (!repo)
+        throw new Error(`repo not found: ${repoSlug}`);
+    const live = await storage.versions_live_by_repo(repo.id);
+    let enqueued = 0;
+    for (const version of live) {
+        const existing = await storage.chunks_by_version(version.id);
+        if (existing.length === 0) {
+            await storage.backlog_enqueue(version.id);
+            enqueued++;
+        }
+    }
+    onProgress?.(`enqueued ${enqueued} version(s)`);
+    const { processed, failed, skipped } = await worker.drainOnce();
+    return { enqueued, processed, failed, skipped };
+}
+//# sourceMappingURL=backfill.js.map

package/dist/embed/backfill.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"backfill.js","sourceRoot":"","sources":["../../src/embed/backfill.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAYH,MAAM,CAAC,KAAK,UAAU,YAAY,CAChC,OAAgB,EAChB,QAAgB,EAChB,MAAc,EACd,UAAkC;IAElC,MAAM,IAAI,GAAG,MAAM,OAAO,CAAC,aAAa,CAAC,QAAQ,CAAC,CAAC;IACnD,IAAI,CAAC,IAAI;QAAE,MAAM,IAAI,KAAK,CAAC,mBAAmB,QAAQ,EAAE,CAAC,CAAC;IAC1D,MAAM,IAAI,GAAG,MAAM,OAAO,CAAC,qBAAqB,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IAC1D,IAAI,QAAQ,GAAG,CAAC,CAAC;IACjB,KAAK,MAAM,OAAO,IAAI,IAAI,EAAE,CAAC;QAC3B,MAAM,QAAQ,GAAG,MAAM,OAAO,CAAC,iBAAiB,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;QAC7D,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC1B,MAAM,OAAO,CAAC,eAAe,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;YAC1C,QAAQ,EAAE,CAAC;QACb,CAAC;IACH,CAAC;IACD,UAAU,EAAE,CAAC,YAAY,QAAQ,aAAa,CAAC,CAAC;IAChD,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,GAAG,MAAM,MAAM,CAAC,SAAS,EAAE,CAAC;IAChE,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC;AAClD,CAAC"}

package/dist/embed/chunker.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Deterministic markdown-body chunker (design §5.3, m4-plan §5 decision 7).
+ *
+ * Contract:
+ *   • Same input → same chunks. Always. Dedup by (model, text_hash)
+ *     relies on this and only this — a change here re-embeds everything.
+ *   • Body-only. Frontmatter is the structured/query side (§3.2); the
+ *     hook never sees it.
+ *   • Splits on ATX heading and blank-line block boundaries; greedy-packs
+ *     consecutive blocks up to MAX_CHUNK_CHARS; a single block exceeding
+ *     the cap hard-splits at the cap.
+ *   • `text_hash` = sha256(chunk_text) — same primitive as token hashing.
+ *
+ * The chunk-size constant is code, not config: `text_hash` dedup keys
+ * would silently invalidate on a config change, and users of `rank`
+ * would see quiet drift in ranking behavior across servers. Revisiting
+ * chunk size later only costs one backfill (§5.3, `embed backfill`).
+ */
+/** Maximum characters per chunk. Constant, not config; see file header. */
+export declare const MAX_CHUNK_CHARS = 2000;
+export type Chunk = {
+    /** 0-based document order. Contiguous within a chunk[] result. */
+    ix: number;
+    text: string;
+    text_hash: string;
+};
+/**
+ * Chunk a document body. Empty / whitespace-only body → empty array
+ * (a valid state; the doc simply never ranks — see §5.3).
+ */
+export declare function chunkBody(body: string): Chunk[];

package/dist/embed/chunker.js

@@ -0,0 +1,121 @@
+/**
+ * Deterministic markdown-body chunker (design §5.3, m4-plan §5 decision 7).
+ *
+ * Contract:
+ *   • Same input → same chunks. Always. Dedup by (model, text_hash)
+ *     relies on this and only this — a change here re-embeds everything.
+ *   • Body-only. Frontmatter is the structured/query side (§3.2); the
+ *     hook never sees it.
+ *   • Splits on ATX heading and blank-line block boundaries; greedy-packs
+ *     consecutive blocks up to MAX_CHUNK_CHARS; a single block exceeding
+ *     the cap hard-splits at the cap.
+ *   • `text_hash` = sha256(chunk_text) — same primitive as token hashing.
+ *
+ * The chunk-size constant is code, not config: `text_hash` dedup keys
+ * would silently invalidate on a config change, and users of `rank`
+ * would see quiet drift in ranking behavior across servers. Revisiting
+ * chunk size later only costs one backfill (§5.3, `embed backfill`).
+ */
+import { createHash } from "node:crypto";
+/** Maximum characters per chunk. Constant, not config; see file header. */
+export const MAX_CHUNK_CHARS = 2000;
+/**
+ * Chunk a document body. Empty / whitespace-only body → empty array
+ * (a valid state; the doc simply never ranks — see §5.3).
+ */
+export function chunkBody(body) {
+    const blocks = splitBlocks(body);
+    const packed = greedyPack(blocks, MAX_CHUNK_CHARS);
+    return packed.map((text, ix) => ({
+        ix,
+        text,
+        text_hash: sha256(text),
+    }));
+}
+/**
+ * Split into blocks at ATX heading and blank-line boundaries. Blank
+ * lines are ONLY the boundary — they don't join the output.
+ *
+ * "Block" here is coarse: consecutive non-blank lines belong to one
+ * block; an ATX heading line starts a fresh block. That covers the
+ * common markdown shapes (paragraphs, lists, headings, code fences)
+ * without a full commonmark parse. If a code fence contains an
+ * accidental `#`-leading line, the heading rule mis-splits — a chunker
+ * is not a renderer, and this is worse cosmetically than semantically:
+ * the split still deterministically produces the same chunks every
+ * time, which is what dedup requires.
+ */
+function splitBlocks(body) {
+    const lines = body.split(/\r?\n/);
+    const blocks = [];
+    let current = [];
+    const push = () => {
+        if (current.length === 0)
+            return;
+        const joined = current.join("\n").replace(/\s+$/, "");
+        if (joined.length > 0)
+            blocks.push(joined);
+        current = [];
+    };
+    for (const line of lines) {
+        const isBlank = line.trim().length === 0;
+        const isHeading = /^\s{0,3}#{1,6}\s/.test(line);
+        if (isBlank) {
+            push();
+            continue;
+        }
+        if (isHeading && current.length > 0) {
+            push();
+        }
+        current.push(line);
+    }
+    push();
+    return blocks;
+}
+/**
+ * Greedy-pack blocks into chunks of at most `cap` characters. A single
+ * block over `cap` hard-splits at exactly `cap` byte-wise on characters
+ * (JS string units) — no attempt to preserve word boundaries. Reason:
+ * an accidental split is far preferable to a per-corpus non-deterministic
+ * split rule (dedup sensitivity, §5.3).
+ */
+function greedyPack(blocks, cap) {
+    const chunks = [];
+    let buf = "";
+    const flush = () => {
+        if (buf.length === 0)
+            return;
+        chunks.push(buf);
+        buf = "";
+    };
+    for (const block of blocks) {
+        if (block.length > cap) {
+            // Flush anything we were building; hard-split the oversized block.
+            flush();
+            for (let i = 0; i < block.length; i += cap) {
+                chunks.push(block.slice(i, i + cap));
+            }
+            continue;
+        }
+        if (buf.length === 0) {
+            buf = block;
+            continue;
+        }
+        // Join with a blank line so a two-block chunk still reads as
+        // two blocks — hooks that stem/tokenize benefit from the separator.
+        const candidate = `${buf}\n\n${block}`;
+        if (candidate.length <= cap) {
+            buf = candidate;
+        }
+        else {
+            flush();
+            buf = block;
+        }
+    }
+    flush();
+    return chunks;
+}
+function sha256(input) {
+    return createHash("sha256").update(input, "utf8").digest("hex");
+}
+//# sourceMappingURL=chunker.js.map

package/dist/embed/chunker.js.map

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

package/dist/embed/cmd-hook.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Subprocess embedding hook (--embed-cmd). Spawns a long-lived process
+ * once; writes one JSON line per batch to stdin; reads one JSON line
+ * back from stdout (design §5.3, m4-plan §5 decision 1).
+ *
+ * Stderr passes through to the server log; the hook doesn't parse it.
+ *
+ * Concurrency: at most one in-flight embed() call per hook instance.
+ * The worker's drain loop is single-flight per batch, so this is fine
+ * for v1 — a hook that needs parallelism can implement it internally.
+ */
+import { type EmbedHook } from "./hook.js";
+export type CmdHookOptions = {
+    command: string;
+    /** Optional args if the command needs them (rare; usually a single script). */
+    args?: readonly string[];
+    timeoutMs?: number;
+    /** stderr sink — defaults to the parent's stderr. */
+    onStderr?: (chunk: string) => void;
+};
+export declare function createCmdEmbedHook(opts: CmdHookOptions): EmbedHook;

package/dist/embed/cmd-hook.js

@@ -0,0 +1,100 @@
+/**
+ * Subprocess embedding hook (--embed-cmd). Spawns a long-lived process
+ * once; writes one JSON line per batch to stdin; reads one JSON line
+ * back from stdout (design §5.3, m4-plan §5 decision 1).
+ *
+ * Stderr passes through to the server log; the hook doesn't parse it.
+ *
+ * Concurrency: at most one in-flight embed() call per hook instance.
+ * The worker's drain loop is single-flight per batch, so this is fine
+ * for v1 — a hook that needs parallelism can implement it internally.
+ */
+import { spawn } from "node:child_process";
+import { validateEmbedResponse } from "./hook.js";
+export function createCmdEmbedHook(opts) {
+    const timeout = opts.timeoutMs ?? 60_000;
+    const onStderr = opts.onStderr ?? ((c) => process.stderr.write(c));
+    let proc = null;
+    let readBuffer = "";
+    let pending = null;
+    let pendingError = null;
+    let inFlight = Promise.resolve();
+    function ensureProc() {
+        if (proc && proc.exitCode === null)
+            return proc;
+        proc = spawn(opts.command, opts.args ?? [], {
+            stdio: ["pipe", "pipe", "pipe"],
+        });
+        proc.stdout.setEncoding("utf8");
+        proc.stderr.setEncoding("utf8");
+        proc.stdout.on("data", (chunk) => {
+            readBuffer += chunk;
+            let nl = readBuffer.indexOf("\n");
+            while (nl >= 0) {
+                const line = readBuffer.slice(0, nl);
+                readBuffer = readBuffer.slice(nl + 1);
+                if (pending) {
+                    const cb = pending;
+                    pending = null;
+                    pendingError = null;
+                    cb(line);
+                }
+                nl = readBuffer.indexOf("\n");
+            }
+        });
+        proc.stderr.on("data", (chunk) => onStderr(chunk));
+        proc.on("exit", (code, signal) => {
+            const err = new Error(`embed hook subprocess exited (code=${code} signal=${signal ?? ""})`);
+            if (pendingError) {
+                const cb = pendingError;
+                pending = null;
+                pendingError = null;
+                cb(err);
+            }
+            proc = null;
+            readBuffer = "";
+        });
+        return proc;
+    }
+    return {
+        label: [opts.command, ...(opts.args ?? [])].join(" "),
+        async embed(chunks) {
+            // Serialize batches — one in-flight at a time. Awaiting the
+            // previous call's promise chains us behind it.
+            const gate = inFlight.catch(() => undefined);
+            inFlight = gate.then(async () => {
+                const p = ensureProc();
+                const linePromise = new Promise((resolve, reject) => {
+                    pending = resolve;
+                    pendingError = reject;
+                });
+                const timer = setTimeout(() => {
+                    if (pendingError) {
+                        const cb = pendingError;
+                        pending = null;
+                        pendingError = null;
+                        cb(new Error(`embed hook timed out after ${timeout}ms`));
+                    }
+                }, timeout);
+                try {
+                    p.stdin.write(`${JSON.stringify({ chunks })}\n`);
+                    const line = await linePromise;
+                    const body = JSON.parse(line);
+                    return validateEmbedResponse(body, chunks);
+                }
+                finally {
+                    clearTimeout(timer);
+                }
+            });
+            return inFlight;
+        },
+        async close() {
+            if (proc && proc.exitCode === null) {
+                proc.stdin.end();
+                proc.kill();
+            }
+            proc = null;
+        },
+    };
+}
+//# sourceMappingURL=cmd-hook.js.map

package/dist/embed/cmd-hook.js.map

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

package/dist/embed/config.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Embed hook configuration resolution — shared between `mrplex serve`
+ * and the local `mrplex embed` commands (m4-plan WS3).
+ *
+ * Precedence per source kind: CLI flag → env var → CLI config file → unset.
+ * Only one source kind may be configured at a time (`--embedder`, legacy
+ * `--embed-url`, or legacy `--embed-cmd` / their env/config equivalents).
+ */
+import type { EmbedHook } from "./hook.js";
+export type EmbedFlagInputs = {
+    /** Unified provider: subprocess command, or http(s):// URL. */
+    embedder?: string;
+    /** @deprecated Use `embedder` with an http(s):// URL. */
+    embed_url?: string;
+    /** @deprecated Use `embedder` with a command. */
+    embed_cmd?: string;
+};
+export type EmbedConfig = {
+    kind: "http";
+    url: string;
+} | {
+    kind: "cmd";
+    command: string;
+} | {
+    kind: "none";
+};
+/**
+ * Parse a unified `--embedder` value. Only `http://` and `https://` select
+ * the HTTP hook; everything else is a subprocess command string.
+ */
+export declare function parseEmbedderSpec(value: string): EmbedConfig;
+export declare function resolveEmbedConfig(inputs?: EmbedFlagInputs): EmbedConfig;
+export declare function describeEmbedConfig(c: EmbedConfig): string;
+/**
+ * Instantiate a hook from a resolved config. Returns null if the
+ * config is `none` — callers decide whether that is fatal.
+ */
+export declare function createHookFromConfig(c: EmbedConfig): EmbedHook | null;
+/** Commander option bundle for commands that accept an embedding provider. */
+export declare const EMBED_CLI_OPTIONS: {
+    readonly embedder: {
+        readonly flags: "--embedder <spec>";
+        readonly description: "embedding provider: command, or http(s):// URL";
+    };
+    readonly embedUrl: {
+        readonly flags: "--embed-url <url>";
+        readonly description: "(deprecated) use --embedder with an http(s):// URL";
+    };
+    readonly embedCmd: {
+        readonly flags: "--embed-cmd <cmd>";
+        readonly description: "(deprecated) use --embedder with a command";
+    };
+};
+export type EmbedCliOpts = {
+    embedder?: string;
+    embedUrl?: string;
+    embedCmd?: string;
+};
+export declare function embedFlagInputsFromCli(opts: EmbedCliOpts): EmbedFlagInputs;
+import type { Command } from "commander";
+export declare function addEmbedCliOptions(cmd: Command): Command;

package/dist/embed/config.js

@@ -0,0 +1,109 @@
+/**
+ * Embed hook configuration resolution — shared between `mrplex serve`
+ * and the local `mrplex embed` commands (m4-plan WS3).
+ *
+ * Precedence per source kind: CLI flag → env var → CLI config file → unset.
+ * Only one source kind may be configured at a time (`--embedder`, legacy
+ * `--embed-url`, or legacy `--embed-cmd` / their env/config equivalents).
+ */
+import { loadConfig } from "../cli/config.js";
+import { createCmdEmbedHook } from "./cmd-hook.js";
+import { createHttpEmbedHook } from "./http-hook.js";
+/**
+ * Parse a unified `--embedder` value. Only `http://` and `https://` select
+ * the HTTP hook; everything else is a subprocess command string.
+ */
+export function parseEmbedderSpec(value) {
+    const trimmed = value.trim();
+    if (trimmed.length === 0) {
+        throw new Error("--embedder is empty");
+    }
+    if (trimmed.startsWith("http://") || trimmed.startsWith("https://")) {
+        return { kind: "http", url: trimmed };
+    }
+    return { kind: "cmd", command: trimmed };
+}
+export function resolveEmbedConfig(inputs = {}) {
+    const cfg = loadConfig();
+    const embedder = inputs.embedder ?? process.env.MRPLEX_EMBEDDER ?? cfg.embedder;
+    const url = inputs.embed_url ?? process.env.MRPLEX_EMBED_URL ?? cfg.embed_url;
+    const cmd = inputs.embed_cmd ?? process.env.MRPLEX_EMBED_CMD ?? cfg.embed_cmd;
+    const sources = [];
+    if (embedder)
+        sources.push("--embedder");
+    if (url)
+        sources.push("--embed-url");
+    if (cmd)
+        sources.push("--embed-cmd");
+    if (sources.length > 1) {
+        throw new Error(`${sources.join(", ")} are mutually exclusive — use --embedder only (http(s):// URL or command)`);
+    }
+    if (embedder)
+        return parseEmbedderSpec(embedder);
+    if (url)
+        return { kind: "http", url };
+    if (cmd)
+        return { kind: "cmd", command: cmd };
+    return { kind: "none" };
+}
+export function describeEmbedConfig(c) {
+    switch (c.kind) {
+        case "http":
+            return `http ${c.url}`;
+        case "cmd":
+            return `cmd ${c.command}`;
+        case "none":
+            return "off";
+    }
+}
+/**
+ * Instantiate a hook from a resolved config. Returns null if the
+ * config is `none` — callers decide whether that is fatal.
+ */
+export function createHookFromConfig(c) {
+    switch (c.kind) {
+        case "http":
+            return createHttpEmbedHook({ url: c.url });
+        case "cmd": {
+            // The command string is split on whitespace (shell-lite). If a
+            // user needs quoted args they can point --embedder at a wrapper
+            // script — same rule production sidecar deployments already use.
+            const parts = c.command.split(/\s+/).filter((p) => p.length > 0);
+            const [command, ...args] = parts;
+            if (!command)
+                throw new Error("--embedder command is empty");
+            return createCmdEmbedHook({ command, args });
+        }
+        case "none":
+            return null;
+    }
+}
+/** Commander option bundle for commands that accept an embedding provider. */
+export const EMBED_CLI_OPTIONS = {
+    embedder: {
+        flags: "--embedder <spec>",
+        description: "embedding provider: command, or http(s):// URL",
+    },
+    embedUrl: {
+        flags: "--embed-url <url>",
+        description: "(deprecated) use --embedder with an http(s):// URL",
+    },
+    embedCmd: {
+        flags: "--embed-cmd <cmd>",
+        description: "(deprecated) use --embedder with a command",
+    },
+};
+export function embedFlagInputsFromCli(opts) {
+    return {
+        embedder: opts.embedder,
+        embed_url: opts.embedUrl,
+        embed_cmd: opts.embedCmd,
+    };
+}
+export function addEmbedCliOptions(cmd) {
+    return cmd
+        .option(EMBED_CLI_OPTIONS.embedder.flags, EMBED_CLI_OPTIONS.embedder.description)
+        .option(EMBED_CLI_OPTIONS.embedUrl.flags, EMBED_CLI_OPTIONS.embedUrl.description)
+        .option(EMBED_CLI_OPTIONS.embedCmd.flags, EMBED_CLI_OPTIONS.embedCmd.description);
+}
+//# sourceMappingURL=config.js.map

package/dist/embed/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../../src/embed/config.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC9C,OAAO,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AAEnD,OAAO,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AAgBrD;;;GAGG;AACH,MAAM,UAAU,iBAAiB,CAAC,KAAa;IAC7C,MAAM,OAAO,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC;IAC7B,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACzB,MAAM,IAAI,KAAK,CAAC,qBAAqB,CAAC,CAAC;IACzC,CAAC;IACD,IAAI,OAAO,CAAC,UAAU,CAAC,SAAS,CAAC,IAAI,OAAO,CAAC,UAAU,CAAC,UAAU,CAAC,EAAE,CAAC;QACpE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,OAAO,EAAE,CAAC;IACxC,CAAC;IACD,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,CAAC;AAC3C,CAAC;AAED,MAAM,UAAU,kBAAkB,CAAC,SAA0B,EAAE;IAC7D,MAAM,GAAG,GAAG,UAAU,EAAE,CAAC;IAEzB,MAAM,QAAQ,GAAG,MAAM,CAAC,QAAQ,IAAI,OAAO,CAAC,GAAG,CAAC,eAAe,IAAI,GAAG,CAAC,QAAQ,CAAC;IAChF,MAAM,GAAG,GAAG,MAAM,CAAC,SAAS,IAAI,OAAO,CAAC,GAAG,CAAC,gBAAgB,IAAI,GAAG,CAAC,SAAS,CAAC;IAC9E,MAAM,GAAG,GAAG,MAAM,CAAC,SAAS,IAAI,OAAO,CAAC,GAAG,CAAC,gBAAgB,IAAI,GAAG,CAAC,SAAS,CAAC;IAE9E,MAAM,OAAO,GAAa,EAAE,CAAC;IAC7B,IAAI,QAAQ;QAAE,OAAO,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC;IACzC,IAAI,GAAG;QAAE,OAAO,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC;IACrC,IAAI,GAAG;QAAE,OAAO,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC;IACrC,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACvB,MAAM,IAAI,KAAK,CACb,GAAG,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,2EAA2E,CACjG,CAAC;IACJ,CAAC;IAED,IAAI,QAAQ;QAAE,OAAO,iBAAiB,CAAC,QAAQ,CAAC,CAAC;IACjD,IAAI,GAAG;QAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,CAAC;IACtC,IAAI,GAAG;QAAE,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,OAAO,EAAE,GAAG,EAAE,CAAC;IAC9C,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC;AAC1B,CAAC;AAED,MAAM,UAAU,mBAAmB,CAAC,CAAc;IAChD,QAAQ,CAAC,CAAC,IAAI,EAAE,CAAC;QACf,KAAK,MAAM;YACT,OAAO,QAAQ,CAAC,CAAC,GAAG,EAAE,CAAC;QACzB,KAAK,KAAK;YACR,OAAO,OAAO,CAAC,CAAC,OAAO,EAAE,CAAC;QAC5B,KAAK,MAAM;YACT,OAAO,KAAK,CAAC;IACjB,CAAC;AACH,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,oBAAoB,CAAC,CAAc;IACjD,QAAQ,CAAC,CAAC,IAAI,EAAE,CAAC;QACf,KAAK,MAAM;YACT,OAAO,mBAAmB,CAAC,EAAE,GAAG,EAAE,CAAC,CAAC,GAAG,EAAE,CAAC,CAAC;QAC7C,KAAK,KAAK,CAAC,CAAC,CAAC;YACX,+DAA+D;YAC/D,gEAAgE;YAChE,iEAAiE;YACjE,MAAM,KAAK,GAAG,CAAC,CAAC,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;YACjE,MAAM,CAAC,OAAO,EAAE,GAAG,IAAI,CAAC,GAAG,KAAK,CAAC;YACjC,IAAI,CAAC,OAAO;gBAAE,MAAM,IAAI,KAAK,CAAC,6BAA6B,CAAC,CAAC;YAC7D,OAAO,kBAAkB,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC;QAC/C,CAAC;QACD,KAAK,MAAM;YACT,OAAO,IAAI,CAAC;IAChB,CAAC;AACH,CAAC;AAED,8EAA8E;AAC9E,MAAM,CAAC,MAAM,iBAAiB,GAAG;IAC/B,QAAQ,EAAE;QACR,KAAK,EAAE,mBAAmB;QAC1B,WAAW,EAAE,gDAAgD;KAC9D;IACD,QAAQ,EAAE;QACR,KAAK,EAAE,mBAAmB;QAC1B,WAAW,EAAE,oDAAoD;KAClE;IACD,QAAQ,EAAE;QACR,KAAK,EAAE,mBAAmB;QAC1B,WAAW,EAAE,4CAA4C;KAC1D;CACO,CAAC;AAQX,MAAM,UAAU,sBAAsB,CAAC,IAAkB;IACvD,OAAO;QACL,QAAQ,EAAE,IAAI,CAAC,QAAQ;QACvB,SAAS,EAAE,IAAI,CAAC,QAAQ;QACxB,SAAS,EAAE,IAAI,CAAC,QAAQ;KACzB,CAAC;AACJ,CAAC;AAID,MAAM,UAAU,kBAAkB,CAAC,GAAY;IAC7C,OAAO,GAAG;SACP,MAAM,CAAC,iBAAiB,CAAC,QAAQ,CAAC,KAAK,EAAE,iBAAiB,CAAC,QAAQ,CAAC,WAAW,CAAC;SAChF,MAAM,CAAC,iBAAiB,CAAC,QAAQ,CAAC,KAAK,EAAE,iBAAiB,CAAC,QAAQ,CAAC,WAAW,CAAC;SAChF,MAAM,CAAC,iBAAiB,CAAC,QAAQ,CAAC,KAAK,EAAE,iBAAiB,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAC;AACtF,CAAC"}

package/dist/embed/hook.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Embedding hook contract (design §5.3).
+ *
+ *   embed(chunks: string[]) → { vectors: number[][], model: string, dim: int }
+ *
+ * mrplex does NOT call any provider itself: the operator wires a hook
+ * that speaks this contract. m4-plan ships two shapes: HTTP endpoint
+ * (--embed-url) and long-lived subprocess with JSON-lines over stdio
+ * (--embed-cmd). In-process plugin is deferred (m4-plan §5 decision 1).
+ *
+ * Contract-validation happens here so every shape gets the same
+ * checks: batch alignment, per-vector dim, non-empty model. A single
+ * bad response fails the whole batch — never partial-write.
+ */
+export type EmbedResponse = {
+    vectors: number[][];
+    model: string;
+    dim: number;
+};
+export type EmbedHook = {
+    /** Human-facing description (URL / command), used in log lines. */
+    label: string;
+    /**
+     * Embed a batch. Batching, rate limiting, provider retries all live
+     * inside the hook (§5.3) — the worker only paces dispatch.
+     *
+     * Contract-invariant: `vectors[i]` corresponds to `chunks[i]`.
+     */
+    embed(chunks: readonly string[]): Promise<EmbedResponse>;
+    /** Release resources (kill subprocess, close sockets). */
+    close(): Promise<void>;
+};
+/**
+ * Validate a response against the hook contract. Returns the response
+ * unchanged on success; throws a descriptive Error on any violation.
+ * Hooks call this before returning so the worker can trust the shape.
+ */
+export declare function validateEmbedResponse(resp: unknown, requested: readonly string[]): EmbedResponse;

package/dist/embed/hook.js

@@ -0,0 +1,56 @@
+/**
+ * Embedding hook contract (design §5.3).
+ *
+ *   embed(chunks: string[]) → { vectors: number[][], model: string, dim: int }
+ *
+ * mrplex does NOT call any provider itself: the operator wires a hook
+ * that speaks this contract. m4-plan ships two shapes: HTTP endpoint
+ * (--embed-url) and long-lived subprocess with JSON-lines over stdio
+ * (--embed-cmd). In-process plugin is deferred (m4-plan §5 decision 1).
+ *
+ * Contract-validation happens here so every shape gets the same
+ * checks: batch alignment, per-vector dim, non-empty model. A single
+ * bad response fails the whole batch — never partial-write.
+ */
+/**
+ * Validate a response against the hook contract. Returns the response
+ * unchanged on success; throws a descriptive Error on any violation.
+ * Hooks call this before returning so the worker can trust the shape.
+ */
+export function validateEmbedResponse(resp, requested) {
+    if (typeof resp !== "object" || resp === null) {
+        throw new Error("embed hook: response is not an object");
+    }
+    const r = resp;
+    const model = r.model;
+    if (typeof model !== "string" || model.length === 0) {
+        throw new Error("embed hook: response.model must be a non-empty string");
+    }
+    const dim = r.dim;
+    if (typeof dim !== "number" || !Number.isInteger(dim) || dim <= 0) {
+        throw new Error(`embed hook: response.dim must be a positive integer (got ${JSON.stringify(dim)})`);
+    }
+    const vectors = r.vectors;
+    if (!Array.isArray(vectors)) {
+        throw new Error("embed hook: response.vectors must be an array");
+    }
+    if (vectors.length !== requested.length) {
+        throw new Error(`embed hook: vectors.length (${vectors.length}) !== requested chunks (${requested.length})`);
+    }
+    for (let i = 0; i < vectors.length; i++) {
+        const v = vectors[i];
+        if (!Array.isArray(v)) {
+            throw new Error(`embed hook: vectors[${i}] is not an array`);
+        }
+        if (v.length !== dim) {
+            throw new Error(`embed hook: vectors[${i}].length (${v.length}) !== dim (${dim})`);
+        }
+        for (let j = 0; j < v.length; j++) {
+            if (typeof v[j] !== "number" || !Number.isFinite(v[j])) {
+                throw new Error(`embed hook: vectors[${i}][${j}] is not a finite number`);
+            }
+        }
+    }
+    return { vectors: vectors, model, dim };
+}
+//# sourceMappingURL=hook.js.map

package/dist/embed/hook.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hook.js","sourceRoot":"","sources":["../../src/embed/hook.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAsBH;;;;GAIG;AACH,MAAM,UAAU,qBAAqB,CAAC,IAAa,EAAE,SAA4B;IAC/E,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,KAAK,IAAI,EAAE,CAAC;QAC9C,MAAM,IAAI,KAAK,CAAC,uCAAuC,CAAC,CAAC;IAC3D,CAAC;IACD,MAAM,CAAC,GAAG,IAA+B,CAAC;IAC1C,MAAM,KAAK,GAAG,CAAC,CAAC,KAAK,CAAC;IACtB,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACpD,MAAM,IAAI,KAAK,CAAC,uDAAuD,CAAC,CAAC;IAC3E,CAAC;IACD,MAAM,GAAG,GAAG,CAAC,CAAC,GAAG,CAAC;IAClB,IAAI,OAAO,GAAG,KAAK,QAAQ,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,GAAG,CAAC,IAAI,GAAG,IAAI,CAAC,EAAE,CAAC;QAClE,MAAM,IAAI,KAAK,CACb,4DAA4D,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,GAAG,CACnF,CAAC;IACJ,CAAC;IACD,MAAM,OAAO,GAAG,CAAC,CAAC,OAAO,CAAC;IAC1B,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC;QAC5B,MAAM,IAAI,KAAK,CAAC,+CAA+C,CAAC,CAAC;IACnE,CAAC;IACD,IAAI,OAAO,CAAC,MAAM,KAAK,SAAS,CAAC,MAAM,EAAE,CAAC;QACxC,MAAM,IAAI,KAAK,CACb,+BAA+B,OAAO,CAAC,MAAM,2BAA2B,SAAS,CAAC,MAAM,GAAG,CAC5F,CAAC;IACJ,CAAC;IACD,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACxC,MAAM,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;QACrB,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC;YACtB,MAAM,IAAI,KAAK,CAAC,uBAAuB,CAAC,mBAAmB,CAAC,CAAC;QAC/D,CAAC;QACD,IAAI,CAAC,CAAC,MAAM,KAAK,GAAG,EAAE,CAAC;YACrB,MAAM,IAAI,KAAK,CAAC,uBAAuB,CAAC,aAAa,CAAC,CAAC,MAAM,cAAc,GAAG,GAAG,CAAC,CAAC;QACrF,CAAC;QACD,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;YAClC,IAAI,OAAO,CAAC,CAAC,CAAC,CAAC,KAAK,QAAQ,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;gBACvD,MAAM,IAAI,KAAK,CAAC,uBAAuB,CAAC,KAAK,CAAC,0BAA0B,CAAC,CAAC;YAC5E,CAAC;QACH,CAAC;IACH,CAAC;IACD,OAAO,EAAE,OAAO,EAAE,OAAqB,EAAE,KAAK,EAAE,GAAG,EAAE,CAAC;AACxD,CAAC"}

package/dist/embed/http-hook.d.ts

@@ -0,0 +1,13 @@
+/**
+ * HTTP embedding hook (--embed-url). POST { chunks: string[] } → the
+ * contract response (design §5.3, m4-plan §5 decision 1).
+ *
+ * Uses Node ≥ 20's built-in fetch — no dep. Timeout defaults to 30s;
+ * anything longer usually means the operator wants a subprocess hook.
+ */
+import { type EmbedHook } from "./hook.js";
+export type HttpHookOptions = {
+    url: string;
+    timeoutMs?: number;
+};
+export declare function createHttpEmbedHook(opts: HttpHookOptions): EmbedHook;

package/dist/embed/http-hook.js

@@ -0,0 +1,39 @@
+/**
+ * HTTP embedding hook (--embed-url). POST { chunks: string[] } → the
+ * contract response (design §5.3, m4-plan §5 decision 1).
+ *
+ * Uses Node ≥ 20's built-in fetch — no dep. Timeout defaults to 30s;
+ * anything longer usually means the operator wants a subprocess hook.
+ */
+import { validateEmbedResponse } from "./hook.js";
+export function createHttpEmbedHook(opts) {
+    const timeout = opts.timeoutMs ?? 30_000;
+    return {
+        label: opts.url,
+        async embed(chunks) {
+            const controller = new AbortController();
+            const timer = setTimeout(() => controller.abort(), timeout);
+            try {
+                const res = await fetch(opts.url, {
+                    method: "POST",
+                    headers: { "content-type": "application/json" },
+                    body: JSON.stringify({ chunks }),
+                    signal: controller.signal,
+                });
+                if (!res.ok) {
+                    const text = await res.text().catch(() => "");
+                    throw new Error(`embed hook HTTP ${res.status}: ${text.slice(0, 500)}`);
+                }
+                const body = await res.json();
+                return validateEmbedResponse(body, chunks);
+            }
+            finally {
+                clearTimeout(timer);
+            }
+        },
+        async close() {
+            // fetch is stateless; nothing to close.
+        },
+    };
+}
+//# sourceMappingURL=http-hook.js.map