@north-light/crouter 0.3.227 → 0.3.228

package/dist/commands/memory/read.js

@@ -1,19 +1,20 @@
 import { CrtrClient } from '../../api/index.js';
 import { interpolateNodePaths } from '../../core/canvas/paths.js';
 import { defineLeaf } from '../../core/command.js';
-import { CrtrError, notFound } from '../../core/errors.js';
+import { CrtrError } from '../../core/errors.js';
 import { memoryExtensionEffectiveCatalog, projectEffectiveMemoryExtensions } from '../../core/memory/extensions.js';
 import { readText, realpathOrSelf } from '../../core/fs-utils.js';
 import { parseFrontmatterGeneric } from '../../core/frontmatter.js';
 import { docLinkNames } from '../../core/memory/doc-link-grammar.js';
-import { createMemoryDocSnapshot, listAllMemoryDocs, resolveMemoryDoc, resolveMemoryDocs } from '../../core/memory-resolver.js';
+import { createMemoryDocSnapshot, listAllMemoryDocs, loadMemoryStoreView, resolveMemoryCandidates, resolveMemoryDocs, } from '../../core/memory-resolver.js';
 import { expandShellBlocks, hasShellBlocks, makeNodeShellRunner } from '../../core/runtime/shell-expansion.js';
-import { deliveredAtOrAbove, loadInjectedDocs, recordDelivery, saveInjectedDocs } from '../../core/substrate/injected-store.js';
-import { ancestorDirsOf, dirDedupKey, docsByName, isDirName, renderDirListing } from '../../core/substrate/listings.js';
+import { emptyContextExposureState, exposedAtOrAbove, exposureTarget, loadContextExposureState, registerDocumentExposure, registerExposure, saveContextExposureState, } from '../../core/substrate/injected-store.js';
+import { dirDedupKey, docListingDirs, docsByName, isDirName, renderDirListing } from '../../core/substrate/listings.js';
 import { memoryReadDocBlocks } from '../../core/substrate/on-read.js';
 import { renderResult } from '../../core/render.js';
-import { effectiveDocKind, normalizeDocName } from '../../core/substrate/schema.js';
-import { MEMORY_KINDS } from './shared.js';
+import { effectiveDocKind } from '../../core/substrate/schema.js';
+import { canonicalSegments } from '../../core/memory/identity.js';
+import { MEMORY_KINDS, requireMountedStore, resolveReadSelector, selectorParam } from './shared.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
@@ -48,6 +49,17 @@ function corpusDocs() {
         return [];
     }
 }
+/** 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 function candidateRow(doc, winner) {
+    return {
+        winner: doc === winner,
+        scope: doc.scope,
+        store_root: doc.root,
+        physical_relative_path: doc.physicalRelativePath,
+        path: doc.path,
+    };
+}
 function attr(s) {
     return s
         .replace(/&/g, '&amp;')
@@ -58,25 +70,32 @@ function attr(s) {
 export const readLeaf = defineLeaf({
     name: 'read',
     description: 'load a memory document body by name',
-    whenToUse: 'a task in front of you matches a stored document and you already know its name — read it before improvising. Exact identity and direct-path matches resolve by scope precedence (node > project stack > profile > user > builtin); bare leaf-name fallback is considered only when no such match exists. A directory name is also a valid target: it returns the neighborhood listing, and walking directories is the sanctioned browse move. You name the document by its crtr identifier, never a file path — do not cat or find the markdown off disk. Reach for `crtr memory find` first when you do not yet know which document applies.',
+    whenToUse: 'a task in front of you matches a stored document and you already know its canonical name — read it before improvising. Resolution is exact and takes the full canonical name (a project document is `<namespace>/<local name>`); among documents sharing one name the winner is the nearest scope (node > project stack > profile > user > builtin). A directory name is a valid target too: it answers with that directory\u2019s own document, when it has one, together with its immediate listing, and walking directories is the sanctioned browse move. You name the document by its crtr identifier, never a file path — do not cat or find the markdown off disk. Reach for `crtr memory find` first when you do not yet know which document applies.',
     help: {
         name: 'memory read',
-        summary: 'resolve a path-derived name to its document body (frontmatter stripped unless --frontmatter), or a directory name to its listing',
+        summary: 'resolve an exact canonical name to its document body (frontmatter stripped unless --frontmatter), plus the directory listing when that name has members',
         params: [
-            { kind: 'positional', name: 'name', required: true, constraint: 'Path-derived memory identifier (e.g. `topic` or `area/topic`). Exact identity and direct-path matches resolve by scope precedence: node > project stack > profile > user > builtin. A bare leaf falls back only when no exact/direct match exists. A directory name returns that directory\u2019s listing instead of a document.' },
+            { kind: 'positional', name: 'name', required: true, constraint: 'Full canonical memory name — a project document is `<namespace>/<local name>`, every other store\u2019s local names are already canonical, where a nested store\'s namespace includes its path under the repository root. Resolution is exact: a file path, a bare leaf, a `<scope>/<name>` spelling, and a trailing `/INDEX` all fail. A name that carries members returns its listing alongside its body; a name that is only a directory returns the listing alone.' },
             { kind: 'flag', name: 'kind', type: 'enum', choices: [...MEMORY_KINDS], required: false, constraint: 'Narrows resolution when the name is ambiguous across kinds.' },
             { kind: 'flag', name: 'frontmatter', type: 'bool', required: false, constraint: 'When present, includes the YAML frontmatter in the returned body. Off by default — only the body is returned.' },
+            selectorParam('scope-read'),
+            selectorParam('dir', {}, 'Reads that store alone: the name resolves against its documents only, and the listing shows its members only.'),
         ],
         output: [
-            { name: 'name', type: 'string', required: true, constraint: 'Resolved document name, or the directory name on a directory read.' },
+            { name: 'name', type: 'string', required: true, constraint: 'Resolved canonical document name, or the directory name on a directory read.' },
+            { name: 'local_name', type: 'string', required: false, constraint: 'Store-local identity, before the store namespace composed the canonical name. Absent on a directory read.' },
             { name: 'kind', type: 'string', required: false, constraint: 'Resolved kind: knowledge or preference. Absent on a directory read.' },
             { name: 'scope', type: 'string', required: false, constraint: 'Scope the document was resolved from: node, project, profile, user, or builtin. Absent on a directory read.' },
             { name: 'path', type: 'string', required: false, constraint: 'Absolute path to the document on disk. Revise it with `crtr memory edit`, never by editing this file — an edit records why the change happened and lands in the doc’s revision history. Absent on a directory read.' },
+            { name: 'store_root', type: 'string', required: false, constraint: 'Absolute memory store root the document loaded from. Absent on a directory read.' },
+            { name: 'physical_relative_path', type: 'string', required: false, constraint: 'Store-relative physical markdown path, ordering prefixes and any `INDEX.md` kept. Absent on a directory read.' },
+            { name: 'representation', type: 'string', required: false, constraint: 'Physical representation of this identity: leaf-file or directory-index. Absent on a directory read.' },
+            { name: 'candidates', type: 'object[]', required: false, constraint: 'Present only when several physical documents share this canonical name: one row per candidate in source order, {winner, scope, store_root, physical_relative_path, path}. The winner is what this read returned; reach a non-winning one with `--dir <its project>`.' },
             { name: 'content', type: 'string', required: false, constraint: 'Document body. Frontmatter stripped unless --frontmatter is set. A document may embed shell as `!`cmd`` or a ```! fenced block; each runs once per read, in the current working directory, and is replaced by its output. Read `path` off disk when you need the literal unexecuted text. May be preceded by one `<auto-loaded-context>` block carrying the doc\u2019s neighborhood listings and any docs routed to this read. Absent on a directory read.' },
-            { name: 'listing', type: 'string[]', required: false, constraint: 'Present only on a directory read: one `[[name]]: <when-and-why>` line per member doc, one bare `[[name]]` per subdirectory. Follow any line with `crtr memory read <name>`.' },
+            { name: 'listing', type: 'string[]', required: false, constraint: 'Present when the name has members — a directory document returns its body AND this listing, a bare directory returns the listing alone: one `[[name]]: <when-and-why>` line per member doc, one bare `[[name]]` per subdirectory. Follow any line with `crtr memory read <name>`.' },
             { name: 'extensions', type: 'object', required: false, constraint: 'Effective valid plugin-owned metadata, keyed by plugin namespace then field. Includes enabled declaration defaults without writing them to frontmatter; disabled and unresolved namespaces are omitted. Present only on a document read.' },
             { name: 'links', type: 'string[]', required: false, constraint: 'Canonical names this document links to via `[[name]]` that resolve in the current corpus — further reading, loaded only on demand with `crtr memory read <name>`. A directory link returns that directory\u2019s listing. Omitted when the body carries no resolvable links.' },
-            { name: 'follow_up', type: 'string', required: false, constraint: 'Present on a directory read, or on a document read whose body links to further memory documents.' },
+            { name: 'follow_up', type: 'string', required: false, constraint: 'Present whenever the read returned a listing or resolvable body links.' },
         ],
         outputKind: 'object',
         effects: [
@@ -88,34 +107,64 @@ export const readLeaf = defineLeaf({
         const nameRaw = input['name'];
         const kindFilter = input['kind'];
         const includeFrontmatter = input['frontmatter'];
-        // Resolve a substrate/memory document across scopes: exact/direct matches
-        // by precedence first, then leaf-name fallback. --kind is threaded
-        // INTO resolution (not a post-filter): a nearer wrong-kind doc is skipped
-        // so a farther matching-kind doc is found instead of shadowing it into a
-        // false not_found. The substrate corpus now includes plugin docs (mounted
-        // under <pluginName>/), so this resolves every name.
-        let doc;
-        try {
-            doc = resolveMemoryDoc(nameRaw, { kind: kindFilter, includeDescendants: true });
+        // The selector decides the corpus: a scope filter over the target view, or
+        // the one exact store `--dir` names. --kind is threaded INTO resolution
+        // (not a post-filter): a nearer wrong-kind doc is skipped so a farther
+        // matching-kind doc is found instead of shadowing it into a false
+        // not_found.
+        const selector = resolveReadSelector({
+            scope: input['scope'],
+            dir: input['dir'],
+        });
+        const kindOpts = kindFilter === undefined ? {} : { kind: kindFilter };
+        let set = null;
+        // Re-runs the throwing resolve when nothing answered, so the canonical
+        // not-found (with its spelling guidance) is the resolver's, not a copy.
+        let fail;
+        let listingByName;
+        let linkByName;
+        if (selector.store !== null) {
+            // `--dir` reads ONE exact store: its documents alone decide what resolves
+            // and what the listings show. Links stay corpus-wide — a body legitimately
+            // points at another store — with the selected store first so it wins its
+            // own names.
+            const view = loadMemoryStoreView(requireMountedStore(selector.store), true);
+            listingByName = docsByName(view.docs);
+            linkByName = docsByName([...view.docs, ...corpusDocs()]);
+            set = view.candidates(nameRaw, kindOpts);
+            fail = () => view.resolve(nameRaw, kindOpts);
         }
-        catch (e) {
-            if (!(e instanceof CrtrError && e.code === 'not_found'))
-                throw e;
+        else {
+            const resolveOpts = {
+                ...kindOpts,
+                ...(selector.scope === undefined ? {} : { scope: selector.scope }),
+                includeDescendants: true,
+            };
+            listingByName = linkByName = docsByName(listAllMemoryDocs(selector.scope, false, true));
+            try {
+                set = resolveMemoryCandidates(nameRaw, resolveOpts);
+            }
+            catch (e) {
+                if (!(e instanceof CrtrError && e.code === 'not_found'))
+                    throw e;
+            }
+            fail = () => resolveMemoryCandidates(nameRaw, resolveOpts);
         }
         const nodeId = process.env['CRTR_NODE_ID'] || undefined;
-        if (doc === undefined) {
-            // No doc answers for a directory — the bare listing does. An explicit
-            // dir read is a deliberate act, so every line renders (unlisted
-            // excluded), never dedup-filtered; rendered members still record at
-            // preview so unsolicited channels stay quiet about them later.
-            const dirName = normalizeDocName(nameRaw.replace(/\/+$/, ''));
-            const byName = docsByName(corpusDocs());
-            if (dirName !== '' && isDirName(byName, dirName)) {
-                const seen = nodeId !== undefined ? loadInjectedDocs(nodeId) : null;
-                const listing = renderDirListing(byName, dirName, seen, false);
-                if (nodeId !== undefined && seen !== null) {
-                    recordDelivery(seen, dirDedupKey(dirName), 'preview');
-                    saveInjectedDocs(nodeId, seen);
+        if (set === null) {
+            // No document answers this name — a directory with no document of its own
+            // still does, through its listing. An explicit dir read is a deliberate
+            // act, so every line renders (unlisted excluded), never dedup-filtered;
+            // rendered members still record at preview so unsolicited channels stay
+            // quiet about them later.
+            const dirName = canonicalSegments(nameRaw.trim()).join('/');
+            if (dirName !== '' && isDirName(listingByName, dirName)) {
+                const contextExposure = nodeId !== undefined ? loadContextExposureState(nodeId) : null;
+                const target = contextExposure === null ? null : exposureTarget(contextExposure, 'transcript');
+                const listing = renderDirListing(listingByName, dirName, target, false);
+                if (nodeId !== undefined && contextExposure !== null && target !== null) {
+                    registerExposure(target, dirDedupKey(dirName), 'preview');
+                    saveContextExposureState(nodeId, contextExposure);
                 }
                 return {
                     name: dirName,
@@ -123,11 +172,9 @@ export const readLeaf = defineLeaf({
                     follow_up: 'Each line is readable with `crtr memory read <name>` — a `[[name]]: <line>` entry is a doc, a bare `[[name]]` is a subdirectory whose read browses deeper. Browse the whole inventory with `crtr memory list`.',
                 };
             }
-            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.',
-            });
+            fail();
         }
+        const doc = set.winner;
         const kind = effectiveDocKind(doc);
         const raw = readMemoryDocContent(doc.path, includeFrontmatter);
         // A read is an explicit act by an agent that can already run shell, so a
@@ -137,71 +184,76 @@ export const readLeaf = defineLeaf({
         const content = hasShellBlocks(raw)
             ? await expandShellBlocks(raw, makeNodeShellRunner({ cwd: process.cwd() }))
             : raw;
-        const byName = docsByName(corpusDocs());
         // `[[name]]` doc links are pointers, never transclusion: surface which
         // linked names actually resolve so the reader can follow one when the
         // task needs that depth, without ever auto-loading a linked body. A link
-        // may also name a directory — a browse link to its listing.
-        const links = docLinkNames(doc.body).filter((linkName) => {
-            if (isDirName(byName, linkName))
-                return true;
-            try {
-                // `resolveMemoryDoc` permits leaf-name fallback for interactive reads;
-                // a stored graph edge does not. Compare the resolved canonical name
-                // so an old shorthand never masquerades as a first-class doc link.
-                return resolveMemoryDoc(linkName, { includeDescendants: true }).name === linkName;
-            }
-            catch {
-                return false;
-            }
-        });
+        // is an exact canonical address — a directory name included, which browses
+        // to its listing.
+        const links = docLinkNames(doc.body).filter((linkName) => linkByName.has(linkName) || isDirName(linkByName, linkName));
         // Reading a doc discloses where it sits (its directory's listing and each
-        // ancestor's, once per transcript) and fires the memory-read event
+        // ancestor's, once per loaded context) and fires the memory-read event
         // (corpus docs whose `memory-read` entries match the resolved name).
         // Both prepend in one <auto-loaded-context> block. Without a node
         // identity the call is stateless: listings render undeduped and nothing
         // records.
-        const seen = nodeId !== undefined ? loadInjectedDocs(nodeId) : null;
+        const contextExposure = nodeId !== undefined
+            ? loadContextExposureState(nodeId)
+            : emptyContextExposureState();
+        const target = exposureTarget(contextExposure, 'transcript');
         const subject = await fetchSubject(nodeId);
         const excludeReal = realpathOrSelf(doc.path);
         // The explicit read IS a content delivery: record it first so unsolicited
         // channels (including this doc's own line in its directory listing) stay
         // quiet about a doc whose full body is already in the transcript.
-        if (seen !== null)
-            recordDelivery(seen, excludeReal, 'content');
+        registerDocumentExposure(target, doc.path, doc.body, 'content');
         const blocks = [];
-        for (const dir of ancestorDirsOf(doc.name)) {
-            if (seen !== null && deliveredAtOrAbove(seen, dirDedupKey(dir), 'preview'))
+        // A doc that fronts a directory carries its members with its body: that
+        // listing is part of the deliberate read (every line renders) and returns
+        // as `listing`, while the ancestors above it stay unsolicited neighborhood
+        // context. The node's own document is never among its children, so nothing
+        // repeats.
+        const dirs = docListingDirs(listingByName, doc.name);
+        const ownDir = dirs[0] === doc.name;
+        let listing;
+        if (ownDir) {
+            listing = renderDirListing(listingByName, doc.name, target, false);
+            registerExposure(target, dirDedupKey(doc.name), 'preview');
+        }
+        for (const dir of ownDir ? dirs.slice(1) : dirs) {
+            if (exposedAtOrAbove(contextExposure, dirDedupKey(dir), 'preview'))
                 continue;
-            const lines = renderDirListing(byName, dir, seen, true);
-            if (seen !== null)
-                recordDelivery(seen, dirDedupKey(dir), 'preview');
+            const lines = renderDirListing(listingByName, dir, target, true);
+            registerExposure(target, dirDedupKey(dir), 'preview');
             if (lines.length > 0)
                 blocks.push(`<memory-listing dir="${attr(dir)}">\n${lines.join('\n')}\n</memory-listing>`);
         }
-        const targetNames = [doc.name];
-        if (doc.plugin !== undefined) {
-            const slash = doc.name.indexOf('/');
-            if (slash > 0)
-                targetNames.push(doc.name.slice(slash + 1));
-        }
-        blocks.push(...memoryReadDocBlocks(subject, excludeReal, targetNames, seen ?? new Map()));
-        if (nodeId !== undefined && seen !== null)
-            saveInjectedDocs(nodeId, seen);
+        blocks.push(...memoryReadDocBlocks(subject, excludeReal, doc.name, target));
+        if (nodeId !== undefined)
+            saveContextExposureState(nodeId, contextExposure);
         const finalContent = blocks.length === 0 ? content : `<auto-loaded-context>\n${blocks.join('\n')}\n</auto-loaded-context>\n\n${content}`;
+        const hasListing = listing !== undefined && listing.length > 0;
+        const followUp = hasListing
+            ? links.length > 0
+                ? 'Each `[[name]]` line in `listing` is one of this directory’s immediate members, and the `[[name]]` links in the body are further reading — follow either with `crtr memory read <name>` only when the task needs that depth.'
+                : 'Each `[[name]]` line in `listing` is one of this directory’s immediate members, readable with `crtr memory read <name>` — follow one only when the task needs that depth.'
+            : links.length > 0
+                ? 'The `[[name]]` links in the body are further reading — follow one with `crtr memory read <name>` only when the task needs that depth.'
+                : null;
         return {
             name: doc.name,
+            local_name: doc.localName,
             kind,
             scope: doc.scope,
             path: doc.path,
+            store_root: doc.root,
+            physical_relative_path: doc.physicalRelativePath,
+            representation: doc.representation,
+            ...(set.candidates.length > 1 ? { candidates: set.candidates.map((c) => candidateRow(c, doc)) } : {}),
             content: finalContent,
+            ...(hasListing ? { listing } : {}),
             extensions: projectEffectiveMemoryExtensions(doc.frontmatter?.['extensions'], memoryExtensionEffectiveCatalog(doc)),
-            ...(links.length > 0
-                ? {
-                    links,
-                    follow_up: 'The `[[name]]` links in the body are further reading — follow one with `crtr memory read <name>` only when the task needs that depth.',
-                }
-                : {}),
+            ...(links.length > 0 ? { links } : {}),
+            ...(followUp === null ? {} : { follow_up: followUp }),
         };
     },
     render: (result) => {

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

@@ -1,40 +1,122 @@
 import { type FlagParam } from '../../core/help.js';
-import type { MemoryDoc, MemoryScope } from '../../core/memory-resolver.js';
+import { type MemoryCandidateSet, type MemoryDoc, type MemoryScope, type MemoryStoreDescriptor } from '../../core/memory-resolver.js';
+import { type DocRepresentation } from '../../core/memory/identity.js';
 import { type MemoryExtensionCatalog } from '../../core/memory/extensions.js';
 import type { MemoryExtensionScalar } from '../../types.js';
 export declare const MEMORY_KINDS: readonly ["knowledge", "preference"];
+export declare const MEMORY_READ_SCOPES: readonly ["user", "project", "profile", "node", "builtin"];
+export declare const MEMORY_WRITE_SCOPES: readonly ["user", "project", "profile", "node"];
 export declare const MEMORY_SCOPES: readonly ["user", "project", "profile", "node"];
 /** Scope sort weight matching resolution precedence (node > project stack >
  *  profile > user > builtin). Used by `list` for its "scope then kind then
  *  name" ordering. */
 export declare function scopeRank(scope: MemoryScope): number;
-/** Resolve the write target scope + its memory dir. Default: project when a
- *  project scope exists for the cwd, else user. An explicit `--scope project`
- *  with no project scope yet scaffolds one (ensureProjectScopeRoot). User scope
- *  always resolves. `--scope profile` is NEVER a default — it requires a
- *  selected profile, from `profileArg` (an explicit `--profile <id-or-name>`)
- *  or else the process's `CRTR_PROFILE_ID`, resolved through the centralized
- *  `loadProfileManifest` (never a raw path join). `dirArg` (an explicit
- *  `--dir <path>`) pins the EXACT project directory, cwd-free: the target is
- *  `<dir>/.crouter/memory/`, scaffolded if absent, never the cwd-ancestor walk
- *  — the way a profiled agent writes into any project in its purview, and the
- *  only way to target a dir shadowed by an ancestor store. `--scope node`
- *  targets the this-node store (`nodes/<CRTR_NODE_ID>/context/memory/`) and
- *  requires a running node. Returns the absolute `<root>/memory` dir to write
- *  under. */
+export declare function registerMemoryListingExposure(identity: string): void;
+/** The raw selector flags a memory leaf accepts. */
+export interface MemorySelectorInput {
+    scope?: string | undefined;
+    dir?: string | undefined;
+    profile?: string | undefined;
+}
+export interface MemoryReadSelector {
+    /** Source-stack filter for a target view, absent when unfiltered. */
+    scope?: MemoryScope;
+    /** The one exact store `--dir` selected, or null for a target view. Returned
+     *  whatever its mount status: lint inspects a store the runtime refuses to
+     *  mount, everything else calls `requireMountedStore` first. */
+    store: MemoryStoreDescriptor | null;
+}
+export interface MemoryWriteSelector {
+    scope: MemoryScope;
+    /** Absolute `<root>/memory` dir the document is written under. */
+    memoryDir: string;
+    /** The store its canonical name composes under. */
+    store: MemoryStoreDescriptor;
+}
+/** Resolve the read selection: a scope filter, or the exact store `--dir`
+ *  names. */
+export declare function resolveReadSelector(input: MemorySelectorInput): MemoryReadSelector;
+/** Resolve the one store a mutation writes to. Default: project when a project
+ *  scope exists for the cwd, else user. An explicit `--scope project` with no
+ *  project scope yet scaffolds one (`ensureProjectScopeRoot`). `--scope
+ *  profile` is NEVER a default — it requires a selected profile, from
+ *  `--profile <id-or-name>` or else the process's `CRTR_PROFILE_ID`, resolved
+ *  through the centralized `loadProfileManifest` (never a raw path join).
+ *  `--scope node` targets the this-node store
+ *  (`nodes/<CRTR_NODE_ID>/context/memory/`) and requires a running node. */
+export declare function resolveWriteSelector(input: MemorySelectorInput): MemoryWriteSelector;
+/** The scope + memory dir a write lands in. Retained for the leaves that still
+ *  place documents by path alone; they cut over to `resolveWriteSelector` and
+ *  `planNewDocumentPlacement` in their own phases. */
 export declare function resolveWriteTarget(scopeArg: string | undefined, profileArg?: string, dirArg?: string): {
     scope: MemoryScope;
     memoryDir: string;
 };
+/** Refuse a project store the runtime will not resolve through. A project
+ *  repository-root store carries the identity every canonical name in it composes under, so
+ *  without a valid declaration no name can be validated, stripped, or placed;
+ *  user, profile, and node stores have no declaration and always pass, even
+ *  before their directory exists. */
+export declare function requireMountedStore(store: MemoryStoreDescriptor): MemoryStoreDescriptor;
+/** Normalize and validate a full canonical name: ordering prefixes are
+ *  physical-path-only, a trailing `INDEX` is never an address, and the segment
+ *  charset is fixed. */
+export declare function requireCanonicalName(rawName: string): string;
+/** The store-local name a full canonical name has inside one exact store, or a
+ *  usage error when it falls outside that store's namespace. `''` names the
+ *  store's own root document — a project store answers at its namespace. */
+export declare function requireLocalNameInStore(store: MemoryStoreDescriptor, rawName: string): string;
+export interface MemoryPlacement {
+    store: MemoryStoreDescriptor;
+    /** Full canonical name — the address the document answers at. */
+    canonicalName: string;
+    /** Store-local name, `''` for the store's own root document. */
+    localName: string;
+    representation: DocRepresentation;
+    /** Store-relative markdown path. */
+    physicalRelativePath: string;
+    /** Absolute path of the `.md` file. */
+    path: string;
+}
+/** Where a NEW document (a `write`, a `move` destination) physically lands in
+ *  one exact store, after proving the canonical identity is free.
+ *
+ *  Both physical forms carry the same identity, so occupancy is checked against
+ *  the loaded identities AND both `<local>.md` and `<local>/INDEX.md` — a file
+ *  whose explicit `name:` points elsewhere still owns its path. The chosen form
+ *  is `<local>/INDEX.md` when the canonical directory already has descendants
+ *  in this store (the document fronts a directory that exists), else
+ *  `<local>.md`; descendants created later never relocate it, because either
+ *  form validly owns the identity. Pass `storeDocs` when the caller already
+ *  loaded the store, and `source` when planning a move, whose own identity and
+ *  file are being vacated. */
+export declare function planNewDocumentPlacement(store: MemoryStoreDescriptor, rawName: string, storeDocs?: readonly MemoryDoc[], source?: MemoryDoc): MemoryPlacement;
+/** The document a mutation acts on, refusing an identity two files in ONE
+ *  store both own. Reads stay answerable (`<name>/INDEX.md` deterministically
+ *  wins), but a mutation would silently pick one of two files, so it stops with
+ *  both paths. Candidates in OTHER stores are ordinary alternates — precedence
+ *  picked the winner and `--dir` reaches the rest. */
+export declare function requireUnambiguousDoc(set: MemoryCandidateSet): MemoryDoc;
+/** Move and delete are the only mutation recovery path for a same-store
+ *  collision. The exact-store winner remains the ordinary target; only the
+ *  selected store's candidates are ordered by their physical path. */
+export interface MutationDocSelection {
+    doc: MemoryDoc;
+    collisionPaths: readonly string[];
+}
+export declare function selectMutationDoc(set: MemoryCandidateSet): MutationDocSelection;
 /** Remove a just-removed file's now-empty parent directories up to (never
- *  including) its tree root, so removing the last entry under an `area/`
- *  prefix does not orphan an empty directory. The root is derived by walking
- *  up one dirname per name segment: a doc named `a/b` sits at `<root>/a/b.md`,
- *  so its root is two dirnames above — the same arithmetic holds for a
- *  `.history/<name>.jsonl` sidecar. Stops at the first non-empty ancestor. */
-export declare function pruneEmptyParents(filePath: string, nameSegments: number): void;
-/** Map a path-derived name (`topic` or `area/topic`) to its file path under a
- *  memory dir, guarding against traversal/absolute escapes. */
+ *  including) its store root, so removing the last entry under an `area/`
+ *  prefix does not orphan an empty directory. `pathSegments` counts the
+ *  PHYSICAL store-relative path (`doc.physicalRelativePath.split('/').length`),
+ *  never the canonical name, which carries the store's namespace on top of it —
+ *  the same count addresses a `.history/<path>.jsonl` sidecar. Stops at the
+ *  first non-empty ancestor. */
+export declare function pruneEmptyParents(filePath: string, pathSegments: number): void;
+/** Map a STORE-LOCAL name (`topic`, `area/topic`, `INDEX`) to its file path
+ *  under a memory dir, guarding against traversal/absolute escapes. Physical
+ *  mapping only: it composes no namespace and collapses no `INDEX`, so a
+ *  canonical name reaches it through `planNewDocumentPlacement`. */
 export declare function memoryFilePath(memoryDir: string, name: string): string;
 export declare function coerceGate(raw: string): Record<string, unknown>;
 /** Coerce one `--surface` value into a validated surfaces entry. Strict where
@@ -96,6 +178,13 @@ export declare function applyExtensionChanges(frontmatter: Record<string, unknow
 /** The frontmatter-overlay flags, keyed by flag name, carrying the prose true
  *  on BOTH leaves. `write` appends its creation clauses with `withConstraint`;
  *  neither leaf restates the other's rules. */
+/** The selector flags, keyed by flag name, carrying the prose true on every
+ *  leaf that accepts them. A leaf appends its own clause with `selectorParam`;
+ *  none of them restates the shared rules. */
+export declare const SELECTOR_PARAMS: Record<string, FlagParam>;
+/** One selector flag, with leaf-specific prose appended to the shared
+ *  constraint and any leaf-specific schema override applied. */
+export declare function selectorParam(name: string, overrides?: Partial<FlagParam>, extraConstraint?: string): FlagParam;
 export declare const FRONTMATTER_OVERLAY_PARAMS: Record<string, FlagParam>;
 /** One overlay flag, with leaf-specific prose appended to the shared
  *  constraint and any leaf-specific schema override applied. */
@@ -105,8 +194,9 @@ export declare function overlayParam(name: string, overrides?: Partial<FlagParam
  *  `--doc-rationale`, because `--rationale` there means why THIS REVISION is
  *  happening. Same field, same prose, two flag names that cannot be confused. */
 export declare const DOC_RATIONALE_CONSTRAINT = "Frontmatter rationale \u2014 the observed agent failure that made this doc necessary. Maintainer-facing only: never ships in any delivered surface (boot render, on-read injection, `memory read` content), visible only via `memory read --frontmatter`. Omitting the flag preserves an existing rationale unchanged.";
-export declare const GUIDE_SURFACES = "Every doc appears in its directory\u2019s listing by default (suppress with --unlisted); everything beyond the listing is explicit `surfaces` routing \u2014 entries declaring WHEN the doc delivers and how much. Events: `boot` delivers in the boot catalog every agent sees; `workspace-open` delivers in first-message context when cwd/profile mounts the doc\u2019s project store (project stores only); `read` fires when the agent reads a matching file (globs vs the file\u2019s absolute path and basename, `./`-anchored globs vs its path relative to the store\u2019s owning repo dir, `match-frontmatter` predicates over the read file\u2019s own YAML frontmatter); `memory-read` fires when another memory doc is read (globs vs that doc\u2019s canonical name, `./` anchored to this doc\u2019s own name directory); `command` fires when a matching shell command runs (globs vs the whole command string, `*` crossing `/`). An entry may also carry `gate`, a node-config predicate using the same vocabulary as the document-level `gate`: event constraints and entry gate both must match, then all participating entries fold to the highest `at` (`content` > `preview` > `name`), with no cross-entry deny precedence. The document-level `gate` remains the hard eligibility check: when it fails, no automatic surface can deliver the document. `at` sets how much delivers: `name` the bare tag, `preview` the routing line, `content` the whole body. Explicit `memory read` and listings remain deliberate access and ignore gates/rungs; only companion docs routed by their `memory-read` entries use entry gates. Each entry is paid by every future agent it fires on, so default down: no surfaces at all is correct for reference depth reached through listings and [[links]], and when a doc fits in a single sentence, deliver `content` directly \u2014 a `preview` routing line would run longer than the doc itself. Sentence-length `content` docs are correct; never pad a memory to be more verbose than the rule or fact it carries.";
+export declare const GUIDE_SURFACES = "Every doc appears in its directory\u2019s listing by default (suppress with --unlisted); everything beyond the listing is explicit `surfaces` routing \u2014 entries declaring WHEN the doc delivers and how much. Events: `boot` delivers in the boot catalog every agent sees; `workspace-open` delivers in first-message context when cwd/profile mounts the doc\u2019s project store (project stores only); `read` fires when the agent reads a matching file (globs vs the file\u2019s absolute path and basename, `./`-anchored globs vs its path relative to the store\u2019s owning repo dir, `match-frontmatter` predicates over the read file\u2019s own YAML frontmatter); `memory-read` fires when another memory doc is read (globs vs that doc\u2019s canonical name, `./` anchored to this doc\u2019s routing anchor \u2014 its own canonical name when it is its directory\u2019s document, otherwise the canonical directory it sits in); `command` fires when a matching shell command runs (globs vs the whole command string, `*` crossing `/`). An entry may also carry `gate`, a node-config predicate using the same vocabulary as the document-level `gate`: event constraints and entry gate both must match, then all participating entries fold to the highest `at` (`content` > `preview` > `name`), with no cross-entry deny precedence. The document-level `gate` remains the hard eligibility check: when it fails, no automatic surface can deliver the document. `at` sets how much delivers: `name` the bare tag, `preview` the routing line, `content` the whole body. Explicit `memory read` and listings remain deliberate access and ignore gates/rungs; only companion docs routed by their `memory-read` entries use entry gates. Each entry is paid by every future agent it fires on, so default down: no surfaces at all is correct for reference depth reached through listings and [[links]], and when a doc fits in a single sentence, deliver `content` directly \u2014 a `preview` routing line would run longer than the doc itself. Sentence-length `content` docs are correct; never pad a memory to be more verbose than the rule or fact it carries.";
 export declare const GUIDE_ROUTING_LINE = "The routing line (--when-and-why-to-read) is the only text an agent reads before deciding to load the doc. The test for its when-clause: it names an observable circumstance in the reader\u2019s current work, not the doc\u2019s topic reworded as an activity. If the WHEN can be inferred from the title alone, it is not a real trigger. Bad on a todo list: \"When planning or prioritizing work across this profile.\" Good: \"When the user mentions something from their todos, or asks what is still outstanding across this profile.\" The test for its because-clause: if it can be derived by paraphrasing the doc\u2019s advice, it is a restatement, not a payoff \u2014 a real payoff names a consequence in the reader\u2019s world that the document itself never asserts. Bad: \"because only genuine first principles belong in taste memory.\" Bad: \"because keeping the test loop fast and free of speculative tests protects the development pace\" \u2014 the doc\u2019s rule as an outcome, derivable straight from its advice. Good: \"because identifying throughlines in user taste lets future decisions be made faster and with less re-litigation.\" Someone mid-task who has not read the doc must be able to decide from this line alone whether the read is worth it. If you cannot name the concrete situation that triggers it, you do not yet understand the memory \u2014 ask the user one sharp question instead of improvising.";
 export declare const GUIDE_PREDICATE_VOCABULARY = "Document gates, surface-entry gates, and match-frontmatter share the same predicate language: a field map is AND-ed across fields; dotted fields resolve nested values; field matchers may be scalar, array, or object. Scalar matchers do exact equality, with arrays matching any element. Array matchers do membership or intersection. Object matchers accept `eq`, `ne`, `in`, `nin`, `exists`, `contains`, `containsAll`, `containsAny`, `matches`, `imatches`, `gt`, `gte`, `lt`, and `lte`. Combinators are `all`, `any`, and `not`; sibling field matchers next to them are AND-ed in. An empty condition is inert. An unknown op never matches.";
-export declare const GUIDE_DOC_LINKS = "Link related docs with `[[canonical/name]]`. A doc link in any body is a first-class cross-reference to another memory document by its exact canonical name \u2014 the same identifier `crtr memory read` takes. A bare directory name is a valid link too: following it returns that directory\u2019s listing, a browse entrance rather than a doc. Links are pointers, never transclusion: the linked body is loaded only when a reader follows it, so a link costs nothing until needed. `crtr memory lint` fails on a link that resolves to no document or directory, and `crtr memory read` lists a doc\u2019s resolvable links alongside its body. There is no alias or label form.";
+export declare const GUIDE_DOC_LINKS = "Link related docs with `[[canonical/name]]`. A doc link in any body is a first-class cross-reference to another memory document by its exact canonical name \u2014 the same identifier `crtr memory read` takes, namespace included for a project document. A bare directory name is a valid link too: following it returns that directory\u2019s own document when it has one, plus the directory listing. Links are pointers, never transclusion: the linked body is loaded only when a reader follows it, so a link costs nothing until needed. `crtr memory lint` fails on a link that resolves to no document or directory, and `crtr memory read` lists a doc\u2019s resolvable links alongside its body. There is no alias, label, or old-name form \u2014 a renamed target needs its links rewritten.";
+export declare const GUIDE_CANONICAL_NAMES = "A document has exactly one address: its canonical name, the store\u2019s namespace composed with the document\u2019s store-local name. A repository declares its namespace once, as `namespace:` on the root `INDEX.md` of `<repository root>/.crouter/memory/`; a store nested inside that repository composes under the repository namespace plus its own directory path relative to the repository root, and declares nothing itself. An installed plugin\u2019s store mounts under the plugin\u2019s own name; user, profile, node, and builtin stores have no namespace, so their local names are already canonical. A local doc `unit-tests` in a store that declares `namespace: acme/core` therefore answers only at `acme/core/unit-tests`, and the store\u2019s root document answers at `acme/core`; a store at `packages/api/.crouter/memory/` in a repository declaring `namespace: acme` answers under `acme/packages/api`. A non-root explicit `name:` in frontmatter is store-LOCAL \u2014 it never carries the namespace, and composition is unconditional, so a name that merely looks prefixed is prefixed again. The namespace itself is immutable through the memory commands: `crtr memory write <namespace> --dir <repository root>` declares it once in an empty repository-root store, `crtr sys migrate --dir <repository root>` converts a legacy one, and nothing else rewrites it. A trailing `INDEX` is never part of an address in any store: `area/INDEX.md` is the document attached to directory `area`, so it answers at `area` and reading `area` returns that body together with the directory\u2019s immediate listing. Resolution is exact \u2014 a file path, a bare leaf, a `<scope>/<name>` spelling, and a trailing `/INDEX` all fail \u2014 so run `crtr memory find <leaf>` when you do not know the canonical name.";
 export {};