@north-light/crouter 0.3.226 → 0.3.228

package/dist/commands/memory/list.js

@@ -1,37 +1,53 @@
 import { defineLeaf } from '../../core/command.js';
-import { listAllMemoryDocs } from '../../core/memory-resolver.js';
+import { listAllMemoryDocs, loadMemoryStoreView } from '../../core/memory-resolver.js';
 import { memoryExtensionEffectiveCatalog, projectEffectiveMemoryExtensions } from '../../core/memory/extensions.js';
 import { renderResult } from '../../core/render.js';
 import { parseSubstrateDoc } from '../../core/substrate/schema.js';
 import { paginate } from '../../core/pagination.js';
-import { MEMORY_KINDS, MEMORY_SCOPES, scopeRank } from './shared.js';
-export function listMemoryDocs(kindFilter, scopeFilter, quiet = false, docs = listAllMemoryDocs(scopeFilter, quiet, true)) {
-    const seen = new Set(); // "scope/name" → first wins
+import { candidateRow } from './read.js';
+import { MEMORY_KINDS, registerMemoryListingExposure, requireMountedStore, resolveReadSelector, scopeRank, selectorParam, } from './shared.js';
+/** The inventory over one corpus. A target view is winner-only: one row per
+ *  canonical identity, first in source order, because that is the document a
+ *  read of the name returns. An exact store (`--dir`) is not deduped — the
+ *  point of naming a store is to see what it physically holds, including a pair
+ *  that shares one identity. */
+export function listMemoryDocs(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 items = [];
-    const addItem = (item) => {
-        const id = `${item.scope}/${item.name}`;
-        if (seen.has(id))
-            return;
-        seen.add(id);
-        items.push(item);
-    };
-    // Substrate memory docs (project > user > builtin precedence).
     for (const doc of docs) {
         const sub = parseSubstrateDoc(doc);
         if (sub === null)
             continue;
         if (kindFilter !== undefined && sub.kind !== kindFilter)
             continue;
-        addItem({
+        if (dedup) {
+            if (seen.has(sub.name))
+                continue;
+            seen.add(sub.name);
+        }
+        items.push({
             name: sub.name,
             kind: sub.kind,
             scope: sub.scope,
             path: sub.path,
+            storeRoot: doc.root,
+            physicalRelativePath: doc.physicalRelativePath,
             shortForm: sub.shortForm,
             slash: sub.slash,
             extensions: projectEffectiveMemoryExtensions(doc.frontmatter?.['extensions'], memoryExtensionEffectiveCatalog(doc)),
+            candidates: byName.get(doc.name) ?? [doc],
         });
     }
+    // Physical path is the final tiebreaker so two rows of one identity keep a
+    // stable order — the cursor key ends on the same component.
     items.sort((a, b) => {
         const sr = scopeRank(a.scope) - scopeRank(b.scope);
         if (sr !== 0)
@@ -39,56 +55,79 @@ export function listMemoryDocs(kindFilter, scopeFilter, quiet = false, docs = li
         const kc = a.kind.localeCompare(b.kind);
         if (kc !== 0)
             return kc;
-        return a.name.localeCompare(b.name);
+        const nc = a.name.localeCompare(b.name);
+        return nc !== 0 ? nc : a.physicalRelativePath.localeCompare(b.physicalRelativePath);
     });
     return items;
 }
 export const listLeaf = defineLeaf({
     name: 'list',
     description: 'inventory of stored memory documents',
-    whenToUse: 'browse everything stored — one line per document with its name, short-form hook, kind, and scope. This is the one surface that shows short-form. Reach for `crtr memory find` instead when you already have a topic or keyword in mind rather than wanting the whole inventory.',
+    whenToUse: 'browse everything stored — one row per canonical name with its short-form hook, kind, and scope. Every name is readable as-is with `crtr memory read`. This is the one surface that shows short-form. Reach for `crtr memory find` instead when you already have a topic or keyword in mind rather than wanting the whole inventory.',
     help: {
         name: 'memory list',
-        summary: 'inventory every memory document across the resolved scopes, one line each',
+        summary: 'inventory every memory document across the resolved scopes, one row per canonical name',
         params: [
             { 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.' },
-            { kind: 'flag', name: 'paths', type: 'bool', required: false, default: false, constraint: 'Include each row\'s absolute file path. Off by default.' },
+            selectorParam('scope-read', {}, 'Default: every resolved scope.'),
+            selectorParam('dir', {}, 'Lists that store alone, and lists it physically: two documents sharing one canonical name both appear, where the default view shows only the winner.'),
+            { kind: 'flag', name: 'paths', type: 'bool', required: false, default: false, constraint: 'Include each row\'s physical location — absolute path, store root, store-relative path, and every other physical document sharing its canonical name. Off by default.' },
             { kind: 'flag', name: 'limit', type: 'int', required: false, default: 50, constraint: 'Default 50, max 200.' },
             { kind: 'flag', name: 'cursor', type: 'string', required: false, constraint: 'Opaque token from next_cursor. Omit on first call.' },
         ],
         output: [
-            { name: 'items', type: 'object[]', required: true, constraint: 'One row per document: {name, short_form, kind, scope, extensions}. extensions carries effective valid plugin-owned metadata; enabled defaults appear here without becoming frontmatter, while disabled and unresolved namespaces are omitted. path is included only with --paths. Every name is readable as-is with `crtr memory read` (a directory segment of a name is readable too — it answers with the directory listing). short_form is the abbreviated hook — shown here and nowhere else. Sorted by scope then kind then name ascending.' },
+            { name: 'items', type: 'object[]', required: true, constraint: 'One row per canonical name: {name, short_form, kind, scope, extensions}. extensions carries effective valid plugin-owned metadata; enabled defaults appear here without becoming frontmatter, while disabled and unresolved namespaces are omitted. With --paths each row also carries path, store_root, physical_relative_path, and — only when several physical documents share the name — candidates, one {winner, scope, store_root, physical_relative_path, path} row each in source order. Every name is readable as-is with `crtr memory read` (a name that carries members answers with its own document plus that directory listing). short_form is the abbreviated hook — shown here and nowhere else. Sorted by scope then kind then name ascending.' },
             { name: 'next_cursor', type: 'string | null', required: true, constraint: 'Opaque token for the next page; null means no more items.' },
             { name: 'total', type: 'integer | null', required: true, constraint: 'Exact total across all pages when cheap to compute (always cheap here); never null in practice for this leaf.' },
             { name: 'follow_up', type: 'string', required: true, constraint: 'Concrete next commands — read a document in full or narrow the inventory.' },
         ],
         outputKind: 'object',
-        effects: ['None. Read-only.'],
+        effects: ['Records this inventory page as listing context for the current node without marking any listed document as loaded.'],
     },
     run: async (input) => {
         const kindFilter = input['kind'];
-        const scopeFilter = input['scope'];
+        const dirArg = input['dir'];
         const includePaths = input['paths'] ?? false;
         const limitRaw = input['limit'];
         const limit = limitRaw !== undefined ? Math.min(Math.max(1, limitRaw), 200) : 50;
         const cursor = input['cursor'];
-        const items = listMemoryDocs(kindFilter, scopeFilter);
-        const keyOf = (d) => `${String(scopeRank(d.scope) + 10).padStart(2, '0')}:${d.kind}:${d.name}`;
+        const selector = resolveReadSelector({ scope: input['scope'], dir: dirArg });
+        const items = selector.store !== null
+            ? listMemoryDocs(kindFilter, loadMemoryStoreView(requireMountedStore(selector.store), false).docs, false)
+            : listMemoryDocs(kindFilter, listAllMemoryDocs(selector.scope, false, true), true);
+        const keyOf = (d) => `${String(scopeRank(d.scope) + 10).padStart(2, '0')}:${d.kind}:${d.name}:${d.physicalRelativePath}`;
         const result = paginate(items, { limit, cursor }, { defaultLimit: 50, maxLimit: 200, keyOf, total: 'count' });
-        return {
+        const output = {
             items: result.items.map((d) => ({
                 name: d.name,
                 short_form: d.shortForm,
                 kind: d.kind,
                 scope: d.scope,
                 extensions: d.extensions,
-                ...(includePaths ? { path: d.path } : {}),
+                ...(includePaths
+                    ? {
+                        path: d.path,
+                        store_root: d.storeRoot,
+                        physical_relative_path: d.physicalRelativePath,
+                        ...(d.candidates.length > 1
+                            ? { candidates: d.candidates.map((c) => candidateRow(c, d.candidates[0])) }
+                            : {}),
+                    }
+                    : {}),
             })),
             next_cursor: result.next_cursor,
             total: result.total,
             follow_up: 'Read one in full with `crtr memory read <name>`, or revise one with `crtr memory edit <name> --rationale "<why>"` (body, routing, frontmatter, and visibility all go through that one verb, and it records the change). Narrow with --kind / --scope, page with --cursor, or search a topic with `crtr memory find <query>`.',
         };
+        registerMemoryListingExposure(`listing:memory-list:${JSON.stringify({
+            kind: kindFilter ?? null,
+            scope: selector.scope ?? null,
+            dir: dirArg ?? null,
+            paths: includePaths,
+            limit,
+            cursor: cursor ?? null,
+        })}`);
+        return output;
     },
     render: (result) => {
         const items = result['items'].map(({ extensions: _extensions, ...item }) => item);

package/dist/commands/memory/move.js

@@ -3,12 +3,12 @@ import { dirname, resolve as resolvePath } from 'node:path';
 import { defineLeaf } from '../../core/command.js';
 import { CrtrError, notFound, usage } from '../../core/errors.js';
 import { ensureDir, pathExists, readText, realpathOrSelf, writeText } from '../../core/fs-utils.js';
-import { listAllMemoryDocs, resolveMemoryDoc } from '../../core/memory-resolver.js';
-import { findDocLinks, isDocLinkName } from '../../core/memory/doc-link-grammar.js';
+import { listAllMemoryDocs, loadMemoryStoreView, resolveMemoryCandidates } from '../../core/memory-resolver.js';
+import { findDocLinks } from '../../core/memory/doc-link-grammar.js';
 import { appendHistoryRecord, buildHistoryRecord, historyLogPathFor } from '../../core/memory/history.js';
-import { docsByName, isDirName } from '../../core/substrate/listings.js';
-import { normalizeDocName } from '../../core/substrate/schema.js';
-import { MEMORY_SCOPES, literalBodySegment, memoryFilePath, pruneEmptyParents } from './shared.js';
+import { explicitLocalName } from '../../core/memory/identity.js';
+import { buildMemoryTree } from '../../core/memory/tree.js';
+import { MEMORY_WRITE_SCOPES, literalBodySegment, planNewDocumentPlacement, pruneEmptyParents, requireCanonicalName, requireLocalNameInStore, requireMountedStore, selectMutationDoc, resolveReadSelector, selectorParam, serializeMemoryDocLiteral, } from './shared.js';
 /** Replace every `[[oldName]]` doc link in a full document source with
  *  `[[newName]]`, splicing only within the literal body segment so the
  *  frontmatter block is never touched. Link spans come from the shared
@@ -25,97 +25,113 @@ function rewriteRefs(source, oldName, newName) {
     }
     return { text, count: links.length };
 }
+/** Every physical document owning the source's exact canonical identity — in
+ *  the target view, or inside the one store `--dir` selected — or null when
+ *  nothing answers to that name. */
+function sourceCandidates(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 moveLeaf = defineLeaf({
     name: 'move',
     description: 'rename or relocate a memory document, rewriting inbound links',
-    whenToUse: 'a stored document should answer to a different name — renamed in place or relocated under another directory. The sanctioned way to move one, so you never mv the markdown off disk: this verb carries the document’s revision history along and rewrites every inbound `[[ref]]` across writable stores, so authored links break loudly or not at all. Moves stay within the document’s own store; one document per move — a directory never moves as a unit, so relocate its members individually.',
+    whenToUse: 'a stored document should answer to a different canonical name — renamed in place or relocated under another directory. The sanctioned way to move one, so you never mv the markdown off disk: this verb carries the document’s revision history along and rewrites every inbound `[[ref]]` across writable stores, so authored links break loudly or not at all. Source and destination are both full canonical names in the SAME store, so a move never changes which repository-relative prefix the document composes under. The repository-root document is immutable, but a nested store’s optional root guide is an ordinary document that may move. One document per move: moving a directory’s own document leaves its members where they are, so relocate a whole directory member by member. If two physical files in that store share the source identity, this verb selects the first physical path in stable lexical order and recovers the collision.',
     help: {
         name: 'memory move',
-        summary: 'move memory/<name>.md to memory/<new-name>.md in its store, rewriting inbound [[refs]] corpus-wide',
+        summary: 'move one document to a new canonical name inside its own store, rewriting inbound [[refs]]',
         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. Builtin and installed-plugin docs are read-only and refuse to move. A directory name is rejected — move member docs individually.' },
-            { kind: 'flag', name: 'to', type: 'string', required: true, constraint: 'The new canonical name, in the same store: `/`-joined segments of [A-Za-z0-9_-], no `NN-` ordering prefix (identity is prefix-stripped, so a prefixed name would not answer to itself). Must not already answer to any document in the corpus.' },
-            { kind: 'flag', name: 'scope', type: 'enum', choices: [...MEMORY_SCOPES], required: false, constraint: 'Restrict resolution to this scope before moving. Use it to disambiguate a name present at multiple scopes. builtin is not a choice — builtin docs ship with the package and cannot move.' },
+            { kind: 'positional', name: 'name', required: true, constraint: 'Full canonical name of the document to move — 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. If two physical files in the selected store own the name, move selects the first path in stable lexical order and recovers the collision. Builtin and installed-plugin documents are read-only and refuse to move, 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 move.' },
+            { kind: 'flag', name: 'to', type: 'string', required: true, constraint: 'The new full canonical name, in the SAME store — the repository namespace and store path included, since a move never crosses stores. `/`-joined segments of [A-Za-z0-9_-], no trailing `INDEX` (a directory’s document answers at the directory name). A nested store’s effective prefix is a legal destination for its optional root guide. Rejected when a document in that store already answers to it, or when either `<local name>.md` or `<local name>/INDEX.md` already exists there.' },
+            selectorParam('scope-read', { choices: [...MEMORY_WRITE_SCOPES] }, 'builtin is not a choice — builtin documents ship with the package and cannot move.'),
+            selectorParam('dir', {}, 'Source, destination, and inbound-link rewriting all stay inside that one store, so moving a non-winning duplicate leaves every other store untouched — and rewrites no link at all, because the name still resolves to the candidate that outranks it here.'),
         ],
         output: [
             { name: 'name', type: 'string', required: true, constraint: 'The document’s new canonical name.' },
-            { name: 'previous_name', type: 'string', required: true, constraint: 'The name it answered to before the move.' },
+            { name: 'previous_name', type: 'string', required: true, constraint: 'The canonical name it answered to before the move.' },
             { name: 'scope', type: 'string', required: true, constraint: 'Scope of the store the document moved within: node, user, project, or profile.' },
-            { name: 'path', type: 'string', required: true, constraint: 'Absolute path of the document at its new location.' },
+            { name: 'path', type: 'string', required: true, constraint: 'Absolute path of the document at its new location — `<local name>/INDEX.md` when that canonical directory already has members in the store, else `<local name>.md`.' },
             { name: 'moved', type: 'boolean', required: true, constraint: 'Always true on success — the file and its revision log now live at the new name.' },
             { name: 'log_path', type: 'string', required: true, constraint: 'Absolute path to the revision log at its new location, ending in a `move` record that names the previous canonical name.' },
-            { name: 'refs_rewritten', type: 'object[]', required: true, constraint: 'Documents whose bodies were rewritten from `[[<previous_name>]]` to `[[<name>]]`. Each: {name, scope, path, refs}. Empty when nothing linked to the document — or when the moved document was shadowed by a same-named doc at a nearer scope, in which case inbound refs keep resolving to that survivor and are left alone.' },
+            { name: 'refs_rewritten', type: 'object[]', required: true, constraint: 'Documents whose bodies were rewritten from `[[<previous_name>]]` to `[[<name>]]`. Each: {name, scope, path, refs}. Empty when nothing linked to the document — or when the moved file is not what that name resolves to here (another store’s candidate wins the address), in which case inbound refs keep resolving to that winner and are left alone.' },
             { name: 'follow_up', type: 'string', required: true, constraint: 'Concrete next commands — read it back at the new name, verify the corpus with lint.' },
         ],
         outputKind: 'object',
         effects: [
-            'Moves memory/<name>.md to memory/<new-name>.md within its store (creating parent directories, pruning any it leaves empty) and moves memory/.history/<name>.jsonl with it, appending a `move` record naming the previous canonical name.',
-            'Rewrites every inbound `[[<name>]]` doc link across writable stores to `[[<new-name>]]`, appending an `edit` record to each rewritten document’s revision log. Aborts before any write when a read-only (builtin or installed-plugin) document carries such a link.',
+            'Moves the document to the physical form its new local name takes in that store (creating parent directories, pruning any it leaves empty) and moves its `.history/<physical path>.jsonl` log with it, appending a `move` record naming the previous canonical name.',
+            'Drops an explicit `name:` frontmatter pin, so the moved document answers to its path-derived identity — the name you asked for.',
+            'Rewrites every inbound `[[<name>]]` doc link to `[[<new-name>]]` — across the target view’s writable stores, or inside the one store `--dir` selected — appending an `edit` record to each rewritten document’s revision log. Aborts before any write when a read-only (builtin or installed-plugin) document carries such a link.',
         ],
     },
     run: async (input) => {
         const nameRaw = input['name'];
-        const newName = (input['to'] ?? '').trim();
+        const newNameRaw = (input['to'] ?? '').trim();
         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') {
-                const dirName = normalizeDocName(nameRaw.replace(/\/+$/, ''));
-                if (dirName !== '' && isDirName(docsByName(listAllMemoryDocs(undefined, true, true)), dirName)) {
-                    throw usage(`${dirName} is a directory, and a directory never moves as a unit — move its member docs individually.`, {
-                        memory: dirName,
-                        next: `Run \`crtr memory read ${dirName}\` to list the members, then \`crtr memory move <member> --to <new-name>\` per doc.`,
-                    });
-                }
-                throw notFound(`memory document not found: ${nameRaw}`, {
+        const dirArg = input['dir'];
+        const selector = resolveReadSelector({ scope: scopeArg, dir: dirArg });
+        const storeView = selector.store === null ? null : loadMemoryStoreView(requireMountedStore(selector.store), true);
+        const set = sourceCandidates(nameRaw, selector.scope, storeView);
+        if (set === null) {
+            const tree = buildMemoryTree(storeView?.docs ?? listAllMemoryDocs(undefined, true, true));
+            if (tree.isDirectory(nameRaw)) {
+                throw usage(`${nameRaw} is a canonical directory with no document of its own, and a directory never moves as a unit — move its members individually.`, {
                     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.',
+                    next: `Run \`crtr memory read ${nameRaw}\` to list the members, then \`crtr memory move <member> --to <new-name>\` per document.`,
                 });
             }
-            throw e; // ambiguous / usage propagate with their own recovery guidance
+            throw notFound(`memory document not found: ${nameRaw}`, {
+                memory: nameRaw,
+                next: 'A move 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 moved here. Manage plugin docs with \`crtr pkg\`.`, { 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 moved. Override it with a same-named doc at a writable scope instead (\`crtr memory write ${doc.name} ...\`).`, { memory: doc.name, scope: 'builtin' });
         }
-        // An explicit frontmatter `name` pins identity independent of the file's
-        // location, so a physical move would change nothing a reader can see.
-        const explicitName = doc.frontmatter?.['name'];
-        if (typeof explicitName === 'string' && explicitName.trim() !== '') {
-            throw usage(`${doc.name} pins its identity with an explicit \`name\` frontmatter field, so its name is not path-derived and a file move would not rename it. Edit the field with \`crtr memory edit ${doc.name}\` instead.`, { memory: doc.name, path: doc.path });
+        // 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 — it answers at the namespace itself and cannot be moved.`, { memory: doc.name, path: doc.path });
         }
-        if (newName === '')
+        if (newNameRaw === '')
             throw usage('--to requires the new canonical name');
-        if (!isDocLinkName(newName)) {
-            throw usage(`invalid new name: ${newName} — a canonical name is one or more [A-Za-z0-9_-] segments joined by \`/\``);
-        }
-        // Identity is derived from the path with `NN-` ordering prefixes stripped,
-        // so a prefixed target name would derive a different identity than asked.
-        if (normalizeDocName(newName) !== newName) {
-            throw usage(`invalid new name: ${newName} — a \`NN-\` ordering prefix is stripped from derived identity, so this doc would answer to ${normalizeDocName(newName)} instead. Name it that directly.`);
-        }
+        const newName = requireCanonicalName(newNameRaw);
         if (newName === doc.name)
             throw usage(`${doc.name} already answers to that name — nothing to move`);
-        const newPath = memoryFilePath(doc.root, newName);
-        if (pathExists(newPath)) {
-            throw usage(`the target is occupied: ${newPath} already exists — pick a free name or delete the occupant first`, { memory: newName, path: newPath });
-        }
-        const corpus = listAllMemoryDocs(undefined, true, true);
-        const byName = docsByName(corpus);
-        const taken = byName.get(newName);
-        if (taken !== undefined) {
-            throw usage(`${newName} already answers to a document (${taken.scope} scope, ${taken.path}) — moving onto it would make every rewritten ref ambiguous. Pick a free name.`, { memory: newName, path: taken.path });
+        if (doc.store.ownerRelativePath === '' && requireLocalNameInStore(doc.store, newName) === '') {
+            throw usage(`${newName} is the repository namespace of the store at ${doc.root} — its repository-root document declares that namespace and is not a destination a move can create.`, { memory: newName });
         }
-        // Refs are rewritten only when this doc is what `[[<name>]]` actually
-        // resolves to. Moving a doc shadowed by a same-named nearer doc leaves
-        // every ref pointing at that surviving winner, so they are left alone.
+        // Occupancy (the identity AND both physical forms of it) is checked in the
+        // one store the document lives in; another store legitimately carries the
+        // same canonical name. The source itself is excluded, so retiring an
+        // explicit `name:` pin back to the file's own path-derived identity is a
+        // legal destination.
         const movedReal = realpathOrSelf(doc.path);
-        const winner = byName.get(doc.name);
+        const placement = planNewDocumentPlacement(doc.store, newName, storeView?.docs, doc);
+        const inPlace = realpathOrSelf(placement.path) === movedReal;
+        // Two corpora, one rule each. Winner facts always come from the live target
+        // view: `--dir` picks which store may be WRITTEN, never who owns the
+        // address, so a selected non-winning duplicate keeps every inbound ref
+        // pointing at the document that still answers here. The rewrite corpus is
+        // what this move may change — that one store under `--dir`, the same target
+        // view otherwise.
+        const targetDocs = listAllMemoryDocs(undefined, true, true);
+        const corpus = storeView?.docs ?? targetDocs;
+        const winner = targetDocs.find((d) => d.name === doc.name);
         const isWinner = winner !== undefined && realpathOrSelf(winner.path) === movedReal;
         const referencing = [];
         const blocked = [];
@@ -153,18 +169,30 @@ export const moveLeaf = defineLeaf({
             appendHistoryRecord(historyLogPathFor(d.root, d.path), buildHistoryRecord({ op: 'edit', rationale: `\`crtr memory move\`: [[${doc.name}]] → [[${newName}]]`, before, after }));
             refsRewritten.push({ name: d.name, scope: d.scope, path: d.path, refs: count });
         }
-        // The doc itself: self-refs rewrite in the same motion as the move.
+        // The doc itself: self-refs rewrite in the same motion as the move. An
+        // explicit `name` pinned identity to that string rather than the path, so
+        // the move drops it — the destination name IS the path-derived identity.
         const before = readText(doc.path);
-        const after = isWinner ? rewriteRefs(before, doc.name, newName).text : before;
-        writeText(newPath, after);
-        rmSync(doc.path);
-        pruneEmptyParents(resolvePath(doc.path), doc.name.split('/').length);
-        // The revision log travels with the doc — history answers to the name the
-        // doc now answers to. A log already at the target (a prior, deleted life
-        // of that name) keeps its records; this doc's records append after them.
+        const rewritten = isWinner ? rewriteRefs(before, doc.name, newName).text : before;
+        let after = rewritten;
+        if (explicitLocalName(doc.frontmatter) !== null) {
+            const frontmatter = { ...(doc.frontmatter ?? {}) };
+            delete frontmatter['name'];
+            after = serializeMemoryDocLiteral(frontmatter, literalBodySegment(rewritten));
+        }
+        writeText(placement.path, after);
+        const physicalSegments = doc.physicalRelativePath.split('/').length;
+        if (!inPlace) {
+            rmSync(doc.path);
+            pruneEmptyParents(resolvePath(doc.path), physicalSegments);
+        }
+        // The revision log travels with the doc — history follows the file, so it
+        // moves to the sidecar mirroring the destination's physical path. A log
+        // already there (a prior, deleted life of that path) keeps its records;
+        // this doc's records append after them.
         const oldLog = historyLogPathFor(doc.root, doc.path);
-        const newLog = historyLogPathFor(doc.root, newPath);
-        if (pathExists(oldLog)) {
+        const newLog = historyLogPathFor(placement.store.storeRoot, placement.path);
+        if (!inPlace && pathExists(oldLog)) {
             ensureDir(dirname(newLog));
             if (pathExists(newLog)) {
                 appendFileSync(newLog, readText(oldLog), 'utf8');
@@ -173,23 +201,25 @@ export const moveLeaf = defineLeaf({
             else {
                 renameSync(oldLog, newLog);
             }
-            pruneEmptyParents(resolvePath(oldLog), doc.name.split('/').length);
+            pruneEmptyParents(resolvePath(oldLog), physicalSegments);
         }
         appendHistoryRecord(newLog, buildHistoryRecord({ op: 'move', from: doc.name, before, after }));
         const refsNote = isWinner
             ? refsRewritten.length > 0
                 ? ` Rewrote [[${doc.name}]] in ${refsRewritten.length} doc${refsRewritten.length === 1 ? '' : 's'}.`
                 : ' No inbound refs needed rewriting.'
-            : ` Inbound [[${doc.name}]] refs were left alone: a same-named doc at a nearer scope still answers to that name.`;
+            : winner === undefined
+                ? ` Inbound [[${doc.name}]] refs were left alone: no document answers to that name in this target view, so no link here pointed at the moved file.`
+                : ` Inbound [[${doc.name}]] refs were left alone: ${winner.path} answers to that name in this target view, so they still resolve to it.`;
         return {
             name: newName,
             previous_name: doc.name,
             scope: doc.scope,
-            path: newPath,
+            path: placement.path,
             moved: true,
             log_path: newLog,
             refs_rewritten: refsRewritten,
-            follow_up: `Moved.${refsNote} Read it back with \`crtr memory read ${newName}\`, and run \`crtr memory lint\` to verify no link dangles.`,
+            follow_up: `Moved${selected.collisionPaths.length > 0 ? ` the first physical path in stable lexical order (${doc.path}) to recover a same-store collision.` : '.'}${refsNote} Read it back with \`crtr memory read ${newName}\`, and run \`crtr memory lint\` to verify no link dangles.`,
         };
     },
 });

package/dist/commands/memory/origin.js

@@ -1,9 +1,10 @@
 import { defineLeaf } from '../../core/command.js';
 import { CrtrError, notFound } from '../../core/errors.js';
-import { resolveMemoryDoc } from '../../core/memory-resolver.js';
+import { loadMemoryStoreView, resolveMemoryCandidates } from '../../core/memory-resolver.js';
 import { ApiError } from '../../api/index.js';
 import { cliClient } from '../api-client.js';
 import { contextDir } from '../../core/canvas/paths.js';
+import { requireMountedStore, requireUnambiguousDoc, resolveReadSelector, selectorParam } from './shared.js';
 export const originLeaf = defineLeaf({
     name: 'origin',
     description: 'deref a memory document back to the node + conversation that created it',
@@ -12,11 +13,19 @@ export const originLeaf = defineLeaf({
         name: 'memory origin',
         summary: 'resolve a doc name to its creation provenance and deref the originating node',
         params: [
-            { kind: 'positional', name: 'name', required: true, constraint: 'Path-derived memory identifier (e.g. `topic` or `area/topic`). Resolved across scopes: node > project > profile > user > builtin.' },
+            { kind: 'positional', name: 'name', required: true, constraint: 'Full canonical memory name (a project document includes its namespace). Resolved exactly across the selected target view; a same-store physical collision is refused.' },
+            selectorParam('scope-read'),
+            selectorParam('dir'),
+            selectorParam('profile'),
         ],
         output: [
             { name: 'name', type: 'string', required: true, constraint: 'Resolved document name.' },
             { name: 'path', type: 'string', required: true, constraint: 'Absolute path to the document on disk.' },
+            { name: 'scope', type: 'string', required: true, constraint: 'Scope whose ordered store view supplied the document.' },
+            { name: 'local_name', type: 'string', required: true, constraint: 'Store-local identity, before project namespace composition.' },
+            { name: 'store_root', type: 'string', required: true, constraint: 'Absolute memory store root containing the document.' },
+            { name: 'physical_relative_path', type: 'string', required: true, constraint: 'Store-relative physical markdown path; sidecars preserve this shape.' },
+            { name: 'representation', type: 'string', required: true, constraint: 'Physical representation: leaf-file or directory-index.' },
             { name: 'origin_recorded', type: 'boolean', required: true, constraint: 'true when the doc carries an `origin` provenance block; false for hand-authored or pre-provenance docs.' },
             { name: 'created', type: 'string', required: false, constraint: 'ISO timestamp the doc was created. Absent when origin_recorded is false.' },
             { name: 'cwd', type: 'string', required: false, constraint: 'Working directory the authoring conversation ran in.' },
@@ -35,25 +44,41 @@ export const originLeaf = defineLeaf({
     },
     run: async (input) => {
         const nameRaw = input['name'];
-        let doc;
+        const selector = resolveReadSelector({
+            scope: input['scope'],
+            dir: input['dir'],
+            profile: input['profile'],
+        });
+        if (selector.store !== null)
+            requireMountedStore(selector.store);
+        let set;
         try {
-            doc = resolveMemoryDoc(nameRaw, { includeDescendants: true });
+            set = selector.store !== null
+                ? loadMemoryStoreView(selector.store, true).candidates(nameRaw)
+                : resolveMemoryCandidates(nameRaw, { includeDescendants: true, ...(selector.scope ? { scope: selector.scope } : {}) });
         }
         catch (e) {
             if (!(e instanceof CrtrError && e.code === 'not_found'))
                 throw e;
+            set = null;
         }
-        if (doc === undefined) {
+        if (set === null) {
             throw notFound(`memory document not found: ${nameRaw}`, {
                 memory: nameRaw,
                 next: 'Run `crtr memory find <query>` to discover documents, or `crtr memory list` to browse the inventory.',
             });
         }
+        const doc = requireUnambiguousDoc(set);
         const origin = doc.frontmatter?.['origin'];
         if (origin === undefined || typeof origin !== 'object') {
             return {
                 name: doc.name,
                 path: doc.path,
+                scope: doc.scope,
+                local_name: doc.localName,
+                store_root: doc.root,
+                physical_relative_path: doc.physicalRelativePath,
+                representation: doc.representation,
                 origin_recorded: false,
                 follow_up: 'No provenance recorded \u2014 this doc was hand-authored or created before provenance capture. Read its body with `crtr memory read ' +
                     doc.name +
@@ -83,6 +108,11 @@ export const originLeaf = defineLeaf({
         return {
             name: doc.name,
             path: doc.path,
+            scope: doc.scope,
+            local_name: doc.localName,
+            store_root: doc.root,
+            physical_relative_path: doc.physicalRelativePath,
+            representation: doc.representation,
             origin_recorded: true,
             created: str(origin['created']) ?? undefined,
             cwd: str(origin['cwd']) ?? undefined,

package/dist/commands/memory/read.d.ts

@@ -1,8 +1,12 @@
 import { createMemoryDocSnapshot, resolveMemoryDocs } from '../../core/memory-resolver.js';
+import type { MemoryDoc } from '../../core/memory-resolver.js';
 export { createMemoryDocSnapshot, resolveMemoryDocs };
 /** Load the body at an already-resolved memory path with the same frontmatter
  * stripping and in-node path interpolation as `memory read`. Callers that
  * already have the resolved path (such as slash-command discovery) avoid
  * re-walking every memory store for each document. */
 export declare function readMemoryDocContent(path: string, includeFrontmatter?: boolean): string;
+/** One physical document sharing a canonical identity, as the path-aware
+ *  surfaces report it. `--dir <its project>` is how a non-winner is reached. */
+export declare function candidateRow(doc: MemoryDoc, winner: MemoryDoc): Record<string, unknown>;
 export declare const readLeaf: import("../../core/command.js").LeafDef;