@ngockhoale/ukit 3.0.6 → 3.0.8

package/src/core/observability/evaluation/optimizationKnowledge.js

@@ -0,0 +1,172 @@
+/**
+ * optimizationKnowledge.js (TASK-013, SPEC §5 DF-FR02/DF-FR12, §7, §8) —
+ * append-only optimization knowledge base.
+ *
+ *   createOptimizationStore({ root, clock? })
+ *     → { recordOptimization(entry): { id }, listOptimizations(filter?), storePath }
+ *
+ * Persists the evidence-linked optimization lineage — hypothesis →
+ * pre-registered experiment → guardrails → decision → rollback — as an
+ * append-only JSONL file under the observability storage root. Records are
+ * immutable once written: a reversal is a NEW record linked via
+ * `supersedes`, never a rewrite, and negative results are never erased.
+ *
+ * Provenance layers (DF-FR02) stay separate: `provenance.source` must name
+ * one of PROVENANCE_SOURCES. A finding with no evidence refs or an unknown
+ * provenance source is stored with `decision: 'unsupported'` — evaluator
+ * opinion is recorded, never promoted to fact or policy.
+ *
+ * Invariants (SPEC §12, DF-FR12):
+ *   - `decision: 'promoted'` or `applied: true` REQUIRE
+ *     `controlled_rollout.evidence_refs` — no promotion from token
+ *     reduction alone; violating entries throw TypeError.
+ *   - `decision: 'unsupported'` records can never carry `applied: true`.
+ *   - This module writes ONLY inside `root` — no runtime config, no
+ *     learning artifacts, no automatic application of anything.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import crypto from 'node:crypto';
+
+export const OPTIMIZATION_STORE_FILE = 'optimization-kb.jsonl';
+
+export const DECISIONS = Object.freeze([
+  'hypothesis',
+  'promoted',
+  'rejected',
+  'rolled_back',
+  'unsupported',
+]);
+
+/** The four provenance layers of DF-FR02 — anything else is unsupported. */
+export const PROVENANCE_SOURCES = Object.freeze([
+  'observed_fact',
+  'derived_metric',
+  'evaluated_judgment',
+  'optimization_decision',
+]);
+
+function isPlainObject(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function stringList(value) {
+  if (!Array.isArray(value)) return [];
+  return [...new Set(value.filter((v) => typeof v === 'string' && v.length > 0))].sort();
+}
+
+function dataCopy(value, fallback) {
+  if (value === undefined) return fallback;
+  return JSON.parse(JSON.stringify(value));
+}
+
+function hasControlledRolloutEvidence(entry) {
+  return (
+    isPlainObject(entry.controlled_rollout) &&
+    Array.isArray(entry.controlled_rollout.evidence_refs) &&
+    entry.controlled_rollout.evidence_refs.some((r) => typeof r === 'string' && r.length > 0)
+  );
+}
+
+function countExistingLines(storePath) {
+  try {
+    const text = fs.readFileSync(storePath, 'utf8');
+    if (text.length === 0) return 0;
+    return text.endsWith('\n') ? text.split('\n').length - 1 : text.split('\n').length;
+  } catch {
+    return 0;
+  }
+}
+
+export function createOptimizationStore({ root, clock } = {}) {
+  if (typeof root !== 'string' || root.length === 0) {
+    throw new TypeError('createOptimizationStore: root must be a non-empty directory path');
+  }
+  const storePath = path.join(root, OPTIMIZATION_STORE_FILE);
+  const now = typeof clock === 'function' ? clock : () => new Date().toISOString();
+
+  function recordOptimization(entry) {
+    if (!isPlainObject(entry)) {
+      throw new TypeError('recordOptimization: entry must be an object');
+    }
+
+    const evidenceRefs = stringList(entry.evidence_refs);
+    const provenanceSource =
+      isPlainObject(entry.provenance) && typeof entry.provenance.source === 'string'
+        ? entry.provenance.source
+        : null;
+    const supported = evidenceRefs.length > 0 && PROVENANCE_SOURCES.includes(provenanceSource);
+
+    let decision = DECISIONS.includes(entry.decision) ? entry.decision : 'hypothesis';
+    let applied = entry.applied === true;
+
+    if (!supported) {
+      // Evaluator opinion without evidence/provenance is stored but can
+      // never be promoted or applied — the invariant is enforced here.
+      decision = 'unsupported';
+      applied = false;
+    } else if ((decision === 'promoted' || applied) && !hasControlledRolloutEvidence(entry)) {
+      throw new TypeError(
+        'recordOptimization: decision promoted / applied requires controlled_rollout.evidence_refs',
+      );
+    }
+
+    const core = {
+      opportunity_id: typeof entry.opportunity_id === 'string' ? entry.opportunity_id : null,
+      hypothesis: typeof entry.hypothesis === 'string' ? entry.hypothesis : null,
+      baseline: dataCopy(entry.baseline, null),
+      variant: dataCopy(entry.variant, null),
+      evidence_refs: evidenceRefs,
+      guardrail: dataCopy(entry.guardrail, null),
+      decision,
+      applied,
+      controlled_rollout: dataCopy(entry.controlled_rollout, null),
+      provenance: { source: provenanceSource },
+      versions: dataCopy(entry.versions, {}),
+      rollback_criterion:
+        typeof entry.rollback_criterion === 'string' ? entry.rollback_criterion : null,
+      supersedes: stringList(entry.supersedes),
+      created_at: now(),
+    };
+
+    const seq = countExistingLines(storePath) + 1;
+    const digest = crypto
+      .createHash('sha256')
+      .update(`${seq}:${JSON.stringify(core)}`)
+      .digest('hex')
+      .slice(0, 12);
+    const record = { id: `opt-${seq}-${digest}`, ...core };
+
+    fs.mkdirSync(root, { recursive: true });
+    fs.appendFileSync(storePath, `${JSON.stringify(record)}\n`, 'utf8');
+    return { id: record.id };
+  }
+
+  function listOptimizations(filter = {}) {
+    let text;
+    try {
+      text = fs.readFileSync(storePath, 'utf8');
+    } catch {
+      return [];
+    }
+    const records = [];
+    for (const line of text.split('\n')) {
+      if (line.length === 0) continue;
+      try {
+        const parsed = JSON.parse(line);
+        if (isPlainObject(parsed)) records.push(parsed);
+      } catch {
+        // Corrupt line: skip — the KB degrades, it never throws on read.
+      }
+    }
+    const { decision, opportunity_id } = isPlainObject(filter) ? filter : {};
+    return records.filter(
+      (r) =>
+        (decision === undefined || r.decision === decision) &&
+        (opportunity_id === undefined || r.opportunity_id === opportunity_id),
+    );
+  }
+
+  return { recordOptimization, listOptimizations, storePath };
+}

package/src/core/observability/evaluation/replay.js

@@ -0,0 +1,143 @@
+/**
+ * replay.js (TASK-014, SPEC §5 DF-FR08/DF-FR12, §8) — honest replay fidelity.
+ *
+ *   replayCase(goldenCase, { policyId }): ReplayResult
+ *
+ * Replay is a READ-ONLY, deterministic operation: it materializes the
+ * recorded run for the requested policy into canonical envelope records and
+ * returns them for static evaluation. It NEVER executes imported content,
+ * never calls a model, and never writes to any store — no fs, no clock, no
+ * randomness. The same (case, policyId) always produces the same records.
+ *
+ * Fidelity tags (declared by the case, never inferred):
+ *   POLICY    — recorded under the named policy variant; full causal claim
+ *               within the recorded episode.
+ *   CONTEXT   — recorded context replay (e.g. bundle-sourced evidence);
+ *               imported content is inert data, evaluated statically only.
+ *   SIMULATED — recorded inputs/versions replayed without a live host;
+ *               user acceptance is not observable → quality stays `unknown`
+ *               and no full causal effect may be claimed.
+ *
+ * Compact run encoding (golden fixture format): each record carries the
+ * canonical field names plus `dt_ms` — the millisecond offset from the
+ * episode start. replayCase materializes `monotonic_ns`, `wall_time_utc`,
+ * `record_id`, `trace_id`, `execution_id` and the shared envelope fields
+ * deterministically; explicit canonical values always win.
+ */
+
+export const REPLAY_TAGS = Object.freeze(['POLICY', 'CONTEXT', 'SIMULATED']);
+
+export const REPLAY_LIMITATIONS = Object.freeze({
+  POLICY: Object.freeze([]),
+  CONTEXT: Object.freeze(['imported_content_static_only']),
+  SIMULATED: Object.freeze([
+    'recorded_inputs_only',
+    'no_user_acceptance_observable',
+    'no_full_causal_claim',
+  ]),
+});
+
+const REPLAY_EPOCH_MS = Date.UTC(2026, 0, 1, 0, 0, 0);
+const REPLAY_WRITER = 'writer-replay';
+const REPLAY_BOOT = 'boot-replay';
+const REPLAY_SESSION = 'session-replay';
+const REPLAY_PROJECT = 'project-replay';
+
+function isPlainObject(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function asTag(value) {
+  return REPLAY_TAGS.includes(value) ? value : 'POLICY';
+}
+
+/**
+ * Resolve the run for `policyId`. `run.same_as` aliases another policy's run
+ * (one hop) so identical variants do not duplicate record bytes.
+ */
+function resolveRun(runs, policyId) {
+  if (!isPlainObject(runs)) return null;
+  let run = runs[policyId];
+  if (isPlainObject(run) && typeof run.same_as === 'string') {
+    run = runs[run.same_as];
+  }
+  return isPlainObject(run) && Array.isArray(run.records) ? run : null;
+}
+
+/**
+ * Materialize one compact record into a canonical envelope record.
+ * Deterministic: ids and clocks derive from (caseId, policyId, index, dt_ms).
+ */
+function materializeRecord(raw, ctx, index) {
+  const record = isPlainObject(raw) ? { ...raw } : {};
+  const dtMs = typeof record.dt_ms === 'number' && Number.isFinite(record.dt_ms)
+    ? record.dt_ms
+    : index;
+  delete record.dt_ms;
+
+  if (typeof record.record_type !== 'string') record.record_type = 'fact';
+  if (typeof record.schema_version !== 'number') record.schema_version = 1;
+  if (typeof record.record_id !== 'string') {
+    record.record_id = `rec-${ctx.caseId}-${ctx.policyId}-${String(index + 1).padStart(4, '0')}`;
+  }
+  if (typeof record.trace_id !== 'string') record.trace_id = ctx.traceId;
+  if (typeof record.execution_id !== 'string') record.execution_id = ctx.executionId;
+  if (typeof record.session_id !== 'string') record.session_id = REPLAY_SESSION;
+  if (typeof record.project_ref !== 'string') record.project_ref = REPLAY_PROJECT;
+  if (typeof record.boot_id !== 'string') record.boot_id = REPLAY_BOOT;
+  if (typeof record.writer_id !== 'string') record.writer_id = REPLAY_WRITER;
+  if (typeof record.sequence !== 'number') record.sequence = index + 1;
+  if (typeof record.wall_time_utc !== 'string') {
+    record.wall_time_utc = new Date(REPLAY_EPOCH_MS + dtMs).toISOString();
+  }
+  if (typeof record.monotonic_ns !== 'number') record.monotonic_ns = dtMs * 1e6;
+  if (typeof record.importance !== 'string') record.importance = 'normal';
+  if (typeof record.privacy_class !== 'string') record.privacy_class = 'public';
+  if (!isPlainObject(record.payload)) record.payload = {};
+  return record;
+}
+
+/**
+ * @param {object} goldenCase — golden case with `runs` and optional
+ *   `fidelity.tag` / `provenance` / `imported_content`.
+ * @param {{ policyId?: string }} [options]
+ * @returns {{ ok: true, case_id, tag, limitations, records, provenance }
+ *         | { ok: false, reason, case_id, tag, limitations }}
+ */
+export function replayCase(goldenCase, { policyId } = {}) {
+  const caseId = isPlainObject(goldenCase) && typeof goldenCase.case_id === 'string'
+    ? goldenCase.case_id
+    : 'unknown';
+  const tag = asTag(isPlainObject(goldenCase) && goldenCase.fidelity && goldenCase.fidelity.tag);
+  const limitations = [...REPLAY_LIMITATIONS[tag]];
+  const provenance = isPlainObject(goldenCase) && isPlainObject(goldenCase.provenance)
+    ? { ...goldenCase.provenance }
+    : {};
+  if (provenance.source === 'support_bundle' && !limitations.includes('imported_content_static_only')) {
+    limitations.push('imported_content_static_only');
+  }
+
+  const fail = (reason) => ({ ok: false, reason, case_id: caseId, tag, limitations });
+  if (!isPlainObject(goldenCase)) return fail('invalid_case');
+  if (typeof policyId !== 'string' || policyId.length === 0) return fail('missing_policy');
+
+  const run = resolveRun(goldenCase.runs, policyId);
+  if (!run) return fail('missing_run');
+
+  const ctx = {
+    caseId,
+    policyId,
+    traceId: `trace-${caseId}-${policyId}`,
+    executionId: `exec-${caseId}-${policyId}`,
+  };
+  const records = run.records.map((raw, index) => materializeRecord(raw, ctx, index));
+
+  return {
+    ok: true,
+    case_id: caseId,
+    tag,
+    limitations,
+    records,
+    provenance: { ...provenance, policy_id: policyId },
+  };
+}