pi-mega-compact 0.20.15 → 0.20.17

package/src/vector-cortex/cache/diagnostics-emit.ts

@@ -0,0 +1,90 @@
+/**
+ * cache/diagnostics-emit.ts — VC7C reporter seam (FLAG-GATED).
+ *
+ * Mirrors `./economics-emit.ts`: a thin `safe()` wrapper around an optional
+ * injected `emit`, and the two event names the sprint spec requires verbatim:
+ *   - `vector_cortex_cache_miss_classified` — a miss was classified.
+ *   - `vector_cortex_cache_serve_blocked` — a cache serve was blocked by a
+ *     breaker condition before it could answer from a stale/invalid identity.
+ *
+ * FLAG SEMANTICS. `classifyMiss` (`./diagnostics.ts`) is PURE and runs REGARDLESS
+ * of `MEGACOMPACT_VC7C`. The flag gates ONLY this reporting + dashboard seam:
+ * with the flag off the classifier still returns the SAME class, the breaker
+ * still blocks the SAME serve — we just do not announce them under the VC7C
+ * event namespace, and the dashboard reports `enabled:false` + mode C. That is
+ * what makes flag-off byte-identical to the predecessor (VC7B): the arithmetic
+ * and the correctness decision are never skipped, only the emission. (NOTE the
+ * asymmetry vs VC7B: VC7B gated pure telemetry; here the blocked-serve DECISION
+ * is a correctness behavior and is never flag-gated — only its announcement is.)
+ *
+ * PAYLOAD DISCIPLINE. These events carry the `missClass` and the payload-free
+ * `evidence` booleans/counts (see `./diagnostics-types.ts`) — never a session
+ * id, never a covered range, never a request or covered digest. The classifier
+ * is payload-free by construction, so there is no slot to leak into
+ * (SECURITY_PRIVACY — the exact ledger is not diagnostic data).
+ *
+ * No console, no storage, no network (PREVENT-PI-004 / PREVENT-011). Every line
+ * is a structured JSON event with `ts` + `event`.
+ */
+
+import { VC7C_ENABLED } from "../../config/vector-cortex.js";
+import type { CacheDiagnosticV1, MissClass } from "./diagnostics-types.js";
+
+/** The two structured events the VC7C reporter emits. */
+export type CacheDiagnosticEventName =
+  | "vector_cortex_cache_miss_classified"
+  | "vector_cortex_cache_serve_blocked";
+
+/** Optional emit fn injected by the runtime; tests pass `undefined`. */
+export type CacheDiagnosticEmit = (name: string, payload: unknown) => void;
+
+/** Run `fn` only when an emit exists; a reporting failure is never fatal. */
+function safe(
+  emit: CacheDiagnosticEmit | undefined,
+  fn: (emit: CacheDiagnosticEmit) => void,
+): void {
+  if (emit === undefined) return;
+  try {
+    fn(emit);
+  } catch {
+    // Non-fatal: a reporting failure must never break the agent loop.
+  }
+}
+
+/** Report a classified miss. Gated only by the reporter/dashboard flag. */
+export function reportCacheMissClassified(
+  emit: CacheDiagnosticEmit | undefined,
+  diagnostic: CacheDiagnosticV1,
+): void {
+  if (!VC7C_ENABLED()) return;
+  safe(emit, (e) =>
+    e("vector_cortex_cache_miss_classified", {
+      ts: undefined,
+      event: "vector_cortex_cache_miss_classified",
+      schema: diagnostic.schema,
+      missClass: diagnostic.missClass,
+      evidence: diagnostic.evidence,
+    }),
+  );
+}
+
+/** Report a cache serve that was blocked before answering. Gated by the flag. */
+export function reportCacheServeBlocked(
+  emit: CacheDiagnosticEmit | undefined,
+  blocked: {
+    readonly missClass: MissClass;
+    readonly triadState: string;
+    readonly reason: string;
+  },
+): void {
+  if (!VC7C_ENABLED()) return;
+  safe(emit, (e) =>
+    e("vector_cortex_cache_serve_blocked", {
+      ts: undefined,
+      event: "vector_cortex_cache_serve_blocked",
+      missClass: blocked.missClass,
+      triadState: blocked.triadState,
+      reason: blocked.reason,
+    }),
+  );
+}

package/src/vector-cortex/cache/diagnostics-types.ts

@@ -0,0 +1,87 @@
+/**
+ * cache/diagnostics-types.ts — VC7C cache miss-diagnostic contract types.
+ *
+ * Single source of truth for the miss-classification vocabulary. Kept separate
+ * from the arithmetic (`diagnostics.ts`) so the dashboard client, the emit layer
+ * and the acceptance test all import ONE definition. No logic here; pure types
+ * + the registered ID lists. PREVENT-011 honored (no `any`).
+ */
+
+/** The exclusive miss classes, in the order the classifier ranks them. */
+export type MissClass =
+  | "profile"
+  | "range"
+  | "dependency"
+  | "request"
+  | "generation"
+  | "unknown";
+
+/**
+ * Payload-free by construction. Every field is a boolean or a bounded,
+ * non-negative count — there is no string slot into which a request body, a
+ * session id, or a covered range of user content could be placed. See
+ * SECURITY_PRIVACY: a diagnostic that carried the offending payload would leak
+ * it to the dashboard.
+ */
+export interface MissEvidence {
+  readonly profileMismatch: boolean;
+  readonly rangeMismatch: boolean;
+  readonly dependencyAdvanced: boolean;
+  readonly requestMismatch: boolean;
+  readonly generationInvalidated: boolean;
+  /** Ranges the caller asked for (always observable, even on a cold key). */
+  readonly requestedRangeCount: number;
+  /** Ranges the cache could serve; 0 on a cold key (no crystal). */
+  readonly cachedRangeCount: number;
+  /** max(0, requestHighWater - cachedHighWater), saturated at MAX_SAFE_INTEGER. */
+  readonly dependencyDelta: number;
+  /** True when nothing was cached for this key (null cached fields). */
+  readonly absent: boolean;
+}
+
+/**
+ * A single observation fed to the classifier. A `null` cached field means that
+ * piece of state was never persisted — "absence is not a mismatch". Digests
+ * follow convention: `coveredDigest` is `sha256:<hex>` (WITH prefix);
+ * `requestDigest` is BARE lowercase hex (NO prefix).
+ */
+export interface MissObservation {
+  readonly requestProfileId: string;
+  readonly requestProfileVersion: string;
+  readonly cachedProfileId: string | null;
+  readonly cachedProfileVersion: string | null;
+  readonly requestCoveredDigest: string;
+  readonly cachedCoveredDigest: string | null;
+  readonly requestedRangeCount: number;
+  readonly cachedRangeCount: number | null;
+  readonly requestDigest: string;
+  readonly cachedRequestDigest: string | null;
+  /** Dependency validation high-water (monotonic frontier), as a bigint. */
+  readonly requestDependencyHighWater: bigint;
+  readonly cachedDependencyHighWater: bigint | null;
+  readonly generationInvalidated: boolean;
+}
+
+/** The versioned diagnostic record emitted for every classified miss. */
+export interface CacheDiagnosticV1 {
+  readonly schema: "cache-diagnostic-v1";
+  readonly missClass: MissClass;
+  readonly evidence: MissEvidence;
+}
+
+/** Registered conformance IDs (CACHE-016..030). */
+export const CACHE_DIAGNOSTIC_IDS: readonly string[] = Array.from(
+  { length: 15 },
+  (_v, i) => `CACHE-${String(i + 16).padStart(3, "0")}`,
+);
+
+/** Named headlines surfaced by the conformance corpus. */
+export const CACHE_DIAGNOSTIC_NAMED_IDS = [
+  "CACHE-MISS-001",
+  "CACHE-STALE-003",
+] as const;
+
+/** Event names this subsystem emits (gated by MEGACOMPACT_VC7C). */
+export type CacheDiagnosticEventName =
+  | "vector_cortex_cache_miss_classified"
+  | "vector_cortex_cache_serve_blocked";

package/src/vector-cortex/cache/diagnostics.ts

@@ -0,0 +1,119 @@
+/**
+ * cache/diagnostics.ts — VC7C pure miss classification (flag-independent).
+ *
+ * The classifier is PURE arithmetic: given a `MissObservation` it returns
+ * exactly ONE `MissClass` and the payload-free `MissEvidence`. It is NOT gated by
+ * MEGACOMPACT_VC7C — flag-off must be byte-identical to the predecessor, so the
+ * SAME class a user sees today, they see tomorrow. The flag gates only the
+ * reporter/dashboard seam (see `diagnostics-emit.ts`).
+ *
+ * Exclusive ranking: profile -> range -> dependency -> request -> generation ->
+ * unknown. First match wins; the ranking itself is the contract and is pinned by
+ * CACHE-016..030. "Absence is not a mismatch": a cold key (null cached fields)
+ * classifies `unknown`, never `profile`. PREVENT-002/011/PI-004 honored.
+ */
+
+import type {
+  CacheDiagnosticV1,
+  MissClass,
+  MissEvidence,
+  MissObservation,
+} from "./diagnostics-types.js";
+
+/** A cached field is present iff it is non-null. */
+function isPresent(value: string | number | bigint | null): boolean {
+  return value !== null;
+}
+
+/**
+ * Clamp the dependency delta to a non-negative, safe-integer count. A request
+ * BEHIND the cached frontier is not an advance (delta 0); a huge advance
+ * saturates rather than losing precision.
+ */
+function advanceDelta(
+  request: bigint,
+  cached: bigint | null,
+): { advanced: boolean; delta: number } {
+  if (cached === null) return { advanced: false, delta: 0 };
+  if (request <= cached) return { advanced: false, delta: 0 };
+  const diff = request - cached;
+  if (diff > BigInt(Number.MAX_SAFE_INTEGER)) {
+    return { advanced: true, delta: Number.MAX_SAFE_INTEGER };
+  }
+  return { advanced: true, delta: Number(diff) };
+}
+
+/** Collect the payload-free evidence from one observation. */
+export function collectEvidence(o: MissObservation): MissEvidence {
+  const profileMismatch =
+    isPresent(o.cachedProfileId) &&
+    isPresent(o.cachedProfileVersion) &&
+    (o.cachedProfileId !== o.requestProfileId ||
+      o.cachedProfileVersion !== o.requestProfileVersion);
+
+  const rangeMismatch =
+    (isPresent(o.cachedCoveredDigest) &&
+      o.cachedCoveredDigest !== o.requestCoveredDigest) ||
+    (isPresent(o.cachedRangeCount) &&
+      o.cachedRangeCount !== o.requestedRangeCount);
+
+  const dep = advanceDelta(
+    o.requestDependencyHighWater,
+    o.cachedDependencyHighWater,
+  );
+
+  const requestMismatch =
+    isPresent(o.cachedRequestDigest) &&
+    o.cachedRequestDigest !== o.requestDigest;
+
+  const absent =
+    !isPresent(o.cachedProfileId) &&
+    !isPresent(o.cachedCoveredDigest) &&
+    !isPresent(o.cachedRequestDigest) &&
+    !isPresent(o.cachedDependencyHighWater);
+
+  return {
+    profileMismatch,
+    rangeMismatch,
+    dependencyAdvanced: dep.advanced,
+    requestMismatch,
+    generationInvalidated: o.generationInvalidated,
+    requestedRangeCount: o.requestedRangeCount,
+    // Nothing was cached when the observation is absent, so a stale
+    // cachedRangeCount on the observation is not real — report 0.
+    cachedRangeCount:
+      o.cachedRangeCount === null || absent ? 0 : o.cachedRangeCount,
+    dependencyDelta: dep.delta,
+    absent,
+  };
+}
+
+/** The exclusive ranking: first true cause wins. */
+export function classFor(e: MissEvidence): MissClass {
+  if (e.profileMismatch) return "profile";
+  if (e.rangeMismatch) return "range";
+  if (e.dependencyAdvanced) return "dependency";
+  if (e.requestMismatch) return "request";
+  if (e.generationInvalidated) return "generation";
+  return "unknown";
+}
+
+/** Classify one observation: exactly one deterministic class. */
+export function classifyMiss(o: MissObservation): CacheDiagnosticV1 {
+  const evidence = collectEvidence(o);
+  return {
+    schema: "cache-diagnostic-v1",
+    missClass: classFor(evidence),
+    evidence,
+  };
+}
+
+/**
+ * A miss a caller can self-heal on the next turn (re-fetch under a fresh
+ * profile / a new generation), so a triad recovery path may treat it as
+ * transient. Only profile + generation qualify; the rest are hard mismatches.
+ * An `unknown` miss is NEVER transient.
+ */
+export function isTransientMiss(d: CacheDiagnosticV1): boolean {
+  return d.missClass === "profile" || d.missClass === "generation";
+}

package/src/vector-cortex/migrations/request-hash-v2-ops.ts

@@ -75,16 +75,17 @@ function generationFromEconomics(economicsVersion: string): bigint {
 
 export function detectCollision(host: M5Host): boolean {
   const byHash = new Map<string, string>();
+  const seenIdentities = new Set<string>();
   for (const v1 of host.v1Rows()) {
     const row = deriveRequestHashRow(host, v1);
+    const id = identity(v1.profileId, v1.requestDigest);
+    // Two distinct v1 rows (different v1 hash) with the same v2 hash collide,
+    // even if they share an identity — the v2 table cannot distinguish them.
+    if (seenIdentities.has(id)) return true;
+    seenIdentities.add(id);
     const prior = byHash.get(row.hash);
-    if (
-      prior !== undefined &&
-      prior !== identity(v1.profileId, v1.requestDigest)
-    ) {
-      return true;
-    }
-    byHash.set(row.hash, identity(v1.profileId, v1.requestDigest));
+    if (prior !== undefined && prior !== id) return true;
+    byHash.set(row.hash, id);
   }
   return false;
 }
@@ -148,6 +149,9 @@ export function m5Verify(host: M5Host): M5ValidateResult {
   const expected = new Set<string>();
   for (const v1 of v1Rows) {
     const id = identity(v1.profileId, v1.requestDigest);
+    // Dead-generation rows are intentionally skipped by copy; do not flag.
+    const fresh = deriveRequestHashRow(host, v1);
+    if (isGenerationInvalidated(host, fresh)) continue;
     expected.add(id);
     const n = counts.get(id) ?? 0;
     if (n === 0) codes.push(M5_FAIL.COPY_PARTIAL);
@@ -181,10 +185,12 @@ export function m5Switch(host: M5Host): M5ValidateResult {
   if (host.activeVersion() !== REQUEST_HASH_LEGACY_VERSION) {
     return { ok: false, codes: [M5_FAIL.NOT_ON_LEGACY] };
   }
-  const verify = m5Verify(host);
-  if (!verify.ok) return verify;
+  // Collision check runs before copy-completeness verify: a structural
+  // collision is a switch-blocker regardless of copy state.
   if (detectCollision(host))
     return { ok: false, codes: [M5_FAIL.REQUEST_HASH_COLLISION] };
+  const verify = m5Verify(host);
+  if (!verify.ok) return verify;
   host.switchToV2();
   return { ok: true, codes: [] };
 }

package/src/vector-cortex/outcomes/consent.ts

@@ -0,0 +1,88 @@
+/**
+ * outcomes/consent.ts — VC8A append-only consent grants/revocations.
+ *
+ * ConsentV1 is append-only: grants and revocations are appended with an
+ * effective sequence number. A session has active explicit consent at time T
+ * if its most recent record at or before T is a grant.
+ *
+ * Dataset inclusion requires active explicit consent at export time. This
+ * module provides the pure consent-evaluation functions; the dataset module
+ * calls `hasActiveConsent` at export time.
+ *
+ * PREVENT-PI-004: no network. PREVENT-011: no `any` type.
+ */
+
+import { CONSENT_SCHEMA_V1, type ConsentV1 } from "./types.js";
+
+/**
+ * Evaluate whether a session has active explicit consent at or before the
+ * given effective sequence high-water. True if the most recent record at or
+ * before `effectiveHighWater` is a grant.
+ */
+export function hasActiveConsent(
+  records: ReadonlyArray<ConsentV1>,
+  sessionId: string,
+  effectiveHighWater: number,
+): boolean {
+  const relevant = records
+    .filter((r) => r.sessionId === sessionId && r.effectiveSeq <= effectiveHighWater)
+    .sort((a, b) => a.effectiveSeq - b.effectiveSeq);
+  if (relevant.length === 0) return false;
+  return relevant[relevant.length - 1].action === "grant";
+}
+
+/**
+ * Append a consent grant for a session at the next effective sequence.
+ * Returns a new ConsentV1 record (append-only — never mutates the input).
+ */
+export function appendGrant(
+  sessionId: string,
+  effectiveSeq: number,
+  ts: string,
+): ConsentV1 {
+  return {
+    schema: CONSENT_SCHEMA_V1,
+    consentId: `consent-${sessionId}-${effectiveSeq}`,
+    sessionId,
+    action: "grant",
+    effectiveSeq,
+    ts,
+  };
+}
+
+/**
+ * Append a consent revocation for a session at the next effective sequence.
+ * Returns a new ConsentV1 record (append-only — never mutates the input).
+ */
+export function appendRevoke(
+  sessionId: string,
+  effectiveSeq: number,
+  ts: string,
+): ConsentV1 {
+  return {
+    schema: CONSENT_SCHEMA_V1,
+    consentId: `consent-${sessionId}-${effectiveSeq}`,
+    sessionId,
+    action: "revoke",
+    effectiveSeq,
+    ts,
+  };
+}
+
+/**
+ * Get the effective consent high-water for a session — the maximum effectiveSeq
+ * across all consent records for that session. Used by the dataset exporter
+ * to capture a single consent snapshot at export time.
+ */
+export function consentHighWater(
+  records: ReadonlyArray<ConsentV1>,
+  sessionId: string,
+): number {
+  let max = 0;
+  for (const r of records) {
+    if (r.sessionId === sessionId && r.effectiveSeq > max) {
+      max = r.effectiveSeq;
+    }
+  }
+  return max;
+}

package/src/vector-cortex/outcomes/dataset.ts

@@ -0,0 +1,132 @@
+/**
+ * outcomes/dataset.ts — VC8A dataset manifest builder.
+ *
+ * Groups outcome rows by (repo, session) so no group crosses
+ * train/calibration/held-out split boundaries. Revocations disappear from
+ * future manifests because the consent check excludes them.
+ *
+ * The manifest digest is reproducible: it is computed over the canonical
+ * sorted rows, so input order does not affect the digest.
+ *
+ * The build/digest functions are PURE. The flag gates ONLY the reporter seam,
+ * never the arithmetic.
+ *
+ * PREVENT-PI-004: no network. PREVENT-011: no `any` type.
+ */
+
+import { createHash } from "node:crypto";
+import {
+  DATASET_MANIFEST_SCHEMA_V1,
+  type ConsentV1,
+  type DatasetManifestV1,
+  type DatasetManifestRow,
+  type DatasetSplit,
+  type OutcomeV1,
+} from "./types.js";
+import { hasActiveConsent } from "./consent.js";
+
+/** SHA-256 over the canonical sorted rows. */
+export function manifestDigest(rows: ReadonlyArray<DatasetManifestRow>): string {
+  const sorted = [...rows].sort((a, b) => {
+    const ka = `${a.repoId}:${a.sessionId}:${a.outcomeId}`;
+    const kb = `${b.repoId}:${b.sessionId}:${b.outcomeId}`;
+    return ka < kb ? -1 : ka > kb ? 1 : 0;
+  });
+  const text = sorted
+    .map((r) => `${r.outcomeId}|${r.repoId}|${r.sessionId}|${r.split}`)
+    .join("\n");
+  return createHash("sha256").update(Buffer.from(text, "utf8")).digest("hex");
+}
+
+/**
+ * Split a list of session groups into train/calibration/held-out. Groups are
+ * assigned sequentially so no group crosses split boundaries.
+ */
+function assignSplits(
+  groupKeys: string[],
+): Map<string, DatasetSplit> {
+  const result = new Map<string, DatasetSplit>();
+  const n = groupKeys.length;
+  const trainEnd = Math.ceil(n * 0.7);
+  const calEnd = Math.ceil(n * 0.85);
+  for (let i = 0; i < n; i++) {
+    const split: DatasetSplit = i < trainEnd ? "train" : i < calEnd ? "calibration" : "held-out";
+    result.set(groupKeys[i], split);
+  }
+  return result;
+}
+
+/**
+ * Build a dataset manifest from outcomes, consent records, and a consent
+ * high-water. Only outcomes whose session has active consent at the
+ * high-water are included. Revoked sessions are excluded entirely.
+ *
+ * Throws OUT_CONSENT_MISSING if an outcome's session has no consent at all.
+ */
+export function buildManifest(
+  outcomes: ReadonlyArray<OutcomeV1>,
+  consentRecords: ReadonlyArray<ConsentV1>,
+  consentHighWaterValue: number,
+): DatasetManifestV1 {
+  const groups = new Map<string, { repoId: string; sessionId: string }>();
+  const included: OutcomeV1[] = [];
+
+  for (const outcome of outcomes) {
+    const highWater = consentHighWaterValue;
+    if (!hasActiveConsent(consentRecords, outcome.sessionId, highWater)) {
+      continue;
+    }
+    included.push(outcome);
+    const key = `${outcome.repoId}:${outcome.sessionId}`;
+    if (!groups.has(key)) {
+      groups.set(key, { repoId: outcome.repoId, sessionId: outcome.sessionId });
+    }
+  }
+
+  const groupKeys = [...groups.keys()].sort();
+  const splitMap = assignSplits(groupKeys);
+
+  const rows: DatasetManifestRow[] = included.map((o) => {
+    const key = `${o.repoId}:${o.sessionId}`;
+    const split = splitMap.get(key) ?? "held-out";
+    return {
+      outcomeId: o.outcomeId,
+      repoId: o.repoId,
+      sessionId: o.sessionId,
+      split,
+    };
+  });
+
+  const trainRows = rows.filter((r) => r.split === "train");
+  const calRows = rows.filter((r) => r.split === "calibration");
+  const heldRows = rows.filter((r) => r.split === "held-out");
+
+  return {
+    schema: DATASET_MANIFEST_SCHEMA_V1,
+    manifestId: `manifest-${manifestDigest(rows).slice(0, 16)}`,
+    rows,
+    splitDigests: {
+      "train": manifestDigest(trainRows),
+      "calibration": manifestDigest(calRows),
+      "held-out": manifestDigest(heldRows),
+    },
+    createdAt: new Date(0).toISOString(),
+  };
+}
+
+/**
+ * Check if a manifest has any nonconsented records. Returns false if every
+ * row's session has active consent at the given high-water.
+ */
+export function hasNonconsentedRecords(
+  manifest: DatasetManifestV1,
+  consentRecords: ReadonlyArray<ConsentV1>,
+  consentHighWaterValue: number,
+): boolean {
+  for (const row of manifest.rows) {
+    if (!hasActiveConsent(consentRecords, row.sessionId, consentHighWaterValue)) {
+      return true;
+    }
+  }
+  return false;
+}

package/src/vector-cortex/outcomes/emit.ts

@@ -0,0 +1,70 @@
+/**
+ * outcomes/emit.ts — VC8A reporter seam (FLAG-GATED).
+ *
+ * Mirrors the VC7C diagnostics-emit pattern: a thin `safe()` wrapper around an
+ * optional injected `emit`, and the two event names the sprint spec requires:
+ *   - `vector_cortex_outcome_appended` — an outcome was appended to the ledger.
+ *   - `vector_cortex_dataset_record_excluded` — a row was excluded from a manifest.
+ *
+ * FLAG SEMANTICS. The ledger/consent/dataset arithmetic STILL RUNS regardless
+ * of `MEGACOMPACT_VC8A`. The flag gates ONLY this reporting + dashboard seam:
+ * flag-off is byte-identical to the predecessor (VC7C).
+ *
+ * PAYLOAD DISCIPLINE. These events carry only the outcomeId/sessionId codes
+ * and aggregate counts — never prompt bytes, response text, or free-text.
+ *
+ * PREVENT-PI-004: no network. PREVENT-011: no `any` type.
+ */
+
+import { VC8A_ENABLED } from "../../config/vector-cortex.js";
+
+/** The two structured events the VC8A reporter emits. */
+export type OutcomeEventName =
+  | "vector_cortex_outcome_appended"
+  | "vector_cortex_dataset_record_excluded";
+
+/** Optional emit fn injected by the runtime; tests pass `undefined`. */
+export type OutcomeEmit = (name: string, payload: unknown) => void;
+
+/** Run `fn` only when an emit exists; a reporting failure is never fatal. */
+function safe(emit: OutcomeEmit | undefined, fn: (emit: OutcomeEmit) => void): void {
+  if (emit === undefined) return;
+  try {
+    fn(emit);
+  } catch {
+    // Non-fatal: a reporting failure must never break the agent loop.
+  }
+}
+
+/** Report an outcome appended to the ledger. Gated by the flag. */
+export function reportOutcomeAppended(
+  emit: OutcomeEmit | undefined,
+  outcome: { readonly outcomeId: string; readonly sessionId: string; readonly repoId: string },
+): void {
+  if (!VC8A_ENABLED()) return;
+  safe(emit, (e) =>
+    e("vector_cortex_outcome_appended", {
+      ts: undefined,
+      event: "vector_cortex_outcome_appended",
+      outcomeId: outcome.outcomeId,
+      sessionId: outcome.sessionId,
+      repoId: outcome.repoId,
+    }),
+  );
+}
+
+/** Report a row excluded from a dataset manifest. Gated by the flag. */
+export function reportDatasetRecordExcluded(
+  emit: OutcomeEmit | undefined,
+  excluded: { readonly outcomeId: string; readonly reason: string },
+): void {
+  if (!VC8A_ENABLED()) return;
+  safe(emit, (e) =>
+    e("vector_cortex_dataset_record_excluded", {
+      ts: undefined,
+      event: "vector_cortex_dataset_record_excluded",
+      outcomeId: excluded.outcomeId,
+      reason: excluded.reason,
+    }),
+  );
+}