@ngockhoale/ukit 3.0.8 → 3.0.10

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

@@ -0,0 +1,135 @@
+// Registry compatibility — SPEC W1 G1-FR02, §4.
+//
+//   checkRegistryCompatibility(prev, next, options?) → { ok, violations }
+//   validateEnvelopeSchemaVersion(record) → { ok } | { ok, reason }
+//
+// Enforces the frozen registry lifecycle rules mechanically, not by
+// convention: entries are append-only. New keys and new OPTIONAL metadata
+// fields are additive and tolerated; mutating an existing entry's meaning
+// (definition, unit, privacy floor) in place, removing a key, resurrecting
+// a deprecated entry, or re-dating an entry's introduced_version is a
+// breaking change that requires a new SCHEMA_VERSION major — never an
+// in-place edit.
+//
+// Violation codes are a static closed set:
+//   meaning_changed         — definition/unit/privacy_class mutated in place
+//   removed                 — a key present in prev is absent in next
+//   deprecated_resurrected  — a deprecated entry lost its deprecation marker
+//   major_required          — introduced_version was rewritten on an
+//                             existing entry (re-dating history) or the
+//                             registry's own version marker regressed
+
+import { SCHEMA_VERSION } from './constants.js';
+
+export const COMPATIBILITY_VIOLATION_CODES = Object.freeze([
+  'meaning_changed',
+  'removed',
+  'deprecated_resurrected',
+  'major_required',
+]);
+
+// Fields whose mutation changes what an entry MEANS. New optional fields
+// not in this list (e.g. additional hints) are additive and tolerated.
+const MEANING_FIELDS = ['definition', 'unit', 'privacy_class'];
+
+function isPlainObject(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function isDeprecated(entry) {
+  return entry.deprecated !== undefined && entry.deprecated !== null;
+}
+
+/**
+ * Compare two registry snapshots ({ key: entry }) under the additive-only
+ * lifecycle contract. `prev`/`next` may be SEMANTIC_REGISTRY, REASON_CODES,
+ * or any same-shaped registry map.
+ *
+ * @param {object} prev — earlier registry snapshot.
+ * @param {object} next — candidate registry snapshot.
+ * @param {{ schemaVersion?: number }} [options] — the schema major the next
+ *   snapshot ships under. Breaking changes are only legitimate when this is
+ *   a NEW major (> SCHEMA_VERSION); defaults to the current SCHEMA_VERSION,
+ *   so callers must opt into a major bump explicitly.
+ * @returns {{ ok: boolean, violations: Array<{ code: string, key: string }> }}
+ */
+export function checkRegistryCompatibility(prev, next, options = {}) {
+  const violations = [];
+  const prevRegistry = isPlainObject(prev) ? prev : {};
+  const nextRegistry = isPlainObject(next) ? next : {};
+  const schemaVersion = options.schemaVersion === undefined ? SCHEMA_VERSION : options.schemaVersion;
+
+  // A declared major bump opens a new registry lineage — breaking changes
+  // are legitimate there and there is nothing to enforce on this contract.
+  if (Number.isInteger(schemaVersion) && schemaVersion > SCHEMA_VERSION) {
+    return { ok: true, violations: [] };
+  }
+  // A regressed major marker is always invalid.
+  if (schemaVersion !== SCHEMA_VERSION) {
+    return { ok: false, violations: [{ code: 'major_required', key: 'schema_version' }] };
+  }
+  // Same-major snapshot pair: enforce the additive-only lifecycle rules.
+
+  for (const key of Object.keys(prevRegistry)) {
+    const before = prevRegistry[key];
+    const after = nextRegistry[key];
+
+    if (after === undefined) {
+      violations.push({ code: 'removed', key });
+      continue;
+    }
+    if (!isPlainObject(before) || !isPlainObject(after)) {
+      violations.push({ code: 'meaning_changed', key });
+      continue;
+    }
+
+    // Re-dating an existing entry's introduced_version rewrites registry
+    // history — always a major boundary, never an in-place edit.
+    if (before.introduced_version !== after.introduced_version) {
+      violations.push({ code: 'major_required', key });
+    }
+
+    if (isDeprecated(before) && !isDeprecated(after)) {
+      violations.push({ code: 'deprecated_resurrected', key });
+    }
+
+    for (const field of MEANING_FIELDS) {
+      if (before[field] === undefined && after[field] === undefined) continue;
+      // A missing field on either side is not a meaning change — older
+      // snapshots simply did not carry the metadata.
+      if (before[field] === undefined || after[field] === undefined) continue;
+      if (before[field] !== after[field]) {
+        violations.push({ code: 'meaning_changed', key });
+        break;
+      }
+    }
+  }
+
+  return { ok: violations.length === 0, violations };
+}
+
+/**
+ * Gate a semantic envelope on its declared schema major. Tolerates any
+ * unknown optional fields — version compatibility is judged ONLY on
+ * `schema_version` (DF-FR03 additive-only tolerance lives upstream in
+ * validateSemanticRecord).
+ *
+ * @param {object} record — candidate semantic envelope.
+ * @returns {{ ok: true } | { ok: false, reason: string }}
+ */
+export function validateEnvelopeSchemaVersion(record) {
+  if (!isPlainObject(record)) {
+    return { ok: false, reason: 'record must be a plain object' };
+  }
+  const version = record.schema_version;
+  if (!Number.isInteger(version)) {
+    return { ok: false, reason: `schema_version must be an integer (got ${JSON.stringify(version)})` };
+  }
+  if (version !== SCHEMA_VERSION) {
+    return {
+      ok: false,
+      reason: `unsupported schema_version ${version} — this major requires schema ${version} support; supported: ${SCHEMA_VERSION}`,
+    };
+  }
+  return { ok: true };
+}

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

@@ -18,111 +18,147 @@ const V1 = '1';
 export const SEMANTIC_REGISTRY = Object.freeze({
   'execution.started': {
     definition: 'An execution unit (task/episode) began. Span root for the execution.',
+    unit: 'event',
     privacy_class: 'internal',
     retention_hint: 'retain',
     introduced_version: V1,
+    deprecated: null,
   },
   'execution.completed': {
     definition: 'An execution unit finished successfully. Payload carries outcome and duration.',
+    unit: 'ms',
     privacy_class: 'internal',
     retention_hint: 'retain',
     introduced_version: V1,
+    deprecated: null,
   },
   'execution.failed': {
     definition: 'An execution unit terminated with failure. Payload carries error_code.',
+    unit: 'ms',
     privacy_class: 'internal',
     retention_hint: 'retain',
     introduced_version: V1,
+    deprecated: null,
   },
   'execution.blocked': {
     definition: 'An execution unit stopped on an unmet precondition or gate.',
+    unit: 'ms',
     privacy_class: 'internal',
     retention_hint: 'retain',
     introduced_version: V1,
+    deprecated: null,
   },
   'tool.started': {
     definition: 'A tool invocation began. Payload may name the tool; arguments stay redacted.',
+    unit: 'event',
     privacy_class: 'sensitive',
     retention_hint: 'retain',
     introduced_version: V1,
+    deprecated: null,
   },
   'tool.completed': {
     definition: 'A tool invocation finished. Payload carries duration; output stays redacted.',
+    unit: 'ms',
     privacy_class: 'sensitive',
     retention_hint: 'retain',
     introduced_version: V1,
+    deprecated: null,
   },
   'tool.failed': {
     definition: 'A tool invocation failed. Payload carries error_code; stderr stays redacted.',
+    unit: 'ms',
     privacy_class: 'sensitive',
     retention_hint: 'retain',
     introduced_version: V1,
+    deprecated: null,
   },
   'model.started': {
     definition: 'A model attempt began. Payload carries attempt_index.',
+    unit: 'event',
     privacy_class: 'internal',
     retention_hint: 'retain',
     introduced_version: V1,
+    deprecated: null,
   },
   'model.completed': {
     definition: 'A model attempt finished. Payload carries duration and typed resource usage.',
+    unit: 'ms',
     privacy_class: 'internal',
     retention_hint: 'retain',
     introduced_version: V1,
+    deprecated: null,
   },
   'model.failed': {
     definition: 'A model attempt failed. Payload carries error_code and typed resource usage.',
+    unit: 'ms',
     privacy_class: 'internal',
     retention_hint: 'retain',
     introduced_version: V1,
+    deprecated: null,
   },
   'cache.hit': {
     definition: 'A cache lookup resolved from cache. Payload identifies the cache seam, not content.',
+    unit: 'event',
     privacy_class: 'internal',
     retention_hint: 'aggregate',
     introduced_version: V1,
+    deprecated: null,
   },
   'cache.miss': {
     definition: 'A cache lookup did not resolve from cache.',
+    unit: 'event',
     privacy_class: 'internal',
     retention_hint: 'aggregate',
     introduced_version: V1,
+    deprecated: null,
   },
   'verification.completed': {
     definition: 'A verification step ran to completion. Payload carries the verdict, not raw output.',
+    unit: 'event',
     privacy_class: 'internal',
     retention_hint: 'retain',
     introduced_version: V1,
+    deprecated: null,
   },
   'context.item.injected': {
     definition: 'A context item (e.g. user correction) entered the episode. Kind only, never content.',
+    unit: 'event',
     privacy_class: 'sensitive',
     retention_hint: 'retain',
     introduced_version: V1,
+    deprecated: null,
   },
   'decision.made': {
     definition: 'An optimization or routing decision was recorded with experiment provenance.',
+    unit: 'event',
     privacy_class: 'internal',
     retention_hint: 'retain',
     introduced_version: V1,
+    deprecated: null,
   },
   'telemetry.dropped': {
     definition: 'Telemetry records were dropped or sampled. Payload carries reason_code and count.',
+    unit: 'records',
     privacy_class: 'internal',
     retention_hint: 'retain',
     introduced_version: V1,
+    deprecated: null,
   },
   'telemetry.recovered': {
     definition: 'Previously incomplete telemetry recovered (e.g. partial tail repaired).',
+    unit: 'records',
     privacy_class: 'internal',
     retention_hint: 'retain',
     introduced_version: V1,
+    deprecated: null,
   },
   'telemetry.redacted': {
     definition: 'A record or field was redacted before persistence. Payload carries the field path.',
+    unit: 'fields',
     privacy_class: 'internal',
     retention_hint: 'retain',
     introduced_version: V1,
+    deprecated: null,
   },
 });
 
@@ -131,87 +167,150 @@ export const SEMANTIC_REGISTRY = Object.freeze({
 export const REASON_CODES = Object.freeze({
   TOOL_TIMEOUT: {
     definition: 'A tool or model call exceeded its deadline.',
+    unit: null,
     introduced_version: V1,
+    deprecated: null,
+    privacy_class: 'internal',
   },
   AUTH_FAILED: {
     definition: 'Authentication or authorization was rejected by the provider.',
+    unit: null,
     introduced_version: V1,
+    deprecated: null,
+    privacy_class: 'internal',
   },
   RATE_LIMITED: {
     definition: 'The provider or host throttled the request.',
+    unit: null,
     introduced_version: V1,
+    deprecated: null,
+    privacy_class: 'internal',
   },
   MODEL_ERROR: {
     definition: 'The model endpoint returned an error response.',
+    unit: null,
     introduced_version: V1,
+    deprecated: null,
+    privacy_class: 'internal',
   },
   NETWORK_ERROR: {
     definition: 'A transport-level failure prevented the call.',
+    unit: null,
     introduced_version: V1,
+    deprecated: null,
+    privacy_class: 'internal',
   },
   QUEUE_OVERFLOW: {
     definition: 'The emit queue exceeded its bound; records were dropped.',
+    unit: null,
     introduced_version: V1,
+    deprecated: null,
+    privacy_class: 'internal',
   },
   SAMPLED_OUT: {
     definition: 'The record was excluded by the configured sampling policy.',
+    unit: null,
     introduced_version: V1,
+    deprecated: null,
+    privacy_class: 'internal',
   },
   HOST_BLIND: {
     definition: 'The host does not expose the field; value stays explicitly unknown.',
+    unit: null,
     introduced_version: V1,
+    deprecated: null,
+    privacy_class: 'internal',
   },
   FLUSH_FAILED: {
     definition: 'A recorder flush could not persist its batch; user task unaffected.',
+    unit: null,
     introduced_version: V1,
+    deprecated: null,
+    privacy_class: 'internal',
   },
   DISK_FULL: {
     definition: 'The storage volume rejected a write for lack of space.',
+    unit: null,
     introduced_version: V1,
+    deprecated: null,
+    privacy_class: 'internal',
   },
   PERMISSION_DENIED: {
     definition: 'The filesystem or OS denied the operation.',
+    unit: null,
     introduced_version: V1,
+    deprecated: null,
+    privacy_class: 'internal',
   },
   SCHEMA_MISMATCH: {
     definition: 'A record or bundle failed schema validation.',
+    unit: null,
     introduced_version: V1,
+    deprecated: null,
+    privacy_class: 'internal',
   },
   CHECKSUM_MISMATCH: {
     definition: 'A segment or bundle digest did not match its manifest.',
+    unit: null,
     introduced_version: V1,
+    deprecated: null,
+    privacy_class: 'internal',
   },
   PARTIAL_TAIL: {
     definition: 'A segment ended mid-record; the tail was truncated on recovery.',
+    unit: null,
     introduced_version: V1,
+    deprecated: null,
+    privacy_class: 'internal',
   },
   ROTATED: {
     definition: 'A segment was rotated out by retention or cap policy.',
+    unit: null,
     introduced_version: V1,
+    deprecated: null,
+    privacy_class: 'internal',
   },
   REDACTED_FIELD: {
     definition: 'A payload field was removed by the privacy gate before persistence.',
+    unit: null,
     introduced_version: V1,
+    deprecated: null,
+    privacy_class: 'internal',
   },
   USER_CANCELLED: {
     definition: 'The user aborted the operation.',
+    unit: null,
     introduced_version: V1,
+    deprecated: null,
+    privacy_class: 'internal',
   },
   GATE_BLOCKED: {
     definition: 'A completion or security gate stopped the execution.',
+    unit: null,
     introduced_version: V1,
+    deprecated: null,
+    privacy_class: 'internal',
   },
   WAITING_ON_TOOL: {
     definition: 'The span is waiting on a tool result.',
+    unit: null,
     introduced_version: V1,
+    deprecated: null,
+    privacy_class: 'internal',
   },
   WAITING_ON_MODEL: {
     definition: 'The span is waiting on a model response.',
+    unit: null,
     introduced_version: V1,
+    deprecated: null,
+    privacy_class: 'internal',
   },
   WAITING_ON_USER: {
     definition: 'The span is waiting on user input.',
+    unit: null,
     introduced_version: V1,
+    deprecated: null,
+    privacy_class: 'internal',
   },
 });
 

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

@@ -112,6 +112,13 @@ function validatePayload(payload, errors) {
   if (payload.telemetry_complete !== undefined && typeof payload.telemetry_complete !== 'boolean') {
     errors.push('payload.telemetry_complete must be a boolean');
   }
+  // Duration is always milliseconds — a unit-suffixed string or non-finite
+  // number is malformed, never a unit conversion request.
+  if (payload.duration_ms !== undefined && payload.duration_ms !== null) {
+    if (typeof payload.duration_ms !== 'number' || !Number.isFinite(payload.duration_ms) || payload.duration_ms < 0) {
+      errors.push('payload.duration_ms must be a non-negative finite number (unit is always milliseconds)');
+    }
+  }
 }
 
 export function validateSemanticRecord(record, context) {

package/src/core/observability/support/import.js

@@ -11,12 +11,16 @@
  *
  * Validation order (fail-fast, first reason wins):
  *   input shape → container parse (zip EOCD/CD/local headers, or dir
- *   listing) → per-entry name safety (flat namespace, no traversal,
- *   no absolute/drive/backslash) → compression method allowlist →
- *   entry/total size caps → zip-bomb ratio → CRC32 + declared-size
- *   integrity → manifest presence → manifest format/checksum/member
- *   verification → file-type allowlist (.md/.json/.jsonl) →
- *   records.jsonl line parsing.
+ *   listing) → one-folder unwrap (zip only: if every member shares
+ *   exactly one `Prefix/…` root — an OS "Compress folder" bundle — the
+ *   prefix is stripped; prefix-only dir entries are ignored; mixed-root
+ *   archives keep raw names and fail below) → symlink check (unix mode
+ *   in CD external attrs, `symlink_entry`) → per-entry name safety
+ *   (flat namespace, no traversal, no absolute/drive/backslash) →
+ *   compression method allowlist → entry/total size caps → zip-bomb
+ *   ratio → CRC32 + declared-size integrity → manifest presence →
+ *   manifest format/checksum/member verification → file-type allowlist
+ *   (.md/.json/.jsonl) → records.jsonl line parsing.
  *
  * Defense invariants:
  *   - Nothing is ever executed, sourced, or written outside the input
@@ -134,15 +138,55 @@ function unzip(buf) {
     const nameLen = buf.readUInt16LE(p + 28);
     const extraLen = buf.readUInt16LE(p + 30);
     const commentLen = buf.readUInt16LE(p + 32);
+    // upper 16 bits of external attrs carry the unix mode (zip spec §4.4.15)
+    const externalAttrs = buf.readUInt32LE(p + 38);
     const localOffset = buf.readUInt32LE(p + 42);
     const name = buf.subarray(p + 46, p + 46 + nameLen).toString('utf8');
-    central.push({ name, method, crc, compressedSize, uncompressedSize, localOffset });
+    central.push({ name, method, crc, compressedSize, uncompressedSize, externalAttrs, localOffset });
     p += 46 + nameLen + extraLen + commentLen;
   }
 
+  // One-folder unwrap (G4-FR09): a real OS "Compress folder → .zip" prefixes
+  // every member with `FolderName/`. When every member shares exactly one
+  // top-level directory prefix, strip it so the flat-name safety rules and
+  // the manifest map apply to the unwrapped names. Prefix-only dir entries
+  // (`FolderName/`) carry no payload and are ignored. Mixed-root archives
+  // (no shared single prefix) keep their raw names and fail the flat-name
+  // checks below — we never guess which subtree is the bundle.
+  const prefixes = new Set();
+  let sharedPrefix = true;
+  for (const e of central) {
+    const i = e.name.indexOf('/');
+    if (i <= 0) {
+      sharedPrefix = false; // root-level or leading-slash member → no unwrap
+      break;
+    }
+    prefixes.add(e.name.slice(0, i + 1));
+  }
+  const members = [];
+  if (sharedPrefix && prefixes.size === 1) {
+    const prefix = [...prefixes][0];
+    for (const e of central) {
+      if (e.name !== prefix) {
+        e.name = e.name.slice(prefix.length);
+        members.push(e);
+      }
+      // e.name === prefix → prefix-only dir entry, ignored
+    }
+  } else {
+    members.push(...central);
+  }
+
   // Metadata-level bounds before touching payloads.
+  const UNIX_S_IFMT = 0o170000;
+  const UNIX_S_IFLNK = 0o120000;
   let totalUncompressed = 0;
-  for (const e of central) {
+  for (const e of members) {
+    // symlink members are rejected on central-directory metadata alone —
+    // the payload is never touched (G4-FR10).
+    if (((e.externalAttrs >>> 16) & UNIX_S_IFMT) === UNIX_S_IFLNK) {
+      return fail('symlink_entry', { name: e.name });
+    }
     if (!isSafeEntryName(e.name)) {
       return fail('unsafe_entry_name', { name: e.name });
     }
@@ -170,7 +214,7 @@ function unzip(buf) {
   }
 
   // Extraction: local header → data slice → inflate → CRC + size check.
-  for (const e of central) {
+  for (const e of members) {
     const off = e.localOffset;
     if (off + 30 > buf.length || buf.readUInt32LE(off) !== LOCAL_SIG) {
       return fail('corrupt_local_header', { name: e.name });

package/src/core/observability/support/paths.js

@@ -30,12 +30,22 @@ import { ioReason } from '../segments/internal.js';
 
 export const SUPPORT_DIR_NAME = 'UKit Support';
 
+/**
+ * Path operations follow the INJECTED platform, never the host: an
+ * observability record replayed on a different OS must still produce the
+ * target platform's separators and join semantics.
+ */
+function pathFor(platform) {
+  return platform === 'win32' ? path.win32 : path.posix;
+}
+
 function candidates({ homeDir, env, platform }) {
   const list = [];
+  const p = pathFor(platform);
   if (platform === 'win32') {
     const profile = env.USERPROFILE || homeDir;
     if (typeof profile === 'string' && profile.length > 0) {
-      list.push(path.join(profile, 'Documents'));
+      list.push(p.join(profile, 'Documents'));
     }
     return list;
   }
@@ -44,7 +54,7 @@ function candidates({ homeDir, env, platform }) {
     if (typeof xdg === 'string' && xdg.length > 0) list.push(xdg);
   }
   if (typeof homeDir === 'string' && homeDir.length > 0) {
-    list.push(path.join(homeDir, 'Documents'));
+    list.push(p.join(homeDir, 'Documents'));
   }
   return list;
 }
@@ -88,7 +98,7 @@ export async function resolveSupportDir(opts = {}) {
       reason = err && err.code === 'EACCES' ? 'documents_not_writable' : ioReason(err);
       continue;
     }
-    return { ok: true, dir: path.join(documents, SUPPORT_DIR_NAME) };
+    return { ok: true, dir: pathFor(platform).join(documents, SUPPORT_DIR_NAME) };
   }
   return { ok: false, reason };
 }