session-orchestrator 3.16.0 → 3.19.0

package/scripts/lib/spiral-carryover.mjs

@@ -23,10 +23,21 @@
  *
  * This module intentionally does NOT reuse `scripts/lib/vault-backfill/glab.mjs`
  * — that helper is vault-specific and wider in scope than needed here.
+ *
+ * Host pinning (#839): every `glab`/`gh` spawn below (the dedup lookup AND the
+ * `issue create` write) is pinned to the resolved repo via `-R <spec>`. A bare
+ * spawn falls back to the ambient `GITLAB_HOST`/`GH_HOST`, which can silently
+ * resolve to the WRONG GitLab instance on a multi-host machine — for a WRITE
+ * path (`issue create`) that means either filing into the wrong project, or
+ * failing open and defeating `findExistingLabeledIssue`'s dedup (which itself
+ * fails open to `{exists:false}` on any CLI error), risking double-filed
+ * issues. See `scripts/lib/vcs-repo-spec.mjs` for the full rationale.
  */
 
 import { execFileSync } from 'node:child_process';
 import { digestSha256Short } from './crypto-digest-utils.mjs';
+import { chargeIssueBudget, formatBlockReason } from './issue-budget.mjs';
+import { resolveRepoSpec } from './vcs-repo-spec.mjs';
 
 /**
  * Compute a stable 8-char sha256 hash of a task description.
@@ -51,13 +62,57 @@ function truncate(s, max) {
   return `${str.slice(0, Math.max(0, max - 1))}…`;
 }
 
+/**
+ * True when the argv describes an issue-CREATE call (not a list/search).
+ * The dedup lookups in this module also go through `runCli`, and those must
+ * never be charged against the issue budget.
+ *
+ * @param {string} cmd
+ * @param {string[]} args
+ * @returns {boolean}
+ */
+function isIssueCreateArgv(cmd, args) {
+  if (cmd !== 'gh' && cmd !== 'glab') return false;
+  if (!Array.isArray(args) || args.length < 2) return false;
+  return args[0] === 'issue' && (args[1] === 'create' || args[1] === 'new');
+}
+
 /**
  * Run a CLI command and return { ok, stdout, stderr }. Never throws.
+ *
+ * ISSUE-BUDGET GATE (both Node producers funnel through here): before shelling
+ * out to an issue-create call, the same `chargeIssueBudget` decision the
+ * `pre-bash-issue-budget` hook applies is evaluated here — otherwise the
+ * programmatic path would be a hole straight through the shell-level cap.
+ *
+ * In practice BOTH current callers are exempt by class (`createSpiralCarryoverIssue`
+ * emits `[Carryover] [SPIRAL|FAILED] …`, `createBrokenWindowIssue` emits the
+ * `broken-window` label), so this gate is a no-op for them by design — that is
+ * exactly the session-end promise at SKILL.md:319 / :1113 being preserved. It
+ * bites for any FUTURE non-exempt producer added to this module.
+ *
  * @param {string} cmd
  * @param {string[]} args
- * @returns {{ ok: boolean, stdout: string, stderr: string }}
+ * @returns {{ ok: boolean, stdout: string, stderr: string, budgetBlocked?: boolean }}
  */
 function runCli(cmd, args) {
+  if (isIssueCreateArgv(cmd, args)) {
+    try {
+      const repoRoot = process.env.CLAUDE_PROJECT_DIR || process.cwd();
+      const titleIdx = args.indexOf('--title');
+      const verdict = chargeIssueBudget({
+        repoRoot,
+        sessionId: process.env.CLAUDE_SESSION_ID || null,
+        command: [cmd, ...args].join(' '),
+        title: titleIdx >= 0 ? (args[titleIdx + 1] ?? null) : null,
+      });
+      if (verdict.decision === 'block') {
+        return { ok: false, stdout: '', stderr: formatBlockReason(verdict), budgetBlocked: true };
+      }
+    } catch {
+      // Fail open — a budget-bookkeeping failure must never lose a carryover.
+    }
+  }
   try {
     const stdout = execFileSync(cmd, args, { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] });
     return { ok: true, stdout: String(stdout ?? ''), stderr: '' };
@@ -96,18 +151,33 @@ function parseIssueCreateOutput(stdout) {
  * Returns `{ exists: false }` on any CLI failure — caller treats this as
  * "probably no duplicate" and proceeds with creation (fail-open).
  *
- * @param {{ taskHash: string, label: string, vcs?: 'gitlab' | 'github' }} opts
+ * @param {{
+ *   taskHash: string,
+ *   label: string,
+ *   vcs?: 'gitlab' | 'github',
+ *   repoRoot?: string,
+ *   resolveRepoSpecFn?: (opts: { repoRoot: string, vcs: 'gitlab' | 'github' }) => string | undefined
+ * }} opts
  * @returns {Promise<{ exists: boolean, issueId?: number, issueUrl?: string }>}
  */
-async function findExistingLabeledIssue({ taskHash, label, vcs = 'gitlab' } = {}) {
+async function findExistingLabeledIssue({
+  taskHash,
+  label,
+  vcs = 'gitlab',
+  repoRoot = process.cwd(),
+  resolveRepoSpecFn = resolveRepoSpec,
+} = {}) {
   if (!taskHash || typeof taskHash !== 'string') {
     return { exists: false };
   }
 
+  const vcsResolved = vcs === 'github' ? 'github' : 'gitlab';
+  const spec = resolveRepoSpecFn({ repoRoot, vcs: vcsResolved });
+
   try {
-    if (vcs === 'github') {
+    if (vcsResolved === 'github') {
       // gh: list open issues carrying the label; body match is done locally.
-      const res = runCli('gh', [
+      const args = [
         'issue',
         'list',
         '--label',
@@ -118,7 +188,9 @@ async function findExistingLabeledIssue({ taskHash, label, vcs = 'gitlab' } = {}
         '100',
         '--json',
         'number,url,body',
-      ]);
+      ];
+      if (spec) args.push('-R', spec);
+      const res = runCli('gh', args);
       if (!res.ok) return { exists: false };
       let arr;
       try {
@@ -136,16 +208,9 @@ async function findExistingLabeledIssue({ taskHash, label, vcs = 'gitlab' } = {}
     }
 
     // Default: gitlab via glab.
-    const res = runCli('glab', [
-      'issue',
-      'list',
-      '--label',
-      label,
-      '--per-page',
-      '100',
-      '--output',
-      'json',
-    ]);
+    const args = ['issue', 'list', '--label', label, '--per-page', '100', '--output', 'json'];
+    if (spec) args.push('-R', spec);
+    const res = runCli('glab', args);
     if (!res.ok) return { exists: false };
     let arr;
     try {
@@ -173,22 +238,42 @@ async function findExistingLabeledIssue({ taskHash, label, vcs = 'gitlab' } = {}
  * Check whether a carryover issue already exists for this task.
  * Thin wrapper over `findExistingLabeledIssue` with the `type:carryover` label.
  *
- * @param {{ taskHash: string, vcs?: 'gitlab' | 'github' }} opts
+ * @param {{
+ *   taskHash: string,
+ *   vcs?: 'gitlab' | 'github',
+ *   repoRoot?: string,
+ *   resolveRepoSpecFn?: (opts: { repoRoot: string, vcs: 'gitlab' | 'github' }) => string | undefined
+ * }} opts
  * @returns {Promise<{ exists: boolean, issueId?: number, issueUrl?: string }>}
  */
-export async function findExistingCarryover({ taskHash, vcs = 'gitlab' } = {}) {
-  return findExistingLabeledIssue({ taskHash, label: 'type:carryover', vcs });
+export async function findExistingCarryover({
+  taskHash,
+  vcs = 'gitlab',
+  repoRoot = process.cwd(),
+  resolveRepoSpecFn = resolveRepoSpec,
+} = {}) {
+  return findExistingLabeledIssue({ taskHash, label: 'type:carryover', vcs, repoRoot, resolveRepoSpecFn });
 }
 
 /**
  * Check whether a broken-window closure issue already exists for this task.
  * Thin wrapper over `findExistingLabeledIssue` with the `broken-window` label.
  *
- * @param {{ taskHash: string, vcs?: 'gitlab' | 'github' }} opts
+ * @param {{
+ *   taskHash: string,
+ *   vcs?: 'gitlab' | 'github',
+ *   repoRoot?: string,
+ *   resolveRepoSpecFn?: (opts: { repoRoot: string, vcs: 'gitlab' | 'github' }) => string | undefined
+ * }} opts
  * @returns {Promise<{ exists: boolean, issueId?: number, issueUrl?: string }>}
  */
-export async function findExistingBrokenWindow({ taskHash, vcs = 'gitlab' } = {}) {
-  return findExistingLabeledIssue({ taskHash, label: 'broken-window', vcs });
+export async function findExistingBrokenWindow({
+  taskHash,
+  vcs = 'gitlab',
+  repoRoot = process.cwd(),
+  resolveRepoSpecFn = resolveRepoSpec,
+} = {}) {
+  return findExistingLabeledIssue({ taskHash, label: 'broken-window', vcs, repoRoot, resolveRepoSpecFn });
 }
 
 /**
@@ -245,7 +330,9 @@ function buildCarryoverBody({ taskDescription, kind, context, taskHash }) {
  *   kind: 'SPIRAL' | 'FAILED',
  *   context: string,
  *   priority?: 'high' | 'medium',
- *   vcs?: 'gitlab' | 'github'
+ *   vcs?: 'gitlab' | 'github',
+ *   repoRoot?: string,
+ *   resolveRepoSpecFn?: (opts: { repoRoot: string, vcs: 'gitlab' | 'github' }) => string | undefined
  * }} opts
  * @returns {Promise<{
  *   created: boolean,
@@ -261,6 +348,8 @@ export async function createSpiralCarryoverIssue({
   context,
   priority = 'high',
   vcs = 'gitlab',
+  repoRoot = process.cwd(),
+  resolveRepoSpecFn = resolveRepoSpec,
 } = {}) {
   try {
     if (kind !== 'SPIRAL' && kind !== 'FAILED') {
@@ -272,10 +361,19 @@ export async function createSpiralCarryoverIssue({
     }
     const vcsResolved = vcs === 'github' ? 'github' : 'gitlab';
 
+    // Resolve the -R/--repo host-pinning spec ONCE (#839); reuse the same
+    // resolved value for the dedup lookup below instead of re-resolving.
+    const spec = resolveRepoSpecFn({ repoRoot, vcs: vcsResolved });
+
     const taskHash = computeTaskHash(taskDescription);
 
     // Dedup check first.
-    const existing = await findExistingCarryover({ taskHash, vcs: vcsResolved });
+    const existing = await findExistingCarryover({
+      taskHash,
+      vcs: vcsResolved,
+      repoRoot,
+      resolveRepoSpecFn: () => spec,
+    });
     if (existing.exists) {
       return {
         created: false,
@@ -288,7 +386,7 @@ export async function createSpiralCarryoverIssue({
     const truncatedDesc = truncate(String(taskDescription ?? '').trim() || '(untitled task)', 80);
     const title = `[Carryover] [${kind}] ${truncatedDesc}`;
     const body = buildCarryoverBody({ taskDescription, kind, context, taskHash });
-    const labels = `priority:${priority},status:ready,type:carryover`;
+    const labels = `priority::${priority},status:ready,type:carryover`;
 
     let cmd;
     let args;
@@ -299,6 +397,7 @@ export async function createSpiralCarryoverIssue({
       cmd = 'glab';
       args = ['issue', 'create', '--title', title, '--description', body, '--label', labels];
     }
+    if (spec) args.push('-R', spec);
 
     const res = runCli(cmd, args);
     if (!res.ok) {
@@ -403,13 +502,15 @@ function buildBrokenWindowBody({ item, taskHash, dueDate, vcs }) {
  *   5. Parse stdout for the issue URL and return `{ created: true, issueId, issueUrl, due }`.
  *
  * Never throws. On any CLI failure returns `{ created: false, skipped: 'error', error }`.
- * `repoRoot` is accepted for signature symmetry with the caller but currently
- * unused — `glab`/`gh` resolve the project from the invoking cwd.
+ * `repoRoot` defaults to `process.cwd()` and is used (#839) to resolve the
+ * `-R`/`--repo` host-pinning spec via `resolveRepoSpecFn` — previously accepted
+ * only for signature symmetry and left unused.
  *
  * @param {{
  *   item: { title?: string, source?: string, description?: string, sessionId?: string },
  *   dueDays?: number,
  *   repoRoot?: string,
+ *   resolveRepoSpecFn?: (opts: { repoRoot: string, vcs: 'gitlab' | 'github' }) => string | undefined,
  *   vcs?: 'gitlab' | 'github'
  * }} opts
  * @returns {Promise<{
@@ -424,7 +525,8 @@ function buildBrokenWindowBody({ item, taskHash, dueDate, vcs }) {
 export async function createBrokenWindowIssue({
   item,
   dueDays = 7,
-  repoRoot: _repoRoot,
+  repoRoot = process.cwd(),
+  resolveRepoSpecFn = resolveRepoSpec,
   vcs = 'gitlab',
 } = {}) {
   try {
@@ -437,11 +539,20 @@ export async function createBrokenWindowIssue({
 
     const dueDate = computeDueDate(dueDays);
 
+    // Resolve the -R/--repo host-pinning spec ONCE (#839); reuse the same
+    // resolved value for the dedup lookup below instead of re-resolving.
+    const spec = resolveRepoSpecFn({ repoRoot, vcs: vcsResolved });
+
     // Dedup key: (source, title) pair — two different sources with the same
     // title are genuinely distinct broken windows and each file separately.
     const taskHash = computeTaskHash(`${source}::${title}`);
 
-    const existing = await findExistingBrokenWindow({ taskHash, vcs: vcsResolved });
+    const existing = await findExistingBrokenWindow({
+      taskHash,
+      vcs: vcsResolved,
+      repoRoot,
+      resolveRepoSpecFn: () => spec,
+    });
     if (existing.exists) {
       return {
         created: false,
@@ -453,7 +564,7 @@ export async function createBrokenWindowIssue({
 
     const issueTitle = `[Broken-Window] ${truncate(title, 80)}`;
     const body = buildBrokenWindowBody({ item, taskHash, dueDate, vcs: vcsResolved });
-    const labels = 'broken-window,priority:high';
+    const labels = 'broken-window,priority::high';
 
     let cmd;
     let args;
@@ -475,6 +586,7 @@ export async function createBrokenWindowIssue({
         dueDate,
       ];
     }
+    if (spec) args.push('-R', spec);
 
     const res = runCli(cmd, args);
     if (!res.ok) {

package/scripts/lib/state-md/mission-status.mjs

@@ -76,6 +76,46 @@ export function writeMissionStatus(contents, missionStatusArray) {
   return updateFrontmatterFields(contents, { 'mission-status': missionStatusArray.slice() });
 }
 
+/**
+ * Mirrors `status` onto the frontmatter `mission-status` entry whose `id` matches
+ * `taskId`, returning a NEW frontmatter object (copy-on-write at object, array and
+ * entry level — the input is never mutated, which keeps `parseMissionStatus`'s
+ * shallow-copy contract intact for anything else holding the same nested entries).
+ *
+ * UPDATE-ONLY by design: when the key is absent, is not an array, or holds no entry
+ * with a matching `id`, the frontmatter is returned unchanged. It is deliberately
+ * neither created nor an error, because `setMissionStatus(contents, taskId, status)`
+ * knows only `id` and `status` — it lacks the `task` and `wave` fields that
+ * `validateMissionStatusEntry` (mission-status-schema.mjs) requires, so a synthesised
+ * entry would be schema-invalid yet look authoritative to frontmatter consumers such
+ * as `vault-status/narrative-mirror.mjs`. Throwing is likewise excluded by the
+ * never-throw contract of `setMissionStatus`.
+ *
+ * `status` is mirrored verbatim without an enum check on purpose: gating it would
+ * reintroduce the exact divergence (body says X, frontmatter says Y) this sync exists
+ * to remove. An out-of-enum value now lands on BOTH surfaces, where the repo's own
+ * validator can see it.
+ *
+ * @param {object} frontmatter
+ * @param {string} taskId
+ * @param {string} status
+ * @returns {object}
+ */
+function syncFrontmatterMissionStatus(frontmatter, taskId, status) {
+  if (frontmatter === null || typeof frontmatter !== 'object' || Array.isArray(frontmatter)) {
+    return frontmatter;
+  }
+  const raw = frontmatter['mission-status'];
+  if (!Array.isArray(raw)) return frontmatter;
+  const idx = raw.findIndex(
+    (e) => e !== null && typeof e === 'object' && !Array.isArray(e) && e.id === taskId
+  );
+  if (idx === -1) return frontmatter;
+  const entries = raw.slice();
+  entries[idx] = { ...raw[idx], status };
+  return { ...frontmatter, 'mission-status': entries };
+}
+
 /**
  * Sets (or updates) the mission status for a single task in the `## Mission Status` body
  * section of STATE.md. Creates the section if it does not exist.
@@ -83,6 +123,13 @@ export function writeMissionStatus(contents, missionStatusArray) {
  * Format of each entry in the section:
  *   - <taskId>: <status> (updated <ISO timestamp>)
  *
+ * Also mirrors `status` into the frontmatter `mission-status` entry with the same `id`
+ * (issue #960 — one writer, two sinks). The body section is what the coordinator writes
+ * during a wave; the frontmatter array is what `parseMissionStatus` consumers read
+ * (`vault-status/narrative-mirror.mjs`, session-end Phase 1.9/1.10). Before this sync the
+ * live writer and the reader sat on different surfaces and drifted apart in both
+ * directions. Frontmatter mirroring is UPDATE-ONLY — see `syncFrontmatterMissionStatus`.
+ *
  * Pure function — no I/O. Returns original `contents` unchanged on bad input.
  *
  * @param {string} contents - Current STATE.md file contents (string)
@@ -97,6 +144,9 @@ export function setMissionStatus(contents, taskId, status) {
   const parsed = parseStateMd(contents);
   if (parsed === null) return contents;
 
+  // Computed once so every return path below emits the same synced frontmatter.
+  const frontmatter = syncFrontmatterMissionStatus(parsed.frontmatter, taskId, status);
+
   const timestamp = new Date().toISOString();
   const bullet = `- ${taskId}: ${status} (updated ${timestamp})`;
   const lines = parsed.body.split('\n');
@@ -115,7 +165,7 @@ export function setMissionStatus(contents, taskId, status) {
     let bodyOut = parsed.body;
     if (!bodyOut.endsWith('\n')) bodyOut += '\n';
     bodyOut += `\n## Mission Status\n\n${bullet}\n`;
-    return serializeStateMd({ frontmatter: parsed.frontmatter, body: bodyOut });
+    return serializeStateMd({ frontmatter, body: bodyOut });
   }
 
   // Find end of section: next ## heading or end of lines
@@ -155,11 +205,11 @@ export function setMissionStatus(contents, taskId, status) {
       const before = lines.slice(0, headingIdx + 1);
       const after = lines.slice(insertAt);
       const rebuilt = [...before, '', bullet, ...after];
-      return serializeStateMd({ frontmatter: parsed.frontmatter, body: rebuilt.join('\n') });
+      return serializeStateMd({ frontmatter, body: rebuilt.join('\n') });
     }
   }
 
-  return serializeStateMd({ frontmatter: parsed.frontmatter, body: lines.join('\n') });
+  return serializeStateMd({ frontmatter, body: lines.join('\n') });
 }
 
 /**

package/scripts/lib/subagents-schema.mjs

@@ -14,7 +14,20 @@
  *   schema_version    1 (integer)
  *
  * Required for event='stop':
- *   duration_ms       positive integer — wall-clock time from start to stop
+ *   duration_ms       positive integer | null — wall-clock time from start to stop.
+ *                     null means "unknown": the producer could not recover a
+ *                     matching 'start' record to measure against (#917). null is
+ *                     an honest absence and is NOT interchangeable with 0.
+ *
+ * duration_ms provenance (#917) — why the write path and the read path differ:
+ *   Before #917 the producer defaulted duration_ms to 0 whenever the harness
+ *   omitted it, which it always does. Every stop record written up to that point
+ *   therefore carries a fabricated 0 (measured 2026-07-30: 2770 of 2770 stop
+ *   records in .orchestrator/metrics/subagents.jsonl). Those records still have
+ *   to read and migrate cleanly, so validation is lenient BY DEFAULT and accepts
+ *   0. Callers on the WRITE path opt into `{ strictDuration: true }`, which
+ *   rejects 0 outright — appendSubagent() does this, so no new record can
+ *   reintroduce the fabricated zero.
  *
  * Optional:
  *   agent_type        string | null — e.g. 'explore', 'writer', 'test-writer'
@@ -70,14 +83,21 @@ export class ValidationError extends Error {
  * violation. Does NOT mutate the input.
  *
  * Required fields: timestamp, event, agent_id, schema_version.
- * Additional requirement when event='stop': duration_ms (positive integer).
+ * Additional requirement when event='stop': duration_ms (integer or null).
  * Optional: agent_type, parent_session_id, token_input, token_output.
  *
  * @param {object} entry
+ * @param {object} [options]
+ * @param {boolean} [options.strictDuration=false] — when true, a stop record's
+ *   duration_ms must be a POSITIVE integer or null; 0 is rejected. Write-path
+ *   callers set this; readers/migrations leave it false so the pre-#917 corpus
+ *   (every stop record carrying a fabricated 0) still validates. See the module
+ *   header § duration_ms provenance.
  * @returns {object} the entry (unchanged) — validation is side-effect-free
  * @throws {ValidationError}
  */
-export function validateSubagent(entry) {
+export function validateSubagent(entry, options = {}) {
+  const strictDuration = options?.strictDuration === true;
   if (!entry || typeof entry !== 'object') {
     throw new ValidationError('subagent record must be a non-null object');
   }
@@ -114,15 +134,24 @@ export function validateSubagent(entry) {
     throw new ValidationError('agent_id must be a non-empty string', 'agent_id');
   }
 
-  // duration_ms — required for stop events
-  if (entry.event === 'stop') {
+  // duration_ms — required for stop events.
+  //
+  // null is an explicit, honest "duration unknown" (#917) — the producer found no
+  // matching 'start' record to measure against. It is deliberately distinct from
+  // 0, which under strictDuration is rejected as the signature of the pre-#917
+  // fabricated default. `undefined` still throws in BOTH modes: a stop record
+  // that omits the field entirely is a producer bug, not an unknown duration.
+  if (entry.event === 'stop' && entry.duration_ms !== null) {
+    const floor = strictDuration ? 1 : 0;
     if (
       typeof entry.duration_ms !== 'number' ||
       !Number.isInteger(entry.duration_ms) ||
-      entry.duration_ms < 0
+      entry.duration_ms < floor
     ) {
       throw new ValidationError(
-        'duration_ms must be a non-negative integer when event=stop',
+        strictDuration
+          ? 'duration_ms must be a positive integer or null when event=stop (0 is not a measurement)'
+          : 'duration_ms must be a non-negative integer or null when event=stop',
         'duration_ms',
       );
     }
@@ -252,11 +281,16 @@ export function migrateLegacySubagent(entry) {
  * Steps:
  *   1. Stamp schema_version if missing.
  *   2. Normalize (apply optional-field defaults).
- *   3. Validate — throws ValidationError on bad input.
+ *   3. Validate with strictDuration — throws ValidationError on bad input.
  *   4. Serialize to JSON + newline.
  *   5. mkdir(dirname, recursive: true).
  *   6. appendFile (POSIX append ≤ PIPE_BUF is atomic for typical JSONL lines).
  *
+ * This is the WRITE path, so it validates with `{ strictDuration: true }`: a stop
+ * record may carry a positive duration or an explicit null, never 0 (#917). The
+ * historic corpus is unaffected — it is only ever read, and readers/migrations use
+ * the lenient default. See the module header § duration_ms provenance.
+ *
  * @param {string} filePath — absolute path to target .jsonl file
  * @param {object} entry — candidate subagent record
  * @returns {Promise<object>} the validated + normalized entry that was written
@@ -268,7 +302,7 @@ export async function appendSubagent(filePath, entry) {
     schema_version: entry?.schema_version ?? CURRENT_SCHEMA_VERSION,
   };
   const normalized = normalizeSubagent(stamped);
-  const validated = validateSubagent(normalized);
+  const validated = validateSubagent(normalized, { strictDuration: true });
   const line = JSON.stringify(validated) + '\n';
   await mkdir(path.dirname(filePath), { recursive: true });
   await appendFile(filePath, line, 'utf8');

package/scripts/lib/telemetry/anon-id.mjs

@@ -0,0 +1,141 @@
+/**
+ * telemetry/anon-id.mjs — rotating anonymous ID for usage-telemetry (Epic #841,
+ * S2 / GitLab #843; PRD docs/prd/2026-07-20-anonymous-usage-telemetry.md §3-FA2).
+ *
+ * PURE, no I/O. The anonymous ID is a random UUID that rotates every
+ * ANON_ID_MAX_AGE_DAYS days. It is NEVER machine-derived (no hostname, MAC,
+ * install path, or any stable hardware/user identifier) — this is the privacy
+ * invariant that avoids the persistent-ID correlation criticism (PRD §4
+ * "Privacy engineering"). Rotation discards the old ID entirely.
+ *
+ * All time is passed IN as a parameter (`now`), never read from the clock inside
+ * this module, so callers stay deterministic and testable.
+ *
+ * Contract:
+ *   newAnonId()                          → a fresh random UUID (v4).
+ *   isExpired(createdAtISO, now, maxAge) → boolean; unparsable createdAt ⇒ true.
+ *   ensureAnonId(record, opts)           → { record, anon_id, rotated, created }.
+ */
+
+import { randomUUID } from 'node:crypto';
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+/** Rotate the anonymous ID after this many days. */
+export const ANON_ID_MAX_AGE_DAYS = 90;
+
+const MS_PER_DAY = 24 * 60 * 60 * 1000;
+
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+
+function isPlainObject(v) {
+  return v !== null && typeof v === 'object' && !Array.isArray(v);
+}
+
+/**
+ * Resolve a `now` argument to epoch-ms. Accepts either a number (already epoch-ms)
+ * or an ISO 8601 string. Returns NaN when it cannot be parsed.
+ * @param {number|string} now
+ * @returns {number}
+ */
+function toEpochMs(now) {
+  if (typeof now === 'number') return now;
+  if (typeof now === 'string') return Date.parse(now);
+  return NaN;
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Mint a fresh anonymous ID. A random UUID (v4) — never derived from any machine
+ * or user attribute.
+ *
+ * @returns {string} a v4 UUID
+ */
+export function newAnonId() {
+  return randomUUID();
+}
+
+/**
+ * Decide whether an anonymous ID minted at `createdAtISO` is older than
+ * `maxAgeDays` relative to `now` and must be rotated.
+ *
+ * Fail-safe posture: an unparsable / missing `createdAtISO` (or `now`) returns
+ * `true` (rotate) — an ID whose age cannot be verified is treated as stale
+ * rather than trusted indefinitely. The age comparison is strict: exactly
+ * `maxAgeDays` old is NOT expired (only strictly older rotates).
+ *
+ * @param {string} createdAtISO — ISO 8601 timestamp the current ID was minted at.
+ * @param {number|string} now   — reference time (epoch-ms or ISO 8601 string).
+ * @param {number} [maxAgeDays=ANON_ID_MAX_AGE_DAYS]
+ * @returns {boolean} true ⇒ rotate.
+ */
+export function isExpired(createdAtISO, now, maxAgeDays = ANON_ID_MAX_AGE_DAYS) {
+  const createdMs = typeof createdAtISO === 'string' ? Date.parse(createdAtISO) : NaN;
+  if (Number.isNaN(createdMs)) return true; // unverifiable age ⇒ rotate
+
+  const nowMs = toEpochMs(now);
+  if (Number.isNaN(nowMs)) return true; // unverifiable reference ⇒ rotate
+
+  const ageMs = nowMs - createdMs;
+  const maxMs = maxAgeDays * MS_PER_DAY;
+  return ageMs > maxMs;
+}
+
+/**
+ * Ensure `record` carries a fresh-enough anonymous ID, returning a NEW record
+ * (the input is never mutated). Three outcomes:
+ *
+ *   - created  — the record had no `anon_id`: mint one, stamp `anon_id_created_at`
+ *                to `now`. Returns `{ created: true, rotated: false }`.
+ *   - rotated  — the existing ID is older than `maxAgeDays` (or its
+ *                `anon_id_created_at` is unparsable): mint a new one, re-stamp
+ *                `anon_id_created_at`, discard the old ID.
+ *                Returns `{ created: false, rotated: true }`.
+ *   - unchanged — the ID is present and fresh: return it as-is (in a shallow
+ *                copy). Returns `{ created: false, rotated: false }`.
+ *
+ * @param {object} record — a record that may carry `anon_id` + `anon_id_created_at`.
+ * @param {{now?: string, maxAgeDays?: number}} [opts]
+ * @returns {{record: object, anon_id: string, rotated: boolean, created: boolean}}
+ */
+export function ensureAnonId(record, { now = new Date().toISOString(), maxAgeDays = ANON_ID_MAX_AGE_DAYS } = {}) {
+  const rec = isPlainObject(record) ? record : {};
+  const currentId = rec.anon_id;
+
+  // created — no usable ID present.
+  if (typeof currentId !== 'string' || currentId.trim() === '') {
+    const anon_id = newAnonId();
+    return {
+      record: { ...rec, anon_id, anon_id_created_at: now },
+      anon_id,
+      rotated: false,
+      created: true,
+    };
+  }
+
+  // rotated — present ID is too old (or its created_at is unparsable).
+  if (isExpired(rec.anon_id_created_at, now, maxAgeDays)) {
+    const anon_id = newAnonId();
+    return {
+      record: { ...rec, anon_id, anon_id_created_at: now },
+      anon_id,
+      rotated: true,
+      created: false,
+    };
+  }
+
+  // unchanged — present and fresh. Return a copy so the input stays untouched.
+  return {
+    record: { ...rec },
+    anon_id: currentId,
+    rotated: false,
+    created: false,
+  };
+}