@ngockhoale/ukit 3.0.6 → 3.0.8

package/src/core/observability/privacy/redaction.js

@@ -0,0 +1,113 @@
+/**
+ * redaction.js (TASK-004)
+ *
+ * Shared low-level string hygiene for the two privacy gates. This module
+ * only knows how to *detect and neutralize* forbidden content inside a
+ * single string — it makes no keep/drop/reject decisions. Those stay with
+ * each gate so the support boundary remains an independent check.
+ *
+ * Leak-safety contract (same as sensitiveValueScanner.js): nothing here
+ * returns a matched value, excerpt, or hash — only redacted strings and
+ * boolean verdicts.
+ */
+
+/**
+ * Ordered redaction rules. Each rule replaces every match with
+ * `[REDACTED:<tag>]`. Vendor-token patterns mirror TOKEN_PATTERNS in
+ * src/core/sensitiveValueScanner.js so a value the scanner would flag is
+ * also removable here; the scanner is still consulted afterwards as a
+ * second signal for anything these patterns miss.
+ */
+export const REDACTION_RULES = [
+  { tag: 'secret', re: /-----BEGIN (?:RSA |EC |DSA |OPENSSH |PGP |ENCRYPTED )?PRIVATE KEY-----/g },
+  { tag: 'secret', re: /\bsk-(?:proj-|ant-|svc-|acct-|admin-)?[A-Za-z0-9_-]{20,}/g },
+  { tag: 'secret', re: /(?<![A-Za-z0-9+/_-])(?:AKIA|ASIA)[0-9A-Z]{16}(?![A-Za-z0-9+/_-])/g },
+  { tag: 'secret', re: /\bgithub_pat_[A-Za-z0-9_]{20,}/g },
+  { tag: 'secret', re: /\bgh[pousr]_[A-Za-z0-9]{30,}\b/g },
+  { tag: 'secret', re: /\bglpat-[A-Za-z0-9_-]{20,}/g },
+  { tag: 'secret', re: /\bxox[baprs]-[A-Za-z0-9-]{10,}/g },
+  { tag: 'secret', re: /(?<![A-Za-z0-9+/_-])AIza[0-9A-Za-z_-]{20,}(?![A-Za-z0-9+/_-])/g },
+  { tag: 'secret', re: /\b[srp]k_live_[A-Za-z0-9]{20,}/g },
+  { tag: 'secret', re: /\beyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\b/g },
+  { tag: 'secret', re: /\bBearer\s+[A-Za-z0-9._~+/=-]{8,}/gi },
+  { tag: 'secret', re: /\bssh-(?:rsa|ed25519|dss)\s+[A-Za-z0-9+/=]{20,}/g },
+  // scheme://user:pass@host — credentials and embedded hostnames
+  { tag: 'secret', re: /\b[a-z][a-z0-9+.-]*:\/\/[^\s/:@]+:[^\s/@]+@[^\s]+/gi },
+  // KEY=value assignments for well-known secret names (.env content)
+  {
+    tag: 'secret',
+    re: /\b[A-Za-z_][A-Za-z0-9_]*(?:KEY|SECRET|TOKEN|PASSWORD|PASSWD|CREDENTIAL)[A-Za-z0-9_]*\s*=\s*[^\s"']+/g,
+  },
+  // absolute POSIX paths (two or more segments)
+  { tag: 'path', re: /\/(?:[\w.@+-]+)(?:\/[\w.@+-]+)+/g },
+  // absolute Windows paths
+  { tag: 'path', re: /\b[A-Za-z]:\\(?:[^\s"']+\\)*[^\s"']*/g },
+  // email addresses
+  { tag: 'pii', re: /\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}\b/g },
+];
+
+/** C0/C1 controls, DEL, bidi/format overrides, zero-width chars, BOM. */
+const FORBIDDEN_CHARS_RE =
+  /[\u0000-\u0008\u000B\u000C\u000E-\u001F\u007F-\u009F\u00AD\u2028-\u202E\u2066-\u2069\u200B-\u200D\u2060\uFEFF\uFFF0-\uFFFF]/g;
+
+/**
+ * True when the string contains a line break. Persisted telemetry is
+ * single-line JSONL; any embedded newline is treated as a log-injection
+ * attempt and the whole value is redacted rather than filtered.
+ */
+export function hasLineBreak(value) {
+  return value.includes('\n') || value.includes('\r');
+}
+
+/**
+ * True when the string still contains content a redaction rule would
+ * remove, a line break, or a forbidden control/format character. Used by
+ * the support gate to *reject* rather than redact.
+ */
+export function containsForbiddenContent(value) {
+  if (typeof value !== 'string') return false;
+  if (hasLineBreak(value)) return true;
+  for (const { re } of REDACTION_RULES) {
+    re.lastIndex = 0;
+    if (re.test(value)) return true;
+  }
+  FORBIDDEN_CHARS_RE.lastIndex = 0;
+  return FORBIDDEN_CHARS_RE.test(value);
+}
+
+/**
+ * Redact a single string. Returns the neutralized value — never throws.
+ * `scanner` is the sensitiveValueScanner.scanText-compatible second
+ * signal; when it flags (or throws) the whole value collapses to a marker
+ * because we cannot safely locate what it saw.
+ */
+export function redactString(value, { scanner, maxChars }) {
+  let out = value;
+
+  if (hasLineBreak(out)) return '[REDACTED:multiline]';
+
+  for (const { tag, re } of REDACTION_RULES) {
+    re.lastIndex = 0;
+    out = out.replace(re, `[REDACTED:${tag}]`);
+  }
+
+  FORBIDDEN_CHARS_RE.lastIndex = 0;
+  out = out.replace(FORBIDDEN_CHARS_RE, '');
+
+  if (typeof scanner === 'function') {
+    let hit = false;
+    try {
+      const res = scanner(out);
+      hit = Boolean(res && res.hasSecret);
+    } catch {
+      hit = true; // fail closed: a broken scanner never passes content
+    }
+    if (hit) return '[REDACTED:secret]';
+  }
+
+  if (out.length > maxChars) {
+    const marker = '…[TRUNCATED]';
+    out = `${out.slice(0, Math.max(0, maxChars - marker.length))}${marker}`;
+  }
+  return out;
+}

package/src/core/observability/privacy/sanitizeForSupport.js

@@ -0,0 +1,133 @@
+/**
+ * sanitizeForSupport.js (TASK-004, SPEC §5 DF-FR06 / §8)
+ *
+ * Independent second boundary in front of the user-facing support view.
+ * Unlike sanitizeObserved it does not repair content — it REJECTS:
+ * unknown envelope fields, non-allowlisted payload fields (default-deny,
+ * applied recursively), any residual forbidden content, oversize values,
+ * and records that were never stamped by the observed gate.
+ *
+ * Signature: sanitizeForSupport(record, options?)
+ *   → { ok: true, record } | { ok: false, reason }
+ * `reason` is a static code — it never echoes matched content.
+ */
+
+import { scanText } from '../../sensitiveValueScanner.js';
+import {
+  ALLOWED_FIELDS,
+  ALLOWED_SUPPORT_PAYLOAD_FIELDS,
+  REDACTION_VERSION,
+  MAX_SUPPORT_RECORD_BYTES,
+  MAX_SUPPORT_STRING_CHARS,
+  MAX_OBJECT_KEYS,
+  MAX_ARRAY_ITEMS,
+  MAX_DEPTH,
+} from './allowlist.js';
+import { containsForbiddenContent } from './redaction.js';
+
+function isPlainObject(value) {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+/**
+ * Recursive support-side check. Returns a static rejection reason or null.
+ * Every object level — payload root included — is held to
+ * ALLOWED_SUPPORT_PAYLOAD_FIELDS: the support view carries codes, counts
+ * and timings only, so an unrecognized key anywhere fails closed.
+ */
+function checkValue(value, ctx, depth) {
+  if (value === null) return null;
+  const t = typeof value;
+  if (t === 'boolean') return null;
+  if (t === 'number') return Number.isFinite(value) ? null : 'non_finite_number';
+  if (t === 'string') {
+    if (value.length > MAX_SUPPORT_STRING_CHARS) return 'support_string_too_long';
+    if (containsForbiddenContent(value)) return 'forbidden_content';
+    if (typeof ctx.scanner === 'function') {
+      let hit = false;
+      try {
+        const res = ctx.scanner(value);
+        hit = Boolean(res && res.hasSecret);
+      } catch {
+        hit = true;
+      }
+      if (hit) return 'scanner_flagged';
+    }
+    return null;
+  }
+  if (depth >= MAX_DEPTH) return 'depth_exceeded';
+  if (Array.isArray(value)) {
+    if (value.length > MAX_ARRAY_ITEMS) return 'array_too_large';
+    for (const item of value) {
+      const reason = checkValue(item, ctx, depth + 1);
+      if (reason) return reason;
+    }
+    return null;
+  }
+  if (isPlainObject(value)) {
+    const keys = Object.keys(value);
+    if (keys.length > MAX_OBJECT_KEYS) return 'object_too_large';
+    for (const key of keys) {
+      if (typeof key !== 'string' || key.length === 0 || key.length > 128) {
+        return 'invalid_key';
+      }
+      if (containsForbiddenContent(key)) return 'forbidden_key';
+      if (!ALLOWED_SUPPORT_PAYLOAD_FIELDS.has(key)) return 'payload_field_not_allowed';
+      const reason = checkValue(value[key], ctx, depth + 1);
+      if (reason) return reason;
+    }
+    return null;
+  }
+  return 'unsupported_value';
+}
+
+/**
+ * @param {object} record a record expected to have passed sanitizeObserved
+ * @param {{ scanner?: (text: string) => { hasSecret: boolean } }} [options]
+ * @returns {{ ok: true, record: object } | { ok: false, reason: string }}
+ */
+export function sanitizeForSupport(record, options = {}) {
+  try {
+    if (!isPlainObject(record)) {
+      return { ok: false, reason: 'record_not_object' };
+    }
+    const ctx = {
+      scanner: typeof options.scanner === 'function' ? options.scanner : scanText,
+    };
+
+    // proof the record crossed the observed gate at the current ruleset
+    if (record.redaction_version !== REDACTION_VERSION) {
+      return { ok: false, reason: 'redaction_version_missing' };
+    }
+
+    for (const key of Object.keys(record)) {
+      if (!ALLOWED_FIELDS.has(key)) return { ok: false, reason: 'envelope_field_not_allowed' };
+    }
+
+    if (!isPlainObject(record.payload)) {
+      return { ok: false, reason: 'payload_not_object' };
+    }
+    const payloadReason = checkValue(record.payload, ctx, 0);
+    if (payloadReason) return { ok: false, reason: payloadReason };
+
+    // envelope scalar values get the same content check
+    for (const [key, value] of Object.entries(record)) {
+      if (key === 'payload') continue;
+      const reason = checkValue(value, ctx, 0);
+      if (reason) return { ok: false, reason };
+    }
+
+    let serialized;
+    try {
+      serialized = JSON.stringify(record);
+    } catch {
+      return { ok: false, reason: 'serialization_failed' };
+    }
+    if (serialized.length > MAX_SUPPORT_RECORD_BYTES) {
+      return { ok: false, reason: 'support_record_too_large' };
+    }
+    return { ok: true, record };
+  } catch {
+    return { ok: false, reason: 'sanitizer_error' };
+  }
+}

package/src/core/observability/privacy/sanitizeObserved.js

@@ -0,0 +1,134 @@
+/**
+ * sanitizeObserved.js (TASK-004, SPEC §5 DF-FR06 / §8)
+ *
+ * Runtime canonical write gate. Runs BEFORE any persistent write: keeps
+ * only allowlisted envelope fields, drops deny-listed free-form payload
+ * fields, redacts secrets/paths/PII inside surviving values, enforces
+ * size/depth caps, and stamps `privacy_class` + `redaction_version`.
+ *
+ * The allowlist is the boundary; sensitiveValueScanner.scanText is one
+ * extra signal, never proof. A missing or broken scanner can never let a
+ * deny-list violation or a redactable value through.
+ *
+ * Signature: sanitizeObserved(record, options?)
+ *   → { ok: true, record } | { ok: false, reason }
+ * `reason` is a static code — it never echoes matched content.
+ */
+
+import { scanText } from '../../sensitiveValueScanner.js';
+import {
+  ALLOWED_FIELDS,
+  DENIED_PAYLOAD_FIELDS,
+  REDACTION_VERSION,
+  MAX_RECORD_BYTES,
+  MAX_STRING_CHARS,
+  MAX_OBJECT_KEYS,
+  MAX_ARRAY_ITEMS,
+  MAX_DEPTH,
+} from './allowlist.js';
+import { redactString } from './redaction.js';
+import { PRIVACY_CLASSES } from '../schema/constants.js';
+import { SEMANTIC_REGISTRY } from '../schema/registry.js';
+
+const VALID_PRIVACY_CLASSES = new Set(PRIVACY_CLASSES);
+
+
+function isPlainObject(value) {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function sanitizeKey(key, ctx) {
+  if (typeof key !== 'string' || key.length === 0 || key.length > 128) return null;
+  const cleaned = redactString(key, { scanner: ctx.scanner, maxChars: 128 });
+  // a key that needed redaction is itself unsafe — drop the entry
+  if (cleaned !== key) return null;
+  return key;
+}
+
+function sanitizeValue(value, ctx, depth) {
+  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, { scanner: ctx.scanner, maxChars: MAX_STRING_CHARS });
+  }
+  if (depth >= MAX_DEPTH) return undefined;
+  if (Array.isArray(value)) {
+    const out = [];
+    for (const item of value.slice(0, MAX_ARRAY_ITEMS)) {
+      const v = sanitizeValue(item, ctx, depth + 1);
+      out.push(v === undefined ? null : v);
+    }
+    return out;
+  }
+  if (isPlainObject(value)) {
+    const out = {};
+    let kept = 0;
+    for (const [k, v] of Object.entries(value)) {
+      if (kept >= MAX_OBJECT_KEYS) break;
+      if (DENIED_PAYLOAD_FIELDS.has(k)) continue;
+      const key = sanitizeKey(k, ctx);
+      if (key === null) continue;
+      const sv = sanitizeValue(v, ctx, depth + 1);
+      if (sv === undefined) continue;
+      out[key] = sv;
+      kept += 1;
+    }
+    return out;
+  }
+  return undefined; // functions, symbols, bigint, class instances — dropped
+}
+
+/**
+ * @param {object} record candidate observability record (not mutated)
+ * @param {{ scanner?: (text: string) => { hasSecret: boolean } }} [options]
+ *   scanner defaults to sensitiveValueScanner.scanText; injectable for
+ *   tests. Pass-through of a broken/absent scanner is impossible by
+ *   construction — deny-list and redaction rules run regardless.
+ * @returns {{ ok: true, record: object } | { ok: false, reason: string }}
+ */
+export function sanitizeObserved(record, options = {}) {
+  try {
+    if (!isPlainObject(record)) {
+      return { ok: false, reason: 'record_not_object' };
+    }
+    const ctx = {
+      scanner: typeof options.scanner === 'function' ? options.scanner : scanText,
+    };
+
+    const out = {};
+    for (const [key, value] of Object.entries(record)) {
+      if (!ALLOWED_FIELDS.has(key)) continue;
+      if (key === 'payload') continue; // handled below
+      const sv = sanitizeValue(value, ctx, 0);
+      if (sv !== undefined) out[key] = sv;
+    }
+
+    if (!isPlainObject(record.payload)) {
+      return { ok: false, reason: 'payload_not_object' };
+    }
+    out.payload = sanitizeValue(record.payload, ctx, 0);
+
+    if (!VALID_PRIVACY_CLASSES.has(out.privacy_class)) {
+      // Missing/invalid class: stamp the registry floor for this semantic name
+      // (never lower a valid class — records may restrict, never loosen).
+      const entry = SEMANTIC_REGISTRY[out.semantic_name];
+      out.privacy_class = entry ? entry.privacy_class : 'internal';
+    }
+    out.redaction_version = REDACTION_VERSION;
+
+    let serialized;
+    try {
+      serialized = JSON.stringify(out);
+    } catch {
+      return { ok: false, reason: 'serialization_failed' };
+    }
+    if (serialized.length > MAX_RECORD_BYTES) {
+      return { ok: false, reason: 'record_too_large' };
+    }
+    return { ok: true, record: out };
+  } catch {
+    return { ok: false, reason: 'sanitizer_error' };
+  }
+}

package/src/core/observability/rollout.js

@@ -0,0 +1,155 @@
+/**
+ * rollout.js (TASK-015, SPEC §5 DF-FR13 / §13) — per-seam staged rollout.
+ *
+ *   SEAM_MIN_STAGE = { recorder: 'shadow', projector: 'canary', evaluation: 'default' }
+ *   resolveSeamStages(config) → { recorder, projector, evaluation }
+ *   resolveSeamConfig(config, seam) → live config view bound to that seam
+ *   killSwitch(config, seam?) → config
+ *
+ * The single global flag `observability.stage` promotes off → shadow →
+ * canary → default; each seam activates at its own minimum stage, so the
+ * ladder is: shadow records only, canary adds the support projection,
+ * default adds the evaluation surface. A seam whose effective stage falls
+ * below its minimum resolves to 'off' — the value existing consumers
+ * (createRecorder, projectSupport) already treat as their kill switch.
+ *
+ * Per-seam overrides live at `observability.seams.<seam>.stage` and are
+ * RESTRICTIVE-ONLY: the effective stage is min(global, override) clamped
+ * to the seam minimum. An override can disable or lower a seam; it can
+ * never raise one above the global stage, so a global 'off' is absolute.
+ * Malformed overrides resolve to 'off' for that seam only — a bad value
+ * can never promote anything.
+ *
+ * killSwitch(config) writes 'off' to the global stage AND pins every seam
+ * override to 'off', so re-raising the global stage later cannot silently
+ * revive a seam — re-enabling after a kill is an explicit per-seam act.
+ * killSwitch(config, seam) pins only that seam. Both mutate the config in
+ * place and return it.
+ *
+ * resolveSeamConfig returns a live view (the `observability` node is a
+ * getter, not a snapshot): mutations via killSwitch or direct config edits
+ * are respected on the consumer's next call, matching the recorder's
+ * live-read contract. A view is tagged so killSwitch(view) redirects to
+ * the source config with the bound seam — killing through a bound view
+ * kills that seam, never a different one.
+ */
+
+import { resolveStage } from './emit/config.js';
+
+const STAGE_RANK = { off: 0, shadow: 1, canary: 2, default: 3 };
+
+export const SEAM_NAMES = Object.freeze(['recorder', 'projector', 'evaluation']);
+
+export const SEAM_MIN_STAGE = Object.freeze({
+  recorder: 'shadow',
+  projector: 'canary',
+  evaluation: 'default',
+});
+
+const BOUND = Symbol('ukit.rollout.bound');
+
+function isPlainObject(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function isValidStage(value) {
+  return typeof value === 'string' && value in STAGE_RANK;
+}
+
+function seamOverride(config, seam) {
+  const seams = isPlainObject(config) && isPlainObject(config.observability)
+    ? config.observability.seams
+    : undefined;
+  if (!isPlainObject(seams)) return undefined;
+  const node = seams[seam];
+  if (!isPlainObject(node)) return undefined;
+  // Present-but-malformed is an explicit 'off' for this seam; absent is
+  // undefined so the global stage applies.
+  return node.stage === undefined ? undefined : (isValidStage(node.stage) ? node.stage : 'off');
+}
+
+function effectiveStage(config, seam) {
+  const global = resolveStage(config);
+  const override = seamOverride(config, seam);
+  const rank = Math.min(STAGE_RANK[global], override === undefined ? STAGE_RANK[global] : STAGE_RANK[override]);
+  const stage = Object.keys(STAGE_RANK).find((s) => STAGE_RANK[s] === rank);
+  return rank >= STAGE_RANK[SEAM_MIN_STAGE[seam]] ? stage : 'off';
+}
+
+/**
+ * @param {object} [config] — project runtime config (reads observability.*)
+ * @returns {{ recorder: string, projector: string, evaluation: string }}
+ */
+export function resolveSeamStages(config = null) {
+  const out = {};
+  for (const seam of SEAM_NAMES) out[seam] = effectiveStage(config, seam);
+  return out;
+}
+
+/**
+ * Live per-seam config view for existing consumers that read
+ * `observability.stage` (createRecorder, projectSupport). The view's
+ * `observability` getter re-resolves on every access, so a kill switch or
+ * config edit is honored on the consumer's next call.
+ *
+ * @param {object} config
+ * @param {string} seam — one of SEAM_NAMES
+ * @returns {object} config view; `observability.stage` = effective seam stage
+ */
+export function resolveSeamConfig(config, seam) {
+  if (!SEAM_NAMES.includes(seam)) {
+    throw new RangeError(`resolveSeamConfig: unknown seam ${JSON.stringify(seam)}`);
+  }
+  const source = isPlainObject(config) ? config : {};
+  const view = { ...source };
+  Object.defineProperty(view, 'observability', {
+    enumerable: true,
+    get() {
+      const base = isPlainObject(source.observability) ? source.observability : {};
+      return { ...base, stage: effectiveStage(source, seam) };
+    },
+  });
+  Object.defineProperty(view, BOUND, { value: { source, seam } });
+  return view;
+}
+
+/**
+ * Kill switch. `killSwitch(config)` disables every seam absolutely (global
+ * 'off' + all seam overrides pinned 'off'); `killSwitch(config, seam)`
+ * disables one seam. Mutates and returns the config. Passing a view from
+ * resolveSeamConfig redirects to its source config and bound seam.
+ *
+ * @param {object} config
+ * @param {string} [seam] — one of SEAM_NAMES; omit for a global kill
+ * @returns {object} the mutated config
+ */
+export function killSwitch(config, seam) {
+  let target = config;
+  let targetSeam = seam;
+  if (isPlainObject(config) && config[BOUND]) {
+    target = config[BOUND].source;
+    targetSeam = seam === undefined ? config[BOUND].seam : seam;
+  }
+  if (!isPlainObject(target)) {
+    throw new TypeError('killSwitch: config must be a plain object');
+  }
+  if (targetSeam !== undefined && !SEAM_NAMES.includes(targetSeam)) {
+    throw new RangeError(`killSwitch: unknown seam ${JSON.stringify(targetSeam)}`);
+  }
+  if (!isPlainObject(target.observability)) target.observability = {};
+  if (targetSeam === undefined) {
+    target.observability.stage = 'off';
+    if (!isPlainObject(target.observability.seams)) target.observability.seams = {};
+    for (const name of SEAM_NAMES) {
+      if (!isPlainObject(target.observability.seams[name])) target.observability.seams[name] = {};
+      target.observability.seams[name].stage = 'off';
+    }
+  } else {
+    if (!isPlainObject(target.observability.seams)) target.observability.seams = {};
+    if (!isPlainObject(target.observability.seams[targetSeam])) {
+      target.observability.seams[targetSeam] = {};
+    }
+    target.observability.seams[targetSeam].stage = 'off';
+  }
+  return target;
+}

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

@@ -0,0 +1,66 @@
+// Semantic envelope constants — SPEC §5 DF-FR01/DF-FR02, §7, §8.
+// Frozen for C54: additive changes only; a breaking semantic change requires a
+// new SCHEMA_VERSION major, never an in-place edit of these vocabularies.
+
+export const SCHEMA_VERSION = 1;
+
+// DF-FR01 envelope. `origin` is the DF-FR02 provenance-layer discriminator:
+// required on non-fact records, absent/optional on observed facts.
+export const ENVELOPE_FIELDS = Object.freeze([
+  'record_type',
+  'semantic_name',
+  'schema_version',
+  'record_id',
+  'trace_id',
+  'span_id',
+  'parent_span_id',
+  'execution_id',
+  'session_id',
+  'project_ref',
+  'boot_id',
+  'writer_id',
+  'sequence',
+  'wall_time_utc',
+  'monotonic_ns',
+  'importance',
+  'privacy_class',
+  'origin',
+  'payload',
+]);
+
+export const REQUIRED_ENVELOPE_FIELDS = Object.freeze([
+  'record_type',
+  'semantic_name',
+  'schema_version',
+  'record_id',
+  'boot_id',
+  'writer_id',
+  'sequence',
+  'wall_time_utc',
+  'importance',
+  'privacy_class',
+  'payload',
+]);
+
+// DF-FR02 four provenance layers: observed fact / derived metric /
+// evaluated judgment / optimization decision.
+export const RECORD_TYPES = Object.freeze(['fact', 'derived', 'evaluation', 'decision']);
+
+// Ordered least → most sensitive. `private` marks canonical private segments
+// (append-only redacted facts) that never reach the support view.
+export const PRIVACY_CLASSES = Object.freeze(['public', 'internal', 'sensitive', 'private']);
+
+export const IMPORTANCE_LEVELS = Object.freeze(['low', 'normal', 'high', 'critical']);
+
+// DF-FR08: resource usage provenance. Missing host measurements stay UNKNOWN,
+// never 0.
+export const RESOURCE_SOURCES = Object.freeze(['PROVIDER', 'LOCAL_TOKENIZER', 'ESTIMATED', 'UNKNOWN']);
+
+// SPEC §7: confidence is always typed and never an instruction authority.
+export const CONFIDENCE_TYPES = Object.freeze([
+  'HEURISTIC',
+  'STATISTICAL',
+  'EVALUATOR',
+  'CALIBRATED_MODEL',
+  'MODEL_SELF_REPORT',
+]);