@ngockhoale/ukit 3.1.9 → 3.2.0

package/src/core/agentRuntime/telemetry.js

@@ -7,6 +7,7 @@
  *   emitSpanRecord(telemetry, ctx, semanticName, payload) → EmitResult
  *   durationMs(startNs, nowNs) → positive ms | null
  *   projectRootFromRuntimeDir(runtimeDir) → projectRoot | null
+ *   buildTraceExcerpt(records, opts) → {entries, gaps, stats} (V-06)
  *
  * Contracts:
  *   - Emission is fire-and-forget: every helper is synchronous, wraps
@@ -31,6 +32,11 @@ import path from 'node:path';
 import { getRecorder } from '../observability/emit/lifecycle.js';
 import { RESOURCE_SOURCES } from '../observability/schema/constants.js';
 import { REASON_CODES } from '../observability/schema/registry.js';
+import { validateSemanticRecord } from '../observability/schema/validate.js';
+import { sanitizeForSupport } from '../observability/privacy/sanitizeForSupport.js';
+import { MAX_SUPPORT_STRING_CHARS } from '../observability/privacy/allowlist.js';
+import { redactString } from '../observability/privacy/redaction.js';
+import { scanText } from '../sensitiveValueScanner.js';
 
 /** Monotonic nanoseconds — BigInt where available (process.hrtime). */
 export function nowNs() {
@@ -55,6 +61,10 @@ function isNonEmptyString(value) {
   return typeof value === 'string' && value.length > 0;
 }
 
+function isPlainObject(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
 /**
  * agent_id source (SPEC §14): UKIT_AGENT_ID env first, config.agent.id
  * second, absent otherwise. The field is omitted entirely — never ''.
@@ -202,3 +212,116 @@ export function typedResource(resource) {
   if (source && source !== 'UNKNOWN') return { resource: { value, source }, complete: true };
   return { resource: { value, source: 'ESTIMATED' }, complete: true };
 }
+
+// --- V-06 trace excerpt for support bundles --------------------------------
+// `buildTraceExcerpt` is the read-side counterpart of emitSpanRecord: it
+// turns recorder-fed SemanticRecords into bounded, sanitized trace lines
+// for a support bundle. Every record passes validateSemanticRecord AND
+// the independent sanitizeForSupport second gate; survivors keep only
+// allowlisted envelope/payload fields, strings pass redactString, and
+// caller-supplied pseudonyms replace raw ids. Non-conforming records are
+// reported as typed gap entries — never silently smuggled, never thrown.
+
+const TRACE_ID_FIELDS = Object.freeze([
+  'record_id', 'trace_id', 'span_id', 'parent_span_id',
+  'execution_id', 'session_id', 'project_ref', 'boot_id', 'writer_id',
+]);
+
+const TRACE_ENVELOPE_KEEP = new Set([
+  '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', 'redaction_version', 'sampling',
+]);
+
+/**
+ * Build a sanitized trace excerpt from SemanticRecords. Never throws.
+ *
+ * Every record passes the FULL two-gate chain — validateSemanticRecord
+ * then the independent sanitizeForSupport default-deny gate — so a
+ * survivor's payload is already allowlist-clean (codes, counts, timings
+ * only). The excerpt keeps only the envelope fields named in
+ * TRACE_ENVELOPE_KEEP, re-passes strings through redactString, and
+ * substitutes caller-supplied pseudonyms for raw ids. Rejects land as
+ * typed gap entries — never silently smuggled, never thrown.
+ *
+ * @param {unknown} records array of records (non-array → 'trace_unavailable')
+ * @param {object} [opts]
+ * @param {number} [opts.maxRecords=256] entry cap (gaps share the budget)
+ * @param {(value:string)=>{hasSecret:boolean}} [opts.scanner] defaults scanText
+ * @param {(value:string,kind:string)=>string} [opts.pseudonymize] id rewrite
+ * @returns {{ entries: Array, gaps: Array, stats: {in:number, kept:number,
+ *   rejected:number, truncated:number} }}
+ */
+
+export function buildTraceExcerpt(records, opts = {}) {
+  const maxRecords = Number.isInteger(opts.maxRecords) ? Math.max(0, opts.maxRecords) : 256;
+  const scanner = typeof opts.scanner === 'function' ? opts.scanner : scanText;
+  const pseudonymize = typeof opts.pseudonymize === 'function' ? opts.pseudonymize : null;
+  const local = { scanner, maxChars: MAX_SUPPORT_STRING_CHARS };
+
+  const entries = [];
+  const gaps = [];
+  const stats = { in: 0, kept: 0, rejected: 0, truncated: 0 };
+
+  if (!Array.isArray(records)) {
+    gaps.push({ index: 0, code: 'trace_unavailable' });
+    return { entries, gaps, stats };
+  }
+
+  for (const record of records) {
+    stats.in += 1;
+    if (entries.length + gaps.length >= maxRecords) {
+      stats.truncated += 1;
+      continue;
+    }
+    const index = stats.in - 1;
+    if (!isPlainObject(record)) {
+      stats.rejected += 1;
+      gaps.push({ index, code: 'record_not_object' });
+      continue;
+    }
+    const valid = validateSemanticRecord(record);
+    if (!valid.ok) {
+      stats.rejected += 1;
+      gaps.push({ index, code: 'schema_rejected' });
+      continue;
+    }
+    const gate = sanitizeForSupport(record, { scanner });
+    if (!gate.ok) {
+      stats.rejected += 1;
+      gaps.push({ index, code: 'support_gate_rejected' });
+      continue;
+    }
+
+    const out = {};
+    for (const key of Object.keys(gate.record)) {
+      if (!TRACE_ENVELOPE_KEEP.has(key)) continue;
+      const value = gate.record[key];
+      if (key === 'sampling') {
+        const s = isPlainObject(value) ? value : {};
+        out.sampling = {
+          policy_version: typeof s.policy_version === 'string'
+            ? redactString(s.policy_version, local) : null,
+          rate: typeof s.rate === 'number' && Number.isFinite(s.rate) ? s.rate : null,
+        };
+        continue;
+      }
+      if (TRACE_ID_FIELDS.includes(key) && typeof value === 'string') {
+        out[key] = pseudonymize ? pseudonymize(value, key) : redactString(value, local);
+        continue;
+      }
+      if (typeof value === 'string') {
+        out[key] = redactString(value, local);
+        continue;
+      }
+      out[key] = value;
+    }
+    // The gate already allowlist-pruned the payload — copy it verbatim.
+    out.payload = gate.record.payload;
+
+    entries.push(out);
+    stats.kept += 1;
+  }
+  return { entries, gaps, stats };
+}

package/src/core/agentRuntime/vmEngine.js

@@ -1,7 +1,8 @@
 /**
  * agentRuntime/vmEngine.js — decision-first-runtime G4 (DR-06), VM vertical
- * slice, omp-scoped, off-rollout (gated by host-side `decisionRuntime.vm`
- * flag; this module reads no config itself).
+ * slice, omp-scoped, off-rollout (`decisionRuntime.vm` gates the V-05
+ * decision-plane classifyFn default below; deterministic escalation stays
+ * the default lane regardless of the flag).
  *
  * Executes a compiled ValidatedPlan (SPEC §4 frozen shape — literal nodes
  * Map, entryNodes, topological order) purely against G1 durable
@@ -39,7 +40,11 @@ import {
   validateTransition,
   validateSemanticEvent,
   validateRetry,
+  validateClassifyVerdict,
 } from './contract.js';
+import { resolveDecisionRuntimeStage } from '../runtimeConfig.js';
+import { createDecisionClient } from '../../decision/client.js';
+import { createVmClassifyFn } from '../../decision/runtimeDecide.js';
 import {
   registerContinuation,
   consumeContinuation,
@@ -88,18 +93,48 @@ async function writeFileAtomic(target, data) {
   await fs.rename(tmp, target);
 }
 
+
 /**
  * Migration contract (decision plane): `classifyFn` is invoked only when the
  * IR itself cannot route an event (see deliver()). It may only consult the
  * decision plane (unic-decision / createDecisionClient registry keys) for a
  * bounded route/escalate answer — never a general LLM call.
  *
- * @param {{dir:string, now?:()=>Date, classifyFn?:Function, startFn?:Function, hooks?:object}} opts
+ * V-05 default: when no `classifyFn` is injected AND
+ * `decisionRuntime.vm.stage` resolves non-'off', the engine installs the
+ * bounded runtimeDecide adapter (runtime.node_route.v1 /
+ * runtime.node_classify.v1 through `decisionClient` — or the default
+ * createDecisionClient when none is injected). Stage 'off' (absent or
+ * malformed) leaves `classifyFn` unset → zero decision calls, byte-identical
+ * behaviour to the deterministic escalation lane.
+ *
+ * @param {{dir:string, now?:()=>Date, classifyFn?:Function, startFn?:Function,
+ *         hooks?:object, config?:object, decisionClient?:object,
+ *         decider?:object}} opts
  */
-export function createVmEngine({ dir, now, classifyFn, startFn, hooks } = {}) {
+export function createVmEngine({
+  dir,
+  now,
+  classifyFn,
+  startFn,
+  hooks,
+  config,
+  decisionClient,
+  decider,
+} = {}) {
   if (typeof dir !== 'string' || dir === '') {
     throw new VmEngineError('malformed_opts', 'dir required');
   }
+  // The injected classifyFn always wins; the decision-plane adapter is a
+  // stage-gated default for embedders that opt in via runtime config.
+  const classify =
+    classifyFn
+    ?? (resolveDecisionRuntimeStage(config ?? null, 'vm') === 'off'
+      ? undefined
+      : createVmClassifyFn({
+          decider,
+          client: decisionClient ?? createDecisionClient({ config }),
+        }));
   const clock = typeof now === 'function' ? now : () => new Date();
   const fire = typeof startFn === 'function' ? startFn : async () => {};
   const instances = new Map(); // planInstanceId -> instance
@@ -712,20 +747,26 @@ export function createVmEngine({ dir, now, classifyFn, startFn, hooks } = {}) {
 
     // classify only when the IR itself cannot route the event (G4-FR05);
     // classifyFn may consult the decision plane for bounded route/escalate
-    // answers only — never a general LLM call (see createVmEngine opts).
+    // answers only — never a general LLM call (see createVmEngine opts). A
+    // throwing classifyFn or a malformed verdict is an unclassifiable event,
+    // never a hard failure (V-05 never-throws contract).
     let outcome = event.safePayload?.outcome;
     let targetMatched = matched;
     if (!targetMatched) {
-      if (typeof classifyFn !== 'function') {
+      if (typeof classify !== 'function') {
         return escalateUnclassified(inst, event);
       }
-      const verdict = await classifyFn(event, { planInstanceId: pi, nodeId, node });
-      if (verdict?.action === 'escalate' || verdict == null) {
-        return escalateUnclassified(inst, event);
+      let verdict = null;
+      try {
+        verdict = await classify(event, { planInstanceId: pi, nodeId, node });
+      } catch {
+        verdict = null;
       }
-      if (verdict?.action === 'route' && typeof verdict.outcome === 'string') {
+      if (validateClassifyVerdict(verdict).ok && verdict.action === 'route') {
         outcome = verdict.outcome;
         targetMatched = node != null && inst.nodes[nodeId]?.state === 'running';
+      } else {
+        return escalateUnclassified(inst, event);
       }
     }
     if (!targetMatched) return escalateUnclassified(inst, event);

package/src/core/runtimeConfig.js

@@ -204,6 +204,18 @@ export function resolveConfigStage(config = null, path) {
   return VALID_ROUTE_STAGES.has(node) ? node : 'off';
 }
 
+// decisionRuntime family stage resolver (V-03): resolves
+// `decisionRuntime.<key>.stage` for one pinned family flag ('vm',
+// 'supervisor', 'scheduler', 'contract', 'adapters', 'context',
+// 'completion', 'quality', 'promotion', 'resourcePolicy',
+// 'diagnostics'). Same semantics as resolveConfigStage: absent config,
+// absent family, non-string key, or malformed stage all resolve 'off'
+// — a bad config can never promote a decisionRuntime slice.
+export function resolveDecisionRuntimeStage(config = null, key = 'vm') {
+  if (typeof key !== 'string' || key.trim() === '') return 'off';
+  return resolveConfigStage(config, `decisionRuntime.${key}.stage`);
+}
+
 // Pushes a stage-enum error when `node.stage` is present but not reserved.
 // Absent stage is valid (absence = 'off'); a non-object node is reported by
 // the caller's own "must be an object" check.

package/src/decision/client.js

@@ -49,9 +49,9 @@ const DEFAULT_CHECKPOINTS = {
   english: 'unic-decision',
   unknownLanguage: 'unic-decision',
 };
-// Credential-safe alias: every UNIC decision credential binds the bare name
-// first — variants (unic-decision-multilingual, …) may lag. On model_not_found
-// the client falls back here once per batch.
+// Credential-safe alias: every UNIC decision credential binds the bare name.
+// On model_not_found the client falls back here once per batch — the bare
+// name is also the only checkpoint name UKit ever sends.
 const FALLBACK_CHECKPOINT = 'unic-decision';
 
 const DEFAULT_TIMEOUT_MS = 5000;
@@ -360,8 +360,7 @@ export function createDecisionClient({
 
         const status = res?.status ?? (res?.ok === false ? 500 : 200);
         if (res?.ok === false || status < 200 || status >= 300) {
-          // A variant checkpoint without bound credentials (e.g.
-          // unic-decision-multilingual before provider binding) returns a 4xx
+          // A checkpoint without bound credentials returns a 4xx
           // model_not_found body — retry once on the bare `unic-decision`
           // model, the credential-safe alias the owner provisions first.
           if (checkpoint !== FALLBACK_CHECKPOINT) {

package/src/decision/runtimeDecide.js

@@ -83,6 +83,46 @@ export const RUNTIME_DECISIONS = Object.freeze([
       'A runtime event may warrant a retry but no deterministic policy covers it. Decide conservatively.',
     candidates: ['retry', 'no_retry', 'escalate'],
   },
+  // V-05: VM decision nodes — the bounded route/classify questions a
+  // vmEngine classifyFn may ask when the plan IR cannot route an event.
+  // Owner is the deterministic escalation lane: every failure mode resolves
+  // to escalateUnclassified, never a hard failure.
+  {
+    decisionKey: 'runtime.node_route.v1',
+    schemaVersion: 1,
+    family: 'runtime',
+    owner: 'vmEngine',
+    kind: 'choice',
+    description: 'Outcome for a VM node event the plan IR could not route — bounded route/escalate answer only.',
+    candidatePolicy: 'node-outcomes-plus-escalate',
+    hardConstraints: ['data-only-no-tool-dispatch'],
+    probabilityPolicy: 'raw-label',
+    fallbackPolicy: 'frozen-conservative-fallback',
+    telemetryClass: 'decision',
+    rolloutStage: 'off',
+    cacheSensitivity: 'none',
+    instruction:
+      'A VM node event did not match any plan selector. Choose the node outcome, or escalate to the deterministic lane.',
+    candidates: ['completed', 'failed', 'cancelled', 'escalate'],
+  },
+  {
+    decisionKey: 'runtime.node_classify.v1',
+    schemaVersion: 1,
+    family: 'runtime',
+    owner: 'vmEngine',
+    kind: 'choice',
+    description: 'Bounded node-declared classification for an unclassifiable VM event; candidates come from the node question block.',
+    candidatePolicy: 'node-declared-candidates',
+    hardConstraints: ['data-only-no-tool-dispatch'],
+    probabilityPolicy: 'raw-label',
+    fallbackPolicy: 'frozen-conservative-fallback',
+    telemetryClass: 'decision',
+    rolloutStage: 'off',
+    cacheSensitivity: 'none',
+    instruction:
+      'Classify this unclassifiable VM node event into exactly one of the node-declared candidates.',
+    candidates: ['completed', 'failed', 'escalate'],
+  },
 ]);
 
 // Decision→fallback action map (frozen, SPEC §4). Fallbacks are conservative:
@@ -92,6 +132,9 @@ const FALLBACK_ACTIONS = Object.freeze({
   'runtime.stall_action.v1': 'continue_observe',
   'runtime.wake_needed.v1': 'escalate',
   'runtime.safe_retry.v1': 'no_retry',
+  // VM decision nodes fail closed onto the deterministic escalation lane.
+  'runtime.node_route.v1': 'escalate',
+  'runtime.node_classify.v1': 'escalate',
 });
 
 // Batch-level statuses → fallback codes. 'abstained' stays distinct so
@@ -135,22 +178,37 @@ function buildStatePacket(item) {
     decisionKey: item.decisionKey ?? null,
     reason: item.reason ?? null,
     eventType: item.event?.eventType ?? item.eventType ?? null,
+    nodeId: typeof item.nodeId === 'string' ? item.nodeId : null,
+    planInstanceId:
+      typeof item.planInstanceId === 'string' ? item.planInstanceId : null,
   };
 }
 
 function buildQuestion(item, entry) {
+  // A node-declared question block may override the registered instruction/
+  // candidates — it is still a bounded choice against one registered key.
+  const instruction =
+    typeof item.instruction === 'string' && item.instruction.length > 0
+      ? item.instruction
+      : typeof entry.instruction === 'string' && entry.instruction.length > 0
+        ? entry.instruction
+        : `Decide ${entry.decisionKey} for the described runtime event.`;
+  const candidates =
+    Array.isArray(item.candidates) && item.candidates.length > 0
+      ? item.candidates
+      : Array.isArray(entry.candidates)
+        ? entry.candidates
+        : [];
   return {
     decisionKey: entry.decisionKey,
     schemaVersion: entry.schemaVersion ?? 1,
     kind: entry.kind,
-    instruction:
-      typeof entry.instruction === 'string' && entry.instruction.length > 0
-        ? entry.instruction
-        : `Decide ${entry.decisionKey} for the described runtime event.`,
-    candidates: Array.isArray(entry.candidates) ? entry.candidates : [],
+    instruction,
+    candidates,
   };
 }
 
+
 /**
  * @param {{client: {requestBatch: Function}, registry?: object,
  *          confidenceFloor?: number|object, now?: Function}} options
@@ -240,3 +298,123 @@ export function createRuntimeDecider({
 
   return { decide };
 }
+
+// ---------------------------------------------------------------------------
+// V-05 — VM decision nodes (agent-vm-runtime V5): a classifyFn for vmEngine
+// that asks one bounded runtime.node_route.v1 / runtime.node_classify.v1
+// question per unclassifiable event. The model answer is data only — the
+// client's tool_calls envelope is consumed as an answer list, NEVER
+// dispatched. Every failure mode maps to the deterministic escalation lane
+// with a fallbackCode; this adapter never throws.
+
+// Registry keys a VM decision node may ask — anything else resolves to the
+// deterministic escalation lane without touching the gateway.
+export const VM_NODE_DECISION_KEYS = Object.freeze([
+  'runtime.node_route.v1',
+  'runtime.node_classify.v1',
+]);
+const DEFAULT_NODE_DECISION_KEY = VM_NODE_DECISION_KEYS[0];
+
+// Node question-block bounds — keeps a bounded choice small enough to stay
+// inside the state/question budget.
+const MAX_NODE_CANDIDATES = 8;
+const MAX_NODE_QUESTION_TEXT = 240;
+
+function isShortString(value) {
+  return typeof value === 'string'
+    && value.length > 0
+    && value.length <= MAX_NODE_QUESTION_TEXT;
+}
+
+// A node question block is valid only when every declared field is
+// well-formed; a malformed block is rejected wholesale (never partially
+// honored) so a bad plan cannot smuggle an unbounded question.
+function validNodeQuestion(question) {
+  return isPlainObject(question)
+    && (question.decisionKey === undefined || isShortString(question.decisionKey))
+    && (question.instruction === undefined || isShortString(question.instruction))
+    && (question.candidates === undefined
+      || (Array.isArray(question.candidates)
+        && question.candidates.length > 0
+        && question.candidates.length <= MAX_NODE_CANDIDATES
+        && question.candidates.every(isShortString)));
+}
+
+/**
+ * Build a vmEngine-compatible `classifyFn(event, ctx)` backed by the decision
+ * plane. Returns only `{action:'route', outcome}` / `{action:'escalate',
+ * fallbackCode?}` verdicts — model unavailability, timeouts, malformed
+ * answers, and adapter faults all resolve to the deterministic escalation
+ * lane with a `fallbackCode`, and the function NEVER throws.
+ *
+ * @param {{client?: {requestBatch: Function}, decider?: {decide: Function},
+ *          registry?: object, confidenceFloor?: number|object}} options
+ *   `decider` wins over `client` (a custom decider composes its own client).
+ *   Neither present → every call escalates 'unavailable' with zero I/O.
+ */
+export function createVmClassifyFn({
+  client,
+  decider,
+  registry,
+  confidenceFloor,
+} = {}) {
+  const resolvedDecider =
+    decider
+    ?? (client != null
+      ? createRuntimeDecider({ client, registry, confidenceFloor })
+      : null);
+
+  return async function vmClassify(event, ctx = {}) {
+    try {
+      const node = isPlainObject(ctx?.node) ? ctx.node : null;
+      const question = node?.question;
+      if (question !== undefined && !validNodeQuestion(question)) {
+        return { action: 'escalate', fallbackCode: 'malformed-question' };
+      }
+      const decisionKey = question?.decisionKey ?? DEFAULT_NODE_DECISION_KEY;
+      if (!VM_NODE_DECISION_KEYS.includes(decisionKey)) {
+        return { action: 'escalate', fallbackCode: 'unregistered-key' };
+      }
+      if (!resolvedDecider || typeof resolvedDecider.decide !== 'function') {
+        return { action: 'escalate', fallbackCode: 'unavailable' };
+      }
+
+      const decision = await resolvedDecider.decide({
+        action: 'model_decision',
+        decisionKey,
+        reason: `vm_unrouted:${String(event?.eventType ?? 'unknown')}`,
+        event: isPlainObject(event) ? event : null,
+        nodeId: typeof ctx?.nodeId === 'string' ? ctx.nodeId : null,
+        planInstanceId:
+          typeof ctx?.planInstanceId === 'string' ? ctx.planInstanceId : null,
+        ...(isShortString(question?.instruction)
+          ? { instruction: question.instruction }
+          : {}),
+        ...(Array.isArray(question?.candidates)
+          ? { candidates: question.candidates }
+          : {}),
+      });
+
+      if (!isPlainObject(decision)) {
+        return { action: 'escalate', fallbackCode: 'invalid' };
+      }
+      if (decision.decidedBy === 'fallback') {
+        return { action: 'escalate', fallbackCode: decision.code ?? 'invalid' };
+      }
+      const outcome = decision.action ?? decision.value;
+      if (outcome === 'escalate') {
+        return { action: 'escalate', decisionKey };
+      }
+      if (typeof outcome !== 'string' || outcome.length === 0) {
+        return { action: 'escalate', fallbackCode: 'invalid' };
+      }
+      // The engine's transition table still gates the outcome — an undeclared
+      // value fails closed to recovery_required downstream, never silently.
+      return { action: 'route', outcome, decisionKey };
+    } catch {
+      // Any adapter fault (bad ctx shape, throwing decider impl) resolves to
+      // the same deterministic lane — decision nodes never hard-fail the VM.
+      return { action: 'escalate', fallbackCode: 'adapter-error' };
+    }
+  };
+}

package/template_project/.claude/ukit/index/unic-decision.mjs

@@ -718,8 +718,7 @@ export async function requestBatch(batch, {
 
     const status = res?.status ?? (res?.ok === false ? 500 : 200);
     if (res?.ok === false || status < 200 || status >= 300) {
-      // A variant checkpoint without bound credentials (e.g.
-      // unic-decision-multilingual before provider binding) returns a 4xx
+      // A checkpoint without bound credentials returns a 4xx
       // model_not_found body — retry once on the bare `unic-decision` model.
       if (checkpoint !== 'unic-decision') {
         let notFound = status === 404;