@smartmemory/stratum 0.3.4 → 0.4.0

package/dist/learn/candidate.js

@@ -0,0 +1,186 @@
+import { createHash } from "node:crypto";
+import { appendFile, mkdir, readFile } from "node:fs/promises";
+import { isAbsolute, join, resolve, sep } from "node:path";
+/**
+ * Turns a durable cluster into a staged, immutable candidate.
+ *
+ * Authoring is TEMPLATED, not model-driven. A template cannot generalize beyond its
+ * inputs, which removes the largest source of harm a semantic-consistency critic exists
+ * to catch, and it makes candidate identity deterministic — the same evidence always
+ * produces the same bytes.
+ *
+ * The candidate carries the RENDERED note, not merely a description of one. Without the
+ * real text there is nothing for the behavioral critic to inspect and no source for the
+ * `after` bytes an apply must write and snapshot.
+ */
+export const SCHEMA_VERSION = "learn-1.0";
+export const TEMPLATE_VERSION = "1";
+export class CandidateError extends Error {
+}
+const SECTION = "## Harvested notes";
+/**
+ * v1 writes only inside the project's own `.stratum/learn/`. Promotion to a project's
+ * primary memory file, or to user scope, is a separate authorized step by design.
+ */
+export function targetPathFor(workspaceRoot) {
+    if (!isAbsolute(workspaceRoot))
+        throw new CandidateError("workspaceRoot must be absolute");
+    const root = resolve(workspaceRoot);
+    const target = resolve(join(root, ".stratum", "learn", "NOTES.md"));
+    // Path allowlist, enforced on the RESOLVED path — a convention would not survive
+    // a workspaceRoot containing `..`.
+    if (target !== root && !target.startsWith(root + sep)) {
+        throw new CandidateError(`target escapes workspace root: ${target}`);
+    }
+    if (root !== workspaceRoot.replace(/\/+$/, "")) {
+        throw new CandidateError(`workspaceRoot is not normalized: ${workspaceRoot}`);
+    }
+    return target;
+}
+export function authorCandidate(cluster) {
+    if (cluster.class !== "durable") {
+        throw new CandidateError(`cluster is ${cluster.class}, not durable`);
+    }
+    if (cluster.evidence.length === 0) {
+        throw new CandidateError("cluster carries no evidence");
+    }
+    // Re-derived, not trusted: `applyEligible` is a computed field on a plain object, so
+    // a caller that hand-builds a Cluster (or edits one) must not be able to smuggle an
+    // unattributed or mixed-provenance lesson into an apply.
+    if (cluster.unattributed || cluster.scope.workspaceRoot === null) {
+        throw new CandidateError("cluster is unattributed and cannot authorize a write");
+    }
+    if (cluster.mixedProvenance) {
+        throw new CandidateError("cluster is mixed-provenance and cannot authorize a write");
+    }
+    if (!cluster.applyEligible)
+        throw new CandidateError("cluster is not apply-eligible");
+    const workspaceRoot = cluster.scope.workspaceRoot;
+    if (workspaceRoot === null)
+        throw new CandidateError("durable cluster has no workspaceRoot");
+    const claim = renderClaim(cluster);
+    const rendered = {
+        content: renderNote(cluster, claim),
+        templateId: `learn/${cluster.shape}`,
+        templateVersion: TEMPLATE_VERSION,
+        insertion: { mode: "append-to-section", section: SECTION },
+    };
+    const clusterId = sha(cluster.key);
+    return {
+        clusterId,
+        // Binds the whole WRITE, not just the bytes: target path and insertion mode change
+        // what gets written (mode "create" discards the existing file), so an identity that
+        // omits them lets an edited sidecar row apply different effects under the same id.
+        revisionId: sha([
+            clusterId,
+            rendered.templateVersion,
+            rendered.content,
+            targetPathFor(workspaceRoot),
+            rendered.insertion.mode,
+            rendered.insertion.section,
+        ].join("\u0000")),
+        schemaVersion: SCHEMA_VERSION,
+        targetKind: "memory",
+        targetPath: targetPathFor(workspaceRoot),
+        scope: {
+            workspaceRoot,
+            flowName: cluster.scope.flowName,
+            stepIds: cluster.scope.stepIds,
+            specDigests: cluster.scope.specDigests,
+        },
+        claim,
+        rendered,
+        evidence: cluster.evidence,
+        observedValues: cluster.observedValues,
+        recurrence: cluster.recurrence,
+        groupingKey: cluster.groupingKey,
+        // Every lesson v1 can currently derive points at a contract, and contracts live in
+        // specs. Surfacing is the deliverable; the fix stays a human's call.
+        requiresHumanAction: cluster.shape === "schema" || cluster.shape === "ensure",
+        // §5.1 tripwire: exactly what the author read. The memory pool is not among it.
+        authoringInputsDigest: sha(JSON.stringify({ key: cluster.key, fingerprint: cluster.fingerprint, recurrence: cluster.recurrence })),
+    };
+}
+function renderClaim(cluster) {
+    const steps = cluster.scope.stepIds.map((s) => `\`${s}\``).join(", ");
+    const { records, distinctRuns, distinctPairs } = cluster.recurrence;
+    const seen = `${records} times across ${distinctRuns} runs / ${distinctPairs} run-step pairs`;
+    const { path, expected } = cluster.contract;
+    // A note that does not name the offending field is not actionable.
+    const field = path.length > 0 ? `\`${path}\`` : "the step output";
+    if (cluster.shape === "schema") {
+        const allowed = expected.length > 0
+            ? ` The contract allows ${expected.map((v) => `\`${v}\``).join(", ")}.`
+            : "";
+        const observed = cluster.observedValues.length > 0
+            ? ` Steps returned ${cluster.observedValues.map((v) => `\`${v}\``).join(", ")}.`
+            : "";
+        return `In flow \`${cluster.scope.flowName}\`, step(s) ${steps} produced ${field} that the declared contract rejected, ${seen}.${allowed}${observed}`;
+    }
+    return `In flow \`${cluster.scope.flowName}\`, step(s) ${steps} failed the same \`${cluster.shape}\` check on ${field}, ${seen}.`;
+}
+function renderNote(cluster, claim) {
+    const recovered = cluster.evidence.filter((record) => record.recovered).length;
+    // Only claim what the evidence shows. "Recovered on retry" is the invisible-waste
+    // story, and it is a different (weaker) finding when most of these actually failed.
+    const impact = recovered === cluster.evidence.length
+        ? "every one recovered on retry, so each cost an extra agent dispatch and nothing surfaced it"
+        : recovered === 0
+            ? "none recovered on retry"
+            : `${recovered} of ${cluster.evidence.length} recovered on retry, so those cost an extra agent dispatch each`;
+    const lines = [
+        `- **${cluster.scope.flowName}: recurring ${cluster.shape} failure on ${cluster.contract.path || "step output"}** — ${claim}`,
+        `  **Why it matters:** ${impact}.`,
+        `  **Fix target:** the declared contract or the step instruction — a spec change, which this loop deliberately will not make for you.`,
+        `  <!-- learn:${sha(cluster.key).slice(0, 12)} -->`,
+    ];
+    return lines.join("\n");
+}
+// ---------------------------------------------------------------------------
+// Sidecar: append-only, its own file, its own schema. Never any other corpus.
+// ---------------------------------------------------------------------------
+export function sidecarPath(dir) {
+    return join(dir, "candidates.jsonl");
+}
+export async function readCandidates(dir) {
+    let raw;
+    try {
+        raw = await readFile(sidecarPath(dir), "utf8");
+    }
+    catch {
+        return [];
+    }
+    const out = [];
+    for (const line of raw.split("\n")) {
+        if (line.trim().length === 0)
+            continue;
+        try {
+            out.push(JSON.parse(line));
+        }
+        catch {
+            // A corrupt line must not hide the rest of the file.
+        }
+    }
+    return out;
+}
+/** Returns how many rows were newly written. Idempotent on `revisionId`. */
+export async function appendCandidates(dir, candidates) {
+    const existing = new Set((await readCandidates(dir)).map((c) => c.revisionId));
+    const fresh = candidates.filter((c) => !existing.has(c.revisionId));
+    if (fresh.length === 0)
+        return 0;
+    await mkdir(dir, { recursive: true });
+    await appendFile(sidecarPath(dir), fresh.map((c) => JSON.stringify(c)).join("\n") + "\n", "utf8");
+    return fresh.length;
+}
+/** The newest revision of each cluster, by file order. */
+export function latestPerCluster(candidates) {
+    const latest = new Map();
+    for (const candidate of candidates)
+        latest.set(candidate.clusterId, candidate);
+    return [...latest.values()];
+}
+function sha(value) {
+    return createHash("sha256").update(value).digest("hex");
+}
+//# sourceMappingURL=candidate.js.map

package/dist/learn/candidate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"candidate.js","sourceRoot":"","sources":["../../src/learn/candidate.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,UAAU,EAAE,KAAK,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAC/D,OAAO,EAAE,UAAU,EAAE,IAAI,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,WAAW,CAAC;AAI3D;;;;;;;;;;;GAWG;AAEH,MAAM,CAAC,MAAM,cAAc,GAAG,WAAW,CAAC;AAC1C,MAAM,CAAC,MAAM,gBAAgB,GAAG,GAAG,CAAC;AAEpC,MAAM,OAAO,cAAe,SAAQ,KAAK;CAAG;AA6B5C,MAAM,OAAO,GAAG,oBAAoB,CAAC;AAErC;;;GAGG;AACH,MAAM,UAAU,aAAa,CAAC,aAAqB;IACjD,IAAI,CAAC,UAAU,CAAC,aAAa,CAAC;QAAE,MAAM,IAAI,cAAc,CAAC,gCAAgC,CAAC,CAAC;IAC3F,MAAM,IAAI,GAAG,OAAO,CAAC,aAAa,CAAC,CAAC;IACpC,MAAM,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,IAAI,EAAE,UAAU,EAAE,OAAO,EAAE,UAAU,CAAC,CAAC,CAAC;IACpE,iFAAiF;IACjF,mCAAmC;IACnC,IAAI,MAAM,KAAK,IAAI,IAAI,CAAC,MAAM,CAAC,UAAU,CAAC,IAAI,GAAG,GAAG,CAAC,EAAE,CAAC;QACtD,MAAM,IAAI,cAAc,CAAC,kCAAkC,MAAM,EAAE,CAAC,CAAC;IACvE,CAAC;IACD,IAAI,IAAI,KAAK,aAAa,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,EAAE,CAAC;QAC/C,MAAM,IAAI,cAAc,CAAC,oCAAoC,aAAa,EAAE,CAAC,CAAC;IAChF,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,MAAM,UAAU,eAAe,CAAC,OAAgB;IAC9C,IAAI,OAAO,CAAC,KAAK,KAAK,SAAS,EAAE,CAAC;QAChC,MAAM,IAAI,cAAc,CAAC,cAAc,OAAO,CAAC,KAAK,eAAe,CAAC,CAAC;IACvE,CAAC;IACD,IAAI,OAAO,CAAC,QAAQ,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAClC,MAAM,IAAI,cAAc,CAAC,6BAA6B,CAAC,CAAC;IAC1D,CAAC;IACD,qFAAqF;IACrF,oFAAoF;IACpF,yDAAyD;IACzD,IAAI,OAAO,CAAC,YAAY,IAAI,OAAO,CAAC,KAAK,CAAC,aAAa,KAAK,IAAI,EAAE,CAAC;QACjE,MAAM,IAAI,cAAc,CAAC,sDAAsD,CAAC,CAAC;IACnF,CAAC;IACD,IAAI,OAAO,CAAC,eAAe,EAAE,CAAC;QAC5B,MAAM,IAAI,cAAc,CAAC,0DAA0D,CAAC,CAAC;IACvF,CAAC;IACD,IAAI,CAAC,OAAO,CAAC,aAAa;QAAE,MAAM,IAAI,cAAc,CAAC,+BAA+B,CAAC,CAAC;IACtF,MAAM,aAAa,GAAG,OAAO,CAAC,KAAK,CAAC,aAAa,CAAC;IAClD,IAAI,aAAa,KAAK,IAAI;QAAE,MAAM,IAAI,cAAc,CAAC,sCAAsC,CAAC,CAAC;IAE7F,MAAM,KAAK,GAAG,WAAW,CAAC,OAAO,CAAC,CAAC;IACnC,MAAM,QAAQ,GAAkB;QAC9B,OAAO,EAAE,UAAU,CAAC,OAAO,EAAE,KAAK,CAAC;QACnC,UAAU,EAAE,SAAS,OAAO,CAAC,KAAK,EAAE;QACpC,eAAe,EAAE,gBAAgB;QACjC,SAAS,EAAE,EAAE,IAAI,EAAE,mBAAmB,EAAE,OAAO,EAAE,OAAO,EAAE;KAC3D,CAAC;IAEF,MAAM,SAAS,GAAG,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;IACnC,OAAO;QACL,SAAS;QACT,mFAAmF;QACnF,oFAAoF;QACpF,mFAAmF;QACnF,UAAU,EAAE,GAAG,CACb;YACE,SAAS;YACT,QAAQ,CAAC,eAAe;YACxB,QAAQ,CAAC,OAAO;YAChB,aAAa,CAAC,aAAa,CAAC;YAC5B,QAAQ,CAAC,SAAS,CAAC,IAAI;YACvB,QAAQ,CAAC,SAAS,CAAC,OAAO;SAC3B,CAAC,IAAI,CAAC,QAAQ,CAAC,CACjB;QACD,aAAa,EAAE,cAAc;QAC7B,UAAU,EAAE,QAAQ;QACpB,UAAU,EAAE,aAAa,CAAC,aAAa,CAAC;QACxC,KAAK,EAAE;YACL,aAAa;YACb,QAAQ,EAAE,OAAO,CAAC,KAAK,CAAC,QAAQ;YAChC,OAAO,EAAE,OAAO,CAAC,KAAK,CAAC,OAAO;YAC9B,WAAW,EAAE,OAAO,CAAC,KAAK,CAAC,WAAW;SACvC;QACD,KAAK;QACL,QAAQ;QACR,QAAQ,EAAE,OAAO,CAAC,QAAQ;QAC1B,cAAc,EAAE,OAAO,CAAC,cAAc;QACtC,UAAU,EAAE,OAAO,CAAC,UAAU;QAC9B,WAAW,EAAE,OAAO,CAAC,WAAW;QAChC,mFAAmF;QACnF,qEAAqE;QACrE,mBAAmB,EAAE,OAAO,CAAC,KAAK,KAAK,QAAQ,IAAI,OAAO,CAAC,KAAK,KAAK,QAAQ;QAC7E,gFAAgF;QAChF,qBAAqB,EAAE,GAAG,CACxB,IAAI,CAAC,SAAS,CAAC,EAAE,GAAG,EAAE,OAAO,CAAC,GAAG,EAAE,WAAW,EAAE,OAAO,CAAC,WAAW,EAAE,UAAU,EAAE,OAAO,CAAC,UAAU,EAAE,CAAC,CACvG;KACF,CAAC;AACJ,CAAC;AAED,SAAS,WAAW,CAAC,OAAgB;IACnC,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACtE,MAAM,EAAE,OAAO,EAAE,YAAY,EAAE,aAAa,EAAE,GAAG,OAAO,CAAC,UAAU,CAAC;IACpE,MAAM,IAAI,GAAG,GAAG,OAAO,iBAAiB,YAAY,WAAW,aAAa,iBAAiB,CAAC;IAC9F,MAAM,EAAE,IAAI,EAAE,QAAQ,EAAE,GAAG,OAAO,CAAC,QAAQ,CAAC;IAC5C,mEAAmE;IACnE,MAAM,KAAK,GAAG,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,IAAI,IAAI,CAAC,CAAC,CAAC,iBAAiB,CAAC;IAClE,IAAI,OAAO,CAAC,KAAK,KAAK,QAAQ,EAAE,CAAC;QAC/B,MAAM,OAAO,GAAG,QAAQ,CAAC,MAAM,GAAG,CAAC;YACjC,CAAC,CAAC,wBAAwB,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG;YACvE,CAAC,CAAC,EAAE,CAAC;QACP,MAAM,QAAQ,GAAG,OAAO,CAAC,cAAc,CAAC,MAAM,GAAG,CAAC;YAChD,CAAC,CAAC,mBAAmB,OAAO,CAAC,cAAc,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG;YAChF,CAAC,CAAC,EAAE,CAAC;QACP,OAAO,aAAa,OAAO,CAAC,KAAK,CAAC,QAAQ,eAAe,KAAK,aAAa,KAAK,yCAAyC,IAAI,IAAI,OAAO,GAAG,QAAQ,EAAE,CAAC;IACxJ,CAAC;IACD,OAAO,aAAa,OAAO,CAAC,KAAK,CAAC,QAAQ,eAAe,KAAK,sBAAsB,OAAO,CAAC,KAAK,eAAe,KAAK,KAAK,IAAI,GAAG,CAAC;AACpI,CAAC;AAED,SAAS,UAAU,CAAC,OAAgB,EAAE,KAAa;IACjD,MAAM,SAAS,GAAG,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,MAAM,CAAC;IAC/E,kFAAkF;IAClF,oFAAoF;IACpF,MAAM,MAAM,GACV,SAAS,KAAK,OAAO,CAAC,QAAQ,CAAC,MAAM;QACnC,CAAC,CAAC,4FAA4F;QAC9F,CAAC,CAAC,SAAS,KAAK,CAAC;YACf,CAAC,CAAC,yBAAyB;YAC3B,CAAC,CAAC,GAAG,SAAS,OAAO,OAAO,CAAC,QAAQ,CAAC,MAAM,iEAAiE,CAAC;IACpH,MAAM,KAAK,GAAG;QACZ,OAAO,OAAO,CAAC,KAAK,CAAC,QAAQ,eAAe,OAAO,CAAC,KAAK,eAAe,OAAO,CAAC,QAAQ,CAAC,IAAI,IAAI,aAAa,QAAQ,KAAK,EAAE;QAC7H,yBAAyB,MAAM,GAAG;QAClC,sIAAsI;QACtI,gBAAgB,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,MAAM;KACpD,CAAC;IACF,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC1B,CAAC;AAED,8EAA8E;AAC9E,8EAA8E;AAC9E,8EAA8E;AAE9E,MAAM,UAAU,WAAW,CAAC,GAAW;IACrC,OAAO,IAAI,CAAC,GAAG,EAAE,kBAAkB,CAAC,CAAC;AACvC,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,cAAc,CAAC,GAAW;IAC9C,IAAI,GAAW,CAAC;IAChB,IAAI,CAAC;QACH,GAAG,GAAG,MAAM,QAAQ,CAAC,WAAW,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC,CAAC;IACjD,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,CAAC;IACZ,CAAC;IACD,MAAM,GAAG,GAAqB,EAAE,CAAC;IACjC,KAAK,MAAM,IAAI,IAAI,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC;QACnC,IAAI,IAAI,CAAC,IAAI,EAAE,CAAC,MAAM,KAAK,CAAC;YAAE,SAAS;QACvC,IAAI,CAAC;YACH,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAmB,CAAC,CAAC;QAC/C,CAAC;QAAC,MAAM,CAAC;YACP,qDAAqD;QACvD,CAAC;IACH,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED,4EAA4E;AAC5E,MAAM,CAAC,KAAK,UAAU,gBAAgB,CACpC,GAAW,EACX,UAAqC;IAErC,MAAM,QAAQ,GAAG,IAAI,GAAG,CAAC,CAAC,MAAM,cAAc,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC;IAC/E,MAAM,KAAK,GAAG,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC;IACpE,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,CAAC,CAAC;IACjC,MAAM,KAAK,CAAC,GAAG,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IACtC,MAAM,UAAU,CAAC,WAAW,CAAC,GAAG,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,IAAI,EAAE,MAAM,CAAC,CAAC;IAClG,OAAO,KAAK,CAAC,MAAM,CAAC;AACtB,CAAC;AAED,0DAA0D;AAC1D,MAAM,UAAU,gBAAgB,CAAC,UAAqC;IACpE,MAAM,MAAM,GAAG,IAAI,GAAG,EAA0B,CAAC;IACjD,KAAK,MAAM,SAAS,IAAI,UAAU;QAAE,MAAM,CAAC,GAAG,CAAC,SAAS,CAAC,SAAS,EAAE,SAAS,CAAC,CAAC;IAC/E,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC;AAC9B,CAAC;AAED,SAAS,GAAG,CAAC,KAAa;IACxB,OAAO,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;AAC1D,CAAC"}

package/dist/learn/classify.js

@@ -0,0 +1,181 @@
+import { createHash } from "node:crypto";
+export const DEFAULT_THRESHOLDS = { minRuns: 2, minPairs: 3 };
+export function issueUnits(record) {
+    if (record.shape === "schema") {
+        const issues = parseIssues(record.reason);
+        if (issues.length > 0) {
+            return issues.map((issue) => {
+                // The declared contract: allowed enum options, or rejected key NAMES — both
+                // properties of the schema, not of the value that failed it.
+                const contract = {
+                    code: String(issue.code ?? ""),
+                    path: toStrings(issue.path).join("."),
+                    expected: [
+                        ...toStrings(issue.options),
+                        ...toStrings(issue.keys),
+                        ...(typeof issue.expected === "string" ? [issue.expected] : []),
+                    ].sort(),
+                };
+                return {
+                    record,
+                    fingerprint: sha(JSON.stringify({ shape: record.shape, ...contract })),
+                    contract,
+                    ...(typeof issue.received === "string" ? { received: issue.received } : {}),
+                };
+            });
+        }
+    }
+    const text = record.shape === "budget"
+        ? "budget"
+        : record.reason.replace(/"[^"]*"/g, '""').replace(/\d+/g, "#").slice(0, 200);
+    const contract = { code: record.shape, path: "", expected: [] };
+    return [{ record, fingerprint: sha(JSON.stringify({ shape: record.shape, text })), contract }];
+}
+/** The primary violated contract of a record — its first issue in canonical order. */
+export function contractFingerprint(record) {
+    const sorted = [...issueUnits(record)].sort((a, b) => a.fingerprint.localeCompare(b.fingerprint));
+    // issueUnits always returns at least one unit, but the compiler cannot know that.
+    return sorted[0]?.fingerprint ?? sha(JSON.stringify({ shape: record.shape, text: "" }));
+}
+function parseIssues(reason) {
+    try {
+        const parsed = JSON.parse(reason);
+        if (Array.isArray(parsed))
+            return parsed;
+        if (typeof parsed === "object" && parsed !== null)
+            return [parsed];
+    }
+    catch {
+        // Not a structured reason; the text path in contractShape handles it.
+    }
+    return [];
+}
+function toStrings(value) {
+    return Array.isArray(value) ? value.filter((v) => typeof v === "string") : [];
+}
+export function groupRecords(records, groupingKey) {
+    const groups = new Map();
+    for (const record of records) {
+        for (const unit of issueUnits(record)) {
+            const parts = [
+                record.workspaceRoot ?? "\u0000unattributed",
+                record.flowName,
+                record.shape,
+                unit.fingerprint,
+            ];
+            // The step id joins the key only for step-scoped grouping. Leaving it out is what
+            // recovers a contract-level lesson that no single step exhibits often enough.
+            if (groupingKey === "step-scoped")
+                parts.splice(2, 0, record.stepId ?? "\u0000flow");
+            const key = parts.join("\u0000");
+            const bucket = groups.get(key);
+            if (bucket === undefined)
+                groups.set(key, [unit]);
+            else
+                bucket.push(unit);
+        }
+    }
+    return groups;
+}
+export function classify(records, thresholds = DEFAULT_THRESHOLDS) {
+    const clusters = [];
+    const claimed = new Set();
+    // Step-agnostic first: a contract-level lesson subsumes the per-step view of the same
+    // issues, and emitting both would report one lesson twice.
+    for (const groupingKey of ["step-agnostic", "step-scoped"]) {
+        for (const [key, bucket] of groupRecords(records, groupingKey)) {
+            const cluster = build(key, groupingKey, bucket, thresholds);
+            if (groupingKey === "step-scoped" &&
+                cluster.class === "durable" &&
+                bucket.every((unit) => claimed.has(identity(unit)))) {
+                continue;
+            }
+            // Only an APPLY-ELIGIBLE aggregate subsumes its per-step view. A mixed-provenance
+            // or unattributed aggregate is discarded downstream, so letting it claim these
+            // units would silently drop clean per-step lessons with it.
+            if (cluster.class === "durable" && cluster.applyEligible) {
+                for (const unit of bucket)
+                    claimed.add(identity(unit));
+            }
+            clusters.push(cluster);
+        }
+    }
+    return clusters.sort((a, b) => a.key.localeCompare(b.key));
+}
+function identity(unit) {
+    const { record } = unit;
+    return [record.runId, record.stepId ?? "", record.at, unit.fingerprint].join("\u0000");
+}
+function build(key, groupingKey, bucket, thresholds) {
+    const rows = bucket.map((unit) => unit.record);
+    const first = rows[0];
+    if (first === undefined)
+        throw new Error("cannot build a cluster from an empty bucket");
+    const runs = new Set(rows.map((r) => r.runId));
+    const pairs = new Set(rows.map((r) => `${r.runId}\u0000${r.stepId ?? ""}`));
+    const stepIds = [...new Set(rows.map((r) => r.stepId).filter((s) => s !== null))].sort();
+    const specDigests = [
+        ...new Set(rows.map((r) => r.specDigest).filter((s) => s !== undefined)),
+    ].sort();
+    const workspaceRoot = first.workspaceRoot ?? null;
+    const unattributed = workspaceRoot === null;
+    // Disjoint spec revisions AND disjoint steps: the records cannot be one contract seen
+    // across edits, so they are more likely two contracts colliding on one fingerprint.
+    const perDigestSteps = new Map();
+    for (const record of rows) {
+        if (record.specDigest === undefined || record.stepId === null)
+            continue;
+        const set = perDigestSteps.get(record.specDigest) ?? new Set();
+        set.add(record.stepId);
+        perDigestSteps.set(record.specDigest, set);
+    }
+    const stepSets = [...perDigestSteps.values()];
+    const mixedProvenance = stepSets.length > 1 &&
+        stepSets.every((a, i) => stepSets.every((b, j) => i === j || disjoint(a, b)));
+    const shape = first.shape;
+    let klass;
+    if (shape === "budget")
+        klass = "transient";
+    else if (runs.size >= thresholds.minRuns && pairs.size >= thresholds.minPairs)
+        klass = "durable";
+    else
+        klass = "step-local";
+    // Evidence is deduped source records: one record violating two constraints is
+    // evidence for two clusters, but only once within each.
+    const evidence = [];
+    const seen = new Set();
+    for (const record of rows) {
+        const id = [record.runId, record.stepId ?? "", record.at].join("\u0000");
+        if (seen.has(id))
+            continue;
+        seen.add(id);
+        evidence.push(record);
+    }
+    return {
+        key,
+        groupingKey,
+        shape,
+        class: klass,
+        fingerprint: bucket[0]?.fingerprint ?? "",
+        contract: bucket[0]?.contract ?? { code: shape, path: "", expected: [] },
+        scope: { workspaceRoot, flowName: first.flowName, stepIds, specDigests },
+        recurrence: { records: bucket.length, distinctRuns: runs.size, distinctPairs: pairs.size },
+        observedValues: [
+            ...new Set(bucket.map((u) => u.received).filter((v) => v !== undefined)),
+        ].sort(),
+        mixedProvenance,
+        unattributed,
+        applyEligible: klass === "durable" && !unattributed && !mixedProvenance,
+        evidence,
+    };
+}
+function disjoint(a, b) {
+    for (const value of a)
+        if (b.has(value))
+            return false;
+    return true;
+}
+function sha(value) {
+    return createHash("sha256").update(value).digest("hex");
+}
+//# sourceMappingURL=classify.js.map

package/dist/learn/classify.js.map

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

package/dist/learn/harvest.js

@@ -0,0 +1,138 @@
+import { readFile, readdir } from "node:fs/promises";
+import { join } from "node:path";
+export async function harvest(flowsDir) {
+    let names;
+    try {
+        names = (await readdir(flowsDir)).filter((name) => name.endsWith(".json")).sort();
+    }
+    catch {
+        // A missing corpus is an empty corpus, not an error.
+        return { records: [], skipped: 0, droppedEvents: 0 };
+    }
+    const records = [];
+    let skipped = 0;
+    let droppedEvents = 0;
+    for (const name of names) {
+        let run;
+        try {
+            run = JSON.parse(await readFile(join(flowsDir, name), "utf8"));
+        }
+        catch {
+            skipped += 1;
+            continue;
+        }
+        try {
+            droppedEvents += collect(run, records);
+        }
+        catch {
+            skipped += 1;
+        }
+    }
+    return { records, skipped, droppedEvents };
+}
+/** Returns the number of failure-shaped events that were malformed and dropped. */
+function collect(run, out) {
+    const runId = str(run.id);
+    if (runId === undefined)
+        throw new Error("run has no id");
+    const flowName = str(run.flowName) ?? "";
+    const workspaceRoot = str(run.workspaceRoot);
+    const specDigest = str(run.revisionDigest);
+    const events = Array.isArray(run.events) ? run.events : [];
+    let dropped = 0;
+    for (const [index, event] of events.entries()) {
+        const type = str(event.type);
+        const detail = isRecord(event.detail) ? event.detail : undefined;
+        if (detail === undefined)
+            continue;
+        if (type === "result") {
+            if (!("failure" in detail))
+                continue;
+            // `failure` is a string in some drifted runs: failure-shaped but unusable.
+            const failure = isRecord(detail.failure) ? detail.failure : undefined;
+            if (failure === undefined) {
+                dropped += 1;
+                continue;
+            }
+            const reason = str(failure.reason);
+            if (reason === undefined) {
+                dropped += 1;
+                continue;
+            }
+            const stepId = str(event.stepId) ?? null;
+            out.push({
+                runId,
+                flowName,
+                stepId,
+                ...(specDigest !== undefined ? { specDigest } : {}),
+                attempt: num(failure.attempt) ?? num(detail.attempt) ?? 0,
+                reason,
+                shape: shapeOf(reason),
+                ...(workspaceRoot !== undefined ? { workspaceRoot } : {}),
+                at: str(event.at) ?? "",
+                recovered: stepId !== null && succeededAfter(events, stepId, index),
+            });
+            continue;
+        }
+        if (type === "budget_exhausted") {
+            const reason = str(detail.reason);
+            if (reason === undefined) {
+                dropped += 1;
+                continue;
+            }
+            out.push({
+                runId,
+                flowName,
+                stepId: null,
+                ...(specDigest !== undefined ? { specDigest } : {}),
+                attempt: num(detail.attempt) ?? 0,
+                reason,
+                shape: "budget",
+                ...(workspaceRoot !== undefined ? { workspaceRoot } : {}),
+                at: str(event.at) ?? "",
+                recovered: false,
+            });
+        }
+    }
+    return dropped;
+}
+/**
+ * Did this step succeed AFTER this failure? Position matters: a success recorded
+ * earlier in the run says nothing about whether this failure was recovered, and
+ * treating it as recovery overstates what the evidence shows.
+ */
+function succeededAfter(events, stepId, afterIndex) {
+    for (let i = afterIndex + 1; i < events.length; i += 1) {
+        const event = events[i];
+        if (event === undefined || str(event.type) !== "result")
+            continue;
+        if (str(event.stepId) !== stepId)
+            continue;
+        const detail = isRecord(event.detail) ? event.detail : undefined;
+        if (detail !== undefined && !isRecord(detail.failure))
+            return true;
+    }
+    return false;
+}
+function shapeOf(reason) {
+    const trimmed = reason.trimStart();
+    if (trimmed.startsWith("[") || trimmed.startsWith("{"))
+        return "schema";
+    if (/budget exhausted/i.test(reason))
+        return "budget";
+    if (trimmed.startsWith("ensure"))
+        return "ensure";
+    if (trimmed.startsWith("gate"))
+        return "gate";
+    return "other";
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function str(value) {
+    return typeof value === "string" ? value : undefined;
+}
+function num(value) {
+    return typeof value === "number" && Number.isFinite(value) ? value : undefined;
+}
+//# sourceMappingURL=harvest.js.map

package/dist/learn/harvest.js.map

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