@remnic/core 9.3.675 → 9.3.677

package/src/orchestrator.ts

@@ -325,6 +325,7 @@ import {
   recallNamespacesForPrincipal,
   resolvePrincipal,
 } from "./namespaces/principal.js";
+import { resolveScopePlan } from "./scopes/scope-plan.js";
 import {
   expandScopeProfileReadNamespaces,
   resolveScopeProfilePlan,
@@ -5770,7 +5771,8 @@ export class Orchestrator {
       options.principalOverride.length > 0
         ? options.principalOverride
         : resolvePrincipal(sessionKey, this.config);
-    if (this.config.namespacesEnabled && !principal) {
+    const namespacesEnabled = this.config.namespacesEnabled;
+    if (namespacesEnabled && !principal) {
       throw new Error("authentication required: namespaces are enabled and no principal was supplied");
     }
 
@@ -5862,6 +5864,7 @@ export class Orchestrator {
             options.namespace?.trim() || undefined,
             options.principalOverride,
             caps,
+            namespacesEnabled,
           );
         } catch (err) {
           log.debug(`direct-answer observation setup failed: ${err}`);
@@ -5931,62 +5934,27 @@ export class Orchestrator {
     namespaceOverride: string | undefined,
     principalOverride: string | undefined,
     caps: CapabilitySet,
+    namespacesEnabled: boolean,
   ): void {
     const expectedSnapshot = this.lastRecall.get(sessionKey);
     if (expectedSnapshot === null) return;
     if (expectedSnapshot.plannerMode === "no_recall") return;
 
-    const principal = principalOverride ?? resolvePrincipal(sessionKey, this.config);
-    // Coding-agent overlay (issue #569) is applied when the session has a
-    // coding context and there is no explicit namespaceOverride — mirrors
-    // the main recall path above.
-    const observationCodingOverlay =
-      namespaceOverride && canReadNamespace(principal, namespaceOverride, this.config)
-        ? null
-        : this.applyCodingRecallOverlay(sessionKey);
-    const observationPrincipalSelf = defaultNamespaceForPrincipal(principal, this.config);
-    const observationCodingSelf = observationCodingOverlay
-      ? combineNamespaces(observationPrincipalSelf, observationCodingOverlay.namespace)
-      : null;
-    const observationScopeProfilePlan =
-      namespaceOverride && canReadNamespace(principal, namespaceOverride, this.config)
-        ? null
-        : resolveScopeProfilePlan({
-            config: this.config,
-            principal,
-            codingContext: sessionKey
-              ? this.getCodingContextForSession(sessionKey)
-              : null,
-            codingOverlay: observationCodingOverlay,
-          });
-    let observationNamespaces: string[];
-    if (namespaceOverride && canReadNamespace(principal, namespaceOverride, this.config)) {
-      observationNamespaces = [namespaceOverride];
-    } else if (observationScopeProfilePlan) {
-      observationNamespaces = expandScopeProfileReadNamespaces({
-        profilePlan: observationScopeProfilePlan,
-        principalSelfNamespace: observationScopeProfilePlan.baseNamespace,
-        config: this.config,
-        principal,
-        codingOverlay: observationCodingOverlay,
-        legacyRecallNamespaces: recallNamespacesForPrincipal(principal, this.config),
-      });
-    } else if (observationCodingOverlay && observationCodingSelf) {
-      // Rule 42 / parity with the main recall path: substitute the self
-      // namespace within the principal's recall list rather than
-      // replacing the full list. Preserves shared and policy-include
-      // namespaces for direct-answer observation queries.
-      const base = recallNamespacesForPrincipal(principal, this.config);
-      const mapped = base.map((ns) =>
-        ns === observationPrincipalSelf ? observationCodingSelf : ns,
-      );
-      const fallbackNs = observationCodingOverlay.readFallbacks.map((fallback) =>
-        combineNamespaces(observationPrincipalSelf, fallback),
-      );
-      observationNamespaces = Array.from(new Set<string>([...mapped, ...fallbackNs]));
-    } else {
-      observationNamespaces = recallNamespacesForPrincipal(principal, this.config);
-    }
+    // Resolve the observation namespace set through the SAME ScopePlan resolver
+    // the main recall path uses (#1521). The observe path does NOT throw on an
+    // unreadable override (it falls through to the coding/legacy branches), so
+    // we skip the readability gate the recall path enforces.
+    const observationScopePlan = resolveScopePlan({
+      config: this.config,
+      sessionKey,
+      namespace: namespaceOverride,
+      principalOverride,
+      codingContext: sessionKey
+        ? this.getCodingContextForSession(sessionKey)
+        : null,
+      namespacesEnabled,
+    });
+    const observationNamespaces = observationScopePlan.readNamespaces;
     const observationQueryPolicy = buildRecallQueryPolicy(prompt, sessionKey, {
       cronRecallPolicyEnabled: this.config.cronRecallPolicyEnabled,
       cronRecallNormalizedQueryMaxChars:
@@ -7587,14 +7555,11 @@ export class Orchestrator {
         && options.principalOverride.length > 0
         ? options.principalOverride
         : resolvePrincipal(sessionKey, this.config);
-    if (this.config.namespacesEnabled && !principal) {
+    const namespacesEnabled = this.config.namespacesEnabled;
+    if (namespacesEnabled && !principal) {
       throw new Error("authentication required: namespaces are enabled and no principal was supplied");
     }
     const namespaceOverride = options.namespace?.trim() || undefined;
-    const readableRecallNamespaces = recallNamespacesForPrincipal(
-      principal,
-      this.config,
-    );
     if (
       namespaceOverride &&
       !canReadNamespace(principal, namespaceOverride, this.config)
@@ -7603,147 +7568,35 @@ export class Orchestrator {
         `namespace override is not readable: ${namespaceOverride}`,
       );
     }
-    // Recall path — overlay the coding-agent namespace (issue #569) when
-    // the session has a codingContext and `codingMode.projectScope` is true.
-    // Explicit `namespace` option still wins, preserving pre-#569 semantics.
-    //
-    // Rule 42: the overlay substitutes the SELF namespace within the
-    // principal's recall list — it does NOT replace the full list. Shared
-    // and `includeInRecallByDefault` policy namespaces stay in the recall
-    // set so coding sessions continue to see team/shared memories. The
-    // overlay is combined with the principal base through `combineNamespaces`
-    // to preserve principal isolation (cross-tenant leakage guard).
-    const codingOverlay = namespaceOverride ? null : this.applyCodingRecallOverlay(sessionKey);
-    const principalSelfNamespace = defaultNamespaceForPrincipal(principal, this.config);
-    const codingSelfNamespace = codingOverlay
-      ? combineNamespaces(principalSelfNamespace, codingOverlay.namespace)
-      : null;
-    const scopeProfilePlan = namespaceOverride
-      ? null
-      : resolveScopeProfilePlan({
-          config: this.config,
-          principal,
-          codingContext: sessionKey
-            ? this.getCodingContextForSession(sessionKey)
-            : null,
-          codingOverlay,
-        });
-    const profileEffectiveNamespace = scopeProfilePlan?.writeNamespace || scopeProfilePlan?.readNamespaces[0];
-    const selfNamespace =
-      namespaceOverride ??
-      profileEffectiveNamespace ??
-      codingSelfNamespace ??
-      principalSelfNamespace;
-    let recallNamespaces: string[];
-    if (namespaceOverride) {
-      recallNamespaces = [namespaceOverride];
-    } else if (scopeProfilePlan) {
-      recallNamespaces = expandScopeProfileReadNamespaces({
-        profilePlan: scopeProfilePlan,
-        principalSelfNamespace: scopeProfilePlan.baseNamespace,
-        config: this.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, PR 3) combined
-      // with the principal base so principal isolation is preserved on
-      // fallback entries as well.
-      const mapped = readableRecallNamespaces.map((ns) =>
-        ns === principalSelfNamespace ? codingSelfNamespace : ns,
-      );
-      const fallbackNs = codingOverlay.readFallbacks.map((fallback) =>
-        combineNamespaces(principalSelfNamespace, fallback),
-      );
-      recallNamespaces = Array.from(new Set<string>([...mapped, ...fallbackNs]));
-    } else {
-      recallNamespaces = readableRecallNamespaces;
-    }
-    // Catalog touch (issue #1499): record reads against the recalled namespaces
-    // so the catalog reflects active read scopes. Best-effort, failure-tolerant.
-    // Round 3 (codex P2): gate behind the no_recall guard — when the planner
-    // selects `no_recall` retrieval is skipped entirely (see the early return at
-    // `recallMode === "no_recall"` below), so marking every readable namespace as
-    // read would falsely inflate `lastReadAt` / catalog recency.
-    // Round 4 (codex P2): also skip when the effective memory result limit is
-    // zero (`topK: 0`, a disabled/zero `memories` recall section, etc.). The QMD
-    // path explicitly returns before searching when `recallResultLimit <= 0`, so
-    // no namespace is actually read and the touch would be spurious.
-    // NOTE: the catalog read touch is recorded LATER, immediately after the
-    // Phase 1 `throwIfRecallAborted` gate (round 6, codex P2 / cursor Medium —
-    // NDXHa/NDmle), so it fires only once retrieval is actually about to run.
-    // Recording it here (recall entry) would set `lastReadAt` for recalls that
-    // are aborted, error out, or short-circuit before any QMD/filesystem read.
-
-    // Effective LCM read NAMESPACE SET (#1505 thread "Include coding fallback
-    // namespaces in LCM reads"). `observe` archives LCM / structured history
-    // under `${effectiveNamespace}:${sessionKey}` for whichever namespace was
-    // effective at write time. A branch-scoped session whose evidence was
-    // archived at project / root scope must still surface it, exactly as normal
-    // QMD/file recall does — QMD/file recall searches the primary overlay key AND
-    // `codingOverlay.readFallbacks` (project / root), NOT just the primary
-    // overlay key. The prior single `lcmReadSessionId` only targeted the primary
-    // overlay, so branch-scoped sessions missed fallback LCM evidence.
+    // Resolve every namespace-bearing field through ONE ScopePlan (#1521): the
+    // read set, the LCM read keys, the coding overlay, and the scope-profile plan
+    // all come from a single pure resolver that delegates to the same helpers
+    // the inline code used. Parity snapshots in scope-plan.test.ts pin the
+    // outputs so this migration cannot change behavior.
     //
-    // READ-AUTHORIZATION (preserved from the prior round's
-    // `lcmReadNamespaceForSession` gate; rule 39 / 42 / 48): the coding-overlay
-    // namespace AND its fallbacks are `<principal>-project-*` sub-namespaces of
-    // the principal SELF base, authorized transitively by that base. They are
-    // included ONLY when the principal self base is in the readable recall set
-    // (`readableRecallNamespaces` — gated by `defaultRecallNamespaces.includes
-    // ("self")` AND `canReadNamespace`). When the self base is NOT readable (e.g.
-    // a write-only / self-omitted principal), the overlay rows are unauthorized
-    // for this reader, so the LCM read collapses to the default store — exactly
-    // what an unqualified, unauthorized recall resolves to — and NEVER searches a
-    // `<principal>-project-*` key (no cross-tenant read leak). This mirrors what
-    // the rest of recall surfaces for such a principal (its readable
-    // shared/policy namespaces have no per-session LCM key, so they contribute
-    // nothing here). `recallNamespaces` itself appends fallbacks unconditionally
-    // for QMD/file recall; the LCM read keys apply the stricter, self-base gate
-    // so the prior round's authorization invariant is preserved.
-    const codingOverlaySelfReadable =
-      codingOverlay !== null &&
-      (scopeProfilePlan
-        ? scopeProfilePlan.layers.some((layer) => layer.id === "userProject" && layer.readable)
-        : readableRecallNamespaces.includes(principalSelfNamespace));
-    let lcmReadNamespaces: string[];
-    if (namespaceOverride) {
-      // Explicit namespace already read-authorized above (canReadNamespace gate).
-      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 = recallNamespaces;
-    } else if (codingOverlay && codingSelfNamespace && codingOverlaySelfReadable) {
-      // Self base readable → overlay rows authorized. Read the primary overlay
-      // key first, then each coding read fallback (project → root), combined with
-      // the principal base for isolation — the SAME ordered set QMD/file recall
-      // searches for this authorized coding session.
-      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), exactly as the prior round did. No
-      // `<principal>-project-*` overlay key is searched.
-      lcmReadNamespaces = [this.config.defaultNamespace];
-    }
-    // Map the ordered, read-authorized namespace set → ordered, deduped LCM read
-    // session_id set. Single-user / no-overlay recall passes a single-namespace
-    // set that collapses to the raw `sessionKey`, so this is `[sessionKey]` —
-    // byte-for-byte the pre-#1495 single-key behavior.
-    const lcmReadSessionIds =
-      scopeProfilePlan && !sessionKey
-        ? []
-        : lcmReadSessionIdsForNamespaces(
-            lcmReadNamespaces,
-            sessionKey,
-            this.config.defaultNamespace,
-          );
+    // Catalog read touch (issue #1499) is recorded LATER — after the Phase 1
+    // abort gate — so it fires only when retrieval actually runs, not for
+    // aborted / short-circuited recalls.
+    const scopePlan = resolveScopePlan({
+      config: this.config,
+      sessionKey,
+      namespace: options.namespace,
+      principalOverride:
+        typeof options.principalOverride === "string"
+          && options.principalOverride.length > 0
+          ? options.principalOverride
+          : undefined,
+      codingContext: sessionKey
+        ? this.getCodingContextForSession(sessionKey)
+        : null,
+      namespacesEnabled,
+    });
+    const {
+      readNamespaces: recallNamespaces,
+      baseNamespace: selfNamespace,
+      scopeProfilePlan,
+      lcmReadSessionIds,
+    } = scopePlan;
     // Query an LCM-backed read across the ordered read key set and return the
     // FIRST non-empty result (#1505 fallback-namespace unification). The primary
     // overlay key is tried first; if a branch-scoped session has no rows under its

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);
+});