@north-light/crouter 0.3.227 → 0.3.228

package/dist/commands/memory/shared.js

@@ -7,104 +7,165 @@ import { existsSync, readdirSync, realpathSync, rmdirSync, statSync } from 'node
 import { dirname, join, resolve as resolvePath } from 'node:path';
 import { stringify as yamlStringify, parse as yamlParse } from 'yaml';
 import { stateBlock } from '../../core/help.js';
+import { loadStoreMemoryDocs, openProjectMemoryStore, } from '../../core/memory-resolver.js';
+import { canonicalSegments, physicalRelativePathFor, stripNamespace, validateExplicitLocalName, } from '../../core/memory/identity.js';
+import { pathExists, realpathOrSelf } from '../../core/fs-utils.js';
 import { usage } from '../../core/errors.js';
 import { memoryExtensionValidationCatalog, } from '../../core/memory/extensions.js';
 import { CRTR_DIR_NAME } from '../../types.js';
-import { scopeMemoryDir, projectScopeRoot, ensureProjectScopeRoot, resetScopeCache, } from '../../core/scope.js';
+import { NEUTRAL_PROJECT_MEMORY, scopeMemoryDir, projectScopeRoot, ensureProjectScopeRoot, resetScopeCache, } from '../../core/scope.js';
 import { loadProfileManifest, profileMemoryDir } from '../../core/profiles/manifest.js';
 import { memoryDir as nodeMemoryDir } from '../../core/runtime/memory.js';
 import { SURFACE_EVENTS, SURFACE_RUNGS } from '../../core/substrate/schema.js';
+import { exposureTarget, loadContextExposureState, registerExposure, saveContextExposureState, } from '../../core/substrate/injected-store.js';
 // The two memory kinds — knowledge (consult: procedural playbooks + factual
 // references merged) vs preference (behave: standing directives). Used as the
 // `--kind` enum choices everywhere.
 export const MEMORY_KINDS = ['knowledge', 'preference'];
-// Scope choices for filtering / targeting (builtin is read-only, not writable).
+// Scope choices for READ-ONLY source filtering — every scope a target view
+// mounts, builtin included. A scope narrows the source stack only: the query is
+// still the full canonical name.
+export const MEMORY_READ_SCOPES = ['user', 'project', 'profile', 'node', 'builtin'];
+// Scope choices a mutation may target. builtin ships with the package and
+// installed-plugin stores are managed by `crtr pkg`, so neither is writable.
 // `node` is the this-node store, writable only inside a running node.
-export const MEMORY_SCOPES = ['user', 'project', 'profile', 'node'];
+export const MEMORY_WRITE_SCOPES = ['user', 'project', 'profile', 'node'];
+// Retained for the leaves that have not yet split their read filter from their
+// write target; each cuts over to the pair above in its own phase.
+export const MEMORY_SCOPES = MEMORY_WRITE_SCOPES;
 /** Scope sort weight matching resolution precedence (node > project stack >
  *  profile > user > builtin). Used by `list` for its "scope then kind then
  *  name" ordering. */
 export function scopeRank(scope) {
     return scope === 'node' ? -1 : scope === 'project' ? 0 : scope === 'profile' ? 1 : scope === 'user' ? 2 : 3;
 }
-/** 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 function resolveWriteTarget(scopeArg, profileArg, dirArg) {
-    if (dirArg !== undefined && dirArg !== '') {
-        if (scopeArg !== undefined && scopeArg !== 'project') {
-            throw usage(`--dir targets a project store and cannot combine with --scope ${scopeArg}`);
-        }
-        if (profileArg !== undefined && profileArg !== '') {
-            throw usage('--profile only applies to --scope profile; --dir targets a project store', {
-                received: profileArg,
-                next: 'Drop --profile when using --dir.',
-            });
-        }
-        const abs = resolvePath(dirArg);
-        if (!existsSync(abs) || !statSync(abs).isDirectory()) {
-            throw usage(`--dir does not exist or is not a directory: ${dirArg}`, {
-                received: dirArg,
-                next: 'Pass an existing project directory.',
-            });
-        }
-        let real = abs;
-        try {
-            real = realpathSync(abs);
-        }
-        catch {
-            /* fall back to the resolved path */
-        }
-        // The scaffold (mkdir of `.crouter/memory/`) happens at write time via the
-        // writer's ensureDir; drop the scope cache so this process's later
-        // resolves see the new root.
-        resetScopeCache();
-        return { scope: 'project', memoryDir: join(real, CRTR_DIR_NAME, 'memory') };
+export function registerMemoryListingExposure(identity) {
+    const nodeId = process.env['CRTR_NODE_ID'];
+    if (nodeId === undefined || nodeId === '')
+        return;
+    const state = loadContextExposureState(nodeId);
+    registerExposure(exposureTarget(state, 'transcript'), identity, 'content');
+    saveContextExposureState(nodeId, state);
+}
+function rejectDirConflicts(input) {
+    if (input.scope !== undefined && input.scope !== '') {
+        throw usage(`--dir selects the project store itself and cannot combine with --scope ${input.scope}`, {
+            received: `--dir ${input.dir} --scope ${input.scope}`,
+            next: 'Drop --scope: --dir already pins the exact project store.',
+        });
+    }
+    if (input.profile !== undefined && input.profile !== '') {
+        throw usage('--profile only applies to --scope profile; --dir selects a project store', {
+            received: input.profile,
+            next: 'Drop --profile when using --dir.',
+        });
+    }
+}
+/** The realpathed project owner directory `--dir` names. */
+function ownerDirFromArg(dirArg) {
+    const abs = resolvePath(dirArg);
+    if (!existsSync(abs) || !statSync(abs).isDirectory()) {
+        throw usage(`--dir does not exist or is not a directory: ${dirArg}`, {
+            received: dirArg,
+            next: 'Pass an existing project directory.',
+        });
+    }
+    try {
+        return realpathSync(abs);
     }
-    let scope;
-    if (scopeArg === 'user' || scopeArg === 'project' || scopeArg === 'profile' || scopeArg === 'node') {
-        scope = scopeArg;
+    catch {
+        return abs;
     }
-    else if (scopeArg !== undefined) {
-        throw usage(`invalid --scope: ${scopeArg} (expected user|project|profile|node)`);
+}
+function parseScope(scopeArg, allowed) {
+    if (scopeArg === undefined || scopeArg === '')
+        return undefined;
+    if (!allowed.includes(scopeArg)) {
+        throw usage(`invalid --scope: ${scopeArg} (expected ${allowed.join('|')})`);
     }
-    else {
-        scope = projectScopeRoot() !== null ? 'project' : 'user';
+    return scopeArg;
+}
+/** A store with no namespace of its own: user, profile, node. */
+function nativeStoreDescriptor(scope, memoryDir) {
+    return {
+        scope,
+        storeRoot: memoryDir,
+        namespace: '',
+        mountStatus: pathExists(memoryDir) ? 'ready' : 'absent',
+        projectMemory: NEUTRAL_PROJECT_MEMORY,
+    };
+}
+/** Resolve the read selection: a scope filter, or the exact store `--dir`
+ *  names. */
+export function resolveReadSelector(input) {
+    if (input.dir !== undefined && input.dir !== '') {
+        rejectDirConflicts(input);
+        return { store: openProjectMemoryStore(ownerDirFromArg(input.dir)) };
+    }
+    if (input.profile !== undefined && input.profile !== '' && input.scope !== 'profile') {
+        throw usage(`--profile only applies to --scope profile (received scope: ${input.scope ?? 'none'})`, {
+            received: input.profile,
+            next: 'Drop --profile, or pass --scope profile to target a specific profile store.',
+        });
     }
-    if (profileArg !== undefined && profileArg !== '' && scope !== 'profile') {
+    const scope = parseScope(input.scope, MEMORY_READ_SCOPES);
+    if (input.profile !== undefined && input.profile !== '') {
+        // Naming a profile selects THAT profile's store exactly; the ambient
+        // selection would otherwise answer for whichever profile this process runs
+        // under, silently ignoring the flag.
+        const { profileId } = loadProfileManifest(input.profile);
+        return { scope: 'profile', store: nativeStoreDescriptor('profile', profileMemoryDir(profileId)) };
+    }
+    return { ...(scope === undefined ? {} : { scope }), store: null };
+}
+/** 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 function resolveWriteSelector(input) {
+    if (input.dir !== undefined && input.dir !== '') {
+        rejectDirConflicts(input);
+        const owner = ownerDirFromArg(input.dir);
+        // The scaffold (mkdir of `.crouter/memory/`) happens at write time via the
+        // writer's ensureDir; drop the scope cache so this process's later resolves
+        // see the new root.
+        resetScopeCache();
+        return {
+            scope: 'project',
+            memoryDir: join(owner, CRTR_DIR_NAME, 'memory'),
+            store: openProjectMemoryStore(owner),
+        };
+    }
+    const requested = parseScope(input.scope, MEMORY_WRITE_SCOPES);
+    const scope = requested ?? (projectScopeRoot() !== null ? 'project' : 'user');
+    if (input.profile !== undefined && input.profile !== '' && scope !== 'profile') {
         throw usage(`--profile only applies to --scope profile (resolved scope: ${scope})`, {
-            received: profileArg,
+            received: input.profile,
             next: 'Drop --profile, or pass --scope profile to target a specific profile store.',
         });
     }
     if (scope === 'node') {
-        // The this-node store: `nodes/<CRTR_NODE_ID>/context/memory/`. Available
-        // only inside a running node; the same dir render.ts's nodeLocalDocs loads
-        // at boot, so a doc written here rides into this node's knowledge block.
+        // The this-node store: the same dir render.ts's nodeLocalDocs loads at
+        // boot, so a doc written here rides into this node's knowledge block.
         const nodeId = process.env['CRTR_NODE_ID'] || '';
         if (nodeId === '') {
             throw usage('node scope requires a running node (CRTR_NODE_ID unset); rerun inside a node');
         }
-        return { scope: 'node', memoryDir: nodeMemoryDir(nodeId) };
+        const memoryDir = nodeMemoryDir(nodeId);
+        return { scope, memoryDir, store: nativeStoreDescriptor(scope, memoryDir) };
     }
     if (scope === 'profile') {
-        const profileIdOrName = profileArg && profileArg !== '' ? profileArg : process.env['CRTR_PROFILE_ID'] || '';
+        const profileIdOrName = input.profile && input.profile !== '' ? input.profile : process.env['CRTR_PROFILE_ID'] || '';
         if (profileIdOrName === '') {
             throw usage('profile scope requires a selected profile; rerun inside a profiled node or pass --profile');
         }
         const { profileId } = loadProfileManifest(profileIdOrName);
-        return { scope: 'profile', memoryDir: profileMemoryDir(profileId) };
+        const memoryDir = profileMemoryDir(profileId);
+        return { scope, memoryDir, store: nativeStoreDescriptor(scope, memoryDir) };
     }
     let memoryDir = scopeMemoryDir(scope);
     if (!memoryDir && scope === 'project') {
@@ -113,17 +174,166 @@ export function resolveWriteTarget(scopeArg, profileArg, dirArg) {
     }
     if (!memoryDir)
         throw usage(`no ${scope} scope available for writing memory documents`);
+    if (scope === 'project') {
+        return { scope, memoryDir, store: openProjectMemoryStore(dirname(dirname(memoryDir))) };
+    }
+    return { scope, memoryDir, store: nativeStoreDescriptor(scope, memoryDir) };
+}
+/** 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 function resolveWriteTarget(scopeArg, profileArg, dirArg) {
+    const { scope, memoryDir } = resolveWriteSelector({ scope: scopeArg, profile: profileArg, dir: dirArg });
     return { scope, memoryDir };
 }
+/** 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 function requireMountedStore(store) {
+    if (store.scope !== 'project' || store.mountStatus === 'ready')
+        return store;
+    const owner = store.ownerDir ?? store.storeRoot;
+    if (store.mountStatus === 'absent') {
+        throw usage(`no memory store at ${store.storeRoot}`, {
+            next: `Initialize it with \`crtr memory write <namespace> --dir ${owner}\`, which declares the repository namespace.`,
+        });
+    }
+    const repositoryRoot = store.repositoryRoot ?? owner;
+    throw usage(store.diagnostic ?? `project memory store at ${store.storeRoot} does not declare a namespace`, {
+        next: `Run \`crtr sys migrate --dir ${repositoryRoot}\`.`,
+    });
+}
+// ---------------------------------------------------------------------------
+// Canonical name → physical placement
+//
+// Every surface takes the FULL canonical name. Placement strips the selected
+// store's namespace off it, checks that neither the identity nor either
+// physical representation of the local name is already taken, and picks the
+// form the new file takes.
+// ---------------------------------------------------------------------------
+/** 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 function requireCanonicalName(rawName) {
+    const name = canonicalSegments(rawName.trim()).join('/');
+    if (name === '')
+        throw usage('memory document name required');
+    const valid = validateExplicitLocalName(name);
+    if (!valid.ok) {
+        throw usage(`invalid memory document name \`${rawName}\`: ${valid.reason}`, {
+            received: rawName,
+            next: 'Pass the full canonical name (a project document is <namespace>/<local name>); run `crtr memory find <leaf>` to look one up.',
+        });
+    }
+    return name;
+}
+/** 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 function requireLocalNameInStore(store, rawName) {
+    requireMountedStore(store);
+    const name = requireCanonicalName(rawName);
+    if (store.namespace === '')
+        return name;
+    const local = stripNamespace(name, store.namespace);
+    if (local === null) {
+        throw usage(`\`${name}\` is not in the namespace of the store at ${store.storeRoot} (\`${store.namespace}\`)`, {
+            memory: name,
+            next: `Every document there answers at \`${store.namespace}/<local name>\`; the store's own document answers at \`${store.namespace}\`.`,
+        });
+    }
+    return local;
+}
+/** 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 function planNewDocumentPlacement(store, rawName, storeDocs, source) {
+    const localName = requireLocalNameInStore(store, rawName);
+    const canonicalName = requireCanonicalName(rawName);
+    const docs = storeDocs ?? loadStoreMemoryDocs(store, true);
+    // A move's own source occupies neither the identity nor the path it is
+    // vacating: retiring an explicit `name:` pin back to the file's path-derived
+    // identity lands the document exactly where it already sits.
+    const sourceReal = source === undefined ? null : realpathOrSelf(source.path);
+    const owner = docs.find((d) => d.name === canonicalName && realpathOrSelf(d.path) !== sourceReal);
+    if (owner !== undefined) {
+        throw usage(`${canonicalName} already exists in ${store.storeRoot}`, {
+            memory: canonicalName,
+            path: owner.path,
+            next: `Revise it with \`crtr memory edit ${canonicalName}\`, which records the change, or move it with \`crtr memory move\`.`,
+        });
+    }
+    const forms = localName === '' ? ['directory-index'] : ['directory-index', 'leaf-file'];
+    const taken = forms
+        .map((representation) => join(store.storeRoot, physicalRelativePathFor(localName, representation)))
+        .filter((path) => pathExists(path) && realpathOrSelf(path) !== sourceReal);
+    if (taken.length > 0) {
+        throw usage(`${canonicalName} cannot be created: ${taken.join(' and ')} already exists`, {
+            memory: canonicalName,
+            path: taken.join(', '),
+            next: 'Both `<name>.md` and `<name>/INDEX.md` carry that identity. Read the existing file, then edit, move, or delete it.',
+        });
+    }
+    const representation = localName === '' || docs.some((d) => d.localName.startsWith(`${localName}/`)) ? 'directory-index' : 'leaf-file';
+    const physicalRelativePath = physicalRelativePathFor(localName, representation);
+    return {
+        store,
+        canonicalName,
+        localName,
+        representation,
+        physicalRelativePath,
+        path: join(store.storeRoot, physicalRelativePath),
+    };
+}
+/** 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 function requireUnambiguousDoc(set) {
+    const winner = set.winner;
+    const sameStore = set.candidates.filter((d) => d.store.storeRoot === winner.store.storeRoot);
+    if (sameStore.length > 1) {
+        throw usage(`${set.name} is owned by ${sameStore.length} files in one store: ${sameStore.map((d) => d.path).join(' and ')}`, {
+            memory: set.name,
+            path: sameStore.map((d) => d.path).join(', '),
+            next: `Recover the collision with \`crtr memory move ${set.name} --to <new-free-name>\`; it selects the first physical path in stable lexical order. Do not remove files by hand; \`crtr memory lint\` reports every such collision.`,
+        });
+    }
+    return winner;
+}
+export function selectMutationDoc(set) {
+    const sameStore = set.candidates.filter((d) => d.store.storeRoot === set.winner.store.storeRoot);
+    const ordered = [...sameStore].sort((a, b) => {
+        const byRelativePath = a.physicalRelativePath.localeCompare(b.physicalRelativePath);
+        return byRelativePath !== 0 ? byRelativePath : a.path.localeCompare(b.path);
+    });
+    return {
+        doc: ordered[0] ?? set.winner,
+        collisionPaths: ordered.length > 1 ? ordered.map((d) => d.path) : [],
+    };
+}
 /** 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 function pruneEmptyParents(filePath, nameSegments) {
+ *  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 function pruneEmptyParents(filePath, pathSegments) {
     let treeRoot = filePath;
-    for (let i = 0; i < nameSegments; i += 1)
+    for (let i = 0; i < pathSegments; i += 1)
         treeRoot = dirname(treeRoot);
     let dir = dirname(filePath);
     while (dir !== treeRoot && dir.startsWith(treeRoot) && existsSync(dir) && readdirSync(dir).length === 0) {
@@ -131,8 +341,10 @@ export function pruneEmptyParents(filePath, nameSegments) {
         dir = dirname(dir);
     }
 }
-/** Map a path-derived name (`topic` or `area/topic`) to its file path under a
- *  memory dir, guarding against traversal/absolute escapes. */
+/** 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 function memoryFilePath(memoryDir, name) {
     const segments = name.split('/').filter((s) => s.length > 0);
     if (segments.length === 0)
@@ -503,12 +715,56 @@ export function applyExtensionChanges(frontmatter, sets, unsets) {
 /** 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 const SELECTOR_PARAMS = {
+    'scope-read': {
+        kind: 'flag',
+        name: 'scope',
+        type: 'enum',
+        choices: [...MEMORY_READ_SCOPES],
+        required: false,
+        constraint: 'Restrict resolution to one source class. A source filter only: the name stays the full canonical name, and project scope keeps its nearest-first precedence. Conflicts with --dir, which selects one exact store instead.',
+    },
+    'scope-write': {
+        kind: 'flag',
+        name: 'scope',
+        type: 'enum',
+        choices: [...MEMORY_WRITE_SCOPES],
+        required: false,
+        constraint: 'Store to write to (builtin documents ship with the package and installed-plugin documents are managed by `crtr pkg`, so neither is writable). Default: project when cwd sits in a project, else user. `project` resolves to the NEAREST ancestor `.crouter/` walking up from cwd — in a nested workspace that can be a parent’s store, not the dir you are standing in; pass --dir to pin the exact project. `profile` requires a selected profile (CRTR_PROFILE_ID) or an explicit --profile. `node` writes the this-node store (`nodes/<CRTR_NODE_ID>/context/memory/`), the nearest scope, seen only by this running node. Conflicts with --dir.',
+    },
+    'dir': {
+        kind: 'flag',
+        name: 'dir',
+        type: 'string',
+        required: false,
+        constraint: 'Exact project directory to operate in — selects `<dir>/.crouter/memory/` by realpath, regardless of cwd, ancestor stores, or which store a target view would pick. THE way to reach one specific project store: another project in your profile’s purview, a store shadowed by an ancestor, or a non-winning duplicate such as a linked worktree that declares the same namespace as its main checkout. The name is still the FULL canonical name — the repository namespace plus that store’s path under the repository root, plus the store-local name. It selects the store itself, so it conflicts with any explicit --scope and with --profile.',
+    },
+    'profile': {
+        kind: 'flag',
+        name: 'profile',
+        type: 'string',
+        required: false,
+        constraint: 'Profile id or name to target, for --scope profile. Names that profile’s store exactly, whichever profile this process runs under. Default: the process CRTR_PROFILE_ID (the node’s selected profile). Resolved through the same profile lookup as `crtr profile show`. Rejected (usage error) unless --scope profile is also selected — never silently ignored for another scope — and rejected with --dir.',
+    },
+};
+/** One selector flag, with leaf-specific prose appended to the shared
+ *  constraint and any leaf-specific schema override applied. */
+export function selectorParam(name, overrides = {}, extraConstraint) {
+    const base = SELECTOR_PARAMS[name];
+    if (base === undefined)
+        throw new Error(`unknown selector param: ${name}`);
+    const constraint = extraConstraint === undefined ? base.constraint : `${base.constraint} ${extraConstraint}`;
+    return { ...base, ...overrides, constraint };
+}
 export const FRONTMATTER_OVERLAY_PARAMS = {
     'kind': { kind: 'flag', name: 'kind', type: 'enum', choices: [...MEMORY_KINDS], required: false, constraint: 'Document kind.' },
     'when-and-why-to-read': { kind: 'flag', name: 'when-and-why-to-read', type: 'string', required: false, constraint: 'ONE routing sentence: "When <circumstance>, this <kind> should be read because <broader downstream payoff>." WHY is the reader\u2019s payoff \u2014 the consequence they secure for their task by reading \u2014 NEVER the doc summary, its rule, or that rule reworded as an outcome (a benefit-shaped restatement still fails). Rendered verbatim as the preview.' },
     'short-form': { kind: 'flag', name: 'short-form', type: 'string', required: false, constraint: 'Frontmatter short-form \u2014 a very abbreviated version of the content, the hook shown in `crtr memory list`.' },
     'unlisted': { kind: 'flag', name: 'unlisted', type: 'bool', required: false, default: false, constraint: 'Suppress this doc from directory listings. Suppression only — explicit reads, [[links]], and surfaces entries still work.' },
-    'surface': { kind: 'flag', name: 'surface', type: 'string', required: false, repeatable: true, constraint: 'One routing entry per occurrence, as a YAML/JSON object `{on, at, match?, match-frontmatter?, gate?}`; the flag set replaces the document’s whole surfaces list. `on` is boot|workspace-open|read|memory-read|command; `at` is name|preview|content. `match` holds the event’s globs — required on read/memory-read/command (a read entry may carry `match-frontmatter`, a predicate over the read file’s own frontmatter, instead), meaningless on boot/workspace-open. Optional entry `gate` is a node-config predicate using the same vocabulary as the document gate; its event constraints and gate both match before it participates. A `./`-anchored glob is relative: for `read` to the store’s owning repo dir, for `memory-read` to the doc’s own name directory. Participating entries fold to their highest `at`; there is no cross-entry deny precedence.' },
+    'surface': { kind: 'flag', name: 'surface', type: 'string', required: false, repeatable: true, constraint: 'One routing entry per occurrence, as a YAML/JSON object `{on, at, match?, match-frontmatter?, gate?}`; the flag set replaces the document’s whole surfaces list. `on` is boot|workspace-open|read|memory-read|command; `at` is name|preview|content. `match` holds the event’s globs — required on read/memory-read/command (a read entry may carry `match-frontmatter`, a predicate over the read file’s own frontmatter, instead), meaningless on boot/workspace-open. Optional entry `gate` is a node-config predicate using the same vocabulary as the document gate; its event constraints and gate both match before it participates. A `./`-anchored glob is relative: for `read` to the store’s owning repo dir, for `memory-read` to this doc’s routing anchor — its own canonical name when the doc is its directory’s document (`<dir>/INDEX.md`), otherwise the canonical directory it sits in. Participating entries fold to their highest `at`; there is no cross-entry deny precedence.' },
     'gate': { kind: 'flag', name: 'gate', type: 'string', required: false, constraint: 'Frontmatter gate \u2014 YAML/JSON object predicate over node config using the same field/matcher vocabulary described in the guide.' },
     'slash': { kind: 'flag', name: 'slash', type: 'bool', required: false, default: false, constraint: 'Presence flags this doc invocable as a pi slash command (`/<name>`, `/` in a nested name rendered as `:`) \u2014 the doc body becomes the command\u2019s injected prompt. Default false: most docs are consulted, not invoked.' },
 };
@@ -526,7 +782,8 @@ export function overlayParam(name, overrides = {}, extraConstraint) {
  *  `--doc-rationale`, because `--rationale` there means why THIS REVISION is
  *  happening. Same field, same prose, two flag names that cannot be confused. */
 export 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 const GUIDE_SURFACES = 'Every doc appears in its directory’s listing by default (suppress with --unlisted); everything beyond the listing is explicit `surfaces` routing — 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’s project store (project stores only); `read` fires when the agent reads a matching file (globs vs the file’s absolute path and basename, `./`-anchored globs vs its path relative to the store’s owning repo dir, `match-frontmatter` predicates over the read file’s own YAML frontmatter); `memory-read` fires when another memory doc is read (globs vs that doc’s canonical name, `./` anchored to this doc’s 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 — 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 const GUIDE_SURFACES = 'Every doc appears in its directory’s listing by default (suppress with --unlisted); everything beyond the listing is explicit `surfaces` routing — 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’s project store (project stores only); `read` fires when the agent reads a matching file (globs vs the file’s absolute path and basename, `./`-anchored globs vs its path relative to the store’s owning repo dir, `match-frontmatter` predicates over the read file’s own YAML frontmatter); `memory-read` fires when another memory doc is read (globs vs that doc’s canonical name, `./` anchored to this doc’s routing anchor — its own canonical name when it is its directory’s 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 — 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 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 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 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 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 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.';