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

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

@@ -0,0 +1,450 @@
+import type {
+  HandoffRecord,
+  ProjectContract,
+  ReconcileFinding,
+  ReconcileReport,
+  ReturnReport,
+} from "./types";
+import { reconcileReportSchema } from "./types";
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function compact(text: string) {
+  return text.replace(/\s+/g, " ").trim().toLowerCase();
+}
+
+function wordsOf(text: string): string[] {
+  const STOP = new Set([
+    "a","an","the","and","or","but","is","are","was","were","it","its",
+    "in","on","at","to","for","of","with","by","from","that","this",
+    "as","be","do","has","have","had","not","no","will","can","may",
+  ]);
+  return compact(text)
+    .replace(/[.,;:!?"'()[\]{}]/g, "")
+    .split(/\s+/)
+    .filter((w) => w.length > 2 && !STOP.has(w));
+}
+
+function overlapRatio(a: string, b: string): number {
+  const setA = new Set(wordsOf(a));
+  const setB = new Set(wordsOf(b));
+  if (setA.size === 0 || setB.size === 0) return 0;
+  let overlap = 0;
+  for (const word of setA) {
+    if (setB.has(word)) overlap++;
+  }
+  return overlap / Math.min(setA.size, setB.size);
+}
+
+// ---------------------------------------------------------------------------
+// Negation detection
+// ---------------------------------------------------------------------------
+
+const NEGATION_MARKERS = [
+  "no ", "not ", "without ", "avoided ", "did not ", "does not ",
+  "do not ", "don't ", "didn't ", "won't ", "never ", "excluded ",
+  "no deep ", "not deep ", "kept away from ", "stayed away from ",
+];
+
+function isNegated(text: string, substanceWords: string[]): boolean {
+  const lower = compact(text);
+  for (const marker of NEGATION_MARKERS) {
+    const markerIdx = lower.indexOf(marker);
+    if (markerIdx === -1) continue;
+    const window = lower.substring(markerIdx, markerIdx + 60 + marker.length);
+    const matchCount = substanceWords.filter((w) => window.includes(w)).length;
+    if (matchCount >= 2 || (matchCount >= 1 && substanceWords.length <= 3)) {
+      return true;
+    }
+  }
+  return false;
+}
+
+// ---------------------------------------------------------------------------
+// Semantic proximity map — catches synonym/euphemism evasion of non-goals
+// ---------------------------------------------------------------------------
+
+const SEMANTIC_PROXIMITY_MAP: Record<string, string[]> = {
+  chat: ["messaging", "conversation", "thread", "threading", "discussion", "direct-message", "instant-message"],
+  messaging: ["chat", "conversation", "thread", "threading", "discussion", "direct-message"],
+  agent: ["autonomous", "self-directed", "orchestrator", "coordinator", "dispatch", "bot", "automated"],
+  autonomous: ["agent", "self-directed", "orchestrator", "automated", "self-governing"],
+  platform: ["marketplace", "hub", "portal", "ecosystem", "suite"],
+  marketplace: ["platform", "hub", "portal", "store", "exchange"],
+  saas: ["multi-tenant", "subscription", "hosted-service", "cloud-service"],
+  subscription: ["saas", "recurring", "billing", "plan", "tier"],
+  analytics: ["metrics", "tracking", "reporting", "charts", "insights", "visualization", "dashboard"],
+  dashboard: ["analytics", "charts", "metrics", "reporting", "overview", "visualization", "panel"],
+  social: ["network", "feed", "follow", "like", "share", "community", "profile"],
+  network: ["social", "feed", "follow", "like", "community", "graph"],
+  enterprise: ["team", "organization", "multi-user", "admin", "role-based", "permissions", "workspace"],
+  integration: ["connector", "plugin", "webhook", "api-connection", "sync", "bridge"],
+};
+
+function expandWithProximity(words: string[]): string[] {
+  const expanded = new Set(words);
+  for (const word of words) {
+    const proximate = SEMANTIC_PROXIMITY_MAP[word];
+    if (proximate) {
+      for (const p of proximate) {
+        expanded.add(p);
+      }
+    }
+  }
+  return Array.from(expanded);
+}
+
+// ---------------------------------------------------------------------------
+// Trace annotation extraction
+// ---------------------------------------------------------------------------
+
+function extractTraceTarget(decision: string): string | null {
+  const match = decision.match(/traces?\s+to[:\s]+(.+?)(?:\)|$)/i);
+  return match?.[1]?.trim() ?? null;
+}
+
+// ---------------------------------------------------------------------------
+// Tactical next-step detection
+// ---------------------------------------------------------------------------
+
+const TACTICAL_MARKERS = [
+  "run ", "test ", "deploy ", "configure ", "set ", "install ",
+  "npm ", "pnpm ", "start ", "verify ", "check ", "review ",
+  "iterate ", "polish ", "fix ", "update ", "push ",
+];
+
+function isTacticalNextStep(text: string): boolean {
+  const lower = compact(text);
+  return TACTICAL_MARKERS.some((m) => lower.startsWith(m) || lower.includes(". " + m));
+}
+
+// ---------------------------------------------------------------------------
+// Tracked clearing — records why a potential finding was suppressed
+// ---------------------------------------------------------------------------
+
+type ClearedFinding = {
+  category: ReconcileFinding["category"];
+  reason: string;
+  parent_source: string;
+};
+
+// ---------------------------------------------------------------------------
+// Six drift checks — each returns findings AND cleared records
+// ---------------------------------------------------------------------------
+
+function checkScopeInflation(
+  report: ReturnReport,
+  handoff: HandoffRecord,
+): { findings: ReconcileFinding[]; cleared: ClearedFinding[] } {
+  const findings: ReconcileFinding[] = [];
+  const cleared: ClearedFinding[] = [];
+  const scopeText = handoff.loop.scope_in.join(" ") + " " + handoff.loop.expected_artifacts.join(" ");
+  const expectedLower = scopeText.toLowerCase();
+  const summaryLower = compact(report.summary);
+
+  for (const artifact of report.artifacts_created) {
+    if (!artifact) continue;
+    const artifactLower = artifact.toLowerCase();
+
+    if (artifactLower.includes("return report") || artifactLower.includes("structured return")) continue;
+    if (artifactLower.includes("candidate") || artifactLower.includes("external")) continue;
+
+    const artifactWords = wordsOf(artifact);
+    const matchInScope = artifactWords.filter((w) => expectedLower.includes(w)).length;
+    const matchInSummary = artifactWords.filter((w) => summaryLower.includes(w)).length;
+
+    if (artifactWords.length > 0 && matchInScope === 0 && matchInSummary < 2) {
+      findings.push({
+        category: "scope-inflation",
+        description: `"${artifact}" does not appear in the handoff scope or expected artifacts.`,
+        severity: "warning",
+        source_field: "artifacts_created",
+        parent_evidence: "",
+      });
+    } else if (matchInSummary >= 2 && matchInScope === 0) {
+      cleared.push({
+        category: "scope-inflation",
+        reason: `"${artifact}" matches the return summary (in-scope work described there).`,
+        parent_source: "summary",
+      });
+    }
+  }
+
+  return { findings, cleared };
+}
+
+function checkNonGoalViolation(
+  report: ReturnReport,
+  contract: ProjectContract,
+): { findings: ReconcileFinding[]; cleared: ClearedFinding[] } {
+  const findings: ReconcileFinding[] = [];
+  const cleared: ClearedFinding[] = [];
+  const returnText = `${report.summary} ${report.decisions_made.join(" ")}`;
+  const returnWords = new Set(wordsOf(returnText));
+
+  for (const nonGoal of contract.non_goals) {
+    const substance = compact(nonGoal)
+      .replace(/^not (a|an)\s+/i, "")
+      .replace(/\.$/, "");
+    const substanceWords = wordsOf(substance);
+
+    if (substanceWords.length === 0) continue;
+
+    const matchCount = substanceWords.filter((w) => returnWords.has(w)).length;
+    const matchRatio = matchCount / substanceWords.length;
+
+    if (matchRatio >= 0.4) {
+      if (isNegated(returnText, substanceWords)) {
+        cleared.push({
+          category: "non-goal-violation",
+          reason: `Return affirms non-goal "${nonGoal}" (negation detected near matching words).`,
+          parent_source: "negation-context",
+        });
+        continue;
+      }
+
+      findings.push({
+        category: "non-goal-violation",
+        description: `Return content overlaps with non-goal: "${nonGoal}".`,
+        severity: "review-required",
+        source_field: "summary/decisions_made",
+        parent_evidence: `Non-goal substance words [${substanceWords.join(", ")}] matched in return text without negation.`,
+      });
+    } else {
+      // Second pass: semantic expansion — catches synonym/euphemism evasion
+      const expandedSubstance = expandWithProximity(substanceWords);
+      if (expandedSubstance.length > substanceWords.length) {
+        const expandedMatchCount = expandedSubstance.filter((w) => returnWords.has(w)).length;
+        const expandedMatchRatio = expandedMatchCount / expandedSubstance.length;
+
+        if (expandedMatchRatio >= 0.15) {
+          if (isNegated(returnText, expandedSubstance)) {
+            cleared.push({
+              category: "non-goal-violation",
+              reason: `Return affirms non-goal "${nonGoal}" (negation detected near semantically expanded words).`,
+              parent_source: "negation-context",
+            });
+            continue;
+          }
+
+          const matchedWords = expandedSubstance.filter((w) => returnWords.has(w));
+          findings.push({
+            category: "non-goal-violation",
+            description: `Return content overlaps with semantic neighbors of non-goal: "${nonGoal}".`,
+            severity: "warning",
+            source_field: "summary/decisions_made",
+            parent_evidence: `Non-goal substance [${substanceWords.join(", ")}] expanded to [${matchedWords.join(", ")}] via semantic proximity (ratio: ${expandedMatchRatio.toFixed(2)}).`,
+          });
+        }
+      }
+    }
+  }
+
+  return { findings, cleared };
+}
+
+function checkGoalDrift(
+  report: ReturnReport,
+  contract: ProjectContract,
+): { findings: ReconcileFinding[]; cleared: ClearedFinding[] } {
+  if (isTacticalNextStep(report.recommended_next_step)) {
+    return {
+      findings: [],
+      cleared: [{
+        category: "goal-drift",
+        reason: `Next step "${report.recommended_next_step.slice(0, 60)}" is a tactical continuation, not a directional change.`,
+        parent_source: "tactical-detection",
+      }],
+    };
+  }
+
+  const outcomeOverlap = overlapRatio(report.recommended_next_step, contract.desired_v1_outcome);
+  const problemOverlap = overlapRatio(report.recommended_next_step, contract.problem);
+  const oneLinerOverlap = overlapRatio(report.recommended_next_step, contract.one_liner);
+  const bestOverlap = Math.max(outcomeOverlap, problemOverlap, oneLinerOverlap);
+
+  if (bestOverlap < 0.1 && report.recommended_next_step.length > 10) {
+    return {
+      findings: [{
+        category: "goal-drift",
+        description: `Recommended next step ("${report.recommended_next_step.slice(0, 80)}") has low overlap with the project's V1 outcome, problem, or one-liner.`,
+        severity: "warning",
+        source_field: "recommended_next_step",
+        parent_evidence: `Best overlap ratio: ${bestOverlap.toFixed(2)} (threshold: 0.10).`,
+      }],
+      cleared: [],
+    };
+  }
+
+  return { findings: [], cleared: [] };
+}
+
+function checkTargetUserShift(
+  report: ReturnReport,
+  contract: ProjectContract,
+): { findings: ReconcileFinding[]; cleared: ClearedFinding[] } {
+  const USER_SEGMENT_MARKERS = [
+    "enterprise", "teams", "students", "beginners", "agencies",
+    "managers", "executives", "consumers", "end users", "administrators",
+  ];
+
+  const contractUserWords = new Set(wordsOf(contract.target_user));
+  const returnText = compact(`${report.summary} ${report.decisions_made.join(" ")}`);
+  const findings: ReconcileFinding[] = [];
+  const cleared: ClearedFinding[] = [];
+
+  for (const segment of USER_SEGMENT_MARKERS) {
+    if (returnText.includes(segment) && !contractUserWords.has(segment)) {
+      if (isNegated(`${report.summary} ${report.decisions_made.join(" ")}`, [segment])) {
+        cleared.push({
+          category: "target-user-shift",
+          reason: `"${segment}" appears near negation — affirming exclusion, not shifting audience.`,
+          parent_source: "negation-context",
+        });
+        continue;
+      }
+
+      findings.push({
+        category: "target-user-shift",
+        description: `Return mentions "${segment}" which is not in the original target user ("${contract.target_user}").`,
+        severity: "warning",
+        source_field: "summary/decisions_made",
+        parent_evidence: `Contract target user: "${contract.target_user}". Segment "${segment}" not found there.`,
+      });
+      break;
+    }
+  }
+
+  return { findings, cleared };
+}
+
+function checkUntrackedDecisions(
+  report: ReturnReport,
+  handoff: HandoffRecord,
+  contract: ProjectContract,
+  specMarkdown?: string,
+): { findings: ReconcileFinding[]; cleared: ClearedFinding[] } {
+  const findings: ReconcileFinding[] = [];
+  const cleared: ClearedFinding[] = [];
+
+  const handoffContext =
+    handoff.loop.scope_in.join(" ") + " " +
+    handoff.loop.blocker_escalation.join(" ") + " " +
+    handoff.loop.done_when.join(" ");
+
+  const contractContext =
+    contract.problem + " " +
+    contract.desired_v1_outcome + " " +
+    contract.non_goals.join(" ") + " " +
+    contract.one_liner;
+
+  const briefContext = specMarkdown ? compact(specMarkdown) : "";
+
+  for (const decision of report.decisions_made) {
+    if (!decision) continue;
+
+    if (overlapRatio(decision, handoffContext) >= 0.15) {
+      cleared.push({ category: "untracked-decision", reason: `Matched handoff scope/escalation/done-when.`, parent_source: "handoff" });
+      continue;
+    }
+
+    if (overlapRatio(decision, contractContext) >= 0.15) {
+      cleared.push({ category: "untracked-decision", reason: `Matched project contract (problem/outcome/non-goals).`, parent_source: "contract" });
+      continue;
+    }
+
+    if (briefContext && overlapRatio(decision, briefContext) >= 0.1) {
+      cleared.push({ category: "untracked-decision", reason: `Matched canonical brief.`, parent_source: "brief" });
+      continue;
+    }
+
+    const traceTarget = extractTraceTarget(decision);
+    if (traceTarget) {
+      const allContext = `${handoffContext} ${contractContext} ${briefContext}`;
+      if (overlapRatio(traceTarget, allContext) >= 0.15) {
+        cleared.push({ category: "untracked-decision", reason: `Trace annotation "${traceTarget}" matched parent context.`, parent_source: "trace-annotation" });
+        continue;
+      }
+    }
+
+    findings.push({
+      category: "untracked-decision",
+      description: `Decision "${decision.slice(0, 80)}" is not traceable to the handoff scope, project contract, or canonical brief.`,
+      severity: "warning",
+      source_field: "decisions_made",
+      parent_evidence: "No parent context matched above 0.15 threshold.",
+    });
+  }
+
+  return { findings, cleared };
+}
+
+function checkEvidenceContradiction(
+  report: ReturnReport,
+  _contract: ProjectContract,
+): { findings: ReconcileFinding[]; cleared: ClearedFinding[] } {
+  const CONTRADICTION_MARKERS = [
+    "does not exist", "not a real problem", "no demand", "not needed",
+    "already solved", "unnecessary", "no evidence of", "users don't", "nobody needs",
+  ];
+
+  const evidenceText = compact(report.evidence.join(" "));
+
+  for (const marker of CONTRADICTION_MARKERS) {
+    if (evidenceText.includes(marker)) {
+      return {
+        findings: [{
+          category: "evidence-contradiction",
+          description: `Evidence contains "${marker}" which may contradict the original problem statement.`,
+          severity: "review-required",
+          source_field: "evidence",
+          parent_evidence: `Marker "${marker}" found in evidence text.`,
+        }],
+        cleared: [],
+      };
+    }
+  }
+
+  return { findings: [], cleared: [] };
+}
+
+// ---------------------------------------------------------------------------
+// Main reconcile function
+// ---------------------------------------------------------------------------
+
+export function reconcileReturn(input: {
+  report: ReturnReport;
+  contract: ProjectContract;
+  handoff: HandoffRecord;
+  spec_markdown?: string;
+}): ReconcileReport {
+  const { report, contract, handoff, spec_markdown } = input;
+
+  const checks = [
+    checkScopeInflation(report, handoff),
+    checkNonGoalViolation(report, contract),
+    checkGoalDrift(report, contract),
+    checkTargetUserShift(report, contract),
+    checkUntrackedDecisions(report, handoff, contract, spec_markdown),
+    checkEvidenceContradiction(report, contract),
+  ];
+
+  const findings = checks.flatMap((c) => c.findings);
+  const allCleared = checks.flatMap((c) => c.cleared);
+  const hasReviewRequired = findings.some((f) => f.severity === "review-required");
+
+  return reconcileReportSchema.parse({
+    findings,
+    drift_detected: findings.length > 0,
+    recommendation:
+      findings.length === 0
+        ? "accept"
+        : hasReviewRequired
+          ? "review-required"
+          : "accept-with-warnings",
+    cleared_count: allCleared.length,
+    checked_count: findings.length + allCleared.length,
+  });
+}

package/node_modules/@switchboard/projections/node_modules/@switchboard/core/src/return-normalizer.ts

@@ -0,0 +1,226 @@
+import { randomBytes } from "crypto";
+import type {
+  AuditResult,
+  ContentMode,
+  NormalizedCaution,
+  NormalizedReturnEnvelope,
+  NormalizedResidual,
+  OutcomeClass,
+  ReconcileReport,
+  ReturnReport,
+  SourceRole,
+  Surface,
+} from "./types";
+import { normalizedReturnEnvelopeSchema } from "./types";
+import { SYSTEM_PATTERNS } from "./canonical-delta";
+
+// ---------------------------------------------------------------------------
+// Normalized Return Envelope — maps raw surface returns into governed shape
+// ---------------------------------------------------------------------------
+//
+// This module converts existing ReturnReport (and optional reconcile/audit
+// context) into a NormalizedReturnEnvelope that downstream receipt, delta,
+// and audit logic can consume without surface-specific branching.
+//
+// Design constraints:
+//   - Every field is filled from structured source data, never prose parsing
+//   - content_mode tracks provenance of each value (direct/wrapped/inferred/reconstructed)
+//   - The envelope is additive — it does not replace ReturnReport, it wraps it
+//   - Existing flows keep working; the envelope is a parallel governed artifact
+// ---------------------------------------------------------------------------
+
+/**
+ * Classify a file path into the system it touches using the shared
+ * SYSTEM_PATTERNS from canonical-delta (single source of truth).
+ */
+function classifyFile(path: string): string {
+  for (const [pattern, label] of SYSTEM_PATTERNS) {
+    if (pattern.test(path)) return label;
+  }
+  return "";
+}
+
+/**
+ * Derive the outcome class from the raw return status and objective_met.
+ */
+function deriveOutcomeClass(report: ReturnReport): OutcomeClass {
+  if (report.status === "done" && report.objective_met === "yes") return "completed";
+  if (report.status === "blocked") return "blocked";
+  if (report.status === "partial" || report.objective_met === "partial") return "partial";
+  if (report.objective_met === "no" && report.status === "done") return "absorbed";
+  return "partial";
+}
+
+/**
+ * Determine the default content mode for a surface's return values.
+ *
+ * Claude Code returns are captured directly from the agent's structured output.
+ * Cursor returns are reconstructed — surface-profiles models Cursor as
+ * can_return_structured: false / human_return, so its values are rebuilt
+ * from the conversation after the fact, not captured from structured output.
+ * ChatGPT returns are wrapped — present but reformatted to fit the schema.
+ */
+function defaultContentMode(surface: Surface): ContentMode {
+  switch (surface) {
+    case "claude-code":
+    case "codex":
+      return "direct";
+    case "cursor":
+      return "reconstructed";
+    case "chatgpt":
+      return "wrapped";
+  }
+}
+
+/**
+ * Derive overall provenance posture from the content modes present.
+ */
+function deriveProvenancePosture(
+  modes: ContentMode[],
+): "captured" | "reconstructed" | "derived" | "mixed" | "unknown" {
+  if (modes.length === 0) return "unknown";
+  const unique = new Set(modes);
+  if (unique.size === 1) {
+    const only = modes[0]!;
+    if (only === "direct") return "captured";
+    if (only === "reconstructed") return "reconstructed";
+    if (only === "inferred") return "derived";
+    if (only === "wrapped") return "captured"; // wrapped is still captured, just reformatted
+  }
+  return "mixed";
+}
+
+/**
+ * Derive confidence posture from the return's evidence strength.
+ */
+function deriveConfidencePosture(report: ReturnReport): "high" | "medium" | "low" | "unknown" {
+  const hasVerification = report.verification_run.length > 0;
+  const hasEvidence = report.evidence.length > 0;
+  const hasCriteria = report.success_criteria_met.length > 0;
+
+  if (hasVerification && hasEvidence && hasCriteria) return "high";
+  if (hasVerification || (hasEvidence && hasCriteria)) return "medium";
+  if (hasEvidence || hasCriteria) return "low";
+  return "unknown";
+}
+
+// ---------------------------------------------------------------------------
+// Primary normalizer — ReturnReport → NormalizedReturnEnvelope
+// ---------------------------------------------------------------------------
+
+export interface NormalizeReturnInput {
+  report: ReturnReport;
+  /** Role of whoever produced the return. Default: "agent". */
+  source_role?: SourceRole;
+  /** Reconcile report, if available. Adds reconcile-sourced cautions. */
+  reconcile?: ReconcileReport | null;
+  /** Audit result, if available. Adds audit-sourced cautions. */
+  audit?: AuditResult | null;
+  /** Dispatch ID to link lineage. */
+  dispatch_id?: string;
+  /** Commands or actions known to have been run during execution. */
+  commands_run?: string[];
+}
+
+export function normalizeReturn(input: NormalizeReturnInput): NormalizedReturnEnvelope {
+  const { report, source_role = "agent", reconcile, audit, dispatch_id = "", commands_run = [] } = input;
+  const mode = defaultContentMode(report.surface_used);
+
+  // --- Changed files with system classification ---
+  const changed_files = report.changed_files.map(path => ({
+    path,
+    system: classifyFile(path),
+  }));
+
+  // --- Evidence items ---
+  const evidence_items = report.evidence.map(text => ({ text, content_mode: mode }));
+
+  // --- Verification runs ---
+  const verification_runs = report.verification_run.map(text => ({ text, content_mode: mode }));
+
+  // --- Success criteria met ---
+  const criteria_met = report.success_criteria_met.map(text => ({ text, content_mode: mode }));
+
+  // --- Decisions ---
+  const decisions = report.decisions_made.map(text => ({ text, content_mode: mode }));
+
+  // --- Cautions (from multiple sources) ---
+  const cautions: NormalizedCaution[] = [];
+
+  // Return-level escalations → cautions
+  for (const e of report.escalations.filter(Boolean)) {
+    cautions.push({ text: e, source: "return" });
+  }
+
+  // Reconcile warnings → cautions
+  if (reconcile) {
+    for (const f of reconcile.findings.filter(f => f.severity === "warning")) {
+      cautions.push({ text: f.description, source: "reconcile" });
+    }
+  }
+
+  // Audit cautions → cautions
+  if (audit) {
+    for (const f of audit.findings.filter(f => f.severity === "caution")) {
+      cautions.push({ text: f.detail, source: "audit" });
+    }
+  }
+
+  // --- Residuals (open items that carry forward) ---
+  const residuals: NormalizedResidual[] = [];
+  for (const b of report.blockers.filter(Boolean)) {
+    residuals.push({ text: b, kind: "blocker" });
+  }
+  for (const e of report.escalations.filter(Boolean)) {
+    residuals.push({ text: e, kind: "escalation" });
+  }
+  if (report.objective_met === "partial") {
+    residuals.push({ text: "Objective only partially met.", kind: "unresolved" });
+  }
+  if (report.objective_met === "no") {
+    residuals.push({ text: "Objective not met.", kind: "unresolved" });
+  }
+
+  // --- Content modes seen (for provenance derivation) ---
+  const allModes: ContentMode[] = [
+    ...evidence_items.map(e => e.content_mode),
+    ...verification_runs.map(v => v.content_mode),
+    ...criteria_met.map(c => c.content_mode),
+    ...decisions.map(d => d.content_mode),
+  ];
+
+  return normalizedReturnEnvelopeSchema.parse({
+    envelope_id: `env-${randomBytes(8).toString("hex")}`,
+    envelope_version: 1,
+    created_at: new Date().toISOString(),
+
+    source_surface: report.surface_used,
+    source_role,
+
+    objective_used: report.objective_attempted,
+    outcome_class: deriveOutcomeClass(report),
+
+    changed_files,
+    touched_artifacts: report.artifacts_created.filter(Boolean),
+    commands_run,
+
+    evidence_items,
+    verification_runs,
+    criteria_met,
+    decisions,
+
+    cautions,
+    residuals,
+
+    recommended_next_step: report.recommended_next_step,
+
+    provenance_posture: deriveProvenancePosture(allModes),
+    confidence_posture: deriveConfidencePosture(report),
+
+    summary: report.summary,
+
+    handoff_id: report.handoff_id,
+    dispatch_id,
+    return_id: report.handoff_id,
+  });
+}