@cassiomc1/forgeloop 1.13.0 → 2.0.0-rc.2

package/src/core/integration-resources.js

@@ -1,7 +1,9 @@
 import path from "node:path";
+import { withProjectStorage } from "../storage/project-boundary.js";
+import { withProjectReadSnapshot } from "../storage/project-read-snapshot.js";
 import { runProtocolInfo } from "../commands/protocol-info.js";
 import { readContract } from "./contract.js";
-import { discoverTasks } from "./task-discovery.js";
+import { discoverTaskSummaries } from "./task-discovery.js";
 import { resolveTaskClaimState } from "./task-claim-state.js";
 import { runStatus } from "../commands/status.js";
 import { runContinuity } from "../commands/continuity.js";
@@ -10,17 +12,23 @@ import { listApprovals } from "./approvals.js";
 import { buildTrajectoryMetrics } from "./trajectory-metrics.js";
 import { loadCapabilityPolicy } from "./capability-policy.js";
 import { readdir } from "node:fs/promises";
-import { readJsonArtifact } from "./artifacts.js";
+import { getOperationalStore, listOperationalArtifactNames } from "../storage/operational-context.js";
+import { readJsonArtifact, parseCapturedJsonArtifact } from "./artifacts.js";
 import { taskDirectory } from "./task-paths.js";
 import { resolveWorkspaceBindingStatus } from "./workspace-binding.js";
-import { listCanonicalHandoffs } from "./handoff.js";
-import { readHandoffAcceptanceLedger, resolveHandoffAcceptance } from "./handoff-acceptance.js";
+import { runHandoffList } from "../commands/handoff-list.js";
 import { resolveResponsibilityStatus } from "./responsibility.js";
 import { readVerificationScope } from "./verification-scope.js";
 import { resolveAttestationStatus } from "./attestation.js";
 import { buildExecutionProfileContext } from "./execution-profile-context.js";
 import { projectStructuralQualityStatus } from "./structural-quality/service.js";
 import { getRepositoryIndexStatus } from "../repository-index/status.js";
+import { buildAuditUxView } from "./audit-ux.js";
+import { runContextPlan } from "../commands/context-plan.js";
+import { runModelRoute } from "../commands/model-route.js";
+import { readPersistedRoute } from "./route-artifact.js";
+import { readWorkState } from "./work-state.js";
+import { readTestUtility } from "./test-intelligence/service.js";
 
 /**
  * Canonical integration resource allowlist.
@@ -86,11 +94,18 @@ export const INTEGRATION_RESOURCE_DEFINITIONS = Object.freeze({
   "task/approvals": Object.freeze({ scope: "TASK", description: "Durable approval artifacts for one task." }),
   "task/metrics": Object.freeze({ scope: "TASK", description: "Read-only trajectory metrics for one task." }),
   "task/context": Object.freeze({ scope: "TASK", description: "Read-only profile-aware task context with bounded presentation policy." }),
+  "task/audit-view": Object.freeze({ scope: "TASK", description: "Bounded read-only Audit UX projection composed from canonical task resolvers." }),
   "task/evaluations": Object.freeze({ scope: "TASK", description: "Persisted trajectory evaluations for one task." }),
+  "task/decisions": Object.freeze({ scope: "TASK", description: "Persisted, fingerprint-bound semantic decisions without lifecycle or evidence authority." }),
+  "task/context-plan": Object.freeze({ scope: "TASK", description: "Bounded non-authoritative semantic context-plan projection." }),
+  "task/model-route": Object.freeze({ scope: "TASK", description: "Deterministic model-routing floor with advisory semantic escalation." }),
+  "task/test-utility": Object.freeze({ scope: "TASK", description: "Non-evidence test inventory and utility analysis; never deletion authority." }),
   "project/capability-policy": Object.freeze({ scope: "PROJECT", description: "Project capability policy, never host authority." }),
   "repository/index-status": Object.freeze({ scope: "PROJECT", description: "Provider-neutral repository-index health and owned-server status." }),
 });
 
+const TASK_RESOURCE_URIS = new Set(Object.keys(INTEGRATION_RESOURCE_DEFINITIONS).filter((uri) => uri.startsWith("task/")));
+
 function ownershipProjection(projection) {
   return {
     taskId: projection.taskId,
@@ -105,6 +120,12 @@ function ownershipProjection(projection) {
   };
 }
 
+async function resourceArtifactNames(projectPath, taskId, kind, directory) {
+  const names = listOperationalArtifactNames(projectPath, taskId, kind);
+  if (names !== null) return names;
+  try { return await readdir(directory); } catch { return []; }
+}
+
 async function readForgeLoopIntegrationResourceCore(uri, {
   projectPath = ".",
   packageRoot = undefined,
@@ -120,67 +141,15 @@ async function readForgeLoopIntegrationResourceCore(uri, {
     throw error;
   }
 
-  switch (uri) {
-    case "protocol/info": {
-      return { uri, data: await runProtocolInfo({ packageVersion }) };
-    }
-    case "project/tasks": {
-      const tasks = await discoverTasks(projectPath, packageRoot);
-      return {
-        uri,
-        data: {
-          count: tasks.length,
-          tasks: tasks.map((task) => ({
-            taskId: task.taskId,
-            healthy: task.healthy !== false,
-            phase: task.phase ?? null,
-            mutationAllowed: task.mutationAllowed !== false,
-          })),
-        },
-      };
-    }
-    case "task/status":
-    case "task/ownership":
-    case "task/contract":
-    case "task/continuity": {
-      if (typeof taskId !== "string" || !taskId) {
-        const error = new Error(`Resource ${uri} requires a taskId`);
-        error.code = "E_TASK_REQUIRED";
-        throw error;
-      }
-      break;
-    }
-    case "task/workspace-binding":
-    case "task/handoffs":
-    case "task/responsibility":
-    case "task/verification-scope":
-    case "task/attestation": {
-      if (typeof taskId !== "string" || !taskId) {
-        const error = new Error(`Resource ${uri} requires a taskId`);
-        error.code = "E_TASK_REQUIRED";
-        throw error;
-      }
-      break;
-    }
-    case "task/structural-quality": {
-      if (typeof taskId !== "string" || !taskId) {
-        const error = new Error(`Resource ${uri} requires a taskId`);
-        error.code = "E_TASK_REQUIRED";
-        throw error;
-      }
-      break;
-    }
-    case "task/actions":
-    case "task/action":
-    case "task/approvals":
-    case "task/metrics":
-    case "task/context":
-    case "task/evaluations": {
-      if (typeof taskId !== "string" || !taskId) {
-        const error = new Error(`Resource ${uri} requires a taskId`); error.code = "E_TASK_REQUIRED"; throw error;
-      }
-      break;
-    }
+  if (uri === "protocol/info") return { uri, data: await runProtocolInfo({ packageVersion }) };
+  if (uri === "project/tasks") {
+    const tasks = await discoverTaskSummaries(projectPath, packageRoot);
+    return { uri, data: { count: tasks.length, tasks } };
+  }
+  if (TASK_RESOURCE_URIS.has(uri) && (typeof taskId !== "string" || !taskId)) {
+    const error = new Error(`Resource ${uri} requires a taskId`);
+    error.code = "E_TASK_REQUIRED";
+    throw error;
   }
 
   if (uri === "task/ownership") {
@@ -198,27 +167,7 @@ async function readForgeLoopIntegrationResourceCore(uri, {
     return { uri, taskId, data: await resolveWorkspaceBindingStatus(projectPath, { packageRoot, taskId }) };
   }
   if (uri === "task/handoffs") {
-    const handoffs = await listCanonicalHandoffs(projectPath, { packageRoot, taskId });
-    const ledger = await readHandoffAcceptanceLedger(projectPath, packageRoot, { taskId });
-    const projectedHandoffs = handoffs.map((handoff) => {
-      const resolved = resolveHandoffAcceptance({
-        events: ledger.events,
-        handoff,
-        ledgerValid: ledger.valid,
-        ledgerErrors: ledger.errors,
-      });
-      return {
-        ...handoff,
-        acceptance: {
-          status: resolved.status,
-          consumerId: resolved.consumerId ?? null,
-          harness: resolved.harness ?? null,
-          acceptedAt: resolved.acceptedAt ?? null,
-          ...(resolved.reasonCodes ? { reasonCodes: [...resolved.reasonCodes] } : {}),
-        },
-      };
-    });
-    return { uri, taskId, data: { taskId, count: projectedHandoffs.length, handoffs: projectedHandoffs } };
+    return { uri, taskId, data: await runHandoffList({ target: projectPath, packageRoot, taskId }) };
   }
   if (uri === "task/responsibility") {
     return { uri, taskId, data: await resolveResponsibilityStatus(projectPath, { packageRoot, taskId }) };
@@ -263,13 +212,57 @@ async function readForgeLoopIntegrationResourceCore(uri, {
   }
   if (uri === "task/evaluations") {
     const dir = path.join(projectPath, taskDirectory(taskId), "evaluations");
-    let names = []; try { names = await readdir(dir); } catch { /* absent is an empty projection */ }
+    const names = await resourceArtifactNames(projectPath, taskId, "evaluations", dir);
     const evaluations = [];
     for (const name of names.filter((entry) => /^eval-[A-Za-z0-9_-]+\.json$/.test(entry)).sort()) {
       evaluations.push((await readJsonArtifact(projectPath, `${taskDirectory(taskId)}/evaluations/${name}`, "trajectory-evaluation", packageRoot)).value);
     }
     return { uri, taskId, data: { evaluations } };
   }
+  if (uri === "task/decisions") {
+    const store = getOperationalStore(projectPath);
+    if (store) {
+      const decisions = await readCapturedDecisions(store, taskId, packageRoot);
+      return { uri, taskId, data: { taskId, decisions } };
+    }
+    const dir = path.join(projectPath, taskDirectory(taskId), "decisions");
+    const names = await resourceArtifactNames(projectPath, taskId, "decisions", dir);
+    const decisions = [];
+    for (const name of names.filter((entry) => /^[A-Za-z0-9][A-Za-z0-9_-]{0,127}\.json$/.test(entry)).sort()) {
+      decisions.push((await readJsonArtifact(projectPath, `${taskDirectory(taskId)}/decisions/${name}`, "semantic-decision", packageRoot)).value);
+    }
+    return { uri, taskId, data: { taskId, decisions } };
+  }
+  if (uri === "task/context-plan") {
+    return { uri, taskId, data: await runContextPlan({ target: projectPath, packageRoot, taskId, profile: runtimeContext?.contextProfile ?? "balanced", readOnly: true }) };
+  }
+  if (uri === "task/model-route") {
+    const state = await readWorkState(projectPath, { packageRoot, taskId });
+    const route = await readPersistedRoute(projectPath, packageRoot, { taskId });
+    return {
+      uri,
+      taskId,
+      data: await runModelRoute({
+        target: projectPath,
+        packageRoot,
+        taskId,
+        workType: route.value.input?.workType,
+        surfaces: route.value.input?.surfaces,
+        risks: route.value.input?.risks,
+        platforms: route.value.input?.platforms,
+        behaviorChange: route.value.input?.behaviorChange,
+        executableChange: route.value.input?.executableChange,
+        generationRequired: route.value.input?.generationRequired,
+        architectureChange: route.value.input?.architectureChange,
+        ambiguity: route.value.input?.ambiguity,
+        contract: { phase: state.phase },
+      }),
+    };
+  }
+  if (uri === "task/test-utility") {
+    const artifact = await readTestUtility({ target: projectPath, packageRoot, taskId });
+    return { uri, taskId, data: artifact.value };
+  }
   if (uri === "project/capability-policy") {
     return { uri, data: await loadCapabilityPolicy(projectPath, packageRoot) };
   }
@@ -292,6 +285,35 @@ async function readForgeLoopIntegrationResourceCore(uri, {
 }
 
 export async function readForgeLoopIntegrationResource(uri, options = {}) {
+  const target = options.projectPath ?? ".";
+  const read = () => readSelectedIntegrationResource(uri, options);
+  // Decisions capture their finite catalog and bytes synchronously; other
+  // task projections retain the complete committed project snapshot.
+  return withProjectStorage(target, () => TASK_RESOURCE_URIS.has(uri) && uri !== "task/decisions"
+    ? withProjectReadSnapshot(target, read) : read(), { readOnly: true, runtimeContext: options.runtimeContext });
+}
+
+async function readSelectedIntegrationResource(uri, options) {
+  if (uri === "task/audit-view") {
+    if (typeof options.taskId !== "string" || !options.taskId) {
+      const error = new Error("Resource task/audit-view requires a taskId"); error.code = "E_TASK_REQUIRED"; throw error;
+    }
+    return {
+      uri,
+      taskId: options.taskId,
+      data: await buildAuditUxView({
+        target: options.projectPath ?? ".",
+        packageRoot: options.packageRoot,
+        taskId: options.taskId,
+        limit: options.limit,
+        beforeSequence: options.beforeSequence,
+        afterSequence: options.afterSequence,
+        categories: options.categories,
+        authorityContext: options.runtimeContext?.authorityContext,
+        runtimeContext: options.runtimeContext,
+      }),
+    };
+  }
   if (uri === "repository/index-status") {
     return {
       uri,
@@ -303,3 +325,13 @@ export async function readForgeLoopIntegrationResource(uri, options = {}) {
   }
   return readForgeLoopIntegrationResourceCore(uri, options);
 }
+
+
+async function readCapturedDecisions(store, taskId, packageRoot) {
+  const decisions = [];
+  for (const entry of store.captureDecisionTexts(taskId)) {
+    if (entry.error) throw entry.error;
+    decisions.push((await parseCapturedJsonArtifact(entry.text, entry.relativePath, "semantic-decision", packageRoot)).value);
+  }
+  return decisions;
+}

package/src/core/ledger-event-collection.js

@@ -0,0 +1,189 @@
+/**
+ * Explicit immutable-source event sequence. This is not an Array or a Proxy.
+ * Readers decode on demand; historical views share only source position identity.
+ * The source owner must hold one immutable snapshot for the sequence's lifetime.
+ * Array-returning filter/map operations deliberately materialize selected proofs;
+ * they do not establish bounded memory for arbitrarily large relation state.
+ */
+const collections = new WeakSet();
+const viewToken = Symbol("ledger-source-view");
+
+function sourceError(message) {
+  return Object.assign(new Error(message), { code: "E_LEDGER_SOURCE_INVALID" });
+}
+
+function integer(value) {
+  const number = Number(value);
+  return Number.isNaN(number) ? 0 : Math.trunc(number);
+}
+
+function bound(value, length) {
+  const index = integer(value);
+  return index < 0 ? Math.max(length + index, 0) : Math.min(index, length);
+}
+
+export class LedgerEventCollection {
+  #source;
+  #start;
+  #end;
+
+  constructor({ length, readAt, iterateRange = null, iterateTypes = null }, view = null, token = null) {
+    if (view) {
+      if (token !== viewToken) throw sourceError("Ledger views must come from their source collection");
+      this.#source = view.source;
+      this.#start = view.start;
+      this.#end = view.end;
+    } else {
+      if (!Number.isSafeInteger(length) || length < 0 || typeof readAt !== "function"
+        || (iterateRange !== null && typeof iterateRange !== "function")
+        || (iterateTypes !== null && typeof iterateTypes !== "function")) {
+        throw sourceError("Ledger source requires a finite length and synchronous readers");
+      }
+      this.#source = { length, readAt, iterateRange, iterateTypes, positions: new WeakMap() };
+      this.#start = 0;
+      this.#end = length;
+    }
+    collections.add(this);
+    Object.freeze(this);
+  }
+
+  get length() { return this.#end - this.#start; }
+
+  #observe(event, index) {
+    if (!event || typeof event !== "object" || Array.isArray(event)) {
+      throw sourceError("Ledger source returned a non-object event");
+    }
+    const known = this.#source.positions.get(event);
+    if (known !== undefined && known !== index) {
+      throw sourceError("Ledger source reused one event object at distinct positions");
+    }
+    this.#source.positions.set(event, index);
+    return event;
+  }
+
+  at(index) {
+    const position = integer(index);
+    const local = position < 0 ? this.length + position : position;
+    if (local < 0 || local >= this.length) return undefined;
+    const absolute = this.#start + local;
+    return this.#observe(this.#source.readAt(absolute), absolute);
+  }
+
+  *values() {
+    if (!this.#source.iterateRange) {
+      for (let index = 0; index < this.length; index += 1) yield this.at(index);
+      return;
+    }
+    let index = this.#start;
+    for (const event of this.#source.iterateRange(this.#start, this.#end)) {
+      if (index >= this.#end) throw sourceError("Ledger source exceeded its declared range");
+      yield this.#observe(event, index);
+      index += 1;
+    }
+    if (index !== this.#end) throw sourceError("Ledger source truncated its declared range");
+  }
+
+  [Symbol.iterator]() { return this.values(); }
+
+  *entries() {
+    let index = 0;
+    for (const event of this) { yield [index, event]; index += 1; }
+  }
+
+  *entriesOfTypes(types) {
+    const selected = new Set(types);
+    if (!this.#source.iterateTypes) {
+      for (const [index, event] of this.entries()) if (selected.has(event.event)) yield [index, event];
+      return;
+    }
+    let previous = this.#start - 1;
+    for (const { index, event } of this.#source.iterateTypes(this.#start, this.#end, [...selected])) {
+      if (!Number.isSafeInteger(index) || index <= previous || index < this.#start || index >= this.#end || !selected.has(event?.event)) {
+        throw sourceError("Ledger typed source returned an invalid position or event type");
+      }
+      previous = index;
+      yield [index - this.#start, this.#observe(event, index)];
+    }
+  }
+
+  slice(start = 0, end = this.length) {
+    const first = bound(start, this.length);
+    const last = Math.max(first, bound(end, this.length));
+    return new LedgerEventCollection({}, { source: this.#source, start: this.#start + first, end: this.#start + last }, viewToken);
+  }
+
+  indexOf(event) {
+    const absolute = event && typeof event === "object" ? this.#source.positions.get(event) : undefined;
+    return absolute === undefined || absolute < this.#start || absolute >= this.#end ? -1 : absolute - this.#start;
+  }
+
+  findIndex(predicate) {
+    for (const [index, event] of this.entries()) if (predicate(event, index, this)) return index;
+    return -1;
+  }
+
+  find(predicate) {
+    for (const [index, event] of this.entries()) if (predicate(event, index, this)) return event;
+    return undefined;
+  }
+
+  findLast(predicate) {
+    for (let index = this.length - 1; index >= 0; index -= 1) {
+      const event = this.at(index);
+      if (predicate(event, index, this)) return event;
+    }
+    return undefined;
+  }
+
+  some(predicate) { return this.findIndex(predicate) !== -1; }
+  every(predicate) { return this.findIndex((event, index) => !predicate(event, index, this)) === -1; }
+
+  filter(predicate) {
+    const selected = [];
+    for (const [index, event] of this.entries()) if (predicate(event, index, this)) selected.push(event);
+    return selected;
+  }
+
+  map(project) {
+    const values = [];
+    for (const [index, event] of this.entries()) values.push(project(event, index, this));
+    return values;
+  }
+}
+
+export function isLedgerEventCollection(events) {
+  return Array.isArray(events) || collections.has(events);
+}
+
+export function ledgerEventAt(events, index) {
+  return Array.isArray(events) ? events[index] : (Number.isSafeInteger(index) && index >= 0 ? events.at(index) : undefined);
+}
+
+/** Preserve strict Array identity; decoded collections prove private source position. */
+export function ledgerEventAtIs(events, index, event) {
+  if (Array.isArray(events)) return events[index] === event;
+  return Number.isSafeInteger(index) && index >= 0 && index < events.length && events.indexOf(event) === index;
+}
+
+/** Typed selection preserves canonical source positions without retaining selected payload arrays. */
+export function* ledgerEntriesOfTypes(events, types) {
+  if (!Array.isArray(events)) { yield* events.entriesOfTypes(types); return; }
+  const selected = new Set(types);
+  for (const [index, event] of events.entries()) if (selected.has(event.event)) yield [index, event];
+}
+
+export function* ledgerEventsOfTypes(events, types) {
+  for (const [, event] of ledgerEntriesOfTypes(events, types)) yield event;
+}
+
+export function ledgerTypeSummary(events, type) {
+  let count = 0;
+  let first;
+  let latest;
+  for (const event of ledgerEventsOfTypes(events, [type])) {
+    if (!count) first = event;
+    latest = event;
+    count += 1;
+  }
+  return { count, first, latest };
+}

package/src/core/ledger-relations.js

@@ -0,0 +1,23 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+
+const owners = new AsyncLocalStorage();
+
+/** Storage supplies an owned scratch backing; pure/array callers retain native collections. */
+export function withLedgerRelationOwner(owner, callback) { return owners.run(owner, callback); }
+export function ledgerRelationMap() { return owners.getStore()?.map() ?? new Map(); }
+export function ledgerRelationSet() { return owners.getStore()?.set() ?? new Set(); }
+
+
+/** Primitive grouped membership; storage may index groups without nested resident Sets. */
+export function ledgerGroupedSet() {
+  const owner = owners.getStore();
+  if (owner?.groupedSet) return owner.groupedSet();
+  const groups = new Map();
+  return {
+    add(group, value) {
+      if (!groups.has(group)) groups.set(group, new Set());
+      groups.get(group).add(value);
+    },
+    *values(group) { yield* groups.get(group) ?? []; },
+  };
+}

package/src/core/model-router/constants.js

@@ -0,0 +1,10 @@
+import { DECISION_AUTHORITY, DECISION_EVIDENCE_AUTHORITY, PINNED_JEV_MODEL } from "../decision/constants.js";
+
+export const MODEL_ROUTE_TIERS = Object.freeze(["NONE", "FAST", "STANDARD", "PRIMARY"]);
+export const MODEL_ROUTE_POLICY_VERSION = 1;
+export const MODEL_ROUTE_PROJECTION_AUTHORITY = DECISION_AUTHORITY;
+export const MODEL_ROUTE_PROJECTION_EVIDENCE_AUTHORITY = DECISION_EVIDENCE_AUTHORITY;
+export const MODEL_ROUTE_JEV_MODEL = PINNED_JEV_MODEL;
+
+export const MODEL_ROUTE_RANK = Object.freeze({ NONE: 0, FAST: 1, STANDARD: 2, PRIMARY: 3 });
+

package/src/core/model-router/policy.js

@@ -0,0 +1,103 @@
+import { MODEL_ROUTE_RANK, MODEL_ROUTE_TIERS } from "./constants.js";
+
+const GENERATION_WORK_TYPES = new Set([
+  "code", "bug", "refactor", "backend", "api", "infrastructure", "security-review", "release",
+]);
+const PRIMARY_WORK_TYPES = new Set(["infrastructure", "security-review", "release"]);
+const PRIMARY_RISKS = new Set(["secrets", "personal-data", "publication", "critical-path", "destructive", "irreversible", "migration", "credentials", "payment"]);
+const PRIMARY_SURFACES = new Set(["auth", "critical-path", "database"]);
+
+function text(value) {
+  return typeof value === "string" ? value.toLowerCase() : "";
+}
+
+function array(value) {
+  return Array.isArray(value) ? value.filter((item) => typeof item === "string") : [];
+}
+
+function contractText(contract) {
+  if (!contract || typeof contract !== "object" || Array.isArray(contract)) return "";
+  const values = [contract.objective, contract.summary, ...(contract.deliverables ?? []), ...(contract.successCriteria ?? []), ...(contract.risks ?? []), ...(contract.constraints ?? [])];
+  return values.map((value) => value && typeof value === "object" ? value.text : value).filter((value) => typeof value === "string").join(" ").toLowerCase();
+}
+
+function normalizedInput(input = {}) {
+  return {
+    workType: text(input.workType),
+    surfaces: array(input.surfaces).map(text),
+    risks: array(input.risks).map(text),
+    platforms: array(input.platforms).map(text),
+    behaviorChange: input.behaviorChange === true,
+    executableChange: input.executableChange === true,
+    generationRequired: input.generationRequired === true,
+    architectureChange: input.architectureChange === true,
+    ambiguity: input.ambiguity === true,
+    contract: input.contract,
+  };
+}
+
+function deterministicFloor(input) {
+  const normalized = normalizedInput(input);
+  const reasons = [];
+  const combined = `${contractText(normalized.contract)} ${normalized.workType} ${normalized.surfaces.join(" ")} ${normalized.risks.join(" ")}`;
+  const generationRequired = normalized.generationRequired
+    || normalized.behaviorChange
+    || normalized.executableChange
+    || GENERATION_WORK_TYPES.has(normalized.workType)
+    || /\b(implement|fix|refactor|change|build|generate|write|modify|code)\b/.test(combined);
+  const primary = normalized.architectureChange
+    || normalized.ambiguity
+    || PRIMARY_WORK_TYPES.has(normalized.workType)
+    || normalized.risks.some((risk) => PRIMARY_RISKS.has(risk))
+    || normalized.surfaces.some((surface) => PRIMARY_SURFACES.has(surface))
+    || /\b(architecture|architectural|security boundary|migration|ambiguous|unknown requirements)\b/.test(combined);
+
+  if (!generationRequired) {
+    reasons.push("NO_GENERATION_REQUIRED");
+    return { floor: "NONE", reasons };
+  }
+  reasons.push("GENERATION_REQUIRED");
+  if (primary) {
+    reasons.push("PRIMARY_COMPLEXITY_OR_RISK");
+    return { floor: "PRIMARY", reasons };
+  }
+  reasons.push("STANDARD_GENERATION_FLOOR");
+  return { floor: "STANDARD", reasons };
+}
+
+function normalizeRecommendation(recommendation) {
+  if (recommendation === null || recommendation === undefined) return null;
+  if (typeof recommendation === "string") {
+    return MODEL_ROUTE_TIERS.includes(recommendation) ? { tier: recommendation, confidence: null, requiresEscalation: false } : null;
+  }
+  if (!recommendation || typeof recommendation !== "object" || Array.isArray(recommendation)) return null;
+  const tier = typeof recommendation.tier === "string" && MODEL_ROUTE_TIERS.includes(recommendation.tier) ? recommendation.tier : null;
+  if (!tier) return null;
+  return {
+    tier,
+    confidence: typeof recommendation.confidence === "number" && Number.isFinite(recommendation.confidence) ? recommendation.confidence : null,
+    requiresEscalation: recommendation.requiresEscalation === true,
+  };
+}
+
+export function resolveModelRoute({ input = {}, semanticRecommendation = null } = {}) {
+  const deterministic = deterministicFloor(input);
+  const recommendation = normalizeRecommendation(semanticRecommendation);
+  let resolved = deterministic.floor;
+  const reasons = [...deterministic.reasons];
+  if (recommendation?.requiresEscalation) {
+    if (MODEL_ROUTE_RANK[resolved] < MODEL_ROUTE_RANK.PRIMARY) resolved = "PRIMARY";
+    reasons.push("JEV_LOW_CONFIDENCE_ESCALATION");
+  } else if (recommendation && MODEL_ROUTE_RANK[recommendation.tier] > MODEL_ROUTE_RANK[resolved]) {
+    resolved = recommendation.tier;
+    reasons.push("JEV_ESCALATION_ONLY");
+  }
+  return {
+    floor: deterministic.floor,
+    resolved,
+    reasons: [...new Set(reasons)],
+    semanticRecommendation: recommendation,
+    generationRequired: deterministic.floor !== "NONE",
+  };
+}
+

package/src/core/model-router/router.js

@@ -0,0 +1,37 @@
+import {
+  MODEL_ROUTE_JEV_MODEL,
+  MODEL_ROUTE_POLICY_VERSION,
+  MODEL_ROUTE_PROJECTION_AUTHORITY,
+  MODEL_ROUTE_PROJECTION_EVIDENCE_AUTHORITY,
+  MODEL_ROUTE_RANK,
+  MODEL_ROUTE_TIERS,
+} from "./constants.js";
+import { resolveModelRoute } from "./policy.js";
+
+export function projectModelRoute({ input = {}, semanticRecommendation = null } = {}) {
+  const route = resolveModelRoute({ input, semanticRecommendation });
+  if (!MODEL_ROUTE_TIERS.includes(route.floor) || !MODEL_ROUTE_TIERS.includes(route.resolved)
+    || MODEL_ROUTE_RANK[route.resolved] < MODEL_ROUTE_RANK[route.floor]) {
+    const error = new Error("Model route violates its deterministic safety floor.");
+    error.code = "E_MODEL_ROUTE_SAFETY_FLOOR_INVALID";
+    throw error;
+  }
+  return {
+    schemaVersion: 1,
+    policyVersion: MODEL_ROUTE_POLICY_VERSION,
+    engine: "typesafe-jev",
+    model: MODEL_ROUTE_JEV_MODEL,
+    floor: route.floor,
+    resolved: route.resolved,
+    reasons: route.reasons,
+    generationRequired: route.generationRequired,
+    semanticRecommendation: route.semanticRecommendation,
+    authority: MODEL_ROUTE_PROJECTION_AUTHORITY,
+    evidenceAuthority: MODEL_ROUTE_PROJECTION_EVIDENCE_AUTHORITY,
+    lifecycleAuthority: false,
+    completionAuthority: false,
+    ownershipAuthority: false,
+    installationAuthority: false,
+  };
+}
+

package/src/core/native-storage.js

@@ -0,0 +1,12 @@
+import { needsExistingProjectScope, withExistingProjectScope } from "../storage/existing-project-scope.js";
+import { getOperationalStore } from "../storage/operational-context.js";
+
+export async function withNativeReadScope(target, callback) {
+  return (await needsExistingProjectScope(target)) ? withExistingProjectScope(target, callback, { readOnly: true }) : callback();
+}
+
+export function requireNativeStore(target, errorFactory, refusalMessage) {
+  const store = getOperationalStore(target);
+  if (!store) throw errorFactory("E_STORAGE_MIGRATION_REQUIRED", refusalMessage);
+  return store;
+}