@indigoai-us/hq-cloud 6.14.28 → 6.14.30

package/src/outcome-telemetry.ts

@@ -0,0 +1,639 @@
+/**
+ * Outcome-event collector — story-completion + project-shipped emitter
+ * (outcome-leaderboard US-004).
+ *
+ * Sibling to `./telemetry.ts` (token usage) and `./skill-telemetry.ts` (skill
+ * invocations). Where those diff `~/.claude/projects/**\/*.jsonl` session logs,
+ * this one diffs HQ PROJECT STATE against a persisted cursor at
+ * `~/.hq/outcome-telemetry-cursor.json`:
+ *
+ *   - `prd.json` `userStories[].passes` flipping `false → true`
+ *       → a `story-completed` outcome event.
+ *   - `board.json` project `status` transitioning to a DONE status
+ *       → a `project-shipped` outcome event.
+ *
+ * After each successful sync (the `all-complete` arm of `bin/sync-runner.ts`,
+ * via `defaultCollectTelemetry`), it walks `<hqRoot>/companies/*` for those two
+ * files, compares each transition-eligible value against the cursor, and POSTs
+ * new transitions to `/v1/outcome-events`. The cursor is only advanced for the
+ * transitions the server 2xx'd, so a transient outage retries next sync.
+ *
+ * Trust model (identical to `./telemetry.ts`): the caller's `personUid` is
+ * resolved SERVER-side from the Cognito JWT — never from the body. The wire row
+ * carries ONLY the outcome type, the ISO-8601 `occurredAt`, the resolved
+ * `companyUid`, `repo`/`branch` context, a `dedupeKey`, and the type-specific
+ * refs (`projectName`, and `storyId` for stories). NO prd/board file content
+ * beyond project name + story id + the status transition ever leaves the machine
+ * — enforced by the `toWireRow` allowlist, matching the server's KEEP_FIELDS in
+ * `apps/hq-pro/src/vault-service/handlers/outcome-events.ts`.
+ *
+ * companyUid resolution mirrors `./telemetry.ts`: the manifest at
+ * `<hqRoot>/companies/manifest.yaml` is parsed ONCE per run (`buildRepoCompanyMap`)
+ * and a project's owning company `cmp_*` uid is looked up by the `companies/<slug>`
+ * directory the prd/board lives under (`RepoCompanyMap.bySlug`). A project whose
+ * company is not cloud-backed resolves to no uid and is SKIPPED — an outcome event
+ * requires a company (the ingest handler makes companyUid a required field).
+ *
+ * dedupeKey (idempotency anchor — replays + multi-machine syncs never
+ * double-count):
+ *   - story-completed → `<companyUid>#<projectName>#<storyId>`
+ *   - project-shipped → `<companyUid>#<projectName>`
+ * The server's conditional PutItem collapses a re-synced event with the same
+ * dedupeKey to a single stored item.
+ *
+ * Errors are swallowed by design — an outcome collector must never abort or
+ * delay a sync (matches the existing collectors). The opt-in gate is the same
+ * `getTelemetryOptIn()` used by usage/skill telemetry.
+ */
+
+import { promises as fs } from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+
+import {
+  buildRepoCompanyMap,
+  type RepoCompanyMap,
+} from "./company-resolver.js";
+import type {
+  OutcomeEventsBatch,
+  OutcomeEventsIngestResult,
+  TelemetryOptInResponse,
+} from "./vault-client.js";
+
+// ── Public surface ────────────────────────────────────────────────────────────
+
+/**
+ * Minimal subset of `VaultClient` the collector needs. Declared as an interface
+ * so tests can inject a stub without a fetch mock. The real `VaultClient` from
+ * `./vault-client.js` satisfies this structurally.
+ */
+export interface OutcomeTelemetryClientSurface {
+  getTelemetryOptIn(): Promise<TelemetryOptInResponse>;
+  postOutcomeEvents(batch: OutcomeEventsBatch): Promise<OutcomeEventsIngestResult>;
+}
+
+export interface CollectOutcomeTelemetryOptions {
+  client: OutcomeTelemetryClientSurface;
+  /**
+   * HQ root — the collector scans `<hqRoot>/companies/*` for prd.json/board.json
+   * and resolves each project's owning company via `<hqRoot>/companies/
+   * manifest.yaml`. REQUIRED: with no hqRoot there is nothing to scan and no
+   * company to attribute, so the collector no-ops.
+   */
+  hqRoot?: string;
+  /** Override `~/.hq/outcome-telemetry-cursor.json` for tests. */
+  cursorPath?: string;
+  /** Override `~/.hq/menubar.json` (the offline opt-in fallback) for tests. */
+  menubarPath?: string;
+  /** Repo context stamped on every event (required common field). Defaults to `hq`. */
+  repo?: string;
+  /** Branch context stamped on every event (required common field). Defaults to `main`. */
+  branch?: string;
+  /** Injectable clock (ISO-8601) for deterministic `occurredAt` in tests. */
+  now?: () => string;
+  /** Diagnostic sink. No-op by default. */
+  log?: (msg: string) => void;
+}
+
+export interface CollectOutcomeTelemetryResult {
+  /** Whether the opt-in check resolved to true. When false, nothing else ran. */
+  enabled: boolean;
+  optInSource: "server" | "menubar-fallback" | "skipped";
+  /** prd.json + board.json files considered. */
+  filesScanned: number;
+  /** Total outcome events successfully POSTed. */
+  eventsSent: number;
+  /** Number of `POST /v1/outcome-events` requests made. */
+  batchesSent: number;
+}
+
+// ── Cursor schema ─────────────────────────────────────────────────────────────
+
+/**
+ * The cursor records the LAST-SEEN state we have already emitted for, keyed by
+ * dedupeKey. A transition is emitted only when the current state differs from
+ * what the cursor holds — so a story that is already `passes:true` in the cursor
+ * (emitted on a prior sync) never re-emits, and a story that regresses
+ * true→false→true re-emits (a genuine new completion). The dedupeKey is the SAME
+ * key the server dedups on, so client-cursor + server-conditional-put are two
+ * layers of the same idempotency guarantee.
+ *
+ * Each entry ALSO pins a STABLE `occurredAt` for the transition. The server
+ * stores an outcome row under `personUid` + `occurredAt#type#dedupeKey`, so a
+ * replay that regenerates `occurredAt` (another machine, or a POST that
+ * succeeded but whose cursor-write then failed) would land under a DIFFERENT
+ * sort key and double-count. The `occurredAt` is therefore assigned ONCE when
+ * the transition is first detected, persisted to the cursor BEFORE the POST, and
+ * reused verbatim on every subsequent detection of the same logical transition —
+ * so the same transition always emits the same event time and replays collapse.
+ */
+interface OutcomeCursorEntry {
+  /** The emitted transition marker (`"story-completed"` / `"project-shipped"`). */
+  type: string;
+  /** Stable ISO-8601 event time, assigned on first detection and reused on replay. */
+  occurredAt: string;
+  /**
+   * True once the server 2xx'd this transition. A `pending:true` entry has a
+   * pinned `occurredAt` (so a replay reuses it) but has NOT yet been confirmed
+   * emitted, so it is still eligible to (re-)send next sync.
+   */
+  pending?: boolean;
+}
+
+interface OutcomeCursor {
+  version: string;
+  /** dedupeKey → the emitted/pending transition entry. */
+  emitted: Record<string, OutcomeCursorEntry>;
+}
+
+function emptyCursor(): OutcomeCursor {
+  return { version: "2", emitted: {} };
+}
+
+/**
+ * Coerce a raw parsed `emitted` map into the current entry shape. Older cursors
+ * (version "1") stored `dedupeKey → typeString`; those entries have no pinned
+ * `occurredAt`, so they are migrated to `{ type, occurredAt: <legacy sentinel> }`
+ * and treated as already-confirmed (a v1 cursor only ever held CONFIRMED
+ * transitions, so migrating them as non-pending preserves "never re-emit").
+ */
+function normalizeEmitted(raw: unknown): Record<string, OutcomeCursorEntry> {
+  const out: Record<string, OutcomeCursorEntry> = {};
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) return out;
+  for (const [key, value] of Object.entries(raw as Record<string, unknown>)) {
+    if (typeof value === "string") {
+      // Legacy v1 entry: `dedupeKey → type`. No stored occurredAt; it was already
+      // confirmed-emitted, so keep it as a non-pending marker with no timestamp
+      // to reuse (empty string means "assign fresh if it somehow re-emits").
+      out[key] = { type: value, occurredAt: "" };
+    } else if (value && typeof value === "object" && !Array.isArray(value)) {
+      const v = value as Record<string, unknown>;
+      if (typeof v.type === "string") {
+        out[key] = {
+          type: v.type,
+          occurredAt: typeof v.occurredAt === "string" ? v.occurredAt : "",
+          ...(v.pending === true ? { pending: true } : {}),
+        };
+      }
+    }
+  }
+  return out;
+}
+
+async function loadCursor(cursorPath: string): Promise<OutcomeCursor> {
+  try {
+    const raw = await fs.readFile(cursorPath, "utf-8");
+    const parsed = JSON.parse(raw) as Partial<OutcomeCursor>;
+    if (
+      parsed &&
+      typeof parsed === "object" &&
+      parsed.emitted &&
+      typeof parsed.emitted === "object" &&
+      !Array.isArray(parsed.emitted)
+    ) {
+      return {
+        version: parsed.version ?? "2",
+        emitted: normalizeEmitted(parsed.emitted),
+      };
+    }
+  } catch {
+    // Missing / unparseable — start fresh.
+  }
+  return emptyCursor();
+}
+
+async function saveCursor(cursorPath: string, cursor: OutcomeCursor): Promise<void> {
+  // Atomic write: tmp + rename (matches ./telemetry.ts).
+  await fs.mkdir(path.dirname(cursorPath), { recursive: true });
+  const tmp = `${cursorPath}.tmp`;
+  await fs.writeFile(tmp, JSON.stringify(cursor, null, 2), "utf-8");
+  await fs.rename(tmp, cursorPath);
+}
+
+// ── Local opt-in fallback ─────────────────────────────────────────────────────
+
+async function readLocalTelemetryEnabled(menubarPath: string): Promise<boolean> {
+  try {
+    const raw = await fs.readFile(menubarPath, "utf-8");
+    const parsed = JSON.parse(raw) as { telemetryEnabled?: unknown };
+    return parsed.telemetryEnabled === true;
+  } catch {
+    return false;
+  }
+}
+
+// ── Transition detection ──────────────────────────────────────────────────────
+
+/**
+ * A board project status is treated as SHIPPED for these values. The Indigo
+ * board uses both `done` and `completed` for finished projects; both count as a
+ * project-shipped transition. Kept lowercase-compared so a `Done`/`DONE`
+ * casing variant still matches.
+ */
+const DONE_STATUSES = new Set(["done", "completed", "shipped", "complete"]);
+
+export function isDoneStatus(status: unknown): boolean {
+  return typeof status === "string" && DONE_STATUSES.has(status.trim().toLowerCase());
+}
+
+/** A single detected outcome transition, before it is shaped for the wire. */
+export interface OutcomeTransition {
+  type: "story-completed" | "project-shipped";
+  companyUid: string;
+  projectName: string;
+  /** Present only for story-completed. */
+  storyId?: string;
+  dedupeKey: string;
+}
+
+interface PrdShape {
+  name?: unknown;
+  userStories?: unknown;
+}
+
+interface BoardShape {
+  projects?: unknown;
+}
+
+/**
+ * Extract the story-completed transitions from a parsed prd.json. A transition
+ * is a story whose `passes` is currently `true` — the cursor decides whether it
+ * is NEW (false→true since last sync) vs already-emitted. `passes` that is not
+ * boolean `true`, or a story with no string `id`, is not a completion.
+ *
+ * `projectName` is the prd's `name`; a prd without one is skipped (the ingest
+ * requires a non-empty projectName). NOTHING else from the prd — no
+ * description, acceptance criteria, files, notes — is read.
+ */
+export function extractStoryTransitions(
+  prd: unknown,
+  companyUid: string,
+): OutcomeTransition[] {
+  if (!prd || typeof prd !== "object" || Array.isArray(prd)) return [];
+  const doc = prd as PrdShape;
+  const projectName = typeof doc.name === "string" ? doc.name.trim() : "";
+  if (!projectName) return [];
+  if (!Array.isArray(doc.userStories)) return [];
+
+  const out: OutcomeTransition[] = [];
+  for (const story of doc.userStories as unknown[]) {
+    if (!story || typeof story !== "object" || Array.isArray(story)) continue;
+    const s = story as Record<string, unknown>;
+    if (s.passes !== true) continue;
+    const storyId = typeof s.id === "string" ? s.id.trim() : "";
+    if (!storyId) continue;
+    out.push({
+      type: "story-completed",
+      companyUid,
+      projectName,
+      storyId,
+      dedupeKey: `${companyUid}#${projectName}#${storyId}`,
+    });
+  }
+  return out;
+}
+
+/**
+ * Extract the project-shipped transitions from a parsed board.json. A transition
+ * is a project whose `status` is a DONE status (see `isDoneStatus`). The
+ * `projectName` is the project's `title` (falling back to `id`); a project with
+ * neither is skipped. NOTHING else from the board — description, scope, app,
+ * prd_path, timestamps — is read.
+ */
+export function extractProjectTransitions(
+  board: unknown,
+  companyUid: string,
+): OutcomeTransition[] {
+  if (!board || typeof board !== "object" || Array.isArray(board)) return [];
+  const doc = board as BoardShape;
+  if (!Array.isArray(doc.projects)) return [];
+
+  const out: OutcomeTransition[] = [];
+  for (const project of doc.projects as unknown[]) {
+    if (!project || typeof project !== "object" || Array.isArray(project)) continue;
+    const p = project as Record<string, unknown>;
+    if (!isDoneStatus(p.status)) continue;
+    const title = typeof p.title === "string" ? p.title.trim() : "";
+    const id = typeof p.id === "string" ? p.id.trim() : "";
+    const projectName = title || id;
+    if (!projectName) continue;
+    out.push({
+      type: "project-shipped",
+      companyUid,
+      projectName,
+      dedupeKey: `${companyUid}#${projectName}`,
+    });
+  }
+  return out;
+}
+
+/**
+ * Shape a detected transition for the wire — the STRICT allowlist that proves
+ * no prd/board content beyond project name, story id, and the status transition
+ * is transmitted. Mirrors the server's KEEP_FIELDS + per-type ref rules in
+ * `apps/hq-pro/src/vault-service/handlers/outcome-events.ts`. `personUid` is
+ * never produced (resolved server-side from the JWT); any other field would be
+ * rejected 4xx by the ingest handler.
+ */
+export function toWireRow(
+  t: OutcomeTransition,
+  ctx: { occurredAt: string; repo: string; branch: string },
+): Record<string, unknown> {
+  const row: Record<string, unknown> = {
+    type: t.type,
+    occurredAt: ctx.occurredAt,
+    companyUid: t.companyUid,
+    repo: ctx.repo,
+    branch: ctx.branch,
+    dedupeKey: t.dedupeKey,
+    projectName: t.projectName,
+  };
+  if (t.type === "story-completed" && t.storyId !== undefined) {
+    row.storyId = t.storyId;
+  }
+  return row;
+}
+
+// ── Filesystem scan ────────────────────────────────────────────────────────────
+
+/**
+ * Resolve a company DIRECTORY name (`companies/<slug>`) to its owning company's
+ * `cmp_*` uid via the manifest slug→uid map. A slug with no cloud-backed
+ * manifest entry resolves to undefined and its projects are skipped.
+ */
+function companyUidForSlug(slug: string, map: RepoCompanyMap): string | undefined {
+  return map.bySlug.get(slug);
+}
+
+/** List the immediate subdirectory names of `dir` (company slugs). */
+async function listCompanySlugs(companiesRoot: string): Promise<string[]> {
+  try {
+    const entries = await fs.readdir(companiesRoot, { withFileTypes: true });
+    return entries.filter((e) => e.isDirectory()).map((e) => e.name);
+  } catch {
+    return [];
+  }
+}
+
+/** Recursively collect every `prd.json` under `root`. Errors are treated as
+ *  absent (missing dir / EACCES), matching the other collectors' walkers. */
+async function listPrdFiles(root: string): Promise<string[]> {
+  const out: string[] = [];
+  async function walk(dir: string): Promise<void> {
+    let entries;
+    try {
+      entries = await fs.readdir(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const ent of entries) {
+      const full = path.join(dir, ent.name);
+      if (ent.isDirectory()) {
+        await walk(full);
+      } else if (ent.isFile() && ent.name === "prd.json") {
+        out.push(full);
+      }
+    }
+  }
+  await walk(root);
+  return out;
+}
+
+async function readJsonFile(filePath: string): Promise<unknown | undefined> {
+  try {
+    const raw = await fs.readFile(filePath, "utf-8");
+    return JSON.parse(raw);
+  } catch {
+    return undefined;
+  }
+}
+
+// ── Field / row bounds ───────────────────────────────────────────────────────
+
+/**
+ * Per-string-field character ceiling enforced by the ingest handler (mirrors the
+ * 2048-char IAM/field limit). A projectName / storyId longer than this makes the
+ * server reject the WHOLE batch, so an over-long field on ONE local project must
+ * not be allowed to poison up to 199 other valid outcomes.
+ */
+export const MAX_FIELD_CHARS = 2048;
+
+/**
+ * Per-event serialized-byte ceiling (4 KB). The server rejects a whole batch if
+ * any single event JSON exceeds this, so an event that would blow the limit is
+ * dropped locally rather than sent.
+ */
+export const MAX_EVENT_BYTES = 4 * 1024;
+
+/**
+ * Decide whether a shaped wire row is within the ingest limits. The
+ * dedupe-relevant fields (companyUid / projectName / storyId, which compose the
+ * dedupeKey) CANNOT be truncated without changing the identity of the outcome,
+ * so an over-limit transition is SKIPPED wholesale rather than mangled — one
+ * malformed local project must never block the valid outcomes in its batch.
+ *
+ * Returns `null` when the row is acceptable, or a human-readable reason string
+ * when it must be skipped (so the caller can log the skip).
+ */
+export function wireRowRejectReason(row: Record<string, unknown>): string | null {
+  for (const [key, value] of Object.entries(row)) {
+    if (typeof value === "string" && value.length > MAX_FIELD_CHARS) {
+      return `field "${key}" exceeds ${MAX_FIELD_CHARS} chars (${value.length})`;
+    }
+  }
+  const bytes = Buffer.byteLength(JSON.stringify(row), "utf-8");
+  if (bytes > MAX_EVENT_BYTES) {
+    return `event exceeds ${MAX_EVENT_BYTES} bytes (${bytes})`;
+  }
+  return null;
+}
+
+// ── Batching ───────────────────────────────────────────────────────────────────
+
+// The ingest caps a batch at 500 events; stay comfortably under it. A real sync
+// flushes a small number of transitions, so this bound is rarely reached.
+const MAX_BATCH_EVENTS = 200;
+
+// ── Main entry point ──────────────────────────────────────────────────────────
+
+/**
+ * Scan HQ project state, detect new story-completed / project-shipped
+ * transitions since the last sync, and POST them.
+ *
+ * Fire-and-forget from the caller's perspective: all errors are caught
+ * internally and surfaced only via `log`. The cursor advances ONLY for
+ * transitions whose batch the server accepted, so a failed POST re-sends next
+ * sync (and the server-side dedupe makes that re-send idempotent).
+ */
+export async function collectAndSendOutcomeTelemetry(
+  opts: CollectOutcomeTelemetryOptions,
+): Promise<CollectOutcomeTelemetryResult> {
+  const home = os.homedir();
+  const cursorPath =
+    opts.cursorPath ?? path.join(home, ".hq", "outcome-telemetry-cursor.json");
+  const menubarPath = opts.menubarPath ?? path.join(home, ".hq", "menubar.json");
+  const repo = opts.repo ?? "hq";
+  const branch = opts.branch ?? "main";
+  const nowIso = opts.now ?? (() => new Date().toISOString());
+  const log = opts.log ?? (() => {});
+
+  // 1. Opt-in gate — same server-authoritative check as usage/skill telemetry,
+  //    with the local menubar.json fallback.
+  let enabled: boolean;
+  let optInSource: CollectOutcomeTelemetryResult["optInSource"];
+  try {
+    const resp = await opts.client.getTelemetryOptIn();
+    enabled = resp.enabled === true;
+    optInSource = "server";
+  } catch (err) {
+    log(
+      `[outcome-telemetry] opt-in check failed (${(err as Error).message ?? err}) — falling back to local menubar.json`,
+    );
+    enabled = await readLocalTelemetryEnabled(menubarPath);
+    optInSource = "menubar-fallback";
+  }
+
+  if (!enabled) {
+    return { enabled: false, optInSource, filesScanned: 0, eventsSent: 0, batchesSent: 0 };
+  }
+
+  // With no hqRoot there is nothing to scan and no company to attribute.
+  if (!opts.hqRoot) {
+    return { enabled: true, optInSource, filesScanned: 0, eventsSent: 0, batchesSent: 0 };
+  }
+
+  // 2. Resolve slug→companyUid ONCE per run (mirrors ./telemetry.ts).
+  const repoCompanyMap: RepoCompanyMap = await buildRepoCompanyMap(opts.hqRoot);
+
+  const companiesRoot = path.join(opts.hqRoot, "companies");
+  const slugs = await listCompanySlugs(companiesRoot);
+
+  // 3. Detect all current transitions across every cloud-backed company.
+  const cursor = await loadCursor(cursorPath);
+  const transitions: OutcomeTransition[] = [];
+  let filesScanned = 0;
+
+  for (const slug of slugs) {
+    const companyUid = companyUidForSlug(slug, repoCompanyMap);
+    // No cloud-backed company for this slug → its projects cannot be attributed
+    // (companyUid is a required ingest field), so skip the whole directory.
+    if (companyUid === undefined) continue;
+
+    const companyDir = path.join(companiesRoot, slug);
+
+    // 3a. Board projects (project-shipped). One board.json per company.
+    const boardPath = path.join(companyDir, "board.json");
+    const board = await readJsonFile(boardPath);
+    if (board !== undefined) {
+      filesScanned++;
+      for (const transition of extractProjectTransitions(board, companyUid)) {
+        transitions.push(transition);
+      }
+    }
+
+    // 3b. Project stories (story-completed). Many prd.json under projects/.
+    const prdFiles = await listPrdFiles(path.join(companyDir, "projects"));
+    for (const prdPath of prdFiles) {
+      const prd = await readJsonFile(prdPath);
+      if (prd === undefined) continue;
+      filesScanned++;
+      for (const transition of extractStoryTransitions(prd, companyUid)) {
+        transitions.push(transition);
+      }
+    }
+  }
+
+  // 4. Keep only transitions the cursor has NOT already CONFIRMED emitting.
+  //    Dedupe within this run too (a dedupeKey seen twice in one scan is one
+  //    event). A `pending` cursor entry (occurredAt pinned, POST not yet 2xx'd)
+  //    is still eligible — it re-sends with its ORIGINAL occurredAt.
+  const seenThisRun = new Set<string>();
+  const pending: OutcomeTransition[] = [];
+  for (const t of transitions) {
+    if (seenThisRun.has(t.dedupeKey)) continue;
+    seenThisRun.add(t.dedupeKey);
+    const entry = cursor.emitted[t.dedupeKey];
+    if (entry && entry.type === t.type && entry.pending !== true) continue; // confirmed already
+    pending.push(t);
+  }
+
+  if (pending.length === 0) {
+    return { enabled: true, optInSource, filesScanned, eventsSent: 0, batchesSent: 0 };
+  }
+
+  // 5. Assign a STABLE occurredAt per transition and shape the wire row.
+  //    - If the cursor already pins an occurredAt for this dedupeKey+type
+  //      (a prior sync detected it), REUSE it verbatim so a replay lands under
+  //      the same server sort key and collapses to one row.
+  //    - Otherwise assign a fresh occurredAt now and pin it in the cursor.
+  //    Rows that would exceed the ingest field/size limits are SKIPPED (their
+  //    dedupe-identifying fields can't be truncated without changing identity),
+  //    so one malformed local project cannot block the valid outcomes.
+  const now = nowIso();
+  interface Sendable {
+    transition: OutcomeTransition;
+    row: Record<string, unknown>;
+  }
+  const sendable: Sendable[] = [];
+  for (const t of pending) {
+    const existing = cursor.emitted[t.dedupeKey];
+    const occurredAt =
+      existing && existing.type === t.type && existing.occurredAt
+        ? existing.occurredAt
+        : now;
+    const row = toWireRow(t, { occurredAt, repo, branch });
+    const reject = wireRowRejectReason(row);
+    if (reject) {
+      log(
+        `[outcome-telemetry] skipping ${t.type} ${t.dedupeKey}: ${reject}`,
+      );
+      continue;
+    }
+    // Pin the stable occurredAt BEFORE the POST so a crash between POST-success
+    // and cursor-flush still reuses the same timestamp on the next detection.
+    cursor.emitted[t.dedupeKey] = { type: t.type, occurredAt, pending: true };
+    sendable.push({ transition: t, row });
+  }
+
+  // Persist the pinned-but-pending timestamps before sending, so a re-detection
+  // after a partial failure reuses the same occurredAt.
+  await saveCursor(cursorPath, cursor);
+
+  if (sendable.length === 0) {
+    return { enabled: true, optInSource, filesScanned, eventsSent: 0, batchesSent: 0 };
+  }
+
+  // 6. Flush in server-sized batches; confirm the cursor per SUCCESSFUL batch.
+  let eventsSent = 0;
+  let batchesSent = 0;
+
+  for (let i = 0; i < sendable.length; i += MAX_BATCH_EVENTS) {
+    const chunk = sendable.slice(i, i + MAX_BATCH_EVENTS);
+    const events = chunk.map((s) => s.row);
+    try {
+      await opts.client.postOutcomeEvents({ events });
+      batchesSent++;
+      eventsSent += events.length;
+      // Confirm these transitions so they never re-send (server-side dedupe also
+      // collapses a replay if the cursor is later lost), keeping their pinned
+      // occurredAt.
+      for (const s of chunk) {
+        cursor.emitted[s.transition.dedupeKey] = {
+          type: s.transition.type,
+          occurredAt: s.row.occurredAt as string,
+        };
+      }
+    } catch (err) {
+      log(
+        `[outcome-telemetry] postOutcomeEvents failed (${(err as Error).message ?? err}) — ${chunk.length} rows re-send next sync`,
+      );
+      // Cursor entries stay `pending:true` with their pinned occurredAt — next
+      // sync retries with the SAME timestamp.
+    }
+  }
+
+  // 7. Persist the cursor (confirmed transitions dropped `pending`).
+  await saveCursor(cursorPath, cursor);
+
+  return { enabled: true, optInSource, filesScanned, eventsSent, batchesSent };
+}