@interf/compiler 0.9.5 → 0.13.0

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

@@ -1,37 +1,61 @@
 export const LOCAL_SERVICE_DEFAULT_HOST = "127.0.0.1";
 export const LOCAL_SERVICE_DEFAULT_PORT = 4873;
-export const LOCAL_SERVICE_POINTER_PATH = [
-    "interf",
-    ".service",
-    "local-service.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",
-    preparationSetups: "/v1/preparation-setups",
-    preparationChanges: "/v1/preparation-changes",
-    methodChanges: "/v1/method-changes",
-    jobs: "/v1/jobs",
-    readinessCheckDrafts: "/v1/readiness-check-drafts",
-    methodAuthoringRuns: "/v1/method-authoring-runs",
-    methodImprovementRuns: "/v1/method-improvement-runs",
     runs: "/v1/runs",
-    reset: "/v1/reset",
-    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

@@ -276,15 +276,15 @@ export function testRunToObservability(run) {
         ? run.started_at ?? new Date().toISOString()
         : undefined);
     const readinessRun = run.readiness_run;
-    const raw = readinessRun?.raw ?? null;
+    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
@@ -298,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;
@@ -323,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
@@ -402,8 +402,8 @@ export function testRunToObservability(run) {
         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,

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;

package/dist/packages/local-service/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/local-service/runtime-persistence.d.ts

@@ -0,0 +1,47 @@
+import { type CompileRun } from "../execution/lib/schema.js";
+import { type RuntimeRun } from "../compiler/lib/schema.js";
+import { type ActionProposalResource, type LocalJobRunResource, type TestRunResource } from "./lib/schema.js";
+export declare function compileRunsRoot(compiledPath: string): string;
+export declare function compileRunPath(compiledPath: string, runId: string): string;
+export declare function testRunsRoot(compiledPath: string): string;
+export declare function testRunPath(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 readTestRunAt(filePath: string): TestRunResource | 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;