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

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

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

@@ -0,0 +1,223 @@
+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,
+  };
+}