@ngockhoale/ukit 3.0.8 → 3.0.10

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

@@ -10,10 +10,21 @@
  *   - `records` — already-collected canonical records, or
  *   - `root`    — canonical segment root; records are pulled through
  *                 readSegments (TASK-006) and its coverage is surfaced.
- * options: { homeDir?, env?, platform?, config?, caps?, now? }
- *   - `config.observability.stage` — 'off' is the kill switch
- *     (skipped/stage_off, nothing written).
+ * options: { homeDir?, env?, platform?, config?, caps?, now?,
+ *            projectKey?, projectRoot? }
+ *   - `config.observability.stage` — 'off' is the kill switch: the call
+ *     returns skipped/stage_off AND best-effort invalidates this
+ *     project's previously-owned material (foreign files survive).
  *   - `caps` — { maxBytes, maxAgeMs, maxDigests, maxRecords }.
+ *   - `projectKey`/`projectRoot`/`snapshot.project_key` — project identity
+ *     for the per-project subdirectory
+ *     `proj-<sha256(key).slice(0,12)>`; precedence
+ *     projectKey > project_key > projectRoot > literal 'unknown'.
+ *
+ *   invalidateSupportView(dir) → { ok, removed } | { ok: false, reason }
+ *     Removes only projector-owned names (our-format manifest list,
+ *     isOwnedName allowlist, digest-* convention); never follows
+ *     symlinks, never touches foreign files.
  *
  * Pipeline: stage gate → Documents resolution → collect → double-gate
  * (validateSemanticRecord + sanitizeForSupport — default-deny, unknown
@@ -192,7 +203,7 @@ function renderSummary({ generatedAt, lagMs, coverage, caps, traces }) {
   return lines.join('\n');
 }
 
-function buildManifest({ generatedAt, pseudonym, coverage, caps, files }) {
+function buildManifest({ generatedAt, pseudonym, coverage, caps, files, projectIdSource }) {
   const fileEntries = {};
   for (const [name, content] of Object.entries(files)) {
     if (name === 'manifest.json') continue;
@@ -207,6 +218,7 @@ function buildManifest({ generatedAt, pseudonym, coverage, caps, files }) {
     project_ref_pseudonym: pseudonym,
     coverage,
     caps,
+    project_id_source: projectIdSource,
     files: fileEntries,
   };
 }
@@ -223,6 +235,98 @@ async function collectRecords(snapshot, coverage) {
   return [];
 }
 
+/**
+ * Project-key precedence (TASK-001 / G4-FR05):
+ *   options.projectKey > snapshot.project_key > options.projectRoot > 'unknown'
+ * The literal 'unknown' key is never a repo basename — identity is the key,
+ * never the pathname.
+ */
+function projectKeyFor(snapshot, options) {
+  if (typeof options.projectKey === 'string' && options.projectKey.length > 0) {
+    return { key: options.projectKey, source: 'project_key' };
+  }
+  if (typeof snapshot.project_key === 'string' && snapshot.project_key.length > 0) {
+    return { key: snapshot.project_key, source: 'project_key' };
+  }
+  if (typeof options.projectRoot === 'string' && options.projectRoot.length > 0) {
+    return { key: options.projectRoot, source: 'project_root' };
+  }
+  return { key: 'unknown', source: 'unknown' };
+}
+
+function projectDirName(key) {
+  return `proj-${sha256Hex(key).slice(0, 12)}`;
+}
+
+/**
+ * invalidateSupportView(dir) → { ok: true, removed: string[] }
+ *                             | { ok: false, reason: string }
+ *
+ * Removes ONLY material this projector owns: names in a manifest that
+ * carries our `format`, plus the retention `isOwnedName` allowlist and the
+ * `digest-*` convention. Never follows symlinks, never touches foreign
+ * files, never removes the directory itself. A missing dir is a clean
+ * no-op; a symlinked or non-directory path is a typed refusal.
+ */
+export async function invalidateSupportView(dir) {
+  if (typeof dir !== 'string' || dir.length === 0) {
+    return { ok: false, reason: 'invalid_dir' };
+  }
+  let st;
+  try {
+    st = await fs.promises.lstat(dir);
+  } catch (err) {
+    if (err && err.code === 'ENOENT') return { ok: true, removed: [] };
+    return { ok: false, reason: ioReason(err) };
+  }
+  if (st.isSymbolicLink() || !st.isDirectory()) {
+    return { ok: false, reason: 'unsupported_file_type' };
+  }
+
+  // Manifest-confirmed ownership set (our format only).
+  let manifestOwned = null;
+  try {
+    const prev = JSON.parse(await fs.promises.readFile(path.join(dir, 'manifest.json'), 'utf8'));
+    if (isPlainObject(prev) && prev.format === SUPPORT_FORMAT && isPlainObject(prev.files)) {
+      manifestOwned = new Set(Object.keys(prev.files));
+      manifestOwned.add('manifest.json');
+    }
+  } catch {
+    manifestOwned = null;
+  }
+
+  let entries;
+  try {
+    entries = await fs.promises.readdir(dir);
+  } catch (err) {
+    return { ok: false, reason: ioReason(err) };
+  }
+
+  const removed = [];
+  for (const name of entries) {
+    const owned =
+      (manifestOwned !== null && manifestOwned.has(name)) ||
+      isOwnedName(name) ||
+      name.startsWith('digest-');
+    if (!owned) continue;
+    let target;
+    try {
+      target = await fs.promises.lstat(path.join(dir, name));
+    } catch {
+      continue;
+    }
+    // regular files only — a symlink or directory at an owned name is not
+    // ours to unlink (never traverse, never rm -r).
+    if (!target.isFile()) continue;
+    try {
+      await fs.promises.rm(path.join(dir, name), { force: true });
+      removed.push(name);
+    } catch {
+      // already gone — best effort
+    }
+  }
+  return { ok: true, removed };
+}
 /**
  * @param {object} snapshot
  * @param {object} [options]
@@ -230,22 +334,54 @@ async function collectRecords(snapshot, coverage) {
  */
 export async function projectSupport(snapshot = {}, options = {}) {
   const none = { status: 'skipped', bytes: 0 };
-  if (resolveStage(options.config) === 'off') {
-    return { ...none, reason: 'stage_off' };
-  }
+  const snap = isPlainObject(snapshot) ? snapshot : {};
+  const { key: projectKey, source: projectIdSource } = projectKeyFor(snap, options);
+  const stageOff = resolveStage(options.config) === 'off';
 
   const resolved = await resolveSupportDir({
     homeDir: options.homeDir,
     env: options.env,
     platform: options.platform,
   });
+
+  if (stageOff) {
+    // Kill switch: previously-owned support material for this project must
+    // not survive the switch. Best-effort — never blocks, never touches
+    // foreign files, skips silently when Documents cannot resolve.
+    if (resolved.ok) {
+      try {
+        await invalidateSupportView(path.join(resolved.dir, projectDirName(projectKey)));
+      } catch {
+        // invalidation is best-effort; the skip result is unchanged
+      }
+    }
+    return { ...none, reason: 'stage_off' };
+  }
+
   if (!resolved.ok) {
     return { status: 'degraded', reason: resolved.reason, bytes: 0 };
   }
-  const dir = resolved.dir;
 
   // The support path itself must be a real directory — never a symlink,
   // never a foreign file. Missing is fine; we create it.
+  try {
+    const st = await fs.promises.lstat(resolved.dir);
+    if (st.isSymbolicLink()) {
+      return { ...none, reason: 'support_path_symlink' };
+    }
+    if (!st.isDirectory()) {
+      return { ...none, reason: 'support_path_not_directory' };
+    }
+  } catch (err) {
+    if (!err || err.code !== 'ENOENT') {
+      return { status: 'degraded', reason: ioReason(err), bytes: 0 };
+    }
+  }
+
+  // Per-project isolation: this project's material lives in its own
+  // proj-<sha256(key).slice(0,12)> subdirectory so alternating projections
+  // from sibling projects never share or clobber a manifest.
+  const dir = path.join(resolved.dir, projectDirName(projectKey));
   try {
     const st = await fs.promises.lstat(dir);
     if (st.isSymbolicLink()) {
@@ -277,7 +413,7 @@ export async function projectSupport(snapshot = {}, options = {}) {
   };
 
   // --- collect + double-gate ---
-  const raw = await collectRecords(isPlainObject(snapshot) ? snapshot : {}, coverage);
+  const raw = await collectRecords(snap, coverage);
   coverage.records_in = raw.length;
 
   const kept = [];
@@ -314,8 +450,8 @@ export async function projectSupport(snapshot = {}, options = {}) {
   coverage.records_projected = projected.length;
 
   const projectRef =
-    typeof snapshot.project_ref === 'string' && snapshot.project_ref.length > 0
-      ? snapshot.project_ref
+    typeof snap.project_ref === 'string' && snap.project_ref.length > 0
+      ? snap.project_ref
       : (kept.find((r) => typeof r.project_ref === 'string') || {}).project_ref;
   const projectPseudonym = projectRef
     ? `proj-${sha256Hex(`${salt}:project:${projectRef}`).slice(0, 16)}`
@@ -390,7 +526,7 @@ export async function projectSupport(snapshot = {}, options = {}) {
   coverage.truncated_records += recordLines.length - keptLines;
   files['records.jsonl'] = keptLines > 0 ? `${recordLines.slice(0, keptLines).join('\n')}\n` : '';
 
-  const manifest = buildManifest({ generatedAt, pseudonym: projectPseudonym, coverage, caps, files });
+  const manifest = buildManifest({ generatedAt, pseudonym: projectPseudonym, coverage, caps, files, projectIdSource });
   files['manifest.json'] = `${JSON.stringify(manifest, null, 2)}\n`;
 
   // --- write phase: per-file atomic temp-rename, manifest last ---

package/src/core/output/index.js

@@ -310,6 +310,9 @@ function buildRawOutputText({ command = '', stdout = '', stderr = '', exitCode =
 }
 
 function buildRecoveryHintSummary(summary, rawPath, { tokensBefore = 0 } = {}) {
+  // TASK-003 fix round 1: a failed tee persist returns rawPath='' — never emit a
+  // dangling `- Full output: ` hint that points at nothing.
+  if (!rawPath) return null;
   const recoveryLine = `- Full output: ${rawPath}`;
   const summaryLines = String(summary ?? '')
     .split(/\r?\n/)
@@ -457,8 +460,15 @@ async function persistRawOutput(projectRoot, {
     exitCode,
   });
 
-  await fs.mkdir(teeCacheDir, { recursive: true });
-  await fs.writeFile(absolutePath, rawOutputText, 'utf8');
+  try {
+    await fs.mkdir(teeCacheDir, { recursive: true });
+    await fs.writeFile(absolutePath, rawOutputText, 'utf8');
+  } catch {
+    // TASK-003 / FR-006: an unwritable tee dir (EACCES, ENOSPC, EEXIST on a
+    // non-dir, …) must degrade to "no raw file" — never reject the caller's
+    // compression result.
+    return { rawSaved: false, rawPath: '', rawBytes: 0 };
+  }
   // Bounded, sampled tee/ prune (BUG-C21-07): advisory only.
   await maybeSweepTeeCache(teeCacheDir).catch(() => {});
 

package/src/core/runtimeConfig.js

@@ -400,6 +400,16 @@ export function buildDefaultRuntimeConfig(overrides = {}) {
       episodeTtlDays: 90,
       promotion: { episodeToRuleRequiresApproval: true },
       recall: { maxRecords: 8 },
+      // M06 rollout flags (SPEC §5 FR-001): per-plane stage on the shared
+      // off→shadow→canary→default ladder. eligibility/writer/index ship
+      // 'default' (the w1-2 path is the shipped behavior); decision ships
+      // 'off' — plumbing only, no consumer yet. killSwitch is absolute.
+      eligibility: { stage: 'default' },
+      writer: { stage: 'default' },
+      index: { stage: 'default' },
+      decision: { stage: 'off' },
+      canaryProjects: [],
+      killSwitch: false,
     },
     memory: {
       enabled: true,
@@ -437,6 +447,35 @@ export function buildDefaultRuntimeConfig(overrides = {}) {
     continuity: {
       resumableRun: { stage: 'off' },
     },
+    // C63 DR-02 + C64 DR-03/04 + C66 DR-06 + C67 DR-07/08 + C69 DR-10
+    // decision-first-runtime (SPEC §2 G1-FR07, §2 G2-FR07/08, §2 G4-FR07,
+    // §2 G5-FR07, §2 G7-FR04/07). Pinned keys — `decisionRuntime.contract`
+    // gates the G1 contract/eventStore prototype; `decisionRuntime.supervisor`
+    // gates the G2 owned-process supervisor; `decisionRuntime.scheduler`
+    // gates the G3 scheduler; `decisionRuntime.vm` gates the G4 plan-VM
+    // engine; `decisionRuntime.adapters`, `decisionRuntime.context`,
+    // `decisionRuntime.completion`, and `decisionRuntime.quality` gate the
+    // G5 adapters/context/completion/quality slice; `decisionRuntime.promotion`
+    // gates the G6 caller-wait promotion profile and
+    // `decisionRuntime.resourcePolicy` gates the G6 pressure/coalescing
+    // policy; `decisionRuntime.diagnostics` gates the G7 explainable-trace /
+    // replay / support-record readers. Absence or malformed stage resolves
+    // 'off' → zero files under .ukit/storage/agent-runtime/, zero behavior
+    // change.
+    decisionRuntime: {
+      contract: { stage: 'off' },
+      supervisor: { stage: 'off' },
+      scheduler: { stage: 'off' },
+      vm: { stage: 'off' },
+      adapters: { stage: 'off' },
+      context: { stage: 'off' },
+      completion: { stage: 'off' },
+      quality: { stage: 'off' },
+      promotion: { stage: 'off' },
+      resourcePolicy: { stage: 'off' },
+      diagnostics: { stage: 'off' },
+    },
+
     // C52 M06 experiments (SPEC §5 FR-021–FR-023). Disabled by default —
     // zero calls and zero prompt content when off; no auto-promotion.
     experiments: {
@@ -731,6 +770,29 @@ export function validateRuntimeConfig(config) {
     }
   }
 
+  // C63 DR-02 + C64 DR-03/04 + C67 DR-07/08 + C68 DR-09 + C69 DR-10
+  // decisionRuntime — optional-present; carries one stage key per prototype
+  // (pinned: decisionRuntime.contract, decisionRuntime.supervisor,
+  // decisionRuntime.scheduler, decisionRuntime.vm, decisionRuntime.adapters,
+  // decisionRuntime.context, decisionRuntime.completion,
+  // decisionRuntime.quality, decisionRuntime.promotion,
+  // decisionRuntime.resourcePolicy, decisionRuntime.diagnostics). Absent →
+  // valid; malformed stage → error + resolver falls back to 'off'.
+  if (config.decisionRuntime !== undefined) {
+    if (!isPlainObject(config.decisionRuntime)) {
+      errors.push('decisionRuntime must be an object.');
+    } else {
+      for (const key of ['contract', 'supervisor', 'scheduler', 'vm', 'adapters', 'context', 'completion', 'quality', 'promotion', 'resourcePolicy', 'diagnostics']) {
+        const stageKey = config.decisionRuntime[key];
+        if (stageKey === undefined) continue;
+        if (!isPlainObject(stageKey)) {
+          errors.push(`decisionRuntime.${key} must be an object.`);
+        } else {
+          pushStageError(errors, stageKey, `decisionRuntime.${key}`);
+        }
+      }
+    }
+  }
   // C52 M06 experiments — optional-present; both experiments are
   // disabled-by-default booleans plus bounded breakers.
   if (config.experiments !== undefined) {
@@ -922,6 +984,27 @@ export function validateRuntimeConfig(config) {
     } else {
       pushPositiveNumberError(errors, memoryV2.recall.maxRecords, 'memoryV2.recall.maxRecords');
     }
+    // M06 rollout flags (SPEC §5 FR-001): stage enum per plane, boolean
+    // killSwitch, string-array canaryProjects. All optional — absent means
+    // 'off'/false/[] at read time; malformed stage → validation error AND
+    // resolves 'off' (flags only reduce capability).
+    for (const plane of ['eligibility', 'writer', 'index', 'decision']) {
+      if (memoryV2[plane] === undefined) continue;
+      if (!isPlainObject(memoryV2[plane])) {
+        errors.push(`memoryV2.${plane} must be an object.`);
+      } else {
+        pushStageError(errors, memoryV2[plane], `memoryV2.${plane}`);
+      }
+    }
+    if (memoryV2.killSwitch !== undefined) {
+      pushBooleanError(errors, memoryV2.killSwitch, 'memoryV2.killSwitch');
+    }
+    if (memoryV2.canaryProjects !== undefined) {
+      if (!Array.isArray(memoryV2.canaryProjects)
+        || memoryV2.canaryProjects.some((entry) => typeof entry !== 'string')) {
+        errors.push('memoryV2.canaryProjects must be an array of strings.');
+      }
+    }
   }
 
   if (!isPlainObject(config.memory)) {

package/src/core/runtimePaths.js

@@ -22,6 +22,9 @@ export function buildRuntimePaths(projectRoot) {
     outputHistoryPath: path.join(cacheRoot, 'output-history.json'),
     userMemoryPath: path.join(memoryRoot, 'user.json'),
     projectsDir: path.join(memoryRoot, 'projects'),
+    // Reserved identity hint slot (SPEC §14): a hint only — the user-level
+    // registry ~/.ukit/storage/projects/registry.json is the authority.
+    projectIdentityPath: path.join(memoryRoot, 'project.json'),
     sessionsDir: path.join(memoryRoot, 'sessions'),
   };
 }

package/src/core/sensitiveValueScanner.js

@@ -36,7 +36,11 @@ const TOKEN_PATTERNS = [
   { label: 'Google API key', re: /(?<![A-Za-z0-9+/_-])AIza[0-9A-Za-z_-]{20,}(?![A-Za-z0-9+/_-])/g },
   { label: 'Stripe live key', re: /\b[srp]k_live_[A-Za-z0-9]{20,}/g },
   { label: 'JWT', re: /\beyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\b/g },
+  // Whole-block pattern must precede the BEGIN-marker pattern so redactText
+  // consumes the full PEM span before the marker can match inside it.
+  { label: 'private-key-block', re: /-----BEGIN (?:RSA |EC |DSA |OPENSSH |PGP |ENCRYPTED )?PRIVATE KEY-----[\s\S]*?-----END (?:RSA |EC |DSA |OPENSSH |PGP |ENCRYPTED )?PRIVATE KEY-----/g },
   { label: 'private key block', re: /-----BEGIN (?:RSA |EC |DSA |OPENSSH |PGP |ENCRYPTED )?PRIVATE KEY-----/g },
+  { label: 'generic-credential', re: /(?:password|passwd|secret|api[_-]?key|access[_-]?token|auth[_-]?token)\s*[:=]\s*['"]?[A-Za-z0-9/+=_.\-]{16,}/gi },
 ];
 
 const SHA256_HEX_RE = /^[0-9a-f]{64}$/i;
@@ -86,6 +90,42 @@ export function scanText(text, options = {}) {
   return { hasSecret: true, allowed: false, labels: [...labels] };
 }
 
+/**
+ * Redact high-confidence secret values from text, replacing each matched
+ * span with `[REDACTED:<label>]` — the label names the pattern class, never
+ * the value. Allowlisted exact values are left intact; gate-off is a clean
+ * passthrough. Never throws; non-string input returns `{text, redacted:false,
+ * labels:[]}` with `text` echoed back.
+ *
+ * @param {string} text
+ * @param {{ allowlistHashes?: string[], gateEnabled?: boolean }} [options]
+ * @returns {{ text: string, redacted: boolean, labels: string[] }}
+ */
+export function redactText(text, options = {}) {
+  const { allowlistHashes = [], gateEnabled = true } = options || {};
+  const clean = { text, redacted: false, labels: [] };
+  if (gateEnabled === false) return clean;
+  if (typeof text !== 'string' || text.length === 0) return clean;
+
+  const allowed = new Set(
+    Array.isArray(allowlistHashes)
+      ? allowlistHashes.filter((h) => typeof h === 'string').map((h) => h.toLowerCase())
+      : [],
+  );
+
+  const labels = new Set();
+  let out = text;
+  for (const { label, re } of TOKEN_PATTERNS) {
+    const marker = `[REDACTED:${label}]`;
+    out = out.replace(re, (match) => {
+      if (allowed.has(sha256(match))) return match;
+      labels.add(label);
+      return marker;
+    });
+  }
+  return { text: out, redacted: labels.size > 0, labels: [...labels] };
+}
+
 /**
  * Gate toggle: enabled unless security.sensitiveDataGate === false
  * (mirrors the hook's explicit-false check on .ukit/storage/config.json).

package/src/core/token/index.js

@@ -270,9 +270,17 @@ export async function readPromptCacheEntry(
     ...cache.entries.slice(0, entryIndex),
     ...cache.entries.slice(entryIndex + 1),
   ].slice(0, maxEntries);
-  const nextDocument = normalizePromptCacheDocument({ entries }, { maxEntries });
-  await writePromptCacheDocument(projectRoot, nextDocument);
-  return nextDocument.entries[0] ?? touchedEntry;
+  try {
+    const nextDocument = normalizePromptCacheDocument({ entries }, { maxEntries });
+    await writePromptCacheDocument(projectRoot, nextDocument);
+    return nextDocument.entries[0] ?? touchedEntry;
+  } catch {
+    // TASK-006 (SPEC §5 FR-009): the touch-write is a side effect of a READ —
+    // a full/unwritable cache (EACCES, ENOSPC, ...) must never reject the
+    // read. Degrade to the in-memory touched entry; the persisted hitCount
+    // simply lags until a later write succeeds.
+    return touchedEntry;
+  }
 }
 
 export async function writePromptCacheEntry(
@@ -297,6 +305,35 @@ export async function writePromptCacheEntry(
   return nextDocument;
 }
 
+/**
+ * deletePromptCacheEntries(projectRoot, {selectedIds}) → Promise<{removed:int}>
+ * Purge sweep (SPEC §5 FR-018): drops every cache entry whose
+ * `metadata.selectedIds` intersects `selectedIds` — cached content embeds
+ * record text, so purged records must not linger in the cache. Persists via
+ * the same normalize+write path as the other cache writers. Empty or absent
+ * cache → {removed:0}; never throws.
+ */
+export async function deletePromptCacheEntries(projectRoot, { selectedIds } = {}) {
+  try {
+    const ids = new Set(Array.isArray(selectedIds) ? selectedIds : []);
+    if (ids.size === 0) return { removed: 0 };
+    const cache = await readPromptCacheDocument(projectRoot);
+    if (cache.entries.length === 0) return { removed: 0 };
+    const kept = cache.entries.filter((entry) => {
+      const entryIds = Array.isArray(entry?.metadata?.selectedIds)
+        ? entry.metadata.selectedIds
+        : [];
+      return !entryIds.some((id) => ids.has(id));
+    });
+    const removed = cache.entries.length - kept.length;
+    if (removed === 0) return { removed: 0 };
+    await writePromptCacheDocument(projectRoot, { entries: kept });
+    return { removed };
+  } catch {
+    return { removed: 0 };
+  }
+}
+
 export function buildPromptCacheStats(rawCache) {
   const cache = normalizePromptCacheDocument(rawCache);
   const totalEntries = cache.entries.length;

package/src/decision/client.js

@@ -213,21 +213,36 @@ export function createDecisionClient({
 
     // Language classification covers state + question text; the English
     // checkpoint is reachable only when the whole request proves English.
-    const serialized = serializeStatePacket(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);
-
-    // Budget gate — oversize state is never silently truncated.
+    // Malformed batch input (cyclic state, non-serializable values, internal
+    // budget-gate faults) resolves to a typed 'invalid' outcome instead of
+    // throwing — requestBatch never throws (unic-decision.mjs:575-586 parity).
+    let serialized;
+    let checkpoint;
     try {
+      serialized = serializeStatePacket(batch.statePacket ?? {});
+      const questionText = questions
+        .map(
+          (q) =>
+            `${q.decisionKey} ${q.instruction} ${(q.candidates ?? []).join(' ')}`,
+        )
+        .join(' ');
+      const languageClass = classifyLanguage(`${serialized} ${questionText}`);
+      checkpoint = resolveCheckpoint(languageClass, config);
+
+      // Budget gate — oversize state is never silently truncated.
       assertStateBudget(serialized, languageClass, maxStateTokens);
     } catch (err) {
       if (err?.code === 'state-too-large') {
-        return outcome('invalid', { fallbackCode: 'state-too-large', checkpoint });
+        return outcome('invalid', {
+          fallbackCode: 'state-too-large',
+          checkpoint: checkpoint ?? null,
+        });
       }
-      throw err;
+      return outcome('invalid', {
+        fallbackCode: 'malformed-question',
+        checkpoint: checkpoint ?? null,
+        detail: err?.message ?? String(err),
+      });
     }
 
     // Sensitive-value gate before serialization leaves the process.
@@ -250,9 +265,18 @@ export function createDecisionClient({
         });
       }
 
-      const body = JSON.stringify(
-        encodeBatch({ model: checkpoint, statePacket: serialized, questions }),
-      );
+      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 deadlineMs = Number.isFinite(batch?.deadlineMs)
         ? batch.deadlineMs

package/src/decision/protocol.js

@@ -172,7 +172,7 @@ 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';
+    if (!Array.isArray(question.candidates) || !question.candidates.includes(value)) return 'out-of-enum';
     return { value };
   }
   if (question.kind === 'noul') {

package/src/decision/registry.js

@@ -23,6 +23,7 @@ export const DECISION_FAMILIES = new Set([
   'review',
   'resume',
   'learn',
+  'runtime',
 ]);
 
 export const DECISION_KINDS = new Set(['choice', 'noul', 'score']);
@@ -37,9 +38,10 @@ export const CACHE_SENSITIVITY = new Set([
   '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]+$/;
+// Segments allow `[a-z0-9_-]` — registered runtime keys (runtime.stall_action.v1,
+// runtime.wake_needed.v1, runtime.safe_retry.v1) use snake_case segments.
+const DECISION_KEY_PATTERN = /^[a-z][a-z0-9_-]*(\.[a-z0-9_-]+)*\.v[0-9]+$/;
 
 const REQUIRED_STRING_FIELDS = [
   'decisionKey',
@@ -280,7 +282,7 @@ function isPlainObject(value) {
   return value !== null && typeof value === 'object' && !Array.isArray(value);
 }
 
-function validateEntry(entry, index, seen) {
+export function validateEntry(entry, index, seen) {
   const label = isPlainObject(entry) && typeof entry.decisionKey === 'string'
     ? entry.decisionKey
     : `entry[${index}]`;