@ngockhoale/ukit 3.0.3 → 3.0.4

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

@@ -0,0 +1,786 @@
+#!/usr/bin/env node
+/**
+ * unic-decision.mjs (TASK-005 / M07, SPEC §5 FR-011)
+ *
+ * Standalone installed-side adapter for the UNIC Decision Agent
+ * (docs/pstack/UNIC_DECISION_SPEC.md §8/§9, CONTRACTS.md C13/C14).
+ *
+ * Modes:
+ *   node unic-decision.mjs --health-probe        one no-tools request; the ONLY
+ *                                                request allowed to carry no
+ *                                                tools (§9). Plain
+ *                                                message.content is accepted
+ *                                                here and nowhere else.
+ *   node unic-decision.mjs --fixture <path>      offline replay: reads
+ *                                                {questions, response} JSON and
+ *                                                prints the normalized
+ *                                                DecisionBatchResult. Zero
+ *                                                transport, zero dispatch.
+ *   node unic-decision.mjs [--root <dir>]        reads a batch JSON on stdin
+ *                                                ({statePacket, questions,
+ *                                                deadlineMs?}), posts it to
+ *                                                <baseUrl>/v1/chat/completions,
+ *                                                prints the typed result.
+ *
+ * Protocol encode/parse is a LITERAL MIRROR of src/decision/protocol.js — this
+ * file cannot import from src/, so the copy is parity-locked by
+ * tests/index/unicDecision.test.js. Endpoint/credential resolution mirrors
+ * src/core/gatewayProbe.js (env → project .claude/settings.json → home
+ * ~/.claude/settings.json); detection conventions follow unic-gateway.mjs.
+ * No literal credentials ever appear here — env indirection only.
+ *
+ * `tool_calls` in responses are data only: parsed exactly once, NEVER
+ * dispatched, never fed back into a tool loop.
+ *
+ * Exit codes: 0 for every typed outcome (including invalid/partial/unavailable
+ * — the JSON status field carries the truth); 1 only for usage errors or
+ * unreadable/malformed input.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { createHash } from 'node:crypto';
+import { fileURLToPath } from 'node:url';
+import {
+  scanText,
+  isSensitiveDataGateEnabled,
+  loadSensitiveAllowlist,
+} from '../runtime/sensitive-value-scanner.mjs';
+
+// ---------------------------------------------------------------------------
+// Protocol mirror — literal copy of src/decision/protocol.js (TASK-002).
+// Parity is locked by tests/index/unicDecision.test.js; edit both or neither.
+// ---------------------------------------------------------------------------
+
+const VALID_KINDS = new Set(['choice', 'noul', 'score']);
+
+export function encodeQuestion(question) {
+  if (!question || typeof question !== 'object') {
+    throw new TypeError('question must be an object.');
+  }
+  const { decisionKey, kind, instruction, candidates } = question;
+  if (typeof decisionKey !== 'string' || decisionKey.length === 0) {
+    throw new TypeError('question.decisionKey must be a non-empty string.');
+  }
+  if (!VALID_KINDS.has(kind)) {
+    throw new TypeError(`question.kind must be one of ${[...VALID_KINDS].join('|')}.`);
+  }
+
+  let value;
+  if (kind === 'choice') {
+    if (!Array.isArray(candidates) || candidates.length === 0) {
+      throw new TypeError('choice question requires a non-empty candidates array.');
+    }
+    value = { type: 'string', enum: [...candidates] };
+  } else if (kind === 'noul') {
+    value = {
+      type: 'boolean',
+      description: 'true iff the proposition holds; interpreted as P(true).',
+    };
+  } else {
+    // score — ordinal integer; the legend MUST be defined in the description.
+    const legend = Array.isArray(candidates) ? candidates : [];
+    value = { type: 'integer' };
+    if (legend.length > 0) {
+      value.minimum = 1;
+      value.maximum = legend.length;
+      value.description = `Ordered scale: ${legend
+        .map((label, i) => `${i + 1}=${label}`)
+        .join(', ')}.`;
+    }
+  }
+
+  return {
+    type: 'function',
+    function: {
+      name: decisionKey,
+      description: String(instruction ?? ''),
+      parameters: {
+        type: 'object',
+        properties: { value },
+        required: ['value'],
+      },
+    },
+  };
+}
+
+// Deterministic serialization shared with statePacket.js: sorted keys so the
+// same logical packet always produces the same bytes (fingerprint-stable).
+function stableStringify(value) {
+  if (value === null || typeof value !== 'object') return JSON.stringify(value);
+  if (Array.isArray(value)) return `[${value.map(stableStringify).join(',')}]`;
+  const keys = Object.keys(value).sort();
+  return `{${keys
+    .map((k) => `${JSON.stringify(k)}:${stableStringify(value[k])}`)
+    .join(',')}}`;
+}
+
+export function encodeBatch({ model, statePacket, questions }) {
+  if (!Array.isArray(questions) || questions.length === 0) {
+    throw new TypeError('encodeBatch requires a non-empty questions array.');
+  }
+  const content =
+    typeof statePacket === 'string' ? statePacket : stableStringify(statePacket);
+  return {
+    model,
+    messages: [{ role: 'user', content }],
+    tools: questions.map(encodeQuestion),
+  };
+}
+
+export function classifyLanguage(text) {
+  if (typeof text !== 'string' || text.trim().length === 0) return 'unknown';
+  let sawLetter = false;
+  for (const ch of text) {
+    if (/\p{L}/u.test(ch)) {
+      sawLetter = true;
+      if (ch.codePointAt(0) > 0x7f) return 'multilingual';
+    } else if (ch.codePointAt(0) > 0x7f) {
+      // Non-letter non-ASCII (emoji, CJK punctuation, …): cannot prove English.
+      return 'multilingual';
+    }
+  }
+  return sawLetter ? 'english' : 'unknown';
+}
+
+function isFiniteNumber(v) {
+  return typeof v === 'number' && Number.isFinite(v);
+}
+
+function invalidAnswer(question, fallbackCode) {
+  return {
+    decisionKey: question.decisionKey,
+    schemaVersion: question.schemaVersion ?? 1,
+    kind: question.kind,
+    value: null,
+    probabilities: null,
+    confidence: null,
+    actProbability: null,
+    calibration: 'unknown',
+    validationStatus: 'invalid',
+    fallbackCode,
+  };
+}
+
+function normalizeProbabilities(raw) {
+  if (raw == null) return { probabilities: null, calibration: 'unknown' };
+  if (typeof raw !== 'object' || Array.isArray(raw)) {
+    return { error: 'non-finite-probabilities' };
+  }
+  const out = {};
+  for (const [k, v] of Object.entries(raw)) {
+    if (!isFiniteNumber(v)) return { error: 'non-finite-probabilities' };
+    out[k] = v;
+  }
+  return { probabilities: out, calibration: 'eligible' };
+}
+
+function validateValue(question, args) {
+  const value = args?.value;
+  if (question.kind === 'choice') {
+    if (typeof value !== 'string') return 'missing-value';
+    if (!question.candidates.includes(value)) return 'out-of-enum';
+    return { value };
+  }
+  if (question.kind === 'noul') {
+    // P(true): accept a boolean or a finite probability in [0,1].
+    if (typeof value === 'boolean') return { value: value ? 1 : 0 };
+    if (isFiniteNumber(value) && value >= 0 && value <= 1) return { value };
+    return 'missing-value';
+  }
+  // score — finite integer within the declared legend range.
+  if (!isFiniteNumber(value) || !Number.isInteger(value)) return 'missing-value';
+  const legend = Array.isArray(question.candidates) ? question.candidates : [];
+  if (legend.length > 0 && (value < 1 || value > legend.length)) return 'out-of-enum';
+  return { value };
+}
+
+export function parseBatchResponse(response, questions) {
+  const message = response?.choices?.[0]?.message;
+  const finishReason = response?.choices?.[0]?.finish_reason ?? null;
+  const toolCalls = Array.isArray(message?.tool_calls) ? message.tool_calls : null;
+
+  const answers = [];
+  let status;
+
+  if (!toolCalls) {
+    status = 'invalid';
+    for (const q of questions) answers.push(invalidAnswer(q, 'malformed-response'));
+  } else if (toolCalls.length === 0) {
+    status = 'abstained';
+    for (const q of questions) answers.push(invalidAnswer(q, 'missing-answer'));
+  } else {
+    // Name-based reconciliation: order in the response is not trusted.
+    const byName = new Map();
+    const duplicates = new Set();
+    const unknown = [];
+    const questionNames = new Set(questions.map((q) => q.decisionKey));
+    for (const call of toolCalls) {
+      const name = call?.function?.name;
+      if (typeof name !== 'string' || !questionNames.has(name)) {
+        unknown.push(name ?? 'unknown');
+        continue;
+      }
+      if (byName.has(name)) {
+        duplicates.add(name);
+        continue;
+      }
+      byName.set(name, call);
+    }
+
+    for (const q of questions) {
+      if (duplicates.has(q.decisionKey)) {
+        answers.push(invalidAnswer(q, 'duplicate-answer'));
+        continue;
+      }
+      const call = byName.get(q.decisionKey);
+      if (!call) {
+        answers.push(invalidAnswer(q, 'missing-answer'));
+        continue;
+      }
+      let args;
+      try {
+        args = JSON.parse(call.function.arguments);
+      } catch {
+        answers.push(invalidAnswer(q, 'malformed-arguments'));
+        continue;
+      }
+      if (!args || typeof args !== 'object' || Array.isArray(args)) {
+        answers.push(invalidAnswer(q, 'malformed-arguments'));
+        continue;
+      }
+      const checked = validateValue(q, args);
+      if (typeof checked === 'string') {
+        answers.push(invalidAnswer(q, checked));
+        continue;
+      }
+      const probs = normalizeProbabilities(args.probabilities);
+      if (probs.error) {
+        answers.push(invalidAnswer(q, probs.error));
+        continue;
+      }
+      answers.push({
+        decisionKey: q.decisionKey,
+        schemaVersion: q.schemaVersion ?? 1,
+        kind: q.kind,
+        value: checked.value,
+        probabilities: probs.probabilities,
+        confidence: isFiniteNumber(args.confidence) ? args.confidence : null,
+        actProbability: isFiniteNumber(args.actProbability)
+          ? args.actProbability
+          : isFiniteNumber(args?.action?.act_probability)
+            ? args.action.act_probability
+            : null,
+        calibration: probs.calibration,
+        validationStatus: 'valid',
+        fallbackCode: null,
+      });
+    }
+
+    // Unknown call names are data too — surfaced as invalid answers, never run.
+    for (const name of unknown) {
+      answers.push({
+        decisionKey: name,
+        schemaVersion: 1,
+        kind: null,
+        value: null,
+        probabilities: null,
+        confidence: null,
+        actProbability: null,
+        calibration: 'unknown',
+        validationStatus: 'invalid',
+        fallbackCode: 'unknown-answer',
+      });
+    }
+
+    const validCount = answers.filter((a) => a.validationStatus === 'valid').length;
+    status =
+      validCount === answers.length ? 'accepted' : validCount > 0 ? 'partial' : 'invalid';
+  }
+
+  return { status, finishReason, answers };
+}
+
+// ---------------------------------------------------------------------------
+// Gateway resolution — mirror of src/core/gatewayProbe.js probe order
+// (env → project .claude/settings.json → home ~/.claude/settings.json), the
+// same conventions unic-gateway.mjs detects on. Never throws.
+// ---------------------------------------------------------------------------
+
+function safeReadJson(filePath) {
+  try {
+    return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+function pickString(...candidates) {
+  for (const candidate of candidates) {
+    if (typeof candidate === 'string' && candidate.length > 0) return candidate;
+  }
+  return null;
+}
+
+function readSettingsEnvBlock(filePath) {
+  const json = safeReadJson(filePath);
+  if (!json || typeof json !== 'object') return null;
+  const envBlock = json.env;
+  if (!envBlock || typeof envBlock !== 'object' || Array.isArray(envBlock)) return null;
+  return envBlock;
+}
+
+function resolveGatewayBaseUrl({ projectRoot, homeDir, env }) {
+  const envUrl = pickString(env?.ANTHROPIC_BASE_URL);
+  if (envUrl) return { baseUrl: envUrl, source: 'env' };
+  const settingsPaths = [
+    ...(projectRoot ? [path.join(projectRoot, '.claude', 'settings.json')] : []),
+    path.join(homeDir ?? os.homedir(), '.claude', 'settings.json'),
+  ];
+  for (const settingsPath of settingsPaths) {
+    const envBlock = readSettingsEnvBlock(settingsPath);
+    const value = pickString(envBlock?.ANTHROPIC_BASE_URL);
+    if (value) return { baseUrl: value, source: 'claude-settings' };
+  }
+  return { baseUrl: null, source: null };
+}
+
+function pickApiKey(envLike) {
+  if (!envLike || typeof envLike !== 'object') return null;
+  // ANTHROPIC_API_KEY → x-api-key; ANTHROPIC_AUTH_TOKEN → Authorization: Bearer.
+  // The wrong header 401s token-auth gateways (gatewayProbe.js comment).
+  if (typeof envLike.ANTHROPIC_API_KEY === 'string' && envLike.ANTHROPIC_API_KEY.length > 0) {
+    return { value: envLike.ANTHROPIC_API_KEY, scheme: 'api-key' };
+  }
+  if (typeof envLike.ANTHROPIC_AUTH_TOKEN === 'string' && envLike.ANTHROPIC_AUTH_TOKEN.length > 0) {
+    return { value: envLike.ANTHROPIC_AUTH_TOKEN, scheme: 'auth-token' };
+  }
+  return null;
+}
+
+function resolveGatewayApiKey({ projectRoot, homeDir, env }) {
+  const envKey = pickApiKey(env ?? {});
+  if (envKey) return { ...envKey, source: 'env' };
+  const settingsPaths = [
+    ...(projectRoot ? [path.join(projectRoot, '.claude', 'settings.json')] : []),
+    path.join(homeDir ?? os.homedir(), '.claude', 'settings.json'),
+  ];
+  for (const settingsPath of settingsPaths) {
+    const envBlock = readSettingsEnvBlock(settingsPath);
+    if (!envBlock) continue;
+    const key = pickApiKey(envBlock);
+    if (key) return { ...key, source: 'claude-settings' };
+  }
+  return { value: null, scheme: null, source: null };
+}
+
+function buildAuthHeaders(key) {
+  if (!key?.value) return {};
+  if (key.scheme === 'auth-token') {
+    return { Authorization: `Bearer ${key.value}` };
+  }
+  return { 'x-api-key': key.value };
+}
+
+// ---------------------------------------------------------------------------
+// Runtime config — minimal merged view (project over user), mirroring
+// route-task.mjs readMergedConfig semantics for the two blocks this adapter
+// reads: decisionPlane and security.
+// ---------------------------------------------------------------------------
+
+function isPlainObject(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function mergeConfigObjects(base, override) {
+  if (!isPlainObject(base)) return isPlainObject(override) ? { ...override } : {};
+  if (!isPlainObject(override)) return { ...base };
+  const out = { ...base };
+  for (const [key, value] of Object.entries(override)) {
+    if (key === '__proto__' || key === 'constructor' || key === 'prototype') continue;
+    out[key] = isPlainObject(value) && isPlainObject(base[key])
+      ? mergeConfigObjects(base[key], value)
+      : value;
+  }
+  return out;
+}
+
+function readMergedConfig(rootDir, homeDir) {
+  const projectRaw = rootDir
+    ? safeReadJson(path.join(rootDir, '.ukit', 'storage', 'config.json'))
+    : null;
+  const userRaw = safeReadJson(
+    path.join(homeDir ?? os.homedir(), '.ukit', 'storage', 'config.json'),
+  );
+  return mergeConfigObjects(userRaw ?? {}, projectRaw ?? {});
+}
+
+// ---------------------------------------------------------------------------
+// Client core — mirror of src/decision/client.js semantics minus the circuit
+// breaker (a one-shot CLI has no cross-request state to protect).
+// ---------------------------------------------------------------------------
+
+const DEFAULT_CHECKPOINTS = {
+  default: 'unic-decision/laya-multilingual',
+  english: 'unic-decision/laya',
+  unknownLanguage: 'unic-decision/auto',
+};
+
+const DEFAULT_TIMEOUT_MS = 5000;
+const DEFAULT_MAX_RETRIES = 1;
+const DEFAULT_STATE_LIMITS = { multilingual: 1024, english: 512 };
+
+function decisionPlaneConfig(config) {
+  const dp = config?.decisionPlane ?? config ?? {};
+  return dp && typeof dp === 'object' ? dp : {};
+}
+
+export function resolveCheckpoint(languageClass, config) {
+  const checkpoints = {
+    ...DEFAULT_CHECKPOINTS,
+    ...(decisionPlaneConfig(config).checkpoints ?? {}),
+  };
+  if (languageClass === 'english') return checkpoints.english;
+  if (languageClass === 'unknown') return checkpoints.unknownLanguage;
+  return checkpoints.default;
+}
+
+// Latency classes for receipts — bands, never raw volatile numbers.
+function latencyClass(ms) {
+  if (!Number.isFinite(ms) || ms < 0) return 'unknown';
+  if (ms < 250) return 'fast';
+  if (ms < 2000) return 'normal';
+  return 'slow';
+}
+
+function requestFingerprint(body) {
+  return createHash('sha256').update(body).digest('hex').slice(0, 16);
+}
+
+function isTransientStatus(status) {
+  return status === 429 || (status >= 500 && status <= 599);
+}
+
+async function readResponseBody(res) {
+  if (res && typeof res.json === 'function') return res.json();
+  if (res && typeof res.text === 'function') return JSON.parse(await res.text());
+  return res;
+}
+
+// Deterministic token estimator + budget gate — mirror of
+// src/decision/statePacket.js (chars/4 vs bytes/3, overestimate is safe).
+function estimateTokens(text) {
+  const chars = String(text).length;
+  const bytes = Buffer.byteLength(String(text), 'utf8');
+  return Math.max(Math.ceil(chars / 4), Math.ceil(bytes / 3));
+}
+
+function stateBudgetExceeded(serialized, languageClass, limits) {
+  const budget =
+    languageClass === 'english'
+      ? (limits?.english ?? DEFAULT_STATE_LIMITS.english)
+      : (limits?.multilingual ?? DEFAULT_STATE_LIMITS.multilingual);
+  return estimateTokens(serialized) > budget;
+}
+
+// Sensitive-value gate over the serialized packet — same scanner the src side
+// uses, fail-closed: a positive detection blocks the request before transport.
+function sensitiveGate(serialized, config) {
+  const scan = scanText(serialized, {
+    gateEnabled: isSensitiveDataGateEnabled(config),
+    allowlistHashes: loadSensitiveAllowlist(config),
+  });
+  return scan.hasSecret ? { blocked: true, labels: scan.labels } : { blocked: false };
+}
+
+async function postWithDeadline(transport, url, headers, body, deadlineMs) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), deadlineMs);
+  try {
+    return await transport(url, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json', ...headers },
+      body,
+      signal: controller.signal,
+    });
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+function outcome(status, extra = {}) {
+  return { status, finishReason: null, answers: [], ...extra };
+}
+
+/**
+ * Send one C13 batch over the configured gateway. `batch` =
+ * {batchId?, boundary?, statePacket, questions, deadlineMs?}. Returns a typed
+ * DecisionBatchResult; never throws for transport-level failures.
+ */
+export async function requestBatch(batch, {
+  config = null,
+  transport = globalThis.fetch?.bind(globalThis),
+  now = () => Date.now(),
+  projectRoot,
+  homeDir,
+  env = process.env,
+} = {}) {
+  const dp = decisionPlaneConfig(config);
+  if (dp.enabled === false) {
+    return outcome('unavailable', { fallbackCode: 'decision-plane-disabled' });
+  }
+  if (!transport) {
+    return outcome('unsupported', { fallbackCode: 'no-transport' });
+  }
+  const questions = Array.isArray(batch?.questions) ? batch.questions : [];
+  if (questions.length === 0) {
+    return outcome('invalid', { fallbackCode: 'empty-batch' });
+  }
+
+  const serialized =
+    typeof batch?.statePacket === 'string'
+      ? batch.statePacket
+      : stableStringify(batch?.statePacket ?? {});
+  const questionText = questions
+    .map((q) => `${q.decisionKey} ${q.instruction} ${(q.candidates ?? []).join(' ')}`)
+    .join(' ');
+  const languageClass = classifyLanguage(`${serialized} ${questionText}`);
+  const checkpoint = resolveCheckpoint(languageClass, config);
+
+  if (stateBudgetExceeded(serialized, languageClass, dp.maxStateTokens)) {
+    return outcome('invalid', { fallbackCode: 'state-too-large', checkpoint });
+  }
+  if (sensitiveGate(serialized, config).blocked) {
+    return outcome('blocked-sensitive', { checkpoint });
+  }
+
+  const base = resolveGatewayBaseUrl({ projectRoot, homeDir, env });
+  if (!base?.baseUrl) {
+    return outcome('unsupported', {
+      fallbackCode: 'endpoint-unconfigured',
+      checkpoint,
+    });
+  }
+  const key = resolveGatewayApiKey({ projectRoot, homeDir, env });
+  const endpoint = {
+    url: `${String(base.baseUrl).replace(/\/+$/, '')}/v1/chat/completions`,
+    headers: buildAuthHeaders(key),
+  };
+
+  let body;
+  try {
+    body = JSON.stringify(
+      encodeBatch({ model: checkpoint, statePacket: serialized, questions }),
+    );
+  } catch (error) {
+    return outcome('invalid', {
+      fallbackCode: 'malformed-question',
+      checkpoint,
+      detail: error?.message ?? String(error),
+    });
+  }
+  const fingerprint = requestFingerprint(body);
+  const timeoutMs = Number.isFinite(dp.timeoutMs) ? dp.timeoutMs : DEFAULT_TIMEOUT_MS;
+  const deadlineMs = Number.isFinite(batch?.deadlineMs) ? batch.deadlineMs : timeoutMs;
+
+  const maxAttempts = 1 + DEFAULT_MAX_RETRIES;
+  let lastError = null;
+  let lastStatus = null;
+  for (let attempt = 0; attempt < maxAttempts; attempt += 1) {
+    const startedAt = now();
+    let res;
+    try {
+      res = await postWithDeadline(transport, endpoint.url, endpoint.headers, body, deadlineMs);
+    } catch (err) {
+      const isTimeout = err?.name === 'AbortError' || err?.code === 'ABORT_ERR';
+      lastError = isTimeout ? 'timeout' : 'unavailable';
+      lastStatus = null;
+      if (isTimeout || attempt + 1 >= maxAttempts) break;
+      continue;
+    }
+
+    const status = res?.status ?? (res?.ok === false ? 500 : 200);
+    if (res?.ok === false || status < 200 || status >= 300) {
+      if (isTransientStatus(status) && attempt + 1 < maxAttempts) continue;
+      if (status === 401 || status === 403) {
+        lastError = 'unavailable';
+        lastStatus = 'auth-rejected';
+      } else if (status === 400 || status === 404 || status === 422) {
+        lastError = 'unsupported';
+        lastStatus = 'endpoint-rejected';
+      } else {
+        lastError = 'unavailable';
+        lastStatus = 'gateway-error';
+      }
+      break;
+    }
+
+    let parsed;
+    try {
+      parsed = await readResponseBody(res);
+    } catch {
+      lastError = 'invalid';
+      lastStatus = 'malformed-response';
+      break;
+    }
+
+    const result = parseBatchResponse(parsed, questions);
+    return {
+      batchId: batch?.batchId ?? null,
+      checkpoint,
+      finishReason: result.finishReason,
+      status: result.status,
+      answers: result.answers,
+      requestFingerprint: fingerprint,
+      latencyClass: latencyClass(now() - startedAt),
+    };
+  }
+
+  return outcome(lastError ?? 'unavailable', {
+    batchId: batch?.batchId ?? null,
+    checkpoint,
+    fallbackCode:
+      lastStatus ?? (lastError === 'timeout' ? 'deadline-exceeded' : 'transport-error'),
+    requestFingerprint: fingerprint,
+  });
+}
+
+/**
+ * Explicit no-tools health probe — the ONLY request allowed to carry no tools
+ * (UNIC_DECISION_SPEC §9). A plain `message.content` reply is accepted here and
+ * nowhere else; it is never interpreted as a policy decision.
+ */
+export async function runHealthProbe({
+  config = null,
+  transport = globalThis.fetch?.bind(globalThis),
+  projectRoot,
+  homeDir,
+  env = process.env,
+} = {}) {
+  const dp = decisionPlaneConfig(config);
+  if (dp.enabled === false) return { status: 'unavailable' };
+  if (!transport) return { status: 'unsupported' };
+  const base = resolveGatewayBaseUrl({ projectRoot, homeDir, env });
+  if (!base?.baseUrl) return { status: 'unsupported', fallbackCode: 'endpoint-unconfigured' };
+  const key = resolveGatewayApiKey({ projectRoot, homeDir, env });
+  const checkpoint = resolveCheckpoint('multilingual', config);
+  const timeoutMs = Number.isFinite(dp.timeoutMs) ? dp.timeoutMs : DEFAULT_TIMEOUT_MS;
+  const body = JSON.stringify({
+    model: checkpoint,
+    messages: [{ role: 'user', content: 'ping' }],
+    max_tokens: 1,
+  });
+  try {
+    const res = await postWithDeadline(
+      transport,
+      `${String(base.baseUrl).replace(/\/+$/, '')}/v1/chat/completions`,
+      buildAuthHeaders(key),
+      body,
+      timeoutMs,
+    );
+    const status = res?.status ?? (res?.ok === false ? 500 : 200);
+    if (res?.ok === false || status < 200 || status >= 300) {
+      return { status: 'unavailable', httpStatus: status };
+    }
+    return { status: 'ok', checkpoint };
+  } catch (err) {
+    return { status: err?.name === 'AbortError' ? 'timeout' : 'unavailable' };
+  }
+}
+
+/**
+ * Offline fixture replay: {questions, response} → normalized
+ * DecisionBatchResult. Zero transport, zero dispatch — the fixture's
+ * tool_calls are parsed as data exactly once.
+ */
+export function runFixture(fixture) {
+  const questions = Array.isArray(fixture?.questions) ? fixture.questions : [];
+  if (questions.length === 0) {
+    return outcome('invalid', { fallbackCode: 'empty-batch' });
+  }
+  return parseBatchResponse(fixture?.response, questions);
+}
+
+// ---------------------------------------------------------------------------
+// CLI
+// ---------------------------------------------------------------------------
+
+function readFlagValue(argv, flag) {
+  const index = argv.indexOf(flag);
+  if (index === -1) return null;
+  const value = argv[index + 1];
+  return value && !value.startsWith('--') ? value : null;
+}
+
+function readStdin() {
+  return new Promise((resolve, reject) => {
+    let data = '';
+    process.stdin.setEncoding('utf8');
+    process.stdin.on('data', (chunk) => { data += chunk; });
+    process.stdin.on('end', () => resolve(data));
+    process.stdin.on('error', reject);
+  });
+}
+
+function printResult(result) {
+  process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+}
+
+async function main() {
+  const args = process.argv.slice(2);
+  const rootDir = readFlagValue(args, '--root') ?? process.env.UKIT_TEST_ROOT ?? process.cwd();
+  const homeDir = process.env.UKIT_TEST_HOME ?? os.homedir();
+  const config = readMergedConfig(rootDir, homeDir);
+
+  if (args.includes('--health-probe')) {
+    printResult(await runHealthProbe({ config, projectRoot: rootDir, homeDir }));
+    return 0;
+  }
+
+  const fixturePath = readFlagValue(args, '--fixture');
+  if (fixturePath !== null) {
+    let fixture;
+    try {
+      fixture = JSON.parse(fs.readFileSync(fixturePath, 'utf8'));
+    } catch (error) {
+      process.stderr.write(
+        `unic-decision: cannot read fixture ${fixturePath}: ${error?.message ?? error}\n`,
+      );
+      return 1;
+    }
+    printResult(runFixture(fixture));
+    return 0;
+  }
+
+  const raw = await readStdin();
+  let batch;
+  try {
+    batch = JSON.parse(raw);
+  } catch {
+    process.stderr.write(
+      'unic-decision: expected a batch JSON on stdin ({statePacket, questions}) '
+        + 'or --fixture <path> or --health-probe\n',
+    );
+    return 1;
+  }
+  printResult(await requestBatch(batch, { config, projectRoot: rootDir, homeDir }));
+  return 0;
+}
+
+const isMainModule = (() => {
+  try {
+    return path.resolve(fileURLToPath(import.meta.url)) === path.resolve(process.argv[1] ?? '');
+  } catch {
+    return false;
+  }
+})();
+
+if (isMainModule) {
+  main()
+    .then((code) => { process.exitCode = code; })
+    .catch((error) => {
+      process.stderr.write(`unic-decision: ${error?.message ?? error}\n`);
+      process.exitCode = 1;
+    });
+}