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

package/node_modules/@switchboard/projections/node_modules/@switchboard/core/src/dossier.ts

@@ -0,0 +1,229 @@
+import type {
+  CompilerSelection,
+  ComplexityClassification,
+  OperatorReview,
+  ReconcileReport,
+  RunDossier,
+  SynthesizedSeed,
+} from "./types";
+import { runDossierSchema } from "./types";
+
+// ---------------------------------------------------------------------------
+// Dossier creation
+// ---------------------------------------------------------------------------
+
+function now() {
+  return new Date().toISOString();
+}
+
+export function createDossier(input: {
+  project_title: string;
+  fixture?: string;
+  complexity: ComplexityClassification;
+  compiler: CompilerSelection;
+  seed: SynthesizedSeed;
+}): RunDossier {
+  const ts = now();
+  return runDossierSchema.parse({
+    run_id: `run-${ts.replace(/[:.]/g, "-").slice(0, 19)}`,
+    project_title: input.project_title,
+    fixture: input.fixture ?? "",
+    created_at: ts,
+    updated_at: ts,
+    complexity_verdict: input.complexity.verdict,
+    process_mode: input.complexity.mode,
+    compiler_type: input.compiler.compiler_type,
+    seed_confidence: input.seed.confidence,
+    steps: [
+      {
+        phase: "seed-extraction",
+        timestamp: ts,
+        outcome: `confidence: ${input.seed.confidence}`,
+        detail: `title: ${input.project_title}, missing: ${input.seed.missing_inputs.length}, questions: ${input.seed.open_questions.length}`,
+      },
+      {
+        phase: "classification",
+        timestamp: ts,
+        outcome: `${input.complexity.verdict} / ${input.complexity.mode}`,
+        detail: input.complexity.rationale,
+      },
+      {
+        phase: "compiler-selection",
+        timestamp: ts,
+        outcome: `${input.compiler.compiler_type} → ${input.compiler.recommended_surface}`,
+        detail: input.compiler.rationale,
+      },
+    ],
+    promotion_result: "pending",
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Dossier step appending
+// ---------------------------------------------------------------------------
+
+export function addDossierStep(
+  dossier: RunDossier,
+  phase: string,
+  outcome: string,
+  detail?: string,
+): RunDossier {
+  return runDossierSchema.parse({
+    ...dossier,
+    updated_at: now(),
+    steps: [
+      ...dossier.steps,
+      {
+        phase,
+        timestamp: now(),
+        outcome,
+        detail: detail ?? "",
+      },
+    ],
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Reconcile recording
+// ---------------------------------------------------------------------------
+
+export function recordReconcile(
+  dossier: RunDossier,
+  reconcile: ReconcileReport,
+  promotionResult: "canonical" | "candidate",
+): RunDossier {
+  return runDossierSchema.parse({
+    ...dossier,
+    updated_at: now(),
+    reconcile_recommendation: reconcile.recommendation,
+    reconcile_findings_count: reconcile.findings.length,
+    reconcile_cleared_count: reconcile.cleared_count,
+    promotion_result: promotionResult,
+    steps: [
+      ...dossier.steps,
+      {
+        phase: "reconcile",
+        timestamp: now(),
+        outcome: `${reconcile.recommendation} (${reconcile.findings.length} findings, ${reconcile.cleared_count} cleared)`,
+        detail: reconcile.findings.map((f) => `${f.category}/${f.severity}: ${f.description.slice(0, 60)}`).join("; "),
+      },
+      {
+        phase: "promotion",
+        timestamp: now(),
+        outcome: promotionResult,
+        detail: promotionResult === "canonical"
+          ? "Promoted to canonical state."
+          : "Held as candidate — requires operator review.",
+      },
+    ],
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Operator review
+// ---------------------------------------------------------------------------
+
+export function addOperatorReview(
+  dossier: RunDossier,
+  judgment: OperatorReview["judgment"],
+  note?: string,
+): RunDossier {
+  return runDossierSchema.parse({
+    ...dossier,
+    updated_at: now(),
+    operator_reviews: [
+      ...dossier.operator_reviews,
+      {
+        date: now().split("T")[0],
+        judgment,
+        note: note ?? "",
+      },
+    ],
+    steps: [
+      ...dossier.steps,
+      {
+        phase: "operator-review",
+        timestamp: now(),
+        outcome: judgment,
+        detail: note ?? "",
+      },
+    ],
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Refs
+// ---------------------------------------------------------------------------
+
+export function setDossierRefs(
+  dossier: RunDossier,
+  refs: Partial<RunDossier["refs"]>,
+): RunDossier {
+  return runDossierSchema.parse({
+    ...dossier,
+    updated_at: now(),
+    refs: { ...dossier.refs, ...refs },
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Render (human-readable summary)
+// ---------------------------------------------------------------------------
+
+export function renderDossier(dossier: RunDossier): string {
+  const lines: string[] = [];
+  lines.push(`# Run dossier: ${dossier.project_title}`);
+  lines.push("");
+  lines.push(`- **Run ID**: ${dossier.run_id}`);
+  if (dossier.fixture) lines.push(`- **Fixture**: ${dossier.fixture}`);
+  lines.push(`- **Created**: ${dossier.created_at}`);
+  lines.push(`- **Updated**: ${dossier.updated_at}`);
+  lines.push("");
+  lines.push("## Classification");
+  lines.push("");
+  lines.push(`| Field | Value |`);
+  lines.push(`|---|---|`);
+  lines.push(`| Complexity | ${dossier.complexity_verdict} |`);
+  lines.push(`| Mode | ${dossier.process_mode} |`);
+  lines.push(`| Compiler | ${dossier.compiler_type} |`);
+  lines.push(`| Seed confidence | ${dossier.seed_confidence} |`);
+  lines.push("");
+  lines.push("## Steps");
+  lines.push("");
+  for (const step of dossier.steps) {
+    lines.push(`- **${step.phase}** → ${step.outcome}${step.detail ? ` — ${step.detail.slice(0, 100)}` : ""}`);
+  }
+  lines.push("");
+
+  if (dossier.reconcile_recommendation) {
+    lines.push("## Reconcile");
+    lines.push("");
+    lines.push(`- **Recommendation**: ${dossier.reconcile_recommendation}`);
+    lines.push(`- **Findings**: ${dossier.reconcile_findings_count}`);
+    lines.push(`- **Cleared**: ${dossier.reconcile_cleared_count}`);
+    lines.push(`- **Promotion**: ${dossier.promotion_result}`);
+    lines.push("");
+  }
+
+  if (dossier.operator_reviews.length > 0) {
+    lines.push("## Operator reviews");
+    lines.push("");
+    for (const review of dossier.operator_reviews) {
+      lines.push(`- **${review.date}**: ${review.judgment}${review.note ? ` — ${review.note}` : ""}`);
+    }
+    lines.push("");
+  }
+
+  if (dossier.refs.seed || dossier.refs.brief || dossier.refs.handoff) {
+    lines.push("## References");
+    lines.push("");
+    if (dossier.refs.seed) lines.push(`- Seed: ${dossier.refs.seed}`);
+    if (dossier.refs.brief) lines.push(`- Brief: ${dossier.refs.brief}`);
+    if (dossier.refs.handoff) lines.push(`- Handoff: ${dossier.refs.handoff}`);
+    if (dossier.refs.execution_return) lines.push(`- Execution return: ${dossier.refs.execution_return}`);
+    if (dossier.refs.reconcile_report) lines.push(`- Reconcile report: ${dossier.refs.reconcile_report}`);
+    lines.push("");
+  }
+
+  return lines.join("\n");
+}

package/node_modules/@switchboard/projections/node_modules/@switchboard/core/src/eval-scope.ts

@@ -0,0 +1,208 @@
+import type {
+  AuditedReceipt,
+  EvaluationResult,
+  ProofManifest,
+  PromotionGate,
+  ValidationScope,
+} from "./types";
+import { promotionGateSchema } from "./types";
+
+// ---------------------------------------------------------------------------
+// Eval Scope — layered validation scope model
+// ---------------------------------------------------------------------------
+//
+// Three scopes, ordered from cheapest/fastest to most thorough:
+//
+//   micro-check  — claim coverage only. No contract compliance, no proof chain.
+//                  Cheap and fast. Suitable for small local changes where
+//                  the system wants a quick sanity check before proceeding.
+//
+//   slice-check  — claim coverage + contract compliance + proof chain integrity
+//                  for a single slice/dispatch. This is the standard check
+//                  after an execution returns.
+//
+//   full-run     — everything in slice-check, plus cross-slice lineage and
+//                  promotion eligibility. Required before any trust promotion
+//                  (e.g. milestone-review, closure-seal, archive-promotion).
+//
+// The scope is:
+//   1. Declared on evaluation input (requested_scope)
+//   2. Classified by classifyScope if not explicitly requested
+//   3. Persisted on the EvaluationResult (validation_scope)
+//   4. Checked by the promotion gate before trust-level advancement
+//
+// Invariant: a broader scope never weakens a narrower check's findings.
+//            It only adds more checks.
+// ---------------------------------------------------------------------------
+
+// ---------------------------------------------------------------------------
+// Full-run availability gate
+// ---------------------------------------------------------------------------
+//
+// full-run is declared in the schema but no full-run-only check exists yet.
+// Until a real promotion_eligibility check is implemented, the system MUST
+// NOT emit validation_scope: "full-run" — doing so would let a paper label
+// satisfy a promotion gate that should require materially stricter checks.
+//
+// Set this to true ONLY when runEvaluation actually runs a full-run-only
+// phase (e.g. cross-slice lineage, promotion eligibility assessment).
+// ---------------------------------------------------------------------------
+
+export const FULL_RUN_AVAILABLE = false;
+
+// ---------------------------------------------------------------------------
+// Scope ordering — for comparison and gate logic
+// ---------------------------------------------------------------------------
+
+const SCOPE_ORDER: Record<ValidationScope, number> = {
+  "micro-check": 0,
+  "slice-check": 1,
+  "full-run": 2,
+};
+
+/**
+ * Returns true if `performed` is at least as broad as `required`.
+ */
+export function scopeCovers(
+  performed: ValidationScope,
+  required: ValidationScope,
+): boolean {
+  return SCOPE_ORDER[performed] >= SCOPE_ORDER[required];
+}
+
+// ---------------------------------------------------------------------------
+// Scope classification — infer scope from what data is available
+// ---------------------------------------------------------------------------
+
+export interface ScopeClassificationInput {
+  /** Explicitly requested scope, if any. */
+  requested_scope?: ValidationScope;
+  /** Whether contract scope items were provided. */
+  has_contracted_scope: boolean;
+  /** Whether contract done-when criteria were provided. */
+  has_contracted_done_when: boolean;
+  /** Whether a proof manifest is available. */
+  has_proof_manifest: boolean;
+}
+
+/**
+ * Classify the validation scope for an evaluation run.
+ *
+ * If the caller requests a specific scope, that scope is honored up to
+ * the maximum achievable scope. If `full-run` is requested but
+ * FULL_RUN_AVAILABLE is false, the scope is downgraded to `slice-check`
+ * because emitting `full-run` without running full-run-only checks
+ * would be dishonest.
+ *
+ * If no scope is requested, we infer from the available data:
+ *   - proof manifest + contract → slice-check
+ *   - proof manifest only → slice-check (proof chain is valuable even without contract)
+ *   - contract only → slice-check (contract compliance is valuable even without proof)
+ *   - neither → micro-check
+ */
+export function classifyScope(input: ScopeClassificationInput): ValidationScope {
+  // Explicit request — honor it, but cap at max achievable
+  if (input.requested_scope) {
+    if (input.requested_scope === "full-run" && !FULL_RUN_AVAILABLE) {
+      // Fail closed: do not emit full-run when no full-run-only check exists
+      return "slice-check";
+    }
+    return input.requested_scope;
+  }
+
+  // Infer from available data — never auto-infer full-run
+  const hasStructuredInput = input.has_contracted_scope
+    || input.has_contracted_done_when
+    || input.has_proof_manifest;
+
+  return hasStructuredInput ? "slice-check" : "micro-check";
+}
+
+// ---------------------------------------------------------------------------
+// Describe what checks a scope includes — for evaluation_scope field
+// ---------------------------------------------------------------------------
+
+/**
+ * Returns the human-readable list of check categories included in a scope.
+ *
+ * full-run only claims promotion_eligibility when FULL_RUN_AVAILABLE is true.
+ * Otherwise it is honest: same checks as slice-check.
+ */
+export function scopeChecks(scope: ValidationScope): string[] {
+  switch (scope) {
+    case "micro-check":
+      return ["claim_coverage"];
+    case "slice-check":
+      return ["claim_coverage", "contract_compliance", "proof_chain_integrity"];
+    case "full-run":
+      return FULL_RUN_AVAILABLE
+        ? ["claim_coverage", "contract_compliance", "proof_chain_integrity", "promotion_eligibility"]
+        : ["claim_coverage", "contract_compliance", "proof_chain_integrity"];
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Promotion gate — enforce minimum scope before trust advancement
+// ---------------------------------------------------------------------------
+
+/**
+ * Promotion levels and their minimum required validation scope.
+ *
+ * This is deliberately not an exhaustive list of all possible promotions.
+ * It covers the ones Switchboard currently needs:
+ *
+ *   - loop_advance: moving to the next loop iteration → slice-check
+ *   - closure_seal: sealing a loop for archival → full-run
+ *   - milestone_review: human-facing milestone claim → full-run
+ */
+export type PromotionLevel =
+  | "loop_advance"
+  | "closure_seal"
+  | "milestone_review";
+
+const PROMOTION_MINIMUM_SCOPE: Record<PromotionLevel, ValidationScope> = {
+  loop_advance: "slice-check",
+  closure_seal: "full-run",
+  milestone_review: "full-run",
+};
+
+/**
+ * Check whether the performed evaluation scope is sufficient for a
+ * requested promotion level.
+ *
+ * Returns a PromotionGate object that can be persisted alongside
+ * the evaluation result.
+ */
+export function checkPromotionGate(
+  performed: ValidationScope,
+  promotionLevel: PromotionLevel,
+): PromotionGate {
+  const required = PROMOTION_MINIMUM_SCOPE[promotionLevel];
+  const allowed = scopeCovers(performed, required);
+
+  const basis = allowed
+    ? `Scope "${performed}" meets minimum "${required}" for ${promotionLevel}.`
+    : `Scope "${performed}" is insufficient for ${promotionLevel}; requires at least "${required}".`;
+
+  return promotionGateSchema.parse({
+    scope_performed: performed,
+    promotion_allowed: allowed,
+    minimum_scope_required: required,
+    gate_basis: basis,
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Scope sufficiency from evaluation result — convenience for consumers
+// ---------------------------------------------------------------------------
+
+/**
+ * Given an existing evaluation result, check if its scope is sufficient
+ * for a given promotion level without re-running the evaluation.
+ */
+export function evaluationScopeAllows(
+  evaluation: EvaluationResult,
+  promotionLevel: PromotionLevel,
+): PromotionGate {
+  return checkPromotionGate(evaluation.validation_scope, promotionLevel);
+}