chainlesschain 0.166.44 → 0.166.45

package/src/lib/evolution/evolution-deployment-profile.js

@@ -1,5 +1,11 @@
 import { randomUUID } from "node:crypto";
-import { readFile, rename, unlink, writeFile } from "node:fs/promises";
+import { readFile } from "node:fs/promises";
+import {
+  readFileSync,
+  renameSync,
+  unlinkSync,
+  writeFileSync,
+} from "node:fs";
 import { dirname, isAbsolute, join } from "node:path";
 import { resolveConfigDataRoot } from "../paths.js";
 import {
@@ -7,9 +13,19 @@ import {
   ensurePrivateDirectory,
   ensurePrivateFile,
 } from "../secure-fs.js";
+import { withFileLock } from "../with-file-lock.js";
 
 export const EVOLUTION_DEPLOYMENT_PROFILE_SCHEMA =
+  "chainlesschain.evolution-deployment-profile/v4";
+
+const LEGACY_EVOLUTION_DEPLOYMENT_PROFILE_SCHEMA =
   "chainlesschain.evolution-deployment-profile/v1";
+const PREVIOUS_EVOLUTION_DEPLOYMENT_PROFILE_SCHEMA =
+  "chainlesschain.evolution-deployment-profile/v2";
+const PRIOR_EVOLUTION_DEPLOYMENT_PROFILE_SCHEMA =
+  "chainlesschain.evolution-deployment-profile/v3";
+const DIGEST = /^sha256:[a-f0-9]{64}$/u;
+const MAX_TRUST_ROOT_REVISION_FLOORS = 64;
 
 export function getEvolutionDeploymentProfilePath({
   env = process.env,
@@ -26,10 +42,48 @@ function normalizeProfile(value) {
   if (!value || typeof value !== "object" || Array.isArray(value))
     throw new TypeError("evolution deployment profile must be an object");
   const keys = Object.keys(value).sort();
-  const expected = ["descriptorPath", "enabled", "schema", "trustRootPath"];
+  const legacy = [
+    LEGACY_EVOLUTION_DEPLOYMENT_PROFILE_SCHEMA,
+    PREVIOUS_EVOLUTION_DEPLOYMENT_PROFILE_SCHEMA,
+    PRIOR_EVOLUTION_DEPLOYMENT_PROFILE_SCHEMA,
+  ].includes(value.schema);
+  const expected =
+    value.schema === LEGACY_EVOLUTION_DEPLOYMENT_PROFILE_SCHEMA
+      ? ["descriptorPath", "enabled", "schema", "trustRootPath"]
+      : value.schema === PREVIOUS_EVOLUTION_DEPLOYMENT_PROFILE_SCHEMA
+        ? [
+            "descriptorPath",
+            "enabled",
+            "revisionFloors",
+            "schema",
+            "trustRootPath",
+          ]
+      : value.schema === PRIOR_EVOLUTION_DEPLOYMENT_PROFILE_SCHEMA
+        ? [
+            "activeTrustRootDigest",
+            "descriptorPath",
+            "enabled",
+            "revisionFloors",
+            "schema",
+            "trustRootPath",
+          ]
+        : [
+            "activeTrustRootDigest",
+            "descriptorPath",
+            "enabled",
+            "revisionFloors",
+            "revokedDescriptorRevisions",
+            "schema",
+            "trustRootPath",
+          ];
   if (JSON.stringify(keys) !== JSON.stringify(expected.sort()))
     throw new TypeError("evolution deployment profile has unexpected fields");
-  if (value.schema !== EVOLUTION_DEPLOYMENT_PROFILE_SCHEMA)
+  if (
+    value.schema !== EVOLUTION_DEPLOYMENT_PROFILE_SCHEMA &&
+    value.schema !== LEGACY_EVOLUTION_DEPLOYMENT_PROFILE_SCHEMA &&
+    value.schema !== PREVIOUS_EVOLUTION_DEPLOYMENT_PROFILE_SCHEMA &&
+    value.schema !== PRIOR_EVOLUTION_DEPLOYMENT_PROFILE_SCHEMA
+  )
     throw new TypeError("evolution deployment profile schema is invalid");
   if (typeof value.enabled !== "boolean")
     throw new TypeError("evolution deployment profile enabled is invalid");
@@ -42,73 +96,263 @@ function normalizeProfile(value) {
         `evolution deployment profile ${name} must be absolute`,
       );
   }
+  const revisionFloors =
+    value.schema === LEGACY_EVOLUTION_DEPLOYMENT_PROFILE_SCHEMA
+      ? {}
+      : normalizeRevisionFloors(value.revisionFloors);
+  const activeTrustRootDigest = legacy
+    ? null
+    : normalizeTrustRootDigest(value.activeTrustRootDigest);
+  const revokedDescriptorRevisions =
+    value.schema === EVOLUTION_DEPLOYMENT_PROFILE_SCHEMA
+      ? normalizeRevokedDescriptorRevisions(value.revokedDescriptorRevisions)
+      : {};
   return Object.freeze({
-    schema: value.schema,
+    schema: EVOLUTION_DEPLOYMENT_PROFILE_SCHEMA,
     enabled: value.enabled,
     descriptorPath: value.descriptorPath,
     trustRootPath: value.trustRootPath,
+    revisionFloors,
+    activeTrustRootDigest,
+    revokedDescriptorRevisions,
   });
 }
 
-export async function readEvolutionDeploymentProfile(options = {}) {
-  const filePath =
-    options.filePath || getEvolutionDeploymentProfilePath(options);
-  try {
-    const profile = normalizeProfile(
-      JSON.parse(await readFile(filePath, "utf8")),
+function normalizeRevokedDescriptorRevisions(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value))
+    throw new TypeError(
+      "evolution deployment profile revokedDescriptorRevisions is invalid",
     );
-    return Object.freeze({ filePath, profile, error: null });
+  const result = {};
+  for (const [trustRootDigest, revisions] of Object.entries(value)) {
+    if (!DIGEST.test(trustRootDigest) || !Array.isArray(revisions))
+      throw new TypeError(
+        "evolution deployment profile revokedDescriptorRevisions is invalid",
+      );
+    const normalized = [...revisions].sort((left, right) => left - right);
+    if (
+      normalized.length > 1024 ||
+      normalized.some(
+        (revision) => !Number.isSafeInteger(revision) || revision < 1,
+      ) ||
+      new Set(normalized).size !== normalized.length
+    ) {
+      throw new TypeError(
+        "evolution deployment profile revokedDescriptorRevisions is invalid",
+      );
+    }
+    result[trustRootDigest] = Object.freeze(normalized);
+  }
+  return Object.freeze(result);
+}
+
+function normalizeTrustRootDigest(value) {
+  if (!DIGEST.test(value || ""))
+    throw new TypeError(
+      "evolution deployment profile activeTrustRootDigest is invalid",
+    );
+  return value;
+}
+
+function normalizeRevisionFloors(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value))
+    throw new TypeError("evolution deployment profile revisionFloors is invalid");
+  const entries = Object.entries(value).sort(([left], [right]) =>
+    left.localeCompare(right),
+  );
+  if (entries.length > MAX_TRUST_ROOT_REVISION_FLOORS)
+    throw new TypeError("evolution deployment profile revisionFloors is too large");
+  for (const [trustRootDigest, revision] of entries) {
+    if (!DIGEST.test(trustRootDigest))
+      throw new TypeError(
+        "evolution deployment profile revisionFloors trust root is invalid",
+      );
+    if (!Number.isSafeInteger(revision) || revision < 1)
+      throw new TypeError(
+        "evolution deployment profile revisionFloors revision is invalid",
+      );
+  }
+  return Object.freeze(Object.fromEntries(entries));
+}
+
+function profilePath(options = {}) {
+  return options.filePath || getEvolutionDeploymentProfilePath(options);
+}
+
+function readProfileSync(filePath) {
+  try {
+    return {
+      profile: normalizeProfile(JSON.parse(readFileSync(filePath, "utf8"))),
+      error: null,
+    };
   } catch (error) {
-    if (error?.code === "ENOENT")
-      return Object.freeze({ filePath, profile: null, error: null });
-    return Object.freeze({
-      filePath,
+    if (error?.code === "ENOENT") return { profile: null, error: null };
+    return {
       profile: null,
       error: error instanceof Error ? error.message : String(error),
-    });
+    };
   }
 }
 
-export async function writeEvolutionDeploymentProfile(input, options = {}) {
-  const profile = normalizeProfile({
-    schema: EVOLUTION_DEPLOYMENT_PROFILE_SCHEMA,
-    enabled: input?.enabled === true,
-    descriptorPath: input?.descriptorPath,
-    trustRootPath: input?.trustRootPath,
-  });
-  const filePath =
-    options.filePath || getEvolutionDeploymentProfilePath(options);
+function writeProfileSync(profile, filePath) {
   ensurePrivateDirectory(dirname(filePath));
   const temporaryPath = join(
     dirname(filePath),
     `.deployment-profile.${randomUUID()}.tmp`,
   );
   try {
-    await writeFile(temporaryPath, `${JSON.stringify(profile, null, 2)}\n`, {
+    writeFileSync(temporaryPath, `${JSON.stringify(profile, null, 2)}\n`, {
       encoding: "utf8",
       mode: PRIVATE_FILE_MODE,
       flag: "wx",
     });
     ensurePrivateFile(temporaryPath);
-    await rename(temporaryPath, filePath);
+    renameSync(temporaryPath, filePath);
     ensurePrivateFile(filePath);
   } catch (error) {
-    await unlink(temporaryPath).catch(() => {});
+    try {
+      unlinkSync(temporaryPath);
+    } catch {
+      // The temporary path either was not created or has already been renamed.
+    }
     throw error;
   }
-  return Object.freeze({ filePath, profile });
+}
+
+function profileFromInput(input) {
+  return normalizeProfile({
+    schema: EVOLUTION_DEPLOYMENT_PROFILE_SCHEMA,
+    enabled: input?.enabled === true,
+    descriptorPath: input?.descriptorPath,
+    trustRootPath: input?.trustRootPath,
+    revisionFloors: input?.revisionFloors || {},
+    activeTrustRootDigest: input?.activeTrustRootDigest,
+    revokedDescriptorRevisions: input?.revokedDescriptorRevisions || {},
+  });
+}
+
+export async function readEvolutionDeploymentProfile(options = {}) {
+  const filePath = profilePath(options);
+  try {
+    const profile = normalizeProfile(
+      JSON.parse(await readFile(filePath, "utf8")),
+    );
+    return Object.freeze({ filePath, profile, error: null });
+  } catch (error) {
+    if (error?.code === "ENOENT")
+      return Object.freeze({ filePath, profile: null, error: null });
+    return Object.freeze({
+      filePath,
+      profile: null,
+      error: error instanceof Error ? error.message : String(error),
+    });
+  }
+}
+
+export async function writeEvolutionDeploymentProfile(input, options = {}) {
+  const proposed = profileFromInput(input);
+  return updateEvolutionDeploymentProfile((current) => ({
+    ...proposed,
+    // This lower-level writer cannot authenticate a descriptor, so it never
+    // lowers or erases a floor established by configureEvolutionDeployment().
+    revisionFloors: Object.fromEntries(
+      Object.keys({
+        ...(current?.revisionFloors || {}),
+        ...proposed.revisionFloors,
+      }).map((trustRootDigest) => [
+        trustRootDigest,
+        Math.max(
+          current?.revisionFloors?.[trustRootDigest] || 0,
+          proposed.revisionFloors[trustRootDigest] || 0,
+        ),
+      ]),
+    ),
+    activeTrustRootDigest:
+      proposed.activeTrustRootDigest || current?.activeTrustRootDigest,
+    revokedDescriptorRevisions: {
+      ...(current?.revokedDescriptorRevisions || {}),
+      ...(proposed.revokedDescriptorRevisions || {}),
+    },
+  }), options);
+}
+
+/**
+ * Atomically read, validate and replace the owner-only profile. The callback is
+ * synchronous by design: `withFileLock` is a cross-process lock and releasing
+ * it while an async callback is pending would reintroduce lost high-water
+ * updates.
+ */
+export function updateEvolutionDeploymentProfile(update, options = {}) {
+  if (typeof update !== "function")
+    throw new TypeError(
+      "evolution deployment profile update must be a function",
+    );
+  const filePath = profilePath(options);
+  ensurePrivateDirectory(dirname(filePath));
+  return withFileLock(
+    filePath,
+    () => {
+      const current = readProfileSync(filePath);
+      if (current.error) throw new Error(current.error);
+      const profile = profileFromInput(update(current.profile));
+      writeProfileSync(profile, filePath);
+      return Object.freeze({ filePath, profile });
+    },
+    { failIfUnavailable: true },
+  );
+}
+
+export function assertEvolutionDeploymentRevisionFloor(profile, descriptor) {
+  const floor = profile?.revisionFloors?.[descriptor?.trustRootDigest];
+  if (floor === undefined) return null;
+  if (
+    !Number.isSafeInteger(descriptor?.revision) ||
+    descriptor.revision < floor
+  ) {
+    const error = new Error(
+      `evolution deployment descriptor revision rollback rejected: received ${descriptor?.revision}, floor ${floor}`,
+    );
+    error.code = "EVOLUTION_DEPLOYMENT_REVISION_ROLLBACK";
+    throw error;
+  }
+  return floor;
+}
+
+export function assertEvolutionDeploymentActiveTrustRoot(profile, descriptor) {
+  const activeTrustRootDigest = profile?.activeTrustRootDigest;
+  if (!activeTrustRootDigest) return null;
+  if (descriptor?.trustRootDigest !== activeTrustRootDigest) {
+    const error = new Error(
+      "evolution deployment descriptor trust root does not match the active profile root",
+    );
+    error.code = "EVOLUTION_DEPLOYMENT_TRUST_ROOT_MISMATCH";
+    throw error;
+  }
+  return activeTrustRootDigest;
+}
+
+export function assertEvolutionDeploymentDescriptorNotRevoked(
+  profile,
+  descriptor,
+) {
+  const revoked = profile?.revokedDescriptorRevisions?.[
+    descriptor?.trustRootDigest
+  ];
+  if (!revoked?.includes(descriptor?.revision)) return;
+  const error = new Error(
+    `evolution deployment descriptor revision ${descriptor.revision} is revoked`,
+  );
+  error.code = "EVOLUTION_DEPLOYMENT_DESCRIPTOR_REVOKED";
+  throw error;
 }
 
 export async function setEvolutionDeploymentProfileEnabled(
   enabled,
   options = {},
 ) {
-  const current = await readEvolutionDeploymentProfile(options);
-  if (current.error) throw new Error(current.error);
-  if (!current.profile)
-    throw new Error("evolution deployment profile is not configured");
-  return writeEvolutionDeploymentProfile(
-    { ...current.profile, enabled: enabled === true },
-    { ...options, filePath: current.filePath },
-  );
+  return updateEvolutionDeploymentProfile((current) => {
+    if (!current)
+      throw new Error("evolution deployment profile is not configured");
+    return { ...current, enabled: enabled === true };
+  }, options);
 }

package/src/lib/evolution/evolution-deployment-root-rotation.js

@@ -0,0 +1,154 @@
+import { createHash, createPublicKey, verify } from "node:crypto";
+import { readFileSync } from "node:fs";
+import { isAbsolute } from "node:path";
+
+export const EVOLUTION_DEPLOYMENT_ROOT_ROTATION_SCHEMA =
+  "chainlesschain.evolution-deployment-root-rotation/v1";
+
+const DIGEST = /^sha256:[a-f0-9]{64}$/u;
+const MAX_ROTATION_BYTES = 64 * 1024;
+
+function canonical(value) {
+  if (value === null || typeof value !== "object") return JSON.stringify(value);
+  if (Array.isArray(value)) return `[${value.map(canonical).join(",")}]`;
+  return `{${Object.keys(value)
+    .sort()
+    .map((key) => `${JSON.stringify(key)}:${canonical(value[key])}`)
+    .join(",")}}`;
+}
+
+function digest(bytes) {
+  return `sha256:${createHash("sha256").update(bytes).digest("hex")}`;
+}
+
+function normalizeRotation(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value))
+    throw new TypeError("evolution deployment root rotation must be an object");
+  const expected = [
+    "fromTrustRootDigest",
+    "minimumDescriptorRevision",
+    "schema",
+    "signature",
+    "toTrustRootDigest",
+  ];
+  if (canonical(Object.keys(value).sort()) !== canonical(expected))
+    throw new TypeError(
+      "evolution deployment root rotation has unexpected or missing fields",
+    );
+  if (value.schema !== EVOLUTION_DEPLOYMENT_ROOT_ROTATION_SCHEMA)
+    throw new TypeError("evolution deployment root rotation schema is invalid");
+  for (const key of ["fromTrustRootDigest", "toTrustRootDigest"]) {
+    if (!DIGEST.test(value[key] || ""))
+      throw new TypeError(`evolution deployment root rotation ${key} is invalid`);
+  }
+  if (value.fromTrustRootDigest === value.toTrustRootDigest)
+    throw new TypeError("evolution deployment root rotation must change trust root");
+  if (
+    !Number.isSafeInteger(value.minimumDescriptorRevision) ||
+    value.minimumDescriptorRevision < 1
+  ) {
+    throw new TypeError(
+      "evolution deployment root rotation minimumDescriptorRevision is invalid",
+    );
+  }
+  if (
+    typeof value.signature !== "string" ||
+    !/^[A-Za-z0-9+/]+={0,2}$/u.test(value.signature) ||
+    value.signature.length === 0
+  ) {
+    throw new TypeError("evolution deployment root rotation signature is invalid");
+  }
+  return Object.freeze({ ...value });
+}
+
+export function serializeEvolutionDeploymentRootRotationPayload(rotation) {
+  const value = normalizeRotation({ ...rotation, signature: "AA==" });
+  return canonical({
+    schema: value.schema,
+    fromTrustRootDigest: value.fromTrustRootDigest,
+    toTrustRootDigest: value.toTrustRootDigest,
+    minimumDescriptorRevision: value.minimumDescriptorRevision,
+  });
+}
+
+/**
+ * Verify a root transition while the profile lock is held. The old root is
+ * authenticated by its exact bytes before it may authorize a new root.
+ */
+export function verifyEvolutionDeploymentRootRotationSync({
+  rotationPath,
+  fromTrustRootPath,
+  expectedFromTrustRootDigest,
+  expectedToTrustRootDigest,
+  destinationRevision,
+}) {
+  if (
+    typeof rotationPath !== "string" ||
+    !isAbsolute(rotationPath) ||
+    typeof fromTrustRootPath !== "string" ||
+    !isAbsolute(fromTrustRootPath)
+  ) {
+    throw new Error("evolution deployment root rotation paths must be absolute");
+  }
+  if (!DIGEST.test(expectedFromTrustRootDigest || ""))
+    throw new Error("evolution deployment root rotation source digest is invalid");
+  if (!DIGEST.test(expectedToTrustRootDigest || ""))
+    throw new Error("evolution deployment root rotation destination digest is invalid");
+  if (!Number.isSafeInteger(destinationRevision) || destinationRevision < 1)
+    throw new Error("evolution deployment root rotation destination revision is invalid");
+
+  let rotation;
+  let fromTrustRootBytes;
+  try {
+    const rotationBytes = readFileSync(rotationPath);
+    if (
+      rotationBytes.byteLength === 0 ||
+      rotationBytes.byteLength > MAX_ROTATION_BYTES
+    ) {
+      throw new Error("evolution deployment root rotation size is invalid");
+    }
+    rotation = normalizeRotation(JSON.parse(rotationBytes.toString("utf8")));
+    fromTrustRootBytes = readFileSync(fromTrustRootPath);
+  } catch (error) {
+    throw new Error(
+      "evolution deployment root rotation could not be read",
+      error instanceof Error ? { cause: error } : undefined,
+    );
+  }
+  if (digest(fromTrustRootBytes) !== expectedFromTrustRootDigest)
+    throw new Error(
+      "evolution deployment root rotation source trust root changed",
+    );
+  if (rotation.fromTrustRootDigest !== expectedFromTrustRootDigest)
+    throw new Error(
+      "evolution deployment root rotation source does not match profile",
+    );
+  if (rotation.toTrustRootDigest !== expectedToTrustRootDigest)
+    throw new Error(
+      "evolution deployment root rotation destination does not match descriptor",
+    );
+  if (destinationRevision < rotation.minimumDescriptorRevision)
+    throw new Error(
+      "evolution deployment root rotation destination revision is below the authorized minimum",
+    );
+  let publicKey;
+  try {
+    publicKey = createPublicKey(fromTrustRootBytes);
+  } catch {
+    throw new Error("evolution deployment root rotation source trust root is invalid");
+  }
+  if (
+    !verify(
+      null,
+      Buffer.from(
+        serializeEvolutionDeploymentRootRotationPayload(rotation),
+        "utf8",
+      ),
+      publicKey,
+      Buffer.from(rotation.signature, "base64"),
+    )
+  ) {
+    throw new Error("evolution deployment root rotation signature rejected");
+  }
+  return rotation;
+}

package/src/lib/evolution/governed-hub-llm.js

@@ -1,8 +1,13 @@
+import { createRequire } from "node:module";
 import { prepareGovernedModelTurn } from "./governed-model-turn.js";
 
+const { createAuthenticatedEvolutionModelClient } = createRequire(
+  import.meta.url,
+)("@chainlesschain/personal-data-hub/model-egress-guard");
+
 // A scoped wrapper preserves the Hub's independent local/cloud consent check.
 // Never replace llm on the process-wide cached Hub or its analysis engine.
-export function createGovernedHubLlm(llm, factory) {
+export function createGovernedHubLlm(llm, factory, options = {}) {
   if (
     !llm ||
     typeof llm.chat !== "function" ||
@@ -14,6 +19,8 @@ export function createGovernedHubLlm(llm, factory) {
   }
   if (typeof factory !== "function")
     throw new TypeError("A Hub evolution factory is required");
+  if (options.onFailure != null && typeof options.onFailure !== "function")
+    throw new TypeError("onFailure must be a function");
   const identity = { name: llm.name, isLocal: llm.isLocal, chat: llm.chat };
   const assertIdentity = () => {
     if (
@@ -27,30 +34,29 @@ export function createGovernedHubLlm(llm, factory) {
     }
   };
   const chat = identity.chat.bind(llm);
-  return Object.freeze({
-    get name() {
+  return createAuthenticatedEvolutionModelClient({
+    getName() {
       assertIdentity();
       return identity.name;
     },
-    get isLocal() {
+    getIsLocal() {
       assertIdentity();
       return identity.isLocal;
     },
-    async chat(messages, options = {}) {
+    async prepare(messages, chatOptions = {}) {
       assertIdentity();
-      const turn = await prepareGovernedModelTurn(factory, {
+      return await prepareGovernedModelTurn(factory, {
         mode: "hub-analysis",
         messages,
-        signal: options.signal,
+        signal: chatOptions.signal,
       });
+    },
+    async transport(messages, chatOptions = {}) {
       assertIdentity();
-      const response = await chat(turn.messages, options);
+      const response = await chat(messages, chatOptions);
       assertIdentity();
-      if (!response || typeof response.text !== "string") {
-        throw new Error("Hub model response must contain text");
-      }
-      await turn.complete(response.text);
       return response;
     },
+    onFailure: options.onFailure,
   });
 }

package/src/lib/evolution/governed-hub-skill.js

@@ -9,25 +9,12 @@ export async function runGovernedHubSkill(
   name,
   options,
 ) {
-  const model = createGovernedHubLlm(hub.llm, factory);
   let failure;
   let failed = false;
-  const llm = Object.freeze({
-    get name() {
-      return model.name;
-    },
-    get isLocal() {
-      return model.isLocal;
-    },
-    async chat(messages, chatOptions) {
-      if (failed) throw failure;
-      try {
-        return await model.chat(messages, chatOptions);
-      } catch (error) {
-        failure = error;
-        failed = true;
-        throw error;
-      }
+  const llm = createGovernedHubLlm(hub.llm, factory, {
+    onFailure(error) {
+      failure = error;
+      failed = true;
     },
   });
   const result = await runSkill({ vault: hub.vault, llm }, name, options);

package/src/lib/evolution/governed-model-turn.js

@@ -34,14 +34,13 @@ export async function prepareGovernedModelTurn(
   { mode, messages, signal },
 ) {
   signal?.throwIfAborted();
-  if (factory === null)
-    return {
-      governed: false,
-      messages,
-      complete: async () => {
-        signal?.throwIfAborted();
-      },
-    };
+  if (factory === null) {
+    const error = new Error(
+      "Model egress requires an authenticated evolution composition factory",
+    );
+    error.code = "CC_AGENT_EVOLUTION_INGRESS_FAILED";
+    throw error;
+  }
   if (typeof factory !== "function")
     throw new TypeError("Invalid evolution composition factory");
   const runId = `${mode}-${randomUUID()}`;

package/src/lib/orchestrator.js

@@ -153,7 +153,9 @@ export class Orchestrator extends EventEmitter {
     this.notifier =
       options.notifier || NotificationManager.fromEnv(options.notify || {});
 
-    this._chat = createChatFn(this._llmOptions);
+    // The task-scoped evolution composition is created in addTask(), so no
+    // provider adapter may be constructed here before its ingress exists.
+    this._chat = null;
     this._cronTimer = null;
 
     // Forward router events
@@ -374,13 +376,17 @@ export class Orchestrator extends EventEmitter {
       (task.context ? `\nAdditional context:\n${task.context}` : "");
 
     try {
-      const chat =
-        evolutionIngress === null
-          ? this._chat
-          : createChatFn({
-              ...this._llmOptions,
-              evolutionIngress,
-            });
+      if (evolutionIngress === null) {
+        const error = new Error(
+          "Orchestrator model egress requires an authenticated evolution ingress",
+        );
+        error.code = "CC_AGENT_EVOLUTION_INGRESS_FAILED";
+        throw error;
+      }
+      const chat = createChatFn({
+        ...this._llmOptions,
+        evolutionIngress,
+      });
       const raw = await chat(
         [
           { role: "system", content: systemPrompt },