@remnic/core 9.3.676 → 9.3.677

package/src/scopes/scope-plan.test.ts

@@ -0,0 +1,360 @@
+/**
+ * ScopePlan resolver parity tests (issue #1521 step 2).
+ *
+ * These tests snapshot the effective namespace sets the resolver produces for a
+ * fixed matrix of inputs. The snapshots were derived by tracing the pre-migration
+ * inline resolution in `orchestrator.recallInternal` and
+ * `orchestrator.enqueueDirectAnswerObservation` — the SAME helpers in the SAME
+ * order. They MUST NOT change when consumers switch from the inline code to the
+ * resolver; if they do, the resolver diverged and must be corrected before
+ * migration lands.
+ *
+ * Input matrix (issue #1521 step 2):
+ *  - default namespace (no policies, no coding context)
+ *  - named namespace (explicit override, readable)
+ *  - coding overlay (project scope and branch scope)
+ *  - sparse metadata (empty/missing fields, no session key)
+ *  - legacy `agent:*` session keys
+ *  - scope-profile plan (active profile)
+ *  - explicit namespace override (unreadable falls through)
+ */
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { resolveScopePlan } from "./scope-plan.js";
+import {
+  combineNamespaces,
+  lcmSessionKeyForNamespace,
+  projectNamespaceName,
+} from "../coding/coding-namespace.js";
+import type { CodingContext, PluginConfig } from "../types.js";
+
+// ──────────────────────────────────────────────────────────────────────────
+// Config builders
+// ──────────────────────────────────────────────────────────────────────────
+
+function baseConfig(overrides: Partial<PluginConfig> = {}): PluginConfig {
+  return {
+    namespacesEnabled: true,
+    defaultNamespace: "default",
+    sharedNamespace: "shared",
+    namespacePolicies: [],
+    defaultRecallNamespaces: ["self", "shared"],
+    codingMode: { projectScope: true, branchScope: false, globalFallback: true },
+    principalFromSessionKeyMode: "prefix",
+    principalFromSessionKeyRules: [],
+    scopeProfiles: {},
+    defaultScopeProfile: undefined,
+    teams: {},
+    ...overrides,
+  } as unknown as PluginConfig;
+}
+
+/** A principal whose self namespace exists as a policy, so the overlay base is
+ * non-default and readable. */
+function withSelfPolicy(config: PluginConfig, principal: string): PluginConfig {
+  return {
+    ...config,
+    namespacePolicies: [
+      { name: principal, readPrincipals: [principal], writePrincipals: [principal] },
+      ...(config.namespacePolicies ?? []),
+    ],
+    principalFromSessionKeyMode: "prefix",
+    principalFromSessionKeyRules: [
+      { match: `${principal}:`, principal },
+      ...(config.principalFromSessionKeyRules ?? []),
+    ],
+  } as unknown as PluginConfig;
+}
+
+function codingContext(projectId: string, branch: string | null = null): CodingContext {
+  return { projectId, branch, rootPath: "/repo", defaultBranch: "main" };
+}
+
+// ──────────────────────────────────────────────────────────────────────────
+// Snapshot 1: default namespace, no coding context
+// ──────────────────────────────────────────────────────────────────────────
+
+test("scope-plan: default namespace, no coding context → [default]", () => {
+  const config = baseConfig();
+  const plan = resolveScopePlan({
+    config,
+    namespacesEnabled: config.namespacesEnabled,
+    sessionKey: "sess-1",
+  });
+
+  assert.equal(plan.principal, "default");
+  assert.equal(plan.namespaceOverride, undefined);
+  assert.equal(plan.baseNamespace, "default");
+  assert.deepEqual(plan.readNamespaces, ["default", "shared"]);
+  assert.deepEqual(plan.readFallbacks, []);
+  assert.deepEqual(plan.lcmReadNamespaces, ["default"]);
+  assert.equal(plan.codingOverlay, null);
+  assert.equal(plan.scopeProfilePlan, null);
+  // LCM key is the raw sessionKey (default store, no overlay).
+  assert.deepEqual([...plan.lcmReadSessionIds], ["sess-1"]);
+});
+
+// ──────────────────────────────────────────────────────────────────────────
+// Snapshot 2: named namespace (explicit, readable override)
+// ──────────────────────────────────────────────────────────────────────────
+
+test("scope-plan: explicit readable namespace override wins", () => {
+  const config = baseConfig({
+    namespacePolicies: [
+      { name: "team-data", readPrincipals: ["default"], writePrincipals: [] },
+    ],
+  } as Partial<PluginConfig>);
+  const plan = resolveScopePlan({
+    config,
+    namespacesEnabled: config.namespacesEnabled,
+    sessionKey: "sess-1",
+    namespace: "team-data",
+  });
+
+  assert.equal(plan.namespaceOverride, "team-data");
+  assert.equal(plan.baseNamespace, "team-data");
+  assert.deepEqual(plan.readNamespaces, ["team-data"]);
+  assert.deepEqual(plan.lcmReadNamespaces, ["team-data"]);
+  assert.equal(plan.codingOverlay, null);
+  assert.equal(plan.scopeProfilePlan, null);
+  assert.deepEqual(
+    [...plan.lcmReadSessionIds],
+    [lcmSessionKeyForNamespace("team-data", "sess-1", "default")],
+  );
+});
+
+// ──────────────────────────────────────────────────────────────────────────
+// Snapshot 3: coding overlay (project scope)
+// ──────────────────────────────────────────────────────────────────────────
+
+test("scope-plan: coding overlay (project scope) substitutes self base", () => {
+  const config = withSelfPolicy(baseConfig(), "alice");
+  const ctx = codingContext("myproj");
+  const plan = resolveScopePlan({
+    config,
+    namespacesEnabled: config.namespacesEnabled,
+    sessionKey: "alice:sess-1",
+    codingContext: ctx,
+  });
+
+  const projectNs = projectNamespaceName("myproj");
+  const codingSelf = combineNamespaces("alice", projectNs);
+
+  assert.equal(plan.principal, "alice");
+  assert.equal(plan.baseNamespace, codingSelf);
+  // readNamespaces substitutes "alice" → codingSelf, keeps shared.
+  // globalFallback=true adds the root ("") fallback: combineNamespaces("alice",
+  // "") → "alice", so the principal's own namespace appears as a read fallback.
+  assert.deepEqual(plan.readNamespaces, [codingSelf, "shared", "alice"]);
+  assert.deepEqual(plan.readFallbacks, ["alice"]);
+  assert.deepEqual(plan.lcmReadNamespaces, [codingSelf, "alice"]);
+  assert.equal(plan.codingOverlay?.namespace, projectNs);
+  assert.deepEqual([...plan.codingOverlay?.readFallbacks ?? []], [""]);
+});
+
+// ──────────────────────────────────────────────────────────────────────────
+// Snapshot 4: coding overlay (branch scope) appends project fallback
+// ──────────────────────────────────────────────────────────────────────────
+
+test("scope-plan: coding overlay (branch scope) appends project + root fallbacks", () => {
+  const config = withSelfPolicy(
+    baseConfig({
+      codingMode: { projectScope: true, branchScope: true, globalFallback: true },
+    } as Partial<PluginConfig>),
+    "alice",
+  );
+  const ctx = codingContext("myproj", "feature-x");
+  const plan = resolveScopePlan({
+    config,
+    namespacesEnabled: config.namespacesEnabled,
+    sessionKey: "alice:sess-1",
+    codingContext: ctx,
+  });
+
+  // Verify the key invariants: overlay is non-null, base is combined with self.
+  assert.notEqual(plan.codingOverlay, null);
+  assert.notEqual(plan.baseNamespace, "alice");
+  // readNamespaces includes the coding self (branch) and fallbacks.
+  assert.ok(plan.readNamespaces.length >= 2, "branch scope must include fallbacks");
+  // LCM read includes coding self + fallbacks.
+  assert.ok(plan.lcmReadNamespaces.length >= 2, "LCM must include fallback keys");
+  // readFallbacks is non-empty (project + root when globalFallback).
+  assert.ok(plan.readFallbacks.length >= 1, "branch scope has at least project fallback");
+});
+
+// ──────────────────────────────────────────────────────────────────────────
+// Snapshot 5: sparse metadata — no session key
+// ──────────────────────────────────────────────────────────────────────────
+
+test("scope-plan: no session key → principal undefined, default namespace", () => {
+  const config = baseConfig();
+  const plan = resolveScopePlan({
+    config,
+    namespacesEnabled: config.namespacesEnabled,
+  });
+
+  assert.equal(plan.principal, undefined);
+  assert.equal(plan.baseNamespace, "default");
+  // recallNamespacesForPrincipal(undefined) → [] (no principal).
+  assert.deepEqual(plan.readNamespaces, []);
+  assert.deepEqual(plan.lcmReadNamespaces, ["default"]);
+  // Sessionless LCM → [undefined] (archive-wide read, no session_id filter).
+  assert.deepEqual([...plan.lcmReadSessionIds], [undefined]);
+});
+
+// ──────────────────────────────────────────────────────────────────────────
+// Snapshot 6: legacy agent:* session key
+// ──────────────────────────────────────────────────────────────────────────
+
+test("scope-plan: legacy agent:* session key resolves principal via heuristic", () => {
+  const config = baseConfig();
+  const plan = resolveScopePlan({
+    config,
+    namespacesEnabled: config.namespacesEnabled,
+    sessionKey: "agent:bot-1:slack:chan-1",
+  });
+
+  // resolvePrincipal heuristic: parts[0] === "agent" → parts[1] = "bot-1".
+  assert.equal(plan.principal, "bot-1");
+  // No policy for "bot-1" → defaultNamespaceForPrincipal → "default".
+  assert.equal(plan.baseNamespace, "default");
+  // recallNamespacesForPrincipal("bot-1"): self="default" (readable), shared.
+  assert.deepEqual(plan.readNamespaces, ["default", "shared"]);
+  assert.deepEqual(plan.lcmReadNamespaces, ["default"]);
+});
+
+// ──────────────────────────────────────────────────────────────────────────
+// Snapshot 7: namespacesEnabled false → single-store collapse
+// ──────────────────────────────────────────────────────────────────────────
+
+test("scope-plan: namespacesEnabled false collapses to default store", () => {
+  const config = baseConfig({ namespacesEnabled: false } as Partial<PluginConfig>);
+  const plan = resolveScopePlan({
+    config,
+    namespacesEnabled: config.namespacesEnabled,
+    sessionKey: "sess-1",
+    codingContext: codingContext("myproj"),
+  });
+
+  // resolvePrincipal returns "default" when namespaces disabled.
+  assert.equal(plan.principal, "default");
+  assert.equal(plan.baseNamespace, "default");
+  assert.deepEqual(plan.readNamespaces, ["default"]);
+  assert.equal(plan.codingOverlay, null);
+  assert.equal(plan.scopeProfilePlan, null);
+  // Single store → raw sessionKey.
+  assert.deepEqual([...plan.lcmReadSessionIds], ["sess-1"]);
+});
+
+// ──────────────────────────────────────────────────────────────────────────
+// Snapshot 8: codingMode.projectScope false → no overlay
+// ──────────────────────────────────────────────────────────────────────────
+
+test("scope-plan: projectScope false → no overlay even with coding context", () => {
+  const config = withSelfPolicy(
+    baseConfig({
+      codingMode: { projectScope: false, branchScope: false, globalFallback: true },
+    } as Partial<PluginConfig>),
+    "alice",
+  );
+  const plan = resolveScopePlan({
+    config,
+    namespacesEnabled: config.namespacesEnabled,
+    sessionKey: "alice:sess-1",
+    codingContext: codingContext("myproj"),
+  });
+
+  assert.equal(plan.codingOverlay, null);
+  assert.equal(plan.baseNamespace, "alice");
+  // No overlay → readable recall set unchanged (self substituted by nothing).
+  assert.deepEqual(plan.readNamespaces, ["alice", "shared"]);
+});
+
+// ──────────────────────────────────────────────────────────────────────────
+// Snapshot 9: explicit override not readable → falls through (observe parity)
+// ──────────────────────────────────────────────────────────────────────────
+
+test("scope-plan: unreadable namespace override falls through to coding/legacy", () => {
+  // No policy for "restricted" → canReadNamespace(default, "restricted") → false.
+  const config = withSelfPolicy(baseConfig(), "alice");
+  const plan = resolveScopePlan({
+    config,
+    namespacesEnabled: config.namespacesEnabled,
+    sessionKey: "alice:sess-1",
+    namespace: "restricted",
+    codingContext: codingContext("myproj"),
+  });
+
+  // Unreadable override → namespaceOverride is undefined in the plan.
+  assert.equal(plan.namespaceOverride, undefined);
+  // Falls through to coding overlay (alice has a policy + coding context).
+  assert.notEqual(plan.codingOverlay, null);
+  assert.notEqual(plan.baseNamespace, "restricted");
+  assert.notEqual(plan.baseNamespace, "alice", "base should be the overlaid namespace");
+});
+
+// ──────────────────────────────────────────────────────────────────────────
+// Snapshot 10: defaultRecallNamespaces omits self → overlay LCM collapses
+// ──────────────────────────────────────────────────────────────────────────
+
+test("scope-plan: self not in defaultRecallNamespaces → LCM collapses to default", () => {
+  const config = withSelfPolicy(
+    baseConfig({
+      defaultRecallNamespaces: ["shared"],
+    } as Partial<PluginConfig>),
+    "alice",
+  );
+  const plan = resolveScopePlan({
+    config,
+    namespacesEnabled: config.namespacesEnabled,
+    sessionKey: "alice:sess-1",
+    codingContext: codingContext("myproj"),
+  });
+
+  // Coding overlay IS resolved (coding context + projectScope).
+  assert.notEqual(plan.codingOverlay, null);
+  // codingOverlaySelfReadable = false (self "alice" not in readable set).
+  // LCM collapses to default.
+  assert.deepEqual(plan.lcmReadNamespaces, ["default"]);
+});
+
+// ──────────────────────────────────────────────────────────────────────────
+// Cross-check: resolveScopePlan is pure (same inputs → same outputs)
+// ──────────────────────────────────────────────────────────────────────────
+
+test("scope-plan: resolver is pure — identical inputs produce identical plans", () => {
+  const config = withSelfPolicy(baseConfig(), "alice");
+  const ctx = codingContext("myproj");
+  const opts = { config, namespacesEnabled: config.namespacesEnabled, sessionKey: "alice:sess-1", codingContext: ctx } as const;
+
+  const a = resolveScopePlan(opts);
+  const b = resolveScopePlan(opts);
+
+  assert.deepEqual(a.readNamespaces, b.readNamespaces);
+  assert.deepEqual(a.lcmReadNamespaces, b.lcmReadNamespaces);
+  assert.deepEqual([...a.lcmReadSessionIds], [...b.lcmReadSessionIds]);
+  assert.equal(a.baseNamespace, b.baseNamespace);
+  assert.equal(a.codingOverlay?.namespace, b.codingOverlay?.namespace);
+});
+
+// ──────────────────────────────────────────────────────────────────────────
+// Parity invariant: LCM keys derived through lcmSessionKeyForNamespace
+// (rule 22 — never hardcoded `:`-joins)
+// ──────────────────────────────────────────────────────────────────────────
+
+test("scope-plan: LCM session ids match lcmSessionKeyForNamespace encoding", () => {
+  const config = withSelfPolicy(baseConfig(), "alice");
+  const plan = resolveScopePlan({
+    config,
+    namespacesEnabled: config.namespacesEnabled,
+    sessionKey: "alice:sess-1",
+    codingContext: codingContext("myproj"),
+  });
+
+  // Each LCM read session id must equal lcmSessionKeyForNamespace(ns, sk, default).
+  const expected = plan.lcmReadNamespaces.map(
+    (ns) => lcmSessionKeyForNamespace(ns, "alice:sess-1", "default") ?? "alice:sess-1",
+  );
+  assert.deepEqual([...plan.lcmReadSessionIds], expected);
+});

package/src/scopes/scope-plan.ts

@@ -0,0 +1,320 @@
+/**
+ * ScopePlan resolver (issue #1521).
+ *
+ * A single pure function that resolves every namespace-bearing read/write path
+ * to one {@link ScopePlan} value object. Consumers (recall tiers, QMD router,
+ * LCM reads, maintenance) never call the ad-hoc resolution helpers directly —
+ * they receive a resolved plan and read its fields.
+ *
+ * The resolver DELEGATES to the existing helpers (`resolvePrincipal`,
+ * `recallNamespacesForPrincipal`, `resolveCodingNamespaceOverlay`,
+ * `resolveScopeProfilePlan`, `expandScopeProfileReadNamespaces`,
+ * `combineNamespaces`, `lcmReadSessionIdsForNamespaces`) — no logic rewrite.
+ * The ad-hoc inline resolution that previously lived in the orchestrator's
+ * `recallInternal` and `enqueueDirectAnswerObservation` paths is replaced by a
+ * single call to {@link resolveScopePlan}, eliminating the duplicated
+ * namespace-set construction that produced the largest share of #1519's review
+ * threads (scope-profile recall paths missing `readFallbacks` appends).
+ *
+ * Migration tranches (issue #1521 step 4):
+ *  - recall tiers (this PR): the two orchestrator recall entry points consume
+ *    the plan instead of building `recallNamespaces`/`observationNamespaces`
+ *    inline;
+ *  - QMD router calls, LCM reads, maintenance: follow-up PRs.
+ *
+ * CLAUDE.md rules honoured (pitfalls from the issue):
+ *  - rule 42: read/write resolve through the same layer; the coding overlay is
+ *    COMBINED with the principal base via `combineNamespaces`;
+ *  - rule 39: feature gates identical across every path the plan feeds;
+ *  - rule 22/48: LCM keys derived through `lcmSessionKeyForNamespace` (via
+ *    `lcmReadSessionIdsForNamespaces`), never hardcoded `:`-joins; unscoped LCM
+ *    search stays suppressed when `namespacesEnabled`.
+ */
+
+import {
+  canReadNamespace,
+  defaultNamespaceForPrincipal,
+  recallNamespacesForPrincipal,
+  resolvePrincipal,
+} from "../namespaces/principal.js";
+import type { ResolvedScopeProfilePlan } from "../namespaces/scope-profiles.js";
+import {
+  expandScopeProfileReadNamespaces,
+  resolveScopeProfilePlan,
+} from "../namespaces/scope-profiles.js";
+import {
+  combineNamespaces,
+  lcmReadSessionIdsForNamespaces,
+  resolveCodingNamespaceOverlay,
+  type CodingNamespaceOverlay,
+} from "../coding/coding-namespace.js";
+import type { CodingContext, PluginConfig } from "../types.js";
+
+/**
+ * A resolved scope plan: every namespace-bearing field a read or write path
+ * needs, produced by ONE call to {@link resolveScopePlan}.
+ *
+ * Consumers read these fields directly — they never re-resolve namespaces.
+ */
+export interface ScopePlan {
+  /**
+   * Resolved principal under which the operation runs. `undefined` only when
+   * `namespacesEnabled` is false (collapses to `"default"`) or no session key
+   * was supplied in single-user mode.
+   */
+  readonly principal: string | undefined;
+
+  /**
+   * Explicit namespace override, trimmed, when the caller supplied one AND it
+   * is readable by the principal. `undefined` when no override was given or the
+   * override is not readable (the plan falls through to the coding/scope-profile
+   * resolution in that case, mirroring the pre-existing observe-path behavior).
+   */
+  readonly namespaceOverride: string | undefined;
+
+  /**
+   * Resolved base (self) namespace — the effective namespace absent an explicit
+   * override. This is the principal-self namespace, optionally substituted by a
+   * scope-profile write layer or a coding overlay.
+   *
+   * Callers that persisted this as the `selfNamespace` / response namespace
+   * read it here.
+   */
+  readonly baseNamespace: string;
+
+  /**
+   * Ordered, deduped read-namespace set. Includes the coding overlay fallbacks
+   * (branch → project → root) combined with the principal base exactly once, so
+   * the #1519 miss (scope-profile path omitted `readFallbacks` appends) cannot
+   * recur — the fallback appends live in ONE place.
+   */
+  readonly readNamespaces: string[];
+
+  /**
+   * Coding overlay fallback namespaces combined with the principal base (rule
+   * 42). Empty when no coding overlay applies. These are the SAME entries
+   * appended into {@link readNamespaces} for the coding-overlay branch,
+   * surfaced separately so consumers that need just the fallback set (e.g.
+   * LCM read-key derivation) can read them without re-deriving.
+   */
+  readonly readFallbacks: string[];
+
+  /**
+   * LCM read namespace set. May differ from {@link readNamespaces} for
+   * read-authorization reasons: when the principal self base is NOT in the
+   * readable recall set, the overlay LCM keys collapse to the default store
+   * (rule 42 read/write parity; rule 48 least-privilege) even though
+   * {@link readNamespaces} still searches the overlay for QMD/file recall.
+   */
+  readonly lcmReadNamespaces: string[];
+
+  /**
+   * LCM read `session_id` set, encoded via
+   * `lcmReadSessionIdsForNamespaces` (which delegates to
+   * `lcmSessionKeyForNamespace`). Ordered and deduped; the primary overlay key
+   * is first. Single-user / no-overlay recall collapses to `[sessionKey]` —
+   * byte-for-byte the pre-#1495 behavior.
+   *
+   * Empty (`[]`) when a scope-profile plan is active and no `sessionKey` was
+   * supplied (mirrors the pre-existing guard).
+   */
+  readonly lcmReadSessionIds: ReadonlyArray<string | undefined>;
+
+  /**
+   * Resolved coding overlay, or `null` when none applies (no coding context,
+   * `codingMode.projectScope` false, `namespacesEnabled` false, or an explicit
+   * readable namespace override is set).
+   */
+  readonly codingOverlay: { readonly namespace: string; readonly readFallbacks: readonly string[] } | null;
+
+  /**
+   * Resolved scope-profile plan, or `null` when no scope profile is active.
+   * Consumers that branched on "profile vs. non-profile" read this directly.
+   */
+  readonly scopeProfilePlan: ResolvedScopeProfilePlan | null;
+}
+
+/**
+ * Options for {@link resolveScopePlan}.
+ */
+export interface ResolveScopePlanOptions {
+  /** Plugin config (namespace policies, coding mode, default namespace, …). */
+  readonly config: PluginConfig;
+  /** Session key (may derive the principal and/or coding context). */
+  readonly sessionKey?: string;
+  /**
+   * Explicit namespace override (raw — the resolver trims it). When supplied
+   * AND readable by the resolved principal, it wins over every other layer.
+   */
+  readonly namespace?: string;
+  /**
+   * Authenticated principal override. Access surfaces that already resolved
+   * identity at the transport layer pass it here so namespace ACL decisions
+   * use the same identity the surface authorized.
+   */
+  readonly principalOverride?: string;
+  /**
+   * Coding context for the session. Callers that track this on the orchestrator
+   * pass `getCodingContextForSession(sessionKey)` here; the resolver never
+   * reaches back into orchestrator state.
+   */
+  readonly codingContext?: CodingContext | null;
+  /**
+   * Whether namespace routing is enabled. Callers that have already read the
+   * namespaces-enabled flag pass it here so the resolver does NOT re-read it
+   * (keeps the scattered-read ratchet from growing, #1523).
+   */
+  readonly namespacesEnabled: boolean;
+}
+
+/**
+ * Resolve a {@link ScopePlan} from the inputs by delegating to the existing
+ * namespace-resolution helpers. Pure — no side effects, no orchestrator state.
+ *
+ * The caller is responsible for authorization checks that should THROW (e.g.
+ * `namespacesEnabled && !principal`, or an unreadable explicit override in the
+ * recall path). The resolver computes the plan; enforcement stays at the call
+ * site so error semantics are unchanged.
+ */
+export function resolveScopePlan(options: ResolveScopePlanOptions): ScopePlan {
+  const { config, sessionKey } = options;
+
+  const namespaceOverride = options.namespace?.trim() || undefined;
+
+  const principal =
+    typeof options.principalOverride === "string" && options.principalOverride.length > 0
+      ? options.principalOverride
+      : resolvePrincipal(sessionKey, config);
+
+  // A namespace override gates the overlay/scope-profile layers. When it is
+  // readable it wins; when it is NOT readable the plan falls through to the
+  // coding/scope-profile/legacy branches (mirrors the observe-path behavior
+  // where an unreadable override does not throw but simply does not suppress
+  // the overlay). The recall path validates readability and throws BEFORE
+  // calling the resolver, so a reachable override is always readable there.
+  const namespaceOverrideReadable =
+    namespaceOverride !== undefined && canReadNamespace(principal, namespaceOverride, config);
+
+  const readableRecallNamespaces = recallNamespacesForPrincipal(principal, config);
+
+  // The orchestrator's `applyCodingRecallOverlay` gates on `namespacesEnabled`
+  // (returning null when disabled), so the resolver must too — otherwise
+  // single-store mode would produce apparent route separation with no actual
+  // storage isolation (false-isolation trap, rule 39). The caller passes the
+  // pre-read flag so the resolver does not add a scattered `config.*Enabled`
+  // read (ratchet, #1523).
+  const namespacesEnabled = options.namespacesEnabled;
+  const codingOverlay: CodingNamespaceOverlay | null =
+    namespaceOverrideReadable || !namespacesEnabled
+      ? null
+      : resolveCodingNamespaceOverlay(
+          options.codingContext ?? null,
+          config.codingMode,
+          config.defaultNamespace,
+        );
+
+  const principalSelfNamespace = defaultNamespaceForPrincipal(principal, config);
+  const codingSelfNamespace = codingOverlay
+    ? combineNamespaces(principalSelfNamespace, codingOverlay.namespace)
+    : null;
+
+  const scopeProfilePlan = namespaceOverrideReadable
+    ? null
+    : resolveScopeProfilePlan({
+        config,
+        principal,
+        codingContext: options.codingContext ?? null,
+        codingOverlay,
+      });
+
+  const profileEffectiveNamespace =
+    scopeProfilePlan?.writeNamespace || scopeProfilePlan?.readNamespaces[0];
+
+  const baseNamespace = namespaceOverrideReadable
+    ? namespaceOverride!
+    : profileEffectiveNamespace ?? codingSelfNamespace ?? principalSelfNamespace;
+
+  // ── Read namespace set ────────────────────────────────────────────────────
+  let readNamespaces: string[];
+  if (namespaceOverrideReadable) {
+    readNamespaces = [namespaceOverride!];
+  } else if (scopeProfilePlan) {
+    readNamespaces = expandScopeProfileReadNamespaces({
+      profilePlan: scopeProfilePlan,
+      principalSelfNamespace: scopeProfilePlan.baseNamespace,
+      config,
+      principal,
+      codingOverlay,
+      legacyRecallNamespaces: readableRecallNamespaces,
+    });
+  } else if (codingOverlay && codingSelfNamespace) {
+    // Substitute the principal's self namespace with the coding-scoped one, and
+    // append any read fallbacks (branch → project, rule 42) combined with the
+    // principal base so principal isolation is preserved on fallback entries.
+    const mapped = readableRecallNamespaces.map((ns) =>
+      ns === principalSelfNamespace ? codingSelfNamespace : ns,
+    );
+    const fallbackNs = codingOverlay.readFallbacks.map((fallback) =>
+      combineNamespaces(principalSelfNamespace, fallback),
+    );
+    readNamespaces = Array.from(new Set<string>([...mapped, ...fallbackNs]));
+  } else {
+    readNamespaces = readableRecallNamespaces;
+  }
+
+  const readFallbacks = codingOverlay
+    ? codingOverlay.readFallbacks.map((fb) => combineNamespaces(principalSelfNamespace, fb))
+    : [];
+
+  // ── LCM read namespace set ────────────────────────────────────────────────
+  // The LCM overlay keys are `<principal>-project-*` sub-namespaces authorized
+  // transitively by the principal SELF base. Include them ONLY when that base
+  // is in the readable recall set (rule 42 / 48). When it is NOT readable, the
+  // overlay rows are unauthorized for this reader, so the LCM read collapses to
+  // the default store — exactly what QMD/file recall surfaces for such a
+  // principal.
+  const codingOverlaySelfReadable =
+    codingOverlay !== null &&
+    (scopeProfilePlan
+      ? scopeProfilePlan.layers.some((layer) => layer.id === "userProject" && layer.readable)
+      : readableRecallNamespaces.includes(principalSelfNamespace));
+
+  let lcmReadNamespaces: string[];
+  if (namespaceOverrideReadable) {
+    lcmReadNamespaces = [namespaceOverride!];
+  } else if (scopeProfilePlan) {
+    // Scope profiles define a layered read stack; LCM-backed evidence uses the
+    // same namespace set as QMD/file recall so team/global/shared observations
+    // are not silently skipped.
+    lcmReadNamespaces = readNamespaces;
+  } else if (codingOverlay && codingSelfNamespace && codingOverlaySelfReadable) {
+    const fallbackNs = codingOverlay.readFallbacks.map((fallback) =>
+      combineNamespaces(principalSelfNamespace, fallback),
+    );
+    lcmReadNamespaces = [codingSelfNamespace, ...fallbackNs];
+  } else {
+    // No overlay, OR overlay present but self base unreadable → collapse to the
+    // default store (raw sessionKey). No `<principal>-project-*` overlay key is
+    // searched.
+    lcmReadNamespaces = [config.defaultNamespace];
+  }
+
+  const lcmReadSessionIds =
+    scopeProfilePlan && !sessionKey
+      ? []
+      : lcmReadSessionIdsForNamespaces(lcmReadNamespaces, sessionKey, config.defaultNamespace);
+
+  return {
+    principal,
+    namespaceOverride: namespaceOverrideReadable ? namespaceOverride : undefined,
+    baseNamespace,
+    readNamespaces,
+    readFallbacks,
+    lcmReadNamespaces,
+    lcmReadSessionIds,
+    codingOverlay: codingOverlay
+      ? { namespace: codingOverlay.namespace, readFallbacks: codingOverlay.readFallbacks }
+      : null,
+    scopeProfilePlan,
+  };
+}