martin-loop 0.1.1 → 0.1.3

package/dist/vendor/core/persistence/store.js

@@ -0,0 +1,84 @@
+/// <reference types="node" />
+import { appendFile, mkdir, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+// ─── FileRunStore implementation ─────────────────────────────────────────────
+export function resolveRunsRoot(env = process.env) {
+    return env["MARTIN_RUNS_DIR"]?.trim() ??
+        join(homedir(), ".martin", "runs");
+}
+export function runDir(runsRoot, runId) {
+    return join(runsRoot, runId);
+}
+export function artifactDir(runsRoot, runId, attemptIndex) {
+    return join(runsRoot, runId, "artifacts", `attempt-${String(attemptIndex).padStart(3, "0")}`);
+}
+/**
+ * Filesystem-backed RunStore. Writes to:
+ *   <runsRoot>/<runId>/contract.json
+ *   <runsRoot>/<runId>/state.json
+ *   <runsRoot>/<runId>/ledger.jsonl
+ *   <runsRoot>/<runId>/artifacts/attempt-<n>/compiled-context.json
+ *   <runsRoot>/<runId>/artifacts/attempt-<n>/diff.patch (if diff provided)
+ *   <runsRoot>/<runId>/artifacts/attempt-<n>/verifier-output.txt (if provided)
+ *   <runsRoot>/<runId>/artifacts/attempt-<n>/grounding-scan.json (if provided)
+ *   <runsRoot>/<runId>/artifacts/attempt-<n>/leash.json (if leash provided)
+ *   <runsRoot>/<runId>/artifacts/attempt-<n>/patch-score.json (if patchScore provided)
+ *   <runsRoot>/<runId>/artifacts/attempt-<n>/patch-decision.json (if patchDecision provided)
+ *   <runsRoot>/<runId>/artifacts/attempt-<n>/rollback-boundary.json (if rollbackBoundary provided)
+ *   <runsRoot>/<runId>/artifacts/attempt-<n>/rollback-outcome.json (if rollbackOutcome provided)
+ */
+export function createFileRunStore(options = {}) {
+    const runsRoot = options.runsRoot ?? resolveRunsRoot();
+    return {
+        async initRun(contract) {
+            const dir = runDir(runsRoot, contract.runId);
+            await mkdir(dir, { recursive: true });
+            await writeJsonFile(join(dir, "contract.json"), contract);
+        },
+        async updateState(runId, state) {
+            const dir = runDir(runsRoot, runId);
+            await mkdir(dir, { recursive: true });
+            await writeJsonFile(join(dir, "state.json"), state);
+        },
+        async appendLedger(runId, event) {
+            const dir = runDir(runsRoot, runId);
+            await mkdir(dir, { recursive: true });
+            await appendFile(join(dir, "ledger.jsonl"), `${JSON.stringify(event)}\n`, "utf8");
+        },
+        async writeAttemptArtifacts(runId, attemptIndex, artifacts) {
+            const dir = artifactDir(runsRoot, runId, attemptIndex);
+            await mkdir(dir, { recursive: true });
+            await writeJsonFile(join(dir, "compiled-context.json"), artifacts.compiledContext);
+            if (artifacts.diff !== undefined) {
+                await writeFile(join(dir, "diff.patch"), artifacts.diff, "utf8");
+            }
+            if (artifacts.verifierOutput !== undefined) {
+                await writeFile(join(dir, "verifier-output.txt"), artifacts.verifierOutput, "utf8");
+            }
+            if (artifacts.groundingScan !== undefined) {
+                await writeJsonFile(join(dir, "grounding-scan.json"), artifacts.groundingScan);
+            }
+            if (artifacts.leash !== undefined) {
+                await writeJsonFile(join(dir, "leash.json"), artifacts.leash);
+            }
+            if (artifacts.patchScore !== undefined) {
+                await writeJsonFile(join(dir, "patch-score.json"), artifacts.patchScore);
+            }
+            if (artifacts.patchDecision !== undefined) {
+                await writeJsonFile(join(dir, "patch-decision.json"), artifacts.patchDecision);
+            }
+            if (artifacts.rollbackBoundary !== undefined) {
+                await writeJsonFile(join(dir, "rollback-boundary.json"), artifacts.rollbackBoundary);
+            }
+            if (artifacts.rollbackOutcome !== undefined) {
+                await writeJsonFile(join(dir, "rollback-outcome.json"), artifacts.rollbackOutcome);
+            }
+        }
+    };
+}
+// ─── Helpers ─────────────────────────────────────────────────────────────────
+async function writeJsonFile(path, value) {
+    await writeFile(path, `${JSON.stringify(value, null, 2)}\n`, "utf8");
+}
+//# sourceMappingURL=store.js.map

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

@@ -0,0 +1,126 @@
+import type { BudgetPreflightEstimate, CostProvenance, EvidenceVector, FailureClass, InterventionType, LoopAttempt, LoopBudget, LoopCost, LoopLifecycleState, LoopStatus, PatchDecisionArtifact, PatchScore, PolicyPhase } from "../contracts/index.js";
+export interface FailureAssessment {
+    failureClass: FailureClass;
+    rationale: string;
+    retryable: boolean;
+    recommendedIntervention: InterventionType;
+}
+export interface CostGovernorState {
+    pressure: "healthy" | "soft_limit" | "hard_limit";
+    shouldStop: boolean;
+    remainingBudgetUsd: number;
+    remainingIterations: number;
+    remainingTokens: number;
+    recommendedIntervention?: InterventionType;
+}
+export interface ExitDecision {
+    shouldExit: boolean;
+    lifecycleState: LoopLifecycleState;
+    status: LoopStatus;
+    reason: string;
+}
+export interface MartinAdapterResultLike {
+    status: "completed" | "failed";
+    summary: string;
+    usage?: {
+        actualUsd: number;
+        estimatedUsd?: number;
+        tokensIn: number;
+        tokensOut: number;
+        provenance?: CostProvenance;
+    };
+    verification: {
+        passed: boolean;
+        summary: string;
+    };
+    failure?: {
+        message: string;
+        classHint?: FailureClass;
+    };
+}
+/**
+ * Maps a PolicyPhase to the LoopLifecycleState used in events and persistence.
+ * FailureClass remains a thin output label — policy reads EvidenceVector, not the label.
+ */
+export declare function policyPhaseToLifecycleState(phase: PolicyPhase): LoopLifecycleState;
+/**
+ * Determines the next PolicyPhase given the current phase and last result.
+ * This is the explicit typed transition table — no implicit fallthrough.
+ */
+export declare function nextPolicyPhase(current: PolicyPhase, result: MartinAdapterResultLike, costState: CostGovernorState, retryCount: number): PolicyPhase;
+export declare function classifyFailure(input: {
+    attempts: LoopAttempt[];
+    result: MartinAdapterResultLike;
+}): FailureAssessment;
+export declare function evaluateCostGovernor(input: {
+    budget: LoopBudget;
+    cost: LoopCost;
+    attemptsUsed: number;
+}): CostGovernorState;
+export declare function inferExit(input: {
+    loop: {
+        budget: LoopBudget;
+        cost: LoopCost;
+        attempts: LoopAttempt[];
+    };
+    lastResult: MartinAdapterResultLike;
+    lastFailure?: FailureAssessment;
+    costState: CostGovernorState;
+    canSwitchAdapter?: boolean;
+}): ExitDecision;
+export interface BudgetPreflightInput {
+    promptCharCount: number;
+    attemptCount: number;
+    remainingBudgetUsd: number;
+    perAttemptCapUsd?: number;
+    pricePerMTokenUsd?: number;
+}
+export interface BudgetPreflightDecision {
+    allowed: boolean;
+    reason: string;
+    estimate: BudgetPreflightEstimate;
+}
+export declare function evaluateBudgetPreflight(input: BudgetPreflightInput): BudgetPreflightDecision;
+export interface EvidenceVectorInput {
+    compilerOutput?: string;
+    testOutput?: string;
+    diff?: string;
+    previousDiff?: string;
+    forbiddenTouchedFiles?: string[];
+    missingSymbols?: string[];
+    actualUsd?: number;
+    previousVerifierScore?: number;
+    verifierScore?: number;
+    retryCountForSurface?: number;
+}
+export declare function computeEvidenceVector(input: EvidenceVectorInput): EvidenceVector;
+export type RecoveryRecipe = "narrow_prompt_targeted_files" | "failing_tests_only" | "force_repo_anatomy_slices" | "tighten_allowlist_reduce_patch" | "strategy_swap" | "abort_safety_violation" | "downgrade_model" | "escalate_human";
+export interface RecoveryDecision {
+    recipe: RecoveryRecipe;
+    rationale: string;
+    intervention: InterventionType;
+}
+export interface PatchDecisionInput {
+    verificationPassed: boolean;
+    previousVerifierScore?: number;
+    verifierScore?: number;
+    groundingViolationCount?: number;
+    safetyViolationCount?: number;
+    scopeViolationCount?: number;
+    changedFileCount?: number;
+    diffNovelty?: number;
+    diffStats?: {
+        filesChanged: number;
+        addedLines: number;
+        deletedLines: number;
+    };
+    costUsd?: number;
+    humanApprovalRequired?: boolean;
+    summary?: string;
+}
+export interface EvaluatedPatchDecision extends PatchDecisionArtifact {
+    score: PatchScore;
+}
+export declare function selectRecoveryRecipe(evidence: EvidenceVector): RecoveryDecision;
+export declare function evaluatePatchDecision(input: PatchDecisionInput): EvaluatedPatchDecision;
+export declare function scorePatchDecision(input: PatchDecisionInput): PatchScore;