martin-loop 0.1.5 → 1.3.0

package/dist/vendor/core/drift/drift-graph.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Lightweight adjacency-list graph used by scope pruning (SLICE-02).
+ * Nodes are file paths (or symbol names). Edges represent import/reference
+ * relationships: for each node, the array contains its direct dependents.
+ */
+export interface DriftGraph {
+    /** Complete set of known node identifiers (file paths or symbol names). */
+    nodes: Set<string>;
+    /** Adjacency list: node → list of directly connected nodes (1 hop). */
+    edges: Record<string, string[]>;
+}
+export interface DriftReport {
+    changedExports: string[];
+    affectedImporters: Array<{
+        file: string;
+        importedSymbol: string;
+    }>;
+    /** Importers with no test coverage for the changed symbol */
+    unvalidatedDownstream: string[];
+    /** true only if unvalidatedDownstream is empty */
+    safe: boolean;
+}
+export interface DriftInput {
+    /** Workspace root — ts-morph will glob all .ts files under it */
+    rootDir: string;
+    /** Path of the changed file, relative to rootDir (forward slashes) */
+    changedFile: string;
+    /** List of exported symbol names that changed */
+    changedExports: string[];
+    /** List of test file paths (absolute or relative to rootDir) that cover the changed symbols */
+    testFiles: string[];
+}
+/**
+ * Builds a DriftReport by walking the workspace with ts-morph.
+ *
+ * Algorithm:
+ * 1. If changedExports is empty → safe: true immediately (no public API touched)
+ * 2. Walk all .ts files (excluding node_modules) looking for imports of any changed symbol
+ * 3. For each importer, check if a test file also imports the same changed symbol
+ * 4. Importers without test coverage → unvalidatedDownstream → safe: false
+ */
+export declare function buildDriftReport(input: DriftInput): Promise<DriftReport>;
+/**
+ * Builds and writes drift-report.json to the run output directory.
+ * Only writes if changedExports is non-empty (no drift = no report needed).
+ */
+export declare function emitDriftReport(input: DriftInput, runDir: string): Promise<DriftReport>;

package/dist/vendor/core/drift/drift-graph.js

@@ -0,0 +1,100 @@
+import { writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { Project } from "ts-morph";
+// ─── Core builder ─────────────────────────────────────────────────────────────
+/**
+ * Builds a DriftReport by walking the workspace with ts-morph.
+ *
+ * Algorithm:
+ * 1. If changedExports is empty → safe: true immediately (no public API touched)
+ * 2. Walk all .ts files (excluding node_modules) looking for imports of any changed symbol
+ * 3. For each importer, check if a test file also imports the same changed symbol
+ * 4. Importers without test coverage → unvalidatedDownstream → safe: false
+ */
+export async function buildDriftReport(input) {
+    if (input.changedExports.length === 0) {
+        return {
+            changedExports: [],
+            affectedImporters: [],
+            unvalidatedDownstream: [],
+            safe: true
+        };
+    }
+    const project = new Project({
+        skipAddingFilesFromTsConfig: true
+    });
+    // Add all .ts files from rootDir (not node_modules, not .d.ts)
+    project.addSourceFilesAtPaths([
+        normalizePath(join(input.rootDir, "**/*.ts")),
+        `!${normalizePath(join(input.rootDir, "**/node_modules/**"))}`,
+        `!${normalizePath(join(input.rootDir, "**/*.d.ts"))}`
+    ]);
+    const changedFilePath = normalizePath(join(input.rootDir, input.changedFile));
+    const affectedImporters = [];
+    for (const sourceFile of project.getSourceFiles()) {
+        const filePath = normalizePath(sourceFile.getFilePath());
+        // Skip the changed file itself
+        if (filePath === changedFilePath)
+            continue;
+        // Check import declarations for any of the changed symbols
+        for (const importDecl of sourceFile.getImportDeclarations()) {
+            const namedImports = importDecl.getNamedImports();
+            for (const namedImport of namedImports) {
+                const symbolName = namedImport.getName();
+                if (input.changedExports.includes(symbolName)) {
+                    affectedImporters.push({
+                        file: filePath,
+                        importedSymbol: symbolName
+                    });
+                }
+            }
+        }
+    }
+    // Determine which importers are test files (by path convention or explicit list)
+    const testFilePaths = new Set(input.testFiles.map(f => normalizePath(f.startsWith("/") || /^[A-Za-z]:/.test(f)
+        ? f
+        : join(input.rootDir, f))));
+    // Also treat files matching *.test.ts or *.spec.ts as test files
+    const testSymbolsCovered = new Set();
+    for (const importer of affectedImporters) {
+        const isTestFile = testFilePaths.has(importer.file) ||
+            /\.(test|spec)\.[tj]s$/.test(importer.file);
+        if (isTestFile) {
+            testSymbolsCovered.add(importer.importedSymbol);
+        }
+    }
+    // unvalidatedDownstream = non-test importers whose symbol has no test coverage
+    const unvalidatedDownstream = [];
+    for (const importer of affectedImporters) {
+        const isTestFile = testFilePaths.has(importer.file) ||
+            /\.(test|spec)\.[tj]s$/.test(importer.file);
+        if (!isTestFile && !testSymbolsCovered.has(importer.importedSymbol)) {
+            if (!unvalidatedDownstream.includes(importer.file)) {
+                unvalidatedDownstream.push(importer.file);
+            }
+        }
+    }
+    return {
+        changedExports: input.changedExports,
+        affectedImporters,
+        unvalidatedDownstream,
+        safe: unvalidatedDownstream.length === 0
+    };
+}
+// ─── Emitter ──────────────────────────────────────────────────────────────────
+/**
+ * Builds and writes drift-report.json to the run output directory.
+ * Only writes if changedExports is non-empty (no drift = no report needed).
+ */
+export async function emitDriftReport(input, runDir) {
+    const report = await buildDriftReport(input);
+    if (input.changedExports.length > 0) {
+        await writeFile(join(runDir, "drift-report.json"), JSON.stringify(report, null, 2), "utf8");
+    }
+    return report;
+}
+// ─── Internal helpers ─────────────────────────────────────────────────────────
+function normalizePath(p) {
+    return p.replace(/\\/g, "/");
+}
+//# sourceMappingURL=drift-graph.js.map

package/dist/vendor/core/drift/objective-lock.d.ts

@@ -0,0 +1,69 @@
+/**
+ * objective-lock.ts — SLICE-05
+ *
+ * Cryptographic objective invariant lock.
+ *
+ * At attempt 1, the loop objective, verificationPlan, and acceptanceCriteria
+ * are hashed together into a SHA-256 lock. Every subsequent attempt re-hashes
+ * the live inputs and hard-fails with `objective_drift` if the hash differs.
+ *
+ * Legitimate scope changes require an explicit `widenObjectiveLock()` call,
+ * which produces an audit entry proving who authorized the change and why.
+ */
+export interface ObjectiveLockInput {
+    objective: string;
+    verificationPlan: string[];
+    acceptanceCriteria?: string[];
+}
+export interface ObjectiveLock {
+    /** SHA-256 hex digest of the canonical lock payload. */
+    sha256: string;
+    /** ISO timestamp when the lock was created. */
+    lockedAt: string;
+}
+export interface ObjectiveLockCheckResult {
+    drifted: boolean;
+    /** Present only when drifted:true. */
+    reason?: string;
+    expectedHash?: string;
+    actualHash?: string;
+}
+export interface ObjectiveWidenAuditEntry {
+    previousHash: string;
+    newHash: string;
+    authorizedBy: string;
+    reason: string;
+    widenedAt: string;
+}
+export interface ObjectiveWidenResult {
+    newLock: ObjectiveLock;
+    auditEntry: ObjectiveWidenAuditEntry;
+}
+/**
+ * Creates a new ObjectiveLock for the given inputs.
+ * Call once at loop start (attempt 1). Store in the loop record.
+ */
+export declare function createObjectiveLock(input: ObjectiveLockInput, now?: string): ObjectiveLock;
+/**
+ * Checks whether the live inputs still match the lock created at attempt 1.
+ *
+ * Returns `{ drifted: false }` if everything is consistent.
+ * Returns `{ drifted: true, reason, expectedHash, actualHash }` if the lock
+ * has been violated — the caller MUST exit the loop with lifecycleState
+ * `objective_drift`.
+ */
+export declare function checkObjectiveLock(lock: ObjectiveLock, currentInput: ObjectiveLockInput): ObjectiveLockCheckResult;
+/**
+ * Authorizes a legitimate scope change. Returns a new lock covering the
+ * new inputs and an immutable audit entry recording who widened it and why.
+ *
+ * The audit entry MUST be appended to the loop's ledger.jsonl before the
+ * run continues with the new lock.
+ */
+export declare function widenObjectiveLock(options: {
+    currentLock: ObjectiveLock;
+    newInput: ObjectiveLockInput;
+    authorizedBy: string;
+    reason: string;
+    now?: string;
+}): ObjectiveWidenResult;

package/dist/vendor/core/drift/objective-lock.js

@@ -0,0 +1,88 @@
+/**
+ * objective-lock.ts — SLICE-05
+ *
+ * Cryptographic objective invariant lock.
+ *
+ * At attempt 1, the loop objective, verificationPlan, and acceptanceCriteria
+ * are hashed together into a SHA-256 lock. Every subsequent attempt re-hashes
+ * the live inputs and hard-fails with `objective_drift` if the hash differs.
+ *
+ * Legitimate scope changes require an explicit `widenObjectiveLock()` call,
+ * which produces an audit entry proving who authorized the change and why.
+ */
+import { createHash } from "node:crypto";
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+/**
+ * Creates a new ObjectiveLock for the given inputs.
+ * Call once at loop start (attempt 1). Store in the loop record.
+ */
+export function createObjectiveLock(input, now = new Date().toISOString()) {
+    return {
+        sha256: computeHash(input),
+        lockedAt: now
+    };
+}
+/**
+ * Checks whether the live inputs still match the lock created at attempt 1.
+ *
+ * Returns `{ drifted: false }` if everything is consistent.
+ * Returns `{ drifted: true, reason, expectedHash, actualHash }` if the lock
+ * has been violated — the caller MUST exit the loop with lifecycleState
+ * `objective_drift`.
+ */
+export function checkObjectiveLock(lock, currentInput) {
+    const currentHash = computeHash(currentInput);
+    if (currentHash === lock.sha256) {
+        return { drifted: false };
+    }
+    return {
+        drifted: true,
+        reason: `Objective lock violated: expected hash ${lock.sha256.slice(0, 12)}… ` +
+            `but got ${currentHash.slice(0, 12)}… — run aborted with lifecycle state objective_drift`,
+        expectedHash: lock.sha256,
+        actualHash: currentHash
+    };
+}
+/**
+ * Authorizes a legitimate scope change. Returns a new lock covering the
+ * new inputs and an immutable audit entry recording who widened it and why.
+ *
+ * The audit entry MUST be appended to the loop's ledger.jsonl before the
+ * run continues with the new lock.
+ */
+export function widenObjectiveLock(options) {
+    const widenedAt = options.now ?? new Date().toISOString();
+    const newLock = createObjectiveLock(options.newInput, widenedAt);
+    const auditEntry = {
+        previousHash: options.currentLock.sha256,
+        newHash: newLock.sha256,
+        authorizedBy: options.authorizedBy,
+        reason: options.reason,
+        widenedAt
+    };
+    return { newLock, auditEntry };
+}
+// ---------------------------------------------------------------------------
+// Internal — canonical hash computation
+// ---------------------------------------------------------------------------
+/**
+ * Produces a deterministic SHA-256 hex digest over:
+ *   - objective (exact text, case-sensitive)
+ *   - verificationPlan (ordered — step order matters)
+ *   - acceptanceCriteria (sorted — order-independent)
+ *
+ * The canonical payload is a stable JSON string to ensure cross-platform
+ * determinism regardless of property insertion order.
+ */
+function computeHash(input) {
+    const sortedCriteria = [...(input.acceptanceCriteria ?? [])].sort();
+    const canonical = JSON.stringify({
+        objective: input.objective,
+        verificationPlan: input.verificationPlan,
+        acceptanceCriteria: sortedCriteria
+    });
+    return createHash("sha256").update(canonical, "utf8").digest("hex");
+}
+//# sourceMappingURL=objective-lock.js.map

package/dist/vendor/core/drift/scope.d.ts

@@ -0,0 +1,46 @@
+/**
+ * scope.ts — SLICE-02
+ *
+ * Drift-graph–scoped context pruning.
+ *
+ * Uses the existing DriftGraph to prune model input context to only the files
+ * within N hops of the objective's named symbols/paths. Prevents the model
+ * from seeing irrelevant files and keeps token budgets tight.
+ */
+import type { DriftGraph } from "./drift-graph.js";
+export interface ScopePruningResult {
+    /** The pruned (or fallback) file list to pass to the model. */
+    files: string[];
+    /** Number of files in the original compiledFiles list. */
+    filesIn: number;
+    /** Number of files returned after pruning. */
+    filesOut: number;
+    /** filesIn - filesOut */
+    prunedCount: number;
+    /** true when the BFS intersection was empty and we fell back to the full set. */
+    fallback: boolean;
+}
+/**
+ * Extracts file-like identifiers from an objective string.
+ *
+ * Matches (in priority order):
+ * 1. Quoted paths  — "src/parser.ts"
+ * 2. Bare paths ending in .ts / .js / .tsx / .jsx
+ * 3. camelCase / PascalCase tokens that look like module/symbol names
+ *
+ * Note: intentionally uses regex, not AST (that's SLICE-06).
+ */
+export declare function extractFilesFromObjective(objective: string): string[];
+/**
+ * Prunes `compiledFiles` to only those reachable from the objective's seed
+ * nodes within `maxHops` traversal steps in `graph`.
+ *
+ * Falls back to the full compiledFiles set when the BFS result has no
+ * intersection with compiledFiles (e.g. graph uses different path conventions).
+ */
+export declare function scopeContextByDriftGraph(options: {
+    objective: string;
+    graph: DriftGraph;
+    compiledFiles: string[];
+    maxHops?: number;
+}): ScopePruningResult;

package/dist/vendor/core/drift/scope.js

@@ -0,0 +1,102 @@
+/**
+ * scope.ts — SLICE-02
+ *
+ * Drift-graph–scoped context pruning.
+ *
+ * Uses the existing DriftGraph to prune model input context to only the files
+ * within N hops of the objective's named symbols/paths. Prevents the model
+ * from seeing irrelevant files and keeps token budgets tight.
+ */
+// ─── Public API ───────────────────────────────────────────────────────────────
+/**
+ * Extracts file-like identifiers from an objective string.
+ *
+ * Matches (in priority order):
+ * 1. Quoted paths  — "src/parser.ts"
+ * 2. Bare paths ending in .ts / .js / .tsx / .jsx
+ * 3. camelCase / PascalCase tokens that look like module/symbol names
+ *
+ * Note: intentionally uses regex, not AST (that's SLICE-06).
+ */
+export function extractFilesFromObjective(objective) {
+    const found = new Set();
+    // 1. Quoted file paths — single or double quotes
+    const quotedRe = /["']([^"'\n]+(?:\.(?:ts|tsx|js|jsx)|[A-Za-z0-9_/.-]+))["']/g;
+    for (const match of objective.matchAll(quotedRe)) {
+        if (match[1])
+            found.add(match[1]);
+    }
+    // 2. Bare paths ending in a recognised extension (not already captured in quotes)
+    const barePathRe = /(?<![/"'])([^\s"']+\.(?:ts|tsx|js|jsx))(?![/"'])/g;
+    for (const match of objective.matchAll(barePathRe)) {
+        if (match[1])
+            found.add(match[1]);
+    }
+    // 3. camelCase / PascalCase identifiers (potential module / symbol names)
+    //    Must start with an uppercase letter or have an internal uppercase letter,
+    //    and be at least 4 chars so we avoid common short words.
+    const camelCaseRe = /\b(?:[A-Z][a-zA-Z0-9]{3,}|[a-z][a-z0-9]*[A-Z][a-zA-Z0-9]{2,})\b/g;
+    for (const match of objective.matchAll(camelCaseRe)) {
+        found.add(match[0]);
+    }
+    return [...found];
+}
+/**
+ * Prunes `compiledFiles` to only those reachable from the objective's seed
+ * nodes within `maxHops` traversal steps in `graph`.
+ *
+ * Falls back to the full compiledFiles set when the BFS result has no
+ * intersection with compiledFiles (e.g. graph uses different path conventions).
+ */
+export function scopeContextByDriftGraph(options) {
+    const { objective, graph, compiledFiles, maxHops = 2 } = options;
+    const filesIn = compiledFiles.length;
+    // Extract seed identifiers from objective text
+    const seeds = extractFilesFromObjective(objective);
+    // BFS from all seed nodes that exist in the graph
+    const reachable = new Set();
+    const queue = [];
+    for (const seed of seeds) {
+        if (graph.nodes.has(seed)) {
+            queue.push({ node: seed, depth: 0 });
+            reachable.add(seed);
+        }
+    }
+    // Process BFS queue
+    let head = 0;
+    while (head < queue.length) {
+        // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+        const item = queue[head++];
+        if (item.depth >= maxHops)
+            continue;
+        const neighbors = graph.edges[item.node] ?? [];
+        for (const neighbor of neighbors) {
+            if (!reachable.has(neighbor)) {
+                reachable.add(neighbor);
+                queue.push({ node: neighbor, depth: item.depth + 1 });
+            }
+        }
+    }
+    // Intersect BFS result with compiledFiles (preserve original ordering)
+    const compiledSet = new Set(compiledFiles);
+    const pruned = compiledFiles.filter(f => reachable.has(f));
+    // Fallback: if intersection is empty return the full original set
+    if (pruned.length === 0) {
+        return {
+            files: [...compiledFiles],
+            filesIn,
+            filesOut: filesIn,
+            prunedCount: 0,
+            fallback: true
+        };
+    }
+    const filesOut = pruned.length;
+    return {
+        files: pruned,
+        filesIn,
+        filesOut,
+        prunedCount: filesIn - filesOut,
+        fallback: false
+    };
+}
+//# sourceMappingURL=scope.js.map

package/dist/vendor/core/drift/signature-lock.d.ts

@@ -0,0 +1,48 @@
+/**
+ * signature-lock.ts — SLICE-06
+ *
+ * AST-level signature lock: extracts named symbols from an objective,
+ * snapshots their TypeScript signatures before the first attempt, then
+ * rejects any patch that silently changes a signature without authorization.
+ *
+ * Authorization phrases in the objective (e.g. "add parameter", "rename")
+ * allow signature changes for the named symbol.
+ */
+export interface SignatureSnapshot {
+    symbolName: string;
+    filePath: string;
+    params: string[];
+    returnType: string;
+    modifiers: string[];
+    kind: "function" | "method" | "class" | "unknown";
+}
+export interface SignatureLockResult {
+    blocked: boolean;
+    reasonCode?: "silent_signature_drift";
+    reason?: string;
+    driftedSymbols: Array<{
+        symbolName: string;
+        before: SignatureSnapshot;
+        after: SignatureSnapshot;
+    }>;
+}
+export declare function isSignatureChangeAuthorized(objective: string, symbolName: string): boolean;
+/**
+ * Extracts likely symbol names from the objective string.
+ * Looks for: camelCase, PascalCase, snake_case, and `backtick` quoted names.
+ */
+export declare function extractSymbolsFromObjective(objective: string): string[];
+export declare function snapshotsEqual(a: SignatureSnapshot, b: SignatureSnapshot): boolean;
+export declare class SignatureLockStore {
+    private snapshots;
+    record(snapshot: SignatureSnapshot): void;
+    get(symbolName: string): SignatureSnapshot | undefined;
+    has(symbolName: string): boolean;
+    clear(): void;
+}
+export declare function checkSignatureDrift(objective: string, before: SignatureSnapshot[], after: SignatureSnapshot[]): SignatureLockResult;
+/**
+ * Extracts SignatureSnapshots for named symbols from TypeScript source code.
+ * Uses ts-morph if available; falls back to a regex-based approximation.
+ */
+export declare function extractSignaturesFromSource(sourceCode: string, filePath: string, targetSymbols: string[]): Promise<SignatureSnapshot[]>;