@interf/compiler 0.22.2 → 0.50.0

package/dist/packages/runtime/build/inspect-map.js

@@ -0,0 +1,270 @@
+/**
+ * INSPECT.md — the DEVELOPER/agent map of a built project folder.
+ *
+ * `home.md` is the entrypoint for an agent doing the PROJECT TASK (read the
+ * prepared context). INSPECT.md is the entrypoint for a developer or coding
+ * agent doing DEVELOPMENT on the build itself: it points at how every agent job
+ * ran so a bad stage SKILL can be debugged and self-improved. This is engine
+ * policy rule 6 ("THE FOLDER IS LEGIBLE") made concrete: open the folder cold,
+ * read one file, and reach every job's prompt / reasoning / output / verdict.
+ *
+ * It is a POINTER MAP, not a new data model. It RECOMPUTES NOTHING and persists
+ * no new state: it reads what the build already recorded —
+ *   - the GraphManifest (intent, Build Plan, readiness, primary metrics)
+ *       via `loadGraphManifest`,
+ *   - the per-attempt stage execution sessions (the graph-scoped record model)
+ *       via `listStageExecutionSessions`, grouped by `build_run_id`,
+ *   - the graph-less plan-draft / plan-improve job runs (the LocalJobRun record
+ *       model) read through their owning Zod schema from the Project job store —
+ * and renders their already-recorded paths. Every record it reads is parsed by
+ * its owner; this module adds no schema. Pointers stay relative to the graph
+ * root (so the map travels with the folder); the plan-job shells live under the
+ * Project, so those pointers are rendered relative to the Project data dir.
+ *
+ * Written best-effort at the end of a successful build (beside the GraphManifest
+ * write). A failure to render the map must never fail a build.
+ */
+import { existsSync, readFileSync, readdirSync, } from "node:fs";
+import { join, relative } from "node:path";
+import { writeFileAtomic } from "./atomic-fs.js";
+import { contextGraphInterfRoot, resolveSourceControlPathForContextGraph, } from "./context-graph-paths.js";
+import { loadGraphManifest, } from "./stage-manifest.js";
+import { listStageExecutionSessions, } from "./stage-session.js";
+import { LocalJobRunResourceSchema, } from "../schemas/jobs.js";
+import { projectServiceJobsRoot, asProjectDataDir, } from "../../contracts/lib/project-paths.js";
+export const CONTEXT_GRAPH_INSPECT_MAP_FILE = "INSPECT.md";
+/**
+ * The graph-less LocalJobRun types whose preserved shells this map points at:
+ * plan-authoring (draft/improve) and benchmark-question drafting. Each freezes a
+ * preserved shell (prompt / reasoning / verdict) and records a `shell_path` in
+ * its result, so the map can point a developer at how that job ran.
+ */
+const PLAN_JOB_TYPES = new Set([
+    "build-plan-draft",
+    "build-plan-improvement",
+    "benchmark-question-draft",
+]);
+function inspectMapPath(contextGraphPath) {
+    return join(contextGraphInterfRoot(contextGraphPath), CONTEXT_GRAPH_INSPECT_MAP_FILE);
+}
+/** Context-relative, forward-slashed pointer for a path under the graph root. */
+function graphRel(contextGraphPath, target) {
+    if (!target)
+        return null;
+    const rel = relative(contextGraphPath, target);
+    return rel ? rel.replaceAll("\\", "/") : ".";
+}
+/** A session pointer is already stored context-relative; just normalize null. */
+function sessionPointer(value) {
+    return value && value.length > 0 ? value : null;
+}
+/**
+ * The output location an attempt wrote. A stage session records its write mounts
+ * (artifact id -> path under the graph); we point at those so a reviewer lands on
+ * what the attempt produced. Falls back to the shell root when no write mount was
+ * recorded (e.g. the native entrypoint). Never recomputed — read from the record.
+ */
+function sessionOutputPointer(session) {
+    const firstWrite = session.artifacts.writes[0];
+    if (firstWrite?.artifact_path)
+        return firstWrite.artifact_path;
+    return sessionPointer(session.shell.root_path);
+}
+function metricLine(metric) {
+    const total = typeof metric.total === "number" ? `/${metric.total}` : "";
+    const unit = metric.unit ? ` ${metric.unit}` : "";
+    return `${metric.label}: ${metric.value}${total}${unit}`;
+}
+/** Read the graph-less plan-draft / plan-improve job runs for this graph's Project. */
+function readPlanJobRuns(contextGraphPath) {
+    let projectDataDir;
+    try {
+        projectDataDir = resolveSourceControlPathForContextGraph(contextGraphPath);
+    }
+    catch {
+        return { projectDataDir: contextGraphPath, runs: [] };
+    }
+    const jobsRoot = projectServiceJobsRoot(asProjectDataDir(projectDataDir));
+    if (!existsSync(jobsRoot))
+        return { projectDataDir, runs: [] };
+    const runs = [];
+    for (const entry of readdirSync(jobsRoot)) {
+        if (!entry.endsWith(".json"))
+            continue;
+        try {
+            const parsed = LocalJobRunResourceSchema.safeParse(JSON.parse(readFileSync(join(jobsRoot, entry), "utf8")));
+            if (parsed.success && PLAN_JOB_TYPES.has(parsed.data.job_type))
+                runs.push(parsed.data);
+        }
+        catch {
+            // A malformed job record is skipped, not fatal — the map is best-effort.
+        }
+    }
+    runs.sort((left, right) => Date.parse(left.created_at) - Date.parse(right.created_at));
+    return { projectDataDir, runs };
+}
+/** One bullet pointing at a plan-authoring job's preserved shell + verdict. */
+function renderPlanJobLines(projectDataDir, run) {
+    const result = (run.result ?? {});
+    const shellPath = typeof result.shell_path === "string" ? result.shell_path : null;
+    const shellRel = shellPath ? graphRel(projectDataDir, shellPath) : null;
+    const lines = [
+        `- ${run.job_type} \`${run.run_id}\` — ${run.status}: ${run.title}`,
+    ];
+    if (shellRel) {
+        lines.push(`  - preserved shell (prompt / reasoning / output / verdict): \`${shellRel}\``);
+    }
+    else {
+        lines.push("  - preserved shell: not recorded for this job");
+    }
+    return lines;
+}
+/** Per-stage attempt pointer block under a Build run heading. */
+function renderStageSessionLines(session) {
+    const stage = session.stage_label ?? session.stage_id ?? session.job_type;
+    const model = session.executor.model ? ` · model ${session.executor.model}` : "";
+    const verdict = session.summary ?? session.error ?? "(no summary recorded)";
+    const lines = [
+        `- ${stage} \`${session.stage_run_id}\` — ${session.status} (attempt ${session.attempt})${model}`,
+        `  - verdict: ${verdict}`,
+    ];
+    // The shell and every pointer rooted under it (prompt / reasoning / status log,
+    // and the output fallback to the shell root) only resolve while the shell is on
+    // disk. `replay_ready` IS that fact: true when the preserved shell exists,
+    // flipped false by reconcilePrunedStageExecutionSessions once retention pruned
+    // it. So a non-replay-ready session must print NO shell-rooted path (it would
+    // dangle); it prints the recorded retention reason instead. The map stays a
+    // pointer map whose pointers resolve (policy rule 6).
+    const shellRoot = sessionPointer(session.shell.root_path);
+    if (session.shell.replay_ready && shellRoot && shellRoot !== ".") {
+        lines.push(`  - preserved shell (replay-ready): \`${shellRoot}\``);
+        const prompt = sessionPointer(session.logs.prompt_path);
+        if (prompt)
+            lines.push(`  - prompt: \`${prompt}\``);
+        const reasoning = sessionPointer(session.runtime_files.reasoning_path);
+        if (reasoning)
+            lines.push(`  - reasoning: \`${reasoning}\``);
+        const status = sessionPointer(session.logs.status_path);
+        if (status)
+            lines.push(`  - status log: \`${status}\``);
+    }
+    else if (session.shell.retention_reason) {
+        lines.push(`  - preserved shell: not retained — ${session.shell.retention_reason}`);
+    }
+    // The output is the build artifact the attempt wrote (under the graph, not the
+    // shell), so it survives a shell prune and is rendered regardless. It only
+    // falls back to the shell root when no artifact write was recorded; suppress
+    // that fallback when the shell is gone so it never dangles.
+    const output = sessionOutputPointer(session);
+    const outputIsShellFallback = output !== null && output === shellRoot;
+    if (output && !(outputIsShellFallback && !session.shell.replay_ready)) {
+        lines.push(`  - output: \`${output}\``);
+    }
+    return lines;
+}
+/** Group stage sessions by their Build run id, preserving first-seen order. */
+function groupSessionsByRun(sessions) {
+    const byRun = new Map();
+    for (const session of sessions) {
+        const key = session.build_run_id ?? "(no build run id)";
+        const bucket = byRun.get(key);
+        if (bucket)
+            bucket.push(session);
+        else
+            byRun.set(key, [session]);
+    }
+    return byRun;
+}
+function renderInspectMap(options) {
+    const { contextGraphPath, manifest, sessions, projectDataDir, planRuns } = options;
+    const intent = manifest?.intent ?? "(no Project intent recorded)";
+    const buildPlan = manifest?.build_plan ?? "(unknown Build Plan)";
+    const projectId = manifest?.project ?? "(unknown Project)";
+    const readiness = manifest?.readiness;
+    const lines = [
+        "# INSPECT — how this project folder was built",
+        "",
+        "Developer/agent map of this built project. `home.md` is the entrypoint for",
+        "doing the project TASK (the prepared context). This file is the entrypoint",
+        "for DEVELOPMENT: every agent job's preserved shell — prompt, reasoning,",
+        "output, verdict — so a coding agent can debug a bad stage SKILL and",
+        "self-improve. All paths are relative to this Context Graph folder unless",
+        "noted. Nothing here is recomputed; it points at what the build recorded.",
+        "",
+        "## Project",
+        "",
+        `- Project: \`${projectId}\``,
+        `- Intent: ${intent}`,
+        `- Build Plan: \`${buildPlan}\``,
+    ];
+    if (readiness) {
+        lines.push(`- Readiness: ${readiness.status} — ${readiness.summary}`);
+    }
+    const primaryMetrics = (manifest?.primary_metrics ?? []).filter((metric) => metric.primary);
+    const metricsToShow = primaryMetrics.length > 0 ? primaryMetrics : (manifest?.primary_metrics ?? []);
+    if (metricsToShow.length > 0) {
+        lines.push("- Primary metrics:");
+        for (const metric of metricsToShow)
+            lines.push(`  - ${metricLine(metric)}`);
+    }
+    lines.push("", "## How the Build Plan was built", "");
+    if (planRuns.length > 0) {
+        lines.push("Plan-authoring jobs for this Project (paths relative to the Project data dir):", "");
+        for (const run of planRuns) {
+            for (const line of renderPlanJobLines(projectDataDir, run))
+                lines.push(line);
+        }
+    }
+    else {
+        lines.push("- No plan-draft or plan-improve job was recorded for this Project (e.g. a built-in Build Plan was selected directly).");
+    }
+    lines.push("", "## Build runs", "");
+    if (sessions.length === 0) {
+        lines.push("- No stage execution sessions were recorded for this Context Graph.");
+    }
+    else {
+        const byRun = groupSessionsByRun(sessions);
+        for (const [runId, runSessions] of byRun) {
+            lines.push(`### Build run \`${runId}\``, "");
+            for (const session of runSessions) {
+                for (const line of renderStageSessionLines(session))
+                    lines.push(line);
+            }
+            lines.push("");
+        }
+    }
+    // One trailing pointer back to the agent-task entrypoint so a reader who opened
+    // INSPECT.md first still finds home.md.
+    if (existsSync(join(contextGraphPath, "home.md"))) {
+        lines.push("---", "", "Agent task entrypoint: `home.md`.", "");
+    }
+    return `${lines.join("\n").replace(/\n{3,}$/, "\n")}\n`;
+}
+/**
+ * Render `<graph>/.interf/INSPECT.md` from already-recorded build state.
+ *
+ * Reads the GraphManifest, the stage execution sessions, and the Project's
+ * plan-draft/improve job runs; writes a pointer map. Returns the absolute path
+ * written, or null when there is nothing to map / a read failed. Best-effort:
+ * callers in the build success path must not let a failure here fail the build.
+ */
+export function writeContextGraphInspectMap(contextGraphPath) {
+    try {
+        const manifest = loadGraphManifest(contextGraphPath);
+        const sessions = listStageExecutionSessions(contextGraphPath);
+        const { projectDataDir, runs: planRuns } = readPlanJobRuns(contextGraphPath);
+        const content = renderInspectMap({
+            contextGraphPath,
+            manifest,
+            sessions,
+            projectDataDir,
+            planRuns,
+        });
+        const path = inspectMapPath(contextGraphPath);
+        writeFileAtomic(path, content);
+        return path;
+    }
+    catch {
+        return null;
+    }
+}