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

package/node_modules/@switchboard/core/src/governance-envelope.ts

@@ -0,0 +1,317 @@
+import type {
+  ActivationState,
+  Assumption,
+  ClosureRecord,
+  ComplexityClassification,
+  GateOutcome,
+  GovernanceEnvelope,
+  NextSlice,
+  ReconcileReport,
+  ReturnReport,
+  SynthesizedSeed,
+} from "./types";
+import { closureRecordSchema, governanceEnvelopeSchema } from "./types";
+import { deriveControlFlags } from "./run-snapshot";
+import { randomBytes } from "crypto";
+
+// ---------------------------------------------------------------------------
+// Activation state — driven by assumption risk
+// ---------------------------------------------------------------------------
+
+export function deriveActivationState(input: {
+  seed: SynthesizedSeed;
+  complexity: ComplexityClassification | null;
+  assumptions?: Assumption[];
+  hasSpec: boolean;
+  hasSurface: boolean;
+  hasActiveHandoff: boolean;
+}): { state: ActivationState; blockers: string[] } {
+  const { seed, complexity, assumptions, hasSpec, hasSurface, hasActiveHandoff } = input;
+  const blockers: string[] = [];
+
+  // Already dispatched → locked
+  if (hasActiveHandoff) {
+    return { state: "locked", blockers: [] };
+  }
+
+  // Governance mode → blocked (scope too broad)
+  if (complexity?.mode === "governance") {
+    blockers.push(`Scope too broad for implementation: ${complexity.rationale}`);
+    return { state: "blocked_by_missing_evidence", blockers };
+  }
+
+  // High-risk missing inputs → blocked
+  const highRiskAssumptions = (assumptions ?? []).filter(
+    a => a.status === "unconfirmed" && a.risk_level === "high"
+  );
+  if (highRiskAssumptions.length > 0) {
+    for (const a of highRiskAssumptions) {
+      blockers.push(a.text);
+    }
+    return { state: "blocked_by_missing_evidence", blockers };
+  }
+
+  // Seed missing inputs → blocked
+  if (seed.missing_inputs.filter(Boolean).length > 0) {
+    for (const m of seed.missing_inputs.filter(Boolean)) {
+      blockers.push(m);
+    }
+    return { state: "blocked_by_missing_evidence", blockers };
+  }
+
+  // Low confidence → held for review
+  if (seed.confidence === "low") {
+    blockers.push("Low confidence in extracted intent — review before locking.");
+    return { state: "held_for_review", blockers };
+  }
+
+  // Medium-risk unconfirmed assumptions → held
+  const medRiskUnconfirmed = (assumptions ?? []).filter(
+    a => a.status === "unconfirmed" && a.risk_level === "medium"
+  );
+  if (medRiskUnconfirmed.length > 0) {
+    for (const a of medRiskUnconfirmed) {
+      blockers.push(a.text);
+    }
+    return { state: "held_for_review", blockers };
+  }
+
+  // Ready but no spec or surface yet → held
+  if (!hasSpec || !hasSurface) {
+    blockers.push("Spec or routing surface not yet determined.");
+    return { state: "held_for_review", blockers };
+  }
+
+  return { state: "ready_to_lock", blockers: [] };
+}
+
+// ---------------------------------------------------------------------------
+// Gate outcome — maps from existing gate labels
+// ---------------------------------------------------------------------------
+
+function mapGateLabel(label: string): GateOutcome {
+  switch (label) {
+    case "accepted": return "accepted";
+    case "accepted-with-cautions": return "accepted_with_cautions";
+    case "held-for-review": return "held_for_review";
+    case "blocked-missing-evidence": return "blocked_by_missing_evidence";
+    // Pre-decision states — do NOT collapse into post-decision semantics
+    case "pending": return "pending_reconcile";
+    case "not-checked": return "not_evaluated";
+    default: return "not_evaluated";
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Derive full governance envelope
+// ---------------------------------------------------------------------------
+
+export function deriveGovernanceEnvelope(input: {
+  // Activation context
+  seed: SynthesizedSeed;
+  complexity: ComplexityClassification | null;
+  assumptions?: Assumption[];
+  hasSpec: boolean;
+  hasSurface: boolean;
+  hasActiveHandoff: boolean;
+
+  // Post-return context (null if no return yet)
+  reconcile: ReconcileReport | null;
+  latestReturn: ReturnReport | null;
+  gateLabel: string; // from deriveGateState().label
+
+  // Closure
+  closureRecord: ClosureRecord | null;
+}): GovernanceEnvelope {
+  const {
+    seed, complexity, assumptions, hasSpec, hasSurface, hasActiveHandoff,
+    reconcile, latestReturn, gateLabel, closureRecord,
+  } = input;
+
+  // Activation (avoid passing `assumptions: undefined` — exactOptionalPropertyTypes distinguishes absent vs undefined)
+  const { state: activation_state, blockers: activation_blockers } = deriveActivationState({
+    seed,
+    complexity,
+    hasSpec,
+    hasSurface,
+    hasActiveHandoff,
+    ...(assumptions !== undefined ? { assumptions } : {}),
+  });
+
+  // Gate outcome
+  const gate_state = latestReturn ? mapGateLabel(gateLabel) : null;
+  const gate_reason = latestReturn ? (gateLabel || "No gate state derived.") : "";
+
+  // Structured counts — directly from source arrays, never from prose
+  const reconcileFindings = reconcile?.findings ?? [];
+  const scopeCheckFindings = reconcileFindings.filter(f =>
+    ["scope-inflation", "non-goal-violation", "goal-drift", "target-user-shift"].includes(f.category)
+  );
+  const scope_check_count = reconcile ? reconcile.checked_count : 0;
+  const scope_check_caution_count = scopeCheckFindings.filter(f => f.severity === "warning").length;
+  const return_caution_count = reconcileFindings.filter(f => f.severity === "warning").length;
+  const verification_run_count = latestReturn?.verification_run.length ?? 0;
+  const evidence_item_count = latestReturn?.evidence.length ?? 0;
+
+  // Blockers — review-required findings + return blockers
+  const blockers: string[] = [];
+  for (const f of reconcileFindings.filter(f => f.severity === "review-required")) {
+    blockers.push(`[reconcile] ${f.description}`);
+  }
+  if (latestReturn) {
+    for (const b of latestReturn.blockers.filter(Boolean)) {
+      blockers.push(`[return] ${b}`);
+    }
+  }
+
+  // Cautions — warning findings
+  const cautions: string[] = [];
+  for (const f of reconcileFindings.filter(f => f.severity === "warning")) {
+    cautions.push(`[reconcile] ${f.description}`);
+  }
+  if (latestReturn) {
+    for (const e of latestReturn.escalations.filter(Boolean)) {
+      cautions.push(`[return] ${e}`);
+    }
+  }
+
+  // Unresolved items — blockers + escalations + partial objective
+  const unresolved_items: string[] = [];
+  if (latestReturn) {
+    for (const b of latestReturn.blockers.filter(Boolean)) unresolved_items.push(b);
+    for (const e of latestReturn.escalations.filter(Boolean)) unresolved_items.push(e);
+    if (latestReturn.objective_met === "partial") {
+      unresolved_items.push("Objective only partially met.");
+    }
+    if (latestReturn.objective_met === "no") {
+      unresolved_items.push("Objective not met.");
+    }
+  }
+
+  // Objective state
+  let objective_state: "met" | "partial" | "unmet" | "not_started" = "not_started";
+  if (latestReturn) {
+    if (latestReturn.objective_met === "yes") objective_state = "met";
+    else if (latestReturn.objective_met === "partial") objective_state = "partial";
+    else objective_state = "unmet";
+  }
+
+  // Control flags
+  // Control flags — use shared logic (same as RunSnapshot)
+  // Map gate outcome to RunPhase equivalent for shared derivation
+  const phaseForFlags = gate_state === "accepted" ? "accepted" as const
+    : gate_state === "accepted_with_cautions" ? "accepted_with_cautions" as const
+    : gate_state === "held_for_review" ? "held_for_review" as const
+    : gate_state === "blocked_by_missing_evidence" ? "blocked" as const
+    : gate_state === "pending_reconcile" ? "return_received" as const
+    : gate_state === "not_evaluated" ? "ready_to_lock" as const
+    : latestReturn ? "return_received" as const
+    : "ready_to_lock" as const;
+  const { stateAdvanceAllowed: state_advance_allowed, closureAllowed: closure_allowed } = deriveControlFlags(phaseForFlags, !!latestReturn);
+
+  return governanceEnvelopeSchema.parse({
+    activation_state,
+    activation_blockers,
+    gate_state,
+    gate_reason,
+    blockers,
+    cautions,
+    unresolved_items,
+    scope_check_count,
+    scope_check_caution_count,
+    return_caution_count,
+    verification_run_count,
+    evidence_item_count,
+    objective_state,
+    state_advance_allowed,
+    closure_allowed,
+    closure_state: closureRecord,
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Build closure record
+// ---------------------------------------------------------------------------
+
+/**
+ * Build closure record — SEAL phase.
+ *
+ * Sealed facts are immutable after this call.
+ * Feedback is appended metadata only.
+ */
+export function buildClosureRecord(input: {
+  gateLabel: string;
+  cautions: string[];
+  unresolved: string[];
+  objectiveMet: string;
+  feedback: Record<string, unknown>;
+  nextSlice?: NextSlice | null;
+  projectId?: string;
+  returnId?: string;
+  deltaId?: string;
+  dispatchId?: string;
+  hasReturn?: boolean;
+}): ClosureRecord {
+  const gate_outcome = mapGateLabel(input.gateLabel);
+
+  let objective_state: "met" | "partial" | "unmet";
+  if (input.objectiveMet === "yes") objective_state = "met";
+  else if (input.objectiveMet === "partial") objective_state = "partial";
+  else objective_state = "unmet";
+
+  // Seal integrity — verify that if we have a return, we captured whatever was on record
+  let seal_integrity: "verified" | "snapshot_empty" | "no_return" = "verified";
+  if (!input.hasReturn && input.hasReturn !== undefined) {
+    seal_integrity = "no_return";
+  } else if (
+    input.cautions.length === 0 && input.unresolved.length === 0 &&
+    input.gateLabel !== "accepted" && input.gateLabel !== "accepted-with-cautions"
+  ) {
+    // Gate says held/blocked but we captured no cautions or unresolved — something may be wrong.
+    // accepted-with-cautions is valid with 0/0 when the gate was pressure/audit-tightened.
+    seal_integrity = "snapshot_empty";
+  }
+
+  const now = new Date().toISOString();
+
+  return closureRecordSchema.parse({
+    closure_id: `cls-${randomBytes(8).toString("hex")}`,
+    project_id: input.projectId ?? "",
+    return_id: input.returnId ?? "",
+    delta_id: input.deltaId ?? "",
+    dispatch_id: input.dispatchId ?? "",
+
+    // Sealed facts
+    sealed_at: now,
+    gate_outcome,
+    cautions_at_close: input.cautions,
+    unresolved_at_close: input.unresolved,
+    objective_state,
+    next_slice_at_close: input.nextSlice ?? null,
+    seal_integrity,
+
+    // Appended metadata
+    feedback_appended_at: now,
+    feedback_snapshot: input.feedback,
+
+    // Legacy compat
+    closed_at: now,
+  });
+}
+
+/**
+ * Append metadata to an existing closure record.
+ * NEVER revises sealed facts — only updates feedback fields.
+ */
+export function appendClosureMetadata(
+  existing: ClosureRecord,
+  metadata: Record<string, unknown>,
+): ClosureRecord {
+  return closureRecordSchema.parse({
+    ...existing,
+    // Sealed facts PRESERVED — not overwritten
+    feedback_appended_at: new Date().toISOString(),
+    feedback_snapshot: { ...existing.feedback_snapshot, ...metadata },
+    // sealed_at, gate_outcome, cautions_at_close, unresolved_at_close UNTOUCHED
+  });
+}

package/node_modules/@switchboard/core/src/handoff-v2.ts

@@ -0,0 +1,221 @@
+import type {
+  EventContext,
+  HandoffContractV2,
+  HandoffPreflightResult,
+  LoopContract,
+  ProcessMode,
+  ProjectContract,
+  RunEvent,
+  RunEventKind,
+  RunHistory,
+  RunToken,
+  Surface,
+} from "./types";
+import { handoffContractV2Schema, handoffPreflightResultSchema, runHistorySchema } from "./types";
+import { randomBytes } from "crypto";
+
+// ---------------------------------------------------------------------------
+// Run token generation
+// ---------------------------------------------------------------------------
+
+export function generateRunToken(specGeneration: number): RunToken {
+  return {
+    token: `rt-${randomBytes(12).toString("hex")}`,
+    spec_generation: specGeneration,
+    created_at: new Date().toISOString(),
+    contract_version: "v2",
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Handoff Contract V2 creation
+// ---------------------------------------------------------------------------
+
+export function createHandoffContractV2(input: {
+  contract: ProjectContract;
+  loop: LoopContract;
+  surface: Surface;
+  fallbackSurface: Surface;
+  processMode: ProcessMode;
+  specGeneration: number;
+  canonicalSnapshotRef?: string;
+}): HandoffContractV2 {
+  const runToken = generateRunToken(input.specGeneration);
+
+  return handoffContractV2Schema.parse({
+    contract_version: "v2",
+    run_token: runToken,
+    spec_generation: input.specGeneration,
+    canonical_snapshot_ref: input.canonicalSnapshotRef ?? "",
+    intent: {
+      objective: input.loop.objective,
+      scope_in: input.loop.scope_in,
+      scope_out: input.loop.scope_out,
+      non_goals: input.contract.non_goals,
+    },
+    constraints: {
+      done_when: input.loop.done_when,
+      success_criteria: input.loop.success_criteria,
+      verify_with: input.loop.verify_with,
+      blocker_escalation: input.loop.blocker_escalation,
+      return_when: input.loop.return_when,
+    },
+    context: {
+      surface: input.surface,
+      fallback_surface: input.fallbackSurface,
+      execution_shape: input.loop.execution_shape,
+      process_mode: input.processMode,
+    },
+    return_expectations: {
+      required_fields: [
+        "status", "objective_met", "done_when_met", "summary",
+        "changed_files", "decisions_made", "evidence",
+        "recommended_next_step",
+      ],
+      must_reference_token: true,
+      must_match_generation: true,
+    },
+    dispatch_state: "queued",
+    created_at: new Date().toISOString(),
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Dispatch state transitions
+// ---------------------------------------------------------------------------
+
+export function advanceDispatchState(
+  contract: HandoffContractV2,
+  newState: HandoffContractV2["dispatch_state"],
+): HandoffContractV2 {
+  return handoffContractV2Schema.parse({ ...contract, dispatch_state: newState });
+}
+
+// ---------------------------------------------------------------------------
+// Run token validation
+// ---------------------------------------------------------------------------
+
+export function validateRunToken(
+  contract: HandoffContractV2,
+  returnToken: string,
+  returnGeneration: number,
+): { valid: boolean; reason: string } {
+  if (returnToken !== contract.run_token.token) {
+    return { valid: false, reason: `Token mismatch: expected ${contract.run_token.token}, got ${returnToken}.` };
+  }
+  if (returnGeneration !== contract.spec_generation) {
+    return { valid: false, reason: `Generation mismatch: expected ${contract.spec_generation}, got ${returnGeneration}. Spec may have changed during execution.` };
+  }
+  return { valid: true, reason: "Token and generation match." };
+}
+
+// ---------------------------------------------------------------------------
+// Preflight
+// ---------------------------------------------------------------------------
+
+export function preflightContract(contract: HandoffContractV2): HandoffPreflightResult {
+  const blockers: string[] = [];
+  const warnings: string[] = [];
+
+  if (!contract.intent.objective) blockers.push("Objective is missing.");
+  if (contract.intent.scope_in.length === 0) blockers.push("Scope-in is empty.");
+  if (contract.constraints.done_when.length === 0) blockers.push("Done-when is empty.");
+  if (contract.constraints.success_criteria.length === 0) blockers.push("Success criteria are empty.");
+  if (!contract.run_token.token) blockers.push("Run token is missing.");
+
+  if (contract.intent.scope_out.length === 0) warnings.push("Scope-out is empty — no explicit exclusions.");
+  if (contract.intent.non_goals.length === 0) warnings.push("Non-goals are empty — no boundary anchors.");
+  if (contract.constraints.verify_with.length === 0) warnings.push("Verify-with is empty — no verification plan.");
+
+  return handoffPreflightResultSchema.parse({ ready: blockers.length === 0, blockers, warnings });
+}
+
+// ---------------------------------------------------------------------------
+// Append-only run history
+// ---------------------------------------------------------------------------
+
+let _evtCtr = 0;
+function eventId(): string { return `evt-${++_evtCtr}-${Date.now().toString(36)}`; }
+
+export function createRunHistory(projectId: string): RunHistory {
+  return runHistorySchema.parse({ events: [], project_id: projectId });
+}
+
+export function appendEvent(
+  history: RunHistory,
+  kind: RunEventKind,
+  detail?: string,
+  runToken?: string,
+  specGeneration?: number,
+  metadata?: Record<string, unknown>,
+  context?: Partial<EventContext>,
+): RunHistory {
+  const event: RunEvent = {
+    id: eventId(),
+    kind,
+    timestamp: new Date().toISOString(),
+    detail: detail ?? "",
+    ...(runToken ? { run_token: runToken } : {}),
+    ...(specGeneration !== undefined ? { spec_generation: specGeneration } : {}),
+    context: {
+      contract_ref: context?.contract_ref ?? "",
+      handoff_id: context?.handoff_id ?? "",
+      dispatch_id: context?.dispatch_id ?? "",
+      return_id: context?.return_id ?? "",
+      delta_id: context?.delta_id ?? "",
+      next_slice_id: context?.next_slice_id ?? "",
+      closure_id: context?.closure_id ?? "",
+      surface: context?.surface ?? "",
+      gate_label: context?.gate_label ?? "",
+      delta_summary: context?.delta_summary ?? "",
+      evidence_summary: context?.evidence_summary ?? "",
+      next_action: context?.next_action ?? "",
+    },
+    metadata: metadata ?? {},
+  };
+  return runHistorySchema.parse({
+    ...history,
+    events: [...history.events, event],
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Late / mismatched return handling
+// ---------------------------------------------------------------------------
+
+export function handleReturnWithToken(
+  contract: HandoffContractV2,
+  returnToken: string,
+  returnGeneration: number,
+): { accepted: boolean; reason: string; store_as: "merge" | "evidence" | "reject" } {
+  const validation = validateRunToken(contract, returnToken, returnGeneration);
+
+  if (validation.valid) {
+    return { accepted: true, reason: "Valid return.", store_as: "merge" };
+  }
+
+  // Token mismatch → reject (wrong execution)
+  if (!validation.reason.includes("Generation")) {
+    return { accepted: false, reason: validation.reason, store_as: "reject" };
+  }
+
+  // Generation mismatch → store as evidence (stale but potentially useful)
+  return { accepted: false, reason: validation.reason, store_as: "evidence" };
+}
+
+// ---------------------------------------------------------------------------
+// Human-readable run ledger summary
+// ---------------------------------------------------------------------------
+
+export function renderRunSummary(history: RunHistory): string {
+  if (history.events.length === 0) return "No events recorded.";
+
+  const lines: string[] = [];
+  for (const evt of history.events) {
+    const time = evt.timestamp.split("T")[1]?.split(".")[0] ?? "";
+    const token = evt.run_token ? ` [${evt.run_token.slice(0, 10)}…]` : "";
+    const gen = evt.spec_generation !== undefined ? ` gen:${evt.spec_generation}` : "";
+    lines.push(`${time} ${evt.kind}${token}${gen}${evt.detail ? ` — ${evt.detail}` : ""}`);
+  }
+  return lines.join("\n");
+}