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

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

@@ -1,317 +0,0 @@
-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

@@ -1,221 +0,0 @@
-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");
-}