supipowers 1.5.2 → 2.0.0

package/src/ultraplan/runtime/tracker-storage.ts

@@ -0,0 +1,368 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import type { PlatformPaths } from "../../platform/types.js";
+import type {
+  UltraPlanHookObservation,
+  UltraPlanPendingMutation,
+  UltraPlanRuntimeTracker,
+  UltraPlanSessionMigrationRecord,
+  UltraPlanStorageError,
+  UltraPlanStorageResult,
+} from "../../types.js";
+import {
+  validateUltraPlanRuntimeTracker,
+  validateUltraPlanSessionMigrationRecord,
+} from "../contracts.js";
+import {
+  getUltraplanExecutionLogPath,
+  getUltraplanHooksLogPath,
+  getUltraplanMigrationRecordPath,
+  getUltraplanRuntimeTrackerPath,
+} from "../project-paths.js";
+
+/**
+ * Slice-2 runtime storage seam.
+ *
+ * This module owns the durable read/write path for `runtime-tracker.json` and `migration.json`.
+ * Task 2.3 will grow this module to additionally own `hooks-log.jsonl`, pendingMutation staging,
+ * and reconciliation of partial writes against the manifest. For Slice 2/1.4 it provides the
+ * round-trip primitives that the storage wrappers and the migration engine depend on.
+ */
+
+function success<T>(value: T): UltraPlanStorageResult<T> {
+  return { ok: true, value };
+}
+
+function failure(
+  pathname: string,
+  kind: UltraPlanStorageError["kind"],
+  message: string,
+  details?: string[],
+): UltraPlanStorageResult<never> {
+  return {
+    ok: false,
+    error: {
+      kind,
+      path: pathname,
+      message,
+      ...(details ? { details } : {}),
+    },
+  };
+}
+
+function ensureDir(filePath: string): void {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+}
+
+function readJsonFile(filePath: string): UltraPlanStorageResult<unknown> {
+  if (!fs.existsSync(filePath)) {
+    return failure(filePath, "missing", `Artifact not found: ${filePath}`);
+  }
+  try {
+    return success(JSON.parse(fs.readFileSync(filePath, "utf8")));
+  } catch (error) {
+    return failure(
+      filePath,
+      "invalid-json",
+      error instanceof Error ? error.message : `Invalid JSON in ${filePath}`,
+    );
+  }
+}
+
+/**
+ * Atomic write: write to a sibling `*.tmp` file, then rename onto the destination. Prevents a
+ * half-written tracker from surviving a crash and being observed by the loader.
+ */
+function writeJsonAtomic(filePath: string, payload: unknown): UltraPlanStorageResult<string> {
+  try {
+    ensureDir(filePath);
+    const tmpPath = `${filePath}.tmp-${process.pid}-${Date.now()}`;
+    fs.writeFileSync(tmpPath, `${JSON.stringify(payload, null, 2)}\n`);
+    fs.renameSync(tmpPath, filePath);
+    return success(filePath);
+  } catch (error) {
+    return failure(
+      filePath,
+      "io",
+      error instanceof Error ? error.message : `Unable to write ${filePath}`,
+    );
+  }
+}
+
+/**
+ * Load the runtime tracker for a given session. Missing tracker is a first-class, non-error
+ * state — callers treat it as "no prior runtime state."
+ */
+export function loadTracker(
+  paths: PlatformPaths,
+  cwd: string,
+  sessionId: string,
+): UltraPlanStorageResult<UltraPlanRuntimeTracker> {
+  const filePath = getUltraplanRuntimeTrackerPath(paths, cwd, sessionId);
+  const parsed = readJsonFile(filePath);
+  if (!parsed.ok) return parsed;
+
+  const validation = validateUltraPlanRuntimeTracker(parsed.value);
+  if (!validation.ok) {
+    return failure(
+      filePath,
+      "validation-error",
+      `Runtime tracker failed schema validation: ${filePath}`,
+      validation.errors,
+    );
+  }
+  return success(validation.value);
+}
+
+/**
+ * Save the runtime tracker atomically after semantic and schema validation. Writes never observe
+ * a half-finalized tracker because the destination rename happens in one filesystem step.
+ */
+export function saveTrackerAtomic(
+  paths: PlatformPaths,
+  cwd: string,
+  sessionId: string,
+  tracker: UltraPlanRuntimeTracker,
+): UltraPlanStorageResult<string> {
+  const filePath = getUltraplanRuntimeTrackerPath(paths, cwd, sessionId);
+  // Normalize the applied-fingerprint ledger before validation: the invariant enforced on
+  // disk is that it contains no duplicates. Callers may hand in repeated fingerprints from
+  // replay flows; we dedupe once here so the persisted tracker stays coherent.
+  const normalized: UltraPlanRuntimeTracker = {
+    ...tracker,
+    appliedFingerprints: dedupeInOrder(tracker.appliedFingerprints),
+  };
+  const validation = validateUltraPlanRuntimeTracker(normalized);
+  if (!validation.ok) {
+    return failure(
+      filePath,
+      "validation-error",
+      `Runtime tracker failed schema validation: ${filePath}`,
+      validation.errors,
+    );
+  }
+  return writeJsonAtomic(filePath, validation.value);
+}
+
+function dedupeInOrder(values: readonly string[]): string[] {
+  const seen = new Set<string>();
+  const out: string[] = [];
+  for (const v of values) {
+    if (!seen.has(v)) {
+      seen.add(v);
+      out.push(v);
+    }
+  }
+  return out;
+}
+
+export function loadMigrationRecord(
+  paths: PlatformPaths,
+  cwd: string,
+  sessionId: string,
+): UltraPlanStorageResult<UltraPlanSessionMigrationRecord> {
+  const filePath = getUltraplanMigrationRecordPath(paths, cwd, sessionId);
+  const parsed = readJsonFile(filePath);
+  if (!parsed.ok) return parsed;
+
+  const validation = validateUltraPlanSessionMigrationRecord(parsed.value);
+  if (!validation.ok) {
+    return failure(
+      filePath,
+      "validation-error",
+      `Migration record failed schema validation: ${filePath}`,
+      validation.errors,
+    );
+  }
+  return success(validation.value);
+}
+
+export function saveMigrationRecord(
+  paths: PlatformPaths,
+  cwd: string,
+  sessionId: string,
+  record: UltraPlanSessionMigrationRecord,
+): UltraPlanStorageResult<string> {
+  const filePath = getUltraplanMigrationRecordPath(paths, cwd, sessionId);
+  const validation = validateUltraPlanSessionMigrationRecord(record);
+  if (!validation.ok) {
+    return failure(
+      filePath,
+      "validation-error",
+      `Migration record failed schema validation: ${filePath}`,
+      validation.errors,
+    );
+  }
+  return writeJsonAtomic(filePath, validation.value);
+}
+
+
+// ---------------------------------------------------------------------------
+// Hooks log (append-only JSONL)
+// ---------------------------------------------------------------------------
+
+/**
+ * Append a normalized hook observation to `hooks-log.jsonl`. This is the audit trail the
+ * reducer reads on replay. The append is suppressed for observations whose `fingerprint` has
+ * already been persisted into the tracker's `appliedFingerprints` set — that is what makes
+ * replay a persisted no-op on both the tracker AND the hooks log.
+ */
+export function appendHookLog(
+  paths: PlatformPaths,
+  cwd: string,
+  sessionId: string,
+  observation: UltraPlanHookObservation,
+): UltraPlanStorageResult<string> {
+  const trackerResult = loadTracker(paths, cwd, sessionId);
+  if (trackerResult.ok) {
+    if (trackerResult.value.appliedFingerprints.includes(observation.fingerprint)) {
+      // Observation already applied; replay is a persisted no-op.
+      return success(getUltraplanHooksLogPath(paths, cwd, sessionId));
+    }
+  } else if (trackerResult.error.kind !== "missing") {
+    // Tracker exists but is unreadable; fail closed.
+    return trackerResult;
+  }
+
+  const logPath = getUltraplanHooksLogPath(paths, cwd, sessionId);
+  try {
+    ensureDir(logPath);
+    fs.appendFileSync(logPath, `${JSON.stringify(observation)}\n`);
+    return success(logPath);
+  } catch (error) {
+    return failure(
+      logPath,
+      "io",
+      error instanceof Error ? error.message : `Unable to append ${logPath}`,
+    );
+  }
+}
+
+export function appendExecutionLog(
+  paths: PlatformPaths,
+  cwd: string,
+  sessionId: string,
+  entry: Record<string, unknown>,
+): UltraPlanStorageResult<string> {
+  const logPath = getUltraplanExecutionLogPath(paths, cwd, sessionId);
+  const observationFingerprint = typeof entry.observationFingerprint === "string"
+    ? entry.observationFingerprint
+    : null;
+  try {
+    ensureDir(logPath);
+    if (observationFingerprint && executionLogContainsObservation(logPath, observationFingerprint)) {
+      return success(logPath);
+    }
+    fs.appendFileSync(logPath, `${JSON.stringify(entry)}\n`);
+    return success(logPath);
+  } catch (error) {
+    return failure(
+      logPath,
+      "io",
+      error instanceof Error ? error.message : `Unable to append ${logPath}`,
+    );
+  }
+}
+
+function executionLogContainsObservation(logPath: string, observationFingerprint: string): boolean {
+  if (!fs.existsSync(logPath)) {
+    return false;
+  }
+
+  for (const line of fs.readFileSync(logPath, "utf8").split("\n")) {
+    if (!line) {
+      continue;
+    }
+
+    try {
+      const parsed = JSON.parse(line) as Record<string, unknown>;
+      if (parsed.observationFingerprint === observationFingerprint) {
+        return true;
+      }
+    } catch {
+      // Ignore malformed historical lines and keep scanning for a matching durable entry.
+    }
+  }
+
+  return false;
+}
+
+// ---------------------------------------------------------------------------
+// Pending-mutation staging and reconciliation
+// ---------------------------------------------------------------------------
+
+/**
+ * Stage a pending mutation atomically: load the tracker, set `pendingMutation`, and rewrite.
+ * Caller provides the exact `UltraPlanPendingMutation` record (attemptId, plan, expected
+ * manifest fingerprint, stagedAt) per spec §durability order item 3.
+ */
+export function stagePendingMutation(
+  paths: PlatformPaths,
+  cwd: string,
+  sessionId: string,
+  pending: UltraPlanPendingMutation,
+): UltraPlanStorageResult<string> {
+  const loaded = loadTracker(paths, cwd, sessionId);
+  if (!loaded.ok) return loaded;
+  const next: UltraPlanRuntimeTracker = {
+    ...loaded.value,
+    pendingMutation: pending,
+    updatedAt: pending.stagedAt,
+  };
+  return saveTrackerAtomic(paths, cwd, sessionId, next);
+}
+
+/**
+ * Clear `pendingMutation` atomically. Used at the end of the durability order (item 5) when
+ * the manifest write has already landed and the attempt is committed to the finalized ledger.
+ */
+export function clearPendingMutation(
+  paths: PlatformPaths,
+  cwd: string,
+  sessionId: string,
+): UltraPlanStorageResult<string> {
+  const loaded = loadTracker(paths, cwd, sessionId);
+  if (!loaded.ok) return loaded;
+  if (loaded.value.pendingMutation === null) {
+    return success(getUltraplanRuntimeTrackerPath(paths, cwd, sessionId));
+  }
+  const next: UltraPlanRuntimeTracker = {
+    ...loaded.value,
+    pendingMutation: null,
+  };
+  return saveTrackerAtomic(paths, cwd, sessionId, next);
+}
+
+export type UltraPlanReconciliationOutcome =
+  | { kind: "no-pending" }
+  | { kind: "committed" }
+  | { kind: "replay-needed"; pending: UltraPlanPendingMutation };
+
+/**
+ * Reconcile a staged `pendingMutation` against the actual manifest contents on resume.
+ *
+ * - When no pending mutation is present, returns `no-pending`.
+ * - When the manifest already matches the staged `expectedManifestFingerprint`, the pending
+ *   mutation is considered committed: clear it and return `committed`.
+ * - Otherwise return `replay-needed` and leave the pending mutation in place so the caller can
+ *   replay the mutation plan idempotently.
+ */
+export function reconcilePendingMutationAgainstManifest(
+  paths: PlatformPaths,
+  cwd: string,
+  sessionId: string,
+  actualManifestFingerprint: string,
+): UltraPlanStorageResult<UltraPlanReconciliationOutcome> {
+  const loaded = loadTracker(paths, cwd, sessionId);
+  if (!loaded.ok) return loaded;
+  const pending = loaded.value.pendingMutation;
+  if (pending === null) {
+    return success({ kind: "no-pending" });
+  }
+  if (pending.expectedManifestFingerprint === actualManifestFingerprint) {
+    const cleared = clearPendingMutation(paths, cwd, sessionId);
+    if (!cleared.ok) return cleared;
+    return success({ kind: "committed" });
+  }
+  return success({ kind: "replay-needed", pending });
+}

package/src/ultraplan/session-selection.ts

@@ -0,0 +1,291 @@
+import type {
+  UltraPlanAuthoredArtifact,
+  UltraPlanCursor,
+  UltraPlanManifest,
+  UltraPlanReviewStatus,
+  UltraPlanScenario,
+  UltraPlanScenarioStatus,
+  UltraPlanSessionBucket,
+  UltraPlanSessionState,
+  UltraPlanSessionSummary,
+  UltraPlanStack,
+} from "../types.js";
+import { hasRequiredUltraPlanScenarioProof } from "./contracts.js";
+
+
+export interface UltraPlanVisibleSession extends UltraPlanSessionSummary {
+  bucket: UltraPlanSessionBucket;
+  idleReasonLabel: string | null;
+}
+
+export interface UltraPlanResolvedCursor {
+  cursor: UltraPlanCursor;
+  source: "persisted" | "recomputed";
+}
+
+const TERMINAL_SCENARIO_STATUSES = new Set<UltraPlanScenarioStatus>([
+  "green-proved",
+  "review-passed",
+  "done",
+]);
+const ONGOING_CURSOR_STATUSES = new Set([
+  "red-running",
+  "green-running",
+  "in-review",
+]);
+
+
+export function mapUltraPlanStateToBucket(state: UltraPlanSessionState): UltraPlanSessionBucket {
+  switch (state) {
+    case "ready":
+      return "pending";
+    case "running":
+      return "ongoing";
+    case "blocked":
+    case "awaiting-user":
+      return "idle";
+    case "complete":
+    case "discarded":
+      return "done";
+  }
+}
+
+export function getUltraPlanIdleReasonLabel(session: UltraPlanSessionSummary): string | null {
+  if (session.state === "awaiting-user") {
+    return session.blocker?.message ? `Awaiting user: ${session.blocker.message}` : "Awaiting user input";
+  }
+
+  if (session.state === "blocked") {
+    return session.blocker?.message ?? "Blocked";
+  }
+
+  return null;
+}
+
+export function resolveUltraPlanSessionBucket(
+  session: UltraPlanSessionSummary,
+  resolved?: UltraPlanResolvedCursor,
+): UltraPlanSessionBucket {
+  const cursor = resolved?.cursor ?? session.cursor;
+
+  if (session.state === "discarded") {
+    return "done";
+  }
+
+  if (!resolved && session.state === "complete") {
+    return "done";
+  }
+
+  if (cursor?.targetType === "session" && cursor.status === "complete") {
+    return "done";
+  }
+
+  if (session.state === "awaiting-user") {
+    return "idle";
+  }
+
+  if (session.state === "blocked" || cursor?.status === "blocked") {
+    return "idle";
+  }
+
+  if (session.state === "running" || (cursor && ONGOING_CURSOR_STATUSES.has(cursor.status))) {
+    return "ongoing";
+  }
+
+  return "pending";
+}
+
+export function getVisibleUltraPlanSessions(
+  sessions: UltraPlanSessionSummary[],
+  options?: { includeDone?: boolean },
+): UltraPlanVisibleSession[] {
+  const includeDone = options?.includeDone ?? false;
+
+  return sessions
+    .map((session) => ({
+      ...session,
+      bucket: resolveUltraPlanSessionBucket(session),
+      idleReasonLabel: getUltraPlanIdleReasonLabel(session),
+    }))
+    .filter((session) => includeDone || session.bucket !== "done");
+}
+
+export function isUltraPlanCursorSummaryValid(
+  manifest: UltraPlanManifest,
+  authored: UltraPlanAuthoredArtifact,
+): boolean {
+  if (!manifest.cursor) {
+    return false;
+  }
+
+  return sameCursor(manifest.cursor, recomputeUltraPlanCursor(manifest, authored));
+}
+
+export function resolveUltraPlanCurrentCursor(
+  manifest: UltraPlanManifest,
+  authored: UltraPlanAuthoredArtifact,
+): UltraPlanResolvedCursor {
+  const recomputed = recomputeUltraPlanCursor(manifest, authored);
+  if (manifest.cursor && sameCursor(manifest.cursor, recomputed)) {
+    return { cursor: recomputed, source: "persisted" };
+  }
+
+  return { cursor: recomputed, source: "recomputed" };
+}
+
+function recomputeUltraPlanCursor(manifest: UltraPlanManifest, authored: UltraPlanAuthoredArtifact): UltraPlanCursor {
+  for (const stack of authored.stacks) {
+    if (stack.applicability === "not-applicable") {
+      continue;
+    }
+
+    const stackCursor = recomputeStackCursor(manifest, stack);
+    if (stackCursor) {
+      return stackCursor;
+    }
+  }
+
+  return {
+    targetType: "session",
+    stack: null,
+    domainId: null,
+    level: null,
+    scenarioId: null,
+    phase: "complete",
+    status: "complete",
+    summary: "Session complete",
+  };
+}
+
+function recomputeStackCursor(manifest: UltraPlanManifest, stack: UltraPlanStack): UltraPlanCursor | null {
+  for (const domain of stack.domains) {
+    const scenarioCursor = findFirstScenarioCursor(domain.unit)
+      ?? findFirstScenarioCursor(domain.integration)
+      ?? findFirstScenarioCursor(domain.e2e);
+
+    if (scenarioCursor) {
+      return scenarioCursor;
+    }
+
+    if (stack.agentSlots.domainReviewEnabled && domain.review.enabled) {
+      if (!stack.agentSlots.domainReviewer) {
+        return {
+          targetType: "domain-review",
+          stack: stack.stack,
+          domainId: domain.id,
+          level: null,
+          scenarioId: null,
+          phase: "waiting",
+          status: "blocked",
+          summary: `${stack.stack} / ${domain.id} / domain review blocked — missing reviewer slot`,
+        };
+      }
+
+      const reviewStatus = getDomainReviewStatus(manifest, stack.stack, domain.id) ?? "pending";
+      if (reviewStatus !== "passed") {
+        return {
+          targetType: "domain-review",
+          stack: stack.stack,
+          domainId: domain.id,
+          level: null,
+          scenarioId: null,
+          phase: reviewStatus === "blocked" ? "waiting" : "review",
+          status: reviewStatus,
+          summary: `${stack.stack} / ${domain.id} / domain review`,
+        };
+      }
+    }
+  }
+
+  if (stack.agentSlots.stackReviewEnabled) {
+    if (!stack.agentSlots.stackReviewer) {
+      return {
+        targetType: "stack-review",
+        stack: stack.stack,
+        domainId: null,
+        level: null,
+        scenarioId: null,
+        phase: "waiting",
+        status: "blocked",
+        summary: `${stack.stack} / stack review blocked — missing reviewer slot`,
+      };
+    }
+
+    const reviewStatus = getStackReviewStatus(manifest, stack.stack) ?? "pending";
+    if (reviewStatus !== "passed") {
+      return {
+        targetType: "stack-review",
+        stack: stack.stack,
+        domainId: null,
+        level: null,
+        scenarioId: null,
+        phase: reviewStatus === "blocked" ? "waiting" : "review",
+        status: reviewStatus,
+        summary: `${stack.stack} / stack review`,
+      };
+    }
+  }
+
+  return null;
+}
+
+function findFirstScenarioCursor(scenarios: UltraPlanScenario[]): UltraPlanCursor | null {
+  for (const scenario of scenarios) {
+    if (!TERMINAL_SCENARIO_STATUSES.has(scenario.status) || !hasRequiredUltraPlanScenarioProof(scenario)) {
+      return {
+        targetType: "scenario",
+        stack: scenario.stack,
+        domainId: scenario.domainId,
+        level: scenario.level,
+        scenarioId: scenario.id,
+        phase: getScenarioPhase(scenario.status),
+        status: scenario.status,
+        summary: `${scenario.stack} / ${scenario.domainId} / ${scenario.level} / ${scenario.title}`,
+      };
+    }
+  }
+
+  return null;
+}
+
+function getDomainReviewStatus(
+  manifest: UltraPlanManifest,
+  stack: UltraPlanStack["stack"],
+  domainId: string,
+): UltraPlanReviewStatus | null {
+  return manifest.reviews.find((review) => review.type === "domain" && review.stack === stack && review.domainId === domainId)?.status ?? null;
+}
+
+function getStackReviewStatus(manifest: UltraPlanManifest, stack: UltraPlanStack["stack"]): UltraPlanReviewStatus | null {
+  return manifest.reviews.find((review) => review.type === "stack" && review.stack === stack)?.status ?? null;
+}
+
+function getScenarioPhase(status: UltraPlanScenarioStatus): UltraPlanCursor["phase"] {
+  switch (status) {
+    case "planned":
+    case "red-running":
+      return "red";
+    case "red-proved":
+    case "green-running":
+      return "green";
+    case "in-review":
+      return "review";
+    case "blocked":
+      return "waiting";
+    case "green-proved":
+    case "review-passed":
+    case "done":
+      return "complete";
+  }
+}
+
+function sameCursor(left: UltraPlanCursor, right: UltraPlanCursor): boolean {
+  return left.targetType === right.targetType
+    && left.stack === right.stack
+    && left.domainId === right.domainId
+    && left.level === right.level
+    && left.scenarioId === right.scenarioId
+    && left.phase === right.phase
+    && left.status === right.status
+    && left.summary === right.summary;
+}