@ngockhoale/ukit 3.1.9 → 3.2.0

package/src/core/agentRuntime/diagnostics.js

@@ -5,15 +5,13 @@
  * Two pure readers over the operation journal:
  *   renderOperationTimeline → deterministic frozen SanitizedTimeline
  *   replayOperation         → read-only frozen ReplayResult
- *
  * Privacy contract (SPEC §5): `summary` strings are assembled from the
  * eventType plus a whitelist of enumerated code/state fields — raw
  * `safePayload` text is NEVER copied into output. Values must match a
  * bounded code pattern; anything else is dropped silently.
  *
- * Read-only guarantee: this module performs no writes, spawns, signals,
- * or enqueues. Journal + contract are the only inputs. It performs no
- * config reads (same convention as eventStore.js).
+ * Read-only guarantee (readers): the two readers perform no writes,
+ * spawns, signals, or enqueues. Journal + contract are the only inputs.
  *
  * DF2-FR07 (TASK-008): this module is ALSO the diagnostics-side emit
  * surface — `emitModelAttempt` and `emitVerificationCompleted` turn a
@@ -21,10 +19,16 @@
  * recorder records parented onto the caller's run span ctx. Emit helpers
  * are synchronous, never throw, and never write to journals — the
  * read-only contract above still holds for the two readers.
+ *
+ * V-06: `exportSupportBundle` is the one WRITER in this module — a
+ * stage-gated (`decisionRuntime.diagnostics`) sanitized support-bundle
+ * assembler; see the section comment above its definition. It resolves
+ * the injected config's stage rather than reading config itself.
  */
 
 import { promises as fs } from 'node:fs';
 import path from 'node:path';
+import crypto from 'node:crypto';
 
 import {
   CONTRACT_VERSION,
@@ -32,8 +36,28 @@ import {
   isTerminal,
   validateTransition,
 } from './contract.js';
-import { readJournal, EventStoreError } from './eventStore.js';
-import { makeSpanContext, emitSpanRecord, typedResource, registryCode } from './telemetry.js';
+import {
+  readJournal,
+  readJournalExcerpt,
+  summarizeEvent,
+  EventStoreError,
+} from './eventStore.js';
+import {
+  makeSpanContext,
+  emitSpanRecord,
+  typedResource,
+  registryCode,
+  buildTraceExcerpt,
+  projectRootFromRuntimeDir,
+} from './telemetry.js';
+import { resolveDecisionRuntimeStage } from '../runtimeConfig.js';
+import { scanText } from '../sensitiveValueScanner.js';
+import { writeFileAtomic } from '../fileOps.js';
+import { ioReason } from '../observability/segments/internal.js';
+import { resolveSupportDir } from '../observability/support/paths.js';
+import { buildManifest } from '../observability/support/manifest.js';
+import { projectDirName } from '../observability/support/projector.js';
+import { redactString } from '../observability/privacy/redaction.js';
 
 export class DiagnosticsError extends Error {
   constructor(code, message) {
@@ -58,41 +82,9 @@ async function pathExists(p) {
   }
 }
 
-/** Bounded code pattern — states, codes, digests only; never free text. */
-const CODE_RE = /^[a-z0-9_.:-]{1,64}$/;
-
-/** Whitelisted safePayload fields whose values are enumerated codes. */
-const CODE_FIELDS = Object.freeze(['code', 'reason', 'status', 'kind', 'attempt']);
-const NUMERIC_FIELDS = Object.freeze(['seq', 'step', 'attempt', 'count', 'durationMs']);
-
-function codeValue(v) {
-  return typeof v === 'string' && CODE_RE.test(v) ? v : null;
-}
-
-/**
- * Build a sanitized summary from eventType + enumerated code fields only.
- * `from`/`to` are emitted only when they are known contract states.
- */
-function summarize(event) {
-  const parts = [event.eventType];
-  const p = event.safePayload;
-  if (p !== null && typeof p === 'object' && !Array.isArray(p)) {
-    for (const f of ['from', 'to']) {
-      if (STATE_SET.has(p[f])) parts.push(`${f}=${p[f]}`);
-    }
-    for (const f of CODE_FIELDS) {
-      const v = codeValue(p[f]);
-      if (v !== null) parts.push(`${f}=${v}`);
-    }
-    for (const f of NUMERIC_FIELDS) {
-      if (Number.isFinite(p[f]) && !['from', 'to'].includes(f) && !CODE_FIELDS.includes(f)) {
-        parts.push(`${f}=${p[f]}`);
-      }
-    }
-  }
-  return parts.join(' ');
-}
-
+// The privacy whitelist (CODE_RE/code fields) and summarizeEvent live in
+// eventStore.js — one convention shared by the timeline reader and the
+// support-bundle journal excerpt.
 /**
  * Read + validate the journal; throws DiagnosticsError('journal_missing')
  * when absent and detects the truncated-tail flag the reader discards.
@@ -213,7 +205,7 @@ export async function renderOperationTimeline(dir, operationId, _opts = {}) {
     seq: e.seq,
     eventType: e.eventType,
     observedAt: e.observedAt,
-    summary: summarize(e),
+    summary: summarizeEvent(e),
     artifactRefs: Object.freeze(
       (Array.isArray(e.artifactRefs) ? e.artifactRefs : []).filter((r) => typeof r === 'string'),
     ),
@@ -346,3 +338,312 @@ export function emitVerificationCompleted(recorder, {
   emitSpanRecord(telemetry, span, 'verification.completed', payload);
   return span;
 }
+
+
+// --- V-06: support-bundle export -------------------------------------------
+// One sanitized bundle per operation: a privacy-gated trace excerpt plus a
+// sanitized journal excerpt, materialized inside the Data Foundation
+// support layout — `Documents/UKit Support/proj-<sha256>/run-<sha256>/`
+// (or an explicit outDir). Same ownership rules as the projector: flat
+// `ukit-support/1` file set, manifest.json written LAST as the commit
+// point, sha256 checksums + byte sizes in the manifest so
+// `ukit telemetry import` can verify a received bundle.
+//
+// Privacy contract (SPEC §5, never loosened):
+//   - stage gate: `decisionRuntime.diagnostics` 'off' → zero writes.
+//   - redaction BEFORE persist: every string passes redactString
+//     (secrets, absolute paths, PII, control chars) with the secret
+//     scanner as a second signal; trace records additionally pass the
+//     independent sanitizeForSupport gate.
+//   - no raw content: payloads are allowlist-pruned — prompts, diffs,
+//     argv, output, paths can never appear (DENIED fields never even
+//     reach the excerpt).
+//   - final belt: the assembled file set is re-scanned; any residual
+//     secret blocks ALL writes (degraded, redaction_incomplete).
+//   - bounded: a hard maxBytes cap trims excerpt lines deterministically
+//     (journal tail first, then trace tail) and declares truncation in
+//     the manifest coverage — never a silent overflow.
+
+const BUNDLE_CAPS = Object.freeze({ maxBytes: 256 * 1024 });
+const BUNDLE_FILES = Object.freeze(['README.md', 'journal.jsonl', 'trace.jsonl', 'SUMMARY.md', 'manifest.json']);
+
+function sha256Hex(input) {
+  return crypto.createHash('sha256').update(input).digest('hex');
+}
+
+/** Deterministic within-bundle id pseudonym — deterministic for tests. */
+function bundlePseudonym(value, kind) {
+  return `${kind.slice(0, 8)}-${sha256Hex(`v06:${String(value)}`).slice(0, 12)}`;
+}
+
+/** Deep string redaction over plain JSON-shaped structures. */
+function redactDeep(value, ctx) {
+  if (value === null) return null;
+  const t = typeof value;
+  if (t === 'boolean') return value;
+  if (t === 'number') return Number.isFinite(value) ? value : null;
+  if (t === 'string') return redactString(value, ctx);
+  if (Array.isArray(value)) return value.map((v) => redactDeep(v, ctx));
+  if (isPlainObject(value)) {
+    const out = {};
+    for (const [k, v] of Object.entries(value)) out[k] = redactDeep(v, ctx);
+    return out;
+  }
+  return null;
+}
+
+function renderBundleReadme() {
+  return [
+    '# UKit run support bundle',
+    '',
+    'This directory was written by `ukit telemetry export-run` (V-06).',
+    'It contains a privacy-sanitized trace excerpt and journal excerpt',
+    'for one agent-runtime operation: codes, states, counts and timings',
+    'only — never prompts, diffs, paths, output or secrets.',
+    '',
+    'Share it by zipping the whole run-* directory. A maintainer can',
+    'validate it with `ukit telemetry import <path>`.',
+    '',
+  ].join('\n');
+}
+
+function renderBundleSummary({ generatedAt, opPseudonym, journal, trace, caps }) {
+  return [
+    '# VM run bundle summary',
+    '',
+    `generated_at: ${generatedAt}`,
+    `operation: ${opPseudonym}`,
+    `journal_status: ${journal.status}`,
+    `journal_entries: ${journal.entries.length}`,
+    `journal_truncated: ${journal.truncated}`,
+    `trace_status: ${trace.status}`,
+    `trace_kept: ${trace.stats.kept}`,
+    `trace_rejected: ${trace.stats.rejected}`,
+    `caps.maxBytes: ${caps.maxBytes}`,
+    '',
+    'Gaps are declared in manifest.json coverage; a missing or corrupt',
+    'journal still produces a bundle — the hole is marked, never hidden.',
+    '',
+  ].join('\n');
+}
+
+/**
+ * Export one operation's sanitized support bundle (V-06).
+ *
+ * @param {string} dir agent-runtime store root (events/, state/)
+ * @param {string} operationId
+ * @param {object} [opts]
+ * @param {object} [opts.config] runtime config — `decisionRuntime.diagnostics`
+ *   stage 'off' (or absent/malformed) returns `{status:'skipped',
+ *   reason:'stage_off'}` with zero writes.
+ * @param {string} [opts.outDir] bundle target directory; absent →
+ *   `Documents/UKit Support/proj-<sha256(projectKey)>/run-<sha256(op)>/`
+ *   via resolveSupportDir + projectDirName.
+ * @param {string} [opts.projectKey] project-key input for the proj dir
+ *   name (defaults to projectRootFromRuntimeDir(dir), then operationId).
+ * @param {Array}  [opts.trace] SemanticRecords for the trace excerpt.
+ * @param {string} [opts.traceRoot] canonical segment root; when given and
+ *   `trace` is absent, records are read from segments.
+ * @param {string} [opts.traceId] restrict a traceRoot read to one trace.
+ * @param {number} [opts.maxBytes] bundle byte cap (default 256 KiB).
+ * @param {number} [opts.now] injectable clock for deterministic output.
+ * @returns {Promise<{status:string, reason?:string, dir?:string,
+ *   files?:string[], bytes?:number, coverage?:object}>}
+ */
+export async function exportSupportBundle(dir, operationId, opts = {}) {
+  const none = { status: 'skipped', bytes: 0 };
+
+  // Stage gate first — 'off' must produce zero writes.
+  if (resolveDecisionRuntimeStage(opts.config ?? null, 'diagnostics') === 'off') {
+    return { ...none, reason: 'stage_off' };
+  }
+
+  const opId = typeof operationId === 'string' && operationId.length > 0
+    ? operationId
+    : 'unknown';
+  const caps = {
+    maxBytes: Number.isInteger(opts.maxBytes) && opts.maxBytes > 0
+      ? opts.maxBytes
+      : BUNDLE_CAPS.maxBytes,
+  };
+  const now = Number.isFinite(opts.now) ? opts.now : Date.now();
+  const generatedAt = new Date(now).toISOString();
+  const opPseudonym = `op-${sha256Hex(`v06:op:${opId}`).slice(0, 16)}`;
+
+  // --- resolve bundle dir -------------------------------------------------
+  let outDir = typeof opts.outDir === 'string' && opts.outDir.length > 0
+    ? opts.outDir
+    : null;
+  if (outDir === null) {
+    const resolved = await resolveSupportDir({
+      homeDir: opts.homeDir,
+      env: opts.env,
+      platform: opts.platform,
+    });
+    if (!resolved.ok) {
+      return { status: 'degraded', reason: resolved.reason, bytes: 0 };
+    }
+    const projectKey = typeof opts.projectKey === 'string' && opts.projectKey.length > 0
+      ? opts.projectKey
+      : (projectRootFromRuntimeDir(dir) ?? `standalone:${opId}`);
+    outDir = path.join(
+      resolved.dir,
+      projectDirName(projectKey),
+      `run-${sha256Hex(`v06:run:${opId}`).slice(0, 12)}`,
+    );
+  }
+
+  // --- journal excerpt (sanitized at the store boundary) -------------------
+  const journal = await readJournalExcerpt(dir, opId, { maxEntries: opts.maxJournalEntries });
+
+  // --- trace excerpt --------------------------------------------------------
+  let traceRecords = Array.isArray(opts.trace) ? opts.trace : null;
+  let traceReadFailed = false;
+  if (traceRecords === null && typeof opts.traceRoot === 'string' && opts.traceRoot.length > 0) {
+    try {
+      const { readSegments } = await import('../observability/segments/readSegments.js');
+      traceRecords = [];
+      for await (const record of readSegments(opts.traceRoot, { limit: 4096 })) {
+        const match = typeof opts.traceId === 'string' && opts.traceId.length > 0
+          ? record?.trace_id === opts.traceId
+          : record?.payload?.operation === opId;
+        if (match) traceRecords.push(record);
+      }
+    } catch {
+      traceReadFailed = true;
+      traceRecords = null;
+    }
+  }
+  const trace = buildTraceExcerpt(traceRecords, {
+    maxRecords: opts.maxTraceRecords,
+    pseudonymize: bundlePseudonym,
+  });
+  const traceStatus = traceReadFailed ? 'unreadable'
+    : traceRecords === null ? 'absent'
+      : trace.stats.kept === 0 && trace.stats.in === 0 ? 'empty' : 'ok';
+  trace.status = traceStatus;
+
+  // --- redact journal excerpt strings (artifact refs are op filenames) ------
+  const redactCtx = { scanner: scanText, maxChars: 1024 };
+  const journalEntries = journal.entries.map((e) => redactDeep(e, redactCtx));
+
+  // --- assemble the file set ------------------------------------------------
+  const files = {};
+  files['README.md'] = renderBundleReadme();
+
+  const journalLines = journalEntries.map((e) => JSON.stringify(e));
+  for (const g of journal.gaps) {
+    journalLines.push(JSON.stringify({ gap: g.code, seq: g.seq }));
+  }
+  if (journal.truncated) {
+    journalLines.push(JSON.stringify({ gap: 'journal_truncated', seq: 0 }));
+  }
+
+  const traceLines = [
+    ...trace.entries.map((e) => JSON.stringify(e)),
+    ...trace.gaps.map((g) => JSON.stringify({ gap: g.code, index: g.index })),
+  ];
+
+  const coverage = () => ({
+    journal: {
+      status: journal.status,
+      entries: journalEntries.length,
+      truncated: journal.truncated,
+      gaps: journal.gaps,
+    },
+    trace: {
+      status: traceStatus,
+      in: trace.stats.in,
+      kept: trace.stats.kept,
+      rejected: trace.stats.rejected,
+      truncated: trace.stats.truncated,
+      gaps: trace.gaps.length,
+    },
+    dropped_lines: 0,
+  });
+
+  // Byte budget: drop excerpt lines deterministically (journal tail first —
+  // the oldest-marked data loses before the self-description does), then
+  // trace tail, and finally declare the bundle unwritable rather than
+  // exceed the cap.
+  let dropped = 0;
+  const assemble = () => {
+    files['journal.jsonl'] = `${journalLines.join('\n')}\n`;
+    if (traceLines.length > 0) files['trace.jsonl'] = `${traceLines.join('\n')}\n`;
+    else delete files['trace.jsonl'];
+    files['SUMMARY.md'] = renderBundleSummary({
+      generatedAt, opPseudonym, journal: { ...journal, entries: journalEntries }, trace, caps,
+    });
+    const cov = coverage();
+    cov.dropped_lines = dropped;
+    files['manifest.json'] = `${JSON.stringify(buildManifest({
+      files,
+      generated_at: generatedAt,
+      operation_ref_pseudonym: opPseudonym,
+      coverage: cov,
+      caps,
+    }), null, 2)}\n`;
+    return Object.entries(files).reduce((s, [, c]) => s + Buffer.byteLength(c, 'utf8'), 0);
+  };
+
+  let total = assemble();
+  while (total > caps.maxBytes && (journalLines.length > 0 || traceLines.length > 0)) {
+    if (journalLines.length > 0) journalLines.pop();
+    else traceLines.pop();
+    dropped += 1;
+    total = assemble();
+  }
+  if (total > caps.maxBytes) {
+    return { status: 'degraded', reason: 'bundle_over_cap', bytes: 0 };
+  }
+
+  // --- final belt: re-scan assembled bytes; any residual secret blocks all --
+  for (const content of Object.values(files)) {
+    const scan = scanText(content);
+    if (scan.hasSecret) {
+      return { status: 'degraded', reason: 'redaction_incomplete', bytes: 0 };
+    }
+  }
+
+  // --- fs safety: refuse foreign files, symlinks and non-regular targets ----
+  try {
+    const st = await fs.lstat(outDir).catch((err) => {
+      if (err && err.code === 'ENOENT') return null;
+      throw err;
+    });
+    if (st !== null) {
+      if (st.isSymbolicLink()) return { ...none, reason: 'support_path_symlink' };
+      if (!st.isDirectory()) return { ...none, reason: 'support_path_not_directory' };
+      const listing = await fs.readdir(outDir);
+      for (const name of listing) {
+        if (!BUNDLE_FILES.includes(name)) return { ...none, reason: 'bundle_dir_foreign' };
+      }
+    }
+    for (const name of Object.keys(files)) {
+      const target = path.join(outDir, name);
+      const t = await fs.lstat(target).catch((err) => {
+        if (err && err.code === 'ENOENT') return null;
+        throw err;
+      });
+      if (t !== null && (t.isSymbolicLink() || !t.isFile())) {
+        return { status: 'skipped', reason: 'bundle_file_blocked', bytes: 0 };
+      }
+    }
+    await fs.mkdir(outDir, { recursive: true });
+    // manifest.json is written last — it is the commit point.
+    for (const name of BUNDLE_FILES) {
+      if (files[name] === undefined) continue;
+      await writeFileAtomic(path.join(outDir, name), files[name]);
+    }
+  } catch (err) {
+    return { status: 'degraded', reason: ioReason(err), bytes: 0 };
+  }
+
+  return {
+    status: 'written',
+    dir: outDir,
+    files: Object.keys(files),
+    bytes: total,
+    coverage: JSON.parse(files['manifest.json']).coverage,
+  };
+}

package/src/core/agentRuntime/eventStore.js

@@ -33,6 +33,7 @@ import { withFileLock } from '../fileOps.js';
 
 import {
   CONTRACT_VERSION,
+  OPERATION_STATES,
   validateSemanticEvent,
   validateEventOrder,
 } from './contract.js';
@@ -230,6 +231,144 @@ export async function* readJournal(dir, operationId) {
   }
 }
 
+// --- V-06 support-bundle excerpt surface -----------------------------------
+// The privacy whitelist lives on the event itself (single convention —
+// diagnostics.js and the support-bundle assembler share these constants).
+// Values must match CODE_RE to surface; anything else is dropped silently,
+// so free text can never ride a summary into a bundle.
+
+const EXCERPT_STATE_SET = new Set(OPERATION_STATES);
+
+/** Bounded code pattern — states, codes, digests only; never free text. */
+const CODE_RE = /^[a-z0-9_.:-]{1,64}$/;
+
+/** Whitelisted safePayload fields whose values are enumerated codes. */
+const CODE_FIELDS = Object.freeze(['code', 'reason', 'status', 'kind', 'attempt']);
+const NUMERIC_FIELDS = Object.freeze(['seq', 'step', 'attempt', 'count', 'durationMs']);
+
+function codeValue(v) {
+  return typeof v === 'string' && CODE_RE.test(v) ? v : null;
+}
+
+/**
+ * Build a sanitized one-line summary from eventType + enumerated code
+ * fields only. `from`/`to` are emitted only when they are known contract
+ * states; raw `safePayload` text is NEVER copied.
+ */
+export function summarizeEvent(event) {
+  const parts = [event.eventType];
+  const p = event.safePayload;
+  if (p !== null && typeof p === 'object' && !Array.isArray(p)) {
+    for (const f of ['from', 'to']) {
+      if (EXCERPT_STATE_SET.has(p[f])) parts.push(`${f}=${p[f]}`);
+    }
+    for (const f of CODE_FIELDS) {
+      const v = codeValue(p[f]);
+      if (v !== null) parts.push(`${f}=${v}`);
+    }
+    for (const f of NUMERIC_FIELDS) {
+      if (Number.isFinite(p[f]) && !['from', 'to'].includes(f) && !CODE_FIELDS.includes(f)) {
+        parts.push(`${f}=${p[f]}`);
+      }
+    }
+  }
+  return parts.join(' ');
+}
+
+/**
+ * Sanitized journal excerpt (V-06): a bounded, content-free view of one
+ * operation journal for support-bundle assembly. Unlike `readJournal`
+ * this API NEVER throws — every failure mode becomes a typed status plus
+ * a `gaps` marker so the bundle can declare the hole instead of failing:
+ *
+ *   status 'ok'         — journal parsed; `entries` may still be empty
+ *   status 'missing'    — no journal file for this operation
+ *   status 'corrupt'    — mid-file invalid line or malformed event;
+ *                         entries before the bad line are kept
+ *   status 'unreadable' — io failure opening/reading the file
+ *
+ * `truncated` flags a crash-torn final line (same tail rule as
+ * `readJournal`). `gaps` entries are `{seq, code}` with bounded codes —
+ * free-text failure details never reach the caller.
+ *
+ * @param {string} dir store root
+ * @param {string} operationId
+ * @param {object} [opts] `{ maxEntries }` (default 512, clamped ≥1)
+ * @returns {Promise<{ operationId: string, status: string, truncated: boolean,
+ *   entries: Array, gaps: Array }>}
+ */
+export async function readJournalExcerpt(dir, operationId, opts = {}) {
+  const maxEntries = Number.isInteger(opts.maxEntries) ? Math.max(1, opts.maxEntries) : 512;
+  const file = journalPath(dir, operationId);
+  const gaps = [];
+  const entries = [];
+  let truncated = false;
+
+  const excerpt = (e) => ({
+    seq: e.seq,
+    eventType: e.eventType,
+    observedAt: e.observedAt,
+    summary: summarizeEvent(e),
+    artifactRefs: (Array.isArray(e.artifactRefs) ? e.artifactRefs : [])
+      .filter((r) => typeof r === 'string'),
+  });
+
+  if (!(await pathExists(file))) {
+    gaps.push({ seq: 0, code: 'journal_missing' });
+    return { operationId, status: 'missing', truncated, entries, gaps };
+  }
+
+  let raw;
+  try {
+    raw = await fs.readFile(file, 'utf8');
+  } catch (err) {
+    if (err && err.code === 'ENOENT') {
+      gaps.push({ seq: 0, code: 'journal_missing' });
+      return { operationId, status: 'missing', truncated, entries, gaps };
+    }
+    gaps.push({ seq: 0, code: 'journal_unreadable' });
+    return { operationId, status: 'unreadable', truncated, entries, gaps };
+  }
+
+  // Line-by-line tolerant parse: unlike readJournal's all-or-nothing
+  // parseJournalFile, the excerpt keeps the good prefix of a corrupt
+  // journal and marks the hole — same torn-tail rule (unterminated or
+  // unparseable final line is a crash artifact, never corruption).
+  truncated = !raw.endsWith('\n');
+  const lines = raw.split('\n');
+  if (!truncated) lines.pop();
+  let lastSeq = 0;
+  for (let i = 0; i < lines.length; i += 1) {
+    const line = lines[i];
+    if (line === '') continue;
+    const isLast = i === lines.length - 1;
+    let event;
+    try {
+      event = JSON.parse(line);
+    } catch {
+      if (isLast && truncated) break; // torn tail — discarded silently
+      gaps.push({ seq: lastSeq, code: 'journal_corrupt' });
+      return { operationId, status: 'corrupt', truncated, entries, gaps };
+    }
+    const shape = validateSemanticEvent(event);
+    if (!shape.ok) {
+      gaps.push({
+        seq: Number.isInteger(event?.seq) ? event.seq : lastSeq,
+        code: codeValue(shape.code) ?? 'journal_corrupt',
+      });
+      return { operationId, status: 'corrupt', truncated, entries, gaps };
+    }
+    if (entries.length >= maxEntries) {
+      gaps.push({ seq: event.seq ?? lastSeq, code: 'excerpt_truncated' });
+      break;
+    }
+    entries.push(excerpt(event));
+    lastSeq = Number.isInteger(event.seq) ? event.seq : lastSeq;
+  }
+
+  return { operationId, status: 'ok', truncated, entries, gaps };
+}
+
 /**
  * Write the guarded operation state file (cache only — the journal is truth).
  * Atomic temp+rename+fsync.