modelrig 0.0.1 → 0.2.0

package/dist/init/observe.d.ts

@@ -0,0 +1,81 @@
+/**
+ * `modelrig observe` — the observe-first (T0/T1) scaffold.
+ *
+ * Onboarding-test run-1's headline finding (F-1): the ONLY documented observe
+ * on-ramp (`instrumentation.md`) is a hand-wired SDK seam with NO CLI. Every
+ * customer-facing surface points a migrating customer at `modelrig init`, which
+ * is route extraction (T2) — so "just show me my runs first" had no CLI
+ * affordance at all. This command closes that gap.
+ *
+ * It does for OBSERVE what `init` does for MIGRATE, and obeys the same hard
+ * rule: it NEVER edits the target's source. It writes exactly two things under
+ * `modelrig/observe/` — a self-contained `record-step` seam (generated fresh,
+ * per the doc's "write your own; do not resurrect a deleted one" rule) and an
+ * `OBSERVE.md` plan whose per-call-site wiring is emitted as a `diff` for the
+ * agent (or human) to apply with judgment, one step at a time.
+ *
+ * Observe is deliberately NOT migration: it drafts no routes, reroutes no
+ * model calls, and changes no behaviour. With `MODELRIG_ARTIFACTS` off the
+ * pipeline is byte-for-byte identical (instrumentation.md).
+ */
+import type { CallSite, FileSystemLike } from "./finder";
+import type { FinderOptions } from "./finder";
+/** One instrumented step the scaffold proposes: a detected model call site
+ * becomes a step boundary whose work products (prompt, raw, parsed) are saved. */
+export interface ObservePlan {
+    readonly site: CallSite;
+    /** Stable, human-legible step key used in `recordStep(...)` and the console. */
+    readonly stepKey: string;
+    /** The `recordStep(...)` line proposed at this site. */
+    readonly snippet: string;
+}
+export interface ObserveResult {
+    readonly plans: readonly ObservePlan[];
+    readonly sitesFound: number;
+    readonly filesScanned: number;
+    readonly filesSkipped: readonly string[];
+    /** Where the generated seam helper lives (repo-relative). */
+    readonly seamPath: string;
+    /** The generated, self-contained seam helper source. */
+    readonly seamContent: string;
+    /** The OBSERVE.md plan (wiring diffs + the human key-mint handoff). */
+    readonly scaffoldMarkdown: string;
+    readonly written: readonly string[];
+    readonly skipped: readonly string[];
+}
+export interface ObserveOptions extends FinderOptions {
+    /** Plan without writing (`--dry-run`). */
+    readonly dryRun?: boolean;
+}
+export interface ObserveDeps {
+    readonly root: string;
+    /** Directory the scaffold writes into (repo-relative), e.g. modelrig/observe. */
+    readonly outDir: string;
+    readonly fs: FileSystemLike & {
+        existsSync: (p: string) => boolean;
+        mkdirSync: (p: string, o: {
+            recursive: boolean;
+        }) => void;
+        writeFileSync: (p: string, c: string, e: "utf8") => void;
+    };
+    readonly path: {
+        join: (...parts: string[]) => string;
+        relative: (from: string, to: string) => string;
+        dirname: (p: string) => string;
+        basename: (p: string, ext?: string) => string;
+    };
+}
+/** A stable step key from a call site: `<dir>_<file>_<line>`, deduped so two
+ * sites never collide. Deterministic, so a second run proposes the same keys. */
+export declare function stepKeyFor(site: CallSite, used: Set<string>): string;
+/** The generated seam. Self-contained and fresh (never resurrected from git
+ * history — that is the point of onboarding-test run-2). Mirrors the reference
+ * `recordStep` in instrumentation.md, plus a `withRun` boundary wrapper. */
+export declare function seamContent(): string;
+export declare function buildObserveMarkdown(plans: readonly ObservePlan[], seamPath: string, result: {
+    sitesFound: number;
+    filesScanned: number;
+    filesSkipped: readonly string[];
+}, path: ObserveDeps["path"]): string;
+export declare function runObserve(deps: ObserveDeps, options?: ObserveOptions): ObserveResult;
+//# sourceMappingURL=observe.d.ts.map

package/dist/init/observe.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"observe.d.ts","sourceRoot":"","sources":["../../src/init/observe.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAGH,OAAO,KAAK,EAAE,QAAQ,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC;AACzD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAE9C;kFACkF;AAClF,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IACxB,gFAAgF;IAChF,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,wDAAwD;IACxD,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,KAAK,EAAE,SAAS,WAAW,EAAE,CAAC;IACvC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,YAAY,EAAE,SAAS,MAAM,EAAE,CAAC;IACzC,6DAA6D;IAC7D,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,wDAAwD;IACxD,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,uEAAuE;IACvE,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;CACrC;AAED,MAAM,WAAW,cAAe,SAAQ,aAAa;IACnD,0CAA0C;IAC1C,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC;CAC3B;AAED,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,iFAAiF;IACjF,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,EAAE,EAAE,cAAc,GAAG;QAC5B,UAAU,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC;QACnC,SAAS,EAAE,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE;YAAE,SAAS,EAAE,OAAO,CAAA;SAAE,KAAK,IAAI,CAAC;QAC1D,aAAa,EAAE,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,KAAK,IAAI,CAAC;KAC1D,CAAC;IACF,QAAQ,CAAC,IAAI,EAAE;QACb,IAAI,EAAE,CAAC,GAAG,KAAK,EAAE,MAAM,EAAE,KAAK,MAAM,CAAC;QACrC,QAAQ,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,KAAK,MAAM,CAAC;QAC/C,OAAO,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,MAAM,CAAC;QAC/B,QAAQ,EAAE,CAAC,CAAC,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,MAAM,KAAK,MAAM,CAAC;KAC/C,CAAC;CACH;AAKD;iFACiF;AACjF,wBAAgB,UAAU,CAAC,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,GAAG,CAAC,MAAM,CAAC,GAAG,MAAM,CAQpE;AAED;;4EAE4E;AAC5E,wBAAgB,WAAW,IAAI,MAAM,CA6DpC;AAoCD,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,SAAS,WAAW,EAAE,EAC7B,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE;IAAE,UAAU,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,SAAS,MAAM,EAAE,CAAA;CAAE,EACrF,IAAI,EAAE,WAAW,CAAC,MAAM,CAAC,GACxB,MAAM,CA+GR;AAED,wBAAgB,UAAU,CAAC,IAAI,EAAE,WAAW,EAAE,OAAO,GAAE,cAAmB,GAAG,aAAa,CA6DzF"}

package/dist/init/observe.js

@@ -0,0 +1,245 @@
+"use strict";
+/**
+ * `modelrig observe` — the observe-first (T0/T1) scaffold.
+ *
+ * Onboarding-test run-1's headline finding (F-1): the ONLY documented observe
+ * on-ramp (`instrumentation.md`) is a hand-wired SDK seam with NO CLI. Every
+ * customer-facing surface points a migrating customer at `modelrig init`, which
+ * is route extraction (T2) — so "just show me my runs first" had no CLI
+ * affordance at all. This command closes that gap.
+ *
+ * It does for OBSERVE what `init` does for MIGRATE, and obeys the same hard
+ * rule: it NEVER edits the target's source. It writes exactly two things under
+ * `modelrig/observe/` — a self-contained `record-step` seam (generated fresh,
+ * per the doc's "write your own; do not resurrect a deleted one" rule) and an
+ * `OBSERVE.md` plan whose per-call-site wiring is emitted as a `diff` for the
+ * agent (or human) to apply with judgment, one step at a time.
+ *
+ * Observe is deliberately NOT migration: it drafts no routes, reroutes no
+ * model calls, and changes no behaviour. With `MODELRIG_ARTIFACTS` off the
+ * pipeline is byte-for-byte identical (instrumentation.md).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.stepKeyFor = stepKeyFor;
+exports.seamContent = seamContent;
+exports.buildObserveMarkdown = buildObserveMarkdown;
+exports.runObserve = runObserve;
+const finder_1 = require("./finder");
+const normalize = (s) => s.replace(/[^A-Za-z0-9]+/g, "_").replace(/^_|_$/g, "").toLowerCase();
+/** A stable step key from a call site: `<dir>_<file>_<line>`, deduped so two
+ * sites never collide. Deterministic, so a second run proposes the same keys. */
+function stepKeyFor(site, used) {
+    const parts = site.file.split("/").filter((p) => p !== "" && p !== "." && p !== "src");
+    const fileStem = (parts[parts.length - 1] ?? "step").replace(/\.[jt]sx?$/, "");
+    const dir = parts.length > 1 ? parts[parts.length - 2] : "app";
+    let key = `${normalize(dir)}_${normalize(fileStem)}_${site.line}`;
+    while (used.has(key))
+        key = `${key}_x`;
+    used.add(key);
+    return key;
+}
+/** The generated seam. Self-contained and fresh (never resurrected from git
+ * history — that is the point of onboarding-test run-2). Mirrors the reference
+ * `recordStep` in instrumentation.md, plus a `withRun` boundary wrapper. */
+function seamContent() {
+    return `/**
+ * ModelRig observe seam — generated by \`modelrig observe\`.
+ *
+ * This is YOURS to keep and edit; it is generated fresh (not copied from any
+ * deleted seam) so it always matches the current SDK. It records each pipeline
+ * run as a run -> step -> artifact chain you click through in the console.
+ *
+ * Observe-only: no routes move, no model calls are rerouted. With
+ * MODELRIG_ARTIFACTS off (or no control plane configured) every call here is
+ * inert and your pipeline behaves byte-for-byte as before. Nothing here ever
+ * throws into your pipeline — a telemetry write that fails is logged and
+ * dropped (instrumentation.md, "Never throws into your pipeline").
+ *
+ * Docs: https://modelrig.dev/instrumentation.html
+ */
+
+import { createRig, loadConfigFromEnv, type Rig } from "modelrig";
+
+const rig: Rig = createRig(loadConfigFromEnv());
+
+/** Open a run context around a whole pipeline, close it on success/failure.
+ * \`episodeKey\` is a grouping key (a natural choice: your per-run attempt id),
+ * not a unique id. Pass \`environment\` (e.g. your NODE_ENV) to tag the run.
+ * Use \`rig.artifacts.run.scope(...)\` instead for concurrent runs in one
+ * process. */
+export async function withRun<T>(
+  opts: { pipeline: string; episodeKey: string; environment?: string },
+  body: () => Promise<T>,
+): Promise<T> {
+  const run = rig.artifacts.run.start({
+    pipeline: opts.pipeline,
+    episodeKey: opts.episodeKey,
+    ...(opts.environment !== undefined ? { environment: opts.environment } : {}),
+  });
+  try {
+    const out = await body();
+    run.end("succeeded");
+    return out;
+  } catch (err) {
+    run.end("failed");
+    throw err;
+  }
+}
+
+/** Save prompt + raw + parsed for one step, link lineage, flag conformance.
+ * A stage whose model call does NOT go through the rig still produces
+ * artifacts (with \`stepKey\` set and no step row) — correct and honest; the
+ * console renders "cost n/a" rather than inventing a number. */
+export function recordStep(
+  stepKey: string,
+  work: { prompt: string; rawText: string; json: unknown; conforms: boolean },
+): void {
+  const p = rig.artifacts.artifact.save(work.prompt, { name: \`\${stepKey}.prompt\`, type: "prompt", stepKey });
+  const raw = rig.artifacts.artifact.save(work.rawText, { name: \`\${stepKey}.raw\`, type: "raw_response", stepKey });
+  const parsed = rig.artifacts.artifact.save(work.json, { name: \`\${stepKey}.output\`, type: "step_output", task: stepKey, stepKey });
+  if (p && parsed) rig.artifacts.artifact.link(parsed, p, "derived_from");
+  if (raw && parsed) rig.artifacts.artifact.link(parsed, raw, "derived_from");
+  if (parsed) rig.artifacts.artifact.evaluate(parsed, { evaluator: "schema-check", kind: "deterministic", passed: work.conforms });
+}
+`;
+}
+/** The import specifier a source file uses to reach the seam. Best-effort
+ * relative path; a coding agent adjusts it to the project's alias if needed. */
+function importSpecifier(fromFile, seamPath, path) {
+    const noExt = seamPath.replace(/\.[jt]sx?$/, "");
+    const rel = path.relative(path.dirname(fromFile), noExt);
+    return rel.startsWith(".") ? rel : `./${rel}`;
+}
+function recordStepSnippet(stepKey) {
+    return (`recordStep(${JSON.stringify(stepKey)}, {\n` +
+        `  prompt,          // the assembled prompt string\n` +
+        `  rawText,         // the model's raw text, pre-parse\n` +
+        `  json: parsed,    // your parsed/validated output\n` +
+        `  conforms,        // did it satisfy your schema?\n` +
+        `});`);
+}
+/** The run boundary is most likely the shallowest detected file (the entry
+ * that drives the pipeline). A heuristic, flagged as such — never asserted. */
+function runBoundaryFile(plans) {
+    let best = null;
+    let bestDepth = Number.POSITIVE_INFINITY;
+    for (const plan of plans) {
+        const depth = plan.site.file.split("/").length;
+        if (depth < bestDepth) {
+            bestDepth = depth;
+            best = plan.site.file;
+        }
+    }
+    return best;
+}
+function buildObserveMarkdown(plans, seamPath, result, path) {
+    const lines = [
+        "# ModelRig observe — wire up run/step/artifact telemetry",
+        "",
+        "**Nothing in your source has changed.** `modelrig observe` generated one seam helper",
+        `(\`${seamPath}\`) and this plan. Observe is **not migration**: no routes were drafted, no`,
+        "model calls rerouted. Applying the wiring below records each run as a run → step →",
+        "artifact chain you click through in the console — and with the flag off, your pipeline",
+        "behaves **byte-for-byte** as before.",
+        "",
+        `Detected **${result.sitesFound} model call site(s)** across ${result.filesScanned} scanned file(s);`,
+        "each is proposed as one instrumented **step**. Apply the diffs one step at a time — a step",
+        "you do not understand yet is a step you can leave for later.",
+        "",
+        "## 1. Turn the namespace on",
+        "",
+        "```bash",
+        "export MODELRIG_ARTIFACTS=1                 # enable the artifact namespace",
+        "# export MODELRIG_ARTIFACT_STEPS=step_a,step_b   # optional: instrument a subset",
+        "```",
+        "",
+        "> **Human handoff (one step, once).** Seeing these runs **in the console** needs a free",
+        "> account + an API key minted at <https://app.modelrig.ai> (`/keys`) — a console login a",
+        "> coding agent cannot perform. Set `MODELRIG_API_KEY=<key>` once a human provides it; the",
+        "> default ingest host (`https://api.modelrig.ai`) needs no other config. Everything else",
+        "> below an agent can do now — plan the handoff, do not stall on it.",
+        "",
+    ];
+    if (plans.length === 0) {
+        lines.push("## No model call sites found", "", "Nothing matched in the scanned files. If you know there are model calls here, they may sit", "behind a helper that hides the SDK — point `modelrig observe` at the file that actually", "calls the provider, or wire `withRun` / `recordStep` by hand from the seam helper above.", "");
+        return `${lines.join("\n")}\n`;
+    }
+    const boundary = runBoundaryFile(plans);
+    const seamNoExt = seamPath.replace(/\.[jt]sx?$/, "");
+    const boundaryImport = boundary === null ? seamNoExt : importSpecifier(boundary, seamPath, path);
+    lines.push("## 2. Open a run context around the pipeline", "", boundary === null
+        ? "Wrap your pipeline's entry point in `withRun(...)` from the seam helper:"
+        : `Your pipeline entry looks like \`${boundary}\` (the shallowest detected call site — a` +
+            " heuristic; move this if your real entry is elsewhere). Wrap it in `withRun(...)`:", "", "```diff", `+ import { withRun } from "${boundaryImport}";`, "", "- export async function runPipeline(input) {", "-   /* ... your steps ... */", "- }", "+ export async function runPipeline(input) {", "+   return withRun(", '+     { pipeline: "my-pipeline", episodeKey: input.attemptId },', "+     async () => {", "+       /* ... your steps ... */", "+     },", "+   );", "+ }", "```", "", "## 3. Record each step's work products", "", "Each detected model call is one step. After the call parses its output, add a `recordStep`", "(the diffs below quote the call line so you can find it):", "");
+    // Group the per-site wiring diffs by file so each file gets one import line.
+    const byFile = new Map();
+    for (const plan of plans) {
+        const list = byFile.get(plan.site.file) ?? [];
+        list.push(plan);
+        byFile.set(plan.site.file, list);
+    }
+    for (const [file, filePlans] of byFile) {
+        lines.push(`### \`${file}\``, "", "```diff", `+ import { recordStep } from "${importSpecifier(file, seamPath, path)}";`, "");
+        for (const plan of filePlans) {
+            lines.push(`  // line ${plan.site.line}: ${plan.site.provider}` +
+                `${plan.site.model !== null ? ` ${plan.site.model}` : ""} call — save its work products`, ...plan.snippet.split("\n").map((l) => `+ ${l}`), "");
+        }
+        lines.push("```", "");
+    }
+    lines.push("## 4. See it", "", "Run your pipeline once, then open the console: **Runs** lists the run, `/runs/[id]` renders", "the semantic chain (artifacts grouped by step, with hashes and evaluation badges), and", "`/artifacts/[id]` shows one artifact's lineage. Un-routed steps show **cost n/a** — correct", "for observe-only; nothing routes through the rig yet.", "", "## When you are ready to migrate (later, optional)", "", "Observe answers *what is my pipeline doing?* When you want to *change what serves a step*,", "that is route extraction (T2) — a separate, behaviour-affecting move behind its own review:", "`modelrig init --scope <this pipeline>`. Observe first is the safer order.", "");
+    return `${lines.join("\n")}\n`;
+}
+function runObserve(deps, options = {}) {
+    const scan = (0, finder_1.scanRepoForCallSites)(deps.root, deps.fs, deps.path, options);
+    const used = new Set();
+    const plans = scan.sites.map((site) => {
+        const stepKey = stepKeyFor(site, used);
+        return { site, stepKey, snippet: recordStepSnippet(stepKey) };
+    });
+    const seamPath = deps.path.join(deps.outDir, "record-step.ts");
+    // Import specifiers and prose are computed root-relative — call sites come
+    // back relative to `root`, so the seam must be expressed the same way for
+    // `path.relative` to yield a sane `../../modelrig/observe/...` specifier.
+    const seamRel = deps.path.relative(deps.root, seamPath);
+    const content = seamContent();
+    const scaffoldMarkdown = buildObserveMarkdown(plans, seamRel, { sitesFound: scan.sites.length, filesScanned: scan.filesScanned, filesSkipped: scan.filesSkipped }, deps.path);
+    if (options.dryRun === true) {
+        return {
+            plans,
+            sitesFound: scan.sites.length,
+            filesScanned: scan.filesScanned,
+            filesSkipped: scan.filesSkipped,
+            seamPath,
+            seamContent: content,
+            scaffoldMarkdown,
+            written: [],
+            skipped: [],
+        };
+    }
+    deps.fs.mkdirSync(deps.outDir, { recursive: true });
+    const written = [];
+    const skipped = [];
+    // The seam is the customer's to edit — never clobber an existing one.
+    if (deps.fs.existsSync(seamPath)) {
+        skipped.push(seamPath);
+    }
+    else {
+        deps.fs.writeFileSync(seamPath, content, "utf8");
+        written.push(seamPath);
+    }
+    // OBSERVE.md is a regenerated report, not a hand-edited draft — always rewrite.
+    const planPath = deps.path.join(deps.outDir, "OBSERVE.md");
+    deps.fs.writeFileSync(planPath, scaffoldMarkdown, "utf8");
+    written.push(planPath);
+    return {
+        plans,
+        sitesFound: scan.sites.length,
+        filesScanned: scan.filesScanned,
+        filesSkipped: scan.filesSkipped,
+        seamPath,
+        seamContent: content,
+        scaffoldMarkdown,
+        written,
+        skipped,
+    };
+}

package/dist/init/run.d.ts

@@ -0,0 +1,99 @@
+/**
+ * `modelrig init` v0 — spec WS2.
+ *
+ * Finds provider call sites in a repo, drafts a route bundle per site, and
+ * writes a MIGRATION.md mapping call site → route → the `rig.run` line that
+ * would replace it.
+ *
+ * THE HARD RULE, restated because it is the whole design: init NEVER edits
+ * the target's source. It writes under `modelrig/routes/drafts/` and nothing
+ * else. The diff is the human's to apply — spec §4 puts writing-to-source
+ * permanently out of scope for this phase, and the drafts-only property is
+ * tested, not just documented.
+ */
+import type { CallSite, FileSystemLike, FinderOptions } from "./finder";
+import type { ModelSelectRow, CapabilityPredicate } from "../registry/select";
+import type { RouteDraft } from "../routes/draft";
+/**
+ * The cost opportunity at a call site — SHOWN, never taken.
+ *
+ * A migration draft routes to the incumbent so the first run reproduces
+ * today's behavior (see draft.ts on why `prefer` is empty). That is a
+ * sequencing decision, not a decision to ignore cost: the saving is the
+ * whole point of the product, so the migration map names it and hands over
+ * the one command that would prove it.
+ *
+ * The number is INDICATIVE. It comes from probe runs on a generic schema
+ * task, not from the caller's traffic — which is exactly why the honest move
+ * is to show it next to a bake-off command rather than act on it.
+ */
+export interface CostOutlook {
+    readonly incumbentEffectiveUsdPer1k: number | null;
+    readonly bestChallenger: {
+        readonly model: string;
+        readonly effectiveUsdPer1k: number;
+    } | null;
+    /** Indicative only; null when the incumbent is unprobed. */
+    readonly indicativeSavingsPct: number | null;
+    /** Why the number is, or is not, available. */
+    readonly note: string;
+}
+export interface InitDraft {
+    readonly route: string;
+    readonly site: CallSite;
+    readonly draft: RouteDraft;
+    readonly candidateReasoning: readonly string[];
+    /** The rig.run(...) call that would replace this site. */
+    readonly replacement: string;
+    readonly costOutlook: CostOutlook;
+}
+export interface InitResult {
+    readonly drafts: readonly InitDraft[];
+    readonly sitesFound: number;
+    readonly filesScanned: number;
+    readonly filesSkipped: readonly string[];
+    readonly written: readonly string[];
+    readonly skipped: readonly string[];
+    readonly migrationMarkdown: string;
+}
+export interface InitOptions extends FinderOptions {
+    /** Registry rows for candidate seeding; empty = incumbent-only drafts. */
+    readonly registryRows?: readonly ModelSelectRow[];
+    readonly challengerCount?: number;
+    /** Plan without writing (`--dry-run`). */
+    readonly dryRun?: boolean;
+}
+export interface InitDeps {
+    readonly root: string;
+    readonly draftsDir: string;
+    readonly fs: FileSystemLike & {
+        existsSync: (p: string) => boolean;
+        mkdirSync: (p: string, o: {
+            recursive: boolean;
+        }) => void;
+        writeFileSync: (p: string, c: string, e: "utf8") => void;
+    };
+    readonly path: {
+        join: (...parts: string[]) => string;
+        relative: (from: string, to: string) => string;
+        dirname: (p: string) => string;
+        basename: (p: string, ext?: string) => string;
+    };
+}
+/** Route name from a call site: `<file stem>.<line>` namespaced by its
+ * directory, e.g. "services.asset_classifier_42". Deterministic so a second
+ * run produces the same names and therefore skips the same drafts. */
+export declare function routeNameFor(site: CallSite, basename: (p: string, ext?: string) => string): string;
+/** What the site's structured-output usage implies about capability needs.
+ * Conservative: a json_schema request implies native enforcement is wanted;
+ * bare JSON mode only implies conformance. */
+export declare function capabilitiesFor(site: CallSite): CapabilityPredicate[];
+/** Price the incumbent against the cheapest probed challenger, honestly. */
+export declare function buildCostOutlook(incumbentKey: string | null, challengerKeys: readonly string[], rows: readonly ModelSelectRow[]): CostOutlook;
+export declare function buildMigrationMarkdown(drafts: readonly InitDraft[], result: {
+    sitesFound: number;
+    filesScanned: number;
+    filesSkipped: readonly string[];
+}): string;
+export declare function runInit(deps: InitDeps, options?: InitOptions): InitResult;
+//# sourceMappingURL=run.d.ts.map

package/dist/init/run.d.ts.map

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