martin-loop 0.1.5 → 1.3.0

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

package/dist/vendor/core/memory/learning-pipeline.d.ts

@@ -0,0 +1,154 @@
+/**
+ * learning-pipeline.ts
+ *
+ * Guarded promotion pipeline for self-improving memory heuristics.
+ *
+ * Flow: candidate → shadow test → holdout validation → approval gate → promoted
+ *
+ * A learning candidate NEVER becomes an active heuristic without passing:
+ *   1. Shadow tests (runs in parallel with existing logic, results compared)
+ *   2. Holdout validation (tested on a held-out set, not the training data)
+ *   3. Approval gate (auto-approved if confidence >= threshold, else requires manual sign-off)
+ *
+ * Fail-open: any pipeline error keeps the existing heuristic active untouched.
+ */
+export type CandidateStatus = "pending_shadow" | "shadow_passed" | "shadow_failed" | "holdout_passed" | "holdout_failed" | "approved" | "manual_review" | "promoted" | "blocked_protected_surface" | "rejected" | "rolled_back";
+export interface LearningCandidateProvenance {
+    sourceType: "trace-intelligence" | "manual" | "memory-palace";
+    patternId?: string;
+    evidenceRunIds?: string[];
+    generatedAt: string;
+    confidenceScore?: number;
+}
+export interface LearningCandidateRollbackPlan {
+    strategy: "restore_last_known_good" | "disable_candidate";
+    note?: string;
+}
+export interface LearningCandidate {
+    candidateId: string;
+    sourceRunId: string;
+    heuristicFamily: string;
+    description: string;
+    payload: Record<string, unknown>;
+    status: CandidateStatus;
+    provenance?: LearningCandidateProvenance;
+    proposedPaths?: string[];
+    rollbackPlan?: LearningCandidateRollbackPlan;
+    shadowPassRate?: number;
+    holdoutPassRate?: number;
+    approvedAt?: string;
+    rejectedAt?: string;
+    rejectedReason?: string;
+    createdAt: string;
+}
+export interface ShadowTestResult {
+    candidateId: string;
+    totalCases: number;
+    passedCases: number;
+    passRate: number;
+    passed: boolean;
+}
+export interface HoldoutResult {
+    candidateId: string;
+    holdoutSize: number;
+    passedCases: number;
+    passRate: number;
+    passed: boolean;
+}
+export interface ApprovalGateConfig {
+    /** Auto-approve when holdout pass rate meets or exceeds this threshold (0–1). Default: 0.85 */
+    autoApproveThreshold: number;
+    /** If true, always require manual sign-off regardless of pass rate */
+    requireManualApproval: boolean;
+}
+export interface PromotionResult {
+    candidateId: string;
+    promoted: boolean;
+    reason: string;
+}
+export interface ActiveLearningHeuristics {
+    schemaVersion: "1.0";
+    updatedAt: string;
+    recallScoring: {
+        failureClassWeight: number;
+        interventionWeight: number;
+        tokenOverlapWeight: number;
+        completionWeight: number;
+    };
+}
+export interface LearningPipelineSummaryEntry {
+    candidateId: string;
+    heuristicFamily: string;
+    status: CandidateStatus;
+    sourceRunId: string;
+    createdAt: string;
+    confidenceScore?: number;
+    summary: string;
+    patternId?: string;
+}
+export interface LearningPipelineSummary {
+    counts: {
+        proposed: number;
+        shadowPassed: number;
+        holdoutPassed: number;
+        approved: number;
+        promoted: number;
+        rejected: number;
+        blockedProtectedSurface: number;
+        rolledBack: number;
+    };
+    protectedPaths: string[];
+    entries: LearningPipelineSummaryEntry[];
+}
+export declare const DEFAULT_PROTECTED_LEARNING_PATHS: readonly ["packages/core/src/leash.ts", "packages/core/src/leash/**", "packages/core/src/policy.ts", "packages/core/src/grounding.ts", "packages/core/src/security/**", "packages/core/src/attestation/**", "packages/contracts/src/**", "packages/mcp/src/**", "packages/cli/src/index.ts", "docs/release/**", "docs/security/**", "docs/handoffs/**", ".planning/**", "scripts/**"];
+export declare const DEFAULT_ACTIVE_LEARNING_HEURISTICS: ActiveLearningHeuristics;
+/**
+ * Runs the candidate heuristic in shadow mode alongside the existing logic.
+ * The shadow result is compared but never used to change actual behaviour.
+ *
+ * `existingScores` and `candidateScores` are parallel arrays — one per recall query.
+ * A case is "passed" when the candidate score >= existing score (does not regress).
+ */
+export declare function runShadowTest(candidateId: string, existingScores: number[], candidateScores: number[]): ShadowTestResult;
+/**
+ * Validates the candidate against a held-out set (data not used to build the candidate).
+ * The holdout set is scored by both the existing and candidate heuristic;
+ * the candidate passes if it meets or exceeds the existing on >= 80% of cases.
+ */
+export declare function runHoldoutValidation(candidateId: string, holdoutExistingScores: number[], holdoutCandidateScores: number[]): HoldoutResult;
+/**
+ * Determines whether a candidate can be promoted based on holdout results and
+ * the configured approval policy.
+ *
+ * Auto-approves when:
+ *   - holdout passed AND holdoutPassRate >= autoApproveThreshold
+ *   - AND requireManualApproval is false
+ *
+ * In all other cases, the candidate is held at "holdout_passed" status and
+ * awaits manual sign-off (future: webhook / dashboard approval flow).
+ */
+export declare function evaluateApprovalGate(holdout: HoldoutResult, config?: ApprovalGateConfig): {
+    approved: boolean;
+    reason: string;
+};
+export declare function persistCandidate(candidate: LearningCandidate, pipelineRoot: string): Promise<void>;
+export declare function loadCandidate(candidateId: string, pipelineRoot: string): Promise<LearningCandidate | undefined>;
+export declare function loadActiveLearningHeuristics(pipelineRoot: string): Promise<ActiveLearningHeuristics>;
+export declare function summarizeLearningPipeline(pipelineRoot: string): Promise<LearningPipelineSummary>;
+export interface PipelineInput {
+    candidate: LearningCandidate;
+    existingScores: number[];
+    candidateScores: number[];
+    holdoutExistingScores: number[];
+    holdoutCandidateScores: number[];
+    approvalConfig?: ApprovalGateConfig;
+    pipelineRoot: string;
+}
+/**
+ * Runs the full guarded promotion pipeline:
+ * shadow → holdout → approval gate → persist result.
+ *
+ * Returns whether the candidate was promoted to "approved" status.
+ * Never throws — any error is caught and candidate is marked rejected.
+ */
+export declare function runPromotionPipeline(input: PipelineInput): Promise<PromotionResult>;