@ngockhoale/ukit 3.0.2 → 3.0.4

package/src/decision/preflight.js

@@ -0,0 +1,492 @@
+/**
+ * preflight.js (TASK-003 / M07)
+ *
+ * Atomic preflight bundle builder/validator/applier (CONTRACTS.md C15/C16,
+ * UNIC_DECISION_SPEC §4/§13). No execution lane may begin from an undecided
+ * AI policy state: the owner derives bounded candidates deterministically,
+ * sends ONE batch containing the whole preflight group, validates the answers
+ * cross-field, and applies the bundle atomically — never half old, half new.
+ *
+ * Apply order is decide → validate → apply → capture fresh execution context
+ * → acknowledge → receipt. A suggestion is never `applied` without host
+ * acknowledgement; advisory hosts record `confirmation:'adapter-applied'`.
+ */
+
+import { createHash } from 'node:crypto';
+import { resolveCheckpoint } from './client.js';
+import { buildStatePacket, serializeStatePacket } from './statePacket.js';
+import { createLease, createCacheEpoch, DEFAULT_LEASE_CHOICES } from './lease.js';
+import { resolveModelTier } from '../core/executionContracts.js';
+
+export const PREFLIGHT_DECISION_KEYS = Object.freeze([
+  'preflight.execution-lane.v1',
+  'preflight.model-role.v1',
+  'preflight.reasoning-effort.v1',
+  'preflight.rigor.v1',
+  'preflight.capabilities.v1',
+  'preflight.verification-depth.v1',
+  'preflight.lease.v1',
+]);
+
+const RIGOR_ORDER = ['r0', 'r1', 'r2', 'r3', 'r4'];
+const EFFORT_ORDER = ['low', 'medium', 'high', 'max'];
+const VERIFICATION_DEPTHS = ['sanity', 'targeted', 'impact', 'full'];
+
+// Deterministic floors for a 'high-risk' route (ARCHITECTURE.md rigor matrix:
+// R3+ → impact+ verification; decision-table-v2 forces effort 'high').
+const HIGH_RISK_MIN_RIGOR = 'r3';
+const HIGH_RISK_MIN_EFFORT = 'high';
+const HIGH_RISK_MIN_DEPTH = 'impact';
+
+function fingerprint(text) {
+  return createHash('sha256').update(text).digest('hex');
+}
+
+function decisionPlane(config) {
+  const dp = config?.decisionPlane ?? config ?? {};
+  return dp && typeof dp === 'object' ? dp : {};
+}
+
+function floorName(riskFloor) {
+  if (typeof riskFloor === 'string') return riskFloor;
+  return riskFloor?.floor ?? 'none';
+}
+
+function unique(values) {
+  return [...new Set(values.filter((v) => typeof v === 'string' && v.length > 0))];
+}
+
+// Owner-bounded lease choices must be positive integers — malformed config
+// entries fall back to the spec defaults everywhere, not just in validation;
+// otherwise Math.min(...) yields NaN and createLease throws on the fallback path.
+function resolveLeaseChoices(dp) {
+  return Array.isArray(dp.leaseChoices) && dp.leaseChoices.length > 0
+    && dp.leaseChoices.every((v) => Number.isInteger(v) && v > 0)
+    ? dp.leaseChoices
+    : [...DEFAULT_LEASE_CHOICES];
+}
+
+/**
+ * Build the atomic preflight batch (C13): one boundary, one atomic question
+ * group covering lane, model role, reasoning effort, rigor, capabilities,
+ * verification depth, and lease. Candidates are derived deterministically
+ * from host capabilities, the route, and config — the model can only pick
+ * from hard-safe labels.
+ *
+ * @param {{route: object, hostCapabilities: object, config?: object,
+ *          languageClass?: string, taskBoundary?: string}} args
+ * @returns {{batch: object, candidateMap: object}}
+ */
+export function buildPreflightBatch({
+  route = {},
+  hostCapabilities = {},
+  config = {},
+  languageClass = 'unknown',
+  taskBoundary = 'task',
+} = {}) {
+  const dp = decisionPlane(config);
+  const execution = route?.execution ?? {};
+  const capabilityPolicy = route?.capabilityPolicy ?? {};
+  const floor = floorName(execution.riskFloor);
+  const highRisk = floor === 'high-risk';
+
+  const leaseChoices = resolveLeaseChoices(dp);
+  const portableEfforts =
+    Array.isArray(dp.portableReasoningEfforts) && dp.portableReasoningEfforts.length > 0
+      ? dp.portableReasoningEfforts
+      : [...EFFORT_ORDER];
+
+  // --- deterministic candidate derivation (owner-side, never model-invented)
+  const laneCandidates = unique(
+    Array.isArray(hostCapabilities?.lanes) && hostCapabilities.lanes.length > 0
+      ? hostCapabilities.lanes
+      : [execution.mode],
+  );
+  const modelRoleCandidates = unique(
+    Array.isArray(hostCapabilities?.modelRoles) && hostCapabilities.modelRoles.length > 0
+      ? hostCapabilities.modelRoles
+      : [execution.modelTier],
+  );
+  const hostEfforts = hostCapabilities?.modelEfforts
+    ? unique(Object.values(hostCapabilities.modelEfforts).flat())
+    : null;
+  const effortCandidates = hostEfforts
+    ? portableEfforts.filter((e) => hostEfforts.includes(e))
+    : portableEfforts;
+  const rigorCandidates = highRisk
+    ? RIGOR_ORDER.slice(RIGOR_ORDER.indexOf(HIGH_RISK_MIN_RIGOR))
+    : [...RIGOR_ORDER];
+  const depthPool =
+    Array.isArray(hostCapabilities?.verificationDepths) && hostCapabilities.verificationDepths.length > 0
+      ? hostCapabilities.verificationDepths
+      : VERIFICATION_DEPTHS;
+  const depthCandidates = highRisk
+    ? depthPool.filter((d) => VERIFICATION_DEPTHS.indexOf(d) >= VERIFICATION_DEPTHS.indexOf(HIGH_RISK_MIN_DEPTH))
+    : depthPool;
+
+  const required = Array.isArray(capabilityPolicy.required) ? capabilityPolicy.required : [];
+  const recommended = Array.isArray(capabilityPolicy.recommended) ? capabilityPolicy.recommended : [];
+  const capabilitySets = {
+    ...(hostCapabilities?.capabilitySets && typeof hostCapabilities.capabilitySets === 'object'
+      ? hostCapabilities.capabilitySets
+      : {}),
+  };
+  if (required.length > 0) capabilitySets['required-only'] = [...required];
+  if (recommended.length > 0) capabilitySets['required+recommended'] = [...required, ...recommended];
+  if (Object.keys(capabilitySets).length === 0) capabilitySets.none = [];
+  const capabilityCandidates = Object.keys(capabilitySets);
+
+  // A choice question with no derivable candidates cannot be asked safely —
+  // encodeQuestion would reject it. Substitute the deterministic baseline
+  // singleton (the value the fallback bundle picks); when no deterministic
+  // label exists (e.g. no model role for an informational lane) the question
+  // is undecidable and is dropped from the batch and its atomic group.
+  const tierDecision = resolveModelTier({
+    executionMode: execution.mode ?? null,
+    riskFloor: { floor },
+    hostCapabilities,
+  });
+  const deterministicLabels = {
+    'preflight.execution-lane.v1': execution.mode ?? null,
+    'preflight.model-role.v1': tierDecision.tier ?? execution.modelTier ?? null,
+    'preflight.reasoning-effort.v1': tierDecision.effort ?? 'medium',
+    'preflight.capabilities.v1': 'none',
+    'preflight.verification-depth.v1': highRisk ? HIGH_RISK_MIN_DEPTH : 'targeted',
+    'preflight.lease.v1': String(Math.min(...leaseChoices)),
+  };
+
+  const candidateMap = {
+    rigor: rigorCandidates,
+    lease: leaseChoices,
+    capabilities: capabilitySets,
+  };
+
+  const questions = [
+    {
+      decisionKey: 'preflight.execution-lane.v1',
+      kind: 'choice',
+      instruction: 'Pick the execution lane for this task boundary.',
+      candidates: laneCandidates,
+    },
+    {
+      decisionKey: 'preflight.model-role.v1',
+      kind: 'choice',
+      instruction: 'Pick the execution model role from the host capability map.',
+      candidates: modelRoleCandidates,
+    },
+    {
+      decisionKey: 'preflight.reasoning-effort.v1',
+      kind: 'choice',
+      instruction: 'Pick the lowest reasoning effort sufficient for the next unresolved work.',
+      candidates: effortCandidates,
+    },
+    {
+      decisionKey: 'preflight.rigor.v1',
+      kind: 'score',
+      instruction: 'Pick the rigor level within the deterministic floor.',
+      candidates: rigorCandidates,
+    },
+    {
+      decisionKey: 'preflight.capabilities.v1',
+      kind: 'choice',
+      instruction: 'Pick the active capability set.',
+      candidates: capabilityCandidates,
+    },
+    {
+      decisionKey: 'preflight.verification-depth.v1',
+      kind: 'choice',
+      instruction: 'Pick the initial verification depth.',
+      candidates: depthCandidates,
+    },
+    {
+      decisionKey: 'preflight.lease.v1',
+      kind: 'choice',
+      instruction: 'Pick how many generations the bundle stays valid.',
+      candidates: leaseChoices.map(String),
+    },
+  ].map((q) => ({
+    schemaVersion: 1,
+    family: 'preflight',
+    owner: 'taskRouting',
+    hardConstraintRefs: [],
+    ...q,
+    candidates:
+      q.candidates.length === 0 && deterministicLabels[q.decisionKey] != null
+        ? [deterministicLabels[q.decisionKey]]
+        : q.candidates,
+  })).filter((q) => q.candidates.length > 0);
+
+  const statePacket = buildStatePacket({
+    taskClass: route?.intent?.kind,
+    execution: { mode: execution.mode, rigor: execution.rigor, phase: execution.phase },
+    riskSignals: route?.evidence?.riskSignals ?? [],
+    capabilityAvailability: Array.isArray(hostCapabilities?.capabilities)
+      ? hostCapabilities.capabilities
+      : [],
+  });
+  const serialized = serializeStatePacket(statePacket);
+  const stateFingerprint = fingerprint(serialized).slice(0, 16);
+  const hostFingerprint = hostCapabilities?.fingerprint ?? null;
+
+  const batch = {
+    batchVersion: 1,
+    batchId: `pf-${stateFingerprint}`,
+    boundary: 'preflight',
+    stateFingerprint,
+    cacheEpoch: createCacheEpoch({
+      id: `epoch-${fingerprint(hostFingerprint ?? 'none').slice(0, 8)}`,
+      prefixFingerprint: hostCapabilities?.prefixFingerprint ?? null,
+    }),
+    languageClass,
+    checkpoint: resolveCheckpoint(languageClass, config),
+    questions,
+    atomicQuestionGroups: [questions.map((q) => q.decisionKey)],
+    stateBudget: dp.maxStateTokens ?? { multilingual: 1024, english: 512 },
+    statePacket,
+    taskBoundary,
+  };
+
+  return { batch, candidateMap };
+}
+
+/**
+ * Validate a parsed answer set into an atomic preflight bundle (C15).
+ * Cross-field rules run over the WHOLE bundle: an unsupported model/effort
+ * pair, an out-of-floor rigor/effort/depth, or any invalid answer blocks the
+ * bundle — it is rejected, never coerced and never half-applied.
+ *
+ * @param {object[]} answers normalized DecisionAnswer list (C14)
+ * @param {{hostCapabilities?: object, riskFloor?: object|string,
+ *          candidateMap?: object, config?: object, batch?: object,
+ *          taskBoundary?: string}} options `batch` (from buildPreflightBatch)
+ *          carries batchId/cacheEpoch onto the bundle for the receipt.
+ * @returns {{status: 'validated'|'blocked', errors: string[], bundle: object}}
+ */
+export function validatePreflightAnswers(
+  answers,
+  { hostCapabilities = {}, riskFloor = null, candidateMap = null, config = {}, batch = null, taskBoundary = 'task' } = {},
+) {
+  const dp = decisionPlane(config);
+  const leaseChoices = resolveLeaseChoices(dp);
+  // Only keys actually asked in the batch are required — buildPreflightBatch
+  // drops undecidable questions (0 derivable candidates), and requiring their
+  // answers would block every such bundle at canary.
+  const askedKeys = new Set(
+    (Array.isArray(batch?.questions) ? batch.questions : [])
+      .map((q) => q?.decisionKey)
+      .filter((k) => typeof k === 'string'),
+  );
+  const isRequired = (key) => askedKeys.size === 0 || askedKeys.has(key);
+  const floor = floorName(riskFloor);
+  const highRisk = floor === 'high-risk';
+  const errors = [];
+
+  const byKey = new Map();
+  for (const answer of Array.isArray(answers) ? answers : []) {
+    if (answer && typeof answer.decisionKey === 'string') byKey.set(answer.decisionKey, answer);
+  }
+
+  const valueOf = (key) => {
+    const answer = byKey.get(key);
+    if (!answer) {
+      if (isRequired(key)) errors.push(`${key}: missing answer.`);
+      return undefined;
+    }
+    if (answer.validationStatus !== 'valid') {
+      errors.push(`${key}: invalid answer (${answer.fallbackCode ?? 'unknown'}).`);
+      return undefined;
+    }
+    return answer.value;
+  };
+
+  const lane = valueOf('preflight.execution-lane.v1');
+  const modelRole = valueOf('preflight.model-role.v1');
+  const effort = valueOf('preflight.reasoning-effort.v1');
+  const rigorScore = valueOf('preflight.rigor.v1');
+  const capabilityLabel = valueOf('preflight.capabilities.v1');
+  const depth = valueOf('preflight.verification-depth.v1');
+  const leaseLabel = valueOf('preflight.lease.v1');
+
+  // score → legend label; choice labels map through the candidate map.
+  const rigorCandidates = candidateMap?.rigor ?? RIGOR_ORDER;
+  let rigor = null;
+  if (rigorScore !== undefined) {
+    rigor = rigorCandidates[rigorScore - 1] ?? null;
+    if (rigor === null) errors.push(`preflight.rigor.v1: score ${rigorScore} is out of the candidate legend.`);
+  }
+
+  const capabilitySets = candidateMap?.capabilities ?? {};
+  let activeCapabilities = null;
+  if (capabilityLabel !== undefined) {
+    activeCapabilities = capabilitySets[capabilityLabel] ?? null;
+    if (activeCapabilities === null) {
+      errors.push(`preflight.capabilities.v1: unknown capability set '${capabilityLabel}'.`);
+    }
+  }
+
+  let leaseGranted = null;
+  if (leaseLabel !== undefined) {
+    const parsed = Number(leaseLabel);
+    if (!leaseChoices.includes(parsed)) {
+      errors.push(`preflight.lease.v1: '${leaseLabel}' is not an owner-bounded lease choice.`);
+    } else {
+      leaseGranted = parsed;
+    }
+  }
+
+  // --- cross-field validation over the whole bundle
+  if (lane !== undefined && Array.isArray(hostCapabilities?.lanes)
+    && hostCapabilities.lanes.length > 0 && !hostCapabilities.lanes.includes(lane)) {
+    errors.push(`execution lane '${lane}' is not host-eligible.`);
+  }
+  if (modelRole !== undefined && Array.isArray(hostCapabilities?.modelRoles)
+    && hostCapabilities.modelRoles.length > 0 && !hostCapabilities.modelRoles.includes(modelRole)) {
+    errors.push(`model role '${modelRole}' is not in the host capability map.`);
+  }
+  const supportedEfforts = modelRole != null ? hostCapabilities?.modelEfforts?.[modelRole] : null;
+  if (effort !== undefined && Array.isArray(supportedEfforts) && !supportedEfforts.includes(effort)) {
+    errors.push(`reasoning effort '${effort}' is not supported by model role '${modelRole}'.`);
+  }
+  if (highRisk) {
+    if (rigor !== null && RIGOR_ORDER.indexOf(rigor) < RIGOR_ORDER.indexOf(HIGH_RISK_MIN_RIGOR)) {
+      errors.push(`rigor '${rigor}' is below the high-risk floor '${HIGH_RISK_MIN_RIGOR}'.`);
+    }
+    if (effort !== undefined && EFFORT_ORDER.indexOf(effort) < EFFORT_ORDER.indexOf(HIGH_RISK_MIN_EFFORT)) {
+      errors.push(`reasoning effort '${effort}' is below the high-risk floor '${HIGH_RISK_MIN_EFFORT}'.`);
+    }
+    if (depth !== undefined && VERIFICATION_DEPTHS.indexOf(depth) < VERIFICATION_DEPTHS.indexOf(HIGH_RISK_MIN_DEPTH)) {
+      errors.push(`verification depth '${depth}' is below the high-risk floor '${HIGH_RISK_MIN_DEPTH}'.`);
+    }
+  }
+
+  const hostFingerprint = hostCapabilities?.fingerprint ?? null;
+  const bundle = {
+    preflightVersion: 1,
+    taskBoundary,
+    batchId: batch?.batchId ?? null,
+    executionLane: lane ?? null,
+    executionModelRole: modelRole ?? null,
+    executionModelId: modelRole != null ? (hostCapabilities?.modelIds?.[modelRole] ?? null) : null,
+    reasoningEffort: effort ?? null,
+    rigor: rigor !== null ? rigor?.toUpperCase() ?? null : null,
+    activeCapabilities: activeCapabilities ?? [],
+    verificationDepth: depth ?? null,
+    lease: leaseGranted !== null ? createLease(leaseGranted, 'generation') : null,
+    hostCapabilityFingerprint: hostFingerprint,
+    cacheEpoch: batch?.cacheEpoch ?? createCacheEpoch({
+      id: `epoch-${fingerprint(hostFingerprint ?? 'none').slice(0, 8)}`,
+      prefixFingerprint: hostCapabilities?.prefixFingerprint ?? null,
+    }),
+    status: errors.length === 0 ? 'validated' : 'blocked',
+  };
+
+  return { status: bundle.status, errors, bundle };
+}
+
+/**
+ * Apply a validated (or deterministic fallback) bundle:
+ * apply → capture fresh execution context → acknowledge → receipt (C16).
+ * A bundle that is not 'validated'/'fallback' is rejected — a suggestion is
+ * never applied, and a blocked bundle is never half-applied.
+ *
+ * @param {object} bundle C15 preflight record from validatePreflightAnswers
+ *                        or buildFallbackPreflight
+ * @param {{host?: {advisoryOnly?: boolean, apply?: Function}}} options
+ * @returns {{preflight: object, receipt: object}}
+ */
+export function applyPreflight(bundle, { host = null } = {}) {
+  const selected = {
+    lane: bundle?.executionLane ?? null,
+    modelRole: bundle?.executionModelRole ?? null,
+    modelId: bundle?.executionModelId ?? null,
+    reasoningEffort: bundle?.reasoningEffort ?? null,
+    lease: bundle?.lease ?? null,
+  };
+  const baseReceipt = {
+    receiptVersion: 1,
+    batchId: bundle?.batchId ?? null,
+    decisionKeys: [...PREFLIGHT_DECISION_KEYS],
+    selected,
+    cacheEpoch: bundle?.cacheEpoch ?? null,
+    hostContextFingerprint: null,
+    confirmation: null,
+    status: 'rejected',
+    evidenceRefs: [],
+  };
+
+  if (!bundle || (bundle.status !== 'validated' && bundle.status !== 'fallback')) {
+    return { preflight: bundle, receipt: baseReceipt };
+  }
+
+  const applied = typeof host?.apply === 'function' ? host.apply(bundle) : null;
+  if (applied?.acknowledged !== true) {
+    // No host acknowledgement → not applied; the bundle keeps its status.
+    return { preflight: bundle, receipt: baseReceipt };
+  }
+
+  const confirmation =
+    bundle.status === 'fallback'
+      ? 'fallback-applied'
+      : host?.advisoryOnly === true
+        ? 'adapter-applied'
+        : 'native-context-captured';
+
+  const preflight = { ...bundle, status: 'applied' };
+  const receipt = {
+    ...baseReceipt,
+    hostContextFingerprint: applied.contextFingerprint ?? null,
+    confirmation,
+    status: 'applied',
+    evidenceRefs: Array.isArray(applied.evidenceRefs) ? applied.evidenceRefs : [],
+  };
+  return { preflight, receipt };
+}
+
+/**
+ * Deterministic baseline bundle for when the Decision Agent is unavailable
+ * (UNIC_DECISION_SPEC §4/§15): decision-table-v2 tier/effort, conservative
+ * rigor/depth floors, required capabilities only, minimal lease.
+ */
+export function buildFallbackPreflight({
+  route = {},
+  hostCapabilities = {},
+  config = {},
+  taskBoundary = 'task',
+} = {}) {
+  const dp = decisionPlane(config);
+  const execution = route?.execution ?? {};
+  const floor = floorName(execution.riskFloor);
+  const highRisk = floor === 'high-risk';
+  const leaseChoices = resolveLeaseChoices(dp);
+
+  const tierDecision = resolveModelTier({
+    executionMode: execution.mode ?? null,
+    riskFloor: typeof execution.riskFloor === 'object' ? execution.riskFloor : { floor },
+    hostCapabilities,
+  });
+  const modelRole = tierDecision.tier ?? execution.modelTier ?? null;
+  const required = Array.isArray(route?.capabilityPolicy?.required)
+    ? route.capabilityPolicy.required
+    : [];
+  const hostFingerprint = hostCapabilities?.fingerprint ?? null;
+
+  return {
+    preflightVersion: 1,
+    taskBoundary,
+    batchId: null,
+    executionLane: execution.mode ?? null,
+    executionModelRole: modelRole,
+    executionModelId: modelRole != null ? (hostCapabilities?.modelIds?.[modelRole] ?? null) : null,
+    reasoningEffort: tierDecision.effort ?? (highRisk ? 'high' : 'medium'),
+    rigor: execution.rigor ?? (highRisk ? 'R3' : 'R1'),
+    activeCapabilities: [...required],
+    verificationDepth: highRisk ? 'impact' : 'targeted',
+    lease: createLease(Math.min(...leaseChoices), 'generation'),
+    hostCapabilityFingerprint: hostFingerprint,
+    cacheEpoch: createCacheEpoch({
+      id: `epoch-${fingerprint(hostFingerprint ?? 'none').slice(0, 8)}`,
+      prefixFingerprint: hostCapabilities?.prefixFingerprint ?? null,
+    }),
+    status: 'fallback',
+  };
+}