switchboard-cli 0.1.0-alpha.2 → 0.1.0-alpha.4

package/node_modules/@switchboard/core/src/audited-receipt.ts

@@ -1,403 +0,0 @@
-import { randomBytes } from "crypto";
-import type {
-  AuditedReceipt,
-  AuditResult,
-  CanonicalDelta,
-  ClaimAssessment,
-  ClaimDisposition,
-  GateState,
-  NextSlice,
-  NormalizedReturnEnvelope,
-  TrustPosture,
-} from "./types";
-import { auditedReceiptSchema } from "./types";
-import { deriveControlFlags } from "./run-snapshot";
-import type { TraceSummary } from "./execution-trace";
-import type { BudgetSummary } from "./budget-ledger";
-import type { OverflowSummary } from "./types";
-
-// ---------------------------------------------------------------------------
-// Audited Receipt — the official product-level receipt
-// ---------------------------------------------------------------------------
-//
-// The audited receipt is what the system trusts. It is built from:
-//   - NormalizedReturnEnvelope (what the agent claimed)
-//   - CanonicalDelta (what actually changed, with evidence accounting)
-//   - GateState (the gate's verdict on the evidence)
-//   - NextSlice (what comes next, if anything)
-//
-// It explicitly distinguishes:
-//   - what was claimed
-//   - what was actually proven
-//   - what remains partial / inferred / weak
-//   - what cautions and residuals carry forward
-//   - whether closure is allowed
-//   - whether canonical state advanced, and on what basis
-// ---------------------------------------------------------------------------
-
-export interface BuildAuditedReceiptInput {
-  envelope: NormalizedReturnEnvelope;
-  delta: CanonicalDelta;
-  gate: GateState;
-  nextSlice: NextSlice | null;
-  projectId?: string;
-  /** Audit result, when available. Feeds explicit audit findings onto the receipt. */
-  audit?: AuditResult | null;
-  /** Trace summary from execution-trace module, when available. */
-  traceSummary?: TraceSummary | null;
-  /** Budget summary from budget-ledger module, when available. */
-  budgetSummary?: BudgetSummary | null;
-  /** Overflow summary from overflow-manifest module, when available. */
-  overflowSummary?: OverflowSummary | null;
-}
-
-// ---------------------------------------------------------------------------
-// Claim assessment — classifies each significant claim by evidence strength
-// ---------------------------------------------------------------------------
-
-function assessClaims(
-  envelope: NormalizedReturnEnvelope,
-  delta: CanonicalDelta,
-): ClaimAssessment[] {
-  const assessments: ClaimAssessment[] = [];
-
-  // Pool of structured evidence for matching
-  const verificationPool = new Set(
-    delta.verification_runs.map(v => v.toLowerCase()),
-  );
-  const evidencePool = new Set(
-    delta.evidence_items.map(e => e.toLowerCase()),
-  );
-  const criteriaPool = new Set(
-    (delta.evidence_accounting?.criteria_met ?? []).map(c => c.toLowerCase()),
-  );
-
-  function classify(text: string): { disposition: ClaimDisposition; basis: string } {
-    const lower = text.toLowerCase();
-    const words = lower.split(/\s+/).filter(w => w.length > 3);
-    const fullMatchThreshold = words.length <= 2 ? 1 : 2;
-
-    // Track best partial match across all pools for fallback to "partial"
-    let bestPartialLine = "";
-    let bestPartialScore = 0;
-    let bestPartialPool = "";
-
-    // Check verification runs
-    for (const v of verificationPool) {
-      const matchCount = words.filter(w => v.includes(w)).length;
-      if (matchCount >= fullMatchThreshold) {
-        return { disposition: "proven", basis: `Matched verification: ${v.slice(0, 80)}` };
-      }
-      if (matchCount > bestPartialScore) {
-        bestPartialScore = matchCount;
-        bestPartialLine = v;
-        bestPartialPool = "verification";
-      }
-    }
-
-    // Check evidence items
-    for (const e of evidencePool) {
-      const matchCount = words.filter(w => e.includes(w)).length;
-      if (matchCount >= fullMatchThreshold) {
-        return { disposition: "supported", basis: `Matched evidence: ${e.slice(0, 80)}` };
-      }
-      if (matchCount > bestPartialScore) {
-        bestPartialScore = matchCount;
-        bestPartialLine = e;
-        bestPartialPool = "evidence";
-      }
-    }
-
-    // Check criteria met
-    for (const c of criteriaPool) {
-      const matchCount = words.filter(w => c.includes(w)).length;
-      if (matchCount >= fullMatchThreshold) {
-        return { disposition: "supported", basis: `Matched criterion: ${c.slice(0, 80)}` };
-      }
-      if (matchCount > bestPartialScore) {
-        bestPartialScore = matchCount;
-        bestPartialLine = c;
-        bestPartialPool = "criterion";
-      }
-    }
-
-    // Partial: at least 1 keyword matched but not enough for full supported/proven
-    if (bestPartialScore >= 1) {
-      return {
-        disposition: "partial",
-        basis: `Partial ${bestPartialPool} match (${bestPartialScore}/${words.length} keywords): ${bestPartialLine.slice(0, 80)}`,
-      };
-    }
-
-    // Content mode from envelope — inferred items get "inferred" disposition
-    const envelopeItem = envelope.evidence_items.find(
-      ei => ei.text.toLowerCase() === lower,
-    );
-    if (envelopeItem && (envelopeItem.content_mode === "inferred" || envelopeItem.content_mode === "reconstructed")) {
-      return { disposition: "inferred", basis: `Content mode: ${envelopeItem.content_mode}` };
-    }
-
-    return { disposition: "unsubstantiated", basis: "No matching structured evidence found." };
-  }
-
-  // Assess the summary claim (the primary output statement)
-  if (envelope.summary) {
-    const result = classify(envelope.summary);
-    assessments.push({ claim: envelope.summary, ...result });
-  }
-
-  // Assess each success criterion claimed
-  for (const criterion of envelope.criteria_met) {
-    const result = classify(criterion.text);
-    assessments.push({ claim: criterion.text, ...result });
-  }
-
-  // Assess each decision made
-  for (const decision of envelope.decisions) {
-    const result = classify(decision.text);
-    assessments.push({ claim: decision.text, ...result });
-  }
-
-  return assessments;
-}
-
-// ---------------------------------------------------------------------------
-// Trust posture — overall trust level derived from gate + evidence + residuals
-// ---------------------------------------------------------------------------
-
-function deriveTrustPosture(
-  gate: GateState,
-  residualCount: number,
-): { posture: TrustPosture; basis: string } {
-  switch (gate.label) {
-    case "accepted":
-      if (residualCount === 0) {
-        return {
-          posture: "verified",
-          basis: `Gate accepted. ${gate.evidence_summary.verification_count} verification(s), ${gate.evidence_summary.evidence_count} evidence item(s). No residuals.`,
-        };
-      }
-      return {
-        posture: "cautioned",
-        basis: `Gate accepted but ${residualCount} residual(s) carry forward.`,
-      };
-
-    case "accepted-with-cautions":
-      return {
-        posture: "cautioned",
-        basis: gate.reason,
-      };
-
-    case "held-for-review":
-      return {
-        posture: "held",
-        basis: gate.reason,
-      };
-
-    case "blocked-missing-evidence":
-      return {
-        posture: "blocked",
-        basis: gate.reason,
-      };
-
-    case "pending":
-    case "not-checked":
-      return {
-        posture: "unknown",
-        basis: gate.reason,
-      };
-  }
-}
-
-// ---------------------------------------------------------------------------
-// Closure basis — why closure is or isn't allowed
-// ---------------------------------------------------------------------------
-
-function deriveClosureBasis(
-  closureAllowed: boolean,
-  gate: GateState,
-  delta: CanonicalDelta,
-): string {
-  if (closureAllowed) {
-    if (delta.objective_state === "met" && delta.unresolved.length === 0) {
-      return "Objective met, gate passed, no unresolved items.";
-    }
-    return `Gate: ${gate.label}. Closure permitted despite ${delta.unresolved.length} unresolved item(s).`;
-  }
-
-  const reasons: string[] = [];
-  if (gate.label === "held-for-review") reasons.push("Gate held for review");
-  if (gate.label === "blocked-missing-evidence") reasons.push("Gate blocked — missing evidence");
-  if (delta.unresolved.length > 0) reasons.push(`${delta.unresolved.length} unresolved item(s)`);
-  if (reasons.length === 0) reasons.push("Pre-return phase — no return to close");
-
-  return reasons.join(". ") + ".";
-}
-
-// ---------------------------------------------------------------------------
-// Advancement basis — what caused canonical state to advance
-// ---------------------------------------------------------------------------
-
-function deriveAdvancementBasis(delta: CanonicalDelta): { advanced: boolean; basis: string } {
-  const ea = delta.evidence_accounting;
-  if (!ea) {
-    // No evidence accounting — check state_fields_advanced
-    if (delta.state_fields_advanced.length > 0) {
-      return { advanced: true, basis: delta.state_fields_advanced.join("; ") };
-    }
-    return { advanced: false, basis: "No evidence accounting available." };
-  }
-
-  if (ea.consequence_type === "no-change") {
-    return { advanced: false, basis: ea.consequence_label };
-  }
-
-  return { advanced: true, basis: ea.consequence_label };
-}
-
-// ---------------------------------------------------------------------------
-// Primary builder — assembles the audited receipt from component objects
-// ---------------------------------------------------------------------------
-
-export function buildAuditedReceipt(input: BuildAuditedReceiptInput): AuditedReceipt {
-  const { envelope, delta, gate, nextSlice, projectId = "", audit, traceSummary, budgetSummary, overflowSummary } = input;
-
-  // Claim assessments
-  const claim_assessments = assessClaims(envelope, delta);
-
-  // Evidence counts from delta's evidence accounting (single source of truth)
-  const ea = delta.evidence_accounting;
-  const verification_count = ea?.verification_run_count ?? delta.verification_runs.length;
-  const evidence_count = ea?.evidence_item_count ?? delta.evidence_items.length;
-  const criteria_met_count = ea?.criteria_met_count ?? 0;
-  const files_changed_count = ea?.file_change_count ?? delta.file_changes.length;
-
-  // --- Explicit audit findings (matches RunSnapshot pattern) ---
-  const audit_required = audit?.audit_required ?? false;
-  const audit_cautions: string[] = [];
-  const audit_blockers: string[] = [];
-  if (audit) {
-    for (const f of audit.findings) {
-      if (f.severity === "caution") {
-        audit_cautions.push(`[audit] ${f.detail}`);
-      } else if (f.severity === "blocker") {
-        audit_blockers.push(`[audit-blocker] ${f.detail}`);
-      }
-    }
-  }
-  const audit_finding_count = audit_cautions.length + audit_blockers.length;
-
-  // Residuals — delta cautions + audit cautions merged (single source of truth)
-  const cautions_on_record = [...delta.cautions, ...audit_cautions, ...audit_blockers];
-  const unresolved_on_record = delta.unresolved;
-  const residual_count = cautions_on_record.length + unresolved_on_record.length;
-
-  // Trust posture
-  const { posture: trust_posture, basis: trust_basis } = deriveTrustPosture(gate, residual_count);
-
-  // Closure — use shared control-flag logic
-  const phase = gate.label === "accepted" ? "accepted" as const
-    : gate.label === "accepted-with-cautions" ? "accepted_with_cautions" as const
-    : gate.label === "held-for-review" ? "held_for_review" as const
-    : gate.label === "blocked-missing-evidence" ? "blocked" as const
-    : "return_received" as const;
-  const { closureAllowed } = deriveControlFlags(phase, true);
-  const closure_basis = deriveClosureBasis(closureAllowed, gate, delta);
-
-  // Advancement
-  const { advanced: state_advanced, basis: advancement_basis } = deriveAdvancementBasis(delta);
-  const consequence_type = ea?.consequence_type ?? "no-change";
-  const consequence_label = ea?.consequence_label ?? "No evidence accounting available.";
-
-  return auditedReceiptSchema.parse({
-    // Identity
-    receipt_id: `aud-${randomBytes(8).toString("hex")}`,
-    receipt_version: 1,
-    created_at: new Date().toISOString(),
-    project_id: projectId || delta.project_id,
-    dispatch_id: envelope.dispatch_id,
-    return_id: envelope.return_id,
-    envelope_id: envelope.envelope_id,
-    delta_id: delta.delta_id,
-
-    // Claimed
-    objective_claimed: envelope.objective_used,
-    outcome_claimed: envelope.outcome_class,
-    summary_claimed: envelope.summary,
-
-    // Proven
-    verification_count,
-    evidence_count,
-    criteria_met_count,
-    files_changed_count,
-    claim_assessments,
-
-    // Gate
-    gate_label: gate.label,
-    gate_reason: gate.reason,
-    gate_honest: gate.honest,
-
-    // Provenance
-    provenance_posture: envelope.provenance_posture,
-    confidence_posture: envelope.confidence_posture,
-
-    // Closure
-    closure_allowed: closureAllowed,
-    closure_basis,
-
-    // Audit findings (explicit, not just reflected in gate)
-    audit_required,
-    audit_finding_count,
-    audit_cautions,
-    audit_blockers,
-
-    // Residuals
-    cautions_on_record,
-    unresolved_on_record,
-    residual_count,
-
-    // Advancement
-    state_advanced,
-    advancement_basis,
-    consequence_type,
-    consequence_label,
-
-    // Next slice (with basis)
-    next_slice_exists: !!nextSlice,
-    next_slice_id: nextSlice?.slice_id ?? "",
-    next_slice_title: nextSlice?.title ?? "",
-    next_slice_ready: nextSlice?.dispatch_ready ?? false,
-    next_slice_why: nextSlice?.why_next ?? "",
-    next_slice_blocking_reason: nextSlice?.blocking_reason ?? "",
-
-    // Execution trace summary
-    trace_step_count: traceSummary?.trace_step_count ?? 0,
-    trace_tool_use_count: traceSummary?.trace_tool_use_count ?? 0,
-    trace_failure_phase: traceSummary?.trace_failure_phase ?? "",
-    trace_error_category: traceSummary?.trace_error_category ?? "",
-    trace_duration_ms: traceSummary?.trace_duration_ms ?? 0,
-    trace_available: traceSummary?.trace_available ?? false,
-
-    // Budget breakdown
-    budget_task_steps: budgetSummary?.task_steps ?? 0,
-    budget_task_tool_uses: budgetSummary?.task_tool_uses ?? 0,
-    budget_verification_steps: budgetSummary?.verification_steps ?? 0,
-    budget_verification_tool_uses: budgetSummary?.verification_tool_uses ?? 0,
-    budget_correction_steps: budgetSummary?.correction_steps ?? 0,
-    budget_correction_tool_uses: budgetSummary?.correction_tool_uses ?? 0,
-    budget_overhead_ratio: budgetSummary?.overhead_ratio ?? 0,
-    budget_had_corrections: budgetSummary?.had_corrections ?? false,
-    budget_posture: budgetSummary?.budget_posture ?? "unknown",
-    budget_posture_basis: budgetSummary?.budget_posture_basis ?? "",
-
-    // Overflow / progressive disclosure
-    overflow_entry_count: overflowSummary?.overflow_entry_count ?? 0,
-    overflow_total_bytes: overflowSummary?.overflow_total_bytes ?? 0,
-    overflow_sources: overflowSummary?.overflow_sources ?? [],
-    overflow_available: overflowSummary?.overflow_available ?? false,
-
-    // Trust
-    trust_posture,
-    trust_basis,
-  });
-}

package/node_modules/@switchboard/core/src/budget-ledger.ts

@@ -1,223 +0,0 @@
-import type { BudgetCategory, BudgetLedger, BudgetLedgerEntry, BudgetPosture } from "./types";
-import { budgetLedgerSchema } from "./types";
-import type { TraceStep, ExecutionTrace } from "./execution-trace";
-
-// ---------------------------------------------------------------------------
-// Budget Ledger — derives task / verification / correction effort breakdown
-// ---------------------------------------------------------------------------
-//
-// The budget ledger aggregates trace steps by their budget category and
-// derives a posture that downstream governance (live events, receipts,
-// evaluation) can consume.
-//
-// It does NOT enforce limits or allocate budgets — it *measures* what
-// happened and classifies the effort distribution. Policy decisions about
-// what budget ratios are acceptable belong to the evaluation lane and
-// route-selection logic.
-//
-// Design invariants:
-//   - The ledger is derived from execution trace data only
-//   - The posture derivation is deterministic and conservative
-//   - An empty trace → posture "unknown" (not "nominal")
-//   - Correction effort is never hidden; had_corrections is always honest
-// ---------------------------------------------------------------------------
-
-// ---------------------------------------------------------------------------
-// Aggregation — sum steps by budget category
-// ---------------------------------------------------------------------------
-
-function aggregateByCategory(steps: TraceStep[]): Map<BudgetCategory, BudgetLedgerEntry> {
-  const map = new Map<BudgetCategory, { step_count: number; tool_use_count: number; duration_ms: number }>();
-
-  for (const step of steps) {
-    const cat = step.budget_category;
-    const acc = map.get(cat) ?? { step_count: 0, tool_use_count: 0, duration_ms: 0 };
-    acc.step_count += 1;
-    if (step.kind === "tool_use" || step.kind === "command") {
-      acc.tool_use_count += 1;
-    }
-    acc.duration_ms += step.duration_hint_ms;
-    map.set(cat, acc);
-  }
-
-  const entries: BudgetLedgerEntry[] = [];
-  for (const cat of ["task", "verification", "correction"] as const) {
-    const acc = map.get(cat);
-    if (acc) {
-      entries.push({ category: cat, ...acc });
-    }
-  }
-
-  return new Map(entries.map(e => [e.category, e]));
-}
-
-// ---------------------------------------------------------------------------
-// Posture derivation — from effort distribution
-// ---------------------------------------------------------------------------
-//
-// Thresholds are intentionally generous for V1. The goal is observability,
-// not punishment. Policy tightening belongs in the evaluation lane.
-//
-//   nominal:     correction ≤ 20% of total, or no corrections at all
-//   caution:     correction > 20% but ≤ 50% of total
-//   over-budget: correction > 50% of total (most effort was rework)
-//   unknown:     no trace data
-// ---------------------------------------------------------------------------
-
-const CORRECTION_CAUTION_THRESHOLD = 0.20;
-const CORRECTION_OVER_BUDGET_THRESHOLD = 0.50;
-
-function derivePosture(
-  totalSteps: number,
-  correctionSteps: number,
-  hadCorrections: boolean,
-): { posture: BudgetPosture; basis: string } {
-  if (totalSteps === 0) {
-    return { posture: "unknown", basis: "No trace steps available." };
-  }
-
-  if (!hadCorrections) {
-    return { posture: "nominal", basis: "No correction effort detected." };
-  }
-
-  const correctionRatio = correctionSteps / totalSteps;
-
-  if (correctionRatio > CORRECTION_OVER_BUDGET_THRESHOLD) {
-    return {
-      posture: "over-budget",
-      basis: `Correction effort is ${(correctionRatio * 100).toFixed(0)}% of total steps (>${(CORRECTION_OVER_BUDGET_THRESHOLD * 100).toFixed(0)}% threshold).`,
-    };
-  }
-
-  if (correctionRatio > CORRECTION_CAUTION_THRESHOLD) {
-    return {
-      posture: "caution",
-      basis: `Correction effort is ${(correctionRatio * 100).toFixed(0)}% of total steps (>${(CORRECTION_CAUTION_THRESHOLD * 100).toFixed(0)}% threshold).`,
-    };
-  }
-
-  return {
-    posture: "nominal",
-    basis: `Correction effort is ${(correctionRatio * 100).toFixed(0)}% of total steps — within nominal range.`,
-  };
-}
-
-// ---------------------------------------------------------------------------
-// Primary builder — derive a BudgetLedger from an ExecutionTrace
-// ---------------------------------------------------------------------------
-
-export function deriveBudgetLedger(trace: ExecutionTrace | null): BudgetLedger {
-  if (!trace || trace.steps.length === 0) {
-    return budgetLedgerSchema.parse({
-      entries: [],
-      total_steps: 0,
-      total_tool_uses: 0,
-      total_duration_ms: 0,
-      overhead_ratio: 0,
-      had_corrections: false,
-      posture: "unknown",
-      posture_basis: "No trace data available.",
-    });
-  }
-
-  const categoryMap = aggregateByCategory(trace.steps);
-
-  const entries: BudgetLedgerEntry[] = [];
-  let totalSteps = 0;
-  let totalToolUses = 0;
-  let totalDuration = 0;
-
-  for (const cat of ["task", "verification", "correction"] as const) {
-    const entry = categoryMap.get(cat);
-    if (entry) {
-      entries.push(entry);
-      totalSteps += entry.step_count;
-      totalToolUses += entry.tool_use_count;
-      totalDuration += entry.duration_ms;
-    }
-  }
-
-  const verifyEntry = categoryMap.get("verification");
-  const correctEntry = categoryMap.get("correction");
-  const overheadSteps = (verifyEntry?.step_count ?? 0) + (correctEntry?.step_count ?? 0);
-  const overheadRatio = totalSteps > 0 ? overheadSteps / totalSteps : 0;
-  const hadCorrections = (correctEntry?.step_count ?? 0) > 0;
-
-  const { posture, basis } = derivePosture(
-    totalSteps,
-    correctEntry?.step_count ?? 0,
-    hadCorrections,
-  );
-
-  return budgetLedgerSchema.parse({
-    entries,
-    total_steps: totalSteps,
-    total_tool_uses: totalToolUses,
-    total_duration_ms: totalDuration,
-    overhead_ratio: Math.round(overheadRatio * 1000) / 1000, // 3 decimal places
-    had_corrections: hadCorrections,
-    posture,
-    posture_basis: basis,
-  });
-}
-
-// ---------------------------------------------------------------------------
-// Convenience — extract budget posture from a ledger for use in live events
-// ---------------------------------------------------------------------------
-
-export function budgetPostureFromLedger(ledger: BudgetLedger | null): BudgetPosture {
-  return ledger?.posture ?? "unknown";
-}
-
-// ---------------------------------------------------------------------------
-// Category counts — convenience for receipt embedding
-// ---------------------------------------------------------------------------
-
-export interface BudgetSummary {
-  task_steps: number;
-  task_tool_uses: number;
-  task_duration_ms: number;
-  verification_steps: number;
-  verification_tool_uses: number;
-  verification_duration_ms: number;
-  correction_steps: number;
-  correction_tool_uses: number;
-  correction_duration_ms: number;
-  overhead_ratio: number;
-  had_corrections: boolean;
-  budget_posture: BudgetPosture;
-  budget_posture_basis: string;
-}
-
-export function deriveBudgetSummary(ledger: BudgetLedger | null): BudgetSummary {
-  if (!ledger) {
-    return {
-      task_steps: 0, task_tool_uses: 0, task_duration_ms: 0,
-      verification_steps: 0, verification_tool_uses: 0, verification_duration_ms: 0,
-      correction_steps: 0, correction_tool_uses: 0, correction_duration_ms: 0,
-      overhead_ratio: 0, had_corrections: false,
-      budget_posture: "unknown", budget_posture_basis: "No budget ledger available.",
-    };
-  }
-
-  const get = (cat: BudgetCategory) => ledger.entries.find(e => e.category === cat);
-  const task = get("task");
-  const verify = get("verification");
-  const correct = get("correction");
-
-  return {
-    task_steps: task?.step_count ?? 0,
-    task_tool_uses: task?.tool_use_count ?? 0,
-    task_duration_ms: task?.duration_ms ?? 0,
-    verification_steps: verify?.step_count ?? 0,
-    verification_tool_uses: verify?.tool_use_count ?? 0,
-    verification_duration_ms: verify?.duration_ms ?? 0,
-    correction_steps: correct?.step_count ?? 0,
-    correction_tool_uses: correct?.tool_use_count ?? 0,
-    correction_duration_ms: correct?.duration_ms ?? 0,
-    overhead_ratio: ledger.overhead_ratio,
-    had_corrections: ledger.had_corrections,
-    budget_posture: ledger.posture,
-    budget_posture_basis: ledger.posture_basis,
-  };
-}