@interf/compiler 0.9.4 → 0.13.0

package/dist/packages/local-service/routes.js

@@ -1,32 +1,61 @@
 export const LOCAL_SERVICE_DEFAULT_HOST = "127.0.0.1";
 export const LOCAL_SERVICE_DEFAULT_PORT = 4873;
-export const LOCAL_SERVICE_INSTANCE_POINTER_PATH = [
-    "interf",
-    ".service",
-    "local-instance.json",
-];
 export const LOCAL_SERVICE_ROUTES = {
     root: "/",
     api: "/v1",
     health: "/health",
+    // 0.13 surface — preparation-keyed.
+    instance: "/v1/instance",
     preparations: "/v1/preparations",
-    workspaceFiles: "/v1/workspace-files",
-    sourceFiles: "/v1/source-files",
     methods: "/v1/methods",
-    jobs: "/v1/jobs",
-    readinessCheckDrafts: "/v1/readiness-check-drafts",
-    methodAuthoringRuns: "/v1/method-authoring-runs",
     runs: "/v1/runs",
-    executor: "/v1/executor",
     actionProposals: "/v1/action-proposals",
-    compileRuns: "/v1/compile-runs",
-    testRuns: "/v1/test-runs",
-    portableContexts: "/v1/portable-contexts",
-    readiness: "/v1/readiness",
+    executor: "/v1/executor",
     openPath: "/v1/open-path",
 };
+/** Preparation-scoped sub-resources (relative to /v1/preparations/<id>/). */
+export const PREPARATION_SUBRESOURCES = {
+    compileRuns: "compile-runs",
+    testRuns: "test-runs",
+    methodAuthoringRuns: "method-authoring-runs",
+    methodImprovementRuns: "method-improvement-runs",
+    readinessCheckDrafts: "readiness-check-drafts",
+    changes: "changes",
+    reset: "reset",
+    runs: "runs",
+    readiness: "readiness",
+    sourceFiles: "source-files",
+    portableContext: "portable-context",
+};
+/** Run-scoped sub-resources (relative to /v1/runs/<run-id>/). */
+export const RUN_SUBRESOURCES = {
+    events: "events",
+    cancel: "cancel",
+    proof: "proof",
+    artifacts: "artifacts",
+};
 export function buildLocalServiceUrl(options = {}) {
     const host = options.host ?? LOCAL_SERVICE_DEFAULT_HOST;
     const port = options.port ?? LOCAL_SERVICE_DEFAULT_PORT;
     return `http://${host}:${port}`;
 }
+/** Path builder: /v1/preparations/<id>. */
+export function preparationResourcePath(prepId) {
+    return `${LOCAL_SERVICE_ROUTES.preparations}/${encodeURIComponent(prepId)}`;
+}
+/** Path builder: /v1/preparations/<id>/<subresource>. */
+export function preparationSubresourcePath(prepId, sub) {
+    return `${preparationResourcePath(prepId)}/${PREPARATION_SUBRESOURCES[sub]}`;
+}
+/** Path builder: /v1/runs/<run-id>. */
+export function runResourcePath(runId) {
+    return `${LOCAL_SERVICE_ROUTES.runs}/${encodeURIComponent(runId)}`;
+}
+/** Path builder: /v1/runs/<run-id>/<subresource>. */
+export function runSubresourcePath(runId, sub) {
+    return `${runResourcePath(runId)}/${RUN_SUBRESOURCES[sub]}`;
+}
+/** Path builder: /v1/methods/<id>. */
+export function methodResourcePath(methodId) {
+    return `${LOCAL_SERVICE_ROUTES.methods}/${encodeURIComponent(methodId)}`;
+}

package/dist/packages/local-service/run-observability.js

@@ -41,8 +41,8 @@ function safeMethodNamePart(value) {
         .replace(/^-+|-+$/g, "")
         || "run";
 }
-function methodTraceName(runType, name) {
-    return `workflow//./interf/${runType}//${safeMethodNamePart(name)}`;
+function interfTraceName(runType, name) {
+    return `interf//./runs/${runType}//${safeMethodNamePart(name)}`;
 }
 function methodStepName(runType, label) {
     return `step//./interf/${runType}//${safeMethodNamePart(label)}`;
@@ -93,15 +93,11 @@ function agentLabelForJob(job) {
 }
 function jobTypeLabelForMetric(type) {
     if (type === "readiness-check-draft")
-        return "Readiness-check draft";
+        return "Draft readiness checks";
     if (type === "method-authoring")
         return "Method draft";
     if (type === "method-improvement")
         return "Method improvement";
-    if (type === "compile")
-        return "Compile";
-    if (type === "test")
-        return "Readiness check";
     return "Local job";
 }
 function stageTracePayload(stage) {
@@ -118,7 +114,7 @@ export function compileRunToObservability(run) {
     const proof = proofChecksForCompileRun(run);
     const executor = run.stages.find((stage) => stage.executor)?.executor ?? null;
     const traceStatus = methodTraceRunStatus(run.status);
-    const methodName = methodTraceName("compile", `Prepare ${run.preparation}`);
+    const methodName = interfTraceName("compile", `Prepare ${run.preparation}`);
     const completedAt = run.finished_at ?? (traceStatus === "completed" || traceStatus === "failed" || traceStatus === "cancelled"
         ? run.started_at ?? run.created_at
         : undefined);
@@ -221,6 +217,7 @@ export function compileRunToObservability(run) {
         created_at: run.created_at,
         started_at: run.started_at ?? null,
         finished_at: run.finished_at ?? null,
+        readiness: run.readiness ?? null,
         metrics: [
             { label: "Preparation", value: run.preparation },
             { label: "Method", value: run.method },
@@ -274,19 +271,20 @@ export function compileRunToObservability(run) {
 export function testRunToObservability(run) {
     const traceStatus = methodTraceRunStatus(run.status);
     const title = `Check readiness ${run.preparation}`;
-    const methodName = methodTraceName("test", title);
+    const methodName = interfTraceName("test", title);
     const completedAt = run.finished_at ?? (traceStatus === "completed" || traceStatus === "failed" || traceStatus === "cancelled"
         ? run.started_at ?? new Date().toISOString()
         : undefined);
-    const raw = run.comparison?.raw ?? null;
-    const compiled = run.comparison?.compiled ?? null;
+    const readinessRun = run.readiness_run;
+    const sourceFiles = readinessRun?.source_files ?? null;
+    const compiled = readinessRun?.compiled ?? null;
     const proofCandidates = [
-        raw
+        sourceFiles
             ? {
                 id: `${run.run_id}-source-files`,
                 label: "source files baseline",
-                ok: raw.ok ?? raw.passed_cases === raw.total_cases,
-                detail: `${raw.passed_cases}/${raw.total_cases} checks`,
+                ok: sourceFiles.ok ?? sourceFiles.passed_cases === sourceFiles.total_cases,
+                detail: `${sourceFiles.passed_cases}/${sourceFiles.total_cases} checks`,
             }
             : null,
         compiled
@@ -300,7 +298,7 @@ export function testRunToObservability(run) {
     ];
     const proof = proofCandidates.filter((value) => value !== null);
     const artifacts = uniqueArtifacts([
-        ...(raw?.run_path ? [{ path: raw.run_path, role: "test", label: "source files readiness run" }] : []),
+        ...(sourceFiles?.run_path ? [{ path: sourceFiles.run_path, role: "test", label: "source files readiness run" }] : []),
         ...(compiled?.run_path ? [{ path: compiled.run_path, role: "test", label: "portable context readiness run" }] : []),
     ]);
     let eventIndex = 0;
@@ -325,13 +323,13 @@ export function testRunToObservability(run) {
         }));
     }
     const targetStepCandidates = [
-        raw
+        sourceFiles
             ? {
                 id: "source-files-baseline",
                 label: "Source files baseline",
-                status: raw.ok ?? raw.passed_cases === raw.total_cases ? "succeeded" : "failed",
-                input: raw.target ?? { type: "source-files", path: run.source_path ?? null },
-                output: raw,
+                status: sourceFiles.ok ?? sourceFiles.passed_cases === sourceFiles.total_cases ? "succeeded" : "failed",
+                input: sourceFiles.target ?? { type: "source-files", path: run.source_path ?? null },
+                output: sourceFiles,
             }
             : null,
         compiled
@@ -354,7 +352,7 @@ export function testRunToObservability(run) {
                 preparation: run.preparation,
                 mode: run.mode,
             },
-            output: run.comparison ?? null,
+            output: readinessRun ?? null,
         });
     }
     for (const step of targetSteps) {
@@ -373,7 +371,7 @@ export function testRunToObservability(run) {
     if (traceStatus === "completed") {
         events.push(traceEvent(run.run_id, "run_completed", completedAt, eventIndex++, {
             output: {
-                comparison: run.comparison,
+                readiness_run: readinessRun,
                 proof,
             },
         }));
@@ -400,11 +398,12 @@ export function testRunToObservability(run) {
         created_at: run.started_at ?? completedAt ?? new Date().toISOString(),
         started_at: run.started_at ?? null,
         finished_at: run.finished_at ?? null,
+        readiness: run.readiness ?? null,
         metrics: [
             { label: "Preparation", value: run.preparation },
             { label: "Mode", value: run.mode },
-            { label: "Readiness checks", value: compiled ? `${compiled.passed_cases}/${compiled.total_cases}` : raw ? `${raw.passed_cases}/${raw.total_cases}` : "0/0" },
-            { label: "Source files", value: raw ? `${raw.passed_cases}/${raw.total_cases}` : "-" },
+            { label: "Readiness checks", value: compiled ? `${compiled.passed_cases}/${compiled.total_cases}` : sourceFiles ? `${sourceFiles.passed_cases}/${sourceFiles.total_cases}` : "0/0" },
+            { label: "Source files", value: sourceFiles ? `${sourceFiles.passed_cases}/${sourceFiles.total_cases}` : "-" },
             { label: "Portable context", value: compiled ? `${compiled.passed_cases}/${compiled.total_cases}` : "-" },
         ],
         artifacts,
@@ -428,7 +427,7 @@ export function testRunToObservability(run) {
                     source_path: run.source_path ?? null,
                     portable_context_path: run.portable_context_path ?? null,
                 },
-                ...(traceStatus === "completed" ? { output: { comparison: run.comparison, proof } } : {}),
+                ...(traceStatus === "completed" ? { output: { readiness_run: readinessRun, proof } } : {}),
                 ...(traceStatus === "failed" ? { error: structuredMethodError(run.error) } : {}),
                 ...(run.started_at ? { startedAt: run.started_at } : {}),
                 ...(completedAt ? { completedAt } : {}),
@@ -441,8 +440,7 @@ export function testRunToObservability(run) {
     });
 }
 export function jobRunToObservability(job) {
-    const runType = (job.job_type === "preparation-setup" ||
-        job.job_type === "readiness-check-draft" ||
+    const runType = (job.job_type === "readiness-check-draft" ||
         job.job_type === "method-authoring" ||
         job.job_type === "method-improvement"
         ? job.job_type
@@ -456,7 +454,7 @@ export function jobRunToObservability(job) {
         }
         : null;
     const traceStatus = methodTraceRunStatus(job.status);
-    const methodName = methodTraceName(runType, job.title);
+    const methodName = interfTraceName(runType, job.title);
     const completedAt = job.finished_at ?? (traceStatus === "completed" || traceStatus === "failed" || traceStatus === "cancelled"
         ? job.started_at ?? job.created_at
         : undefined);

package/dist/packages/local-service/runtime-caches.d.ts

@@ -0,0 +1,76 @@
+/**
+ * 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.
+ */
+/**
+ * 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 declare class RunListingCache<TRecord> {
+    /** prepDataDir -> preparation -> records (newest-first sorted). */
+    private byWorkspace;
+    /** prepDataDir -> runId -> preparation. */
+    private runIndex;
+    get(prepDataDir: string, preparation: string, fill: () => TRecord[], runIdOf: (record: TRecord) => string): TRecord[];
+    /** Look up which preparation owns this runId, if known. */
+    preparationFor(prepDataDir: string, runId: string): string | null;
+    /** Invalidate a single preparation's cached records and id index. */
+    invalidatePreparation(prepDataDir: string, preparation: string): void;
+    /** Drop everything for a workspace (e.g. after a reset). */
+    invalidateWorkspace(prepDataDir: string): void;
+}
+/**
+ * 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 declare class ReadinessCache<TReadiness> {
+    private byWorkspace;
+    get(prepDataDir: string, preparation: string, compute: () => TReadiness): TReadiness;
+    invalidatePreparation(prepDataDir: string, preparation: string): void;
+    invalidateWorkspace(prepDataDir: string): void;
+}
+/**
+ * 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 declare class MtimeListingCache<TList> {
+    private static readonly TTL_MS;
+    private cache;
+    get(cacheKey: string, folderPath: string, fill: () => TList): TList;
+    invalidate(cacheKey: string): void;
+    invalidateAll(): void;
+}
+/**
+ * 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 declare class MethodListingCache<TList> {
+    private cache;
+    get(cacheKey: string, rootPaths: string[], fill: () => TList): TList;
+    invalidate(cacheKey: string): void;
+    invalidateAll(): void;
+}

package/dist/packages/local-service/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/local-service/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;