@north-light/crouter 0.3.227 → 0.3.228

package/dist/core/memory-resolver.js

@@ -1,34 +1,18 @@
-import { basename, join, relative, sep } from 'node:path';
+import { dirname, join, relative, sep } from 'node:path';
 import { readdirSync } from 'node:fs';
 import { CRTR_DIR_NAME } from '../types.js';
-import { pathExists, readText, walkFiles } from './fs-utils.js';
+import { pathExists, readText, realpathOrSelf, walkFiles } from './fs-utils.js';
 import { parseFrontmatterGeneric } from './frontmatter.js';
-import { listInstalledPlugins, listInstalledPluginsInRoot, parseSkillQualifier } from './resolver.js';
-import { ambiguous, notFound, usage } from './errors.js';
+import { listInstalledPlugins, listInstalledPluginsInRoot } from './resolver.js';
+import { notFound, usage } from './errors.js';
 import { warn } from './output.js';
 import { NEUTRAL_PROJECT_MEMORY, pluginMemoryDir, projectScopeRoots, projectScopeRootsWithMemory, scopeMemoryDir } from './scope.js';
-import { effectiveDocKind, normalizeDocName, normalizeNameSegment, resolveDocName } from './substrate/schema.js';
+import { effectiveDocKind } from './substrate/schema.js';
+import { INDEX_SEGMENT, canonicalSegments, composeCanonicalName, localNameFromPath, normalizeNameSegment, representationForPath, resolveLocalName, routingAnchorFor, validateNamespace, } from './memory/identity.js';
 import { loadProfileManifest, profileMemoryDir } from './profiles/manifest.js';
 import { memoryDir as nodeMemoryDir } from './runtime/memory.js';
 import { descendantStoreRoots } from './nested-stores.js';
-/** The native (non-plugin) store dirs in resolution precedence — node >
- *  project stack > profile > user, builtin excluded as a read-only corpus.
- *  Addresses a store directly when the document itself may be absent, which is
- *  how a DELETED doc's revision log is still found: history outlives the doc,
- *  so its lookup cannot go through document resolution. */
-export function nativeMemoryStoresInPrecedence(scope, includeDescendants = false) {
-    const out = [];
-    for (const source of memorySourcesInPrecedence(ambientTarget(), scope, includeDescendants)) {
-        if (source.scope === 'builtin' || source.memoryDir === null)
-            continue;
-        out.push({ scope: source.scope, memoryDir: source.memoryDir });
-    }
-    return out;
-}
-/** Canonical, unambiguous identifier for a memory document: `<scope>/<name>`. */
-export function memoryDocId(doc) {
-    return `${doc.scope}/${doc.name}`;
-}
+import { associateRepository } from './memory/repository-association.js';
 /** The target the ambient process describes: cwd + the two env seams every
  *  profile/node-aware memory path reads through (`CRTR_PROFILE_ID`,
  *  `CRTR_NODE_ID`). */
@@ -43,6 +27,10 @@ function ambientTarget() {
 function selectedProfileId() {
     return ambientTarget().profileId ?? '';
 }
+// ---------------------------------------------------------------------------
+// Store discovery: which physical stores a target sees, in what order, and
+// whether each one's namespace lets it mount.
+// ---------------------------------------------------------------------------
 /** The memory scopes in resolution precedence: node > project stack > profile >
  *  user > builtin. Node is included only when the target names one and ranks
  *  NEAREST — a node doc overrides any wider scope. Project is included only when
@@ -63,38 +51,168 @@ function scopesInPrecedence(target, scope) {
     out.push('builtin');
     return out;
 }
-/** Memory loads project scopes as a stack, not a single nearest root: every
- *  ancestor `.crouter/` from cwd upward (widened by a selected profile's
- *  `projects`) contributes, nearest first. Profile is a singleton store
- *  resolved through the centralized `loadProfileManifest` — never a raw path
- *  join — and drops out silently (never throws the resolver) when the
- *  selected profile id no longer resolves to a manifest. User and builtin
- *  remain singleton scopes after that. */
-function memorySourcesInPrecedence(target, scope, includeDescendants = false) {
+/** Resolve a project store through its repository-root declaration. */
+function projectStoreDescriptor(ownerDir, storeRoot, projectMemory) {
+    const base = { scope: 'project', storeRoot, ownerDir, projectMemory };
+    if (!pathExists(storeRoot))
+        return { ...base, namespace: '', mountStatus: 'absent' };
+    const association = associateRepository(ownerDir);
+    if (!association.ok) {
+        const remedy = `run \`crtr sys migrate --dir ${ownerDir}\``;
+        if (association.code === 'no-project-root') {
+            return {
+                ...base,
+                namespace: '',
+                mountStatus: 'undeclared',
+                mountFailure: 'association',
+                diagnostic: `project memory store at ${storeRoot} has no repository root declaring \`namespace:\` — ${remedy}`,
+            };
+        }
+        return {
+            ...base,
+            namespace: '',
+            mountStatus: 'invalid',
+            mountFailure: 'association',
+            diagnostic: `project memory store at ${storeRoot} cannot be associated: ${association.reason} — ${remedy}`,
+        };
+    }
+    const { association: repository } = association;
+    const repositoryFields = {
+        namespacePath: repository.declarationPath,
+        repositoryRoot: repository.repositoryRoot,
+        repositoryKey: repository.repositoryKey,
+        ownerRelativePath: repository.ownerRelativePath,
+    };
+    const rootIndex = repository.declarationPath;
+    const nested = repository.ownerRelativePath !== '';
+    const remedy = `run \`crtr sys migrate --dir ${repository.repositoryRoot}\``;
+    const missingDiagnostic = nested
+        ? `nested project memory store at ${storeRoot} takes its identity from ${rootIndex}, which is missing root ${INDEX_SEGMENT}.md declaring \`namespace:\` — ${remedy}`
+        : `project memory store has no root ${INDEX_SEGMENT}.md declaring \`namespace:\` — ${remedy}`;
+    if (!pathExists(rootIndex)) {
+        return {
+            ...base,
+            ...repositoryFields,
+            namespace: '',
+            mountStatus: 'undeclared',
+            mountFailure: 'undeclared-root',
+            diagnostic: missingDiagnostic,
+        };
+    }
+    let declared;
+    try {
+        declared = parseFrontmatterGeneric(readText(rootIndex)).data?.['namespace'];
+    }
+    catch (e) {
+        return {
+            ...base,
+            ...repositoryFields,
+            namespace: '',
+            mountStatus: 'invalid',
+            mountFailure: 'invalid-root',
+            diagnostic: `project memory store's ${rootIndex} does not parse (${firstLine(e)}) — ${remedy}`,
+        };
+    }
+    if (declared === undefined || declared === null || declared === '') {
+        const diagnostic = nested
+            ? `nested project memory store at ${storeRoot} takes its identity from ${rootIndex}, which declares no \`namespace:\` — ${remedy}`
+            : `project memory store's ${rootIndex} declares no \`namespace:\` — ${remedy}`;
+        return {
+            ...base,
+            ...repositoryFields,
+            namespace: '',
+            mountStatus: 'undeclared',
+            mountFailure: 'undeclared-root',
+            diagnostic,
+        };
+    }
+    // No coercion: a numeric or otherwise non-string declaration is a malformed
+    // store, not a namespace. Coercing it would mount a store whose namespace no
+    // memory command can then edit.
+    if (typeof declared !== 'string') {
+        return {
+            ...base,
+            ...repositoryFields,
+            namespace: '',
+            mountStatus: 'invalid',
+            mountFailure: 'invalid-root',
+            diagnostic: `project memory store declares a non-string \`namespace:\` (${JSON.stringify(declared)}) — quote it in ${rootIndex}, or ${remedy}`,
+        };
+    }
+    const valid = validateNamespace(declared);
+    if (!valid.ok) {
+        return {
+            ...base,
+            ...repositoryFields,
+            namespace: '',
+            mountStatus: 'invalid',
+            mountFailure: 'invalid-root',
+            diagnostic: `project memory store declares an invalid namespace \`${declared}\` (${valid.reason}) — ${remedy}`,
+        };
+    }
+    return {
+        ...base,
+        ...repositoryFields,
+        repositoryNamespace: declared,
+        namespace: composeCanonicalName(declared, repository.ownerRelativePath),
+        mountStatus: 'ready',
+    };
+}
+/** A store with no namespace of its own: user, profile, node, builtin. */
+function plainStoreDescriptor(scope, storeRoot) {
+    if (storeRoot === null) {
+        return { scope, storeRoot: '', namespace: '', mountStatus: 'absent', projectMemory: NEUTRAL_PROJECT_MEMORY };
+    }
+    return {
+        scope,
+        storeRoot,
+        namespace: '',
+        mountStatus: pathExists(storeRoot) ? 'ready' : 'absent',
+        projectMemory: NEUTRAL_PROJECT_MEMORY,
+    };
+}
+/** An installed plugin's store, mounted under the plugin's own name. */
+function pluginStoreDescriptor(plugin, scope, projectMemory) {
+    const storeRoot = pluginMemoryDir(plugin);
+    return {
+        scope,
+        storeRoot,
+        namespace: plugin.name,
+        plugin: plugin.name,
+        mountStatus: pathExists(storeRoot) ? 'ready' : 'absent',
+        projectMemory,
+    };
+}
+/** The exact project store owned by `ownerDir` — the `--dir` selector's store,
+ *  loaded whatever its mount status so lint and migration can inspect a store
+ *  the runtime refuses to mount. */
+export function openProjectMemoryStore(ownerDir) {
+    const owner = realpathOrSelf(ownerDir);
+    return projectStoreDescriptor(owner, join(owner, CRTR_DIR_NAME, 'memory'), NEUTRAL_PROJECT_MEMORY);
+}
+/** Every store a target sees, in precedence order: node, each project store
+ *  nearest-first (its enabled plugins after it), then profile, user, builtin.
+ *  One real store reached twice contributes once, at its first position. */
+export function memoryStoresInPrecedence(target, scope, includeDescendants = false) {
     const out = [];
+    const projectStores = (crtrRoot, projectMemory) => {
+        out.push(projectStoreDescriptor(dirname(crtrRoot), join(crtrRoot, 'memory'), projectMemory));
+        for (const plugin of listInstalledPluginsInRoot('project', crtrRoot).filter((p) => p.enabled)) {
+            out.push(pluginStoreDescriptor(plugin, 'project', projectMemory));
+        }
+    };
     for (const s of scopesInPrecedence(target, scope)) {
         if (s === 'project') {
             const annotated = projectScopeRootsWithMemory(target.cwd, target.profileId);
-            for (const { root, memory } of annotated) {
-                out.push({
-                    scope: 'project',
-                    memoryDir: join(root, 'memory'),
-                    plugins: listInstalledPluginsInRoot('project', root).filter((p) => p.enabled),
-                    projectMemory: memory,
-                });
-            }
+            for (const { root, memory } of annotated)
+                projectStores(root, memory);
             // Descendant stores rank after every ancestor source (and before
-            // profile): an ancestor doc always beats a nested doc on a name tie.
-            // They carry the neutral ceiling — no profile entry names them, and
-            // descendant discovery is off for every automatic delivery path.
+            // profile): an ancestor doc always wins an equal-canonical tie against a
+            // nested one. They carry the neutral ceiling — no profile entry names
+            // them, and descendant discovery is off for every automatic delivery path.
             if (includeDescendants) {
                 for (const root of descendantStoreRoots(annotated.map(({ root: r }) => r))) {
-                    out.push({
-                        scope: 'project',
-                        memoryDir: join(root, 'memory'),
-                        plugins: listInstalledPluginsInRoot('project', root).filter((p) => p.enabled),
-                        projectMemory: NEUTRAL_PROJECT_MEMORY,
-                    });
+                    projectStores(root, NEUTRAL_PROJECT_MEMORY);
                 }
             }
         }
@@ -103,173 +221,330 @@ function memorySourcesInPrecedence(target, scope, includeDescendants = false) {
             if (profileId !== '') {
                 try {
                     const { profileId: resolvedId } = loadProfileManifest(profileId);
-                    out.push({ scope: 'profile', memoryDir: profileMemoryDir(resolvedId), plugins: [], projectMemory: NEUTRAL_PROJECT_MEMORY });
+                    out.push(plainStoreDescriptor('profile', profileMemoryDir(resolvedId)));
                 }
                 catch {
-                    // Missing/deleted/invalid selected profile: no profile memory source.
+                    // Missing/deleted/invalid selected profile: no profile memory store.
                 }
             }
         }
         else if (s === 'node') {
-            // The this-node store — a singleton dir in the node's context, no plugins.
-            // Silently absent when the target names no node.
             const nodeId = target.nodeId ?? '';
             if (nodeId !== '')
-                out.push({ scope: 'node', memoryDir: nodeMemoryDir(nodeId), plugins: [], projectMemory: NEUTRAL_PROJECT_MEMORY });
+                out.push(plainStoreDescriptor('node', nodeMemoryDir(nodeId)));
         }
         else {
-            out.push({
-                scope: s,
-                memoryDir: scopeMemoryDir(s),
-                plugins: listInstalledPlugins(s).filter((p) => p.enabled),
-                projectMemory: NEUTRAL_PROJECT_MEMORY,
-            });
+            out.push(plainStoreDescriptor(s, scopeMemoryDir(s)));
+            for (const plugin of listInstalledPlugins(s).filter((p) => p.enabled)) {
+                out.push(pluginStoreDescriptor(plugin, s, NEUTRAL_PROJECT_MEMORY));
+            }
         }
     }
-    return out;
+    const seen = new Set();
+    const deduped = out.filter((store) => {
+        if (store.storeRoot === '')
+            return false;
+        const key = realpathOrSelf(store.storeRoot);
+        if (seen.has(key))
+            return false;
+        seen.add(key);
+        return true;
+    });
+    const collisions = new Map();
+    for (const store of deduped) {
+        if (store.scope !== 'project' ||
+            store.mountStatus !== 'ready' ||
+            store.repositoryRoot === undefined ||
+            store.ownerRelativePath === undefined)
+            continue;
+        const key = `${store.repositoryRoot}\u0000${store.ownerRelativePath}`;
+        const group = collisions.get(key);
+        if (group)
+            group.push(store);
+        else
+            collisions.set(key, [store]);
+    }
+    return deduped.map((store) => {
+        if (store.scope !== 'project' ||
+            store.mountStatus !== 'ready' ||
+            store.repositoryRoot === undefined ||
+            store.ownerRelativePath === undefined)
+            return store;
+        const group = collisions.get(`${store.repositoryRoot}\u0000${store.ownerRelativePath}`);
+        if (group === undefined || group.length < 2)
+            return store;
+        const owners = group.map((member) => member.ownerDir ?? member.storeRoot).join(', ');
+        return {
+            ...store,
+            mountStatus: 'invalid',
+            mountFailure: 'collision',
+            diagnostic: `project memory stores at ${owners} normalize to the same effective prefix \`${store.namespace}\` — rename one owner directory`,
+        };
+    });
+}
+/** The native (non-plugin) MOUNTED store dirs in resolution precedence.
+ *  Addresses a store directly when the document itself may be absent, which is
+ *  how a DELETED doc's revision log is still found: history outlives the doc,
+ *  so its lookup cannot go through document resolution. */
+export function nativeMemoryStoresInPrecedence(scope, includeDescendants = false) {
+    return memoryStoresInPrecedence(ambientTarget(), scope, includeDescendants)
+        .filter((store) => store.mountStatus === 'ready' && store.scope !== 'builtin' && store.plugin === undefined)
+        .map((store) => ({ scope: store.scope, memoryDir: store.storeRoot, store }));
+}
+// ---------------------------------------------------------------------------
+// Document loading: one store's markdown files become canonically-identified
+// documents.
+// ---------------------------------------------------------------------------
+function firstLine(e) {
+    return (e instanceof Error ? e.message : String(e)).split('\n')[0] ?? '';
 }
-function loadMemoryDoc(scope, root, path, fallbackName, projectMemory = NEUTRAL_PROJECT_MEMORY) {
+/** Load one markdown file as a document of `store`, or null when it has no
+ *  canonical identity — a root `INDEX.md` in a store without a namespace, which
+ *  would compose to the empty name. */
+function loadMemoryDoc(store, path, physicalRelativePath) {
     const { data, body } = parseFrontmatterGeneric(readText(path));
-    return { name: resolveDocName(data, fallbackName), scope, path, root, frontmatter: data, body, projectMemory };
+    const pathLocal = localNameFromPath(physicalRelativePath);
+    const representation = representationForPath(physicalRelativePath);
+    // A store's root INDEX.md is the store's own document: its identity is the
+    // namespace itself, never an explicit `name` (lint rejects one there).
+    const localName = pathLocal === '' ? '' : resolveLocalName(data, pathLocal);
+    const name = composeCanonicalName(store.namespace, localName);
+    if (name === '')
+        return null;
+    return {
+        name,
+        localName,
+        scope: store.scope,
+        path,
+        root: store.storeRoot,
+        physicalRelativePath,
+        representation,
+        routingAnchor: routingAnchorFor(name, representation),
+        store,
+        frontmatter: data,
+        body,
+        projectMemory: store.projectMemory,
+        ...(store.plugin === undefined ? {} : { plugin: store.plugin }),
+    };
+}
+/** Within one store, `foo/INDEX.md` deterministically precedes `foo.md` for the
+ *  same canonical identity: the directory form physically fronts the directory.
+ *  Lint errors on the pair and every mutation refuses it, but a read still has
+ *  one answer. */
+function compareDocs(a, b) {
+    const byName = a.name.localeCompare(b.name);
+    if (byName !== 0)
+        return byName;
+    if (a.representation !== b.representation)
+        return a.representation === 'directory-index' ? -1 : 1;
+    return a.physicalRelativePath.localeCompare(b.physicalRelativePath);
 }
-/** All memory docs in one memory/ dir, scanned recursively for *.md (topical
- *  subdirs supported), sorted by resolver identity (explicit frontmatter name
- *  when present, else path-derived). SKILL.md bundles are legacy Agent Skills
- *  and are ignored; crouter memory docs are plain .md files under memory/. */
-function listMemoryDocsInDir(scope, dir, quiet = false, projectMemory = NEUTRAL_PROJECT_MEMORY) {
-    if (!dir || !pathExists(dir))
+/** Every document in one store, sorted by canonical identity. SKILL.md bundles
+ *  are Agent Skills, not memory docs. Enumeration stops at a nested `.crouter/`:
+ *  that is another store's mount point, never this store's content. */
+export function loadStoreMemoryDocs(store, quiet = false) {
+    if (store.storeRoot === '' || !pathExists(store.storeRoot))
         return [];
     const docs = [];
-    const found = [];
-    const stack = [dir];
-    while (stack.length) {
-        const d = stack.pop();
-        let entries;
-        try {
-            entries = readdirSync(d, { withFileTypes: true });
-        }
-        catch {
-            continue;
-        }
-        for (const e of entries) {
-            // Enumeration stops at store boundaries: a nested `.crouter/` is another
-            // scope's mount point (e.g. a dir-scoped store inside a dir that is itself
-            // a store, like builtin-memory in the crouter repo), never this store's
-            // own content — walking into it would register a different tier's docs.
-            if (e.isDirectory()) {
-                if (e.name !== CRTR_DIR_NAME)
-                    stack.push(join(d, e.name));
-            }
-            else if (e.isFile() && e.name.endsWith('.md') && e.name !== 'SKILL.md') {
-                const file = join(d, e.name);
-                const raw = relative(dir, file).replace(/\.md$/i, '').split(sep).join('/');
-                const name = normalizeDocName(raw);
-                if (name)
-                    found.push({ path: file, name });
-            }
-        }
-    }
-    for (const { path, name } of found) {
+    for (const path of walkFiles(store.storeRoot, (n) => n.endsWith('.md') && n !== 'SKILL.md', (d) => d === CRTR_DIR_NAME)) {
+        const physicalRelativePath = relative(store.storeRoot, path).split(sep).join('/');
         // COLLECTION layer: the strict frontmatter parser throws on invalid YAML.
-        // Isolate one malformed doc with a clear scoped notice + skip, so a single
-        // bad file can't brick `memory list`/`find` or the substrate boot render.
-        // `quiet` suppresses the notice for a targeted resolve (a leaf-name read),
-        // where another doc's health is irrelevant noise before the result.
+        // Isolate one malformed doc with a scoped notice + skip, so a single bad
+        // file can't brick `memory list`/`find` or the substrate boot render.
+        // `quiet` suppresses the notice for a targeted resolve, where another doc's
+        // health is noise before the result.
         try {
-            docs.push(loadMemoryDoc(scope, dir, path, name, projectMemory));
+            const doc = loadMemoryDoc(store, path, physicalRelativePath);
+            if (doc === null) {
+                if (!quiet)
+                    warn(`${path}: a root ${INDEX_SEGMENT}.md has no canonical name in a store without a namespace`);
+                continue;
+            }
+            docs.push(doc);
         }
         catch (e) {
-            const msg = (e instanceof Error ? e.message : String(e)).split('\n')[0];
             if (!quiet)
-                warn(`invalid frontmatter in ${path}: ${msg}`);
+                warn(`invalid frontmatter in ${path}: ${firstLine(e)}`);
         }
     }
-    return docs.sort((a, b) => a.name.localeCompare(b.name));
+    return docs.sort(compareDocs);
 }
-/** All native memory docs for a scope. Project scope is a nearest-first stack of
- *  every ancestor `.crouter/memory/` (widened by a selected profile's project
- *  stack); profile is the selected profile's own singleton store, resolved
- *  through `loadProfileManifest`; user and builtin are singleton stores. */
-export function listMemoryDocs(scope, quiet = false) {
-    const target = ambientTarget();
-    if (scope === 'project') {
-        return listProjectMemoryDocs(target.cwd, target.profileId, quiet);
-    }
-    if (scope === 'profile') {
-        const profileId = target.profileId ?? '';
-        if (profileId === '')
-            return [];
-        try {
-            const { profileId: resolvedId } = loadProfileManifest(profileId);
-            return listMemoryDocsInDir('profile', profileMemoryDir(resolvedId), quiet);
-        }
-        catch {
-            return [];
-        }
-    }
-    if (scope === 'node') {
-        const nodeId = target.nodeId ?? '';
-        if (nodeId === '')
-            return [];
-        return listMemoryDocsInDir('node', nodeMemoryDir(nodeId), quiet);
-    }
-    return listMemoryDocsInDir(scope, scopeMemoryDir(scope), quiet);
-}
-/** All of one plugin's substrate docs, mounted under the virtual `<pluginName>/`
- *  namespace. Walks `pluginMemoryDir(plugin)` recursively for *.md, deriving each
- *  doc's name exactly as `listMemoryDocs` does (path-relative, no extension,
- *  slash-separated) then prefixing the plugin name. Builtin has no plugins. */
+/** All of one plugin's substrate docs, mounted under the plugin's own name:
+ *  each doc's store-local name (explicit or path-derived) composes under that
+ *  mount prefix. */
 export function listPluginMemoryDocs(plugin, scope, quiet = false, projectMemory = NEUTRAL_PROJECT_MEMORY) {
-    const dir = pluginMemoryDir(plugin);
-    if (!pathExists(dir))
-        return [];
+    return loadStoreMemoryDocs(pluginStoreDescriptor(plugin, scope, projectMemory), quiet);
+}
+// ---------------------------------------------------------------------------
+// Views: exact canonical resolution over a loaded corpus.
+// ---------------------------------------------------------------------------
+/** The canonical form of a query: empty segments dropped. An `NN-` ordering
+ *  prefix is physical-path-only and is NOT stripped here — a canonical name
+ *  never carries one, so `04-base` is simply no document's address. */
+function normalizeQuery(rawName) {
+    return canonicalSegments(rawName.trim()).join('/');
+}
+function notFoundError(rawName, name, scope) {
+    const segments = canonicalSegments(name);
+    const collapsedIndex = segments[segments.length - 1] === INDEX_SEGMENT;
+    if (collapsedIndex)
+        segments.pop();
+    const leaf = segments[segments.length - 1] ?? name;
+    const next = collapsedIndex
+        ? `A directory's own document answers at the directory name — drop the trailing /${INDEX_SEGMENT}. Run \`crtr memory find ${leaf}\` to find the canonical name.`
+        : `Resolution takes the full canonical name (a project doc is <namespace>/<local name>). Run \`crtr memory find ${leaf}\` to find it.`;
+    return notFound(`memory document not found: ${rawName}`, { memory: name, ...(scope ? { scope } : {}), next });
+}
+function makeView(stores, docs, scope) {
+    const candidatesFor = (rawName, opts) => {
+        const name = normalizeQuery(rawName);
+        if (name === '')
+            return null;
+        const kind = opts?.kind;
+        const candidates = docs.filter((d) => d.name === name && (kind === undefined || effectiveDocKind(d) === kind));
+        if (candidates.length === 0)
+            return null;
+        return { name, winner: candidates[0], candidates };
+    };
+    return {
+        stores,
+        docs,
+        candidates: candidatesFor,
+        candidateSets(opts) {
+            const kind = opts?.kind;
+            const grouped = new Map();
+            for (const doc of docs) {
+                if (kind !== undefined && effectiveDocKind(doc) !== kind)
+                    continue;
+                const bucket = grouped.get(doc.name);
+                if (bucket)
+                    bucket.push(doc);
+                else
+                    grouped.set(doc.name, [doc]);
+            }
+            return [...grouped.entries()]
+                .sort(([a], [b]) => a.localeCompare(b))
+                .map(([name, candidates]) => ({ name, winner: candidates[0], candidates }));
+        },
+        resolve(rawName, opts) {
+            const name = normalizeQuery(rawName);
+            if (name === '')
+                throw usage('memory document name required');
+            const set = candidatesFor(name, opts);
+            if (set === null)
+                throw notFoundError(rawName, name, scope);
+            return set.winner;
+        },
+    };
+}
+/** Load one target's whole corpus: every mounted store's documents in source
+ *  order. A project store that does not mount is reported once (unless quiet)
+ *  with its migration remedy and contributes nothing. */
+export function loadMemoryTargetView(target, opts = {}) {
+    const quiet = opts.quiet ?? false;
+    const stores = memoryStoresInPrecedence(target, opts.scope, opts.includeDescendants ?? false);
     const docs = [];
-    for (const file of walkFiles(dir, (n) => n.endsWith('.md') && n !== 'SKILL.md', (d) => d === CRTR_DIR_NAME)) {
-        const derived = normalizeDocName(relative(dir, file).replace(/\.md$/i, '').split(sep).join('/'));
-        if (!derived)
+    for (const store of stores) {
+        if (store.mountStatus === 'absent')
+            continue;
+        if (store.mountStatus !== 'ready') {
+            if (!quiet && store.diagnostic !== undefined)
+                warn(`memory store not mounted: ${store.diagnostic}`);
             continue;
-        const name = `${plugin.name}/${derived}`;
-        try {
-            docs.push({ ...loadMemoryDoc(scope, dir, file, name, projectMemory), plugin: plugin.name });
-        }
-        catch (e) {
-            const msg = (e instanceof Error ? e.message : String(e)).split('\n')[0];
-            if (!quiet)
-                warn(`invalid frontmatter in ${file}: ${msg}`);
         }
+        docs.push(...loadStoreMemoryDocs(store, quiet));
     }
-    return docs.sort((a, b) => a.name.localeCompare(b.name));
+    return { target, ...makeView(stores, docs, opts.scope) };
 }
-/** All docs belonging to a single resolved source: native docs first, then
- *  enabled-plugin docs — native wins on a first-wins dedup within the source.
- *  Shared by `listAllMemoryDocs` (flattens every source) and `resolveMemoryDoc`
- *  (consults one source's docs at a time, nearest source first). */
-function sourceMemoryDocs(source, quiet = false) {
-    return [
-        ...listMemoryDocsInDir(source.scope, source.memoryDir, quiet, source.projectMemory),
-        ...source.plugins.flatMap((p) => listPluginMemoryDocs(p, source.scope, quiet, source.projectMemory)),
-    ];
+/** Load ONE exact physical store. An undeclared/invalid project store loads
+ *  under the empty namespace so lint and migration can inspect what it holds;
+ *  no target view ever sees those documents. */
+export function loadMemoryStoreView(store, quiet = false) {
+    return { store, ...makeView([store], loadStoreMemoryDocs(store, quiet)) };
 }
+// ---------------------------------------------------------------------------
+// Corpus listing.
+// ---------------------------------------------------------------------------
 /** All project-scoped docs visible from an explicit node workspace/profile — the
  *  project-only slice of a `MemoryTarget` view, used where only workspace docs
  *  are wanted (a workspace-open render). For a full-precedence target-addressed
  *  lookup, use `resolveMemoryDocForTarget`. */
 export function listProjectMemoryDocs(startDir = process.cwd(), profileId = selectedProfileId() || null, quiet = false) {
-    return projectScopeRootsWithMemory(startDir, profileId).flatMap(({ root, memory }) => sourceMemoryDocs({
-        scope: 'project',
-        memoryDir: join(root, 'memory'),
-        plugins: listInstalledPluginsInRoot('project', root).filter((plugin) => plugin.enabled),
-        projectMemory: memory,
-    }, quiet));
+    return [
+        ...loadMemoryTargetView({ cwd: startDir, profileId, nodeId: null }, { scope: 'project', quiet }).docs,
+    ];
 }
 /** All memory docs across the resolved sources, in precedence order: each
  *  ancestor project `.crouter/` from nearest to farthest, then the selected
  *  profile's memory (if any), then user, then builtin. Within each source,
- *  native docs are emitted before enabled-plugin docs, so native wins on the
- *  caller's first-wins dedup. */
+ *  native docs are emitted before enabled-plugin docs, and equal-canonical
+ *  candidates stay in source order, so a caller's first-wins dedup yields the
+ *  address winners. */
 export function listAllMemoryDocs(scope, quiet = false, includeDescendants = false) {
-    return memorySourcesInPrecedence(ambientTarget(), scope, includeDescendants).flatMap((source) => sourceMemoryDocs(source, quiet));
+    return [...loadMemoryTargetView(ambientTarget(), { ...(scope ? { scope } : {}), quiet, includeDescendants }).docs];
+}
+export function createMemoryDocSnapshot(target = ambientTarget()) {
+    // Quiet: a snapshot feeds command registration and migration planning, where
+    // another doc's frontmatter health is noise — corpus health is `lint`'s job.
+    const view = loadMemoryTargetView(target, { quiet: true });
+    return {
+        docs: view.docs,
+        resolve: (names) => {
+            const resolved = new Map();
+            for (const rawName of names) {
+                const set = view.candidates(rawName);
+                // A command registration reports its own body-read failure; one
+                // malformed/stale identity must not suppress every other slash command.
+                if (set !== null)
+                    resolved.set(rawName, set.winner);
+            }
+            return resolved;
+        },
+    };
+}
+/** Resolve several canonical names over one memory-source snapshot. Failed
+ * names are omitted so callers can preserve their per-document error behavior. */
+export function resolveMemoryDocs(names) {
+    return createMemoryDocSnapshot().resolve(names);
 }
+/** The address winner for an exact canonical name in the ambient target. */
+export function resolveMemoryDoc(rawName, opts = {}) {
+    return resolveMemoryDocForTarget(rawName, ambientTarget(), opts);
+}
+/** Resolve a memory document as ANOTHER node would see it — the same precedence
+ *  chain (node-local > project stack > profile > user > builtin), read from the
+ *  target's cwd/profile/node rather than the host process's. This is what crtrd
+ *  resolves a `[[name]]` link through: the daemon's own cwd and env name no
+ *  node, and the same name can be a different document for two nodes. */
+export function resolveMemoryDocForTarget(rawName, target, opts = {}) {
+    return resolveMemoryCandidatesForTarget(rawName, target, opts).winner;
+}
+/** Every physical candidate for an exact canonical name in the ambient target,
+ *  in source order — what path-aware inventory, diagnostics, and automatic
+ *  event eligibility consume instead of the winner alone. */
+export function resolveMemoryCandidates(rawName, opts = {}) {
+    return resolveMemoryCandidatesForTarget(rawName, ambientTarget(), opts);
+}
+export function resolveMemoryCandidatesForTarget(rawName, target, opts = {}) {
+    const view = loadMemoryTargetView(target, { ...opts, quiet: true });
+    const name = normalizeQuery(rawName);
+    if (name === '')
+        throw usage('memory document name required');
+    const set = view.candidates(name, opts);
+    if (set === null)
+        throw notFoundError(rawName, name, opts.scope);
+    return set;
+}
+/** The address winner for an exact canonical name inside ONE project store —
+ *  the `--dir` selector's resolution. The query is still the full canonical
+ *  name, including that store's namespace. */
+export function resolveMemoryDocInStore(rawName, store, opts = {}) {
+    return loadMemoryStoreView(store, true).resolve(rawName, opts);
+}
+// ---------------------------------------------------------------------------
+// Physical sidecar lookup: the revision log mirrors the doc tree, so it is
+// addressed by PHYSICAL path segments, not by canonical identity.
+// ---------------------------------------------------------------------------
 /** Find the direct child of `dir` — an `ext` file (matched on name minus
  *  extension) or a directory — whose NORMALIZED display name equals
  *  `segment`. An exact literal match (no prefix to strip) wins over a
@@ -309,215 +584,26 @@ function matchNormalizedChild(dir, segment, want, ext = '.md') {
     return normalizedHit;
 }
 /** Resolve a NORMALIZED (numeric-prefix-stripped) segment path against a
- *  physical memory dir: walk intermediate segments matching each as a
- *  directory by normalized name, then resolve the final segment as either a
- *  `.md` file or a directory. Either half is null when
- *  the segment path does not resolve that way. This is what makes
- *  `00-runtime-base/00-authoring.md` findable as `runtime-base/authoring` and `01-spine/00-has-manager`
- *  findable as `spine/has-manager` — the physical path keeps its pins, only
- *  lookup is prefix-blind. */
-function resolveNormalizedPath(baseDir, segments, ext = '.md') {
+ *  physical dir: walk intermediate segments matching each as a directory by
+ *  normalized name, then resolve the final segment as an `ext` file. Null when
+ *  the segment path does not resolve. This is what keeps a sidecar findable
+ *  when its physical path carries ordering pins — `00-topic.md` logged at
+ *  `.history/00-topic.jsonl` still answers to `topic`. */
+function resolveNormalizedFile(baseDir, segments, ext) {
     let curDir = baseDir;
     for (let i = 0; i < segments.length - 1; i++) {
         const next = matchNormalizedChild(curDir, segments[i], 'dir', ext);
         if (!next)
-            return { filePath: null, dirPath: null };
+            return null;
         curDir = next;
     }
-    const last = segments[segments.length - 1];
-    return {
-        filePath: matchNormalizedChild(curDir, last, 'file', ext),
-        dirPath: matchNormalizedChild(curDir, last, 'dir', ext),
-    };
+    return matchNormalizedChild(curDir, segments[segments.length - 1], 'file', ext);
 }
-/** Resolve a document NAME against a `.history` tree, which mirrors the doc
- *  tree segment for segment with `.jsonl` in place of `.md`. Reuses the doc
- *  resolution rules so a log outlives its doc under the same name the doc had:
- *  numeric prefixes stay prefix-blind (`00-topic.md` logged at
- *  `.history/00-topic.jsonl` still answers to `topic`). Returns null when
- *  nothing resolves. */
+/** Resolve PHYSICAL path segments against a `.history` tree, which mirrors the
+ *  doc tree segment for segment with `.jsonl` in place of `.md`. A log outlives
+ *  its document, so this lookup cannot go through document resolution. */
 export function resolveHistoryLogPath(historyDir, segments) {
-    return resolveNormalizedPath(historyDir, segments, '.jsonl').filePath;
-}
-/** Direct full-path lookup of memory/<name>.md within ONE source. Returns that
- *  source's single hit, or undefined — a source can produce at most one direct
- *  match (native wins over plugin within the source, and at most one plugin's
- *  name can match). A directory name matches NO doc here: the read leaf
- *  answers a directory with its listing, never a stand-in document.
- *
- *  `name`'s segments are already normalized (a caller-supplied identifier is
- *  never authored with a numeric prefix); resolution against the physical tree
- *  is prefix-blind via `resolveNormalizedPath` so a normalized name finds an
- *  `NN-`-pinned physical file/dir. */
-function findMemoryMatchInSource(name, segments, source, legacyDirectoryIndex = false) {
-    const isLegacySkillDoc = segments.at(-1) === 'SKILL';
-    // Native memory dir first inside this source (native-before-plugin
-    // precedence), then its enabled plugins.
-    const dir = source.memoryDir;
-    if (dir) {
-        const { filePath, dirPath } = resolveNormalizedPath(dir, segments);
-        if (!isLegacySkillDoc && filePath !== null)
-            return loadMemoryDoc(source.scope, dir, filePath, name, source.projectMemory);
-        if (legacyDirectoryIndex && dirPath !== null) {
-            const indexPath = join(dirPath, 'INDEX.md');
-            if (pathExists(indexPath))
-                return loadMemoryDoc(source.scope, dir, indexPath, name, source.projectMemory);
-        }
-    }
-    // Plugin memory dir: a `<plugin>/<rest>` name resolves against that enabled
-    // plugin's memory/ tree (the `<pluginName>/` mount that listAllMemoryDocs
-    // enumerates — `read` must resolve what `list` shows).
-    const slash = name.indexOf('/');
-    if (slash <= 0 && !legacyDirectoryIndex)
-        return undefined;
-    const pluginName = slash > 0 ? name.slice(0, slash) : name;
-    const rest = slash > 0 ? name.slice(slash + 1) : '';
-    for (const p of source.plugins) {
-        if (p.name !== pluginName)
-            continue;
-        const pdir = pluginMemoryDir(p);
-        const restSegments = rest === '' ? [] : rest.split('/');
-        if (restSegments.length > 0) {
-            const { filePath } = resolveNormalizedPath(pdir, restSegments);
-            if (restSegments.at(-1) !== 'SKILL' && filePath !== null)
-                return loadMemoryDoc(source.scope, pdir, filePath, name, source.projectMemory);
-        }
-        if (legacyDirectoryIndex) {
-            const indexDir = rest === '' ? pdir : resolveNormalizedPath(pdir, restSegments).dirPath;
-            if (indexDir !== null) {
-                const indexPath = join(indexDir, 'INDEX.md');
-                if (pathExists(indexPath))
-                    return loadMemoryDoc(source.scope, pdir, indexPath, name, source.projectMemory);
-            }
-        }
-    }
-    return undefined;
-}
-function formatLeafAmbiguous(leaf, matches) {
-    const ids = matches.map(memoryDocId).join(', ');
-    return `ambiguous memory document: ${leaf} matches multiple documents: ${ids}`;
-}
-function loadMemorySources(target, scope, includeDescendants = false) {
-    // Quiet: a targeted read must not spew other docs' frontmatter warnings
-    // before its own result (esp. a not_found) — corpus health is `lint`'s job.
-    return memorySourcesInPrecedence(target, scope, includeDescendants).map((source) => ({
-        source,
-        docs: sourceMemoryDocs(source, true),
-    }));
-}
-export function createMemoryDocSnapshot(target = ambientTarget()) {
-    const defaultSources = loadMemorySources(target);
-    const sourcesByScope = new Map([[undefined, defaultSources]]);
-    const sourceFor = (scope) => {
-        let sources = sourcesByScope.get(scope);
-        if (sources === undefined) {
-            sources = loadMemorySources(target, scope);
-            sourcesByScope.set(scope, sources);
-        }
-        return sources;
-    };
-    return {
-        docs: defaultSources.flatMap(({ docs }) => docs),
-        resolve: (names) => {
-            const resolved = new Map();
-            for (const rawName of names) {
-                try {
-                    const parsed = parseSkillQualifier(rawName);
-                    resolved.set(rawName, resolveMemoryDocFromSources(rawName, {}, sourceFor(parsed.scope)));
-                }
-                catch {
-                    // A command registration reports its own body-read failure below; one
-                    // malformed/stale identity must not suppress every other slash command.
-                }
-            }
-            return resolved;
-        },
-        legacyDirectoryIndex: (name) => {
-            if (name === 'INDEX' || name.endsWith('/INDEX'))
-                return null;
-            try {
-                const parsed = parseSkillQualifier(name);
-                const sources = sourceFor(parsed.scope);
-                const legacy = resolveMemoryDocFromSources(name, {}, sources, true);
-                if (basename(legacy.path) !== 'INDEX.md')
-                    return null;
-                const explicitName = `${name}/INDEX`;
-                const explicit = resolveMemoryDocFromSources(explicitName, {}, sources);
-                return explicit.path === legacy.path ? explicitName : null;
-            }
-            catch {
-                return null;
-            }
-        },
-    };
-}
-function resolveMemoryDocFromSources(rawName, opts, sources, legacyDirectoryIndex = false) {
-    const parsed = parseSkillQualifier(rawName);
-    if (parsed.scope && opts.scope && parsed.scope !== opts.scope) {
-        throw usage(`scope conflict: identifier "${rawName}" uses scope "${parsed.scope}" but --scope is "${opts.scope}"`);
-    }
-    const name = parsed.segments.join('/');
-    if (name === '')
-        throw usage(`memory document name required`);
-    const segments = name.split('/');
-    const isLeafQuery = !name.includes('/');
-    const kindOk = (d) => opts.kind === undefined || effectiveDocKind(d) === opts.kind;
-    // Strong matches across the full scope stack come first. This preserves
-    // nearest-scope shadowing for canonical/direct collisions without allowing a
-    // nested plugin template's leaf to hide a user doc whose full identity is the
-    // query.
-    for (const { source, docs } of sources) {
-        const identity = docs.find((d) => d.name === name);
-        if (identity && kindOk(identity))
-            return identity;
-        const direct = findMemoryMatchInSource(name, segments, source, legacyDirectoryIndex);
-        if (direct && kindOk(direct))
-            return direct;
-    }
-    if (isLeafQuery) {
-        for (const { docs } of sources) {
-            const leafMatches = docs.filter((d) => (d.name.split('/').pop() ?? d.name) === name && kindOk(d));
-            if (leafMatches.length === 0)
-                continue;
-            // Same path-derived name within this source → precedence wins (return
-            // first); genuinely different docs sharing a leaf → ambiguous.
-            const distinctNames = new Set(leafMatches.map((d) => d.name));
-            if (distinctNames.size === 1)
-                return leafMatches[0];
-            throw ambiguous(formatLeafAmbiguous(name, leafMatches), {
-                memory: name,
-                candidates: leafMatches.map((d) => ({
-                    id: memoryDocId(d),
-                    scope: d.scope,
-                    path: d.path,
-                })),
-                next: 'Multiple documents share this leaf name. Re-run with one of the full names in candidates.',
-            });
-        }
-    }
-    throw notFound(`memory document not found: ${rawName}`, {
-        memory: name,
-        scope: parsed.scope,
-    });
-}
-/** Resolve several unqualified names over one memory-source snapshot. Failed
- * names are omitted so callers can preserve their per-document error behavior. */
-export function resolveMemoryDocs(names) {
-    return createMemoryDocSnapshot().resolve(names);
-}
-export function resolveMemoryDoc(rawName, opts = {}) {
-    return resolveMemoryDocForTarget(rawName, ambientTarget(), opts);
-}
-/** Resolve a memory document as ANOTHER node would see it — the same precedence
- *  chain (node-local > project stack > profile > user > builtin), read from the
- *  target's cwd/profile/node rather than the host process's. This is what crtrd
- *  resolves a `[[name]]` link through: the daemon's own cwd and env name no
- *  node, and the same name can be a different document for two nodes. */
-export function resolveMemoryDocForTarget(rawName, target, opts = {}) {
-    const parsed = parseSkillQualifier(rawName);
-    if (parsed.scope && opts.scope && parsed.scope !== opts.scope) {
-        throw usage(`scope conflict: identifier "${rawName}" uses scope "${parsed.scope}" but --scope is "${opts.scope}"`);
-    }
-    const effectiveScope = opts.scope ?? parsed.scope;
-    return resolveMemoryDocFromSources(rawName, opts, loadMemorySources(target, effectiveScope, opts.includeDescendants ?? false));
+    if (segments.length === 0)
+        return null;
+    return resolveNormalizedFile(historyDir, segments, '.jsonl');
 }