@interf/compiler 0.9.5 → 0.16.0

package/dist/packages/engine/runtime-caches.js

@@ -0,0 +1,191 @@
+/**
+ * Runtime read-side caches.
+ *
+ * The local service runtime fronts a filesystem-backed model: every
+ * "list" or "get" call walks `.interf/runtime/...`, parses each JSON
+ * record through Zod, and returns the typed shape. Polling clients
+ * (Compiler UI, CLI status loops) hit those endpoints multiple times
+ * per second; on workspaces with hundreds of compile / test runs this
+ * shows up as the dominant CPU cost.
+ *
+ * The caches here memoize the parsed-and-validated results. Each cache
+ * is per-workspace so multi-workspace runtimes do not cross-pollinate,
+ * and each cache exposes both a read path (`get(...)`) and an explicit
+ * invalidation hook (`invalidate(...)`). The runtime calls
+ * `invalidate*` whenever it writes, so the next read repopulates from
+ * disk. Invalidation is intentionally broad (per-preparation, not
+ * per-record) — staleness is the only correctness bug worth avoiding,
+ * and per-record invalidation introduces fan-out without measurably
+ * lowering recompute cost.
+ */
+import { existsSync, statSync } from "node:fs";
+import { resolve } from "node:path";
+/**
+ * Per-(workspace, preparation) cache for compile run records, plus a
+ * runId -> preparation index so `getCompileRun(runId)` can resolve to
+ * the owning preparation without scanning every preparation's runs.
+ */
+export class RunListingCache {
+    /** prepDataDir -> preparation -> records (newest-first sorted). */
+    byWorkspace = new Map();
+    /** prepDataDir -> runId -> preparation. */
+    runIndex = new Map();
+    get(prepDataDir, preparation, fill, runIdOf) {
+        const wsKey = resolve(prepDataDir);
+        let bucket = this.byWorkspace.get(wsKey);
+        if (!bucket) {
+            bucket = new Map();
+            this.byWorkspace.set(wsKey, bucket);
+        }
+        const cached = bucket.get(preparation);
+        if (cached)
+            return cached;
+        const fresh = fill();
+        bucket.set(preparation, fresh);
+        let index = this.runIndex.get(wsKey);
+        if (!index) {
+            index = new Map();
+            this.runIndex.set(wsKey, index);
+        }
+        for (const record of fresh) {
+            index.set(runIdOf(record), preparation);
+        }
+        return fresh;
+    }
+    /** Look up which preparation owns this runId, if known. */
+    preparationFor(prepDataDir, runId) {
+        const wsKey = resolve(prepDataDir);
+        return this.runIndex.get(wsKey)?.get(runId) ?? null;
+    }
+    /** Invalidate a single preparation's cached records and id index. */
+    invalidatePreparation(prepDataDir, preparation) {
+        const wsKey = resolve(prepDataDir);
+        const bucket = this.byWorkspace.get(wsKey);
+        if (bucket) {
+            bucket.delete(preparation);
+            if (bucket.size === 0)
+                this.byWorkspace.delete(wsKey);
+        }
+        const index = this.runIndex.get(wsKey);
+        if (index) {
+            for (const [runId, owner] of index) {
+                if (owner === preparation)
+                    index.delete(runId);
+            }
+            if (index.size === 0)
+                this.runIndex.delete(wsKey);
+        }
+    }
+    /** Drop everything for a workspace (e.g. after a reset). */
+    invalidateWorkspace(prepDataDir) {
+        const wsKey = resolve(prepDataDir);
+        this.byWorkspace.delete(wsKey);
+        this.runIndex.delete(wsKey);
+    }
+}
+/**
+ * Per-(workspace, preparation) readiness cache. Readiness joins compile
+ * runs, test runs, readiness-check runs, and the preparation config; it
+ * is computed on every poll. The cache invalidates when the runtime
+ * writes any of those underlying objects for a given preparation.
+ */
+export class ReadinessCache {
+    byWorkspace = new Map();
+    get(prepDataDir, preparation, compute) {
+        const wsKey = resolve(prepDataDir);
+        let bucket = this.byWorkspace.get(wsKey);
+        if (!bucket) {
+            bucket = new Map();
+            this.byWorkspace.set(wsKey, bucket);
+        }
+        const cached = bucket.get(preparation);
+        if (cached !== undefined)
+            return cached;
+        const fresh = compute();
+        bucket.set(preparation, fresh);
+        return fresh;
+    }
+    invalidatePreparation(prepDataDir, preparation) {
+        const wsKey = resolve(prepDataDir);
+        const bucket = this.byWorkspace.get(wsKey);
+        if (bucket) {
+            bucket.delete(preparation);
+            if (bucket.size === 0)
+                this.byWorkspace.delete(wsKey);
+        }
+    }
+    invalidateWorkspace(prepDataDir) {
+        this.byWorkspace.delete(resolve(prepDataDir));
+    }
+}
+/**
+ * Source-folder listing cache keyed by `(cacheKey, folderRootMtime)`.
+ * `cacheKey` is the slot identifier; `folderPath` is the directory the
+ * cache stats for an mtime probe. UI polling is the hot path; CLI
+ * commands rarely hit the same path twice in <2s, hence the short TTL
+ * fallback.
+ */
+export class MtimeListingCache {
+    static TTL_MS = 2000;
+    cache = new Map();
+    get(cacheKey, folderPath, fill) {
+        const now = Date.now();
+        const stat = safeStat(folderPath);
+        const currentMtime = stat?.mtimeMs ?? 0;
+        const entry = this.cache.get(cacheKey);
+        if (entry
+            && entry.mtimeMs === currentMtime
+            && entry.expiresAt > now) {
+            return entry.value;
+        }
+        const value = fill();
+        this.cache.set(cacheKey, {
+            mtimeMs: currentMtime,
+            expiresAt: now + MtimeListingCache.TTL_MS,
+            value,
+        });
+        return value;
+    }
+    invalidate(cacheKey) {
+        this.cache.delete(cacheKey);
+    }
+    invalidateAll() {
+        this.cache.clear();
+    }
+}
+/**
+ * Method-package listing cache keyed by the joined mtimes of the
+ * builtin / user / workspace method roots. If any of those ticks (a
+ * new local Method, an edit to the user library, etc.) the cache
+ * misses and we re-resolve.
+ */
+export class MethodListingCache {
+    cache = new Map();
+    get(cacheKey, rootPaths, fill) {
+        const fingerprint = rootPaths
+            .map((path) => `${path}:${safeStat(path)?.mtimeMs ?? 0}`)
+            .join("|");
+        const entry = this.cache.get(cacheKey);
+        if (entry && entry.key === fingerprint)
+            return entry.value;
+        const value = fill();
+        this.cache.set(cacheKey, { key: fingerprint, value });
+        return value;
+    }
+    invalidate(cacheKey) {
+        this.cache.delete(cacheKey);
+    }
+    invalidateAll() {
+        this.cache.clear();
+    }
+}
+function safeStat(path) {
+    try {
+        if (!existsSync(path))
+            return null;
+        return statSync(path);
+    }
+    catch {
+        return null;
+    }
+}

package/dist/packages/engine/runtime-event-applier.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Pure event-to-resource transformations for the local service runtime.
+ *
+ * Each apply function takes the current run resource plus one event and
+ * returns the next resource — no side effects, no shared state. This is
+ * what lets the runtime coordinator stay small: every other handler can
+ * compose these without learning the resource shape.
+ */
+import { type CompileRun, type InterfRunEvent } from "./execution/lib/schema.js";
+import { type LocalJobEvent, type LocalJobRunResource } from "./lib/schema.js";
+export declare function applyEventToCompileRun(run: CompileRun, event: InterfRunEvent): CompileRun;
+export declare function applyEventToLocalJob(run: LocalJobRunResource, event: LocalJobEvent): LocalJobRunResource;

package/dist/packages/engine/runtime-event-applier.js

@@ -0,0 +1,177 @@
+import { uniqueArtifacts } from "./run-observability.js";
+export function applyEventToCompileRun(run, event) {
+    const now = event.timestamp;
+    const stageFor = (stageId) => {
+        const existing = run.stages.find((stage) => stage.stage_id === stageId);
+        if (existing)
+            return existing;
+        const created = {
+            run_id: run.run_id,
+            stage_id: stageId,
+            status: "queued",
+            artifacts: [],
+        };
+        run.stages.push(created);
+        return created;
+    };
+    const updateStage = (stageId, patch) => {
+        const current = stageFor(stageId);
+        Object.assign(current, patch);
+    };
+    switch (event.type) {
+        case "run.started":
+            return {
+                ...run,
+                status: "running",
+                started_at: run.started_at ?? now,
+                events: [...run.events, event],
+            };
+        case "stage.started":
+            updateStage(event.stage_id, {
+                status: "running",
+                started_at: now,
+                stage_index: event.stage_index,
+                stage_total: event.stage_total,
+            });
+            break;
+        case "artifact.written": {
+            const stage = stageFor(event.stage_id);
+            updateStage(event.stage_id, {
+                artifacts: uniqueArtifacts([...(stage.artifacts ?? []), event.artifact]),
+            });
+            break;
+        }
+        case "proof.updated":
+            if (event.stage_id) {
+                updateStage(event.stage_id, {
+                    latest_proof: event.proof,
+                });
+            }
+            return {
+                ...run,
+                latest_proof: event.proof,
+                events: [...run.events, event],
+            };
+        case "log.appended":
+            break;
+        case "stage.passed":
+            updateStage(event.stage_id, {
+                status: "succeeded",
+                finished_at: now,
+                summary: event.summary ?? null,
+                failure: null,
+            });
+            break;
+        case "stage.failed":
+            updateStage(event.stage_id, {
+                status: "failed",
+                finished_at: now,
+                summary: event.error,
+                failure: event.error,
+            });
+            break;
+        case "run.completed":
+            return {
+                ...run,
+                // Once cancelled, the cancelled status is sticky; the handler may
+                // still emit a completion event after the cancel signal has landed.
+                status: run.status === "cancelled" ? "cancelled" : "succeeded",
+                finished_at: run.finished_at ?? now,
+                events: [...run.events, event],
+            };
+        case "run.failed":
+            return {
+                ...run,
+                status: run.status === "cancelled" ? "cancelled" : "failed",
+                finished_at: run.finished_at ?? now,
+                events: [...run.events, event],
+            };
+        case "readiness.updated":
+            return {
+                ...run,
+                readiness: event.readiness,
+                events: [...run.events, event],
+            };
+        default:
+            break;
+    }
+    return {
+        ...run,
+        events: [...run.events, event],
+    };
+}
+export function applyEventToLocalJob(run, event) {
+    const stepFor = (stepId) => {
+        const existing = run.steps.find((step) => step.id === stepId);
+        if (existing)
+            return existing;
+        const created = {
+            id: stepId,
+            label: stepId,
+            status: "queued",
+        };
+        run.steps.push(created);
+        return created;
+    };
+    const updateStep = (stepId, patch) => {
+        if (!stepId)
+            return;
+        Object.assign(stepFor(stepId), patch);
+    };
+    switch (event.type) {
+        case "job.started":
+            return {
+                ...run,
+                status: "running",
+                started_at: run.started_at ?? event.timestamp,
+                events: [...run.events, event],
+            };
+        case "step.started":
+            updateStep(event.step_id, {
+                status: "running",
+                started_at: event.timestamp,
+                ...(event.input ? { input: event.input } : {}),
+            });
+            break;
+        case "step.completed":
+            updateStep(event.step_id, {
+                status: "succeeded",
+                finished_at: event.timestamp,
+                summary: event.message ?? null,
+                ...(event.output ? { output: event.output } : {}),
+            });
+            break;
+        case "step.failed":
+            updateStep(event.step_id, {
+                status: "failed",
+                finished_at: event.timestamp,
+                summary: event.message ?? null,
+                ...(event.output ? { output: event.output } : {}),
+            });
+            break;
+        case "job.completed":
+            return {
+                ...run,
+                status: "succeeded",
+                finished_at: run.finished_at ?? event.timestamp,
+                events: [...run.events, event],
+            };
+        case "job.failed":
+            return {
+                ...run,
+                status: "failed",
+                finished_at: run.finished_at ?? event.timestamp,
+                error: event.message ?? "Job failed.",
+                events: [...run.events, event],
+            };
+        case "artifact.written":
+        case "log.appended":
+            break;
+        default:
+            break;
+    }
+    return {
+        ...run,
+        events: [...run.events, event],
+    };
+}

package/dist/packages/engine/runtime-persistence.d.ts

@@ -0,0 +1,47 @@
+import { type CompileRun } from "./execution/lib/schema.js";
+import { type RuntimeRun } from "./compile/lib/schema.js";
+import { type ActionProposalResource, type LocalJobRunResource, type VerifyRunResource } from "./lib/schema.js";
+export declare function compileRunsRoot(compiledPath: string): string;
+export declare function compileRunPath(compiledPath: string, runId: string): string;
+export declare function verifyRunsRoot(compiledPath: string): string;
+export declare function verifyRunPath(compiledPath: string, runId: string): string;
+export declare function localJobsRoot(rootPath: string): string;
+export declare function localJobPath(rootPath: string, runId: string): string;
+export declare function actionProposalsRoot(rootPath: string): string;
+export declare function actionProposalPath(rootPath: string, proposalId: string): string;
+export declare function readJsonFile(filePath: string): unknown | null;
+export declare function writeJsonFile(filePath: string, value: unknown): void;
+export declare function readJsonOrNull<T>(filePath: string, schema: {
+    safeParse(value: unknown): {
+        success: true;
+        data: T;
+    } | {
+        success: false;
+    };
+}): T | null;
+export declare function listJsonFiles(dirPath: string): string[];
+export declare function readCompileRunAt(filePath: string): CompileRun | null;
+export declare function readVerifyRunAt(filePath: string): VerifyRunResource | null;
+export declare function readLocalJobRunAt(filePath: string): LocalJobRunResource | null;
+export declare function readActionProposalAt(filePath: string): ActionProposalResource | null;
+/**
+ * Read the per-stage runtime-run history NDJSON. Each line is a `RuntimeRun`
+ * record; lines that fail to parse are silently skipped so the runtime can
+ * tolerate a partially-written tail without crashing.
+ */
+export declare function readRuntimeRunHistory(compiledPath: string): RuntimeRun[];
+/**
+ * Sort items newest-first using `started_at` (with a `finished_at` fallback).
+ * Used for compile/test run lists where the canonical order is by activity
+ * window, not by record-creation time.
+ */
+export declare function newestFirst<T extends {
+    started_at?: string | null;
+    finished_at?: string | null;
+}>(items: T[]): T[];
+/** Sort items newest-first using their `created_at` timestamp. */
+export declare function byCreatedAtDesc<T extends {
+    created_at: string;
+}>(items: T[]): T[];
+/** Parse an ISO timestamp into milliseconds; returns 0 for invalid input. */
+export declare function timestampKey(value?: string | null): number;

package/dist/packages/engine/runtime-persistence.js

@@ -0,0 +1,137 @@
+/**
+ * Filesystem and JSON persistence helpers for the local service runtime.
+ *
+ * These functions are pure: they take absolute paths and return values, with
+ * no shared state. Every other runtime module composes on top of this layer
+ * so the runtime coordinator stays small.
+ */
+import { existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync, } from "node:fs";
+import { dirname, join } from "node:path";
+import { CompileRunSchema, } from "./execution/lib/schema.js";
+import { compiledRuntimeRunHistoryPath, compiledRuntimeRoot, testRootForCompiled, } from "./compile/compiled-paths.js";
+import { RuntimeRunSchema, } from "./compile/lib/schema.js";
+import { asPreparationDataDir, preparationServiceActionProposalsRoot, preparationServiceJobsRoot, } from "../contracts/lib/preparation-paths.js";
+import { ActionProposalResourceSchema, LocalJobRunResourceSchema, VerifyRunResourceSchema, } from "./lib/schema.js";
+// ---- Path helpers --------------------------------------------------------
+export function compileRunsRoot(compiledPath) {
+    return join(compiledRuntimeRoot(compiledPath), "compile-runs");
+}
+export function compileRunPath(compiledPath, runId) {
+    return join(compileRunsRoot(compiledPath), `${runId}.json`);
+}
+export function verifyRunsRoot(compiledPath) {
+    return join(testRootForCompiled(compiledPath), "service-runs");
+}
+export function verifyRunPath(compiledPath, runId) {
+    return join(verifyRunsRoot(compiledPath), `${runId}.json`);
+}
+export function localJobsRoot(rootPath) {
+    return preparationServiceJobsRoot(asPreparationDataDir(rootPath));
+}
+export function localJobPath(rootPath, runId) {
+    return join(localJobsRoot(rootPath), `${runId}.json`);
+}
+export function actionProposalsRoot(rootPath) {
+    return preparationServiceActionProposalsRoot(asPreparationDataDir(rootPath));
+}
+export function actionProposalPath(rootPath, proposalId) {
+    return join(actionProposalsRoot(rootPath), `${proposalId}.json`);
+}
+// ---- JSON IO -------------------------------------------------------------
+export function readJsonFile(filePath) {
+    try {
+        return JSON.parse(readFileSync(filePath, "utf8"));
+    }
+    catch {
+        return null;
+    }
+}
+export function writeJsonFile(filePath, value) {
+    mkdirSync(dirname(filePath), { recursive: true });
+    writeFileSync(filePath, `${JSON.stringify(value, null, 2)}\n`);
+}
+export function readJsonOrNull(filePath, schema) {
+    const raw = readJsonFile(filePath);
+    if (raw === null)
+        return null;
+    const parsed = schema.safeParse(raw);
+    return parsed.success ? parsed.data : null;
+}
+export function listJsonFiles(dirPath) {
+    if (!existsSync(dirPath))
+        return [];
+    try {
+        if (!statSync(dirPath).isDirectory())
+            return [];
+    }
+    catch {
+        return [];
+    }
+    return readdirSync(dirPath)
+        .filter((entry) => entry.endsWith(".json"))
+        .map((entry) => join(dirPath, entry));
+}
+// ---- Typed readers -------------------------------------------------------
+export function readCompileRunAt(filePath) {
+    return readJsonOrNull(filePath, CompileRunSchema);
+}
+export function readVerifyRunAt(filePath) {
+    return readJsonOrNull(filePath, VerifyRunResourceSchema);
+}
+export function readLocalJobRunAt(filePath) {
+    return readJsonOrNull(filePath, LocalJobRunResourceSchema);
+}
+export function readActionProposalAt(filePath) {
+    return readJsonOrNull(filePath, ActionProposalResourceSchema);
+}
+/**
+ * Read the per-stage runtime-run history NDJSON. Each line is a `RuntimeRun`
+ * record; lines that fail to parse are silently skipped so the runtime can
+ * tolerate a partially-written tail without crashing.
+ */
+export function readRuntimeRunHistory(compiledPath) {
+    const historyPath = compiledRuntimeRunHistoryPath(compiledPath);
+    if (!existsSync(historyPath))
+        return [];
+    try {
+        return readFileSync(historyPath, "utf8")
+            .split(/\r?\n/)
+            .map((line) => line.trim())
+            .filter((line) => line.length > 0)
+            .map((line) => {
+            try {
+                return RuntimeRunSchema.safeParse(JSON.parse(line));
+            }
+            catch {
+                return { success: false };
+            }
+        })
+            .filter((parsed) => parsed.success)
+            .map((parsed) => parsed.data);
+    }
+    catch {
+        return [];
+    }
+}
+// ---- Sort helpers --------------------------------------------------------
+/**
+ * Sort items newest-first using `started_at` (with a `finished_at` fallback).
+ * Used for compile/test run lists where the canonical order is by activity
+ * window, not by record-creation time.
+ */
+export function newestFirst(items) {
+    return [...items].sort((left, right) => {
+        const leftTime = Date.parse(left.started_at ?? left.finished_at ?? "");
+        const rightTime = Date.parse(right.started_at ?? right.finished_at ?? "");
+        return (Number.isFinite(rightTime) ? rightTime : 0) - (Number.isFinite(leftTime) ? leftTime : 0);
+    });
+}
+/** Sort items newest-first using their `created_at` timestamp. */
+export function byCreatedAtDesc(items) {
+    return [...items].sort((left, right) => Date.parse(right.created_at) - Date.parse(left.created_at));
+}
+/** Parse an ISO timestamp into milliseconds; returns 0 for invalid input. */
+export function timestampKey(value) {
+    const parsed = Date.parse(value ?? "");
+    return Number.isFinite(parsed) ? parsed : 0;
+}

package/dist/packages/engine/runtime-proposal-helpers.d.ts

@@ -0,0 +1,35 @@
+import { type SourcePreparationConfig } from "../project/lib/schema.js";
+import { type ActionProposalPlanActionType, type ActionProposalResource } from "./lib/schema.js";
+export declare const ACTION_PLANNER_CLARIFICATION_MESSAGE = "I can help with this Interf Workspace. Ask a question about Interf, or ask me to create a Preparation, prepare, check readiness, improve, or draft a Method and I will prepare an approval proposal.";
+export type LocalTestMode = "source-files" | "compiled" | "both";
+export declare function createActionProposalId(): string;
+export declare function sanitizeActionProposalPlan(value: unknown): unknown;
+export declare function configuredAgentName(): string | null;
+export declare function detectedExecutorOptions(currentAgentName: string | null): {
+    name: string;
+    display_name: string;
+    command: string;
+    current: boolean;
+}[];
+export declare function slugFromText(value: string): string;
+export declare function escapeRegExp(value: string): string;
+export declare function stringValue(values: Record<string, unknown> | undefined, key: string): string | null;
+export declare function actionTypeFromValues(values: Record<string, unknown> | undefined): ActionProposalPlanActionType | null;
+export declare function directServiceEndpointForAction(actionType: ActionProposalPlanActionType): string | null;
+export declare function numberValue(values: Record<string, unknown> | undefined, key: string): number | null;
+export declare function testModeFromValues(values: Record<string, unknown> | undefined): LocalTestMode | null;
+export declare function testModeValue(values: Record<string, unknown> | undefined, defaultMode?: LocalTestMode): LocalTestMode;
+export declare function testModeCliTarget(mode: LocalTestMode): "source-files" | "portable-context" | "both";
+export declare function methodIdForProposal(message: string, values: Record<string, unknown> | undefined): string;
+export declare function actionValueMethodTaskPrompt(values: Record<string, unknown> | undefined): string | null;
+export declare function normalizeMethodAuthoringText(value: string): string;
+export declare function extractMethodAuthoringSection(value: string, label: string): string | null;
+export declare function stripMethodCommandPrefix(value: string, methodId: string): string;
+export declare function methodAuthoringPromptFallback(message: string, methodId: string): string;
+export declare function methodAuthoringHintFromPrompt(prompt: string): string;
+export declare function methodLabelFromId(methodId: string): string;
+export declare function detachMethodFromPreparation(preparation: SourcePreparationConfig, methodId: string): SourcePreparationConfig;
+export declare function requireSelectedMethod(preparation: SourcePreparationConfig): string;
+export declare function actionCommandPreview(actionType: ActionProposalResource["action_type"], preparationName: string | null, methodId: string | null, values: Record<string, unknown> | undefined): string;
+export declare function hasCompiledTestTarget(sourcePath: string, preparationConfig: SourcePreparationConfig): boolean;
+export declare function actionAssistantMessage(actionType: ActionProposalResource["action_type"], preparationName: string | null, commandPreview: string): string;