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

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

@@ -0,0 +1,904 @@
+import { randomBytes } from "crypto";
+import type {
+  AuditedReceipt,
+  AuditResult,
+  CanonicalDelta,
+  ClaimAssessmentV2,
+  ClaimDisposition,
+  EvidenceItemV2,
+  ExecutionMetadata,
+  FindingV2,
+  GateState,
+  IssuanceAssessment,
+  NextSlice,
+  NormalizedReturnEnvelope,
+  ProofManifest,
+  ProofSummary,
+  ReceiptIssuedV2,
+  ReceiptLifecyclePosture,
+  ReceiptStatusEvent,
+  ReceiptVerdict,
+  TrustPosture,
+  UnresolvedGap,
+  VerificationResult,
+} from "./types";
+import {
+  receiptIssuedV2Schema,
+  receiptLifecyclePostureSchema,
+} from "./types";
+import { deriveControlFlags } from "./run-snapshot";
+import type { TraceSummary } from "./execution-trace";
+import type { BudgetSummary } from "./budget-ledger";
+
+// ---------------------------------------------------------------------------
+// Receipt V2 — immutable issuance + append-only lifecycle
+// ---------------------------------------------------------------------------
+
+// ---------------------------------------------------------------------------
+// Honesty guardrails — banned / restricted copy patterns
+// ---------------------------------------------------------------------------
+
+const BANNED_UNQUALIFIED_TERMS = [
+  "no issues",
+  "safe to deploy",
+  "certified",
+  "approved",
+  "audited",
+  "compliant",
+  "guaranteed",
+];
+
+const RESTRICTED_VERIFIED_TERM = "verified";
+
+/**
+ * Check if text contains banned honesty terms.
+ * Returns list of violations found.
+ */
+export function checkHonestyViolations(text: string): string[] {
+  const lower = text.toLowerCase();
+  const violations: string[] = [];
+
+  for (const term of BANNED_UNQUALIFIED_TERMS) {
+    if (lower.includes(term)) {
+      violations.push(`Banned term "${term}" found in receipt text`);
+    }
+  }
+
+  // "verified" without scope qualifier is restricted
+  if (lower.includes(RESTRICTED_VERIFIED_TERM)) {
+    // Check if it's scope-qualified (preceded by "partially", "scope-", etc.)
+    const verifiedIdx = lower.indexOf(RESTRICTED_VERIFIED_TERM);
+    const before = lower.slice(Math.max(0, verifiedIdx - 20), verifiedIdx).trim();
+    const qualifiers = ["partially", "scope-qualified", "within scope", "for scope", "slice-check"];
+    const isQualified = qualifiers.some(q => before.includes(q));
+    if (!isQualified) {
+      violations.push(`Unqualified "${RESTRICTED_VERIFIED_TERM}" — must be scope-qualified`);
+    }
+  }
+
+  return violations;
+}
+
+/**
+ * Returns true if the given verdict text is safe for use in a receipt.
+ */
+export function isHonestCopy(text: string): boolean {
+  return checkHonestyViolations(text).length === 0;
+}
+
+// ---------------------------------------------------------------------------
+// Posture precedence — resolves current lifecycle posture from status events
+// ---------------------------------------------------------------------------
+
+const POSTURE_PRECEDENCE: ReceiptLifecyclePosture[] = [
+  "REVOKED",
+  "SUSPENDED",
+  "EXPIRED",
+  "SUPERSEDED",
+  "CURRENT_WITH_LIMITS",
+  "CURRENT",
+];
+
+/**
+ * Resolve the current lifecycle posture from an ordered list of status events.
+ * Events are processed in chronological order.
+ * Precedence: REVOKED > SUSPENDED > EXPIRED > SUPERSEDED > CURRENT_WITH_LIMITS > CURRENT
+ */
+export function resolveCurrentPosture(
+  events: ReceiptStatusEvent[],
+): { posture: ReceiptLifecyclePosture; basis: string; active_limits: string[] } {
+  if (events.length === 0) {
+    return { posture: "CURRENT", basis: "No status events — receipt is current.", active_limits: [] };
+  }
+
+  // Process events chronologically to build state
+  let revoked = false;
+  let revokeReason = "";
+  let suspended = false;
+  let suspendReason = "";
+  let expired = false;
+  let expiryReason = "";
+  let superseded = false;
+  let supersededBy = "";
+  const activeLimits: string[] = [];
+
+  for (const event of events) {
+    switch (event.event_type) {
+      case "REVOKED":
+        revoked = true;
+        revokeReason = event.reason;
+        break;
+      case "SUSPENDED":
+        suspended = true;
+        suspendReason = event.reason;
+        break;
+      case "REINSTATED":
+        suspended = false;
+        break;
+      case "EXPIRED":
+        expired = true;
+        expiryReason = event.reason;
+        break;
+      case "EXPIRY_SET":
+        // Check if the expiry time has passed
+        if (event.expiry_at && new Date(event.expiry_at) <= new Date()) {
+          expired = true;
+          expiryReason = event.reason || `Expired at ${event.expiry_at}`;
+        }
+        break;
+      case "SUPERSEDED_BY":
+        superseded = true;
+        supersededBy = event.superseded_by_receipt_id;
+        break;
+      case "LIMIT_APPLIED":
+        activeLimits.push(event.limit_description || event.reason);
+        break;
+      case "LIMIT_LIFTED": {
+        const idx = activeLimits.indexOf(event.limit_description || event.reason);
+        if (idx >= 0) activeLimits.splice(idx, 1);
+        break;
+      }
+    }
+  }
+
+  // Resolve by precedence
+  if (revoked) {
+    return { posture: "REVOKED", basis: revokeReason, active_limits: activeLimits };
+  }
+  if (suspended) {
+    return { posture: "SUSPENDED", basis: suspendReason, active_limits: activeLimits };
+  }
+  if (expired) {
+    return { posture: "EXPIRED", basis: expiryReason, active_limits: activeLimits };
+  }
+  if (superseded) {
+    return {
+      posture: "SUPERSEDED",
+      basis: `Superseded by receipt ${supersededBy}`,
+      active_limits: activeLimits,
+    };
+  }
+  if (activeLimits.length > 0) {
+    return {
+      posture: "CURRENT_WITH_LIMITS",
+      basis: `${activeLimits.length} active limit(s): ${activeLimits.join("; ")}`,
+      active_limits: activeLimits,
+    };
+  }
+
+  return { posture: "CURRENT", basis: "No limiting status events.", active_limits: [] };
+}
+
+// ---------------------------------------------------------------------------
+// Verdict aggregation — deterministic receipt verdict from evidence
+// ---------------------------------------------------------------------------
+
+/**
+ * Derive the human-facing receipt verdict from verification results, evidence,
+ * findings, gaps, gate state, and proof summary.
+ *
+ * Rules:
+ * - Missing proof manifest forces inconclusive or not_verified
+ * - Unresolved critical unknowns block pure verified treatment
+ * - Scope must be explicit per verification result
+ * - "verified" only when scope is full and evidence is sufficient
+ */
+export function deriveReceiptVerdict(input: {
+  gate: GateState;
+  verification_results: VerificationResult[];
+  unresolved_gaps: UnresolvedGap[];
+  proof_summary: ProofSummary;
+  claim_assessments: ClaimAssessmentV2[];
+  residual_count: number;
+  /** Pre-computed honesty violations from summary text (if any). */
+  honesty_violations?: string[];
+}): IssuanceAssessment {
+  const { gate, verification_results, unresolved_gaps, proof_summary, claim_assessments, residual_count } = input;
+  const degradation_reasons: string[] = [];
+
+  // Pre-apply honesty violations — these degrade the verdict, not just decorate it
+  const honestyViolations = input.honesty_violations ?? [];
+  if (honestyViolations.length > 0) {
+    degradation_reasons.push(
+      ...honestyViolations.map(v => `Honesty violation in summary: ${v}`),
+    );
+  }
+
+  // Hard degradation: missing proof manifest
+  if (!proof_summary.manifest_present) {
+    degradation_reasons.push("Proof manifest is missing — cannot independently verify provenance");
+    return {
+      verdict: "inconclusive",
+      verdict_basis: "Proof manifest is not present. Receipt cannot verify execution provenance independently.",
+      scope_qualified: false,
+      scope_description: "",
+      degradation_reasons,
+      honesty_violations: honestyViolations,
+    };
+  }
+
+  // Hard degradation: gate blocked or held
+  if (gate.label === "blocked-missing-evidence") {
+    degradation_reasons.push(`Gate blocked: ${gate.reason}`);
+    return {
+      verdict: "not_verified",
+      verdict_basis: `Gate blocked — ${gate.reason}`,
+      scope_qualified: false,
+      scope_description: "",
+      degradation_reasons,
+      honesty_violations: honestyViolations,
+    };
+  }
+
+  if (gate.label === "held-for-review") {
+    degradation_reasons.push(`Gate held: ${gate.reason}`);
+    return {
+      verdict: "inconclusive",
+      verdict_basis: `Gate held for review — ${gate.reason}`,
+      scope_qualified: false,
+      scope_description: "",
+      degradation_reasons,
+      honesty_violations: honestyViolations,
+    };
+  }
+
+  // Check for critical unresolved gaps
+  const criticalGaps = unresolved_gaps.filter(g => g.impact === "blocks_verification");
+  if (criticalGaps.length > 0) {
+    degradation_reasons.push(`${criticalGaps.length} gap(s) block verification`);
+  }
+
+  // Check verification results
+  const failedVerifications = verification_results.filter(v => v.outcome === "fail");
+  const passedVerifications = verification_results.filter(v => v.outcome === "pass");
+  const totalVerifications = verification_results.length;
+
+  if (failedVerifications.length > 0) {
+    degradation_reasons.push(`${failedVerifications.length} verification(s) failed`);
+  }
+
+  // Check claim assessment quality
+  const unsubstantiated = claim_assessments.filter(c => c.disposition === "unsubstantiated");
+  const inferred = claim_assessments.filter(c => c.disposition === "inferred");
+  if (unsubstantiated.length > 0) {
+    degradation_reasons.push(`${unsubstantiated.length} claim(s) unsubstantiated`);
+  }
+
+  // Determine verdict
+  let verdict: ReceiptVerdict;
+  let scope_description = "";
+
+  if (criticalGaps.length > 0 || failedVerifications.length > 0) {
+    verdict = "not_verified";
+  } else if (
+    gate.label === "accepted" &&
+    residual_count === 0 &&
+    unsubstantiated.length === 0 &&
+    passedVerifications.length > 0 &&
+    degradation_reasons.length === 0
+  ) {
+    verdict = "verified";
+    scope_description = `${passedVerifications.length} verification(s) passed across ${totalVerifications} total`;
+  } else if (gate.label === "accepted" || gate.label === "accepted-with-cautions") {
+    if (inferred.length > 0 || unsubstantiated.length > 0 || residual_count > 0 || degradation_reasons.length > 0) {
+      verdict = "partially_verified";
+    } else {
+      verdict = "verified";
+    }
+    scope_description = `${passedVerifications.length}/${totalVerifications} verification(s) passed`;
+  } else {
+    verdict = "inconclusive";
+  }
+
+  return {
+    verdict,
+    verdict_basis: degradation_reasons.length > 0
+      ? `Degraded: ${degradation_reasons.join("; ")}`
+      : `Gate ${gate.label}, ${passedVerifications.length} verification(s) passed, ${residual_count} residual(s).`,
+    scope_qualified: verdict === "verified" && totalVerifications > 0,
+    scope_description,
+    degradation_reasons,
+    honesty_violations: honestyViolations,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Build claim assessments (V2 two-axis model)
+// ---------------------------------------------------------------------------
+
+function assessClaimsV2(
+  envelope: NormalizedReturnEnvelope,
+  delta: CanonicalDelta,
+): ClaimAssessmentV2[] {
+  const assessments: ClaimAssessmentV2[] = [];
+
+  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;
+
+    let bestPartialLine = "";
+    let bestPartialScore = 0;
+    let bestPartialPool = "";
+
+    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";
+      }
+    }
+
+    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";
+      }
+    }
+
+    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";
+      }
+    }
+
+    if (bestPartialScore >= 1) {
+      return {
+        disposition: "partial",
+        basis: `Partial ${bestPartialPool} match (${bestPartialScore}/${words.length} keywords): ${bestPartialLine.slice(0, 80)}`,
+      };
+    }
+
+    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." };
+  }
+
+  // Summary claim
+  if (envelope.summary) {
+    const result = classify(envelope.summary);
+    assessments.push({
+      claim: envelope.summary,
+      source: "executor",
+      provenance_type: "claimed",
+      ...result,
+    });
+  }
+
+  // Criteria claims
+  for (const criterion of envelope.criteria_met) {
+    const result = classify(criterion.text);
+    assessments.push({
+      claim: criterion.text,
+      source: "executor",
+      provenance_type: criterion.content_mode === "direct" ? "observed" : "claimed",
+      ...result,
+    });
+  }
+
+  // Decision claims
+  for (const decision of envelope.decisions) {
+    const result = classify(decision.text);
+    assessments.push({
+      claim: decision.text,
+      source: "executor",
+      provenance_type: "derived",
+      ...result,
+    });
+  }
+
+  return assessments;
+}
+
+// ---------------------------------------------------------------------------
+// Build verification results from delta/evidence
+// ---------------------------------------------------------------------------
+
+function buildVerificationResults(delta: CanonicalDelta): VerificationResult[] {
+  const results: VerificationResult[] = [];
+
+  for (const run of delta.verification_runs) {
+    results.push({
+      verification_id: `vr-${randomBytes(4).toString("hex")}`,
+      scope: "execution",
+      method: run.slice(0, 80),
+      outcome: "pass",
+      coverage: "",
+      determinism: "unknown",
+      evidence_type: "captured",
+      detail: run,
+    });
+  }
+
+  for (const check of delta.tests_or_checks) {
+    results.push({
+      verification_id: `vr-${randomBytes(4).toString("hex")}`,
+      scope: "test",
+      method: check.name,
+      outcome: check.passed ? "pass" : "fail",
+      coverage: "",
+      determinism: "deterministic",
+      evidence_type: "captured",
+      detail: `Test "${check.name}" — ${check.passed ? "passed" : "failed"}`,
+    });
+  }
+
+  return results;
+}
+
+// ---------------------------------------------------------------------------
+// Build evidence items from delta
+// ---------------------------------------------------------------------------
+
+function buildEvidenceItemsV2(delta: CanonicalDelta): EvidenceItemV2[] {
+  const items: EvidenceItemV2[] = [];
+
+  for (const ev of delta.evidence_items) {
+    items.push({
+      evidence_id: `ev-${randomBytes(4).toString("hex")}`,
+      kind: "other",
+      provenance: "captured",
+      description: ev,
+      reference: "",
+    });
+  }
+
+  for (const fc of delta.file_changes) {
+    items.push({
+      evidence_id: `ev-${randomBytes(4).toString("hex")}`,
+      kind: "file_diff",
+      provenance: "captured",
+      description: `File changed: ${fc.path}`,
+      reference: fc.path,
+    });
+  }
+
+  return items;
+}
+
+// ---------------------------------------------------------------------------
+// Build findings from audit + gate
+// ---------------------------------------------------------------------------
+
+function buildFindingsV2(audit: AuditResult | null | undefined, gate: GateState): FindingV2[] {
+  const findings: FindingV2[] = [];
+
+  if (audit) {
+    for (const f of audit.findings) {
+      findings.push({
+        finding_id: `fn-${randomBytes(4).toString("hex")}`,
+        severity: f.severity === "blocker" ? "blocker" : f.severity === "caution" ? "caution" : "info",
+        category: f.check,
+        detail: f.detail,
+        resolution: "",
+      });
+    }
+  }
+
+  if (!gate.honest) {
+    findings.push({
+      finding_id: `fn-${randomBytes(4).toString("hex")}`,
+      severity: "concern",
+      category: "gate_honesty",
+      detail: "Gate label is not consistent with evidence — gate_honest is false.",
+      resolution: "",
+    });
+  }
+
+  return findings;
+}
+
+// ---------------------------------------------------------------------------
+// Build unresolved gaps
+// ---------------------------------------------------------------------------
+
+function buildUnresolvedGaps(delta: CanonicalDelta): UnresolvedGap[] {
+  return delta.unresolved.map(text => ({
+    gap_id: `gap-${randomBytes(4).toString("hex")}`,
+    description: text,
+    impact: "degrades_confidence" as const,
+    category: "unresolved_item",
+  }));
+}
+
+// ---------------------------------------------------------------------------
+// Trust posture derivation (reused from V1 for backward compat)
+// ---------------------------------------------------------------------------
+
+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 };
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Build proof summary from proof manifest
+// ---------------------------------------------------------------------------
+
+function buildProofSummary(manifest: ProofManifest | null | undefined): ProofSummary {
+  if (!manifest) {
+    return {
+      captured_count: 0,
+      reconstructed_count: 0,
+      derived_count: 0,
+      total_artifacts: 0,
+      manifest_present: false,
+      manifest_id: "",
+    };
+  }
+
+  return {
+    captured_count: manifest.provenance_summary.captured_count,
+    reconstructed_count: manifest.provenance_summary.reconstructed_count,
+    derived_count: manifest.provenance_summary.derived_count,
+    total_artifacts: manifest.artifacts.length,
+    manifest_present: true,
+    manifest_id: manifest.manifest_id,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Primary builder — build immutable ReceiptIssuedV2 from component objects
+// ---------------------------------------------------------------------------
+
+export interface BuildReceiptV2Input {
+  envelope: NormalizedReturnEnvelope;
+  delta: CanonicalDelta;
+  gate: GateState;
+  nextSlice: NextSlice | null;
+  projectId?: string;
+  audit?: AuditResult | null;
+  traceSummary?: TraceSummary | null;
+  budgetSummary?: BudgetSummary | null;
+  proofManifest?: ProofManifest | null;
+  executionMeta?: Partial<ExecutionMetadata>;
+  v1ReceiptId?: string;
+  /** Meta harness provenance — when a harness compile pass ran for this dispatch. */
+  harnessProvenance?: {
+    harness_ran: boolean;
+    compilation_id: string;
+    selected_candidate_id: string;
+    experiment: string;
+    selection_rationale: string;
+    context_chars_added: number;
+    was_no_op: boolean;
+  } | null;
+}
+
+export function buildReceiptIssuedV2(input: BuildReceiptV2Input): ReceiptIssuedV2 {
+  const {
+    envelope, delta, gate, nextSlice, projectId = "",
+    audit, proofManifest, executionMeta, v1ReceiptId,
+  } = input;
+
+  // Claim assessments (two-axis)
+  const claim_assessments = assessClaimsV2(envelope, delta);
+
+  // Verification results
+  const verification_results = buildVerificationResults(delta);
+
+  // Evidence items
+  const evidence_items = buildEvidenceItemsV2(delta);
+
+  // Findings
+  const findings = buildFindingsV2(audit, gate);
+
+  // Unresolved gaps
+  const unresolved_gaps = buildUnresolvedGaps(delta);
+
+  // Residuals
+  const auditCautions = audit?.findings.filter(f => f.severity === "caution").map(f => `[audit] ${f.detail}`) ?? [];
+  const auditBlockers = audit?.findings.filter(f => f.severity === "blocker").map(f => `[audit-blocker] ${f.detail}`) ?? [];
+  const cautions_on_record = [...delta.cautions, ...auditCautions, ...auditBlockers];
+  const unresolved_on_record = delta.unresolved;
+  const residual_count = cautions_on_record.length + unresolved_on_record.length;
+
+  // Proof summary
+  const proof_summary = buildProofSummary(proofManifest);
+
+  // Enforce honesty guards on the summary BEFORE verdict derivation
+  const summaryViolations = checkHonestyViolations(envelope.summary);
+
+  // Issuance assessment (human-facing verdict) — honesty violations degrade the verdict
+  const issuance_assessment = deriveReceiptVerdict({
+    gate,
+    verification_results,
+    unresolved_gaps,
+    proof_summary,
+    claim_assessments,
+    residual_count,
+    honesty_violations: summaryViolations,
+  });
+
+  // Trust posture (V1 compat) — aligned down if issuance_assessment is weaker
+  let { posture: trust_posture, basis: trust_basis } = deriveTrustPosture(gate, residual_count);
+
+  // Prevent trust_posture from being stronger than issuance_assessment.verdict
+  const verdictToTrust: Record<string, TrustPosture> = {
+    verified: "verified",
+    partially_verified: "cautioned",
+    inconclusive: "held",
+    not_verified: "blocked",
+    disputed: "held",
+  };
+  const trustRank: Record<TrustPosture, number> = {
+    verified: 0, cautioned: 1, held: 2, blocked: 3, unknown: 4,
+  };
+  const verdictTrust = verdictToTrust[issuance_assessment.verdict] ?? "unknown";
+  if (trustRank[trust_posture] < trustRank[verdictTrust]) {
+    trust_posture = verdictTrust;
+    trust_basis = `Aligned to issuance verdict "${issuance_assessment.verdict}": ${issuance_assessment.verdict_basis}`;
+  }
+
+  // Closure
+  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);
+
+  let closure_basis: string;
+  if (closureAllowed) {
+    closure_basis = delta.objective_state === "met" && delta.unresolved.length === 0
+      ? "Objective met, gate passed, no unresolved items."
+      : `Gate: ${gate.label}. Closure permitted despite ${delta.unresolved.length} unresolved item(s).`;
+  } else {
+    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");
+    closure_basis = reasons.join(". ") + ".";
+  }
+
+  // Advancement
+  const ea = delta.evidence_accounting;
+  let state_advanced: boolean;
+  let advancement_basis: string;
+  if (!ea) {
+    state_advanced = delta.state_fields_advanced.length > 0;
+    advancement_basis = state_advanced ? delta.state_fields_advanced.join("; ") : "No evidence accounting available.";
+  } else if (ea.consequence_type === "no-change") {
+    state_advanced = false;
+    advancement_basis = ea.consequence_label;
+  } else {
+    state_advanced = true;
+    advancement_basis = ea.consequence_label;
+  }
+
+  // Execution metadata
+  const execution: ExecutionMetadata = {
+    surface: executionMeta?.surface ?? envelope.source_surface,
+    model: executionMeta?.model ?? "",
+    duration_ms: executionMeta?.duration_ms ?? 0,
+    realization_type: executionMeta?.realization_type ?? "",
+    environment: executionMeta?.environment ?? "",
+    human_intervention: executionMeta?.human_intervention ?? "unknown",
+  };
+
+  return receiptIssuedV2Schema.parse({
+    receipt_id: `rcv2-${randomBytes(8).toString("hex")}`,
+    receipt_version: 2,
+    issued_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,
+
+    objective_asked: envelope.objective_used,
+    scope_summary: delta.evidence_accounting
+      ? `${delta.evidence_accounting.scope_check_pass_count}/${delta.evidence_accounting.scope_check_count} scope checks passed`
+      : "",
+
+    execution,
+
+    outcome_claimed: envelope.outcome_class,
+    summary_claimed: envelope.summary,
+
+    claim_assessments,
+    verification_results,
+    evidence_items,
+    findings,
+    unresolved_gaps,
+
+    gate_label: gate.label,
+    gate_reason: gate.reason,
+    gate_honest: gate.honest,
+
+    issuance_assessment,
+
+    state_advanced,
+    advancement_basis,
+    consequence_type: ea?.consequence_type ?? "no-change",
+    consequence_label: ea?.consequence_label ?? "No evidence accounting available.",
+
+    cautions_on_record,
+    unresolved_on_record,
+    residual_count,
+
+    next_slice_exists: !!nextSlice,
+    next_slice_id: nextSlice?.slice_id ?? "",
+    next_slice_title: nextSlice?.title ?? "",
+
+    proof_summary,
+    provenance_posture: envelope.provenance_posture,
+
+    audit_and_evaluation_links: {},
+    redaction_profile: { mode: "full", redacted_fields: [], share_safe: false },
+
+    closure_allowed: closureAllowed,
+    closure_basis,
+
+    trust_posture,
+    trust_basis,
+
+    v1_receipt_id: v1ReceiptId ?? "",
+
+    harness_provenance: input.harnessProvenance ?? {
+      harness_ran: false,
+      compilation_id: "",
+      selected_candidate_id: "",
+      experiment: "",
+      selection_rationale: "",
+      context_chars_added: 0,
+      was_no_op: true,
+    },
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Create a status event
+// ---------------------------------------------------------------------------
+
+export function createStatusEvent(
+  receiptId: string,
+  eventType: ReceiptStatusEvent["event_type"],
+  reason: string,
+  opts?: {
+    issued_by?: string;
+    superseded_by_receipt_id?: string;
+    expiry_at?: string;
+    limit_description?: string;
+  },
+): ReceiptStatusEvent {
+  return {
+    event_id: `rse-${randomBytes(8).toString("hex")}`,
+    receipt_id: receiptId,
+    event_type: eventType,
+    reason,
+    issued_by: opts?.issued_by ?? "system",
+    issued_at: new Date().toISOString(),
+    superseded_by_receipt_id: opts?.superseded_by_receipt_id ?? "",
+    expiry_at: opts?.expiry_at ?? "",
+    limit_description: opts?.limit_description ?? "",
+    metadata: {},
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Prepare share-safe view of a receipt
+// ---------------------------------------------------------------------------
+
+/**
+ * Prepare a share-safe view of a V2 receipt. The share view:
+ * - Preserves: posture, scope, evidence basis, open item count, integrity, timestamps, evaluation scope
+ * - May redact: internal project IDs, environment details
+ * - Must NOT be more reassuring than the full view
+ */
+export function prepareShareView(
+  receipt: ReceiptIssuedV2,
+  statusEvents: ReceiptStatusEvent[],
+): ReceiptIssuedV2 & { current_status: ReturnType<typeof resolveCurrentPosture> } {
+  const current_status = resolveCurrentPosture(statusEvents);
+
+  // Create share-safe copy — preserve decision-critical context
+  const shareReceipt: ReceiptIssuedV2 = {
+    ...receipt,
+    redaction_profile: {
+      mode: "share",
+      redacted_fields: ["project_id"],
+      share_safe: true,
+    },
+    // Redact internal identifiers but keep everything decision-critical
+    project_id: "[redacted]",
+  };
+
+  return { ...shareReceipt, current_status };
+}
+
+// ---------------------------------------------------------------------------
+// Format receipt for JSON export
+// ---------------------------------------------------------------------------
+
+export function formatReceiptForExport(
+  receipt: ReceiptIssuedV2,
+  statusEvents: ReceiptStatusEvent[],
+  evaluation?: { evaluation_id: string; verdict: string; scope: string; timestamp: string; basis: string } | null,
+): Record<string, unknown> {
+  const current_status = resolveCurrentPosture(statusEvents);
+
+  // Attach evaluation links if available
+  const withEval: ReceiptIssuedV2 = evaluation
+    ? {
+      ...receipt,
+      audit_and_evaluation_links: {
+        latest_evaluation_id: evaluation.evaluation_id,
+        evaluation_verdict: evaluation.verdict,
+        evaluation_scope: evaluation.scope,
+        evaluation_timestamp: evaluation.timestamp,
+        evaluation_basis: evaluation.basis,
+      },
+    }
+    : receipt;
+
+  return {
+    receipt: withEval,
+    current_status,
+    status_history: statusEvents,
+    exported_at: new Date().toISOString(),
+    export_format_version: "1.0.0",
+  };
+}