martin-loop 0.1.4 → 1.3.0

package/dist/vendor/core/learning/prior-sets.js

@@ -0,0 +1,111 @@
+import { readFile, writeFile } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+// ─── Gate ordering ────────────────────────────────────────────────────────────
+const GATE_ORDER = ["development", "backtest", "shadow", "live"];
+function gateIndex(gate) {
+    return GATE_ORDER.indexOf(gate);
+}
+function nextGate(current) {
+    const idx = gateIndex(current);
+    return idx < GATE_ORDER.length - 1 ? GATE_ORDER[idx + 1] ?? null : null;
+}
+function prevGate(current) {
+    const idx = gateIndex(current);
+    return idx > 0 ? GATE_ORDER[idx - 1] ?? null : null;
+}
+// ─── Factory ──────────────────────────────────────────────────────────────────
+export function createPriorSet(input) {
+    const confidence = Object.keys(input.priors).length > 0
+        ? Object.values(input.priors).reduce((a, b) => a + b, 0) / Object.keys(input.priors).length
+        : 0;
+    return {
+        priorSetId: input.priorSetId,
+        taskClass: input.taskClass,
+        version: 1,
+        confidence,
+        priors: { ...input.priors },
+        lastUpdatedAt: new Date().toISOString(),
+        promotionGate: "development",
+        sampleCount: 0
+    };
+}
+// ─── Persistence ─────────────────────────────────────────────────────────────
+const STORE_FILE = "prior-sets.json";
+export async function loadPriorStore(storeDir) {
+    const path = join(storeDir, STORE_FILE);
+    if (!existsSync(path))
+        return { priorSets: [] };
+    const raw = await readFile(path, "utf8");
+    return JSON.parse(raw);
+}
+export async function savePriorStore(store, storeDir) {
+    await writeFile(join(storeDir, STORE_FILE), JSON.stringify(store, null, 2), "utf8");
+}
+// ─── Operations ───────────────────────────────────────────────────────────────
+/**
+ * Promotes a PriorSet to the next gate in the sequence.
+ * Gates must advance sequentially: development → backtest → shadow → live.
+ * Throws if the target gate is not the immediate next gate.
+ */
+export async function promotePriorSet(priorSetId, targetGate, storeDir) {
+    const store = await loadPriorStore(storeDir);
+    const idx = store.priorSets.findIndex(p => p.priorSetId === priorSetId);
+    if (idx === -1)
+        throw new Error(`PriorSet not found: ${priorSetId}`);
+    const current = store.priorSets[idx];
+    const expected = nextGate(current.promotionGate);
+    if (expected === null || targetGate !== expected) {
+        throw new Error(`Invalid promotion: ${current.promotionGate} → ${targetGate}. ` +
+            `Expected next gate: ${expected ?? "none (already at live)"}. Gates must advance sequentially.`);
+    }
+    const updated = {
+        ...current,
+        promotionGate: targetGate,
+        version: current.version + 1,
+        lastUpdatedAt: new Date().toISOString()
+    };
+    store.priorSets[idx] = updated;
+    await savePriorStore(store, storeDir);
+    return updated;
+}
+/**
+ * Rolls back a PriorSet to the previous gate.
+ * Rollback is always available from any gate above development.
+ * Throws if already at development.
+ */
+export async function rollbackPriorSet(priorSetId, storeDir) {
+    const store = await loadPriorStore(storeDir);
+    const idx = store.priorSets.findIndex(p => p.priorSetId === priorSetId);
+    if (idx === -1)
+        throw new Error(`PriorSet not found: ${priorSetId}`);
+    const current = store.priorSets[idx];
+    const prev = prevGate(current.promotionGate);
+    if (prev === null) {
+        throw new Error(`Cannot rollback ${priorSetId}: already at development gate.`);
+    }
+    const updated = {
+        ...current,
+        promotionGate: prev,
+        version: current.version + 1,
+        lastUpdatedAt: new Date().toISOString()
+    };
+    store.priorSets[idx] = updated;
+    await savePriorStore(store, storeDir);
+    return updated;
+}
+/**
+ * Returns all PriorSets from the store.
+ */
+export async function listPriorSets(storeDir) {
+    const store = await loadPriorStore(storeDir);
+    return store.priorSets;
+}
+/**
+ * Returns a single PriorSet by ID, or null if not found.
+ */
+export async function getPriorSet(priorSetId, storeDir) {
+    const store = await loadPriorStore(storeDir);
+    return store.priorSets.find(p => p.priorSetId === priorSetId) ?? null;
+}
+//# sourceMappingURL=prior-sets.js.map

package/dist/vendor/core/learning/promotion-gate.d.ts

@@ -0,0 +1,17 @@
+export interface GuardedPromotionInput {
+    candidateId: string;
+    holdoutPassed: number;
+    holdoutTotal: number;
+    regressionCount: number;
+    rollbackPlan: string;
+    humanApproved: boolean;
+    permanentChange: boolean;
+}
+export interface GuardedPromotionDecision {
+    candidateId: string;
+    decision: "promote" | "reject";
+    reasons: string[];
+    allowedClaimWording: string;
+    nonClaims: string[];
+}
+export declare function evaluateGuardedPromotion(input: GuardedPromotionInput): GuardedPromotionDecision;

package/dist/vendor/core/learning/promotion-gate.js

@@ -0,0 +1,23 @@
+export function evaluateGuardedPromotion(input) {
+    const reasons = [];
+    if (input.holdoutTotal <= 0 || input.holdoutPassed !== input.holdoutTotal) {
+        reasons.push("holdout suite did not pass completely");
+    }
+    if (input.regressionCount > 0) {
+        reasons.push("regressions detected");
+    }
+    if (input.rollbackPlan.trim().length === 0) {
+        reasons.push("rollback plan missing");
+    }
+    if (input.permanentChange && !input.humanApproved) {
+        reasons.push("human approval required for permanent change");
+    }
+    return {
+        candidateId: input.candidateId,
+        decision: reasons.length === 0 ? "promote" : "reject",
+        reasons,
+        allowedClaimWording: "guarded self-improvement candidate promotion only after holdout, rollback, and human approval gates pass.",
+        nonClaims: ["unqualified self-improving", "silent self-modification"]
+    };
+}
+//# sourceMappingURL=promotion-gate.js.map

package/dist/vendor/core/leash/blast-radius.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Blast Radius Estimator — pre-execution risk scoring.
+ *
+ * Before any attempt runs, estimates the potential scope of impact (0–100)
+ * based on:
+ * - Objective language (refactor/migrate/delete keywords increase radius)
+ * - Known hotspot files in the likely path (files with regression history)
+ * - Repository size (larger repos have wider potential impact)
+ * - Files explicitly in scope (each hotspot-adjacent file adds risk)
+ *
+ * The router uses this score to gate high-risk tasks onto high-trust models.
+ * The CLI displays it in the pre-run Mission Brief.
+ */
+import type { RepoHotspot } from "../graph/hotspots.js";
+export interface BlastRadiusInput {
+    /** The task objective text, used for keyword analysis */
+    objective: string;
+    /** Absolute path to the repository root */
+    repoRoot: string;
+    /** Files the task has explicitly identified as targets (optional) */
+    currentFiles?: string[];
+    /** Hotspot data from MartinGraph.assembleHotspotContext() (optional) */
+    hotspots?: RepoHotspot[];
+}
+export interface BlastRadiusResult {
+    /** Risk score 0–100. >70 triggers high-trust route enforcement. */
+    score: number;
+    /** Files identified as likely to be touched based on scope + hotspot data */
+    filesAtRisk: string[];
+    /** Subset of filesAtRisk that have recorded regression history */
+    hotspotsInPath: string[];
+    /** Categorical risk label derived from score */
+    regressionRisk: "low" | "medium" | "high";
+    /** Human-readable explanation of what drove the score */
+    rationale: string;
+}
+/**
+ * Estimates the blast radius of a planned task before execution.
+ * Non-throwing: if directory reads fail, falls back gracefully with
+ * a conservative medium score.
+ */
+export declare function estimateBlastRadius(input: BlastRadiusInput): Promise<BlastRadiusResult>;

package/dist/vendor/core/leash/blast-radius.js

@@ -0,0 +1,156 @@
+/**
+ * Blast Radius Estimator — pre-execution risk scoring.
+ *
+ * Before any attempt runs, estimates the potential scope of impact (0–100)
+ * based on:
+ * - Objective language (refactor/migrate/delete keywords increase radius)
+ * - Known hotspot files in the likely path (files with regression history)
+ * - Repository size (larger repos have wider potential impact)
+ * - Files explicitly in scope (each hotspot-adjacent file adds risk)
+ *
+ * The router uses this score to gate high-risk tasks onto high-trust models.
+ * The CLI displays it in the pre-run Mission Brief.
+ */
+import { readdir } from "node:fs/promises";
+import { join } from "node:path";
+/** Keywords that strongly suggest broad file scope changes */
+const HIGH_BLAST_KEYWORDS = [
+    "refactor",
+    "migrate",
+    "restructure",
+    "rename",
+    "move",
+    "delete",
+    "remove all",
+    "overhaul",
+    "rewrite",
+    "reorganize",
+    "consolidate"
+];
+/** Keywords that suggest narrow, test-scoped changes (reduce risk) */
+const LOW_BLAST_KEYWORDS = [
+    "test",
+    "spec",
+    "fixture",
+    "mock",
+    "stub",
+    "snapshot",
+    "add test",
+    "write test"
+];
+/**
+ * Estimates the blast radius of a planned task before execution.
+ * Non-throwing: if directory reads fail, falls back gracefully with
+ * a conservative medium score.
+ */
+export async function estimateBlastRadius(input) {
+    const { objective, repoRoot, currentFiles = [], hotspots = [] } = input;
+    const objectiveLower = objective.toLowerCase();
+    const rationale = [];
+    let score = 10; // Every task has nonzero blast radius
+    // ── Keyword analysis ──────────────────────────────────────────────────────
+    const highKeywordsFound = HIGH_BLAST_KEYWORDS.filter((k) => objectiveLower.includes(k));
+    if (highKeywordsFound.length > 0) {
+        const delta = Math.min(25, highKeywordsFound.length * 12);
+        score += delta;
+        rationale.push(`Objective contains high-scope keywords: ${highKeywordsFound.join(", ")} (+${String(delta)})`);
+    }
+    const lowKeywordsFound = LOW_BLAST_KEYWORDS.filter((k) => objectiveLower.includes(k));
+    if (lowKeywordsFound.length > 0 && highKeywordsFound.length === 0) {
+        score -= 10;
+        rationale.push(`Objective is test-scoped (${lowKeywordsFound[0]}), reducing radius (-10)`);
+    }
+    // ── Repository size ───────────────────────────────────────────────────────
+    const repoFileCount = await countFiles(repoRoot);
+    if (repoFileCount > 500) {
+        score += 20;
+        rationale.push(`Large repository (${String(repoFileCount)} files, +20)`);
+    }
+    else if (repoFileCount > 100) {
+        score += 8;
+        rationale.push(`Medium repository (${String(repoFileCount)} files, +8)`);
+    }
+    // ── Hotspot overlap ───────────────────────────────────────────────────────
+    const filesAtRisk = [...currentFiles];
+    const hotspotsInPath = [];
+    // Add hotspot files that are likely in scope (high regression count)
+    const criticalHotspots = hotspots.filter((h) => h.regressionCount > 2);
+    for (const hotspot of criticalHotspots) {
+        const delta = 15;
+        score += delta;
+        hotspotsInPath.push(hotspot.file);
+        if (!filesAtRisk.includes(hotspot.file))
+            filesAtRisk.push(hotspot.file);
+        rationale.push(`Hotspot in path: ${hotspot.file} (${String(hotspot.regressionCount)} regressions, +${String(delta)})`);
+    }
+    // Files with any regression history add smaller penalty
+    const mildHotspots = hotspots.filter((h) => h.regressionCount > 0 && h.regressionCount <= 2);
+    for (const hotspot of mildHotspots) {
+        score += 5;
+        if (!filesAtRisk.includes(hotspot.file))
+            filesAtRisk.push(hotspot.file);
+    }
+    if (mildHotspots.length > 0) {
+        rationale.push(`${String(mildHotspots.length)} files with minor regression history (+${String(mildHotspots.length * 5)})`);
+    }
+    // ── Explicit files in scope ────────────────────────────────────────────────
+    if (currentFiles.length > 0) {
+        const adjacentHotspots = currentFiles.filter((f) => hotspots.some((h) => h.file === f && h.regressionCount > 0));
+        if (adjacentHotspots.length > 0) {
+            score += adjacentHotspots.length * 10;
+            rationale.push(`${String(adjacentHotspots.length)} explicitly targeted files have regression history (+${String(adjacentHotspots.length * 10)})`);
+        }
+    }
+    // ── Clamp and label ───────────────────────────────────────────────────────
+    const clampedScore = Math.max(0, Math.min(100, score));
+    const regressionRisk = clampedScore >= 70 ? "high" : clampedScore >= 40 ? "medium" : "low";
+    if (rationale.length === 0) {
+        rationale.push("No elevated risk signals detected");
+    }
+    return {
+        score: clampedScore,
+        filesAtRisk,
+        hotspotsInPath,
+        regressionRisk,
+        rationale: rationale.join("; ")
+    };
+}
+/**
+ * Counts source files in a directory (non-recursive for performance).
+ * Only counts .ts, .tsx, .js, .jsx, .py, .go, .rs files — not config/docs.
+ * Returns 0 on any error (missing dir, permission denied, etc.).
+ */
+async function countFiles(dir) {
+    const SOURCE_EXTENSIONS = new Set([
+        ".ts", ".tsx", ".js", ".jsx", ".py", ".go", ".rs", ".java", ".cs", ".rb"
+    ]);
+    async function countRecursive(current, depth) {
+        if (depth > 6)
+            return 0; // don't recurse into deep vendor trees
+        try {
+            const entries = await readdir(current, { withFileTypes: true });
+            let count = 0;
+            for (const entry of entries) {
+                if (entry.name.startsWith(".") || entry.name === "node_modules" || entry.name === "dist") {
+                    continue;
+                }
+                if (entry.isDirectory()) {
+                    count += await countRecursive(join(current, entry.name), depth + 1);
+                }
+                else if (SOURCE_EXTENSIONS.has(extname(entry.name))) {
+                    count += 1;
+                }
+            }
+            return count;
+        }
+        catch {
+            return 0;
+        }
+    }
+    return countRecursive(dir, 0);
+}
+function extname(name) {
+    const dot = name.lastIndexOf(".");
+    return dot >= 0 ? name.slice(dot) : "";
+}
+//# sourceMappingURL=blast-radius.js.map

package/dist/vendor/core/leash/policy-leash.d.ts

@@ -0,0 +1,31 @@
+import { type LeashInput, type PolicyResult } from "@martin/policy";
+import type { SafetyLeashDecision } from "../leash.js";
+export interface PolicyLeashOptions {
+    /** Explicit compiled policy path. Raw Rego fails closed inside @martin/policy. */
+    policyPath?: string;
+    /** Explicit compiled WASM policy path. Takes precedence over policyPath. */
+    policyWasmPath?: string;
+    /** Repository root used for .martin/policy.wasm discovery. */
+    repoRoot?: string;
+    timeoutMs?: number;
+}
+export interface PolicyDeniedInput {
+    surface: string;
+    command?: string | null;
+    path?: string;
+    value?: string | null;
+    reasons: string[];
+}
+export interface PolicyLeashVerdict {
+    allow: boolean;
+    reasons: string[];
+    deniedInputs: PolicyDeniedInput[];
+    inputsEvaluated: number;
+    source?: PolicyResult["source"];
+    policyPath?: string;
+    error?: string;
+}
+export type PolicyBackedSafetyLeashDecision = SafetyLeashDecision & {
+    policyVerdict: PolicyLeashVerdict;
+};
+export declare function applyPolicyToLeashDecision(decision: SafetyLeashDecision, inputs: LeashInput[], options?: PolicyLeashOptions): Promise<PolicyBackedSafetyLeashDecision>;

package/dist/vendor/core/leash/policy-leash.js

@@ -0,0 +1,117 @@
+import { evaluate as evaluateOpaPolicy } from "@martin/policy";
+export async function applyPolicyToLeashDecision(decision, inputs, options = {}) {
+    const policyVerdict = await evaluatePolicyInputs(inputs, options);
+    if (policyVerdict.allow) {
+        return {
+            ...decision,
+            policyVerdict
+        };
+    }
+    const policyViolations = policyVerdict.deniedInputs.flatMap(toPolicyViolations);
+    const policyBlockedCommands = policyVerdict.deniedInputs
+        .map((input) => input.command)
+        .filter((command) => typeof command === "string" && command.length > 0);
+    return {
+        ...decision,
+        allowed: false,
+        blocked: true,
+        riskLevel: "blocked",
+        blockedCommands: [...new Set([...decision.blockedCommands, ...policyBlockedCommands])],
+        violations: [...decision.violations, ...policyViolations],
+        reason: joinReasons([
+            decision.reason,
+            `OPA policy denied ${policyVerdict.deniedInputs.length} safety input(s): ${policyVerdict.reasons.join("; ")}`
+        ]),
+        policyVerdict
+    };
+}
+async function evaluatePolicyInputs(inputs, options) {
+    if (inputs.length === 0) {
+        return {
+            allow: true,
+            reasons: [],
+            deniedInputs: [],
+            inputsEvaluated: 0
+        };
+    }
+    const deniedInputs = [];
+    const reasons = new Set();
+    let source;
+    let policyPath;
+    for (const input of inputs) {
+        try {
+            const result = await withTimeout(evaluateOpaPolicy(input, options.policyWasmPath ?? options.policyPath, options.repoRoot ? { repoRoot: options.repoRoot } : undefined), options.timeoutMs ?? 2_000);
+            source ??= result.source;
+            policyPath ??= result.policyPath;
+            if (!result.allow) {
+                for (const reason of result.reasons) {
+                    reasons.add(reason);
+                }
+                deniedInputs.push({
+                    surface: input.surface,
+                    ...(input.command !== undefined ? { command: input.command } : {}),
+                    ...(input.path !== undefined ? { path: input.path } : {}),
+                    ...(input.value !== undefined ? { value: input.value } : {}),
+                    reasons: result.reasons
+                });
+            }
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            reasons.add(message);
+            deniedInputs.push({
+                surface: input.surface,
+                ...(input.command !== undefined ? { command: input.command } : {}),
+                ...(input.path !== undefined ? { path: input.path } : {}),
+                ...(input.value !== undefined ? { value: input.value } : {}),
+                reasons: [message]
+            });
+            return {
+                allow: false,
+                reasons: [...reasons],
+                deniedInputs,
+                inputsEvaluated: inputs.length,
+                ...(source ? { source } : {}),
+                ...(policyPath ? { policyPath } : {}),
+                error: message
+            };
+        }
+    }
+    return {
+        allow: deniedInputs.length === 0,
+        reasons: [...reasons],
+        deniedInputs,
+        inputsEvaluated: inputs.length,
+        ...(source ? { source } : {}),
+        ...(policyPath ? { policyPath } : {})
+    };
+}
+function toPolicyViolations(input) {
+    return input.reasons.map((reason) => ({
+        kind: "policy_denied",
+        message: `OPA policy denied ${input.surface}: ${reason}`,
+        ...(input.command ? { command: input.command } : {}),
+        ...(input.path ? { file: input.path } : {}),
+        ...(input.value ? { match: input.value } : {})
+    }));
+}
+function joinReasons(values) {
+    return values.filter((value) => Boolean(value && value.length > 0)).join(" ");
+}
+async function withTimeout(promise, timeoutMs) {
+    let timeout;
+    try {
+        return await Promise.race([
+            promise,
+            new Promise((_, reject) => {
+                timeout = setTimeout(() => reject(new Error(`OPA policy evaluation timed out after ${timeoutMs}ms.`)), timeoutMs);
+            })
+        ]);
+    }
+    finally {
+        if (timeout) {
+            clearTimeout(timeout);
+        }
+    }
+}
+//# sourceMappingURL=policy-leash.js.map

package/dist/vendor/core/memo/memo.d.ts

@@ -0,0 +1,63 @@
+/**
+ * memo.ts — SLICE-03
+ *
+ * Attempt memoization via objective + verifier + file hash key.
+ *
+ * On a cache HIT: the caller replays the stored patch with zero model calls.
+ * On a cache MISS: the caller runs the normal attempt path, then calls storeMemo.
+ *
+ * Cache key: SHA-256 of (objective, verifierCommand, sorted file path → hash pairs)
+ * Cache location: <memoRoot>/<key>/  (default: ~/.martin/memo/)
+ * Invalidation: any file hash change produces a different key → automatic miss
+ * TTL: keys never expire (deterministic inputs → deterministic output is safe to reuse)
+ */
+export interface MemoInput {
+    /** Exact objective text. */
+    objective: string;
+    /** The verifier command string (e.g. "pnpm test"). */
+    verifierCommand: string;
+    /**
+     * Map of relevant file paths → their SHA-256 (or similar) hashes.
+     * Any change in any hash invalidates the cache key.
+     */
+    fileHashes: Record<string, string>;
+}
+export interface MemoEntry {
+    /** The SHA-256 cache key that produced this entry. */
+    key: string;
+    /** Unified diff text that was produced by the original attempt. */
+    patch: string;
+    /** Raw verifier output from the original successful attempt. */
+    verifierOutput: string;
+    /** ISO timestamp when the entry was stored. */
+    storedAt: string;
+}
+/**
+ * Computes the deterministic SHA-256 cache key for a given MemoInput.
+ *
+ * File hashes are sorted by path before hashing so that insertion order
+ * does not affect the key (same files → same key).
+ *
+ * verificationPlan step order IS significant (pass-order matters for verifiers).
+ */
+export declare function computeMemoKey(input: MemoInput): string;
+/**
+ * Returns the stored MemoEntry for the given inputs, or null on a cache miss.
+ *
+ * A miss occurs when:
+ *   - No entry exists for this key (never been run)
+ *   - Any file hash changed (different key → automatic miss)
+ */
+export declare function lookupMemo(input: MemoInput, memoRoot?: string): Promise<MemoEntry | null>;
+/**
+ * Persists a successful attempt result to the memo cache.
+ *
+ * Writes two files under <memoRoot>/<key>/:
+ *   - entry.json — the full MemoEntry (patch + verifier output)
+ *   - cache-hit.json — lightweight provenance artifact for audit trail
+ *
+ * The `entry.key` is set to the computed key before writing.
+ */
+export declare function storeMemo(input: MemoInput, entry: Omit<MemoEntry, "key"> & {
+    key?: string;
+}, memoRoot?: string): Promise<string>;

package/dist/vendor/core/memo/memo.js

@@ -0,0 +1,97 @@
+/**
+ * memo.ts — SLICE-03
+ *
+ * Attempt memoization via objective + verifier + file hash key.
+ *
+ * On a cache HIT: the caller replays the stored patch with zero model calls.
+ * On a cache MISS: the caller runs the normal attempt path, then calls storeMemo.
+ *
+ * Cache key: SHA-256 of (objective, verifierCommand, sorted file path → hash pairs)
+ * Cache location: <memoRoot>/<key>/  (default: ~/.martin/memo/)
+ * Invalidation: any file hash change produces a different key → automatic miss
+ * TTL: keys never expire (deterministic inputs → deterministic output is safe to reuse)
+ */
+import { createHash } from "node:crypto";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { homedir } from "node:os";
+// ---------------------------------------------------------------------------
+// Key computation
+// ---------------------------------------------------------------------------
+/**
+ * Computes the deterministic SHA-256 cache key for a given MemoInput.
+ *
+ * File hashes are sorted by path before hashing so that insertion order
+ * does not affect the key (same files → same key).
+ *
+ * verificationPlan step order IS significant (pass-order matters for verifiers).
+ */
+export function computeMemoKey(input) {
+    const sortedFiles = Object.entries(input.fileHashes)
+        .sort(([a], [b]) => a.localeCompare(b));
+    const canonical = JSON.stringify({
+        objective: input.objective,
+        verifierCommand: input.verifierCommand,
+        fileHashes: Object.fromEntries(sortedFiles)
+    });
+    return createHash("sha256").update(canonical, "utf8").digest("hex");
+}
+// ---------------------------------------------------------------------------
+// Lookup
+// ---------------------------------------------------------------------------
+/**
+ * Returns the stored MemoEntry for the given inputs, or null on a cache miss.
+ *
+ * A miss occurs when:
+ *   - No entry exists for this key (never been run)
+ *   - Any file hash changed (different key → automatic miss)
+ */
+export async function lookupMemo(input, memoRoot = defaultMemoRoot()) {
+    const key = computeMemoKey(input);
+    const entryPath = join(memoRoot, key, "entry.json");
+    try {
+        const raw = await readFile(entryPath, "utf8");
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+}
+// ---------------------------------------------------------------------------
+// Store
+// ---------------------------------------------------------------------------
+/**
+ * Persists a successful attempt result to the memo cache.
+ *
+ * Writes two files under <memoRoot>/<key>/:
+ *   - entry.json — the full MemoEntry (patch + verifier output)
+ *   - cache-hit.json — lightweight provenance artifact for audit trail
+ *
+ * The `entry.key` is set to the computed key before writing.
+ */
+export async function storeMemo(input, entry, memoRoot = defaultMemoRoot()) {
+    const key = computeMemoKey(input);
+    const keyDir = join(memoRoot, key);
+    await mkdir(keyDir, { recursive: true });
+    const fullEntry = { ...entry, key };
+    // Write the main entry
+    await writeFile(join(keyDir, "entry.json"), `${JSON.stringify(fullEntry, null, 2)}\n`, "utf8");
+    // Write the provenance artifact (lightweight, safe to read without loading full patch)
+    const provenance = {
+        key,
+        objective: input.objective,
+        verifierCommand: input.verifierCommand,
+        fileCount: Object.keys(input.fileHashes).length,
+        storedAt: entry.storedAt
+    };
+    await writeFile(join(keyDir, "cache-hit.json"), `${JSON.stringify(provenance, null, 2)}\n`, "utf8");
+    return key;
+}
+// ---------------------------------------------------------------------------
+// Internals
+// ---------------------------------------------------------------------------
+function defaultMemoRoot() {
+    return process.env["MARTIN_MEMO_DIR"]?.trim()
+        ?? join(homedir(), ".martin", "memo");
+}
+//# sourceMappingURL=memo.js.map