@ngockhoale/ukit 3.0.3 → 3.0.5

package/src/decision/protocol.js

@@ -0,0 +1,308 @@
+/**
+ * protocol.js (TASK-002 / M07)
+ *
+ * Pure, offline-testable encoders/decoders for the UNIC Decision Agent
+ * (docs/pstack/UNIC_DECISION_SPEC.md §8/§9, CONTRACTS.md C13/C14).
+ *
+ * A question is encoded as an OpenAI `tools[]` item — a function *schema*, never
+ * a callable. `parseBatchResponse` reads `choices[0].message.tool_calls` as data
+ * exactly once; it NEVER dispatches a call, never feeds a tool result back, and
+ * never continues an agent tool loop. Invalid/missing/duplicate/out-of-enum/
+ * non-finite answers invalidate only their own question.
+ */
+
+const VALID_KINDS = new Set(['choice', 'noul', 'score']);
+
+/**
+ * Encode one decision question as an OpenAI function-tool schema item.
+ *
+ * kind mapping (UNIC_DECISION_SPEC §8):
+ *   choice → string enum over `candidates`
+ *   noul   → boolean (interpreted as P(true))
+ *   score  → integer with an ordered legend derived from `candidates`
+ *
+ * Exactly one decision-bearing property (`value`) per question.
+ *
+ * @param {{decisionKey: string, kind: 'choice'|'noul'|'score',
+ *          instruction: string, candidates?: string[]}} question
+ * @returns {{type:'function', function: object}}
+ */
+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(',')}}`;
+}
+
+/**
+ * Build the OpenAI-compatible `/v1/chat/completions` request body for a batch.
+ * `temperature`, `stream`, and `tool_choice` are intentionally omitted — the
+ * endpoint ignores them (UNIC_DECISION_SPEC §8).
+ *
+ * @param {{model: string, statePacket: object|string, questions: object[]}} args
+ * @returns {{model: string, messages: object[], tools: object[]}}
+ */
+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),
+  };
+}
+
+/**
+ * Deterministic language classifier (UNIC_DECISION_SPEC §3). The English
+ * checkpoint may only receive state this function proves all-English:
+ * any non-ASCII letter (Vietnamese diacritics, CJK, Cyrillic, …) or any
+ * non-Latin letter forces 'multilingual'. Text with no letters at all is
+ * 'unknown' — never silently promoted to English.
+ *
+ * @param {string} text
+ * @returns {'english'|'multilingual'|'unknown'}
+ */
+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)) {
+    // Probabilities must be finite AND in [0,1] — an out-of-range value marked
+    // calibration 'eligible' is data-quality noise for shadow-agreement analysis.
+    if (!isFiniteNumber(v) || v < 0 || v > 1) 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 };
+}
+
+/**
+ * Parse one chat/completions response into a normalized DecisionBatchResult
+ * (C14). `arguments` is parsed exactly once per call; calls are data only.
+ *
+ * Batch status: 'accepted' (all valid) | 'partial' (mixed) | 'abstained'
+ * (no tool calls) | 'invalid' (malformed envelope or every answer invalid).
+ *
+ * @param {object} response parsed response body
+ * @param {object[]} questions the questions that were sent
+ * @returns {object} DecisionBatchResult
+ */
+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 >= 0 && args.confidence <= 1
+          ? args.confidence
+          : null,
+        actProbability: isFiniteNumber(args.actProbability) && args.actProbability >= 0 && args.actProbability <= 1
+          ? args.actProbability
+          : isFiniteNumber(args?.action?.act_probability) && args.action.act_probability >= 0 && args.action.act_probability <= 1
+            ? 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 };
+}

package/src/decision/registry.js

@@ -0,0 +1,384 @@
+/**
+ * registry.js (TASK-003 / M07)
+ *
+ * Decision catalog (CONTRACTS.md C17, UNIC_DECISION_SPEC §5). Every
+ * consequential nondeterministic AI choice is registered here — or explicitly
+ * declared deterministic elsewhere. The registry is metadata consumed by the
+ * existing owners; it is NOT a second router and resolves nothing by itself.
+ *
+ * Module-level functions operate on the default registry preloaded with
+ * DECISION_REGISTRY (the shipped initial catalog). `createDecisionRegistry`
+ * builds an isolated instance for tests and embedders.
+ */
+
+import { VALID_ROUTE_STAGES } from '../core/runtimeConfig.js';
+
+export const DECISION_FAMILIES = new Set([
+  'preflight',
+  'route',
+  'rigor',
+  'capability',
+  'workflow',
+  'verify',
+  'review',
+  'resume',
+  'learn',
+]);
+
+export const DECISION_KINDS = new Set(['choice', 'noul', 'score']);
+
+// How a decision's answer interacts with the cache epoch (C16):
+//   frozen-in-epoch        — lane/model: frozen once the epoch opens
+//   verified-native-update — effort: may change mid-epoch only via a verified
+//                            native update that preserves prefix identity
+//   none                   — not part of the cache-sensitive preflight bundle
+export const CACHE_SENSITIVITY = new Set([
+  'frozen-in-epoch',
+  'verified-native-update',
+  'none',
+]);
+
+// Stable dotted key ending in an explicit schema version: `family.name.vN`.
+const DECISION_KEY_PATTERN = /^[a-z][a-z0-9-]*(\.[a-z0-9-]+)*\.v[0-9]+$/;
+
+const REQUIRED_STRING_FIELDS = [
+  'decisionKey',
+  'family',
+  'owner',
+  'kind',
+  'candidatePolicy',
+  'probabilityPolicy',
+  'fallbackPolicy',
+  'telemetryClass',
+];
+
+/**
+ * The shipped initial catalog (SPEC §5 FR-005). Preflight questions are owned
+ * by taskRouting; the rest are registered to their existing owners. All ship
+ * at rolloutStage 'off' — deterministic policy stays authoritative until a
+ * family stage is promoted in runtime config.
+ */
+export const DECISION_REGISTRY = Object.freeze([
+  {
+    decisionKey: 'preflight.execution-lane.v1',
+    schemaVersion: 1,
+    family: 'preflight',
+    owner: 'taskRouting',
+    kind: 'choice',
+    description: 'Execution lane for the next task boundary, from host-eligible lanes.',
+    candidatePolicy: 'host-eligible-lanes',
+    hardConstraints: ['lane-eligibility'],
+    probabilityPolicy: 'raw-label',
+    fallbackPolicy: 'deterministic-route',
+    telemetryClass: 'decision',
+    rolloutStage: 'off',
+    cacheSensitivity: 'frozen-in-epoch',
+    leasePolicy: 'preflight-bundle',
+  },
+  {
+    decisionKey: 'preflight.model-role.v1',
+    schemaVersion: 1,
+    family: 'preflight',
+    owner: 'taskRouting',
+    kind: 'choice',
+    description: 'Execution model role from the host-declared capability map.',
+    candidatePolicy: 'host-model-roles',
+    hardConstraints: ['host-capability-map'],
+    probabilityPolicy: 'raw-label',
+    fallbackPolicy: 'decision-table-v2',
+    telemetryClass: 'decision',
+    rolloutStage: 'off',
+    cacheSensitivity: 'frozen-in-epoch',
+    leasePolicy: 'preflight-bundle',
+  },
+  {
+    decisionKey: 'preflight.reasoning-effort.v1',
+    schemaVersion: 1,
+    family: 'preflight',
+    owner: 'taskRouting',
+    kind: 'choice',
+    description: 'Lowest portable reasoning effort sufficient for the next unresolved work.',
+    candidatePolicy: 'host-efforts-intersect-portable',
+    hardConstraints: ['model-effort-compatibility'],
+    probabilityPolicy: 'raw-label',
+    fallbackPolicy: 'decision-table-v2',
+    telemetryClass: 'decision',
+    rolloutStage: 'off',
+    cacheSensitivity: 'verified-native-update',
+    leasePolicy: 'preflight-bundle',
+  },
+  {
+    decisionKey: 'preflight.rigor.v1',
+    schemaVersion: 1,
+    family: 'preflight',
+    owner: 'taskRouting',
+    kind: 'score',
+    description: 'Rigor level r0-r4 inside deterministic floors.',
+    candidatePolicy: 'floor-filtered-rigor',
+    hardConstraints: ['risk-floor'],
+    probabilityPolicy: 'raw-label',
+    fallbackPolicy: 'deterministic-floor',
+    telemetryClass: 'decision',
+    rolloutStage: 'off',
+    cacheSensitivity: 'none',
+    leasePolicy: 'preflight-bundle',
+  },
+  {
+    decisionKey: 'preflight.capabilities.v1',
+    schemaVersion: 1,
+    family: 'preflight',
+    owner: 'taskRouting',
+    kind: 'choice',
+    description: 'Active capability set label from owner-derived bounded sets.',
+    candidatePolicy: 'owner-derived-sets',
+    hardConstraints: ['capability-availability'],
+    probabilityPolicy: 'raw-label',
+    fallbackPolicy: 'deterministic-route',
+    telemetryClass: 'decision',
+    rolloutStage: 'off',
+    cacheSensitivity: 'none',
+    leasePolicy: 'preflight-bundle',
+  },
+  {
+    decisionKey: 'preflight.verification-depth.v1',
+    schemaVersion: 1,
+    family: 'preflight',
+    owner: 'taskRouting',
+    kind: 'choice',
+    description: 'Initial verification posture: sanity | targeted | impact | full.',
+    candidatePolicy: 'floor-filtered-depths',
+    hardConstraints: ['risk-floor'],
+    probabilityPolicy: 'raw-label',
+    fallbackPolicy: 'deterministic-route',
+    telemetryClass: 'decision',
+    rolloutStage: 'off',
+    cacheSensitivity: 'none',
+    leasePolicy: 'preflight-bundle',
+  },
+  {
+    decisionKey: 'preflight.lease.v1',
+    schemaVersion: 1,
+    family: 'preflight',
+    owner: 'taskRouting',
+    kind: 'choice',
+    description: 'Decision lease length from the owner-bounded lease choices.',
+    candidatePolicy: 'config-lease-choices',
+    hardConstraints: ['lease-choices'],
+    probabilityPolicy: 'raw-label',
+    fallbackPolicy: 'minimal-lease',
+    telemetryClass: 'decision',
+    rolloutStage: 'off',
+    cacheSensitivity: 'none',
+    leasePolicy: 'preflight-bundle',
+  },
+  {
+    decisionKey: 'route.intent-kind.v1',
+    schemaVersion: 1,
+    family: 'route',
+    owner: 'taskRouting',
+    kind: 'choice',
+    description: 'Intent kind for the route: informational | mutation | investigation | review | delivery.',
+    candidatePolicy: 'owner-shortlist',
+    hardConstraints: ['lane-eligibility'],
+    probabilityPolicy: 'raw-label',
+    fallbackPolicy: 'deterministic-route',
+    telemetryClass: 'decision',
+    rolloutStage: 'off',
+    cacheSensitivity: 'none',
+    leasePolicy: 'none',
+  },
+  {
+    decisionKey: 'route.rigor.v1',
+    schemaVersion: 1,
+    family: 'rigor',
+    owner: 'taskRouting',
+    kind: 'score',
+    description: 'R0-R4 rigor recommendation inside deterministic floors.',
+    candidatePolicy: 'floor-filtered-rigor',
+    hardConstraints: ['risk-floor', 'monotonic-escalation'],
+    probabilityPolicy: 'raw-label',
+    fallbackPolicy: 'deterministic-floor',
+    telemetryClass: 'decision',
+    rolloutStage: 'off',
+    cacheSensitivity: 'none',
+    leasePolicy: 'none',
+  },
+  {
+    decisionKey: 'capability.impact.v1',
+    schemaVersion: 1,
+    family: 'capability',
+    owner: 'taskRouting',
+    kind: 'noul',
+    description: 'P(the impact/blast-radius capability should activate for this task).',
+    candidatePolicy: 'owner-shortlist',
+    hardConstraints: ['capability-availability', 'active-set-cap'],
+    probabilityPolicy: 'noul-threshold',
+    fallbackPolicy: 'deterministic-route',
+    telemetryClass: 'decision',
+    rolloutStage: 'off',
+    cacheSensitivity: 'none',
+    leasePolicy: 'none',
+  },
+  {
+    decisionKey: 'verify.depth.v1',
+    schemaVersion: 1,
+    family: 'verify',
+    owner: 'verificationPlan',
+    kind: 'choice',
+    description: 'Verification depth among allowed levels.',
+    candidatePolicy: 'floor-filtered-depths',
+    hardConstraints: ['required-evidence'],
+    probabilityPolicy: 'raw-label',
+    fallbackPolicy: 'deterministic-verification-plan',
+    telemetryClass: 'decision',
+    rolloutStage: 'off',
+    cacheSensitivity: 'none',
+    leasePolicy: 'none',
+  },
+  {
+    decisionKey: 'resume.next-action.v1',
+    schemaVersion: 1,
+    family: 'resume',
+    owner: 'resumableRun',
+    kind: 'choice',
+    description: 'Next valid resumable action at a continuation boundary.',
+    candidatePolicy: 'owner-shortlist',
+    hardConstraints: ['task-boundary', 'source-freshness'],
+    probabilityPolicy: 'raw-label',
+    fallbackPolicy: 'deterministic-continuation',
+    telemetryClass: 'decision',
+    rolloutStage: 'off',
+    cacheSensitivity: 'none',
+    leasePolicy: 'none',
+  },
+  {
+    decisionKey: 'learn.candidate-class.v1',
+    schemaVersion: 1,
+    family: 'learn',
+    owner: 'learningCandidates',
+    kind: 'choice',
+    description: 'Learning candidate classification for a captured signal.',
+    candidatePolicy: 'owner-shortlist',
+    hardConstraints: ['promotion-approval'],
+    probabilityPolicy: 'raw-label',
+    fallbackPolicy: 'deterministic-classifier',
+    telemetryClass: 'decision',
+    rolloutStage: 'off',
+    cacheSensitivity: 'none',
+    leasePolicy: 'none',
+  },
+]);
+
+// Deep-freeze the shipped catalog — entries are shared metadata consumed by
+// every registry instance, not scratch space a caller may mutate.
+for (const entry of DECISION_REGISTRY) {
+  if (Array.isArray(entry.hardConstraints)) Object.freeze(entry.hardConstraints);
+  Object.freeze(entry);
+}
+
+function isPlainObject(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function validateEntry(entry, index, seen) {
+  const label = isPlainObject(entry) && typeof entry.decisionKey === 'string'
+    ? entry.decisionKey
+    : `entry[${index}]`;
+  const errors = [];
+
+  if (!isPlainObject(entry)) {
+    return [`${label}: entry must be a plain object.`];
+  }
+  for (const field of REQUIRED_STRING_FIELDS) {
+    if (typeof entry[field] !== 'string' || entry[field].length === 0) {
+      errors.push(`${label}: ${field} must be a non-empty string.`);
+    }
+  }
+  if (typeof entry.decisionKey === 'string' && entry.decisionKey.length > 0) {
+    if (!DECISION_KEY_PATTERN.test(entry.decisionKey)) {
+      errors.push(`${label}: decisionKey must be a stable dotted key ending in .vN.`);
+    }
+    if (seen.has(entry.decisionKey)) {
+      errors.push(`${label}: duplicate decisionKey.`);
+    }
+    seen.add(entry.decisionKey);
+  }
+  if (!Number.isInteger(entry.schemaVersion) || entry.schemaVersion < 1) {
+    errors.push(`${label}: schemaVersion must be a positive integer.`);
+  }
+  if (typeof entry.family === 'string' && !DECISION_FAMILIES.has(entry.family)) {
+    errors.push(`${label}: family must be one of: ${[...DECISION_FAMILIES].join(', ')}.`);
+  }
+  if (typeof entry.kind === 'string' && !DECISION_KINDS.has(entry.kind)) {
+    errors.push(`${label}: kind must be one of: ${[...DECISION_KINDS].join(', ')}.`);
+  }
+  if (entry.rolloutStage !== undefined && !VALID_ROUTE_STAGES.has(entry.rolloutStage)) {
+    errors.push(`${label}: rolloutStage must be one of: ${[...VALID_ROUTE_STAGES].join(', ')}.`);
+  }
+  if (entry.hardConstraints !== undefined && !Array.isArray(entry.hardConstraints)) {
+    errors.push(`${label}: hardConstraints must be an array.`);
+  }
+  if (entry.cacheSensitivity !== undefined && !CACHE_SENSITIVITY.has(entry.cacheSensitivity)) {
+    errors.push(`${label}: cacheSensitivity must be one of: ${[...CACHE_SENSITIVITY].join(', ')}.`);
+  }
+  return errors;
+}
+
+/**
+ * Create an isolated decision registry.
+ * @param {object[]} [entries] initial entries (defaults to DECISION_REGISTRY)
+ */
+export function createDecisionRegistry(entries = DECISION_REGISTRY) {
+  const list = [];
+  const byKey = new Map(); // first registration wins for lookups
+
+  function registerDecision(entry) {
+    if (!isPlainObject(entry)) {
+      throw new TypeError('registerDecision requires a plain object entry.');
+    }
+    list.push(entry);
+    if (typeof entry.decisionKey === 'string' && !byKey.has(entry.decisionKey)) {
+      byKey.set(entry.decisionKey, entry);
+    }
+    return entry;
+  }
+
+  function getDecision(decisionKey) {
+    return byKey.get(decisionKey) ?? null;
+  }
+
+  function listDecisions({ family = null, stage = null } = {}) {
+    return list.filter(
+      (entry) =>
+        (family === null || entry.family === family) &&
+        (stage === null || entry.rolloutStage === stage),
+    );
+  }
+
+  function validateRegistry() {
+    const seen = new Set();
+    const errors = list.flatMap((entry, index) => validateEntry(entry, index, seen));
+    return { valid: errors.length === 0, errors };
+  }
+
+  for (const entry of entries) registerDecision(entry);
+  return { entries: list, registerDecision, getDecision, listDecisions, validateRegistry };
+}
+
+const defaultRegistry = createDecisionRegistry();
+
+export function registerDecision(entry) {
+  return defaultRegistry.registerDecision(entry);
+}
+
+export function getDecision(decisionKey) {
+  return defaultRegistry.getDecision(decisionKey);
+}
+
+export function listDecisions(filter = {}) {
+  return defaultRegistry.listDecisions(filter);
+}
+
+export function validateRegistry() {
+  return defaultRegistry.validateRegistry();
+}