switchboard-cli 0.1.0-alpha.1 → 0.1.0-alpha.3

package/node_modules/@switchboard/core/src/canonical-delta.ts

@@ -0,0 +1,754 @@
+import type {
+  CanonicalDelta,
+  ConsequenceType,
+  EvidenceAccounting,
+  FileChange,
+  GateState,
+  NextSlice,
+  NormalizedReturnEnvelope,
+  ProjectContract,
+  ReconcileReport,
+  ResidualResolution,
+  ReturnReport,
+  TestCheck,
+} from "./types";
+import { canonicalDeltaSchema, evidenceAccountingSchema, nextSliceSchema } from "./types";
+import { randomBytes } from "crypto";
+
+// ---------------------------------------------------------------------------
+// System detection from file paths
+// ---------------------------------------------------------------------------
+
+// Shared system detection patterns — used by both canonical-delta and run-snapshot.
+// Exported so run-snapshot imports the same list (single source of truth).
+export const SYSTEM_PATTERNS: [RegExp, string][] = [
+  [/supabase|\.sql$/i, "Supabase / Database"],
+  [/middleware/i, "Middleware"],
+  [/auth/i, "Auth"],
+  [/api\//i, "API routes"],
+  [/components?\//i, "UI components"],
+  [/lib\//i, "Library / utilities"],
+  [/\.css$/i, "Styles"],
+  [/\.config\.|next\.config|tsconfig/i, "Config"],
+  [/\.spec\.|\.test\.|__tests__|tests?\//i, "Tests"],
+  [/redis/i, "Redis"],
+  [/storage|upload/i, "Storage / uploads"],
+  [/migration/i, "Database migrations"],
+  [/payment|billing|stripe/i, "Payment / Billing"],
+];
+
+function detectSystems(files: string[]): string[] {
+  const systems = new Set<string>();
+  for (const file of files) {
+    for (const [pattern, label] of SYSTEM_PATTERNS) {
+      if (pattern.test(file)) systems.add(label);
+    }
+  }
+  return [...systems];
+}
+
+// ---------------------------------------------------------------------------
+// Boundary check
+// ---------------------------------------------------------------------------
+
+function checkBoundaries(
+  contract: ProjectContract,
+  report: ReturnReport,
+): { preserved: string[]; violated: string[] } {
+  const preserved: string[] = [];
+  const violated: string[] = [];
+  const returnText = `${report.summary} ${report.decisions_made.join(" ")}`.toLowerCase();
+
+  for (const ng of contract.non_goals) {
+    const substance = ng.toLowerCase().replace(/^not\s+(a\s+|an\s+)?/i, "").replace(/\.$/, "").trim();
+
+    // Require the full substance phrase (or a significant portion) to appear,
+    // not just individual short words. This prevents "panel" matching "admin panel".
+    const phrasePresent = returnText.includes(substance);
+    const significantWords = substance.split(/\s+/).filter(w => w.length > 4);
+    const multiWordMatch = significantWords.length >= 2 &&
+      significantWords.every(w => returnText.includes(w));
+
+    const mentioned = phrasePresent || multiWordMatch;
+
+    if (mentioned) {
+      // Check for negation near the mention
+      const idx = returnText.indexOf(significantWords[0] ?? substance.split(/\s+/)[0] ?? "");
+      const window = returnText.substring(Math.max(0, idx - 30), idx + 30);
+      const negated = /\bno\b|\bnot\b|\bwithout\b|\bavoided\b|\bexcluded\b/.test(window);
+
+      if (!negated) {
+        violated.push(ng);
+      } else {
+        preserved.push(ng);
+      }
+    } else {
+      preserved.push(ng);
+    }
+  }
+
+  return { preserved, violated };
+}
+
+// ---------------------------------------------------------------------------
+// Evidence accounting — single source of truth for all counts
+// ---------------------------------------------------------------------------
+
+export function computeEvidenceAccounting(input: {
+  report: ReturnReport;
+  reconcile: ReconcileReport | null;
+  boundariesPreserved: string[];
+  boundariesViolated: string[];
+  cautions: string[];
+  unresolved: string[];
+}): EvidenceAccounting {
+  const { report, reconcile, boundariesPreserved, boundariesViolated, cautions, unresolved } = input;
+
+  // Scope checks from reconcile
+  const reconcileFindings = reconcile?.findings ?? [];
+  const scopeCategories = new Set(["scope-inflation", "non-goal-violation", "goal-drift", "target-user-shift", "untracked-decision", "evidence-contradiction"]);
+  const scopeFindings = reconcileFindings.filter(f => scopeCategories.has(f.category));
+  const scope_check_count = reconcile ? reconcile.checked_count : 0;
+  const scope_check_pass_count = scope_check_count - scopeFindings.length;
+  const scope_check_caution_count = scopeFindings.filter(f => f.severity === "warning").length;
+  const scope_check_blocker_count = scopeFindings.filter(f => f.severity === "review-required").length;
+
+  // Consequence type — why did state advance?
+  let consequence_type: ConsequenceType = "no-change";
+  let consequence_label = "No change recorded.";
+
+  if (report.changed_files.length > 0) {
+    consequence_type = "code-change";
+    consequence_label = `${report.changed_files.length} file(s) changed.`;
+  } else if (report.status === "done" && report.decisions_made.length > 0) {
+    consequence_type = "contract-clarification";
+    consequence_label = `${report.decisions_made.length} decision(s) recorded. No files changed.`;
+  } else if (report.status === "done" || report.objective_met === "yes" || report.objective_met === "partial") {
+    consequence_type = "absorbed-return";
+    consequence_label = "Return absorbed. No files changed.";
+  } else if (unresolved.length > 0) {
+    consequence_type = "open-items-recorded";
+    consequence_label = `${unresolved.length} open item(s) recorded. No files changed.`;
+  } else {
+    consequence_type = "no-change";
+    consequence_label = "State recorded but no measurable change.";
+  }
+
+  return evidenceAccountingSchema.parse({
+    scope_check_count,
+    scope_check_pass_count: Math.max(0, scope_check_pass_count),
+    scope_check_caution_count,
+    scope_check_blocker_count,
+
+    verification_run_count: report.verification_run.length,
+    verification_runs: report.verification_run,
+
+    evidence_item_count: report.evidence.length,
+    evidence_items: report.evidence,
+
+    file_change_count: report.changed_files.length,
+    artifact_change_count: report.artifacts_created.filter(Boolean).length,
+
+    criteria_met_count: report.success_criteria_met.length,
+    criteria_met: report.success_criteria_met,
+
+    caution_count: cautions.length,
+    unresolved_count: unresolved.length,
+
+    boundary_preserved_count: boundariesPreserved.length,
+    boundary_violated_count: boundariesViolated.length,
+
+    consequence_type,
+    consequence_label,
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Residual resolution — maps prior-loop residuals to current-loop evidence
+// ---------------------------------------------------------------------------
+
+export function deriveResidualResolutions(input: {
+  priorCautions: string[];
+  priorUnresolved: string[];
+  currentReport: ReturnReport;
+  currentDelta?: CanonicalDelta | null;
+}): ResidualResolution[] {
+  const { priorCautions, priorUnresolved, currentReport } = input;
+  const resolutions: ResidualResolution[] = [];
+
+  // Strict evidence pools — only structured proof fields, NOT summary.
+  // Summary fallback was presentation-layer inference, not provenance.
+  const structuredEvidence = [
+    ...currentReport.evidence,
+    ...currentReport.verification_run,
+    ...currentReport.success_criteria_met,
+    ...currentReport.decisions_made,
+  ].map(e => e.toLowerCase());
+
+  const artifactPool = [
+    ...currentReport.changed_files,
+    ...currentReport.artifacts_created.filter(Boolean),
+  ].map(a => a.toLowerCase());
+
+  const allStrictLines = [...structuredEvidence, ...artifactPool];
+
+  function findEvidence(residualText: string): { evidence: string; disposition: ResidualResolution["disposition"] } {
+    const words = residualText.toLowerCase()
+      .replace(/^\[.*?\]\s*/, "") // strip [reconcile] etc. prefixes
+      .replace(/^blocker:\s*/i, "")
+      .replace(/^escalation:\s*/i, "")
+      .split(/\s+/)
+      .filter(w => w.length > 3);
+
+    // Find the best-matching structured evidence line
+    let bestMatch = "";
+    let bestScore = 0;
+    for (const line of allStrictLines) {
+      const score = words.filter(w => line.includes(w)).length;
+      if (score > bestScore) {
+        bestScore = score;
+        bestMatch = line;
+      }
+    }
+
+    // Require at least 2 keyword matches (or 1 if the residual is very short)
+    const threshold = words.length <= 3 ? 1 : 2;
+    if (bestScore >= threshold) {
+      return { evidence: bestMatch, disposition: "resolved" };
+    }
+
+    // No summary fallback — if structured evidence doesn't match, it's carried forward
+    return { evidence: "", disposition: "carried_forward" };
+  }
+
+  for (const caution of priorCautions) {
+    const { evidence, disposition } = findEvidence(caution);
+    resolutions.push({
+      prior_residual_text: caution,
+      source: "caution",
+      loop2_evidence_used: evidence,
+      disposition,
+      resolution_note: disposition === "resolved"
+        ? `Matched to structured evidence: ${evidence.slice(0, 80)}${evidence.length > 80 ? "…" : ""}`
+        : "No matching structured evidence found in current loop.",
+    });
+  }
+
+  for (const item of priorUnresolved) {
+    const source: ResidualResolution["source"] = item.startsWith("Blocker:") ? "blocker"
+      : item.startsWith("Escalation:") ? "escalation"
+      : "unresolved";
+    const { evidence, disposition } = findEvidence(item);
+    resolutions.push({
+      prior_residual_text: item,
+      source,
+      loop2_evidence_used: evidence,
+      disposition,
+      resolution_note: disposition === "resolved"
+        ? `Matched to structured evidence: ${evidence.slice(0, 80)}${evidence.length > 80 ? "…" : ""}`
+        : "No matching structured evidence found in current loop.",
+    });
+  }
+
+  return resolutions;
+}
+
+// ---------------------------------------------------------------------------
+// Derive canonical delta
+// ---------------------------------------------------------------------------
+
+export function deriveCanonicalDelta(input: {
+  report: ReturnReport;
+  contract: ProjectContract;
+  gateState: GateState;
+  reconcile?: ReconcileReport | null;
+  priorCautions?: string[];
+  priorUnresolved?: string[];
+  /** Whether the report's changed_files actually exist in the repo. Default true. */
+  repoGrounded?: boolean;
+  /** Normalized envelope, when available. Provides richer typed data for provenance. */
+  envelope?: NormalizedReturnEnvelope | null;
+}): CanonicalDelta {
+  const { report, contract, gateState, envelope } = input;
+  const { preserved, violated } = checkBoundaries(contract, report);
+
+  // What was implemented
+  const implemented: string[] = [];
+  if (report.summary) implemented.push(report.summary);
+  for (const art of report.artifacts_created) {
+    if (art && !implemented.some(i => i.includes(art))) implemented.push(art);
+  }
+
+  // Systems touched — prefer pre-classified from envelope when available
+  const systems_touched = envelope
+    ? [...new Set(envelope.changed_files.map(f => f.system).filter(Boolean))]
+    : detectSystems(report.changed_files);
+
+  // Verified
+  const verified = [
+    ...report.verification_run.map(v => `✓ ${v}`),
+    ...report.evidence.map(e => `✓ ${e}`),
+  ];
+
+  // Cautions
+  const cautions: string[] = [];
+  if (gateState.evidence_summary.caution_count > 0) {
+    cautions.push(`${gateState.evidence_summary.caution_count} reconcile caution(s)`);
+  }
+  if (violated.length > 0) {
+    cautions.push(`${violated.length} boundary violation(s): ${violated.join("; ")}`);
+  }
+  if (report.status !== "done") {
+    cautions.push(`Execution status: ${report.status}`);
+  }
+
+  // Unresolved
+  const unresolved: string[] = [];
+  for (const b of report.blockers) { if (b) unresolved.push(`Blocker: ${b}`); }
+  for (const e of report.escalations) { if (e) unresolved.push(`Escalation: ${e}`); }
+  if (report.objective_met !== "yes") {
+    unresolved.push(`Objective only ${report.objective_met} met.`);
+  }
+
+  // Decisions with trace status
+  const decisions = report.decisions_made.map(d => ({
+    text: d,
+    traced: /traces?\s+to/i.test(d) || contract.non_goals.some(ng => {
+      const words = ng.toLowerCase().split(/\s+/).filter(w => w.length > 3);
+      return words.some(w => d.toLowerCase().includes(w));
+    }),
+  }));
+
+  // Summary — verification_runs and evidence_items counted separately to prevent
+  // conflation. The legacy `verified` array merges both (kept for compat), but the
+  // summary must not say "7 verification(s)" when 3 are runs and 4 are evidence.
+  const parts: string[] = [];
+  parts.push(`${report.changed_files.length} file(s) changed`);
+  if (systems_touched.length > 0) parts.push(`across ${systems_touched.join(", ")}`);
+  parts.push(`${report.verification_run.length} verification run(s)`);
+  if (report.evidence.length > 0) parts.push(`${report.evidence.length} evidence item(s)`);
+  if (cautions.length > 0) parts.push(`${cautions.length} caution(s)`);
+  if (unresolved.length > 0) parts.push(`${unresolved.length} unresolved`);
+
+  // Structured file changes — prefer pre-classified from envelope
+  const file_changes: FileChange[] = envelope
+    ? envelope.changed_files.map(f => ({ path: f.path, system: f.system }))
+    : report.changed_files.map(path => {
+        let system = "";
+        for (const [pattern, label] of SYSTEM_PATTERNS) {
+          if (pattern.test(path)) { system = label; break; }
+        }
+        return { path, system };
+      });
+
+  // Structured test checks — only from real test framework output, NOT from verification_run.
+  // verification_run lines are already counted in verification_runs[].
+  // Duplicating them here caused the proof ledger to double-count.
+  const tests_or_checks: TestCheck[] = [];
+
+  // Artifact changes
+  const artifact_changes = report.artifacts_created.filter(Boolean);
+
+  // Objective state
+  let objective_state: "met" | "partial" | "unmet" | "not_started" = "not_started";
+  if (report.objective_met === "yes") objective_state = "met";
+  else if (report.objective_met === "partial") objective_state = "partial";
+  else objective_state = "unmet";
+
+  // State fields advanced — repoGrounded flag controls the "in repo" claim
+  const repoGroundedForDelta = input.repoGrounded ?? true;
+  const state_fields_advanced: string[] = [];
+  if (report.status === "done") state_fields_advanced.push("stage → return-ingested → closed (on seal)");
+  if (report.changed_files.length > 0) {
+    state_fields_advanced.push(
+      repoGroundedForDelta
+        ? `${report.changed_files.length} file(s) in repo`
+        : `${report.changed_files.length} file(s) claimed (simulated — not repo-grounded)`
+    );
+  }
+  if (report.decisions_made.length > 0) state_fields_advanced.push(`${report.decisions_made.length} decision(s) recorded`);
+  if (report.evidence.length > 0) state_fields_advanced.push(`${report.evidence.length} evidence item(s) added`);
+
+  // Evidence accounting — single source of truth
+  const evidence_accounting = computeEvidenceAccounting({
+    report,
+    reconcile: input.reconcile ?? null,
+    boundariesPreserved: preserved,
+    boundariesViolated: violated,
+    cautions,
+    unresolved,
+  });
+
+  return canonicalDeltaSchema.parse({
+    // Identity & lineage
+    delta_id: `delta-${randomBytes(8).toString("hex")}`,
+    project_id: contract.project_id,
+    parent_contract_id: contract.project_id,
+    return_id: report.handoff_id,
+    gate_state: gateState.label,
+    objective_state,
+    created_at: new Date().toISOString(),
+
+    // What changed
+    implemented,
+    systems_touched,
+    file_changes,
+    artifact_changes,
+
+    // Evidence
+    tests_or_checks,
+    verification_runs: report.verification_run,
+    evidence_items: report.evidence,
+
+    // Boundaries
+    boundaries_preserved: preserved,
+    boundaries_violated: violated,
+
+    // Open items
+    cautions,
+    unresolved,
+    decisions,
+
+    // State fields
+    state_fields_advanced,
+
+    // Display
+    summary: parts.join(". ") + ".",
+
+    // Evidence accounting
+    evidence_accounting,
+
+    // Legacy
+    verified,
+
+    // Residual resolutions — populated when prior residuals are provided
+    residual_resolutions: (input.priorCautions?.length || input.priorUnresolved?.length)
+      ? deriveResidualResolutions({
+          priorCautions: input.priorCautions ?? [],
+          priorUnresolved: input.priorUnresolved ?? [],
+          currentReport: report,
+        })
+      : [],
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Derive next slice
+// ---------------------------------------------------------------------------
+
+export function deriveNextSlice(input: {
+  report: ReturnReport;
+  contract: ProjectContract;
+  gateState: GateState;
+  delta: CanonicalDelta;
+  /** Whether the delta's changed_files actually exist in the repo. Default true. */
+  repoGrounded?: boolean;
+}): NextSlice {
+  const { report, contract, gateState, delta } = input;
+  const repoGrounded = input.repoGrounded ?? true;
+
+  // Title — residual-aware: if partial, derive from unresolved items, not just recommended_next_step
+  const rawNext = report.recommended_next_step || "Continue implementation.";
+  const isPartial = report.objective_met === "partial" || report.objective_met === "no";
+
+  let title: string;
+  if (isPartial && delta.unresolved.length > 0) {
+    // Derive title from the first unresolved item (the most urgent residual)
+    const firstUnresolved = delta.unresolved[0]!.replace(/^Blocker:\s*/i, "").replace(/^Escalation:\s*/i, "");
+    title = firstUnresolved.length > 60 ? firstUnresolved.slice(0, 57) + "…" : firstUnresolved;
+  } else {
+    title = rawNext.length > 60 ? rawNext.slice(0, 57) + "…" : rawNext;
+  }
+
+  // Rationale — residual-aware, grounded in what was just done
+  let rationale: string;
+  if (report.status === "done" && report.objective_met === "yes") {
+    // Build a specific rationale explaining why the next step follows from the completed work
+    const systemsSummary = delta.systems_touched.length > 0
+      ? delta.systems_touched.join(", ")
+      : "the implementation";
+    const evidenceSummary =
+      delta.verification_runs.length > 0 && delta.evidence_items.length > 0
+        ? `${delta.verification_runs.length} verification run(s), ${delta.evidence_items.length} evidence item(s)`
+        : delta.verification_runs.length > 0
+          ? `${delta.verification_runs.length} verification run(s)`
+          : delta.evidence_items.length > 0
+            ? `${delta.evidence_items.length} evidence item(s)`
+            : "execution returned clean";
+    const fileScope = delta.file_changes.length > 0
+      ? `${delta.file_changes.length} file(s) changed across ${systemsSummary}`
+      : `work completed in ${systemsSummary}`;
+
+    // Detect what scope the evidence covers — local/schema vs staging vs production
+    const allEvidence = [...delta.verification_runs, ...delta.evidence_items].map(e => e.toLowerCase());
+    const hasStaging = allEvidence.some(e => /staging|hosted|deployed|push.*linked|production.*schema/i.test(e));
+    const hasProduction = allEvidence.some(e => /production(?!.*schema)/i.test(e));
+    const verificationScope = hasProduction ? "production-verified" : hasStaging ? "staging-verified" : "local/schema-validated";
+
+    rationale = `Previous slice completed: ${fileScope}, ${evidenceSummary}. The next step advances from ${verificationScope} state to ${rawNext.length > 80 ? rawNext.slice(0, 77) + "…" : rawNext}.`;
+  } else if (isPartial && delta.unresolved.length > 0) {
+    rationale = `Previous slice partially met its objective. ${delta.unresolved.length} residual item(s) carry forward as the next bounded scope.`;
+  } else if (report.status === "partial") {
+    rationale = "Previous slice partially completed. This continues the remaining work.";
+  } else if (report.status === "blocked") {
+    rationale = "Previous slice blocked. This addresses the blocking issue.";
+  } else {
+    rationale = "Derived from the execution return's recommendation.";
+  }
+
+  // Scope — residual-aware: include each unresolved item as a concrete scope line
+  const scope: string[] = [];
+  if (isPartial && delta.unresolved.length > 0) {
+    for (const u of delta.unresolved) {
+      const clean = u.replace(/^Blocker:\s*/i, "").replace(/^Escalation:\s*/i, "");
+      scope.push(clean);
+    }
+  } else {
+    scope.push(rawNext);
+  }
+  if (delta.cautions.length > 0 && scope.length < 5) {
+    scope.push(`Address ${delta.cautions.length} caution(s) from previous run.`);
+  }
+
+  // Systems likely touched
+  const systems_likely = delta.systems_touched.length > 0 ? delta.systems_touched : ["Same systems as previous slice"];
+
+  // Ready for dispatch?
+  const hasBlockers = delta.unresolved.length > 0;
+  const hasViolations = delta.boundaries_violated.length > 0;
+  const gateBlocking = gateState.label === "held-for-review" || gateState.label === "blocked-missing-evidence";
+  const simulationHold = !repoGrounded && delta.file_changes.length > 0;
+
+  const ready_for_dispatch = !hasBlockers && !hasViolations && !gateBlocking && !simulationHold;
+  let review_reason = "";
+  if (!ready_for_dispatch) {
+    const reasons: string[] = [];
+    if (simulationHold) reasons.push("Execution was simulated — changed files are not repo-grounded. Re-run against real repo before dispatch.");
+    if (hasBlockers) reasons.push(`${delta.unresolved.length} unresolved item(s)`);
+    if (hasViolations) reasons.push(`${delta.boundaries_violated.length} boundary violation(s)`);
+    if (gateBlocking) reasons.push(`Gate: ${gateState.label}`);
+    review_reason = reasons.join(". ") + ".";
+  }
+
+  // Surface the most critical unresolved blocker
+  const unresolved_blocker = delta.unresolved.length > 0
+    ? delta.unresolved[0]!.replace(/^Blocker:\s*/i, "").replace(/^Escalation:\s*/i, "")
+    : "";
+
+  // Surface key assumption: if objective was partial or there are boundary violations
+  let assumption = "";
+  if (simulationHold) {
+    assumption = "Execution was simulated — changed files are fixtures, not repo-grounded. Real repo grounding required before dispatch.";
+  } else if (report.objective_met === "partial") {
+    assumption = "Previous slice only partially met its objective — remaining work may need adjustment.";
+  } else if (delta.boundaries_violated.length > 0) {
+    assumption = `Boundary violation(s) may constrain the next slice: ${delta.boundaries_violated[0]}.`;
+  } else if (report.status === "blocked") {
+    assumption = "Previous slice was blocked — the blocker must be resolved before dispatch.";
+  }
+
+  // Status lifecycle
+  let status: "draft" | "ready" | "held" | "blocked" = "draft";
+  if (ready_for_dispatch) {
+    status = "ready";
+  } else if (simulationHold) {
+    status = "held";
+  } else if (gateBlocking) {
+    status = gateState.label === "held-for-review" ? "held" : "blocked";
+  } else if (hasBlockers || hasViolations) {
+    status = "blocked";
+  }
+
+  // Required inputs — what must be resolved before dispatch
+  const required_inputs: string[] = [];
+  if (hasBlockers) {
+    for (const u of delta.unresolved) required_inputs.push(u);
+  }
+  if (hasViolations) {
+    for (const v of delta.boundaries_violated) required_inputs.push(`Resolve boundary: ${v}`);
+  }
+
+  // Expected evidence — what the next slice should prove
+  const expected_evidence: string[] = [];
+  if (report.status === "partial") {
+    expected_evidence.push("Completion of remaining work from previous slice.");
+  }
+  if (report.verification_run.length > 0) {
+    expected_evidence.push("Verification checks pass (same or equivalent).");
+  }
+  expected_evidence.push("Evidence of implementation attached.");
+
+  // Open dependencies
+  const open_dependencies = delta.unresolved.filter(Boolean);
+
+  return nextSliceSchema.parse({
+    // Identity & lineage
+    slice_id: `slice-${randomBytes(8).toString("hex")}`,
+    project_id: contract.project_id,
+    parent_contract_id: contract.project_id,
+    parent_delta_id: delta.delta_id,
+    created_from: "absorbed-return",
+    created_at: new Date().toISOString(),
+
+    // Core
+    title,
+    objective: isPartial && delta.unresolved.length > 0
+      ? `Resolve ${delta.unresolved.length} residual item(s) from partial run: ${scope.slice(0, 2).join("; ")}`
+      : rawNext,
+    why_next: rationale,
+    status,
+    dispatch_ready: ready_for_dispatch,
+
+    // Context
+    scope,
+    systems_in_play: systems_likely,
+    required_inputs,
+    expected_evidence,
+    open_dependencies,
+    blocking_reason: review_reason,
+
+    // Legacy compat
+    rationale,
+    systems_likely,
+    ready_for_dispatch,
+    review_reason,
+    unresolved_blocker,
+    assumption,
+  });
+}
+
+// ---------------------------------------------------------------------------
+// UI-facing delta summary — structured counts + concise display
+// ---------------------------------------------------------------------------
+
+export type DeltaUISummary = {
+  file_count: number;
+  artifact_count: number;
+  test_count: number;
+  test_pass_count: number;
+  evidence_count: number;
+  system_count: number;
+  systems: string[];
+  preserved_boundary_count: number;
+  violated_boundary_count: number;
+  caution_count: number;
+  unresolved_count: number;
+  objective_state: string;
+  gate_state: string;
+  headline: string;
+  preserved_summary: string;
+  unresolved_summary: string;
+};
+
+export function deriveDeltaUISummary(delta: CanonicalDelta): DeltaUISummary {
+  const file_count = delta.file_changes.length;
+  const artifact_count = delta.artifact_changes.length;
+  const test_count = delta.tests_or_checks.length;
+  const test_pass_count = delta.tests_or_checks.filter(t => t.passed).length;
+  const evidence_count = delta.evidence_items.length;
+  const system_count = delta.systems_touched.length;
+  const preserved_boundary_count = delta.boundaries_preserved.length;
+  const violated_boundary_count = delta.boundaries_violated.length;
+  const caution_count = delta.cautions.length;
+  const unresolved_count = delta.unresolved.length;
+
+  // Headline
+  const parts: string[] = [];
+  if (file_count > 0) parts.push(`${file_count} file(s)`);
+  else parts.push("No files changed");
+  if (system_count > 0) parts.push(`across ${delta.systems_touched.join(", ")}`);
+  if (test_count > 0) parts.push(`${test_pass_count}/${test_count} check(s) passed`);
+  if (evidence_count > 0) parts.push(`${evidence_count} evidence`);
+  const headline = parts.join(". ") + ".";
+
+  // Preserved summary
+  const preserved_summary = preserved_boundary_count > 0
+    ? `${preserved_boundary_count} boundary(s) preserved: ${delta.boundaries_preserved.slice(0, 3).join(", ")}`
+    : "No boundaries to preserve.";
+
+  // Unresolved summary
+  const unresolved_summary = unresolved_count > 0
+    ? `${unresolved_count} item(s): ${delta.unresolved.slice(0, 3).join("; ")}`
+    : "Nothing unresolved.";
+
+  return {
+    file_count,
+    artifact_count,
+    test_count,
+    test_pass_count,
+    evidence_count,
+    system_count,
+    systems: delta.systems_touched,
+    preserved_boundary_count,
+    violated_boundary_count,
+    caution_count,
+    unresolved_count,
+    objective_state: delta.objective_state,
+    gate_state: delta.gate_state,
+    headline,
+    preserved_summary,
+    unresolved_summary,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Activation-path next slice — created when a project is first compiled
+// ---------------------------------------------------------------------------
+
+export function deriveNextSliceFromActivation(input: {
+  contract: ProjectContract;
+  seed: { first_build_slice: string; confidence: string; missing_inputs: string[]; open_questions: string[] };
+  systems: string[];
+  currentObjective: string;
+}): NextSlice {
+  const { contract, seed, systems, currentObjective } = input;
+
+  const title = seed.first_build_slice || currentObjective || "First bounded implementation slice.";
+  const objective = currentObjective || seed.first_build_slice || contract.desired_v1_outcome;
+
+  const hasMissing = seed.missing_inputs.filter(Boolean).length > 0;
+  const lowConfidence = seed.confidence === "low";
+
+  let status: "draft" | "ready" | "held" | "blocked" = "ready";
+  let blocking_reason = "";
+  if (hasMissing) {
+    status = "blocked";
+    blocking_reason = `${seed.missing_inputs.length} missing input(s) must be resolved.`;
+  } else if (lowConfidence) {
+    status = "held";
+    blocking_reason = "Low confidence — review intent before dispatch.";
+  }
+
+  const required_inputs = seed.missing_inputs.filter(Boolean);
+  const open_dependencies = seed.open_questions.filter(Boolean);
+
+  return nextSliceSchema.parse({
+    slice_id: `slice-${randomBytes(8).toString("hex")}`,
+    project_id: contract.project_id,
+    parent_contract_id: contract.project_id,
+    parent_delta_id: "",
+    created_from: "activation",
+    created_at: new Date().toISOString(),
+
+    title,
+    objective,
+    why_next: "This is the first bounded slice derived from project activation.",
+    status,
+    dispatch_ready: status === "ready",
+
+    scope: [title],
+    systems_in_play: systems,
+    required_inputs,
+    expected_evidence: ["Implementation evidence attached.", "Verification checks pass."],
+    open_dependencies,
+    blocking_reason,
+
+    // Legacy compat
+    rationale: "First slice from activation.",
+    systems_likely: systems,
+    ready_for_dispatch: status === "ready",
+    review_reason: blocking_reason,
+    unresolved_blocker: required_inputs[0] ?? "",
+    assumption: lowConfidence ? "Low confidence — intent may need refinement." : "",
+  });
+}