@north-light/crouter 0.3.227 → 0.3.229

package/dist/commands/memory/delete.js

@@ -3,22 +3,41 @@ import { resolve as resolvePath } from 'node:path';
 import { defineLeaf } from '../../core/command.js';
 import { CrtrError, notFound, usage } from '../../core/errors.js';
 import { readText } from '../../core/fs-utils.js';
-import { resolveMemoryDoc } from '../../core/memory-resolver.js';
+import { loadMemoryStoreView, resolveMemoryCandidates } from '../../core/memory-resolver.js';
 import { appendHistoryRecord, buildHistoryRecord, historyLogPathFor } from '../../core/memory/history.js';
-import { MEMORY_SCOPES, pruneEmptyParents } from './shared.js';
+import { MEMORY_WRITE_SCOPES, pruneEmptyParents, requireMountedStore, selectMutationDoc, resolveReadSelector, selectorParam, } from './shared.js';
+/** Every physical document owning that exact canonical identity — in the target
+ *  view, or inside the one store `--dir` selected — or null when nothing
+ *  answers to the name. */
+function targetCandidates(rawName, scope, storeView) {
+    if (storeView !== null)
+        return storeView.candidates(rawName);
+    try {
+        return resolveMemoryCandidates(rawName, {
+            includeDescendants: true,
+            ...(scope !== undefined ? { scope } : {}),
+        });
+    }
+    catch (e) {
+        if (e instanceof CrtrError && e.code === 'not_found')
+            return null;
+        throw e; // usage propagates with its own recovery guidance
+    }
+}
 export const deleteLeaf = defineLeaf({
     name: 'delete',
     description: 'delete a memory document by name',
-    whenToUse: 'a stored document is wrong, obsolete, or superseded and should be removed — the sanctioned way to delete one, so you never rm the markdown off disk. Resolves the name exactly as `read` does (exact/direct matches by node > project stack > profile > user precedence, then leaf-name fallback) and removes that file: if you can read it, you can delete it. Refuses docs you do not own — builtin docs (shipped with the package) and installed-plugin docs (managed by `crtr pkg`) — and refuses an ambiguous leaf name rather than guessing which doc to destroy; pass the full `area/topic` name or `--scope` to pin one.',
+    whenToUse: 'a stored document is wrong, obsolete, or superseded and should be removed — the sanctioned way to delete one, so you never rm the markdown off disk. Resolves the full canonical name exactly as `read` does and removes that one file: if you can read it, you can delete it. Refuses docs you do not own — builtin docs (shipped with the package) and installed-plugin docs (managed by `crtr pkg`). If two physical files in the selected store share the name, it selects the first physical path in stable lexical order and recovers the collision.',
     help: {
         name: 'memory delete',
-        summary: 'resolve a path-derived name and remove that document from its scope store',
+        summary: 'resolve an exact canonical name and remove that document from its store',
         params: [
-            { kind: 'positional', name: 'name', required: true, constraint: 'Path-derived memory identifier (e.g. `topic` or `area/topic`), resolved as `read` resolves it: exact identity/direct path by precedence node > project stack > profile > user, then bare leaf fallback. A leaf matching multiple different docs in one source is rejected as ambiguous — pass the full name or --scope to disambiguate. May be scope-prefixed (`user/topic`) to pin the store directly.' },
-            { kind: 'flag', name: 'scope', type: 'enum', choices: [...MEMORY_SCOPES], required: false, constraint: 'Restrict resolution to this scope before deleting. Use it to disambiguate a leaf name present at multiple scopes, or to assert which store you mean. builtin is not a choice — builtin docs ship with the package and cannot be deleted.' },
+            { kind: 'positional', name: 'name', required: true, constraint: 'Full canonical name of the document — a project document is `<namespace>/<local name>`. Resolution is exact, as `read` resolves it: a file path, a bare leaf, a `<scope>/<name>` spelling, and a trailing `/INDEX` all fail. A canonical directory’s own document is deleted at the directory name; its members are untouched and stay reachable. If two physical files in the selected store own the name, delete selects the first path in stable lexical order and reports it. Builtin and installed-plugin documents are read-only and refuse to delete, as does the repository-root document, which declares the immutable namespace for every document in the repository; a nested store’s root guide is ordinary and may be deleted.' },
+            selectorParam('scope-read', { choices: [...MEMORY_WRITE_SCOPES] }, 'builtin is not a choice — builtin documents ship with the package and cannot be deleted.'),
+            selectorParam('dir', {}, 'Deletes from that one store, including a non-winning duplicate no target view resolves to.'),
         ],
         output: [
-            { name: 'name', type: 'string', required: true, constraint: 'Path-derived name of the deleted document.' },
+            { name: 'name', type: 'string', required: true, constraint: 'Canonical name of the deleted document.' },
             { name: 'scope', type: 'string', required: true, constraint: 'Scope the document was deleted from: node, user, project, or profile.' },
             { name: 'path', type: 'string', required: true, constraint: 'Absolute path of the file that was removed.' },
             { name: 'deleted', type: 'boolean', required: true, constraint: 'Always true on success — the file was removed. A missing document fails with not_found instead.' },
@@ -27,39 +46,47 @@ export const deleteLeaf = defineLeaf({
         ],
         outputKind: 'object',
         effects: [
-            'Permanently removes memory/<name>.md from the resolved scope store, and prunes any parent directories it leaves empty. Irreversible.',
-            'Appends a `delete` record carrying the document’s full final text to memory/.history/<name>.jsonl. The log itself is never removed.',
+            'Permanently removes the resolved file from its store, and prunes any parent directories it leaves empty. Irreversible. Refuses the repository-root document: it declares the immutable `namespace:` every document in this repository composes under, so removing it would unmount the whole repository.',
+            'Appends a `delete` record carrying the document’s full final text to `.history/<physical path>.jsonl` in the same store. The log itself is never removed.',
         ]
     },
     run: async (input) => {
         const nameRaw = input['name'];
         const scopeArg = input['scope'];
-        let doc;
-        try {
-            doc = resolveMemoryDoc(nameRaw, { includeDescendants: true, ...(scopeArg !== undefined ? { scope: scopeArg } : {}) });
-        }
-        catch (e) {
-            if (e instanceof CrtrError && e.code === 'not_found') {
-                throw notFound(`memory document not found: ${nameRaw}`, {
-                    memory: nameRaw,
-                    next: 'Run `crtr memory find <query>` to locate it, or `crtr memory list` to browse the inventory. If it exists at another scope, pass --scope.',
-                });
-            }
-            throw e; // ambiguous / usage propagate with their own recovery guidance
+        const dirArg = input['dir'];
+        const selector = resolveReadSelector({ scope: scopeArg, dir: dirArg });
+        const storeView = selector.store === null ? null : loadMemoryStoreView(requireMountedStore(selector.store), true);
+        const set = targetCandidates(nameRaw, selector.scope, storeView);
+        if (set === null) {
+            throw notFound(`memory document not found: ${nameRaw}`, {
+                memory: nameRaw,
+                next: 'A delete takes the full canonical name (a project document is <namespace>/<local name>), and a directory’s own document answers at the directory name. Run `crtr memory find <leaf>` to look it up, or pass --dir to reach one exact project store.',
+            });
         }
+        const selected = selectMutationDoc(set);
+        const doc = selected.doc;
         if (doc.plugin !== undefined) {
             throw usage(`${doc.name} belongs to the installed plugin "${doc.plugin}" — it is not a scope doc and cannot be deleted here. Manage plugin docs with \`crtr pkg\`. To override just this doc, write a same-named doc at a writable scope (\`crtr memory write ${doc.name} ...\`).`, { memory: doc.name, plugin: doc.plugin });
         }
         if (doc.scope === 'builtin') {
             throw usage(`${doc.name} is a builtin document shipped with the package (read-only) — it cannot be deleted. Override it with a same-named doc at a writable scope instead (\`crtr memory write ${doc.name} ...\`).`, { memory: doc.name, scope: 'builtin' });
         }
+        // Only the repository-root document declares the namespace and is
+        // immutable through the memory commands.
+        if (doc.localName === '' && doc.store.ownerRelativePath === '') {
+            throw usage(`${doc.name} is the repository-root document at ${doc.path}, which declares the namespace every document in this repository composes under — deleting it would unmount the whole repository, so it cannot be deleted.`, {
+                memory: doc.name,
+                path: doc.path,
+                next: `Delete the documents under \`${doc.name}/\` individually, or revise the repository-root document with \`crtr memory edit ${doc.name} --rationale "<why>"\`.`,
+            });
+        }
         const before = readText(doc.path);
         const logPath = historyLogPathFor(doc.root, doc.path);
         rmSync(doc.path);
-        pruneEmptyParents(resolvePath(doc.path), doc.name.split('/').length);
+        pruneEmptyParents(resolvePath(doc.path), doc.physicalRelativePath.split('/').length);
         // The log is the audit trail and outlives the doc: the tombstone carries the
         // full final text, and a later `write` of the same name keeps appending to
-        // this same log — one log per name over its whole life.
+        // this same log — one log per physical path over its whole life.
         appendHistoryRecord(logPath, buildHistoryRecord({ op: 'delete', before, after: '' }));
         return {
             name: doc.name,
@@ -67,7 +94,7 @@ export const deleteLeaf = defineLeaf({
             path: doc.path,
             deleted: true,
             log_path: logPath,
-            follow_up: `Removed. Its revision history survives — read it with \`crtr memory history ${doc.name}\`, or browse what remains with \`crtr memory list\`.`,
+            follow_up: `Removed${selected.collisionPaths.length > 0 ? ` the first physical path in stable lexical order (${doc.path}) to recover a same-store collision.` : '.'} Its revision history survives — read it with \`crtr memory history ${doc.name}\`, or browse what remains with \`crtr memory list\`.`,
         };
     },
 });

package/dist/commands/memory/edit.js

@@ -2,9 +2,9 @@ import { defineLeaf } from '../../core/command.js';
 import { CrtrError, notFound, usage } from '../../core/errors.js';
 import { parseFrontmatterGeneric } from '../../core/frontmatter.js';
 import { readText, writeText } from '../../core/fs-utils.js';
-import { resolveMemoryDoc } from '../../core/memory-resolver.js';
+import { loadMemoryStoreView, resolveMemoryCandidates, } from '../../core/memory-resolver.js';
 import { appendHistoryRecord, buildHistoryRecord, historyLogPathFor, readHistoryRecords, } from '../../core/memory/history.js';
-import { DOC_RATIONALE_CONSTRAINT, GUIDE_DOC_LINKS, GUIDE_PREDICATE_VOCABULARY, GUIDE_ROUTING_LINE, GUIDE_SURFACES, MEMORY_SCOPES, coerceGate, coerceSurface, memoryExtensionCatalogForDoc, memoryExtensionFieldCatalogHelp, overlayParam, parseRequestedExtensionChanges, applyExtensionChanges, literalBodySegment, serializeMemoryDocLiteral, } from './shared.js';
+import { DOC_RATIONALE_CONSTRAINT, GUIDE_CANONICAL_NAMES, GUIDE_DOC_LINKS, GUIDE_PREDICATE_VOCABULARY, GUIDE_ROUTING_LINE, GUIDE_SURFACES, coerceGate, coerceSurface, memoryExtensionCatalogForDoc, memoryExtensionFieldCatalogHelp, overlayParam, parseRequestedExtensionChanges, applyExtensionChanges, literalBodySegment, serializeMemoryDocLiteral, selectorParam, requireLocalNameInStore, requireUnambiguousDoc, resolveReadSelector, } from './shared.js';
 /** Frontmatter fields an overlay flag cannot express removing. `kind` and the
  *  routing line are the document's contract (a doc without them is malformed);
  *  `origin` and `last-updated` are runtime provenance. */
@@ -25,10 +25,11 @@ export const editLeaf = defineLeaf({
             GUIDE_ROUTING_LINE + '\n\n' +
             GUIDE_SURFACES + '\n\n' +
             GUIDE_PREDICATE_VOCABULARY + '\n\n' +
+            GUIDE_CANONICAL_NAMES + '\n\n' +
             GUIDE_DOC_LINKS + '\n\n' +
             'Create a document that does not exist yet with `crtr memory write`. Read the revisions back with `crtr memory history`.',
         params: [
-            { kind: 'positional', name: 'name', required: true, constraint: 'Path-derived memory identifier (e.g. `topic` or `area/topic`), resolved as `read` resolves it: exact identity/direct path by precedence node > project stack > profile > user, then bare leaf fallback. A leaf matching multiple documents in one source is rejected as ambiguous \u2014 pass the full name or --scope. Builtin and installed-plugin docs are read-only corpora and are refused.' },
+            { kind: 'positional', name: 'name', required: true, constraint: 'Full canonical identity, resolved exactly in the target view or exact project store. A project document requires its complete `<namespace>/<local name>`; a directory document answers at the directory name, never with a trailing `/INDEX`. Same-store physical collisions are refused with both paths; `--dir` selects one exact project store. Builtin and installed-plugin docs are read-only corpora and are refused.' },
             { kind: 'flag', name: 'rationale', type: 'string', required: true, constraint: 'Why THIS REVISION is happening \u2014 the audit-trail entry, required on every edit. Recorded in the document\u2019s revision history, NEVER written into the document. To change the doc\u2019s standing `rationale` frontmatter field instead, use --doc-rationale.' },
             { kind: 'flag', name: 'verbatim', type: 'bool', required: false, constraint: 'Declares the piped body a verbatim payload from the principal \u2014 their own text, relayed unchanged \u2014 rather than agent-authored prose. Pure provenance recorded in the history record; the save path is identical either way, because there is only one save path and it never transforms.' },
             overlayParam('kind'),
@@ -42,7 +43,9 @@ export const editLeaf = defineLeaf({
             { kind: 'flag', name: 'extension', type: 'string', required: false, repeatable: true, constraint: 'Set one declared plugin field as `extensions.<plugin>.<field>=VALUE`. The path is required in full; booleans accept only true or false, numbers require finite numeric syntax, and strings/enums preserve the literal text after the first =. Every requested field validates before the document is revised.' },
             { kind: 'flag', name: 'unset-extension', type: 'string', required: false, repeatable: true, constraint: 'Remove one explicitly persisted declared field by its full `extensions.<plugin>.<field>` path. A removed explicit value lets its declaration default apply only in structured output.' },
             { kind: 'flag', name: 'unset', type: 'enum', choices: [...CLEARABLE_FIELDS], required: false, repeatable: true, constraint: 'Remove a frontmatter field an overlay flag cannot express removing. One field per occurrence. `kind`, `when-and-why-to-read`, `origin`, and `last-updated` are never clearable.' },
-            { kind: 'flag', name: 'scope', type: 'enum', choices: [...MEMORY_SCOPES], required: false, constraint: 'Restrict resolution to this scope before editing. A disambiguation filter only \u2014 never a creation target, and never a way to move a doc between stores.' },
+            selectorParam('scope-read', {}, 'Edit resolves the address winner and refuses same-store physical collisions.'),
+            selectorParam('dir'),
+            selectorParam('profile'),
             { kind: 'stdin', name: 'body', required: false, constraint: 'Full replacement body (markdown, no frontmatter), saved byte for byte. Piped on stdin only \u2014 this leaf already claims the one positional for NAME. Absent or empty stdin leaves the existing body untouched, which is how a frontmatter-only revision is made.' },
         ],
         output: [
@@ -58,7 +61,7 @@ export const editLeaf = defineLeaf({
         outputKind: 'object',
         dynamicState: () => memoryExtensionFieldCatalogHelp('edit'),
         effects: [
-            'Rewrites memory/<name>.md at the resolved scope and appends one `edit` record to memory/.history/<name>.jsonl.',
+            'Rewrites the selected physical memory document and appends one `edit` record to its mirrored `.history` sidecar.'
         ],
     },
     run: async (input) => {
@@ -67,12 +70,27 @@ export const editLeaf = defineLeaf({
         const rationale = input['rationale'];
         const verbatim = input['verbatim'] === true;
         const stdinBody = input['body'] ?? '';
+        const dirArg = input['dir'];
+        const profileArg = input['profile'];
+        const selector = resolveReadSelector({ scope: scopeArg, dir: dirArg, profile: profileArg });
         let doc;
         try {
-            doc = resolveMemoryDoc(nameRaw, {
-                includeDescendants: true,
-                ...(scopeArg !== undefined ? { scope: scopeArg } : {}),
-            });
+            const set = selector.store === null
+                ? resolveMemoryCandidates(nameRaw, {
+                    includeDescendants: true,
+                    ...(selector.scope === undefined ? {} : { scope: selector.scope }),
+                })
+                : (() => {
+                    requireLocalNameInStore(selector.store, nameRaw);
+                    return loadMemoryStoreView(selector.store, true).candidates(nameRaw);
+                })();
+            if (set === null) {
+                throw notFound(`memory document not found: ${nameRaw}`, {
+                    memory: nameRaw,
+                    next: `\`edit\` revises a document that already exists. Create it with \`crtr memory write ${nameRaw} ...\`, or run \`crtr memory find <query>\` if it exists under another name.`,
+                });
+            }
+            doc = requireUnambiguousDoc(set);
         }
         catch (e) {
             if (e instanceof CrtrError && e.code === 'not_found') {
@@ -81,7 +99,7 @@ export const editLeaf = defineLeaf({
                     next: `\`edit\` revises a document that already exists. Create it with \`crtr memory write ${nameRaw} ...\`, or run \`crtr memory find <query>\` if it exists under another name.`,
                 });
             }
-            throw e; // ambiguous / usage propagate with their own recovery guidance
+            throw e;
         }
         if (doc.plugin !== undefined) {
             throw usage(`${doc.name} belongs to the installed plugin "${doc.plugin}" \u2014 a read-only corpus managed by \`crtr pkg\`, not editable here. To override just this doc, write a same-named doc at a writable scope (\`crtr memory write ${doc.name} ...\`).`, { memory: doc.name, plugin: doc.plugin });
@@ -94,6 +112,28 @@ export const editLeaf = defineLeaf({
         const parsed = parseFrontmatterGeneric(before);
         const previous = { ...(parsed.data ?? {}) };
         const frontmatter = { ...previous };
+        if (doc.scope === 'project' && doc.localName === '') {
+            if (doc.store.ownerRelativePath !== '' && Object.prototype.hasOwnProperty.call(previous, 'namespace')) {
+                throw usage(`a nested store's INDEX.md carries no namespace: — the repository at ${doc.store.repositoryRoot ?? doc.root} declares it`, {
+                    memory: doc.name,
+                    path: doc.path,
+                    next: `Run \`crtr memory lint --dir ${doc.store.ownerDir ?? doc.root}\` or \`crtr sys migrate --dir ${doc.store.repositoryRoot ?? doc.root}\`.`,
+                });
+            }
+            if (doc.store.ownerRelativePath === '' && previous['namespace'] !== doc.store.repositoryNamespace) {
+                throw usage(`the repository namespace on ${doc.path} is immutable; it must remain \`${doc.store.repositoryNamespace}\``, {
+                    memory: doc.name,
+                    path: doc.path,
+                });
+            }
+            if (previous['name'] !== undefined) {
+                throw usage(`the project root INDEX at ${doc.path} cannot carry a \`name:\` field`, {
+                    memory: doc.name,
+                    path: doc.path,
+                    next: `Run \`crtr sys migrate --dir ${doc.store.repositoryRoot ?? doc.store.ownerDir ?? doc.root}\`.`,
+                });
+            }
+        }
         const setIf = (key, value) => {
             if (value !== undefined)
                 frontmatter[key] = value;

package/dist/commands/memory/find.js

@@ -1,81 +1,99 @@
 import { defineLeaf } from '../../core/command.js';
 import { usage } from '../../core/errors.js';
-import { listAllMemoryDocs } from '../../core/memory-resolver.js';
+import { listAllMemoryDocs, loadMemoryStoreView } from '../../core/memory-resolver.js';
 import { parseSubstrateDoc } from '../../core/substrate/schema.js';
 import { paginate } from '../../core/pagination.js';
-import { MEMORY_KINDS, MEMORY_SCOPES } from './shared.js';
-function substrateUnit(d) {
-    return {
-        name: d.name,
-        kind: d.kind,
-        scope: d.scope,
-        path: d.path,
-        routing: d.whenAndWhyToRead,
-        shortForm: d.shortForm,
-        loadBody: () => d.body,
-    };
-}
-/** The candidate set: every substrate memory document (native + plugin, supplied
- *  by listAllMemoryDocs), optionally narrowed to one kind and/or one scope.
- *  Within that explicit narrowing find searches EVERYTHING — it never applies
- *  gate or visibility-rung filtering (design §11#3); --kind/--scope are caller
- *  intent, not a visibility policy.
+import { candidateRow } from './read.js';
+import { MEMORY_KINDS, registerMemoryListingExposure, requireMountedStore, resolveReadSelector, selectorParam, } from './shared.js';
+/** The search space over one corpus: every substrate memory document, narrowed
+ *  to one kind when asked. Within that narrowing find searches EVERYTHING — it
+ *  never applies gate or visibility-rung filtering; --kind/--scope/--dir are
+ *  caller intent, not a visibility policy.
  *
- *  Dedup by (scope, name): native and plugin docs of the same scope can collide
- *  on identity. The FIRST unit encountered for a given identity wins — native
- *  before plugin, which mirrors the memory resolver's own precedence. */
-function candidates(kindFilter, scopeFilter) {
-    const seen = new Set(); // "scope/name" → first wins
-    const add = (u) => {
-        const id = `${u.scope}/${u.name}`;
-        if (seen.has(id))
-            return;
-        seen.add(id);
-        units.push(u);
-    };
+ *  A target view is deduped by canonical name, first in source order wins, so a
+ *  hit names the document a read of that name returns. An exact store (`--dir`)
+ *  is not deduped: naming a store means seeing what it physically holds. */
+function searchUnits(kindFilter, docs, dedup) {
+    const byName = new Map();
+    for (const doc of docs) {
+        const bucket = byName.get(doc.name);
+        if (bucket !== undefined)
+            bucket.push(doc);
+        else
+            byName.set(doc.name, [doc]);
+    }
+    const seen = new Set();
     const units = [];
-    for (const doc of listAllMemoryDocs(scopeFilter, false, true)) {
+    for (const doc of docs) {
         const sub = parseSubstrateDoc(doc);
         if (sub === null)
             continue;
         if (kindFilter !== undefined && sub.kind !== kindFilter)
             continue;
-        add(substrateUnit(sub));
+        if (dedup) {
+            if (seen.has(sub.name))
+                continue;
+            seen.add(sub.name);
+        }
+        units.push({
+            name: sub.name,
+            localName: doc.localName,
+            kind: sub.kind,
+            scope: sub.scope,
+            path: sub.path,
+            storeRoot: doc.root,
+            physicalRelativePath: doc.physicalRelativePath,
+            routing: sub.whenAndWhyToRead,
+            shortForm: sub.shortForm,
+            candidates: byName.get(doc.name) ?? [doc],
+            loadBody: () => sub.body,
+        });
     }
     return units;
 }
+/** The physical location fields --paths adds to any hit shape. */
+function pathFields(u) {
+    return {
+        path: u.path,
+        store_root: u.storeRoot,
+        physical_relative_path: u.physicalRelativePath,
+        ...(u.candidates.length > 1 ? { candidates: u.candidates.map((c) => candidateRow(c, u.candidates[0])) } : {}),
+    };
+}
 export const findLeaf = defineLeaf({
     name: 'find',
     description: 'relevance search across memory documents',
-    whenToUse: 'you already have a topic or keyword in mind and need to find which document covers it — ranks documents by relevance, weighted over name, the read-routing line, and short-form (add --body to also weigh body text). Searches every scope by default regardless of any visibility gate; --scope narrows to one. Reach for `crtr memory list` instead when you want the whole inventory rather than a topic match, and --grep when you need an exact regex or literal-string match across document bodies.',
+    whenToUse: 'the discovery surface when you do NOT know a document\u2019s canonical name — ranks documents by relevance over the canonical name, the store-local name, the physical path, the read-routing line, and short-form (add --body to also weigh body text), and every hit reports the canonical name `crtr memory read` takes. Searches every scope by default regardless of any visibility gate; --scope narrows to one class of store, --dir to one exact store. Reach for `crtr memory list` instead when you want the whole inventory rather than a topic match, and --grep when you need an exact regex or literal-string match across document bodies.',
     help: {
         name: 'memory find',
-        summary: 'bounded relevance search across memory documents, weighted over name/routing-line/short-form (and body with --body)',
+        summary: 'bounded relevance search across memory documents, weighted over name/local name/physical path/routing-line/short-form (and body with --body)',
         params: [
-            { kind: 'positional', name: 'query', required: true, constraint: 'With ranked search (default): whitespace-separated terms, matched case-insensitively and weighted over name, the read-routing line, and short-form (plus body with --body); documents matching more/stronger fields rank higher. By default returns at most 10 hits scoring at least half the top score. With --grep: an ECMAScript regex applied to each document body line.' },
+            { kind: 'positional', name: 'query', required: true, constraint: 'With ranked search (default): whitespace-separated terms, matched case-insensitively and weighted over the document\u2019s names (canonical, store-local, and physical path), the read-routing line, and short-form (plus body with --body); documents matching more/stronger fields rank higher. By default returns at most 10 hits scoring at least half the top score. With --grep: an ECMAScript regex applied to each document body line.' },
             { kind: 'flag', name: 'kind', type: 'enum', choices: [...MEMORY_KINDS], required: false, constraint: 'Filter to a single kind. Default: all kinds.' },
-            { kind: 'flag', name: 'scope', type: 'enum', choices: [...MEMORY_SCOPES], required: false, constraint: 'Filter to a single scope. Default: all resolved scopes, builtin included.' },
+            selectorParam('scope-read', {}, 'Default: every resolved scope, builtin included.'),
+            selectorParam('dir', {}, 'Searches that store alone, and searches it physically: two documents sharing one canonical name are both searched and both reported, where the default view searches only the winner.'),
             { kind: 'flag', name: 'grep', type: 'bool', required: false, constraint: 'Treat the query as an ECMAScript regex and match it against document bodies, instead of weighted relevance ranking. Mutually exclusive with --body.' },
             { kind: 'flag', name: 'body', type: 'bool', required: false, constraint: 'Also weigh document body text in the relevance ranking (in addition to name/when/why/short-form). Ignored under --grep, which always scans bodies.' },
             { kind: 'flag', name: 'limit', type: 'int', required: false, constraint: 'Maximum hits to return per page after relevance filtering. Default 10, hard max 100.' },
             { kind: 'flag', name: 'cursor', type: 'string', required: false, constraint: 'Opaque token from next_cursor. Omit on first call.' },
             { kind: 'flag', name: 'min-score', type: 'int', required: false, constraint: 'Ranked mode only. Minimum score to return, replacing the default adaptive floor of half the top score. Must be at least 1.' },
-            { kind: 'flag', name: 'paths', type: 'bool', required: false, constraint: 'Include absolute file paths in hits. Off by default; names are sufficient for `crtr memory read <name>`.' },
+            { kind: 'flag', name: 'paths', type: 'bool', required: false, constraint: 'Include each hit\u2019s physical location — absolute path, store root, store-relative path, and every other physical document sharing its canonical name. Off by default; the canonical name is sufficient for `crtr memory read <name>`.' },
         ],
         output: [
             { name: 'query', type: 'string', required: true, constraint: 'Echo of the input query.' },
             { name: 'matches', type: 'integer', required: true, constraint: 'Total matches before the default relevance floor and limit are applied (ranked mode) or total matching lines (grep mode) — across all pages, not just this one.' },
-            { name: 'hits', type: 'object[]', required: true, constraint: 'Ranked mode — each: {name, kind, scope, score, short_form}, sorted by score descending. Grep mode — each: {name, scope, line, text}, sorted by name then line. With --paths, each shape also includes path. Paginated via --limit/--cursor.' },
+            { name: 'hits', type: 'object[]', required: true, constraint: 'Ranked mode — each: {name, kind, scope, score, short_form}, sorted by score descending. Grep mode — each: {name, scope, line, text}, sorted by name then line. `name` is always the canonical name, whatever field matched. With --paths, each shape also carries path, store_root, physical_relative_path, and candidates when several physical documents share the name. Paginated via --limit/--cursor.' },
             { name: 'next_cursor', type: 'string | null', required: true, constraint: 'Opaque token for the next page; null means no more items.' },
             { name: 'follow_up', type: 'string', required: true, constraint: 'Concrete next commands for reading a hit in full or refining the search.' },
         ],
         outputKind: 'object',
-        effects: ['None. Read-only.'],
+        effects: ['Records this search page as listing context for the current node without marking any matched document as loaded.'],
     },
     run: async (input) => {
         const query = input['query'];
         const kindFilter = input['kind'];
-        const scopeFilter = input['scope'];
+        const dirArg = input['dir'];
+        const selector = resolveReadSelector({ scope: input['scope'], dir: dirArg });
         const grep = input['grep'];
         const weighBody = input['body'];
         const limitArg = input['limit'];
@@ -93,7 +111,21 @@ export const findLeaf = defineLeaf({
         if (minScore !== undefined && minScore < 1)
             throw usage('--min-score must be at least 1.');
         const limit = limitArg ?? 10;
-        const units = candidates(kindFilter, scopeFilter);
+        const listingIdentity = `listing:memory-find:${JSON.stringify({
+            query,
+            kind: kindFilter ?? null,
+            scope: selector.scope ?? null,
+            dir: dirArg ?? null,
+            grep: grep === true,
+            body: weighBody === true,
+            limit,
+            cursor: cursor ?? null,
+            minScore: minScore ?? null,
+            paths: includePaths === true,
+        })}`;
+        const units = selector.store !== null
+            ? searchUnits(kindFilter, loadMemoryStoreView(requireMountedStore(selector.store), false).docs, false)
+            : searchUnits(kindFilter, listAllMemoryDocs(selector.scope, false, true), true);
         // --- grep mode: regex over every unit's body, one row per matching line ---
         if (grep) {
             let regex;
@@ -108,25 +140,32 @@ export const findLeaf = defineLeaf({
                 const lines = u.loadBody().split('\n');
                 lines.forEach((text, idx) => {
                     if (regex.test(text))
-                        matches.push({ name: u.name, scope: u.scope, path: u.path, line: idx + 1, text });
+                        matches.push({ name: u.name, scope: u.scope, unit: u, line: idx + 1, text });
                 });
             }
+            // Physical path is part of the identity: under --dir two documents can
+            // share one canonical name, and pagination needs unique ascending keys.
             matches.sort((a, b) => {
                 const nc = a.name.localeCompare(b.name);
                 if (nc !== 0)
                     return nc;
                 const sc = a.scope.localeCompare(b.scope);
-                return sc !== 0 ? sc : a.line - b.line;
+                if (sc !== 0)
+                    return sc;
+                const pc = a.unit.physicalRelativePath.localeCompare(b.unit.physicalRelativePath);
+                return pc !== 0 ? pc : a.line - b.line;
             });
-            const keyOf = (m) => `${m.name}:${m.scope}:${String(m.line).padStart(7, '0')}`;
+            const keyOf = (m) => `${m.name}:${m.scope}:${m.unit.physicalRelativePath}:${String(m.line).padStart(7, '0')}`;
             const page = paginate(matches, { limit, cursor }, { defaultLimit: 10, maxLimit: 100, keyOf, total: 'omit' });
-            return {
+            const output = {
                 query,
                 matches: matches.length,
-                hits: page.items.map(({ path, ...match }) => includePaths ? { ...match, path } : match),
+                hits: page.items.map(({ unit, ...match }) => (includePaths ? { ...match, ...pathFields(unit) } : match)),
                 next_cursor: page.next_cursor,
                 follow_up: 'Read a hit with `crtr memory read <name>`. Run `crtr memory find -h` for filters and verbosity.',
             };
+            registerMemoryListingExposure(listingIdentity);
+            return output;
         }
         // --- ranked mode: weighted relevance over name/routing-line/short-form(+body) ---
         const terms = query
@@ -137,13 +176,19 @@ export const findLeaf = defineLeaf({
             throw usage('query must contain at least one non-whitespace term');
         const hits = [];
         for (const u of units) {
+            // One name weight over three spellings of the same document: an agent
+            // searching a store-local name or a physical path is searching for the
+            // identity, and counting each spelling separately would inflate the band
+            // the adaptive floor is calibrated against.
             const nameLc = u.name.toLowerCase();
+            const localLc = u.localName.toLowerCase();
+            const physLc = u.physicalRelativePath.toLowerCase();
             const routingLc = u.routing.toLowerCase();
             const shortLc = u.shortForm.toLowerCase();
             const bodyLc = weighBody ? u.loadBody().toLowerCase() : null;
             let score = 0;
             for (const term of terms) {
-                if (nameLc.includes(term))
+                if (nameLc.includes(term) || localLc.includes(term) || physLc.includes(term))
                     score += 10;
                 if (routingLc.includes(term))
                     score += 5;
@@ -156,18 +201,20 @@ export const findLeaf = defineLeaf({
                 hits.push({ unit: u, score });
         }
         // Sort comparator MUST match keyOf exactly (score desc, then scope asc,
-        // then name asc as the final deterministic identity component — the
-        // candidate dedup keys on scope+name, so this pair is always unique).
-        // Sorting equal-score hits from different scopes by name alone while the
-        // cursor key orders by scope first would let the array disagree with its
-        // own keys, and paginate() would silently skip a later item.
+        // then name asc, then physical path asc — which is unique even under --dir,
+        // where two documents can share one canonical name). Sorting equal-score
+        // hits by one order while the cursor key uses another would let the array
+        // disagree with its own keys, and paginate() would silently skip an item.
         hits.sort((a, b) => {
             if (b.score !== a.score)
                 return b.score - a.score;
             const scopeCmp = a.unit.scope.localeCompare(b.unit.scope);
             if (scopeCmp !== 0)
                 return scopeCmp;
-            return a.unit.name.localeCompare(b.unit.name);
+            const nameCmp = a.unit.name.localeCompare(b.unit.name);
+            if (nameCmp !== 0)
+                return nameCmp;
+            return a.unit.physicalRelativePath.localeCompare(b.unit.physicalRelativePath);
         });
         const adaptiveFloor = hits.length === 0 ? 1 : Math.max(1, Math.ceil(hits[0].score / 2));
         const floor = minScore ?? adaptiveFloor;
@@ -175,9 +222,9 @@ export const findLeaf = defineLeaf({
         // relevant is already sorted score-desc/scope-asc/name-asc, which is
         // exactly ascending order by this key (higher score → smaller key),
         // satisfying paginate's ascending-key precondition.
-        const keyOf = (h) => `${String(1_000_000 - h.score).padStart(7, '0')}:${h.unit.scope}:${h.unit.name}`;
+        const keyOf = (h) => `${String(1_000_000 - h.score).padStart(7, '0')}:${h.unit.scope}:${h.unit.name}:${h.unit.physicalRelativePath}`;
         const page = paginate(relevant, { limit, cursor }, { defaultLimit: 10, maxLimit: 100, keyOf, total: 'omit' });
-        return {
+        const output = {
             query,
             matches: hits.length,
             hits: page.items.map((h) => ({
@@ -186,10 +233,12 @@ export const findLeaf = defineLeaf({
                 scope: h.unit.scope,
                 score: h.score,
                 short_form: h.unit.shortForm,
-                ...(includePaths ? { path: h.unit.path } : {}),
+                ...(includePaths ? pathFields(h.unit) : {}),
             })),
             next_cursor: page.next_cursor,
             follow_up: 'Read a hit with `crtr memory read <name>`. Run `crtr memory find -h` for filters and verbosity.',
         };
+        registerMemoryListingExposure(listingIdentity);
+        return output;
     },
 });