@mneme-ai/core 0.22.2 → 0.24.0

package/dist/htc/abstract.d.ts

@@ -0,0 +1,41 @@
+/**
+ * HTC Layer 1 — semantic abstracts.
+ *
+ * For each commit, ask the enricher to condense subject+body+files into ~30
+ * tokens of plain-English meaning. The result is cached forever (token cost
+ * paid once); subsequent queries reuse it without paying the LLM tax again.
+ *
+ * Prompt format is INTENTIONALLY rigid — consistency at the abstract layer
+ * keeps Layer 2 (cluster summaries) and Layer 3 (memoir) stable too.
+ */
+import type { AbstractResult, HtcEnricher } from "./types.js";
+/** System prompt — kept short + directive, no preamble allowed. */
+export declare const ABSTRACT_SYSTEM_PROMPT: string;
+export interface AbstractCommitInput {
+    hash: string;
+    subject: string;
+    body?: string;
+    files?: string[];
+}
+export interface AbstractInput {
+    commit: AbstractCommitInput;
+    enricher: HtcEnricher;
+}
+export declare function buildAbstractUserPrompt(commit: AbstractCommitInput): string;
+/** Generate a single ~30-token abstract for one commit. */
+export declare function generateAbstract(input: AbstractInput): Promise<AbstractResult>;
+export interface BatchAbstractOptions {
+    /** Concurrent in-flight enricher calls; default 3 (free providers like Groq rate-limit). */
+    concurrency?: number;
+    onProgress?: (done: number, total: number) => void;
+    onError?: (hash: string, err: string) => void;
+}
+/**
+ * Generate abstracts for many commits with a concurrency cap. Failures are
+ * recorded via onError but DO NOT abort the batch — the caller decides
+ * whether to retry the failed hashes.
+ *
+ * Returns one AbstractResult per SUCCESSFUL commit (failures omitted).
+ */
+export declare function generateAbstractsBatch(commits: AbstractCommitInput[], enricher: HtcEnricher, opts?: BatchAbstractOptions): Promise<AbstractResult[]>;
+//# sourceMappingURL=abstract.d.ts.map

package/dist/htc/abstract.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"abstract.d.ts","sourceRoot":"","sources":["../../src/htc/abstract.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,KAAK,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAG9D,mEAAmE;AACnE,eAAO,MAAM,sBAAsB,QAEuC,CAAC;AAE3E,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;CAClB;AAED,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,mBAAmB,CAAC;IAC5B,QAAQ,EAAE,WAAW,CAAC;CACvB;AAED,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,mBAAmB,GAAG,MAAM,CAe3E;AAED,2DAA2D;AAC3D,wBAAsB,gBAAgB,CAAC,KAAK,EAAE,aAAa,GAAG,OAAO,CAAC,cAAc,CAAC,CAwBpF;AAED,MAAM,WAAW,oBAAoB;IACnC,4FAA4F;IAC5F,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,UAAU,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IACnD,OAAO,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;CAC/C;AAED;;;;;;GAMG;AACH,wBAAsB,sBAAsB,CAC1C,OAAO,EAAE,mBAAmB,EAAE,EAC9B,QAAQ,EAAE,WAAW,EACrB,IAAI,GAAE,oBAAyB,GAC9B,OAAO,CAAC,cAAc,EAAE,CAAC,CA6B3B"}

package/dist/htc/abstract.js

@@ -0,0 +1,97 @@
+import { estimateTokens } from "./types.js";
+/** System prompt — kept short + directive, no preamble allowed. */
+export const ABSTRACT_SYSTEM_PROMPT = "You are a senior engineer condensing git commit data into ~30 tokens " +
+    "of plain-English meaning. Output ONLY the condensed text, no preamble.";
+export function buildAbstractUserPrompt(commit) {
+    const subject = commit.subject?.trim() || "(empty)";
+    const body = commit.body?.trim() ? commit.body.trim() : "(none)";
+    const files = (commit.files ?? []).slice(0, 3);
+    const filesLine = files.length ? files.join(", ") : "(none)";
+    return [
+        `Commit subject: ${subject}`,
+        `Body: ${body}`,
+        `Files (sample): ${filesLine}`,
+        "",
+        "Condense to ~30 tokens. Format: \"WHAT changed + WHY\". Examples:",
+        "  \"auth: replaced session cookies with JWT for stateless CDN deploys\"",
+        "  \"fix: AR property tap shows detail on Android — race in event listener\"",
+        "  \"refactor: split payment.ts into 3 modules so legacy + V2 can coexist\"",
+    ].join("\n");
+}
+/** Generate a single ~30-token abstract for one commit. */
+export async function generateAbstract(input) {
+    const start = Date.now();
+    const userPrompt = buildAbstractUserPrompt(input.commit);
+    const result = await input.enricher.enrich({
+        system: ABSTRACT_SYSTEM_PROMPT,
+        user: userPrompt,
+        // Cap output so the model can't blow past ~30 tokens; 80 = comfortable
+        // headroom for sub-word splits without inviting paragraphs.
+        maxTokens: 80,
+        // Low temp — we want stable, comparable abstracts across runs.
+        temperature: 0.2,
+    });
+    const generationMs = Date.now() - start;
+    const text = (result.text ?? "").trim();
+    // Strip wrapping quotes the model sometimes adds.
+    const abstract = stripWrappingQuotes(text);
+    return {
+        hash: input.commit.hash,
+        abstract,
+        tokenCount: estimateTokens(abstract),
+        generationMs,
+        generator: input.enricher.name,
+        generatedAt: new Date().toISOString(),
+    };
+}
+/**
+ * Generate abstracts for many commits with a concurrency cap. Failures are
+ * recorded via onError but DO NOT abort the batch — the caller decides
+ * whether to retry the failed hashes.
+ *
+ * Returns one AbstractResult per SUCCESSFUL commit (failures omitted).
+ */
+export async function generateAbstractsBatch(commits, enricher, opts = {}) {
+    const concurrency = Math.max(1, opts.concurrency ?? 3);
+    const results = [];
+    let done = 0;
+    // Simple worker-pool: N workers pulling from a shared cursor.
+    let cursor = 0;
+    async function worker() {
+        while (true) {
+            const i = cursor++;
+            if (i >= commits.length)
+                return;
+            const c = commits[i];
+            try {
+                const r = await generateAbstract({ commit: c, enricher });
+                results.push(r);
+            }
+            catch (err) {
+                const msg = err?.message ?? String(err);
+                opts.onError?.(c.hash, msg);
+            }
+            finally {
+                done++;
+                opts.onProgress?.(done, commits.length);
+            }
+        }
+    }
+    const workers = [];
+    for (let i = 0; i < concurrency; i++)
+        workers.push(worker());
+    await Promise.all(workers);
+    return results;
+}
+function stripWrappingQuotes(s) {
+    if (s.length < 2)
+        return s;
+    const first = s.charCodeAt(0);
+    const last = s.charCodeAt(s.length - 1);
+    // ", ', or curly quotes
+    const QUOTES = [0x22, 0x27, 0x201c, 0x201d, 0x2018, 0x2019];
+    if (QUOTES.includes(first) && QUOTES.includes(last))
+        return s.slice(1, -1).trim();
+    return s;
+}
+//# sourceMappingURL=abstract.js.map

package/dist/htc/abstract.js.map

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

package/dist/htc/abstract.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=abstract.test.d.ts.map

package/dist/htc/abstract.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"abstract.test.d.ts","sourceRoot":"","sources":["../../src/htc/abstract.test.ts"],"names":[],"mappings":""}

package/dist/htc/abstract.test.js

@@ -0,0 +1,169 @@
+import { describe, it, expect, vi } from "vitest";
+import { ABSTRACT_SYSTEM_PROMPT, buildAbstractUserPrompt, generateAbstract, generateAbstractsBatch, } from "./abstract.js";
+import { estimateTokens } from "./types.js";
+function mockEnricher(text, name = "mock:test") {
+    return {
+        name,
+        enrich: vi.fn().mockResolvedValue({ text }),
+    };
+}
+describe("buildAbstractUserPrompt", () => {
+    it("includes subject + body + first 3 files", () => {
+        const prompt = buildAbstractUserPrompt({
+            hash: "a".repeat(40),
+            subject: "fix: race in event listener",
+            body: "Android only — touch event fired before render flush.",
+            files: ["app/AR.tsx", "app/utils/events.ts", "app/test.ts", "app/extra.ts"],
+        });
+        expect(prompt).toContain("fix: race in event listener");
+        expect(prompt).toContain("Android only");
+        expect(prompt).toContain("app/AR.tsx, app/utils/events.ts, app/test.ts");
+        // Only first 3 files — extra.ts must be excluded.
+        expect(prompt).not.toContain("app/extra.ts");
+    });
+    it("falls back to '(empty)' / '(none)' when fields missing", () => {
+        const prompt = buildAbstractUserPrompt({ hash: "x", subject: "" });
+        expect(prompt).toContain("Commit subject: (empty)");
+        expect(prompt).toContain("Body: (none)");
+        expect(prompt).toContain("Files (sample): (none)");
+    });
+    it("includes the rigid format examples (consistency anchor)", () => {
+        const prompt = buildAbstractUserPrompt({ hash: "x", subject: "anything" });
+        expect(prompt).toContain("WHAT changed + WHY");
+        expect(prompt).toContain("auth: replaced session cookies with JWT");
+    });
+});
+describe("generateAbstract", () => {
+    it("calls enricher with system + user prompts and returns AbstractResult", async () => {
+        const enricher = mockEnricher("auth: replaced session cookies with JWT for stateless CDN deploys", "ollama:qwen2.5:3b");
+        const r = await generateAbstract({
+            commit: {
+                hash: "a".repeat(40),
+                subject: "auth: switch to JWT",
+                body: "Sessions don't replicate across CDN.",
+                files: ["src/auth.ts"],
+            },
+            enricher,
+        });
+        expect(r.hash).toBe("a".repeat(40));
+        expect(r.abstract).toContain("JWT");
+        expect(r.generator).toBe("ollama:qwen2.5:3b");
+        expect(r.tokenCount).toBeGreaterThan(0);
+        expect(r.generationMs).toBeGreaterThanOrEqual(0);
+        expect(r.generatedAt).toBeDefined();
+        expect(enricher.enrich).toHaveBeenCalledTimes(1);
+        const call = enricher.enrich.mock.calls[0][0];
+        expect(call.system).toBe(ABSTRACT_SYSTEM_PROMPT);
+        expect(call.user).toContain("auth: switch to JWT");
+        expect(call.maxTokens).toBe(80);
+    });
+    it("token count math = ceil(words * 1.3)", () => {
+        // 10 words → ceil(10 * 1.3) = 13
+        expect(estimateTokens("one two three four five six seven eight nine ten")).toBe(13);
+        expect(estimateTokens("")).toBe(0);
+        expect(estimateTokens("   ")).toBe(0);
+    });
+    it("strips wrapping straight + curly quotes from model output", async () => {
+        const enricher = mockEnricher('"refactor: split payment.ts into 3 modules"');
+        const r = await generateAbstract({
+            commit: { hash: "h", subject: "refactor" },
+            enricher,
+        });
+        expect(r.abstract.startsWith('"')).toBe(false);
+        expect(r.abstract.endsWith('"')).toBe(false);
+        expect(r.abstract).toBe("refactor: split payment.ts into 3 modules");
+        const enricher2 = mockEnricher("“feat: X”");
+        const r2 = await generateAbstract({
+            commit: { hash: "h", subject: "feat" },
+            enricher: enricher2,
+        });
+        expect(r2.abstract).toBe("feat: X");
+    });
+    it("trims whitespace around the model's text", async () => {
+        const enricher = mockEnricher("   feat: trim me   \n\n");
+        const r = await generateAbstract({
+            commit: { hash: "h", subject: "x" },
+            enricher,
+        });
+        expect(r.abstract).toBe("feat: trim me");
+    });
+});
+describe("generateAbstractsBatch", () => {
+    it("processes every commit and returns one result each", async () => {
+        const enricher = mockEnricher("abstract text");
+        const commits = Array.from({ length: 5 }, (_, i) => ({
+            hash: String(i).padStart(40, "0"),
+            subject: `subject ${i}`,
+        }));
+        const out = await generateAbstractsBatch(commits, enricher, { concurrency: 2 });
+        expect(out).toHaveLength(5);
+        expect(enricher.enrich).toHaveBeenCalledTimes(5);
+    });
+    it("emits onProgress for every completion", async () => {
+        const enricher = mockEnricher("ok");
+        const onProgress = vi.fn();
+        const commits = [
+            { hash: "a".repeat(40), subject: "1" },
+            { hash: "b".repeat(40), subject: "2" },
+            { hash: "c".repeat(40), subject: "3" },
+        ];
+        await generateAbstractsBatch(commits, enricher, { concurrency: 2, onProgress });
+        expect(onProgress).toHaveBeenCalledTimes(3);
+        // Last call should have done === total.
+        const last = onProgress.mock.calls[onProgress.mock.calls.length - 1];
+        expect(last[0]).toBe(3);
+        expect(last[1]).toBe(3);
+    });
+    it("records errors via onError without aborting the batch", async () => {
+        const enricher = {
+            name: "mock:flaky",
+            enrich: vi.fn().mockImplementation((input) => {
+                if (input.user.includes("FAIL")) {
+                    return Promise.reject(new Error("rate-limit hit"));
+                }
+                return Promise.resolve({ text: "ok" });
+            }),
+        };
+        const onError = vi.fn();
+        const commits = [
+            { hash: "a".repeat(40), subject: "good 1" },
+            { hash: "b".repeat(40), subject: "FAIL me" },
+            { hash: "c".repeat(40), subject: "good 2" },
+        ];
+        const out = await generateAbstractsBatch(commits, enricher, {
+            concurrency: 1,
+            onError,
+        });
+        expect(out).toHaveLength(2); // failures excluded
+        expect(onError).toHaveBeenCalledTimes(1);
+        expect(onError.mock.calls[0][0]).toBe("b".repeat(40));
+        expect(onError.mock.calls[0][1]).toContain("rate-limit");
+    });
+    it("respects concurrency cap (≤ N in flight)", async () => {
+        let inFlight = 0;
+        let peak = 0;
+        const enricher = {
+            name: "mock:concurrent",
+            enrich: vi.fn().mockImplementation(async () => {
+                inFlight++;
+                peak = Math.max(peak, inFlight);
+                await new Promise((r) => setTimeout(r, 5));
+                inFlight--;
+                return { text: "ok" };
+            }),
+        };
+        const commits = Array.from({ length: 10 }, (_, i) => ({
+            hash: String(i).padStart(40, "0"),
+            subject: `s${i}`,
+        }));
+        await generateAbstractsBatch(commits, enricher, { concurrency: 3 });
+        expect(peak).toBeLessThanOrEqual(3);
+        expect(peak).toBeGreaterThan(0);
+    });
+    it("defaults concurrency to 3 when not specified", async () => {
+        const enricher = mockEnricher("ok");
+        const out = await generateAbstractsBatch([{ hash: "a".repeat(40), subject: "x" }], enricher);
+        expect(out).toHaveLength(1);
+    });
+});
+//# sourceMappingURL=abstract.test.js.map

package/dist/htc/abstract.test.js.map

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

package/dist/htc/clusters.d.ts

@@ -0,0 +1,38 @@
+/**
+ * HTC Layer 2 — topic cluster summaries.
+ *
+ * Takes pre-built clusters (from insights/cluster.buildClusters) plus the
+ * cached Layer-1 abstracts and asks the enricher to roll each cluster up
+ * into a ~100-token paragraph: topic + major changes + sequence.
+ *
+ * The cluster's `label` is extracted from the LLM's output (first sentence
+ * heuristic). We never invent labels — if the model produces nothing
+ * usable, we fall back to "cluster <id>".
+ */
+import type { ClusterSummary, HtcEnricher } from "./types.js";
+export declare const CLUSTER_SYSTEM_PROMPT: string;
+export interface ClusterInput {
+    /** Stable cluster identifier; persisted as cluster_id. */
+    id: string;
+    memberHashes: string[];
+}
+export interface GenerateClusterSummariesOptions {
+    concurrency?: number;
+    onProgress?: (done: number, total: number) => void;
+    onError?: (clusterId: string, err: string) => void;
+}
+export declare function buildClusterUserPrompt(abstracts: string[]): string;
+/**
+ * Extract a short topic label from the LLM's summary. Heuristic: take the
+ * first colon-prefixed phrase ("auth: …") OR the first 4 words of the first
+ * sentence. Caps at ~40 chars. Never invents — falls back to caller-provided
+ * fallback when the summary is empty.
+ */
+export declare function extractLabel(summary: string, fallback: string): string;
+export declare function generateClusterSummary(cluster: ClusterInput, abstracts: Map<string, string>, enricher: HtcEnricher): Promise<ClusterSummary>;
+/**
+ * Batch summary generation with bounded concurrency. Failures recorded via
+ * onError; the surviving results are returned.
+ */
+export declare function generateClusterSummaries(abstracts: Map<string, string>, clusters: ClusterInput[], enricher: HtcEnricher, opts?: GenerateClusterSummariesOptions): Promise<ClusterSummary[]>;
+//# sourceMappingURL=clusters.d.ts.map

package/dist/htc/clusters.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"clusters.d.ts","sourceRoot":"","sources":["../../src/htc/clusters.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,OAAO,KAAK,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAG9D,eAAO,MAAM,qBAAqB,QAGmB,CAAC;AAEtD,MAAM,WAAW,YAAY;IAC3B,0DAA0D;IAC1D,EAAE,EAAE,MAAM,CAAC;IACX,YAAY,EAAE,MAAM,EAAE,CAAC;CACxB;AAED,MAAM,WAAW,+BAA+B;IAC9C,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,UAAU,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IACnD,OAAO,CAAC,EAAE,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;CACpD;AAED,wBAAgB,sBAAsB,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,MAAM,CAOlE;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAUtE;AAED,wBAAsB,sBAAsB,CAC1C,OAAO,EAAE,YAAY,EACrB,SAAS,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,EAC9B,QAAQ,EAAE,WAAW,GACpB,OAAO,CAAC,cAAc,CAAC,CAoCzB;AAED;;;GAGG;AACH,wBAAsB,wBAAwB,CAC5C,SAAS,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,EAC9B,QAAQ,EAAE,YAAY,EAAE,EACxB,QAAQ,EAAE,WAAW,EACrB,IAAI,GAAE,+BAAoC,GACzC,OAAO,CAAC,cAAc,EAAE,CAAC,CA4B3B"}

package/dist/htc/clusters.js

@@ -0,0 +1,103 @@
+import { estimateTokens } from "./types.js";
+export const CLUSTER_SYSTEM_PROMPT = "Summarize a group of related git commits into ~100 tokens. Output a brief " +
+    "paragraph that names the topic, lists the major changes, and notes any " +
+    "sequence (e.g. \"started with X, evolved to Y\").";
+export function buildClusterUserPrompt(abstracts) {
+    const lines = ["Commit abstracts (one per line):"];
+    for (const a of abstracts) {
+        const trimmed = a.trim();
+        if (trimmed)
+            lines.push(`  - ${trimmed}`);
+    }
+    return lines.join("\n");
+}
+/**
+ * Extract a short topic label from the LLM's summary. Heuristic: take the
+ * first colon-prefixed phrase ("auth: …") OR the first 4 words of the first
+ * sentence. Caps at ~40 chars. Never invents — falls back to caller-provided
+ * fallback when the summary is empty.
+ */
+export function extractLabel(summary, fallback) {
+    const trimmed = summary.trim();
+    if (!trimmed)
+        return fallback;
+    // Pattern A: "topic: rest of sentence"
+    const colonMatch = trimmed.match(/^([A-Za-z0-9 _\-/.]{2,40}?):/);
+    if (colonMatch)
+        return colonMatch[1].trim().toLowerCase();
+    // Pattern B: first sentence, first 4 words.
+    const firstSentence = trimmed.split(/[.!?\n]/)[0].trim();
+    const words = firstSentence.split(/\s+/).slice(0, 4).join(" ");
+    return (words || fallback).slice(0, 40).toLowerCase();
+}
+export async function generateClusterSummary(cluster, abstracts, enricher) {
+    // Pull the abstracts for this cluster's members. Missing ones are skipped
+    // (caller should ensure Layer 1 was generated; we don't refuse, but a
+    // cluster with zero abstracts can't be summarized usefully).
+    const memberAbstracts = [];
+    for (const hash of cluster.memberHashes) {
+        const a = abstracts.get(hash);
+        if (a)
+            memberAbstracts.push(a);
+    }
+    if (memberAbstracts.length === 0) {
+        throw new Error(`Cluster ${cluster.id} has no Layer-1 abstracts available; generate abstracts first.`);
+    }
+    const start = Date.now();
+    const result = await enricher.enrich({
+        system: CLUSTER_SYSTEM_PROMPT,
+        user: buildClusterUserPrompt(memberAbstracts),
+        // ~100 tokens target → 200 cap leaves room without inviting essays.
+        maxTokens: 200,
+        temperature: 0.3,
+    });
+    const generationMs = Date.now() - start;
+    const summary = (result.text ?? "").trim();
+    const label = extractLabel(summary, `cluster ${cluster.id}`);
+    return {
+        clusterId: cluster.id,
+        label,
+        summary,
+        memberHashes: cluster.memberHashes,
+        tokenCount: estimateTokens(summary),
+        generationMs,
+        generator: enricher.name,
+        generatedAt: new Date().toISOString(),
+    };
+}
+/**
+ * Batch summary generation with bounded concurrency. Failures recorded via
+ * onError; the surviving results are returned.
+ */
+export async function generateClusterSummaries(abstracts, clusters, enricher, opts = {}) {
+    const concurrency = Math.max(1, opts.concurrency ?? 3);
+    const out = [];
+    let done = 0;
+    let cursor = 0;
+    async function worker() {
+        while (true) {
+            const i = cursor++;
+            if (i >= clusters.length)
+                return;
+            const c = clusters[i];
+            try {
+                const s = await generateClusterSummary(c, abstracts, enricher);
+                out.push(s);
+            }
+            catch (err) {
+                const msg = err?.message ?? String(err);
+                opts.onError?.(c.id, msg);
+            }
+            finally {
+                done++;
+                opts.onProgress?.(done, clusters.length);
+            }
+        }
+    }
+    const workers = [];
+    for (let i = 0; i < concurrency; i++)
+        workers.push(worker());
+    await Promise.all(workers);
+    return out;
+}
+//# sourceMappingURL=clusters.js.map

package/dist/htc/clusters.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"clusters.js","sourceRoot":"","sources":["../../src/htc/clusters.ts"],"names":[],"mappings":"AAYA,OAAO,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAE5C,MAAM,CAAC,MAAM,qBAAqB,GAChC,4EAA4E;IAC5E,yEAAyE;IACzE,mDAAmD,CAAC;AActD,MAAM,UAAU,sBAAsB,CAAC,SAAmB;IACxD,MAAM,KAAK,GAAG,CAAC,kCAAkC,CAAC,CAAC;IACnD,KAAK,MAAM,CAAC,IAAI,SAAS,EAAE,CAAC;QAC1B,MAAM,OAAO,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC;QACzB,IAAI,OAAO;YAAE,KAAK,CAAC,IAAI,CAAC,OAAO,OAAO,EAAE,CAAC,CAAC;IAC5C,CAAC;IACD,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC1B,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,YAAY,CAAC,OAAe,EAAE,QAAgB;IAC5D,MAAM,OAAO,GAAG,OAAO,CAAC,IAAI,EAAE,CAAC;IAC/B,IAAI,CAAC,OAAO;QAAE,OAAO,QAAQ,CAAC;IAC9B,uCAAuC;IACvC,MAAM,UAAU,GAAG,OAAO,CAAC,KAAK,CAAC,8BAA8B,CAAC,CAAC;IACjE,IAAI,UAAU;QAAE,OAAO,UAAU,CAAC,CAAC,CAAE,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;IAC3D,4CAA4C;IAC5C,MAAM,aAAa,GAAG,OAAO,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC,CAAC,CAAE,CAAC,IAAI,EAAE,CAAC;IAC1D,MAAM,KAAK,GAAG,aAAa,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IAC/D,OAAO,CAAC,KAAK,IAAI,QAAQ,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,WAAW,EAAE,CAAC;AACxD,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,sBAAsB,CAC1C,OAAqB,EACrB,SAA8B,EAC9B,QAAqB;IAErB,0EAA0E;IAC1E,sEAAsE;IACtE,6DAA6D;IAC7D,MAAM,eAAe,GAAa,EAAE,CAAC;IACrC,KAAK,MAAM,IAAI,IAAI,OAAO,CAAC,YAAY,EAAE,CAAC;QACxC,MAAM,CAAC,GAAG,SAAS,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QAC9B,IAAI,CAAC;YAAE,eAAe,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IACjC,CAAC;IACD,IAAI,eAAe,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACjC,MAAM,IAAI,KAAK,CACb,WAAW,OAAO,CAAC,EAAE,gEAAgE,CACtF,CAAC;IACJ,CAAC;IAED,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;IACzB,MAAM,MAAM,GAAG,MAAM,QAAQ,CAAC,MAAM,CAAC;QACnC,MAAM,EAAE,qBAAqB;QAC7B,IAAI,EAAE,sBAAsB,CAAC,eAAe,CAAC;QAC7C,oEAAoE;QACpE,SAAS,EAAE,GAAG;QACd,WAAW,EAAE,GAAG;KACjB,CAAC,CAAC;IACH,MAAM,YAAY,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,KAAK,CAAC;IACxC,MAAM,OAAO,GAAG,CAAC,MAAM,CAAC,IAAI,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;IAC3C,MAAM,KAAK,GAAG,YAAY,CAAC,OAAO,EAAE,WAAW,OAAO,CAAC,EAAE,EAAE,CAAC,CAAC;IAC7D,OAAO;QACL,SAAS,EAAE,OAAO,CAAC,EAAE;QACrB,KAAK;QACL,OAAO;QACP,YAAY,EAAE,OAAO,CAAC,YAAY;QAClC,UAAU,EAAE,cAAc,CAAC,OAAO,CAAC;QACnC,YAAY;QACZ,SAAS,EAAE,QAAQ,CAAC,IAAI;QACxB,WAAW,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;KACtC,CAAC;AACJ,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,wBAAwB,CAC5C,SAA8B,EAC9B,QAAwB,EACxB,QAAqB,EACrB,OAAwC,EAAE;IAE1C,MAAM,WAAW,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,WAAW,IAAI,CAAC,CAAC,CAAC;IACvD,MAAM,GAAG,GAAqB,EAAE,CAAC;IACjC,IAAI,IAAI,GAAG,CAAC,CAAC;IACb,IAAI,MAAM,GAAG,CAAC,CAAC;IAEf,KAAK,UAAU,MAAM;QACnB,OAAO,IAAI,EAAE,CAAC;YACZ,MAAM,CAAC,GAAG,MAAM,EAAE,CAAC;YACnB,IAAI,CAAC,IAAI,QAAQ,CAAC,MAAM;gBAAE,OAAO;YACjC,MAAM,CAAC,GAAG,QAAQ,CAAC,CAAC,CAAE,CAAC;YACvB,IAAI,CAAC;gBACH,MAAM,CAAC,GAAG,MAAM,sBAAsB,CAAC,CAAC,EAAE,SAAS,EAAE,QAAQ,CAAC,CAAC;gBAC/D,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;YACd,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,MAAM,GAAG,GAAI,GAAa,EAAE,OAAO,IAAI,MAAM,CAAC,GAAG,CAAC,CAAC;gBACnD,IAAI,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,EAAE,GAAG,CAAC,CAAC;YAC5B,CAAC;oBAAS,CAAC;gBACT,IAAI,EAAE,CAAC;gBACP,IAAI,CAAC,UAAU,EAAE,CAAC,IAAI,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;YAC3C,CAAC;QACH,CAAC;IACH,CAAC;IAED,MAAM,OAAO,GAAoB,EAAE,CAAC;IACpC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,WAAW,EAAE,CAAC,EAAE;QAAE,OAAO,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC;IAC7D,MAAM,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;IAC3B,OAAO,GAAG,CAAC;AACb,CAAC"}

package/dist/htc/clusters.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=clusters.test.d.ts.map

package/dist/htc/clusters.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"clusters.test.d.ts","sourceRoot":"","sources":["../../src/htc/clusters.test.ts"],"names":[],"mappings":""}

package/dist/htc/clusters.test.js

@@ -0,0 +1,128 @@
+import { describe, it, expect, vi } from "vitest";
+import { CLUSTER_SYSTEM_PROMPT, buildClusterUserPrompt, extractLabel, generateClusterSummary, generateClusterSummaries, } from "./clusters.js";
+function mockEnricher(text, name = "mock:test") {
+    return {
+        name,
+        enrich: vi.fn().mockResolvedValue({ text }),
+    };
+}
+describe("buildClusterUserPrompt", () => {
+    it("formats abstracts as a bulleted list", () => {
+        const prompt = buildClusterUserPrompt([
+            "auth: replaced session cookies with JWT",
+            "auth: rotated JWT signing keys quarterly",
+        ]);
+        expect(prompt).toContain("Commit abstracts (one per line):");
+        expect(prompt).toContain("  - auth: replaced session cookies with JWT");
+        expect(prompt).toContain("  - auth: rotated JWT signing keys");
+    });
+    it("skips blank entries", () => {
+        const prompt = buildClusterUserPrompt(["real one", "  ", "", "another"]);
+        const bullets = prompt.split("\n").filter((l) => l.startsWith("  - "));
+        expect(bullets).toHaveLength(2);
+    });
+});
+describe("extractLabel", () => {
+    it("uses the colon-prefixed topic when present", () => {
+        expect(extractLabel("auth: switched to JWT for stateless deploys", "fb")).toBe("auth");
+        expect(extractLabel("payment refactor: split into V2", "fb")).toBe("payment refactor");
+    });
+    it("falls back to first 4 words when no colon", () => {
+        expect(extractLabel("Payment module evolved over many quarters.", "fb")).toBe("payment module evolved over");
+    });
+    it("uses fallback on empty input", () => {
+        expect(extractLabel("", "cluster 7")).toBe("cluster 7");
+        expect(extractLabel("   ", "cluster 7")).toBe("cluster 7");
+    });
+    it("caps label length at 40 chars", () => {
+        const long = "this is a very long opening sentence with no colon punctuation here";
+        const label = extractLabel(long, "fb");
+        expect(label.length).toBeLessThanOrEqual(40);
+    });
+});
+describe("generateClusterSummary", () => {
+    it("calls enricher with cluster prompt + builds summary", async () => {
+        const enricher = mockEnricher("auth refactor: started with cookie sessions, evolved to JWT for CDN-friendly deploys.", "groq:llama-3.3-70b");
+        const abstracts = new Map([
+            ["aaa", "auth: cookie session"],
+            ["bbb", "auth: switched to JWT"],
+        ]);
+        const r = await generateClusterSummary({ id: "c1", memberHashes: ["aaa", "bbb"] }, abstracts, enricher);
+        expect(r.clusterId).toBe("c1");
+        expect(r.label).toBe("auth refactor");
+        expect(r.summary).toContain("JWT");
+        expect(r.memberHashes).toEqual(["aaa", "bbb"]);
+        expect(r.tokenCount).toBeGreaterThan(0);
+        expect(r.generator).toBe("groq:llama-3.3-70b");
+        const call = enricher.enrich.mock.calls[0][0];
+        expect(call.system).toBe(CLUSTER_SYSTEM_PROMPT);
+        expect(call.user).toContain("auth: cookie session");
+        expect(call.user).toContain("auth: switched to JWT");
+    });
+    it("throws when no Layer-1 abstracts exist for the cluster", async () => {
+        const enricher = mockEnricher("never called");
+        await expect(generateClusterSummary({ id: "c2", memberHashes: ["missing1", "missing2"] }, new Map(), enricher)).rejects.toThrow(/no Layer-1 abstracts/);
+        expect(enricher.enrich).not.toHaveBeenCalled();
+    });
+    it("uses fallback label when summary has no clear topic", async () => {
+        const enricher = mockEnricher("");
+        await expect(generateClusterSummary({ id: "c3", memberHashes: ["aaa"] }, new Map([["aaa", "anything"]]), enricher)).resolves.toMatchObject({ label: "cluster c3" });
+    });
+});
+describe("generateClusterSummaries", () => {
+    it("processes all clusters and returns ClusterSummary[]", async () => {
+        const enricher = mockEnricher("topic: brief summary");
+        const abstracts = new Map([
+            ["a", "abstract a"],
+            ["b", "abstract b"],
+            ["c", "abstract c"],
+            ["d", "abstract d"],
+        ]);
+        const clusters = [
+            { id: "c1", memberHashes: ["a", "b"] },
+            { id: "c2", memberHashes: ["c", "d"] },
+        ];
+        const out = await generateClusterSummaries(abstracts, clusters, enricher, {
+            concurrency: 2,
+        });
+        expect(out).toHaveLength(2);
+        expect(enricher.enrich).toHaveBeenCalledTimes(2);
+    });
+    it("records errors via onError without aborting", async () => {
+        const enricher = {
+            name: "mock:flaky",
+            enrich: vi.fn().mockImplementation((input) => {
+                if (input.user.includes("BAD"))
+                    return Promise.reject(new Error("server 503"));
+                return Promise.resolve({ text: "ok: clean summary" });
+            }),
+        };
+        const abstracts = new Map([
+            ["a", "good one"],
+            ["b", "BAD one"],
+            ["c", "good two"],
+        ]);
+        const onError = vi.fn();
+        const out = await generateClusterSummaries(abstracts, [
+            { id: "c1", memberHashes: ["a"] },
+            { id: "c2", memberHashes: ["b"] },
+            { id: "c3", memberHashes: ["c"] },
+        ], enricher, { concurrency: 1, onError });
+        expect(out).toHaveLength(2);
+        expect(onError).toHaveBeenCalledTimes(1);
+        expect(onError.mock.calls[0][0]).toBe("c2");
+    });
+    it("invokes onProgress with monotonically increasing done count", async () => {
+        const enricher = mockEnricher("topic: x");
+        const abstracts = new Map([["a", "x"]]);
+        const onProgress = vi.fn();
+        await generateClusterSummaries(abstracts, [
+            { id: "c1", memberHashes: ["a"] },
+            { id: "c2", memberHashes: ["a"] },
+        ], enricher, { onProgress });
+        expect(onProgress).toHaveBeenCalledTimes(2);
+        const last = onProgress.mock.calls[onProgress.mock.calls.length - 1];
+        expect(last).toEqual([2, 2]);
+    });
+});
+//# sourceMappingURL=clusters.test.js.map