@ngockhoale/ukit 3.0.7 → 3.0.9

package/src/decision/runtimeDecide.js

@@ -0,0 +1,242 @@
+// src/decision/runtimeDecide.js — pure (no I/O, no config of its own).
+// C65 G3-FR03/FR04 — registered semantic decisions + bounded fallback.
+//
+// createRuntimeDecider({ client, registry?, confidenceFloor?, now? }) produces
+// the `decideFn` runtimeScheduler expects: one ambiguous classified item →
+// exactly one client.requestBatch → TypedDecision, or a typed conservative
+// Fallback on every failure mode. The gateway is contacted ONLY for items
+// classified 'model_decision' with a registered decisionKey — known signals
+// never reach the model.
+//
+// Fallback contract (SPEC §4, frozen):
+//   { decidedBy:'fallback', code:
+//     'timeout'|'invalid'|'unavailable'|'low_confidence'|'abstained',
+//     action: <conservative per decisionKey> }
+// Fallback NEVER auto-approves a retry or an escalation-to-action and never
+// throws.
+
+import {
+  createDecisionRegistry,
+  DECISION_REGISTRY,
+} from './registry.js';
+
+const DEFAULT_CONFIDENCE_FLOOR = 0.6;
+
+/**
+ * Registered runtime.*.v1 semantic decisions (G3-FR03). Each entry conforms
+ * to validateEntry/DECISION_KEY_PATTERN; `instruction`/`candidates` ride
+ * along as entry metadata so the decider can build the wire question without
+ * a second source of truth. All ship at rolloutStage 'off'.
+ */
+export const RUNTIME_DECISIONS = Object.freeze([
+  {
+    decisionKey: 'runtime.stall_action.v1',
+    schemaVersion: 1,
+    family: 'runtime',
+    owner: 'runtimeScheduler',
+    kind: 'choice',
+    description: 'Action for an ambiguous stalled/timeout observation without explicit spec policy.',
+    candidatePolicy: 'conservative-stall-actions',
+    hardConstraints: ['no-auto-kill'],
+    probabilityPolicy: 'raw-label',
+    fallbackPolicy: 'frozen-conservative-fallback',
+    telemetryClass: 'decision',
+    rolloutStage: 'off',
+    cacheSensitivity: 'none',
+    instruction:
+      'A runtime operation reported a stalled or timeout observation with no explicit spec policy. Choose the next action.',
+    candidates: ['continue_observe', 'request_nudge', 'escalate'],
+  },
+  {
+    decisionKey: 'runtime.wake_needed.v1',
+    schemaVersion: 1,
+    family: 'runtime',
+    owner: 'runtimeScheduler',
+    kind: 'choice',
+    description: 'Whether an ambiguous runtime event needs to wake a host/human, from an unparseable or unknown payload.',
+    candidatePolicy: 'conservative-wake-actions',
+    hardConstraints: ['no-silent-drop'],
+    probabilityPolicy: 'raw-label',
+    fallbackPolicy: 'frozen-conservative-fallback',
+    telemetryClass: 'decision',
+    rolloutStage: 'off',
+    cacheSensitivity: 'none',
+    instruction:
+      'A runtime event arrived with an unparseable or unrecognized payload. Decide whether to keep observing or escalate.',
+    candidates: ['continue_observe', 'escalate'],
+  },
+  {
+    decisionKey: 'runtime.safe_retry.v1',
+    schemaVersion: 1,
+    family: 'runtime',
+    owner: 'runtimeScheduler',
+    kind: 'choice',
+    description: 'Whether an ambiguous failure-adjacent event is safe to retry within registered bounds.',
+    candidatePolicy: 'conservative-retry-actions',
+    hardConstraints: ['no-auto-retry-approval'],
+    probabilityPolicy: 'raw-label',
+    fallbackPolicy: 'frozen-conservative-fallback',
+    telemetryClass: 'decision',
+    rolloutStage: 'off',
+    cacheSensitivity: 'none',
+    instruction:
+      'A runtime event may warrant a retry but no deterministic policy covers it. Decide conservatively.',
+    candidates: ['retry', 'no_retry', 'escalate'],
+  },
+]);
+
+// Decision→fallback action map (frozen, SPEC §4). Fallbacks are conservative:
+// a stall keeps observing (never auto-kills), an unknown retry does not retry,
+// an ambiguous wake escalates to a human boundary.
+const FALLBACK_ACTIONS = Object.freeze({
+  'runtime.stall_action.v1': 'continue_observe',
+  'runtime.wake_needed.v1': 'escalate',
+  'runtime.safe_retry.v1': 'no_retry',
+});
+
+// Batch-level statuses → fallback codes. 'abstained' stays distinct so
+// shadow-agreement telemetry can separate model-refusal from transport
+// failure; everything else folds into the nearest conservative class.
+const STATUS_CODES = Object.freeze({
+  timeout: 'timeout',
+  invalid: 'invalid',
+  abstained: 'abstained',
+  unavailable: 'unavailable',
+  unsupported: 'unavailable',
+  'blocked-sensitive': 'invalid',
+});
+
+function isPlainObject(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function fallback(code, action) {
+  return { decidedBy: 'fallback', code, action };
+}
+
+function fallbackActionFor(decisionKey) {
+  return FALLBACK_ACTIONS[decisionKey] ?? 'escalate';
+}
+
+function resolveFloor(confidenceFloor, decisionKey) {
+  if (isPlainObject(confidenceFloor)) {
+    const perKey = confidenceFloor[decisionKey];
+    return Number.isFinite(perKey) ? perKey : DEFAULT_CONFIDENCE_FLOOR;
+  }
+  return Number.isFinite(confidenceFloor) ? confidenceFloor : DEFAULT_CONFIDENCE_FLOOR;
+}
+
+// Minimal state packet — only the fields the model needs; the full event
+// payload stays out of the request (budget + sensitive-value gates live in
+// the client).
+function buildStatePacket(item) {
+  return {
+    stateVersion: 1,
+    decisionKey: item.decisionKey ?? null,
+    reason: item.reason ?? null,
+    eventType: item.event?.eventType ?? item.eventType ?? null,
+  };
+}
+
+function buildQuestion(item, entry) {
+  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 : [],
+  };
+}
+
+/**
+ * @param {{client: {requestBatch: Function}, registry?: object,
+ *          confidenceFloor?: number|object, now?: Function}} options
+ *   registry: defaults to DECISION_REGISTRY composed with RUNTIME_DECISIONS —
+ *   the shipped catalog is frozen, so composition copies, never mutates.
+ * @returns {{decide: (item: object) => Promise<object>}}
+ */
+export function createRuntimeDecider({
+  client,
+  registry,
+  confidenceFloor,
+  now = () => Date.now(),
+} = {}) {
+  const resolvedRegistry =
+    registry ?? createDecisionRegistry([...DECISION_REGISTRY, ...RUNTIME_DECISIONS]);
+  void now; // injectable for parity with client/scheduler; no clock use yet.
+
+  async function decide(item) {
+    if (!isPlainObject(item)) {
+      return fallback('invalid', 'escalate');
+    }
+    // Only 'model_decision' items reach the gateway — known local signals are
+    // decided upstream by runtimeFilter and pass through untouched.
+    if (item.action !== 'model_decision') {
+      return item;
+    }
+    const decisionKey = item.decisionKey;
+    const conservative = fallbackActionFor(decisionKey);
+    const entry =
+      typeof decisionKey === 'string' ? resolvedRegistry.getDecision(decisionKey) : null;
+    if (!entry) {
+      // Unregistered/unknown key — never send an unregistered question to the
+      // gateway; conservative fallback instead.
+      return fallback('invalid', conservative);
+    }
+
+    let result;
+    try {
+      result = await client.requestBatch({
+        batchId: item.batchId ?? null,
+        boundary: 'runtime',
+        statePacket: buildStatePacket(item),
+        questions: [buildQuestion(item, entry)],
+      });
+    } catch {
+      // A throwing client never propagates — SPEC §5: decideFn throws →
+      // 'invalid', scheduler stays alive.
+      return fallback('invalid', conservative);
+    }
+
+    const statusCode = STATUS_CODES[result?.status];
+    if (statusCode !== undefined) {
+      return fallback(statusCode, conservative);
+    }
+
+    const answer = Array.isArray(result?.answers)
+      ? result.answers.find(
+          (a) => a?.decisionKey === decisionKey && a?.validationStatus === 'valid',
+        )
+      : null;
+    if (!answer) {
+      return fallback('invalid', conservative);
+    }
+    // Missing confidence is treated as low confidence — never auto-approve.
+    const confidence = Number.isFinite(answer.confidence) ? answer.confidence : 0;
+    if (confidence < resolveFloor(confidenceFloor, decisionKey)) {
+      return fallback('low_confidence', conservative);
+    }
+
+    return {
+      decidedBy: 'model',
+      decisionKey,
+      action: answer.value,
+      value: answer.value,
+      kind: answer.kind ?? entry.kind,
+      confidence: answer.confidence,
+      probabilities: answer.probabilities ?? null,
+      calibration: answer.calibration ?? 'unknown',
+      checkpoint: result?.checkpoint ?? null,
+      batchId: result?.batchId ?? null,
+      requestFingerprint: result?.requestFingerprint ?? null,
+      latencyClass: result?.latencyClass ?? null,
+      circuitState: result?.circuitState ?? null,
+      finishReason: result?.finishReason ?? null,
+    };
+  }
+
+  return { decide };
+}

package/src/decision/runtimeFilter.js

@@ -0,0 +1,150 @@
+// src/decision/runtimeFilter.js — pure (no I/O, no config, no gateway).
+// C65 G3-FR01 — deterministic pre-filter for G1/G2 SemanticEvents.
+// Known signals are decided locally and must NEVER produce a model call
+// downstream; only genuinely ambiguous items return action 'model_decision'
+// with a registered `runtime.*.v1` decisionKey.
+//
+// Interface (SPEC §4, frozen):
+//   classifyRuntimeEvent(event, policy?) -> {
+//     action: 'local_transition'|'local_observation'|'local_action'
+//             |'model_decision'|'escalate'|'ignore',
+//     priority: 'critical'|'decision'|'progress',
+//     coalesceKey?: string,   // only for coalescible progress
+//     decisionKey?: string,   // only when action='model_decision'
+//     reason: string }
+//
+// Consumes: SemanticEvent { eventType, safePayload, operationId, seq, ... }
+// from src/core/agentRuntime/contract.js; liveness class vocabulary from
+// src/core/agentRuntime/liveness.js.
+// Consumed by: runtimeScheduler.submit (TASK-002), runtimeDecide (TASK-003).
+
+import { TERMINAL_STATES } from '../core/agentRuntime/contract.js';
+import { LIVENESS_CLASSES } from '../core/agentRuntime/liveness.js';
+
+const TERMINAL_SET = new Set(TERMINAL_STATES);
+const LIVENESS_SET = new Set(LIVENESS_CLASSES);
+
+// Observation classes that represent redundant progress — safe to coalesce
+// by key, latest wins (SPEC §5).
+const COALESCIBLE_CLASSES = new Set(['live_progressing', 'silent_live']);
+
+// Observation classes where a stall decision may be needed: with an explicit
+// spec/policy stallAction the action is deterministic; without one the item
+// is ambiguous and goes to the model via runtime.stall_action.v1.
+const STALL_CLASSES = new Set(['stalled', 'timeout']);
+
+// Ambiguous items that need a semantic decision: which decision key each
+// maps to. Keys must be registered in the decision registry (TASK-003).
+const DECISION_KEYS = Object.freeze({
+  stall: 'runtime.stall_action.v1',
+  ambiguous: 'runtime.wake_needed.v1',
+});
+
+// Signals that a human/authorization boundary must resolve — never dropped,
+// never coalesced, never auto-acted-on.
+const ESCALATION_EVENT_TYPE = /permission|input[_-]?required|authoriz/i;
+const ESCALATION_CLASS = /permission|input[_-]?required|authoriz|approval/i;
+
+function result(action, priority, reason, extra) {
+  return { action, priority, reason, ...extra };
+}
+
+const ignore = (reason) => result('ignore', 'progress', reason);
+
+/**
+ * Classify one runtime SemanticEvent into a local action, a model-decision
+ * candidate, an escalation, or ignore. Pure: no I/O, no config import.
+ *
+ * @param {object} event  G1 SemanticEvent envelope
+ * @param {object} [policy] { stallAction?: string } — explicit spec policy
+ * @returns {{action:string,priority:string,coalesceKey?:string,
+ *            decisionKey?:string,reason:string}}
+ */
+export function classifyRuntimeEvent(event, policy) {
+  if (event === null || typeof event !== 'object' || Array.isArray(event)) {
+    return ignore('malformed_event');
+  }
+  const eventType = event.eventType;
+  if (typeof eventType !== 'string' || eventType.length === 0) {
+    return ignore('malformed_event');
+  }
+
+  // Permission / user-input / authorization signals escalate deterministically,
+  // regardless of the channel they arrive on.
+  if (ESCALATION_EVENT_TYPE.test(eventType)) {
+    return result('escalate', 'critical', `escalation_signal:${eventType}`);
+  }
+
+  const safePayload = event.safePayload;
+  const operationId =
+    typeof event.operationId === 'string' && event.operationId.length > 0
+      ? event.operationId
+      : 'unknown';
+
+  switch (eventType) {
+    case 'operation.transition': {
+      if (typeof safePayload !== 'object' || safePayload === null) {
+        return result('model_decision', 'decision', 'unparseable_payload', {
+          decisionKey: DECISION_KEYS.ambiguous,
+        });
+      }
+      const to = safePayload.to;
+      if (TERMINAL_SET.has(to)) {
+        return result('local_transition', 'critical', `terminal_transition:${to}`);
+      }
+      // Non-terminal transition (queued→running, recovery_required, …):
+      // known signal, decided locally; never reaches the model.
+      return result('local_transition', 'progress', `transition:${to ?? 'unknown'}`);
+    }
+
+    case 'operation.observation': {
+      if (typeof safePayload !== 'object' || safePayload === null) {
+        return result('model_decision', 'decision', 'unparseable_payload', {
+          decisionKey: DECISION_KEYS.ambiguous,
+        });
+      }
+      const cls = safePayload.class;
+
+      if (typeof cls === 'string' && ESCALATION_CLASS.test(cls)) {
+        return result('escalate', 'critical', `escalation_signal:${cls}`);
+      }
+
+      if (COALESCIBLE_CLASSES.has(cls)) {
+        return result('local_observation', 'progress', `observation:${cls}`, {
+          coalesceKey: `obs:${operationId}:${cls}`,
+        });
+      }
+
+      if (STALL_CLASSES.has(cls)) {
+        const stallAction =
+          policy && typeof policy === 'object' && typeof policy.stallAction === 'string'
+            ? policy.stallAction
+            : null;
+        if (stallAction) {
+          return result('local_action', 'critical', `policy_stall_action:${stallAction}:${cls}`);
+        }
+        return result('model_decision', 'decision', `ambiguous_stall:${cls}`, {
+          decisionKey: DECISION_KEYS.stall,
+        });
+      }
+
+      if (LIVENESS_SET.has(cls)) {
+        // 'exited' — the only remaining liveness class. Terminal-adjacent
+        // sample signal: critical so it is never dropped/starved by progress.
+        return result('local_observation', 'critical', `observation:${cls}`);
+      }
+
+      // Unrecognized observation class — ambiguous.
+      return result('model_decision', 'decision', `unknown_observation_class:${cls ?? 'none'}`, {
+        decisionKey: DECISION_KEYS.ambiguous,
+      });
+    }
+
+    default:
+      // Valid envelope shape but a vocabulary the filter does not own —
+      // ambiguous, candidate for a semantic decision.
+      return result('model_decision', 'decision', `unknown_event_type:${eventType}`, {
+        decisionKey: DECISION_KEYS.ambiguous,
+      });
+  }
+}

package/src/decision/runtimeScheduler.js

@@ -0,0 +1,239 @@
+/**
+ * runtimeScheduler.js (G3-FR02)
+ *
+ * Bounded 3-tier queue for classified runtime items (SPEC §4):
+ *   - critical : terminal/failure/cancel/permission — emitted directly via
+ *                emitFn at flush; never dropped, never coalesced, never
+ *                counted against maxQueue, always drained first.
+ *   - decision : ambiguous items awaiting decideFn.
+ *   - progress : redundant progress — coalesced by coalesceKey while an
+ *                entry is pending (latest wins); eligible for drain after
+ *                coalesceWindowMs from first arrival.
+ *
+ * Serial drain (maxInFlight = 1 — the gateway is a single local model).
+ * decideFn failures convert to typed Fallback objects emitted via emitFn;
+ * a decideFn that never resolves yields { code:'timeout' }.
+ *
+ * Pure module: no I/O, no config. All dependencies injected via opts.
+ */
+
+import { resolveConfigStage } from '../core/runtimeConfig.js';
+import { selectResourcePolicy } from '../core/agentRuntime/resourcePolicy.js';
+
+// G6 (DR-09): `decisionRuntime.resourcePolicy.stage` — absent/malformed →
+// 'off'; 'shadow' consults selectResourcePolicy on submit and records a
+// bounded receipt WITHOUT changing enqueue behavior. A policy throw or
+// malformed decision deterministically falls back to the prior path.
+const RESOURCE_FLAG = 'decisionRuntime.resourcePolicy.stage';
+const RESOURCE_RECEIPT_CAP = 128;
+
+// priority → eventClass for the resource consult. Scheduler-internal,
+// fail-open: unknown priorities consult as 'progress' (the only coalescible
+// class); malformed input still resolves emit downstream.
+const EVENT_CLASS_BY_PRIORITY = Object.freeze({
+  critical: 'terminal',
+  progress: 'progress',
+  decision: 'progress',
+});
+
+const DEFAULT_COALESCE_WINDOW_MS = 250;
+const DEFAULT_MAX_QUEUE = 256;
+const DEFAULT_DECISION_TIMEOUT_MS = 5000;
+
+function fallback(code, item) {
+  return { decidedBy: 'fallback', code, action: item?.action ?? 'ignore' };
+}
+
+export function createScheduler(opts = {}) {
+  const decideFn = opts.decideFn ?? (async () => fallback('unavailable'));
+  const emitFn = opts.emitFn ?? (() => {});
+  const now = opts.now ?? (() => Date.now());
+  const coalesceWindowMs = opts.coalesceWindowMs ?? DEFAULT_COALESCE_WINDOW_MS;
+  const maxQueue = opts.maxQueue ?? DEFAULT_MAX_QUEUE;
+  const decisionTimeoutMs = opts.decisionTimeoutMs ?? DEFAULT_DECISION_TIMEOUT_MS;
+  // maxInFlight accepted for forward-compat; drain is serial regardless.
+  void (opts.maxInFlight ?? 1);
+
+  const resourceStage = () => resolveConfigStage(opts.config ?? null, RESOURCE_FLAG);
+  const resourcePolicyFn = typeof opts.resourcePolicyFn === 'function'
+    ? opts.resourcePolicyFn
+    : selectResourcePolicy;
+  const resourcesFn = typeof opts.resourcesFn === 'function'
+    ? opts.resourcesFn
+    : () => ({});
+  const resourceReceipts = [];
+
+  function recordResourceReceipt(entry) {
+    if (resourceReceipts.length >= RESOURCE_RECEIPT_CAP) resourceReceipts.shift();
+    resourceReceipts.push(Object.freeze(entry));
+  }
+
+  /**
+   * Shadow consult: evaluate the resource policy for this submit and record
+   * a bounded receipt. Never changes enqueue behavior; never throws.
+   */
+  function consultResourcePolicy(item) {
+    let decision;
+    let error;
+    try {
+      const resources = resourcesFn() ?? {};
+      decision = resourcePolicyFn({
+        cpuPressure: typeof resources.cpuPressure === 'string' ? resources.cpuPressure : 'normal',
+        eventClass: EVENT_CLASS_BY_PRIORITY[item?.priority] ?? 'progress',
+        queueDepth: boundedSize(),
+      });
+    } catch (err) {
+      error = String(err?.message ?? err);
+    }
+    const valid = decision !== null && typeof decision === 'object'
+      && (decision.action === 'emit' || decision.action === 'coalesce' || decision.action === 'defer');
+    recordResourceReceipt({
+      priority: item?.priority ?? null,
+      stage: resourceStage(),
+      decision: valid ? { action: decision.action, reason: decision.reason } : null,
+      error: error ?? null,
+    });
+  }
+
+  const critical = [];
+  const decision = [];
+  const progressPending = new Map(); // coalesceKey -> { item, firstArrival }
+  const timers = new Set();
+  let closed = false;
+  let closedWith = 0;
+  const counters = { submitted: 0, coalesced: 0, dropped: 0, deferred: 0, emitted: 0 };
+
+  function boundedSize() {
+    return decision.length + progressPending.size;
+  }
+
+  function submit(item) {
+    if (closed || !item || typeof item !== 'object') {
+      return { accepted: false, code: closed ? 'closed' : 'invalid' };
+    }
+    // G6 resource consult — shadow evaluates+records a bounded receipt;
+    // enqueue below is always the prior path (throw/malformed → prior
+    // behavior deterministically).
+    if (resourceStage() !== 'off') {
+      consultResourcePolicy(item);
+    }
+    if (item.priority === 'critical') {
+      critical.push(item);
+      counters.submitted++;
+      return { accepted: true };
+    }
+    if (item.priority === 'progress' && item.coalesceKey) {
+      const existing = progressPending.get(item.coalesceKey);
+      if (existing) {
+        existing.item = item; // latest wins
+        counters.coalesced++;
+        counters.submitted++;
+        return { accepted: true };
+      }
+      if (boundedSize() >= maxQueue) {
+        counters.dropped++;
+        return { accepted: false, code: 'queue_full' };
+      }
+      progressPending.set(item.coalesceKey, { item, firstArrival: now() });
+      counters.submitted++;
+      return { accepted: true };
+    }
+    // decision tier (or progress without a key — cannot coalesce)
+    if (boundedSize() >= maxQueue) {
+      counters.dropped++;
+      return { accepted: false, code: 'queue_full' };
+    }
+    decision.push(item);
+    counters.submitted++;
+    return { accepted: true };
+  }
+
+  function scheduleTimeout(ms) {
+    let handle;
+    const p = new Promise((resolve) => {
+      handle = setTimeout(() => {
+        timers.delete(handle);
+        resolve('timeout');
+      }, ms);
+      if (typeof handle.unref === 'function') handle.unref();
+    });
+    timers.add(handle);
+    return { promise: p, cancel: () => { clearTimeout(handle); timers.delete(handle); } };
+  }
+
+  async function decide(item) {
+    const t = scheduleTimeout(decisionTimeoutMs);
+    try {
+      const result = await Promise.race([Promise.resolve().then(() => decideFn(item)), t.promise]);
+      t.cancel();
+      if (result === 'timeout') return fallback('timeout', item);
+      if (result && result.decidedBy === 'fallback') return result;
+      if (result === undefined || result === null) return fallback('invalid', item);
+      return result;
+    } catch {
+      t.cancel();
+      return fallback('invalid', item);
+    }
+  }
+
+  async function flush() {
+    const report = { processed: 0, emitted: 0, coalesced: 0, dropped: 0, deferred: 0 };
+    if (closed) return report;
+
+    while (critical.length) {
+      const item = critical.shift();
+      emitFn(item);
+      counters.emitted++;
+      report.processed++;
+      report.emitted++;
+    }
+    while (decision.length) {
+      const item = decision.shift();
+      emitFn(await decide(item));
+      counters.emitted++;
+      report.processed++;
+      report.emitted++;
+    }
+    const t = now();
+    for (const [key, entry] of progressPending) {
+      if (t - entry.firstArrival < coalesceWindowMs) {
+        counters.deferred++;
+        report.deferred++;
+        continue;
+      }
+      progressPending.delete(key);
+      emitFn(await decide(entry.item));
+      counters.emitted++;
+      report.processed++;
+      report.emitted++;
+    }
+    return report;
+  }
+
+  function stats() {
+    return {
+      ...counters,
+      pending: critical.length + decision.length + progressPending.size,
+      closedWith,
+      closed,
+    };
+  }
+
+  async function close() {
+    if (closed) return;
+    closed = true;
+    closedWith = critical.length + decision.length + progressPending.size;
+    critical.length = 0;
+    decision.length = 0;
+    progressPending.clear();
+    for (const h of timers) clearTimeout(h);
+    timers.clear();
+  }
+
+  /** Bounded frozen receipts of shadow-stage resource-policy consults (G6). */
+  function resourcePolicyReceipts() {
+    return [...resourceReceipts];
+  }
+
+  return { submit, flush, stats, close, resourcePolicyReceipts };
+}

package/src/index/buildIndex.js

@@ -255,9 +255,9 @@ export async function buildCodeIndex({ rootDir = process.cwd(), changedFiles = n
       && Array.isArray(previousCallsArtifact.items);
 
     if (canReuseParsedArtifacts) {
-      const previousSymbolsByPath = groupBy(previousSymbolsArtifact.items ?? [], (item) => item.filePath);
-      const previousImportsByPath = groupBy(previousImportsArtifact.items ?? [], (item) => item.from);
-      const previousCallsByPath = groupBy(previousCallsArtifact.items ?? [], (item) => item.filePath);
+      const previousSymbolsByPath = groupBy(previousSymbolsArtifact.items ?? [], (item) => item?.filePath);
+      const previousImportsByPath = groupBy(previousImportsArtifact.items ?? [], (item) => item?.from);
+      const previousCallsByPath = groupBy(previousCallsArtifact.items ?? [], (item) => item?.filePath);
 
       for (const filePath of reusableCodeFiles) {
         symbols.push(...(previousSymbolsByPath.get(filePath) ?? []));
@@ -891,9 +891,9 @@ async function tryIncrementalIndexUpdate({ absoluteRoot, indexDir, changedPaths,
   }
   const styleFilePaths = styleEntries.filter(Boolean).map((entry) => normalizeRelative(absoluteRoot, entry.absolutePath));
 
-  const previousSymbolsByPath = groupBy(symbolsArtifact.items ?? [], (item) => item.filePath);
-  const previousImportsByPath = groupBy(importsArtifact.items ?? [], (item) => item.from);
-  const previousCallsByPath = groupBy(callsArtifact.items ?? [], (item) => item.filePath);
+  const previousSymbolsByPath = groupBy(symbolsArtifact.items ?? [], (item) => item?.filePath);
+  const previousImportsByPath = groupBy(importsArtifact.items ?? [], (item) => item?.from);
+  const previousCallsByPath = groupBy(callsArtifact.items ?? [], (item) => item?.filePath);
 
   const parsedSet = new Set(parsedFiles);
   const codeFiles = mergedFileRecords.filter((record) => CODE_EXTENSIONS.has(record.ext));
@@ -2385,8 +2385,8 @@ const ARCHETYPE_RULES = [
   { pattern: /(?:^|\/)(?:models?|schemas?)\//, archetype: 'schema' },
 ];
 
-function classifyArchetypes(fileRecords, symbols) {
-  const symbolNamesByPath = groupBy(symbols, (s) => s.filePath);
+export function classifyArchetypes(fileRecords, symbols) {
+  const symbolNamesByPath = groupBy(symbols, (s) => s?.filePath);
 
   return fileRecords
     .filter((f) => CODE_EXTENSIONS.has(f.ext))
@@ -2409,12 +2409,13 @@ function classifyArchetypes(fileRecords, symbols) {
 
       if (!archetype) {
         const fileSymbols = symbolNamesByPath.get(file.filePath) ?? [];
-        const hasDefaultExport = fileSymbols.some((s) => s.name === 'default');
+        const hasDefaultExport = fileSymbols.some((s) => s?.name === 'default');
         const hasComponentSignal = file.ext === '.vue'
           || fileSymbols.some((s) =>
-            s.type === 'component-name'
-            || s.name.toLowerCase().includes('component')
-            || s.name.toLowerCase().includes('page'),
+            s?.type === 'component-name'
+            || (typeof s?.name === 'string'
+              && (s.name.toLowerCase().includes('component')
+                || s.name.toLowerCase().includes('page'))),
           );
 
         if ((hasDefaultExport || file.ext === '.vue') && hasComponentSignal) {