@isaacriehm/cairn-core 0.1.0

package/dist/init/setup-runners.js

@@ -0,0 +1,143 @@
+/**
+ * Spawners for actually executing setup steps from `harness init`.
+ *
+ * Each function inherits stdio so the operator sees curl / pnpm / docker
+ * progress live. Returns success/failure; the caller surfaces the result
+ * in the wizard summary.
+ */
+import { spawn } from "node:child_process";
+import { createWriteStream, existsSync, mkdirSync, statSync, unlinkSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { homedir } from "node:os";
+import { startProgress } from "./visual.js";
+const HERE = dirname(fileURLToPath(import.meta.url));
+/** dist/init/setup-runners.js → walk up to package root. */
+const PKG_ROOT = resolve(HERE, "..", "..");
+const WHISPER_MODEL_DIR = join(homedir(), ".local", "harness", "models");
+const WHISPER_MODEL_FILE = "ggml-large-v3-turbo-q5_0.bin";
+const WHISPER_MODEL_URL = "https://huggingface.co/ggerganov/whisper.cpp/resolve/main/ggml-large-v3-turbo-q5_0.bin?download=true";
+export async function downloadWhisperModel() {
+    mkdirSync(WHISPER_MODEL_DIR, { recursive: true });
+    const out = join(WHISPER_MODEL_DIR, WHISPER_MODEL_FILE);
+    if (existsSync(out)) {
+        return { ok: true, exit_code: 0, note: "model already on disk" };
+    }
+    return downloadWithProgress({
+        url: WHISPER_MODEL_URL,
+        destPath: out,
+        label: "Downloading whisper model",
+    });
+}
+/**
+ * Stream-download a URL to disk, showing a cli-progress bar with bytes +
+ * transfer rate. Falls back to a single-line in-place update on non-TTY.
+ *
+ * Uses the global `fetch()` available in Node 22+. No new deps.
+ */
+async function downloadWithProgress(opts) {
+    let response;
+    try {
+        response = await fetch(opts.url);
+    }
+    catch (err) {
+        return {
+            ok: false,
+            exit_code: null,
+            note: `fetch failed — ${err instanceof Error ? err.message : String(err)}`,
+        };
+    }
+    if (!response.ok) {
+        return {
+            ok: false,
+            exit_code: response.status,
+            note: `HTTP ${response.status} ${response.statusText}`,
+        };
+    }
+    const lenHeader = response.headers.get("content-length");
+    const total = lenHeader !== null && Number.isFinite(Number.parseInt(lenHeader, 10))
+        ? Number.parseInt(lenHeader, 10)
+        : 0;
+    if (response.body === null) {
+        return { ok: false, exit_code: null, note: "empty response body" };
+    }
+    const sink = createWriteStream(opts.destPath, { flags: "w" });
+    const progress = startProgress({ label: opts.label, total: Math.max(total, 1) });
+    let received = 0;
+    const startedAt = Date.now();
+    try {
+        const reader = response.body.getReader();
+        let last = 0;
+        while (true) {
+            const { value, done } = await reader.read();
+            if (done)
+                break;
+            received += value.byteLength;
+            sink.write(value);
+            const now = Date.now();
+            if (now - last > 80) {
+                const elapsedSec = Math.max((now - startedAt) / 1000, 0.001);
+                const speedMb = (received / elapsedSec / 1_048_576).toFixed(1);
+                progress.set(received, { speedMb });
+                last = now;
+            }
+        }
+        sink.end();
+        await new Promise((resolveP) => sink.on("close", () => resolveP()));
+        progress.set(received, {
+            speedMb: ((received / Math.max((Date.now() - startedAt) / 1000, 0.001) / 1_048_576).toFixed(1)),
+        });
+        progress.stop(true, `whisper model downloaded (${(received / 1_048_576).toFixed(0)}MB)`);
+        return { ok: true, exit_code: 0 };
+    }
+    catch (err) {
+        progress.stop(false, "download failed");
+        try {
+            sink.end();
+        }
+        catch {
+            // ignore
+        }
+        try {
+            if (existsSync(opts.destPath) && statSync(opts.destPath).size < (total || Infinity)) {
+                unlinkSync(opts.destPath);
+            }
+        }
+        catch {
+            // ignore
+        }
+        return {
+            ok: false,
+            exit_code: null,
+            note: err instanceof Error ? err.message : String(err),
+        };
+    }
+}
+export async function runHarnessSetupScript(script, extraArgs = []) {
+    const scriptPath = join(PKG_ROOT, "scripts", `${script}.ts`);
+    if (!existsSync(scriptPath)) {
+        return {
+            ok: false,
+            exit_code: null,
+            note: `script not found: ${scriptPath}`,
+        };
+    }
+    // pnpm exec resolves tsx from the harness pkg's node_modules; we stay
+    // in PKG_ROOT so workspace-style filtering doesn't matter.
+    return runInherit("pnpm", ["exec", "tsx", scriptPath, ...extraArgs], PKG_ROOT);
+}
+function runInherit(command, args, cwd) {
+    return new Promise((resolveP) => {
+        const child = spawn(command, args, {
+            stdio: "inherit",
+            ...(cwd !== undefined ? { cwd } : {}),
+        });
+        child.on("error", (err) => {
+            resolveP({ ok: false, exit_code: null, note: String(err) });
+        });
+        child.on("exit", (code) => {
+            resolveP({ ok: code === 0, exit_code: code });
+        });
+    });
+}
+//# sourceMappingURL=setup-runners.js.map

package/dist/init/setup-runners.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"setup-runners.js","sourceRoot":"","sources":["../../src/init/setup-runners.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,KAAK,EAAE,MAAM,oBAAoB,CAAC;AAC3C,OAAO,EAAE,iBAAiB,EAAE,UAAU,EAAE,SAAS,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACzF,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACnD,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AACzC,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAClC,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAE5C,MAAM,IAAI,GAAG,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;AACrD,4DAA4D;AAC5D,MAAM,QAAQ,GAAG,OAAO,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,CAAC,CAAC;AAE3C,MAAM,iBAAiB,GAAG,IAAI,CAAC,OAAO,EAAE,EAAE,QAAQ,EAAE,SAAS,EAAE,QAAQ,CAAC,CAAC;AACzE,MAAM,kBAAkB,GAAG,8BAA8B,CAAC;AAC1D,MAAM,iBAAiB,GACrB,sGAAsG,CAAC;AASzG,MAAM,CAAC,KAAK,UAAU,oBAAoB;IACxC,SAAS,CAAC,iBAAiB,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAClD,MAAM,GAAG,GAAG,IAAI,CAAC,iBAAiB,EAAE,kBAAkB,CAAC,CAAC;IACxD,IAAI,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;QACpB,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC,EAAE,IAAI,EAAE,uBAAuB,EAAE,CAAC;IACnE,CAAC;IACD,OAAO,oBAAoB,CAAC;QAC1B,GAAG,EAAE,iBAAiB;QACtB,QAAQ,EAAE,GAAG;QACb,KAAK,EAAE,2BAA2B;KACnC,CAAC,CAAC;AACL,CAAC;AAQD;;;;;GAKG;AACH,KAAK,UAAU,oBAAoB,CAAC,IAAkB;IACpD,IAAI,QAAkB,CAAC;IACvB,IAAI,CAAC;QACH,QAAQ,GAAG,MAAM,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IACnC,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,OAAO;YACL,EAAE,EAAE,KAAK;YACT,SAAS,EAAE,IAAI;YACf,IAAI,EAAE,kBAAkB,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE;SAC3E,CAAC;IACJ,CAAC;IACD,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC;QACjB,OAAO;YACL,EAAE,EAAE,KAAK;YACT,SAAS,EAAE,QAAQ,CAAC,MAAM;YAC1B,IAAI,EAAE,QAAQ,QAAQ,CAAC,MAAM,IAAI,QAAQ,CAAC,UAAU,EAAE;SACvD,CAAC;IACJ,CAAC;IACD,MAAM,SAAS,GAAG,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,gBAAgB,CAAC,CAAC;IACzD,MAAM,KAAK,GACT,SAAS,KAAK,IAAI,IAAI,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,QAAQ,CAAC,SAAS,EAAE,EAAE,CAAC,CAAC;QACnE,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAC,SAAS,EAAE,EAAE,CAAC;QAChC,CAAC,CAAC,CAAC,CAAC;IAER,IAAI,QAAQ,CAAC,IAAI,KAAK,IAAI,EAAE,CAAC;QAC3B,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,SAAS,EAAE,IAAI,EAAE,IAAI,EAAE,qBAAqB,EAAE,CAAC;IACrE,CAAC;IAED,MAAM,IAAI,GAAG,iBAAiB,CAAC,IAAI,CAAC,QAAQ,EAAE,EAAE,KAAK,EAAE,GAAG,EAAE,CAAC,CAAC;IAC9D,MAAM,QAAQ,GAAG,aAAa,CAAC,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,KAAK,EAAE,IAAI,CAAC,GAAG,CAAC,KAAK,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC;IACjF,IAAI,QAAQ,GAAG,CAAC,CAAC;IACjB,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;IAC7B,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,QAAQ,CAAC,IAAI,CAAC,SAAS,EAAE,CAAC;QACzC,IAAI,IAAI,GAAG,CAAC,CAAC;QACb,OAAO,IAAI,EAAE,CAAC;YACZ,MAAM,EAAE,KAAK,EAAE,IAAI,EAAE,GAAG,MAAM,MAAM,CAAC,IAAI,EAAE,CAAC;YAC5C,IAAI,IAAI;gBAAE,MAAM;YAChB,QAAQ,IAAI,KAAK,CAAC,UAAU,CAAC;YAC7B,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;YAClB,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;YACvB,IAAI,GAAG,GAAG,IAAI,GAAG,EAAE,EAAE,CAAC;gBACpB,MAAM,UAAU,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,GAAG,GAAG,SAAS,CAAC,GAAG,IAAI,EAAE,KAAK,CAAC,CAAC;gBAC7D,MAAM,OAAO,GAAG,CAAC,QAAQ,GAAG,UAAU,GAAG,SAAS,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;gBAC/D,QAAQ,CAAC,GAAG,CAAC,QAAQ,EAAE,EAAE,OAAO,EAAE,CAAC,CAAC;gBACpC,IAAI,GAAG,GAAG,CAAC;YACb,CAAC;QACH,CAAC;QACD,IAAI,CAAC,GAAG,EAAE,CAAC;QACX,MAAM,IAAI,OAAO,CAAO,CAAC,QAAQ,EAAE,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,GAAG,EAAE,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC;QAC1E,QAAQ,CAAC,GAAG,CAAC,QAAQ,EAAE;YACrB,OAAO,EAAE,CAAC,CAAC,QAAQ,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,SAAS,CAAC,GAAG,IAAI,EAAE,KAAK,CAAC,GAAG,SAAS,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;SAChG,CAAC,CAAC;QACH,QAAQ,CAAC,IAAI,CAAC,IAAI,EAAE,6BAA6B,CAAC,QAAQ,GAAG,SAAS,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC;QACzF,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC,EAAE,CAAC;IACpC,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,QAAQ,CAAC,IAAI,CAAC,KAAK,EAAE,iBAAiB,CAAC,CAAC;QACxC,IAAI,CAAC;YACH,IAAI,CAAC,GAAG,EAAE,CAAC;QACb,CAAC;QAAC,MAAM,CAAC;YACP,SAAS;QACX,CAAC;QACD,IAAI,CAAC;YACH,IAAI,UAAU,CAAC,IAAI,CAAC,QAAQ,CAAC,IAAI,QAAQ,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,IAAI,GAAG,CAAC,KAAK,IAAI,QAAQ,CAAC,EAAE,CAAC;gBACpF,UAAU,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;YAC5B,CAAC;QACH,CAAC;QAAC,MAAM,CAAC;YACP,SAAS;QACX,CAAC;QACD,OAAO;YACL,EAAE,EAAE,KAAK;YACT,SAAS,EAAE,IAAI;YACf,IAAI,EAAE,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC;SACvD,CAAC;IACJ,CAAC;AACH,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,qBAAqB,CACzC,MAIsB,EACtB,YAAsB,EAAE;IAExB,MAAM,UAAU,GAAG,IAAI,CAAC,QAAQ,EAAE,SAAS,EAAE,GAAG,MAAM,KAAK,CAAC,CAAC;IAC7D,IAAI,CAAC,UAAU,CAAC,UAAU,CAAC,EAAE,CAAC;QAC5B,OAAO;YACL,EAAE,EAAE,KAAK;YACT,SAAS,EAAE,IAAI;YACf,IAAI,EAAE,qBAAqB,UAAU,EAAE;SACxC,CAAC;IACJ,CAAC;IACD,sEAAsE;IACtE,2DAA2D;IAC3D,OAAO,UAAU,CACf,MAAM,EACN,CAAC,MAAM,EAAE,KAAK,EAAE,UAAU,EAAE,GAAG,SAAS,CAAC,EACzC,QAAQ,CACT,CAAC;AACJ,CAAC;AAED,SAAS,UAAU,CACjB,OAAe,EACf,IAAc,EACd,GAAY;IAEZ,OAAO,IAAI,OAAO,CAAC,CAAC,QAAQ,EAAE,EAAE;QAC9B,MAAM,KAAK,GAAG,KAAK,CAAC,OAAO,EAAE,IAAI,EAAE;YACjC,KAAK,EAAE,SAAS;YAChB,GAAG,CAAC,GAAG,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SACtC,CAAC,CAAC;QACH,KAAK,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,GAAG,EAAE,EAAE;YACxB,QAAQ,CAAC,EAAE,EAAE,EAAE,KAAK,EAAE,SAAS,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QAC9D,CAAC,CAAC,CAAC;QACH,KAAK,CAAC,EAAE,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,EAAE;YACxB,QAAQ,CAAC,EAAE,EAAE,EAAE,IAAI,KAAK,CAAC,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QAChD,CAAC,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist/init/source-comments/classify.d.ts

@@ -0,0 +1,98 @@
+/**
+ * Phase 7b — Haiku batch classifier for source-comment blocks.
+ *
+ * Walker outputs essay-style comment blocks; this module batches 20 per Haiku
+ * call and returns one classification per block. Per spec §15 the categories
+ * are: rationale | constraint | citation | license | other.
+ *
+ * Cost ceiling: full (operator picked "no cap" per RESUME §Open / deferred).
+ *
+ * Resilience:
+ *   - one batch failure doesn't fail the run; the block is reported as
+ *     `failed` with `kind: "other"` so the strip-replace stage skips it
+ *   - partial JSON returned by Haiku (e.g. missing block_id) is tolerated;
+ *     missing fields default to safe values
+ */
+import type { CommentBlock } from "./walker.js";
+export type CommentClassKind = "rationale" | "constraint" | "citation" | "license" | "other";
+export interface CommentClassification {
+    blockId: string;
+    kind: CommentClassKind;
+    /** Proposed DEC draft title — non-empty only when classifier suggests one. */
+    suggestedDecDraft: string;
+    /** Proposed §V invariant body — non-empty only when classifier suggests one. */
+    suggestedInvariant: string;
+    /** Canonical-map topic slug. */
+    suggestedCanonicalTopic: string;
+    /** True when the Haiku call (or batch parse) failed for this block. */
+    failed: boolean;
+    errorMessage?: string;
+}
+export interface ClassifyArgs {
+    blocks: CommentBlock[];
+    /**
+     * Optional progress callback fired after each batch completes. `index` is
+     * the 0-based batch index, `total` is the total number of batches.
+     */
+    onBatchProgress?: (row: {
+        index: number;
+        total: number;
+        classified: number;
+        failed: number;
+    }) => void;
+    /**
+     * Test override — when set, every block is classified by this function and
+     * no Haiku call is made.
+     */
+    mockClassify?: (block: CommentBlock) => CommentClassification;
+}
+export interface ClassifyResult {
+    classifications: CommentClassification[];
+    /** Approximate input tokens — sum over batches when usage is reported. */
+    inputTokens: number;
+    /** Approximate output tokens — sum over batches when usage is reported. */
+    outputTokens: number;
+    batchesRun: number;
+    batchesFailed: number;
+}
+export declare function classifyBlocks(args: ClassifyArgs): Promise<ClassifyResult>;
+declare function buildBatchPrompt(batch: CommentBlock[]): string;
+export declare const _internal: {
+    buildBatchPrompt: typeof buildBatchPrompt;
+    BATCH_SIZE: number;
+    BATCH_SCHEMA: {
+        readonly type: "object";
+        readonly additionalProperties: false;
+        readonly required: readonly ["results"];
+        readonly properties: {
+            readonly results: {
+                readonly type: "array";
+                readonly items: {
+                    readonly type: "object";
+                    readonly additionalProperties: false;
+                    readonly required: readonly ["block_id", "kind"];
+                    readonly properties: {
+                        readonly block_id: {
+                            readonly type: "string";
+                        };
+                        readonly kind: {
+                            readonly type: "string";
+                            readonly enum: readonly ["rationale", "constraint", "citation", "license", "other"];
+                        };
+                        readonly suggested_dec_draft: {
+                            readonly type: "string";
+                        };
+                        readonly suggested_invariant: {
+                            readonly type: "string";
+                        };
+                        readonly suggested_canonical_topic: {
+                            readonly type: "string";
+                        };
+                    };
+                };
+            };
+        };
+    };
+    SYSTEM_PROMPT: string;
+};
+export {};

package/dist/init/source-comments/classify.js

@@ -0,0 +1,244 @@
+/**
+ * Phase 7b — Haiku batch classifier for source-comment blocks.
+ *
+ * Walker outputs essay-style comment blocks; this module batches 20 per Haiku
+ * call and returns one classification per block. Per spec §15 the categories
+ * are: rationale | constraint | citation | license | other.
+ *
+ * Cost ceiling: full (operator picked "no cap" per RESUME §Open / deferred).
+ *
+ * Resilience:
+ *   - one batch failure doesn't fail the run; the block is reported as
+ *     `failed` with `kind: "other"` so the strip-replace stage skips it
+ *   - partial JSON returned by Haiku (e.g. missing block_id) is tolerated;
+ *     missing fields default to safe values
+ */
+import { runClaude } from "../../claude/index.js";
+import { logger } from "../../logger.js";
+const log = logger("init.source-comments.classify");
+const BATCH_SIZE = 20;
+const PER_BATCH_TIMEOUT_MS = 90_000;
+const PROSE_CAP_PER_BLOCK = 1500;
+/* -------------------------------------------------------------------------- */
+/* Schema                                                                     */
+/* -------------------------------------------------------------------------- */
+const BATCH_SCHEMA = {
+    type: "object",
+    additionalProperties: false,
+    required: ["results"],
+    properties: {
+        results: {
+            type: "array",
+            items: {
+                type: "object",
+                additionalProperties: false,
+                required: ["block_id", "kind"],
+                properties: {
+                    block_id: { type: "string" },
+                    kind: {
+                        type: "string",
+                        enum: ["rationale", "constraint", "citation", "license", "other"],
+                    },
+                    suggested_dec_draft: { type: "string" },
+                    suggested_invariant: { type: "string" },
+                    suggested_canonical_topic: { type: "string" },
+                },
+            },
+        },
+    },
+};
+const SYSTEM_PROMPT = `You classify source-code comment blocks for Cairn adoption.
+
+Each comment block in the batch has:
+  - block_id   — the stable identifier you must echo back
+  - file       — repo-relative source path
+  - lang       — language token (js/py/rs/go/...)
+  - kind       — block | jsdoc | line-cluster | license
+  - prose      — the comment text with markers stripped
+
+Return JSON: { "results": [ { block_id, kind, suggested_dec_draft?, suggested_invariant?, suggested_canonical_topic? } ] }
+
+\`kind\` choices:
+  - "rationale"  comment explains *why* a non-obvious choice was made (DEC candidate)
+  - "constraint" comment states a domain/system invariant (§V candidate)
+  - "citation"   comment is a reference to docs/spec/issue (canonical-map candidate)
+  - "license"    comment is a license / copyright header — pass through, never strip
+  - "other"      banal narration ("returns the user object"), TODO chatter, debug notes
+
+Heuristics:
+  - One sentence about what code does = "other".
+  - Multi-paragraph rationale tying behavior to a domain rule = "rationale".
+  - Hard-coded business rule that's wrong if violated = "constraint".
+  - Cross-reference to RFC / spec / ticket / docs = "citation".
+
+Optional fields:
+  - suggested_dec_draft        5-10 word imperative title; populate only for "rationale"
+  - suggested_invariant        1-sentence invariant body; populate only for "constraint"
+  - suggested_canonical_topic  kebab-case topic slug; populate when topic is clear
+
+Be conservative. When in doubt, "other". Always echo the block_id verbatim.`;
+/* -------------------------------------------------------------------------- */
+/* Public API                                                                 */
+/* -------------------------------------------------------------------------- */
+export async function classifyBlocks(args) {
+    const blocks = args.blocks;
+    const total = Math.ceil(blocks.length / BATCH_SIZE);
+    const out = new Array(blocks.length);
+    if (args.mockClassify !== undefined) {
+        for (let i = 0; i < blocks.length; i++) {
+            const b = blocks[i];
+            if (b === undefined)
+                continue;
+            out[i] = args.mockClassify(b);
+        }
+        return {
+            classifications: out,
+            inputTokens: 0,
+            outputTokens: 0,
+            batchesRun: total,
+            batchesFailed: 0,
+        };
+    }
+    let inputTokens = 0;
+    let outputTokens = 0;
+    let batchesRun = 0;
+    let batchesFailed = 0;
+    for (let batchIdx = 0; batchIdx < total; batchIdx++) {
+        const start = batchIdx * BATCH_SIZE;
+        const end = Math.min(start + BATCH_SIZE, blocks.length);
+        const batch = blocks.slice(start, end);
+        let batchResult;
+        try {
+            batchResult = await classifyOneBatch(batch);
+            batchesRun += 1;
+            inputTokens += batchResult.inputTokens;
+            outputTokens += batchResult.outputTokens;
+        }
+        catch (err) {
+            batchesFailed += 1;
+            const msg = err instanceof Error ? err.message : String(err);
+            log.warn({ batchIdx, total, err: msg }, "batch classify failed");
+            batchResult = {
+                byId: new Map(),
+                inputTokens: 0,
+                outputTokens: 0,
+                errorMessage: msg,
+            };
+        }
+        for (let i = 0; i < batch.length; i++) {
+            const b = batch[i];
+            if (b === undefined)
+                continue;
+            const pre = batchResult.byId.get(b.id);
+            if (pre !== undefined) {
+                out[start + i] = pre;
+            }
+            else {
+                out[start + i] = {
+                    blockId: b.id,
+                    kind: b.kind === "license" ? "license" : "other",
+                    suggestedDecDraft: "",
+                    suggestedInvariant: "",
+                    suggestedCanonicalTopic: "",
+                    failed: batchResult.errorMessage !== undefined,
+                    ...(batchResult.errorMessage !== undefined
+                        ? { errorMessage: batchResult.errorMessage }
+                        : {}),
+                };
+            }
+        }
+        args.onBatchProgress?.({
+            index: batchIdx,
+            total,
+            classified: out.filter((c) => c !== undefined && !c.failed).length,
+            failed: out.filter((c) => c !== undefined && c.failed).length,
+        });
+    }
+    return {
+        classifications: out,
+        inputTokens,
+        outputTokens,
+        batchesRun,
+        batchesFailed,
+    };
+}
+async function classifyOneBatch(batch) {
+    const prompt = buildBatchPrompt(batch);
+    const result = await runClaude({
+        tier: "haiku",
+        system: SYSTEM_PROMPT,
+        prompt,
+        jsonSchema: BATCH_SCHEMA,
+        timeoutMs: PER_BATCH_TIMEOUT_MS,
+    });
+    const usage = result.usage;
+    const inputTokens = typeof usage?.["input_tokens"] === "number" ? usage["input_tokens"] : 0;
+    const outputTokens = typeof usage?.["output_tokens"] === "number" ? usage["output_tokens"] : 0;
+    const parsed = result.parsed;
+    if (typeof parsed !== "object" || parsed === null) {
+        throw new Error("haiku batch returned non-object payload");
+    }
+    const obj = parsed;
+    const arr = Array.isArray(obj["results"]) ? obj["results"] : [];
+    const byId = new Map();
+    for (const entryRaw of arr) {
+        if (typeof entryRaw !== "object" || entryRaw === null)
+            continue;
+        const entry = entryRaw;
+        const blockId = typeof entry["block_id"] === "string" ? entry["block_id"] : "";
+        if (blockId.length === 0)
+            continue;
+        const kindRaw = entry["kind"];
+        const kind = kindRaw === "rationale" ||
+            kindRaw === "constraint" ||
+            kindRaw === "citation" ||
+            kindRaw === "license"
+            ? kindRaw
+            : "other";
+        byId.set(blockId, {
+            blockId,
+            kind,
+            suggestedDecDraft: typeof entry["suggested_dec_draft"] === "string"
+                ? entry["suggested_dec_draft"]
+                : "",
+            suggestedInvariant: typeof entry["suggested_invariant"] === "string"
+                ? entry["suggested_invariant"]
+                : "",
+            suggestedCanonicalTopic: typeof entry["suggested_canonical_topic"] === "string"
+                ? entry["suggested_canonical_topic"]
+                : "",
+            failed: false,
+        });
+    }
+    return { byId, inputTokens, outputTokens };
+}
+function buildBatchPrompt(batch) {
+    const lines = [];
+    lines.push(`You are classifying ${batch.length} source-comment block${batch.length === 1 ? "" : "s"}.`);
+    lines.push("Echo every block_id in the same order. Use the schema exactly. Be terse.");
+    lines.push("");
+    for (const b of batch) {
+        const prose = b.prose.length > PROSE_CAP_PER_BLOCK
+            ? `${b.prose.slice(0, PROSE_CAP_PER_BLOCK)}\n…[truncated]`
+            : b.prose;
+        lines.push("---");
+        lines.push(`block_id: ${b.id}`);
+        lines.push(`file: ${b.file}`);
+        lines.push(`lang: ${b.lang}`);
+        lines.push(`kind: ${b.kind}`);
+        lines.push(`lines: ${b.lineCount}`);
+        lines.push(`words: ${b.wordCount}`);
+        lines.push("prose: |");
+        for (const line of prose.split("\n")) {
+            lines.push(`  ${line}`);
+        }
+    }
+    return lines.join("\n");
+}
+export const _internal = {
+    buildBatchPrompt,
+    BATCH_SIZE,
+    BATCH_SCHEMA,
+    SYSTEM_PROMPT,
+};
+//# sourceMappingURL=classify.js.map

package/dist/init/source-comments/classify.js.map

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

package/dist/init/source-comments/index.d.ts

@@ -0,0 +1,8 @@
+export { HEURISTIC, detectLang, walkSourceComments, } from "./walker.js";
+export type { CommentBlock, CommentKind, CommentLang, WalkOptions, WalkResult, } from "./walker.js";
+export { classifyBlocks, _internal as _classifyInternal, } from "./classify.js";
+export type { ClassifyArgs, ClassifyResult, CommentClassKind, CommentClassification, } from "./classify.js";
+export { runSourceCommentsIngestion } from "./ingest.js";
+export type { IngestSourceCommentsArgs, IngestSourceCommentsResult, } from "./ingest.js";
+export { applyStripReplace, previewStripReplace, _internal as _stripReplaceInternal, } from "./strip-replace.js";
+export type { DirtyDecision, FileOutcome, ReplaceItem, SkipReason, StripReplaceArgs, StripReplaceResult, } from "./strip-replace.js";

package/dist/init/source-comments/index.js

@@ -0,0 +1,5 @@
+export { HEURISTIC, detectLang, walkSourceComments, } from "./walker.js";
+export { classifyBlocks, _internal as _classifyInternal, } from "./classify.js";
+export { runSourceCommentsIngestion } from "./ingest.js";
+export { applyStripReplace, previewStripReplace, _internal as _stripReplaceInternal, } from "./strip-replace.js";
+//# sourceMappingURL=index.js.map

package/dist/init/source-comments/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/init/source-comments/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,SAAS,EACT,UAAU,EACV,kBAAkB,GACnB,MAAM,aAAa,CAAC;AAQrB,OAAO,EACL,cAAc,EACd,SAAS,IAAI,iBAAiB,GAC/B,MAAM,eAAe,CAAC;AAOvB,OAAO,EAAE,0BAA0B,EAAE,MAAM,aAAa,CAAC;AAKzD,OAAO,EACL,iBAAiB,EACjB,mBAAmB,EACnB,SAAS,IAAI,qBAAqB,GACnC,MAAM,oBAAoB,CAAC"}

package/dist/init/source-comments/ingest.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Phase 7b orchestrator — walker → classifier → persist.
+ *
+ * Output:
+ *   - DEC drafts (one per "rationale" classification with non-empty title)
+ *     written to `.cairn/ground/decisions/_inbox/<id>.draft.md`
+ *   - Invariant proposals appended to
+ *     `.cairn/baseline/invariant-proposals-<ISO>.yaml`
+ *   - Canonical-map citations appended to
+ *     `.cairn/baseline/canonical-citations-<ISO>.yaml`
+ *   - Full audit (every block + classification) at
+ *     `.cairn/baseline/source-comments-<ISO>.yaml` — consumed by the
+ *     strip-replace stage so it doesn't have to re-walk.
+ */
+import type { ClassifyArgs, CommentClassification, CommentClassKind } from "./classify.js";
+import type { WalkOptions, WalkResult } from "./walker.js";
+export interface IngestSourceCommentsArgs {
+    repoRoot: string;
+    /** Forwarded to walker — typically left undefined for full-repo walks. */
+    walkOptions?: Partial<WalkOptions>;
+    /** Forwarded to classifier (for tests / mock runs). */
+    mockClassify?: ClassifyArgs["mockClassify"];
+    /** Optional progress hook for batch-level updates. */
+    onBatchProgress?: ClassifyArgs["onBatchProgress"];
+    /** When true, no DEC drafts / proposals / citations are written. */
+    dryRun?: boolean;
+    /** When set, override `Date.now()` for deterministic test outputs. */
+    nowIso?: string;
+}
+export interface IngestSourceCommentsResult {
+    walk: WalkResult;
+    classifications: CommentClassification[];
+    decDraftsWritten: {
+        id: string;
+        path: string;
+        sourceFile: string;
+    }[];
+    invariantProposalsAdded: number;
+    canonicalCitationsAdded: number;
+    auditPath: string;
+    auditRelPath: string;
+    invariantProposalsPath: string | null;
+    canonicalCitationsPath: string | null;
+    inputTokens: number;
+    outputTokens: number;
+    batchesRun: number;
+    batchesFailed: number;
+    /** Distribution by classifier kind. */
+    kindCounts: Record<CommentClassKind, number>;
+}
+export declare function runSourceCommentsIngestion(args: IngestSourceCommentsArgs): Promise<IngestSourceCommentsResult>;