@deksden-com/dd-flow-cli 0.4.0 → 0.4.1

package/dist/services/runs.js

@@ -1,14 +1,21 @@
+import crypto from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
+import { spawnSync } from "node:child_process";
 import { formatFullId, isFullEntityId, isShortEntityId, parseFullEntityId } from "../domain/entity-ids.js";
+import { checksumForFlowFlagValues, isFlowFlagDowngrade, loadProjectFlowContract, resolveFlowFlags } from "../domain/flow-contract.js";
 import { AppError } from "../shared/errors.js";
 import { ensureDir, projectRunHome, projectRunIndexPath, projectRunJsonPath, resolveProjectRoot } from "../storage/paths.js";
 import { appendAudit } from "./audit.js";
 import { registerProject, requireProjectByRoot } from "./projects.js";
 import { buildRunFlowGuidance } from "./flow-guidance.js";
 import { readProtocolRuntimeState, requireProtocol } from "./protocols.js";
-const runSchemaId = "dd-flow/flow-run-index@2";
-const legacyRunSchemaId = "dd-flow/flow-run-index@1";
+import { checkpointRunUsage, usageForRun } from "./usage.js";
+import { refreshRunSessionProjection } from "./run-projection.js";
+const runSchemaId = "dd-flow/flow-run-index@3";
+const legacyRunSchemaId = "dd-flow/flow-run-index@2";
+const oldestRunSchemaId = "dd-flow/flow-run-index@1";
+const runtimeSchemaId = "dd-flow/flow-run@1";
 const runIdType = "RUN";
 const allowedRunFlowKinds = [
     "mb_sdlc",
@@ -25,14 +32,24 @@ const allowedRunFlowKinds = [
 ];
 export function startFlowRun(context, input) {
     const projectRoot = resolveProjectRoot(input.projectRoot);
+    const flowContract = loadProjectFlowContract(projectRoot);
     registerProject(context, { root: projectRoot });
     const project = requireProjectByRoot(context, projectRoot);
     const workspaceRoot = resolveWorkspaceRoot(input.workspaceRoot ?? projectRoot);
     const flowKind = parseRunFlowKind(input.flowKind);
     const slug = normalizeSlug(input.slug);
-    const runId = nextRunId(context, slug);
+    const runId = nextRunId(context, project.id, slug);
     const { shortId } = parseFullEntityId(runId);
     const now = context.now();
+    const flowFlags = resolveFlowFlags(flowContract, {
+        flowKind,
+        ...(input.preset ? { preset: input.preset } : {}),
+        ...(input.taskProfile !== undefined ? { taskProfile: input.taskProfile } : {}),
+        ...(input.protocolOverrides ? { protocolOverrides: input.protocolOverrides } : {}),
+        ...(input.runOverrides ? { runOverrides: input.runOverrides } : {}),
+        snapshotRevision: 1,
+        now
+    });
     const runHome = projectRunHome(context.ddFlowHome, project.id, runId);
     const runIndexAbsolute = projectRunIndexPath(context.ddFlowHome, project.id, runId);
     const runDirRelative = path.posix.join("runs", runId);
@@ -61,7 +78,8 @@ export function startFlowRun(context, input) {
         },
         execution: {
             project_root: project.root,
-            workspace_root: workspaceRoot
+            workspace_root: workspaceRoot,
+            git: gitFacts(workspaceRoot)
         },
         legacy: {
             project_tasks_run_dir: null
@@ -73,11 +91,18 @@ export function startFlowRun(context, input) {
         verdict: "pending",
         next_action: input.nextAction ?? null,
         created_at: now,
-        updated_at: now
+        updated_at: now,
+        started_at: now,
+        timing_status: "measured",
+        runtime_revision: 1,
+        snapshot_revision: flowFlags.snapshot_revision,
+        snapshot_checksum: flowFlags.snapshot_checksum,
+        reconciliation_status: "reconciled",
+        flow_flags: flowFlags
     };
     ensureDir(path.dirname(runtimePath));
     ensureDir(runHome);
-    writeJsonFile(runtimePath, index);
+    writeJsonFile(runtimePath, runtimeSnapshotForIndex(index, 1));
     writeJsonFile(runIndexAbsolute, index);
     context.db.run(`INSERT INTO flow_runs
       (id, short_id, slug, project_id, project_root, workspace_root, flow_kind, subject_type, subject_id,
@@ -111,13 +136,167 @@ export function startFlowRun(context, input) {
         eventType: "flow_run.started",
         payload: { run_id: runId, flow_kind: flowKind, subject: index.subject, workspace_root: workspaceRoot, run_home: runHome }
     });
+    appendRunTimeline(runHome, { at: now, type: "run_started", run_id: runId });
+    appendRunTimeline(runHome, {
+        at: now,
+        type: "flow_flags_resolved",
+        run_id: runId,
+        snapshot_revision: flowFlags.snapshot_revision,
+        snapshot_checksum: flowFlags.snapshot_checksum,
+        preset: flowFlags.preset.applied
+    });
     return { ok: true, run: flowRunSummary(requireRunById(context, project.id, runId)), index };
 }
 export function getFlowRunStatus(context, input) {
+    const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
+    const run = resolveRun(context, project.id, input.runId);
+    refreshRunSessionProjection(context, project.id, run.id);
+    const refreshedRun = requireRunById(context, project.id, run.id);
+    const index = parseRunIndex(refreshedRun.index_json);
+    const runtime = readRuntimeSnapshot(refreshedRun.runtime_path);
+    return { ok: true, run: flowRunSummary(refreshedRun), index, ...(runtime ? { runtime } : {}), flow_guidance: guidanceForRun(context, refreshedRun, index) };
+}
+export function getFlowRunFlagsStatus(context, input) {
     const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
     const run = resolveRun(context, project.id, input.runId);
     const index = parseRunIndex(run.index_json);
-    return { ok: true, run: flowRunSummary(run), index, flow_guidance: guidanceForRun(context, run, index) };
+    const runtime = readRuntimeSnapshot(run.runtime_path);
+    const flags = runtime?.flow_flags ?? index.flow_flags;
+    if (!flags) {
+        return {
+            ok: true,
+            run_id: run.id,
+            resolution_status: "legacy_incomplete",
+            flow_flags: null,
+            snapshot_revision: null,
+            snapshot_checksum: null
+        };
+    }
+    return {
+        ok: true,
+        run_id: run.id,
+        resolution_status: flags.resolution_status,
+        snapshot_revision: flags.snapshot_revision,
+        snapshot_checksum: flags.snapshot_checksum,
+        flow_flags: flags,
+        runtime_revision: runtime?.runtime_revision ?? index.runtime_revision ?? null
+    };
+}
+export function reviseFlowRunFlags(context, input) {
+    const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
+    const run = resolveRun(context, project.id, input.runId);
+    const idempotencyKey = requiredPlain(input.idempotencyKey, "idempotency-key");
+    context.db.exec("BEGIN IMMEDIATE");
+    let committed = false;
+    try {
+        const existingMutation = context.db.get("SELECT result_json FROM flow_run_flag_mutations WHERE project_id = ? AND run_id = ? AND idempotency_key = ?", [project.id, run.id, idempotencyKey]);
+        if (existingMutation) {
+            const result = { ...JSON.parse(existingMutation.result_json), idempotent: true };
+            context.db.exec("COMMIT");
+            committed = true;
+            return result;
+        }
+        // Read the authority only after the write lock: two callers with the same
+        // expected revision must not both pass the compare-and-set check.
+        const lockedRun = requireRunById(context, project.id, run.id);
+        const index = parseRunIndex(lockedRun.index_json);
+        const runtime = readRuntimeSnapshot(lockedRun.runtime_path);
+        const current = runtime?.flow_flags ?? index.flow_flags;
+        if (!current) {
+            throw new AppError("validation", "Legacy RUN has no flow-flag snapshot; revise is unavailable", 2, { run_id: run.id });
+        }
+        if (!Number.isInteger(input.expectedRevision) || input.expectedRevision < 1) {
+            throw new AppError("validation", "expected-revision must be a positive integer", 2, {
+                expected_revision: input.expectedRevision
+            });
+        }
+        if (current.snapshot_revision !== input.expectedRevision) {
+            throw new AppError("conflict", "Flow-flag snapshot revision is stale", 1, {
+                run_id: run.id,
+                expected_revision: input.expectedRevision,
+                actual_revision: current.snapshot_revision
+            });
+        }
+        const now = context.now();
+        const contract = loadProjectFlowContract(lockedRun.project_root);
+        const next = resolveFlowFlags(contract, {
+            flowKind: index.flow_kind,
+            preset: input.preset ?? current.preset.applied,
+            runOverrides: input.flags,
+            snapshotRevision: input.expectedRevision + 1,
+            now
+        });
+        for (const [key, value] of Object.entries(current.values)) {
+            if (!(key in input.flags) && !input.preset)
+                next.values[key] = value;
+        }
+        const downgrades = Object.entries(current.values).flatMap(([key, currentValue]) => {
+            const candidate = next.values[key];
+            return candidate && isFlowFlagDowngrade(key, candidate.value, currentValue.value)
+                ? [{ key, currentValue, candidate }]
+                : [];
+        });
+        const reason = input.reason?.trim();
+        const floorDowngrades = downgrades.filter(({ currentValue }) => currentValue.source.kind === "escalation");
+        if (floorDowngrades.length > 0) {
+            throw new AppError("validation", "Flow-flag downgrade would cross an applied mandatory floor", 2, {
+                flags: floorDowngrades.map(({ key, currentValue, candidate }) => ({ flag: key, current: currentValue.value, requested: candidate.value }))
+            });
+        }
+        if (downgrades.length > 0 && (!input.allowDowngrade || !reason)) {
+            throw new AppError("validation", "Flow-flag downgrade requires --allow-downgrade and --reason", 2, {
+                flags: downgrades.map(({ key, currentValue, candidate }) => ({ flag: key, current: currentValue.value, requested: candidate.value }))
+            });
+        }
+        if (downgrades.length > 0 && reason) {
+            for (const { candidate } of downgrades) {
+                candidate.rationale = `${candidate.rationale}; explicit downgrade revision: ${reason}`;
+                candidate.source = { ...candidate.source, ref: `${candidate.source.ref}#${idempotencyKey}`, revision: next.snapshot_revision };
+            }
+        }
+        next.snapshot_checksum = checksumForFlowFlagValues(next.values);
+        index.flow_flags = next;
+        index.snapshot_revision = next.snapshot_revision;
+        index.snapshot_checksum = next.snapshot_checksum;
+        index.reconciliation_status = "reconciled";
+        index.updated_at = now;
+        const result = {
+            ok: true,
+            run_id: run.id,
+            snapshot_revision: next.snapshot_revision,
+            snapshot_checksum: next.snapshot_checksum,
+            flow_flags: next,
+            ...(reason ? { reason } : {})
+        };
+        persistRunIndex(context, project, run, index, {
+            flagRevision: { revision: next.snapshot_revision, checksum: next.snapshot_checksum, at: now, idempotency_key: idempotencyKey }
+        });
+        context.db.run(`INSERT INTO flow_run_flag_mutations
+        (project_id, run_id, idempotency_key, expected_revision, resulting_revision, result_json, created_at)
+       VALUES (?, ?, ?, ?, ?, ?, ?)`, [project.id, run.id, idempotencyKey, input.expectedRevision, next.snapshot_revision, JSON.stringify(result), now]);
+        context.db.exec("COMMIT");
+        committed = true;
+        appendAudit(context, {
+            projectId: project.id,
+            eventType: "flow_run.flags_revised",
+            payload: { run_id: run.id, snapshot_revision: next.snapshot_revision, snapshot_checksum: next.snapshot_checksum, ...(reason ? { reason } : {}) }
+        });
+        appendRunTimeline(runArtifactRoot(run), {
+            at: now,
+            type: "flow_flags_revised",
+            run_id: run.id,
+            snapshot_revision: next.snapshot_revision,
+            snapshot_checksum: next.snapshot_checksum,
+            idempotency_key: idempotencyKey,
+            ...(reason ? { reason } : {})
+        });
+        return result;
+    }
+    catch (error) {
+        if (!committed)
+            context.db.exec("ROLLBACK");
+        throw error;
+    }
 }
 export function listFlowRuns(context, input) {
     const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
@@ -146,7 +325,9 @@ export function attachFlowRunStage(context, input) {
         dir,
         status,
         ...(input.dataSchemaId ? { data_schema_id: input.dataSchemaId } : existing?.data_schema_id ? { data_schema_id: existing.data_schema_id } : {}),
-        updated_at: now
+        updated_at: now,
+        ...(status === "running" && !existing?.started_at ? { started_at: now } : {}),
+        ...(status === "running" ? { attempt: nextAttempt(existing) } : {})
     };
     upsertStage(index, stageRun);
     index.updated_at = now;
@@ -156,6 +337,17 @@ export function attachFlowRunStage(context, input) {
         eventType: "flow_run.stage_attached",
         payload: { run_id: run.id, stage, dir, status }
     });
+    appendRunTimeline(runArtifactRoot(run), { at: now, type: "stage_attached", run_id: run.id, stage, status, attempt: stageRun.attempt ?? null });
+    if (status === "running") {
+        context.db.run("UPDATE flow_sessions SET current_stage = ?, updated_at = ? WHERE project_id = ? AND run_id = ?", [
+            stage,
+            now,
+            project.id,
+            run.id
+        ]);
+        refreshRunSessionProjection(context, project.id, run.id);
+        checkpointRunUsage(context, { projectId: project.id, runId: run.id, checkpoint: "stage_started", stage, stageAttempt: stageRun.attempt ?? null });
+    }
     const updatedRun = requireRunById(context, project.id, run.id);
     return { ok: true, run: flowRunSummary(updatedRun), stage_run: stageRun, index, flow_guidance: guidanceForRun(context, updatedRun, index) };
 }
@@ -178,16 +370,20 @@ export function completeFlowRunStage(context, input) {
         ...(input.dataSchemaId ? { data_schema_id: input.dataSchemaId } : {}),
         ...(input.report ? { report: input.report } : {}),
         ...(input.aliases && input.aliases.length > 0 ? { artifact_aliases: input.aliases } : {}),
-        updated_at: now
+        updated_at: now,
+        ...(status === "done" || status === "blocked" || status === "failed" || status === "skipped" ? { completed_at: now } : {})
     };
     upsertStage(index, stageRun);
     index.updated_at = now;
     persistRunIndex(context, project, run, index);
+    refreshRunSessionProjection(context, project.id, run.id);
     appendAudit(context, {
         projectId: project.id,
         eventType: "flow_run.stage_completed",
         payload: { run_id: run.id, stage, status, stage_report: input.stageReport ?? null, data: input.data ?? null }
     });
+    appendRunTimeline(runArtifactRoot(run), { at: now, type: "stage_completed", run_id: run.id, stage, status, attempt: stageRun.attempt ?? null });
+    checkpointRunUsage(context, { projectId: project.id, runId: run.id, checkpoint: "stage_finished", stage, stageAttempt: stageRun.attempt ?? null });
     const updatedRun = requireRunById(context, project.id, run.id);
     return { ok: true, run: flowRunSummary(updatedRun), stage_run: stageRun, index, flow_guidance: guidanceForRun(context, updatedRun, index) };
 }
@@ -205,18 +401,89 @@ export function completeFlowRun(context, input) {
         index.completed_at = now;
     }
     persistRunIndex(context, project, run, index);
+    refreshRunSessionProjection(context, project.id, run.id);
     appendAudit(context, {
         projectId: project.id,
         eventType: "flow_run.completed",
         payload: { run_id: run.id, status, verdict: index.verdict, next_action: index.next_action }
     });
+    appendRunTimeline(runArtifactRoot(run), { at: now, type: "run_completed", run_id: run.id, status });
+    checkpointRunUsage(context, { projectId: project.id, runId: run.id, checkpoint: "run_finished" });
     const updatedRun = requireRunById(context, project.id, run.id);
     return { ok: true, run: flowRunSummary(updatedRun), index, flow_guidance: guidanceForRun(context, updatedRun, index) };
 }
+const timelineSections = ["stages", "events", "sessions", "usage", "artifacts"];
+export function getFlowRunTimeline(context, input) {
+    const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
+    const run = resolveRun(context, project.id, input.runId);
+    const index = parseRunIndex(run.index_json);
+    const file = path.join(runArtifactRoot(run), "timeline.jsonl");
+    const events = fs.existsSync(file)
+        ? fs.readFileSync(file, "utf8").split(/\r?\n/).flatMap((line) => { try {
+            return line.trim() ? [JSON.parse(line)] : [];
+        }
+        catch {
+            return [];
+        } })
+        : [];
+    const hidden = parseHiddenTimelineSections(input.hiddenSections ?? []);
+    const sessions = index.sessions;
+    const elapsedMs = durationMs(index.started_at ?? run.created_at, index.completed_at ?? null);
+    const report = {
+        ok: true,
+        schema_id: "dd-flow/run-timeline@2",
+        run_id: run.id,
+        timing_status: index.timing_status ?? "legacy_incomplete",
+        hidden_sections: [...hidden],
+        available_sections: timelineSections,
+        summary: {
+            flow_kind: index.flow_kind,
+            subject: index.subject,
+            status: index.status,
+            verdict: index.verdict,
+            started_at: index.started_at ?? null,
+            completed_at: index.completed_at ?? null,
+            elapsed_ms: elapsedMs,
+            stage_count: index.stage_runs.length,
+            event_count: events.length,
+            session_count: sessions.length
+        }
+    };
+    if (!hidden.has("stages"))
+        report.stages = index.stage_runs.map((stage) => ({
+            ...stage,
+            elapsed_ms: durationMs(stage.started_at ?? null, stage.completed_at ?? null)
+        }));
+    if (!hidden.has("events"))
+        report.events = events;
+    if (!hidden.has("sessions"))
+        report.sessions = sessions;
+    if (!hidden.has("usage"))
+        report.usage = usageForRun(context, { projectId: project.id, runId: run.id, groupBy: "session" });
+    if (!hidden.has("artifacts"))
+        report.artifacts = index.stage_runs.map((stage) => ({
+            stage: stage.stage,
+            dir: stage.dir,
+            stage_report: stage.stage_report ?? null,
+            data: stage.data ?? null,
+            report: stage.report ?? null,
+            artifact_aliases: stage.artifact_aliases ?? []
+        }));
+    return report;
+}
+export function getFlowRunUsage(context, input) {
+    const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
+    const run = resolveRun(context, project.id, input.runId);
+    return usageForRun(context, { projectId: project.id, runId: run.id, groupBy: input.groupBy ?? "session" });
+}
+export function appendFlowRunTimelineEvent(context, projectId, runId, event) {
+    const run = requireRunById(context, projectId, runId);
+    appendRunTimeline(runArtifactRoot(run), { run_id: run.id, ...event });
+}
 function guidanceForRun(context, run, index) {
     if (run.subject_type === "protocol") {
         try {
-            const protocol = requireProtocol(context, run.subject_id);
+            const protocol = requireProtocol(context, run.subject_id, run.project_id);
             const state = readProtocolRuntimeState(context, protocol).state;
             return buildRunFlowGuidance({
                 stageRuns: index.stage_runs,
@@ -233,12 +500,19 @@ function guidanceForRun(context, run, index) {
     }
     return buildRunFlowGuidance({ stageRuns: index.stage_runs, runId: run.id, runDir: index.run_home?.relative_path ?? index.workspace.run_dir });
 }
-function persistRunIndex(context, project, run, index) {
+function persistRunIndex(context, project, run, index, options = {}) {
     const runtimePath = run.runtime_path || projectRunJsonPath(context.ddFlowHome, project.id, run.id);
     const runIndexPath = run.run_index_path || projectRunIndexPath(context.ddFlowHome, project.id, run.id);
+    const previousRuntime = readRuntimeSnapshot(runtimePath);
+    const runtimeRevision = Math.max(index.runtime_revision ?? 0, previousRuntime?.runtime_revision ?? 0) + 1;
+    index.runtime_revision = runtimeRevision;
+    const history = [...(previousRuntime?.flag_revision_history ?? [])];
+    if (options.flagRevision) {
+        history.push(options.flagRevision);
+    }
     ensureDir(path.dirname(runtimePath));
     ensureDir(path.dirname(runIndexPath));
-    writeJsonFile(runtimePath, index);
+    writeJsonFile(runtimePath, runtimeSnapshotForIndex(index, runtimeRevision, history));
     writeJsonFile(runIndexPath, index);
     context.db.run(`UPDATE flow_runs
      SET status = ?, verdict = ?, next_action = ?, index_json = ?, runtime_path = ?, run_index_path = ?,
@@ -256,6 +530,69 @@ function persistRunIndex(context, project, run, index) {
         run.id
     ]);
 }
+function appendRunTimeline(runHome, event) {
+    ensureDir(runHome);
+    const timelinePath = path.join(runHome, "timeline.jsonl");
+    let sequence = 0;
+    if (fs.existsSync(timelinePath)) {
+        const lines = fs.readFileSync(timelinePath, "utf8").trim().split(/\r?\n/).filter(Boolean);
+        const last = lines.length > 0 ? JSON.parse(lines[lines.length - 1]) : undefined;
+        sequence = typeof last?.sequence === "number" ? last.sequence : lines.length;
+    }
+    const enriched = {
+        event_id: crypto.randomUUID(),
+        sequence: sequence + 1,
+        ...event
+    };
+    fs.appendFileSync(timelinePath, `${JSON.stringify(enriched)}\n`);
+}
+function runtimeSnapshotForIndex(index, runtimeRevision, flagRevisionHistory = []) {
+    const rest = { ...index };
+    Reflect.deleteProperty(rest, "schema_id");
+    return {
+        ...rest,
+        schema_id: runtimeSchemaId,
+        run_index_schema_id: index.schema_id,
+        runtime_revision: runtimeRevision,
+        ...(flagRevisionHistory.length > 0 ? { flag_revision_history: flagRevisionHistory.slice(-32) } : {})
+    };
+}
+function readRuntimeSnapshot(file) {
+    if (!file || !fs.existsSync(file))
+        return undefined;
+    try {
+        const value = JSON.parse(fs.readFileSync(file, "utf8"));
+        return value.schema_id === runtimeSchemaId ? value : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function parseHiddenTimelineSections(values) {
+    const hidden = new Set();
+    for (const value of values) {
+        if (!timelineSections.includes(value)) {
+            throw new AppError("validation", "--hide must name a timeline section", 2, {
+                value,
+                allowed: timelineSections
+            });
+        }
+        hidden.add(value);
+    }
+    return hidden;
+}
+function durationMs(startedAt, completedAt) {
+    if (!startedAt || !completedAt)
+        return null;
+    const value = Date.parse(completedAt) - Date.parse(startedAt);
+    return Number.isFinite(value) && value >= 0 ? value : null;
+}
+function nextAttempt(existing) {
+    if (!existing?.attempt)
+        return "try-001";
+    const number = Number(existing.attempt.replace("try-", ""));
+    return `try-${String(Number.isFinite(number) ? number + 1 : 1).padStart(3, "0")}`;
+}
 function upsertStage(index, stageRun) {
     const position = index.stage_runs.findIndex((item) => item.stage === stageRun.stage);
     if (position === -1) {
@@ -292,8 +629,8 @@ function requireRunById(context, projectId, runId) {
     }
     return run;
 }
-function nextRunId(context, slug) {
-    const rows = context.db.all("SELECT id FROM flow_runs WHERE id LIKE 'RUN-%'");
+function nextRunId(context, projectId, slug) {
+    const rows = context.db.all("SELECT id FROM flow_runs WHERE project_id = ? AND id LIKE 'RUN-%'", [projectId]);
     const max = rows.reduce((value, row) => {
         try {
             const parsed = parseFullEntityId(row.id);
@@ -303,13 +640,7 @@ function nextRunId(context, slug) {
             return value;
         }
     }, 0);
-    for (let sequence = max + 1; sequence <= 999; sequence += 1) {
-        const id = formatFullId(runIdType, sequence, slug);
-        if (!context.db.get("SELECT id FROM flow_runs WHERE id = ?", [id])) {
-            return id;
-        }
-    }
-    throw new AppError("validation", "RUN id sequence exhausted", 2);
+    return formatFullId(runIdType, max + 1, slug);
 }
 function flowRunSummary(run) {
     return {
@@ -340,7 +671,7 @@ function flowRunSummary(run) {
 }
 function parseRunIndex(text) {
     const index = JSON.parse(text);
-    if (index.schema_id !== runSchemaId && index.schema_id !== legacyRunSchemaId) {
+    if (index.schema_id !== runSchemaId && index.schema_id !== legacyRunSchemaId && index.schema_id !== oldestRunSchemaId) {
         throw new AppError("validation", `Invalid run index schema: ${String(index.schema_id)}`, 2);
     }
     return index;
@@ -434,3 +765,10 @@ function writeJsonFile(file, value) {
 function runArtifactRoot(run) {
     return path.dirname(run.run_index_path);
 }
+function gitFacts(workspaceRoot) {
+    const read = (args) => {
+        const result = spawnSync("git", ["-C", workspaceRoot, ...args.split(" ")], { encoding: "utf8" });
+        return result.status === 0 ? result.stdout.trim() || null : null;
+    };
+    return { branch: read("branch --show-current"), head: read("rev-parse HEAD") };
+}

package/dist/services/schema-validation.js

@@ -2,6 +2,7 @@ import fs from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { Ajv } from "ajv/dist/ajv.js";
+import { normalizeFlowContract } from "../domain/flow-contract.js";
 import { AppError } from "../shared/errors.js";
 const schemaNamePattern = /^[a-z0-9][a-z0-9-]*$/;
 const mandatoryMbUpgradeReviewAspectIds = [
@@ -34,15 +35,15 @@ export function validateSchema(options) {
     if (!schemaNamePattern.test(options.schemaName)) {
         throw new AppError("usage", "--schema must be a schema name such as mb-upgrade-review-data", 2);
     }
-    const schemaResolution = resolveSchema(options);
-    const schema = readJson(schemaResolution.path, "schema");
     const filePath = path.resolve(options.file);
     const data = readJson(filePath, "input file");
+    const schemaResolution = resolveSchema(options, data);
+    const schema = readJson(schemaResolution.path, "schema");
     const ajv = new Ajv({ allErrors: true, strict: false, validateFormats: false });
     const validate = ajv.compile(schema);
     const valid = validate(data);
     const errors = valid ? [] : (validate.errors ?? []).map(formatAjvError);
-    const semanticErrors = validateSemanticSchema(options.schemaName, data);
+    const semanticErrors = valid ? validateSemanticSchema(options.schemaName, data) : [];
     const allErrors = [...errors, ...semanticErrors];
     if (allErrors.length > 0) {
         throw new AppError("schema_validation", `${path.basename(filePath)} does not match schema`, 2, {
@@ -58,16 +59,23 @@ export function validateSchema(options) {
         errors: []
     };
 }
-function resolveSchema(options) {
-    const fileName = `${options.schemaName}.schema.json`;
-    const candidates = [];
-    if (options.schemaDir) {
-        candidates.push({ path: path.join(path.resolve(options.schemaDir), fileName), source: "schema_dir" });
-    }
+function resolveSchema(options, data) {
+    const dataRecord = asRecord(data);
+    const dataSchemaId = dataRecord ? stringValue(dataRecord, "schema_id") : undefined;
+    const fileNames = options.schemaName === "flow-run-index" && dataSchemaId === "dd-flow/flow-run-index@3"
+        ? ["flow-run-index-v3.schema.json", "flow-run-index.schema.json"]
+        : [`${options.schemaName}.schema.json`];
     const projectRoot = path.resolve(options.projectRoot ?? process.cwd());
-    candidates.push({ path: path.join(projectRoot, ".memory-bank", "dd-flow", "schemas", fileName), source: "project" });
-    candidates.push({ path: path.join(projectRoot, "dd-flow", "schemas", fileName), source: "canonical" });
-    candidates.push({ path: path.join(bundledSchemaDir(), fileName), source: "bundled" });
+    const roots = [
+        ...(options.schemaDir ? [{ directory: path.resolve(options.schemaDir), source: "schema_dir" }] : []),
+        { directory: path.join(projectRoot, ".memory-bank", "dd-flow", "schemas"), source: "project" },
+        { directory: path.join(projectRoot, "dd-flow", "schemas"), source: "canonical" },
+        { directory: bundledSchemaDir(), source: "bundled" }
+    ];
+    const candidates = roots.flatMap((root) => fileNames.map((fileName) => ({
+        path: path.join(root.directory, fileName),
+        source: root.source
+    })));
     const found = candidates.find((candidate) => fs.existsSync(candidate.path));
     if (!found) {
         throw new AppError("schema_not_found", `Schema not found: ${options.schemaName}`, 2, {
@@ -121,6 +129,21 @@ function validateSemanticSchema(schemaName, data) {
     if (schemaName === "mb-sdlc-review-report") {
         return validateMbSdlcReviewReport(root);
     }
+    if (schemaName === "flow-contract") {
+        try {
+            normalizeFlowContract(root);
+            return [];
+        }
+        catch (error) {
+            if (!(error instanceof AppError))
+                throw error;
+            return [{
+                    path: typeof error.details.path === "string" ? error.details.path : "/",
+                    message: error.message,
+                    keyword: "dd-flow/flow-contract-semantic"
+                }];
+        }
+    }
     return [];
 }
 function validateMbUpgradeReviewData(root) {