@ngockhoale/ukit 3.0.12 → 3.1.1

package/src/core/observability/schema/validate.js

@@ -3,9 +3,10 @@
 //   validateSemanticRecord(record, context?) → { ok: boolean, errors: string[] }
 //
 // Validates one semantic envelope against SCHEMA_VERSION 1. Never throws:
-// malformed input returns { ok: false, errors }. Unknown optional fields are
-// tolerated (DF-FR03); unknown REQUIRED-field values (schema_version,
-// record_type, semantic_name, vocabularies) are rejected.
+// malformed input returns { ok: false, errors }. Unknown ENVELOPE fields
+// reject (the envelope is the frozen contract surface — DF2-FR01); unknown
+// payload fields are tolerated. Unknown REQUIRED-field values
+// (schema_version, record_type, semantic_name, vocabularies) are rejected.
 //
 // `context` is optional cross-record state for stream validation:
 //   { knownSpanIds?: Set<string>, seenSequences?: Set<string> }
@@ -17,6 +18,7 @@
 
 import {
   SCHEMA_VERSION,
+  ENVELOPE_FIELDS,
   REQUIRED_ENVELOPE_FIELDS,
   RECORD_TYPES,
   PRIVACY_CLASSES,
@@ -26,8 +28,23 @@ import {
 } from './constants.js';
 import { SEMANTIC_REGISTRY, REASON_CODES } from './registry.js';
 
-const OPTIONAL_ID_FIELDS = ['trace_id', 'span_id', 'parent_span_id', 'execution_id', 'session_id', 'project_ref'];
+const OPTIONAL_ID_FIELDS = [
+  'trace_id',
+  'span_id',
+  'parent_span_id',
+  'execution_id',
+  'session_id',
+  'project_ref',
+  'agent_id',
+  'project_instance_id',
+];
 const REASON_CODE_FIELDS = ['error_code', 'reason_code', 'wait_code'];
+// Fields a v1 reader knows about: the frozen envelope plus the stamp
+// sanitizeObserved adds before persistence. Anything else at the top level
+// is an unknown envelope field and rejects.
+const KNOWN_ENVELOPE_FIELDS = new Set([...ENVELOPE_FIELDS, 'redaction_version']);
+// DF2-FR01: correlation ids are bounded opaque strings.
+const MAX_ID_FIELD_CHARS = 128;
 const ISO_8601_RE = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[+-]\d{2}:\d{2})$/;
 
 function isPlainObject(value) {
@@ -106,8 +123,19 @@ function validatePayload(payload, errors) {
       errors.push(`payload.${field} ${JSON.stringify(code)} is not in the reason-code registry`);
     }
   }
-  if (payload.confidence !== undefined && !CONFIDENCE_TYPES.includes(payload.confidence)) {
-    errors.push(`payload.confidence must be one of ${CONFIDENCE_TYPES.join('|')}`);
+  // Confidence is either the typed enum (v1) or the v1.1 scored shape
+  // {type: CONFIDENCE_TYPE, value: finite number} used by anomaly.detected.
+  if (payload.confidence !== undefined && payload.confidence !== null) {
+    if (isPlainObject(payload.confidence)) {
+      if (!CONFIDENCE_TYPES.includes(payload.confidence.type)) {
+        errors.push(`payload.confidence.type must be one of ${CONFIDENCE_TYPES.join('|')} (got ${JSON.stringify(payload.confidence.type)})`);
+      }
+      if (typeof payload.confidence.value !== 'number' || !Number.isFinite(payload.confidence.value)) {
+        errors.push('payload.confidence.value must be a finite number');
+      }
+    } else if (!CONFIDENCE_TYPES.includes(payload.confidence)) {
+      errors.push(`payload.confidence must be one of ${CONFIDENCE_TYPES.join('|')}`);
+    }
   }
   if (payload.telemetry_complete !== undefined && typeof payload.telemetry_complete !== 'boolean') {
     errors.push('payload.telemetry_complete must be a boolean');
@@ -128,6 +156,16 @@ export function validateSemanticRecord(record, context) {
     return { ok: false, errors: ['record must be a plain object'] };
   }
 
+
+  // The envelope is the frozen contract surface: any top-level key outside
+  // the known field set (envelope + the persisted redaction stamp) rejects.
+  // New fields arrive only via schema-versioned additive releases.
+  for (const key of Object.keys(record)) {
+    if (!KNOWN_ENVELOPE_FIELDS.has(key)) {
+      errors.push(`unknown envelope field: ${key}`);
+    }
+  }
+
   for (const field of REQUIRED_ENVELOPE_FIELDS) {
     if (record[field] === undefined || record[field] === null) {
       errors.push(`missing required field: ${field}`);
@@ -199,6 +237,30 @@ export function validateSemanticRecord(record, context) {
     }
   }
 
+  // DF2-FR01 v1.1 additive shapes — correlation ids are bounded opaque
+  // strings; sampling stamps the policy that produced this record.
+  for (const field of ['agent_id', 'project_instance_id']) {
+    const value = record[field];
+    if (value !== undefined && value !== null) {
+      if (typeof value !== 'string' || value.length === 0 || value.length > MAX_ID_FIELD_CHARS) {
+        errors.push(`${field} must be a non-empty string of at most ${MAX_ID_FIELD_CHARS} characters`);
+      }
+    }
+  }
+  if (record.sampling !== undefined && record.sampling !== null) {
+    const sampling = record.sampling;
+    if (!isPlainObject(sampling)) {
+      errors.push('sampling must be an object {policy_version, rate}');
+    } else {
+      if (!isNonEmptyString(sampling.policy_version) || sampling.policy_version.length > MAX_ID_FIELD_CHARS) {
+        errors.push(`sampling.policy_version must be a non-empty string of at most ${MAX_ID_FIELD_CHARS} characters`);
+      }
+      if (typeof sampling.rate !== 'number' || !Number.isFinite(sampling.rate) || sampling.rate < 0 || sampling.rate > 1) {
+        errors.push('sampling.rate must be a number in [0, 1]');
+      }
+    }
+  }
+
   if (!isPlainObject(record.payload)) {
     errors.push('payload must be an object');
   } else {

package/src/core/observability/segments/internal.js

@@ -10,11 +10,38 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import crypto from 'node:crypto';
+import zlib from 'node:zlib';
 
 export const ACTIVE_FILE = 'active.jsonl';
 export const STATE_FILE = '_state.json';
 export const QUARANTINE_DIR = 'quarantine';
 export const SEALED_RE = /^seg-(\d+)-([A-Za-z0-9_-]+)-([A-Za-z0-9_-]+)\.jsonl$/;
+export const SEALED_ZST_RE = /^seg-(\d+)-([A-Za-z0-9_-]+)-([A-Za-z0-9_-]+)\.jsonl\.zst$/;
+
+// Meta sidecar `compression` field values (SPEC §10): 'zst' sealed via
+// zlib.zstdCompressSync, 'none' plain JSONL (legacy segments and Node <22.15).
+export const COMPRESSION_ZST = 'zst';
+export const COMPRESSION_NONE = 'none';
+
+/** zlib provider for a policy/opts object — injectable for tests (policy.zlib). */
+export function zlibOf(source) {
+  const z = source && source.zlib;
+  return z && typeof z === 'object' ? z : zlib;
+}
+
+let zstdProbe;
+
+/**
+ * True when zstd compression is usable on this runtime (Node ≥22.15).
+ * Presence-checked against `zlib.zstdCompressSync`; the real-zlib result is
+ * cached per process — an injected `source.zlib` is evaluated every call.
+ */
+export function zstdAvailable(source) {
+  const z = source && source.zlib !== undefined ? zlibOf(source) : null;
+  if (z) return typeof z.zstdCompressSync === 'function';
+  if (zstdProbe === undefined) zstdProbe = typeof zlib.zstdCompressSync === 'function';
+  return zstdProbe;
+}
 
 export const DEFAULT_IO_TIMEOUT_MS = 5000;
 
@@ -136,7 +163,11 @@ export async function resolveFileInDir(filePath, timeoutMs = DEFAULT_IO_TIMEOUT_
 }
 
 export function metaPathFor(segmentPath) {
-  return segmentPath.replace(/\.jsonl$/, '.meta.json');
+  // Per-format sidecar: a .zst segment pairs with seg-*.jsonl.zst.meta.json so
+  // an orphaned plain .jsonl (crash mid-seal) can never inherit the zst meta.
+  return segmentPath.endsWith('.jsonl.zst')
+    ? `${segmentPath}.meta.json`
+    : segmentPath.replace(/\.jsonl$/, '.meta.json');
 }
 
 export function sha256Buffer(buf) {
@@ -181,11 +212,12 @@ export function sanitizeNameComponent(value) {
 
 /**
  * Enumerate the segment directory.
- * → { ok: true, sealed: [{ name, seq, path, size }], active: { path, size } | null,
+ * → { ok: true, sealed: [{ name, seq, path, size, compressed }], active: { path, size } | null,
  *     skipped: [{ name, reason }] }
  *   | { ok: false, reason }
- * Symlinks are never followed — reported as skipped. Foreign .jsonl files that
- * match neither the active nor sealed naming scheme are skipped, never read.
+ * Symlinks are never followed — reported as skipped. Foreign .jsonl/.jsonl.zst
+ * files that match neither the active nor sealed naming scheme are skipped,
+ * never read. `compressed` marks seg-*.jsonl.zst entries (zstd-sealed).
  */
 export async function listSegments(root, timeoutMs = DEFAULT_IO_TIMEOUT_MS) {
   let entries;
@@ -201,7 +233,7 @@ export async function listSegments(root, timeoutMs = DEFAULT_IO_TIMEOUT_MS) {
   for (const entry of entries) {
     const name = entry.name;
     if (name === QUARANTINE_DIR || name === STATE_FILE || name.endsWith('.meta.json')) continue;
-    if (!name.endsWith('.jsonl')) continue;
+    if (!name.endsWith('.jsonl') && !name.endsWith('.jsonl.zst')) continue;
     if (entry.isSymbolicLink()) {
       skipped.push({ name, reason: 'symlink_skipped' });
       continue;
@@ -223,8 +255,10 @@ export async function listSegments(root, timeoutMs = DEFAULT_IO_TIMEOUT_MS) {
       continue;
     }
     const m = SEALED_RE.exec(name);
-    if (m) {
-      sealed.push({ name, seq: Number.parseInt(m[1], 10), path: full, size });
+    const mz = m ? null : SEALED_ZST_RE.exec(name);
+    if (m || mz) {
+      const hit = m || mz;
+      sealed.push({ name, seq: Number.parseInt(hit[1], 10), path: full, size, compressed: Boolean(mz) });
     } else {
       skipped.push({ name, reason: 'unrecognized_segment_name' });
     }
@@ -233,7 +267,7 @@ export async function listSegments(root, timeoutMs = DEFAULT_IO_TIMEOUT_MS) {
   return { ok: true, sealed, active, skipped };
 }
 
-/** Total bytes held in live .jsonl segment files (meta/state excluded). */
+/** Total bytes held in live segment files (meta/state excluded). */
 export function totalSegmentBytes(listing) {
   let total = listing.active ? listing.active.size : 0;
   for (const seg of listing.sealed) total += seg.size;

package/src/core/observability/segments/readSegments.js

@@ -3,7 +3,7 @@
  *
  * Typed reader over the append-only JSONL segment store.
  *
- *   readSegments(root, { fromInclusive?, limit?, ioTimeoutMs? })
+ *   readSegments(root, { fromInclusive?, limit?, ioTimeoutMs?, zlib? })
  *     → AsyncIterable<record> with attached:
  *         .coverage → { expired_segments, quarantined_segments, corrupt_lines,
  *                       partial_tail_bytes, cursor_missed, degraded[] }
@@ -19,6 +19,10 @@
  * Integrity: every sealed segment's sha256 is verified against its meta
  * sidecar before a single row is served; a mismatch or missing meta sends the
  * segment to quarantine/ — corrupt data is never falsified into the stream.
+ * seg-*.jsonl.zst payloads are decoded via zlib.zstdDecompressSync after the
+ * checksum passes (checksum covers the stored bytes); a decode failure is
+ * quarantined like a corrupt .jsonl, and a missing decoder on old Node
+ * degrades 'zstd_unavailable' instead of throwing.
  * A partial tail row in the active segment (hard-kill artifact) is skipped
  * and counted, never parsed. Symlinked or foreign-named files are never
  * followed or read.
@@ -38,6 +42,7 @@ import {
   resolveRoot,
   sha256Buffer,
   withTimeout,
+  zlibOf,
 } from './internal.js';
 
 export function readSegments(root, opts = {}) {
@@ -129,6 +134,35 @@ export function readSegments(root, opts = {}) {
         }
         continue;
       }
+      if (seg.compressed) {
+        const decompress = zlibOf(opts).zstdDecompressSync;
+        let decoded = null;
+        if (typeof decompress !== 'function') {
+          // Old Node can't decode — degrade typed, never claim the records.
+          degrade('zstd_unavailable', seg.name);
+          continue;
+        }
+        try {
+          decoded = decompress(buf);
+        } catch {
+          decoded = null;
+        }
+        if (decoded === null || decoded.length === 0) {
+          // Stored bytes verified but not a valid/non-empty zstd stream →
+          // corrupt like a bad .jsonl: quarantine, never falsify rows.
+          const q = await quarantineSegment(resolved.root, seg.name, 'decode_failed', {
+            ioTimeoutMs: timeoutMs,
+          });
+          if (q.ok) {
+            coverage.quarantined_segments += 1;
+            degrade('decode_failed_quarantined', seg.name);
+          } else {
+            degrade(`quarantine_failed:${q.reason}`, seg.name);
+          }
+          continue;
+        }
+        buf = decoded;
+      }
       const text = buf.toString('utf8');
       const complete = text.endsWith('\n') ? text.slice(0, -1) : text;
       for (const line of complete.split('\n')) {

package/src/core/observability/segments/recovery.js

@@ -31,14 +31,15 @@ import {
 } from './internal.js';
 
 /**
- * Move a corrupt sealed segment (and its meta sidecar) into `quarantine/`.
+ * Move a corrupt sealed segment (.jsonl or .jsonl.zst, and its meta sidecar)
+ * into `quarantine/`.
  * The segment is never deleted and never silently repaired — it is preserved
  * for inspection outside the live read path.
  */
 export async function quarantineSegment(root, segmentName, reason, opts = {}) {
   const timeoutMs = Number.isFinite(opts.ioTimeoutMs) ? opts.ioTimeoutMs : DEFAULT_IO_TIMEOUT_MS;
   const base = path.basename(String(segmentName));
-  if (base !== segmentName || !base.endsWith('.jsonl')) {
+  if (base !== segmentName || !(base.endsWith('.jsonl') || base.endsWith('.jsonl.zst'))) {
     return { ok: false, reason: 'unsafe_path' };
   }
   const quarantineDir = path.join(root, QUARANTINE_DIR);

package/src/core/observability/segments/retention.js

@@ -6,9 +6,13 @@
  *
  *   active.jsonl                  shared append target (O_APPEND — concurrent
  *                                 writers interleave whole rows, never bytes)
- *   seg-<seq>-<boot>-<writer>.jsonl   sealed segment
+ *   seg-<seq>-<boot>-<writer>.jsonl   sealed segment (or .jsonl.zst when the
+ *                                     runtime has zlib.zstdCompressSync)
  *   seg-<...>.meta.json           sidecar: checksum, record/seq/importance
- *                                 stats, sealed_at_ms, recovered flag
+ *                                 stats, sealed_at_ms, recovered flag,
+ *                                 compression ('zst'|'none')
+ *   seg-<seq>.claim               0-byte seq allocator: 'wx' claim at seal,
+ *                                 never released — a seq can never be reused
  *   quarantine/                   corrupt sealed segments (never falsified)
  *   _state.json                   next_segment_seq, expired/quarantined
  *                                 counters, disabled flag, active_since_ms
@@ -32,7 +36,8 @@
  *                                         | { ok: false, reason }
  *
  * policy: { maxSegmentBytes, maxSegmentAgeMs, maxTotalBytes, ioTimeoutMs,
- *           now } — `now` is injectable for deterministic tests.
+ *           now, zlib } — `now` and `zlib` are injectable for deterministic
+ *           tests (zlib stub → compression 'none' fallback).
  */
 
 import fs from 'node:fs';
@@ -42,6 +47,8 @@ import { validateSemanticRecord } from '../schema/validate.js';
 import { IMPORTANCE_LEVELS } from '../schema/constants.js';
 import {
   ACTIVE_FILE,
+  COMPRESSION_NONE,
+  COMPRESSION_ZST,
   DEFAULT_IO_TIMEOUT_MS,
   ioReason,
   ioTimeoutMsOf,
@@ -56,6 +63,8 @@ import {
   totalSegmentBytes,
   withTimeout,
   writeState,
+  zlibOf,
+  zstdAvailable,
 } from './internal.js';
 
 function importanceRank(level) {
@@ -64,10 +73,15 @@ function importanceRank(level) {
 }
 
 /**
- * Seal the current active segment: parse stats, checksum the exact bytes,
- * move it aside via link+unlink (atomic, never overwrites an existing seal),
- * and write its meta sidecar. Concurrent rotators lose the race on ENOENT
- * and simply report not-sealed.
+ * Seal the current active segment: claim a seq via seg-<seq>.claim ('wx',
+ * never released), move the file aside via an atomic rename, then parse
+ * stats + checksum the exact moved bytes, compress to seg-*.jsonl.zst when
+ * zstd is available (compression:'zst'), and write its meta sidecar.
+ * The meta write is the commit point — the plain
+ * .jsonl is deleted only after meta lands, so a crash mid-seal leaves an
+ * orphan .jsonl whose missing/meta-less state routes it to quarantine rather
+ * than being served twice. Concurrent rotators lose the race on ENOENT and
+ * simply report not-sealed.
  */
 async function sealActive(root, state, policy) {
   const timeoutMs = ioTimeoutMsOf(policy);
@@ -87,9 +101,91 @@ async function sealActive(root, state, policy) {
     return { ok: true, sealed: false };
   }
 
+  // Peek only to name the segment — boot/writer from the first valid row.
+  // Authoritative stats/checksum come from a post-rename read: the file may
+  // gain rows between this read and the move.
+  let bootId = 'unknown';
+  let writerId = 'unknown';
+  try {
+    const peek = await withTimeout(fs.promises.readFile(activePath), timeoutMs);
+    for (const line of peek.toString('utf8').split('\n')) {
+      if (line.length === 0) continue;
+      let parsed = null;
+      try {
+        parsed = JSON.parse(line);
+      } catch {
+        continue;
+      }
+      if (bootId === 'unknown' && typeof parsed.boot_id === 'string') bootId = parsed.boot_id;
+      if (writerId === 'unknown' && typeof parsed.writer_id === 'string') writerId = parsed.writer_id;
+      if (bootId !== 'unknown' && writerId !== 'unknown') break;
+    }
+  } catch (err) {
+    if (err && err.code === 'ENOENT') return { ok: true, sealed: false };
+    return { ok: false, reason: ioReason(err) };
+  }
+
+  // Segments are named seg-<seq>-<boot>-<writer>.* — the name alone cannot
+  // arbitrate seq ownership because concurrent sealers see different
+  // boot/writer components (a stale next_segment_seq otherwise commits the
+  // same seq twice under different names and scrambles read order). The
+  // seg-<seq>.claim marker is the atomic allocator: 'wx' creation wins the
+  // seq, and a claim is NEVER released — a burned seq cannot be reused, so a
+  // segment sealed later can never sort before an earlier commit even when
+  // _state.json reads stale. Claims happen before the move, so seq follows
+  // segment append order. Orphan claims from a lost race or crash are
+  // 0-byte and ignored by the listing.
+  //
+  // The move itself is rename(active → seg-N.jsonl), not link+unlink: under
+  // concurrent sealers link+unlink lets BOTH movers commit the same inode —
+  // a recreated active.jsonl satisfies the second unlink. Rename is atomic:
+  // exactly one mover wins; the loser sees ENOENT and reports not-sealed.
+  let seq = state.next_segment_seq;
+  let name = null;
+  let sealedPath = null;
+  for (let attempt = 0; attempt < 64; attempt++) {
+    const padded = String(seq).padStart(6, '0');
+    name = `seg-${padded}-${sanitizeNameComponent(bootId)}-${sanitizeNameComponent(writerId)}.jsonl`;
+    const target = path.join(root, name);
+    try {
+      await withTimeout(
+        fs.promises.writeFile(path.join(root, `seg-${padded}.claim`), '', { flag: 'wx' }),
+        timeoutMs,
+      );
+    } catch (err) {
+      if (err && err.code === 'EEXIST') {
+        seq += 1;
+        continue;
+      }
+      return { ok: false, reason: ioReason(err) };
+    }
+    try {
+      // Claim won — but a crash-orphan segment may still sit at this name
+      // (its claim predates this run). Never rename over it: burn the seq
+      // and let the reader quarantine the meta-less orphan.
+      await withTimeout(fs.promises.lstat(target), timeoutMs);
+      seq += 1;
+      continue;
+    } catch (err) {
+      if (!(err && err.code === 'ENOENT')) return { ok: false, reason: ioReason(err) };
+    }
+    try {
+      await withTimeout(fs.promises.rename(activePath, target), timeoutMs);
+      sealedPath = target;
+      break;
+    } catch (err) {
+      // ENOENT: another sealer moved active.jsonl first — our claim stays
+      // (the seq is burned), nothing else to unwind.
+      if (err && err.code === 'ENOENT') return { ok: true, sealed: false };
+      return { ok: false, reason: ioReason(err) };
+    }
+  }
+  // Every attempt collided — never write meta for a name that was not sealed.
+  if (!sealedPath) return { ok: false, reason: 'seal_conflict' };
+
   let buf;
   try {
-    buf = await withTimeout(fs.promises.readFile(activePath), timeoutMs);
+    buf = await withTimeout(fs.promises.readFile(sealedPath), timeoutMs);
   } catch (err) {
     return { ok: false, reason: ioReason(err) };
   }
@@ -101,8 +197,6 @@ async function sealActive(root, state, policy) {
   let seqMax = null;
   let importanceMax = 'low';
   let maxRank = -1;
-  let bootId = 'unknown';
-  let writerId = 'unknown';
   const text = buf.toString('utf8');
   const complete = text.endsWith('\n') ? text.slice(0, -1) : text;
   for (const line of complete.split('\n')) {
@@ -128,30 +222,29 @@ async function sealActive(root, state, policy) {
     }
   }
 
-  // link+unlink: fails atomically if the target seal already exists (another
-  // writer won the seq) — rename would silently overwrite it.
-  let seq = state.next_segment_seq;
-  let name = null;
-  let linked = false;
-  for (let attempt = 0; attempt < 64; attempt++) {
-    name = `seg-${String(seq).padStart(6, '0')}-${sanitizeNameComponent(bootId)}-${sanitizeNameComponent(writerId)}.jsonl`;
-    const target = path.join(root, name);
+  // Compression happens only here, at seal time — the emit/append hot path is
+  // untouched. The payload lands via tmp+rename (atomic, never a half-written
+  // .zst); any compress/write failure drops back to 'none' on the plain
+  // .jsonl — a seal never fails over compression.
+  let payloadPath = sealedPath;
+  let payloadBuf = buf;
+  let compression = COMPRESSION_NONE;
+  if (zstdAvailable(policy)) {
     try {
-      await withTimeout(fs.promises.link(activePath, target), timeoutMs);
-      await withTimeout(fs.promises.unlink(activePath), timeoutMs);
-      linked = true;
-      break;
-    } catch (err) {
-      if (err && err.code === 'ENOENT') return { ok: true, sealed: false }; // lost the race
-      if (err && err.code === 'EEXIST') {
-        seq += 1;
-        continue;
+      const out = zlibOf(policy).zstdCompressSync(buf);
+      if (Buffer.isBuffer(out) && out.length > 0) {
+        const zstPath = `${sealedPath}.zst`;
+        const tmpPath = `${zstPath}.tmp-${process.pid}-${seq}`;
+        await withTimeout(fs.promises.writeFile(tmpPath, out), timeoutMs);
+        await withTimeout(fs.promises.rename(tmpPath, zstPath), timeoutMs);
+        payloadPath = zstPath;
+        payloadBuf = out;
+        compression = COMPRESSION_ZST;
       }
-      return { ok: false, reason: ioReason(err) };
+    } catch {
+      // 'none' fallback — the reserved .jsonl simply stays the segment.
     }
   }
-  // Every attempt collided — never write meta for a name that was not sealed.
-  if (!linked) return { ok: false, reason: 'seal_conflict' };
 
   const meta = {
     sealed_seq: seq,
@@ -164,21 +257,32 @@ async function sealActive(root, state, policy) {
     importance_max: importanceMax,
     corrupt_lines: corruptLines,
     recovered: false,
-    checksum: sha256Buffer(buf),
+    compression,
+    checksum: sha256Buffer(payloadBuf),
   };
   try {
     await withTimeout(
-      fs.promises.writeFile(metaPathFor(path.join(root, name)), JSON.stringify(meta, null, 2)),
+      fs.promises.writeFile(metaPathFor(payloadPath), JSON.stringify(meta, null, 2)),
       timeoutMs,
     );
   } catch (err) {
     return { ok: false, reason: ioReason(err) };
   }
 
+  // Commit point passed: drop the plain .jsonl when a .zst payload exists.
+  if (compression === COMPRESSION_ZST) {
+    try {
+      await withTimeout(fs.promises.unlink(sealedPath), timeoutMs);
+    } catch {
+      // Orphan .jsonl beside a committed .zst: it has no meta of its own, so
+      // the reader quarantines it — never falsified, never double-served.
+    }
+  }
+
   state.next_segment_seq = Math.max(state.next_segment_seq, seq + 1);
   state.active_since_ms = null;
   await writeState(root, state, timeoutMs);
-  return { ok: true, sealed: true, name };
+  return { ok: true, sealed: true, name: path.basename(payloadPath) };
 }
 
 /**