@hassangameryt/freeflow 0.7.3 → 0.8.0

package/pi-extension/dist/cognitive-routing/runtime.js

@@ -0,0 +1,396 @@
+import { randomUUID } from "node:crypto";
+import { ContextAssembler } from "./assembler.js";
+import { EventStore } from "./event-store.js";
+import { ToolGate } from "./gate.js";
+import { Handoffs } from "./handoffs.js";
+import { ToolHandlers } from "./handlers.js";
+import { ModelControl } from "./model-control.js";
+import { RoutingSession } from "./session.js";
+import { RoutingStatus } from "./status.js";
+import { isTaskEvidence } from "./sources.js";
+import { PROFILES, canonical, isWorkerProfile, requireCondition as check, samePair } from "./types.js";
+/**
+ * Cognitive Routing as the Pi extension sees it. Binds routing to the current session, follows ancestry and
+ * configuration changes, handles /freeflow profile and resume commands, and forwards each host hook to the part that
+ * owns it: model control, status, the tool gate, request assembly, handoffs, and the routing tools.
+ */
+export class RoutingRuntime {
+  pi;
+  packageRoots;
+  /** State shared with every part of routing for the bound session. */
+  session = new RoutingSession();
+  models;
+  status;
+  gate;
+  assembler;
+  handoffs;
+  tools;
+  targetSignature;
+  constructor(pi, packageRoots = []) {
+    this.pi = pi;
+    this.packageRoots = packageRoots;
+    this.models = new ModelControl(this.session, this.pi);
+    this.status = new RoutingStatus(this.session, this.models);
+    this.gate = new ToolGate(this.session, this.packageRoots);
+    this.assembler = new ContextAssembler(this.session, this.pi, this.models);
+    this.handoffs = new Handoffs(this.session, this.pi, this.models, this.assembler);
+    this.tools = new ToolHandlers(this.session, this.models, this.gate, this.assembler, this.status);
+  }
+  get projectionEnabled() {
+    return this.session.projectionEnabled;
+  }
+  async settled(ctx) {
+    if (!this.session.store || !this.session.supported() || this.session.store.blocked || !ctx.isIdle?.()) return;
+    this.session.ctx = ctx;
+    this.session.retireUnbound(
+      "Native run settled without a complete source binding; prior effects remain unresolved.",
+    );
+  }
+  /** The Coordinator's model while a delegated worker holds the assignment; the Coordinator resumes on return. */
+  suspendedCoordinator() {
+    try {
+      const state = this.session.stateData();
+      if (
+        !this.session.supported() ||
+        state.control !== "automatic" ||
+        !isWorkerProfile(state.profile) ||
+        !state.assignmentId
+      )
+        return;
+      const pair = this.session.profilePair("coordinator");
+      return { provider: pair.provider, modelId: pair.modelId, requester: "coordinator" };
+    } catch {
+      return;
+    }
+  }
+  async bind(ctx, capability, startup = false) {
+    this.session.token = randomUUID();
+    this.session.ctx = ctx;
+    this.session.capability = capability;
+    this.session.resetTurn();
+    this.session.manualHold = undefined;
+    this.session.automaticControl = false;
+    this.models.applying = undefined;
+    this.models.externalChange = false;
+    this.session.error = undefined;
+    this.session.projectionError = undefined;
+    this.session.operations = Promise.resolve();
+    this.targetSignature = canonical({ delegation: capability.delegation, profiles: capability.profiles });
+    this.session.suppressed = startup && process.argv.some((a) => /^(--model|--thinking)(=|$)/.test(a));
+    this.session.store = new EventStore(this.pi, ctx.sessionManager);
+    const subject = this.session.subject();
+    if (!capability.effective || this.session.suppressed) return;
+    try {
+      await this.session.store.reconcile();
+      this.session.guard(subject);
+      const state = this.session.stateData();
+      this.session.manualHold = state.control === "manual" ? state.profile : undefined;
+      this.session.automaticControl = !state.events.size || state.control === "automatic";
+      await this.models.validateProfilePairs(this.session.profilePairs(this.session.requiredProfiles(state)));
+      this.models.announcePresets(ctx);
+      const interrupted = this.handoffs.interruptedRun(state);
+      const resumable = this.handoffs.resumableAssignment(state);
+      this.session.retireUnbound("Session rebind found an unfinished execution; no task effects replayed.");
+      if (!state.events.size) {
+        await this.models.transition(
+          this.session.profilePair("coordinator"),
+          () =>
+            this.session.append({
+              type: "control",
+              control: "automatic",
+              profile: "coordinator",
+              reason: "Initial routing activation",
+            }),
+          subject,
+        );
+      } else if (
+        state.control === "automatic" &&
+        state.profile &&
+        !samePair(this.models.intended(), this.session.profilePair(state.profile))
+      ) {
+        // Reload reconstructs responsibility; it does not silently reapply the last setter.
+        await this.models.transition(
+          this.session.profilePair("coordinator"),
+          () =>
+            this.session.append({
+              type: "control",
+              control: "automatic",
+              profile: "coordinator",
+              reason: "Rebind reconciles historical responsibility with current host control",
+            }),
+          subject,
+        );
+      }
+      // Only a run cut off mid-flight resumes on its own; reopening an idle session never starts work.
+      if (interrupted && ctx.hasUI) {
+        const token = this.session.token;
+        setTimeout(() => void this.handoffs.resumeAfterCrash(ctx, token), 0);
+      } else if (resumable)
+        ctx.ui?.notify?.(
+          `The ${resumable.worker} assignment is unchanged. Run /freeflow resume to continue it; a new message goes to Coordinator.`,
+          "info",
+        );
+    } catch (error) {
+      if (this.session.current(subject)) this.session.mark(error);
+    }
+  }
+  /** Write routing events staged before the session's first prompt; nothing to write once routing is unbound. */
+  writeStaged(events) {
+    if (!this.session.store || !events.length) return;
+    try {
+      this.session.store.writeStaged(events);
+    } catch (error) {
+      this.session.mark(error);
+    }
+  }
+  unbind() {
+    this.session.token = randomUUID();
+    this.session.store = undefined;
+    this.session.ctx = undefined;
+    this.session.resetTurn();
+  }
+  async refresh(ctx, capability) {
+    this.session.ctx = ctx;
+    const was = this.session.capability?.effective === true;
+    const signature = canonical({ delegation: capability.delegation, profiles: capability.profiles });
+    if (this.session.capability && (was !== capability.effective || signature !== this.targetSignature))
+      this.session.revision++;
+    this.session.capability = capability;
+    if (!capability.effective) {
+      this.session.turn = undefined;
+      return;
+    }
+    if (!this.session.store) {
+      await this.bind(ctx, capability);
+      return;
+    }
+    if (!was) {
+      const subject = this.session.subject();
+      this.session.suppressed = false;
+      try {
+        await this.session.store.reconcile();
+        this.session.guard(subject);
+        this.session.error = undefined;
+        await this.models.transition(
+          this.session.profilePair("coordinator"),
+          () =>
+            this.session.append({
+              type: "control",
+              control: "automatic",
+              profile: "coordinator",
+              reason: "Capability re-enabled; Coordinator reconciliation",
+            }),
+          subject,
+        );
+        this.session.automaticControl = true;
+      } catch (error) {
+        if (this.session.current(subject)) this.session.mark(error);
+      }
+    } else if (this.targetSignature && signature !== this.targetSignature) {
+      this.session.error = "configuration_changed: reconcile profile configuration before automatic execution";
+      this.session.announceBlock(ctx);
+    }
+    if (
+      canonical({ delegation: this.session.capability?.delegation, profiles: this.session.capability?.profiles }) ===
+      signature
+    )
+      this.targetSignature = signature;
+    this.models.announcePresets(ctx);
+  }
+  async ancestryChanged(ctx, navigation = true) {
+    this.session.revision++;
+    this.session.ctx = ctx;
+    this.session.resetTurn();
+    if (!this.session.store || !this.session.supported()) return;
+    const subject = this.session.subject();
+    try {
+      await this.session.store.reconcile();
+      this.session.guard(subject);
+      this.session.error = undefined;
+      const state = this.session.stateData();
+      await this.models.validateProfilePairs(this.session.profilePairs(this.session.requiredProfiles(state)));
+      this.session.retireUnbound(
+        "Selected historical ancestry ends before execution binding; effects are not replayed.",
+      );
+      if (this.session.manualHold) {
+        const held = this.session.manualHold;
+        await this.models.transition(
+          this.session.profilePair(held),
+          () =>
+            this.session.append({
+              type: "control",
+              control: "manual",
+              profile: held,
+              reason: "Current explicit manual hold survives navigation",
+            }),
+          subject,
+        );
+      } else if (
+        (this.session.automaticControl || !state.events.size) &&
+        (navigation || !samePair(this.models.intended(), this.session.profilePair(state.profile ?? "coordinator")))
+      ) {
+        await this.models.transition(
+          this.session.profilePair("coordinator"),
+          () =>
+            this.session.append({
+              type: "control",
+              control: "automatic",
+              profile: "coordinator",
+              reason: "Coordinator reconciles selected native ancestry",
+            }),
+          subject,
+        );
+      }
+    } catch (error) {
+      if (this.session.current(subject)) this.session.mark(error);
+    }
+  }
+  async command(args, ctx) {
+    const words = args.trim().split(/\s+/);
+    if (!["profile", "resume"].includes(words[0])) return false;
+    try {
+      if (words[0] === "profile" && words[1] === "history") {
+        check(words.length === 2 || (words.length === 3 && words[2] === "diagnostics"), "invalid_history_command");
+        ctx.ui.notify(
+          JSON.stringify(
+            words[2] === "diagnostics"
+              ? this.status.detail(30)
+              : this.tools.inspectUnit({ view: "history", limit: 30 }),
+          ),
+          "info",
+        );
+        return true;
+      }
+      check(ctx.isIdle?.(), "not_idle");
+      this.session.ctx = ctx;
+      if (words[0] === "resume" && words.length === 1) {
+        await this.handoffs.resume(ctx);
+        return true;
+      }
+      check(
+        words.length === 2 && [...PROFILES, "auto"].includes(words[1]),
+        "invalid_profile_command",
+        "Use /freeflow profile coordinator|helper|executor|auto|history, or /freeflow resume.",
+      );
+      const result =
+        words[1] === "auto" ? await this.models.setAutomaticControl() : await this.models.setManualProfile(words[1]);
+      ctx.ui.notify(JSON.stringify(result), result.status === "blocked" ? "warning" : "info");
+    } catch (error) {
+      ctx.ui.notify(error instanceof Error ? error.message : String(error), "warning");
+    }
+    return true;
+  }
+  beforeRun(ctx, fromPrompt = true) {
+    return this.models.beforeRun(ctx, fromPrompt);
+  }
+  runStarted() {
+    this.models.runStarted();
+  }
+  startedByMessage(message) {
+    return this.models.startedByMessage(message);
+  }
+  nativeChange(ctx) {
+    return this.models.nativeChange(ctx);
+  }
+  cycleManualProfile() {
+    return this.models.cycleManualProfile();
+  }
+  setManualProfile(profile, _mechanism) {
+    return this.models.setManualProfile(profile, _mechanism);
+  }
+  setAutomaticControl(_mechanism) {
+    return this.models.setAutomaticControl(_mechanism);
+  }
+  sessionProfileOverrides() {
+    return this.models.sessionProfileOverrides();
+  }
+  sessionDelegationOverride() {
+    return this.models.sessionDelegationOverride();
+  }
+  setSessionDelegationOverride(override, mechanism = "Session delegation override") {
+    return this.models.setSessionDelegationOverride(override, mechanism);
+  }
+  setSessionProfileOverride(profile, override, mechanism = "Session profile override") {
+    return this.models.setSessionProfileOverride(profile, override, mechanism);
+  }
+  resetSessionProfileOverrides(mechanism = "Reset session profile overrides") {
+    return this.models.resetSessionProfileOverrides(mechanism);
+  }
+  preflight(event, ctx) {
+    return this.gate.preflight(event, ctx);
+  }
+  operationScope(ctx = this.session.ctx) {
+    return this.gate.operationScope(ctx);
+  }
+  observationScope() {
+    return this.gate.observationScope();
+  }
+  admitOperation(scope, effect, _operation, ctx = this.session.ctx) {
+    return this.gate.admitOperation(scope, effect, _operation, ctx);
+  }
+  admitProgram(scope, ctx = this.session.ctx) {
+    return this.gate.admitProgram(scope, ctx);
+  }
+  resultReadAccess(id) {
+    return this.gate.resultReadAccess(id);
+  }
+  budgetNotice(messages, ctx) {
+    return this.assembler.budgetNotice(messages, ctx);
+  }
+  context(ctx, incoming) {
+    return this.assembler.context(ctx, incoming);
+  }
+  messageEnd(message) {
+    return this.handoffs.messageEnd(message);
+  }
+  turnEnd(event, ctx) {
+    return this.handoffs.turnEnd(event, ctx);
+  }
+  state() {
+    return this.status.state();
+  }
+  /** The assignment in progress, if any; Freeflow compaction records it so routing can tell the worker it compacted. */
+  currentAssignment() {
+    if (!this.state().effective) return undefined;
+    return this.session.stateData().assignmentId ?? undefined;
+  }
+  /**
+   * The assignment in progress, for compaction: the entries of the tool results it produced (task evidence only) and
+   * the refs already selected as its evidence. Undefined when no worker holds an assignment.
+   */
+  assignmentResults() {
+    try {
+      const state = this.session.stateData();
+      const assignmentId = state.assignmentId;
+      if (!this.state().effective || !assignmentId) return undefined;
+      const entryIds = new Set();
+      for (const source of this.session.sources().byRef.values())
+        if (source.assignmentId === assignmentId && isTaskEvidence(source)) entryIds.add(source.entry.id);
+      return { entryIds, selected: new Set(state.selections.get(assignmentId)?.selected ?? []) };
+    } catch {
+      return undefined;
+    }
+  }
+  /** A source ref's tool result, for compaction to carry; only task evidence, the results routing lets be selected. */
+  evidenceSource(ref) {
+    try {
+      const source = this.session.sources().byRef.get(ref);
+      if (!source || !isTaskEvidence(source)) return undefined;
+      const text = (source.message.content ?? [])
+        .map((part) => (part?.type === "text" ? part.text : part?.type === "image" ? "[image]" : ""))
+        .join("");
+      return { tool: source.message.toolName ?? "tool", text };
+    } catch {
+      return undefined;
+    }
+  }
+  setResultGrantPort(port) {
+    return this.tools.setResultGrantPort(port);
+  }
+  setEffectFencePort(port) {
+    return this.tools.setEffectFencePort(port);
+  }
+  invoke(name, callId, input, signal, ctx) {
+    return this.tools.invoke(name, callId, input, signal, ctx);
+  }
+}

package/pi-extension/dist/{cognitive-routing-v2 → cognitive-routing}/schemas.js

@@ -69,6 +69,7 @@ export const ROUTING_SCHEMAS = {
           operation: operation("recover"),
           request: string(),
           paths: { type: "array", maxItems: 32, items: string(4096) },
+          results: { type: "array", maxItems: 32, uniqueItems: true, items: string(256) },
         },
         ["operation", "request"],
       ),
@@ -140,6 +141,48 @@ for (const schema of Object.values(ROUTING_SCHEMAS)) {
       description:
         "For add, use exact eligible visible refs directly when their identity and eligibility are clear; inspect when identity, eligibility, representation, or selection state is unclear. Never add refs marked not offered for new evidence selection. For remove, use currently selected or unresolved refs; a non-selectable ref may be named to clear its unresolved request and requires reason.",
     };
+  // The provider sees one flattened root, so each field names the operations whose strict shape accepts it.
+  const operations = schema.oneOf.map((branch) => branch.properties.operation.enum[0]);
+  for (const [field, property] of Object.entries(schema.properties)) {
+    if (field === "operation") continue;
+    const accepting = operations.filter((_op, i) => Object.hasOwn(schema.oneOf[i].properties, field));
+    if (accepting.length === operations.length) continue;
+    const scope = `Only for operation: ${accepting.join(", ")}.`;
+    schema.properties[field] = {
+      ...property,
+      description: property.description ? `${property.description} ${scope}` : scope,
+    };
+  }
+}
+const expected = (schema) =>
+  schema.enum
+    ? `one of ${schema.enum.join(", ")}`
+    : schema.type === "string"
+      ? `a non-empty string of at most ${schema.maxLength} characters`
+      : schema.type === "array"
+        ? `an array of at most ${schema.maxItems} items`
+        : schema.type === "integer"
+          ? `an integer from ${schema.minimum} to ${schema.maximum}`
+          : `type ${schema.type}`;
+/** Explain why routing arguments match no strict operation shape, naming what to change. */
+export function explainRoutingArguments(name, input) {
+  const schema = ROUTING_SCHEMAS[name];
+  const operations = schema.oneOf.map((branch) => branch.properties.operation.enum[0]);
+  const operation = isObject(input) ? input.operation : undefined;
+  const branch = schema.oneOf.find((b) => b.properties.operation.enum[0] === operation);
+  if (!isObject(input) || !branch)
+    return `Invalid ${name} arguments: operation must be one of ${operations.join(", ")}. No operation was accepted.`;
+  const allowed = Object.keys(branch.properties);
+  const problems = [];
+  const unknown = Object.keys(input).filter((field) => !allowed.includes(field));
+  if (unknown.length) problems.push(`remove field${unknown.length > 1 ? "s" : ""} ${unknown.join(", ")}`);
+  const missing = branch.required.filter((field) => !Object.hasOwn(input, field));
+  if (missing.length) problems.push(`missing required field${missing.length > 1 ? "s" : ""} ${missing.join(", ")}`);
+  for (const field of allowed)
+    if (Object.hasOwn(input, field) && !matches(input[field], branch.properties[field]))
+      problems.push(`${field} must be ${expected(branch.properties[field])}`);
+  if (!problems.length) problems.push("arguments do not match this operation's shape");
+  return `Invalid ${name} arguments for operation ${operation}: ${problems.join("; ")}. Allowed fields: ${allowed.join(", ")}. No operation was accepted.`;
 }
 export function matches(value, schema) {
   if (schema.oneOf) return schema.oneOf.filter((branch) => matches(value, branch)).length === 1;
@@ -164,10 +207,3 @@ export function matches(value, schema) {
     return Number.isSafeInteger(value) && value >= schema.minimum && value <= schema.maximum;
   return false;
 }
-export function schemaForProfile(name, coordinator) {
-  const schema = ROUTING_SCHEMAS[name];
-  if (name !== "freeflow_unit" || coordinator) return schema;
-  const branches = schema.oneOf.filter((b) => b.properties.operation.enum[0] === "inspect");
-  const properties = Object.assign({}, ...branches.map((b) => b.properties));
-  return { ...schema, properties, oneOf: branches };
-}

package/pi-extension/dist/cognitive-routing/session.js

@@ -0,0 +1,221 @@
+import { randomUUID } from "node:crypto";
+import { Sources } from "./sources.js";
+import { ViewCache } from "./projection.js";
+import { pairFromProfile } from "./config.js";
+import { initialState } from "./state.js";
+import { RoutingError, isWorkerProfile, requireCondition as check, samePair, workersForDelegation } from "./types.js";
+import { cachedBranch } from "../host/branch.js";
+const STAGED_CONTROL = new Set(["control", "profile-overrides", "delegation-override"]);
+export const ROUTING_RECOVERY_HINT =
+  "Run /freeflow profile auto to reconcile routing, or /freeflow resume to continue saved work.";
+/**
+ * State and identity shared by every part of routing for one bound session: the event journal, the host
+ * context, the current turn, blocking errors, control mode, and the queue that orders control changes.
+ */
+export class RoutingSession {
+  store;
+  ctx;
+  capability;
+  token = randomUUID();
+  turn;
+  messages = [];
+  error;
+  projectionError;
+  suppressed = false;
+  operations = Promise.resolve();
+  revision = 0;
+  manualHold;
+  automaticControl = false;
+  sourceCache;
+  /** Rendered view messages reused across requests (see ViewCache); rebuilt after a rebind or ancestry change. */
+  viewCache = new ViewCache();
+  /** Replayed tool results for the current turn, keyed by operation id. */
+  receipts = new Map();
+  /** Recently served inspection pages, keyed by request; at most eight are kept. */
+  pages = new Map();
+  get projectionEnabled() {
+    return this.supported() && this.capability?.projection === true && this.stateData().control === "automatic";
+  }
+  /** Forgets everything derived for the current turn: its context view, sources, replay receipts, and pages. */
+  resetTurn() {
+    this.turn = undefined;
+    this.messages = [];
+    this.sourceCache = undefined;
+    this.viewCache = new ViewCache();
+    this.receipts.clear();
+    this.pages.clear();
+  }
+  subject() {
+    const branch = cachedBranch(this.store?.reader) ?? [];
+    return {
+      token: this.token,
+      revision: this.revision,
+      store: this.store,
+      leafId: branch.at(-1)?.id ?? null,
+      userId: branch.filter((e) => e.message?.role === "user").at(-1)?.id ?? null,
+    };
+  }
+  current(s) {
+    if (s.token !== this.token || s.revision !== this.revision || s.store !== this.store) return false;
+    const branch = cachedBranch(this.store?.reader) ?? [];
+    return (
+      (!s.leafId || branch.some((e) => e.id === s.leafId)) &&
+      (branch.filter((e) => e.message?.role === "user").at(-1)?.id ?? null) === s.userId
+    );
+  }
+  guard(s) {
+    check(
+      this.current(s),
+      "stale_operation",
+      "Routing state changed while the operation was waiting; no further effects applied.",
+    );
+  }
+  taskBasis(state, assignmentId) {
+    return state.resumeBasis.has(assignmentId)
+      ? state.resumeBasis.get(assignmentId)
+      : state.assignments.get(assignmentId)?.basisUserEntryId;
+  }
+  delegation(state = this.stateData()) {
+    return state.delegationOverride ?? this.capability?.delegation ?? "executor";
+  }
+  enabledWorkers(state = this.stateData()) {
+    return workersForDelegation(this.delegation(state));
+  }
+  assignedWorker(state, assignmentId = state.assignmentId) {
+    const assignment = assignmentId ? state.assignments.get(assignmentId) : undefined;
+    const handoff = assignment ? state.handoffs.get(assignment.delegateHandoffId) : undefined;
+    check(
+      handoff?.kind === "delegate" && handoff.assignmentId === assignment?.id && isWorkerProfile(handoff.to),
+      "assignment_worker_missing",
+      "The current assignment has no valid recorded worker.",
+    );
+    return handoff.to;
+  }
+  requiredProfiles(state = this.stateData(), delegation = this.delegation(state)) {
+    const profiles = new Set(["coordinator", ...workersForDelegation(delegation)]);
+    if (state.profile) profiles.add(state.profile);
+    if (this.manualHold) profiles.add(this.manualHold);
+    const assignment = state.assignmentId ? state.assignments.get(state.assignmentId) : undefined;
+    if (assignment?.state === "outstanding" || state.recoveryId) profiles.add(this.assignedWorker(state));
+    const pending = state.pendingId ? state.handoffs.get(state.pendingId) : undefined;
+    if (pending && isWorkerProfile(pending.to)) profiles.add(pending.to);
+    return [...profiles];
+  }
+  retireUnbound(reason) {
+    for (const execution of this.stateData().executions.values()) {
+      if (!execution.assistantEntryId && !execution.interrupted)
+        this.append({ type: "execution-interrupted", executionId: execution.id, reason });
+    }
+    this.turn = undefined;
+  }
+  openTurn() {
+    if (!this.turn || this.turn.opened) return;
+    const t = this.turn;
+    this.append({
+      type: "execution-opened",
+      execution: {
+        id: t.id,
+        profile: t.profile,
+        assignmentId: t.assignmentId,
+        recoveryId: t.recoveryId,
+        basisUserEntryId: t.basisUserEntryId,
+        pair: t.pair,
+        resultEntryIds: [],
+      },
+    });
+    t.opened = true;
+  }
+  stateData() {
+    return this.store?.state() ?? initialState();
+  }
+  sources(state = this.stateData()) {
+    const branch = cachedBranch(this.ctx.sessionManager);
+    const cache = this.sourceCache;
+    // The cached branch is the same array until the leaf moves, so an unchanged branch needs no filtering.
+    if (cache && cache.branch === branch && cache.authors === state.authors.size) return cache.source;
+    const entries = branch.filter((e) =>
+      ["message", "custom_message", "compaction", "branch_summary"].includes(e.type),
+    );
+    if (
+      cache &&
+      cache.authors === state.authors.size &&
+      entries.length === cache.entries.length &&
+      entries.every((e, i) => e === cache.entries[i])
+    ) {
+      cache.branch = branch;
+      return cache.source;
+    }
+    const active = this.ctx.sessionManager.buildContextEntries?.();
+    const activeIds = active ? new Set(active.map((e) => e.id)) : undefined;
+    const source = cache?.source ?? new Sources([], state);
+    source.refresh(entries, state, activeIds);
+    this.sourceCache = { branch, entries, authors: state.authors.size, source };
+    return source;
+  }
+  observed(ctx = this.ctx) {
+    return ctx?.model?.provider && ctx?.model?.id && ctx?.thinkingLevel
+      ? { provider: ctx.model.provider, modelId: ctx.model.id, thinking: ctx.thinkingLevel }
+      : undefined;
+  }
+  supported() {
+    return !!this.capability?.effective && !this.suppressed;
+  }
+  append(data, op, step) {
+    check(this.store, "routing_unavailable");
+    // Control changes made while no run is active affect no request until the next prompt; stage them there.
+    const stage = STAGED_CONTROL.has(data.type) && this.ctx?.isIdle?.() !== false;
+    return this.store.append(this.store.make(data, op, step), stage);
+  }
+  enqueue(action) {
+    const token = this.token;
+    const result = this.operations.then(() => {
+      check(token === this.token, "stale_instance");
+      return action();
+    });
+    this.operations = result.catch(() => {});
+    return result;
+  }
+  mark(error) {
+    if (this.error && error instanceof RoutingError && error.code === "routing_blocked") return;
+    this.error =
+      error instanceof RoutingError
+        ? `${error.code}: ${error.message}`
+        : error instanceof Error
+          ? error.message
+          : String(error);
+  }
+  announced;
+  // Tell the user once per distinct block; routing stays blocked until an explicit control clears it.
+  announceBlock(ctx) {
+    if (!this.error || this.announced === this.error) return;
+    this.announced = this.error;
+    ctx?.ui?.notify?.(`Cognitive Routing blocked: ${this.error}. ${ROUTING_RECOVERY_HINT}`, "warning");
+  }
+  assertAvailable(profile) {
+    check(
+      this.supported() && this.store && !this.error && !this.store.blocked,
+      "routing_unavailable",
+      this.error ?? this.store?.blocked ?? "Routing is inactive.",
+    );
+    const state = this.stateData();
+    check(state.control === "automatic", "manual_control");
+    if (profile) check(state.profile === profile && this.turn?.profile === profile, "wrong_profile");
+    if (state.profile) check(samePair(this.observed(), this.profilePair(state.profile)), "configuration_mismatch");
+  }
+  configuredProfilePair(profile) {
+    const configured = this.capability?.profiles[profile];
+    check(configured, "profile_missing");
+    return pairFromProfile(configured);
+  }
+  profilePair(profile) {
+    return this.stateData().profileOverrides.get(profile) ?? this.configuredProfilePair(profile);
+  }
+  profilePairs(profiles = this.requiredProfiles()) {
+    return Object.fromEntries(profiles.map((profile) => [profile, this.profilePair(profile)]));
+  }
+  workerBasis(state, assignmentId) {
+    const recovery = state.recoveryId ? state.recoveries.get(state.recoveryId) : undefined;
+    if (recovery?.state === "reading") return state.handoffs.get(recovery.requestHandoffId)?.basisUserEntryId ?? null;
+    return this.taskBasis(state, assignmentId);
+  }
+}