@north-light/crouter 0.3.317 → 0.3.319

package/dist/commands/memory/shared.js

@@ -1,802 +1,12 @@
-// Shared constants + helpers for the `crtr memory` command family. The leaf
-// handlers (list/read/find/write) consume the resolver, substrate schema, and
-// scope modules and build their documented output objects on top of the small
-// helpers here. Nothing in this file forks on kind or re-implements the
-// schema/gate/resolver — it only composes them.
-import { envNodeId, envProfileId } from '../../shared/env.js';
-import { existsSync, readdirSync, realpathSync, rmdirSync, statSync } from 'node:fs';
-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 { NEUTRAL_PROJECT_MEMORY, scopeMemoryDir, projectScopeRoot, ensureProjectScopeRoot, resetScopeCache, } from '../../core/scope.js';
-import { loadProfileManifest, resolveProfileOperand, 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 { SUPPRESSIBLE_RULES } from '../../core/substrate/frontmatter-validation.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 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_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;
-}
-export function registerMemoryListingExposure(identity) {
-    const nodeId = envNodeId();
-    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);
-    }
-    catch {
-        return abs;
-    }
-}
-function parseScope(scopeArg, allowed) {
-    if (scopeArg === undefined || scopeArg === '')
-        return undefined;
-    if (!allowed.includes(scopeArg)) {
-        throw usage(`invalid --scope: ${scopeArg} (expected ${allowed.join('|')})`);
-    }
-    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.',
-        });
-    }
-    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 } = resolveProfileOperand(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: input.profile,
-            next: 'Drop --profile, or pass --scope profile to target a specific profile store.',
-        });
-    }
-    if (scope === 'node') {
-        // 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 = envNodeId() || '';
-        if (nodeId === '') {
-            throw usage('node scope requires a running node (CRTR_NODE_ID unset); rerun inside a node');
-        }
-        const memoryDir = nodeMemoryDir(nodeId);
-        return { scope, memoryDir, store: nativeStoreDescriptor(scope, memoryDir) };
-    }
-    if (scope === 'profile') {
-        // A typed `--profile` gets fuzzy tolerance; the ambient `CRTR_PROFILE_ID`
-        // is a durable id this process was launched under, so it resolves strictly
-        // — a stale one must fail rather than write into a neighbouring store.
-        const typed = input.profile !== undefined && input.profile !== '';
-        const profileIdOrName = typed ? input.profile : envProfileId() || '';
-        if (profileIdOrName === '') {
-            throw usage('profile scope requires a selected profile; rerun inside a profiled node or pass --profile');
-        }
-        const { profileId } = typed ? resolveProfileOperand(profileIdOrName) : loadProfileManifest(profileIdOrName);
-        const memoryDir = profileMemoryDir(profileId);
-        return { scope, memoryDir, store: nativeStoreDescriptor(scope, memoryDir) };
-    }
-    let memoryDir = scopeMemoryDir(scope);
-    if (!memoryDir && scope === 'project') {
-        // Explicit --scope project with no project root yet → scaffold it.
-        memoryDir = join(ensureProjectScopeRoot(), 'memory');
-    }
-    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 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 < pathSegments; i += 1)
-        treeRoot = dirname(treeRoot);
-    let dir = dirname(filePath);
-    while (dir !== treeRoot && dir.startsWith(treeRoot) && existsSync(dir) && readdirSync(dir).length === 0) {
-        rmdirSync(dir);
-        dir = dirname(dir);
-    }
-}
-/** 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)
-        throw usage('memory document name required');
-    if (segments.some((s) => s === '.' || s === '..')) {
-        throw usage(`invalid memory document name: ${name}`);
-    }
-    return join(memoryDir, ...segments) + '.md';
-}
-/** Coerce a `--gate` string into a predicate tree. The gate field MUST be a
- *  YAML/JSON object (the field→matcher map the schema expects). Throws a usage
- *  error when the input fails to parse or does not parse to a non-null,
- *  non-array object — a scalar or array gate silently makes a doc never-eligible
- *  (the matcher engine ignores non-object predicates), so passing one is always
- *  a mistake and must be caught at authoring time rather than stored. */
-function parseYamlObject(raw) {
-    const parsed = yamlParse(raw);
-    if (parsed !== null && typeof parsed === 'object' && !Array.isArray(parsed)) {
-        return parsed;
-    }
-    return `expected an object, got ${JSON.stringify(parsed)}`;
-}
-export function coerceGate(raw) {
-    const result = parseYamlObject(raw);
-    if (typeof result === 'string') {
-        throw usage(`--gate must be a YAML/JSON object (field→matcher map): ${result}. ` +
-            `Example: --gate '{kind: design}' or --gate '{orchestration.depth: {gte: 2}}'`);
-    }
-    return result;
-}
-// The frontmatter keys one `surfaces` entry may carry.
-const SURFACE_ENTRY_KEYS = new Set(['on', 'match', 'match-frontmatter', 'gate', 'at']);
-/** Coerce one `--surface` value into a validated surfaces entry. Strict where
- *  the runtime parser is tolerant: a flag that would be silently dropped or
- *  trimmed at render time is an authoring mistake and fails HERE. The entry is
- *  returned in canonical key order with a single glob kept as a bare string,
- *  so the stored YAML stays as compact as the flag that authored it. */
-export function coerceSurface(raw) {
-    const parsed = yamlParse(raw);
-    if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
-        throw usage(`--surface must be a YAML/JSON object entry {on, at, match?, match-frontmatter?, gate?}, got ${JSON.stringify(parsed)}. ` +
-            `Example: --surface '{on: read, match: "src/**", at: content}'`);
-    }
-    const rec = parsed;
-    for (const key of Object.keys(rec)) {
-        if (!SURFACE_ENTRY_KEYS.has(key)) {
-            throw usage(`--surface: unknown key \`${key}\` (an entry carries only on, match, match-frontmatter, gate, at)`);
-        }
-    }
-    const on = rec['on'];
-    if (typeof on !== 'string' || !SURFACE_EVENTS.includes(on)) {
-        throw usage(`--surface: invalid \`on\`: ${JSON.stringify(on)} (expected ${SURFACE_EVENTS.join('|')})`);
-    }
-    const at = rec['at'];
-    if (typeof at !== 'string' || !SURFACE_RUNGS.includes(at)) {
-        throw usage(`--surface: invalid \`at\`: ${JSON.stringify(at)} (expected ${SURFACE_RUNGS.join('|')})`);
-    }
-    let match;
-    if (rec['match'] !== undefined) {
-        if (on === 'boot' || on === 'workspace-open') {
-            throw usage(`--surface: \`match\` is meaningless on \`${on}\` — the entry's presence is the match; drop it`);
-        }
-        if (typeof rec['match'] === 'string') {
-            const t = rec['match'].trim();
-            if (t === '')
-                throw usage('--surface: `match` must be a non-empty glob or a non-empty glob list');
-            match = t;
-        }
-        else if (Array.isArray(rec['match'])) {
-            const globs = rec['match'].map((g) => (typeof g === 'string' ? g.trim() : ''));
-            if (globs.length === 0 || globs.some((g) => g === '')) {
-                throw usage('--surface: `match` must be a non-empty glob or a non-empty glob list');
-            }
-            match = globs.length === 1 ? globs[0] : globs;
-        }
-        else {
-            throw usage(`--surface: invalid \`match\`: ${JSON.stringify(rec['match'])} (expected a glob string or list)`);
-        }
-    }
-    const matchFrontmatter = rec['match-frontmatter'];
-    if (matchFrontmatter !== undefined) {
-        if (on !== 'read')
-            throw usage('--surface: `match-frontmatter` is a `read`-event predicate only');
-        if (matchFrontmatter === null || typeof matchFrontmatter !== 'object' || Array.isArray(matchFrontmatter)) {
-            throw usage(`--surface: invalid \`match-frontmatter\`: ${JSON.stringify(matchFrontmatter)} (expected a field→matcher object)`);
-        }
-    }
-    if ((on === 'read' || on === 'memory-read' || on === 'command' || on === 'pre-command') && match === undefined && matchFrontmatter === undefined) {
-        throw usage(`--surface: a \`${on}\` entry requires \`match\`${on === 'read' ? ' or `match-frontmatter`' : ''}`);
-    }
-    const gate = rec['gate'];
-    if (gate !== undefined && (gate === null || typeof gate !== 'object' || Array.isArray(gate))) {
-        throw usage(`--surface: invalid \`gate\`: ${JSON.stringify(gate)} (expected a field→matcher object)`);
-    }
-    return {
-        on,
-        ...(match !== undefined ? { match } : {}),
-        ...(matchFrontmatter !== undefined ? { 'match-frontmatter': matchFrontmatter } : {}),
-        ...(gate !== undefined ? { gate } : {}),
-        at,
-    };
-}
-// Canonical frontmatter field order for a substrate document. Known fields come
-// first in this order; any preserved-on-update extras append after. `origin` is
-// provenance the runtime stamps at creation (never the author) — it sorts last
-// of the known fields so the authoring contract stays at the top of the block.
-const FRONTMATTER_ORDER = [
-    'kind',
-    'when-and-why-to-read',
-    'short-form',
-    'unlisted',
-    'surfaces',
-    'gate',
-    'slash',
-    'rationale',
-    'lint-ignore',
-    'last-updated',
-    'origin',
-];
-/** Provenance for a doc at the moment it is created: when, where, and which
- *  node's conversation authored it. Read from the env the runtime injects into
- *  every node's pi process (CRTR_NODE_ID/KIND/MODE/NODE_CWD); when invoked
- *  outside a node (a human at the CLI) only `created` + `cwd` are recorded.
- *  Stamped ONCE at create and preserved verbatim on every later update —
- *  `crtr memory origin <name>` derefs the `node` pointer back to the live node
- *  (its session conversation, context dir, current state). */
-export function buildOrigin() {
-    const env = process.env;
-    const origin = {
-        created: new Date().toISOString(),
-        cwd: env['CRTR_NODE_CWD'] ?? process.cwd(),
-    };
-    const nodeId = env['CRTR_NODE_ID'];
-    if (nodeId !== undefined && nodeId !== '')
-        origin['node'] = nodeId;
-    return origin;
-}
-/** Serialize a substrate frontmatter record + body into a complete `.md`
- *  document. Frontmatter is emitted as a `---` fenced YAML block (the `yaml`
- *  package — the same one the parser uses — so nested gate maps and surfaces
- *  entry lists round-trip), in canonical field order with preserved extras last. */
-export function serializeMemoryDoc(frontmatter, body) {
-    const ordered = {};
-    for (const key of FRONTMATTER_ORDER) {
-        if (frontmatter[key] !== undefined)
-            ordered[key] = frontmatter[key];
-    }
-    for (const key of Object.keys(frontmatter)) {
-        if (!(key in ordered) && frontmatter[key] !== undefined)
-            ordered[key] = frontmatter[key];
-    }
-    const yamlText = yamlStringify(ordered).replace(/\n+$/, '');
-    const cleanBody = body.replace(/^\n+/, '').replace(/\s+$/, '');
-    return `---\n${yamlText}\n---\n\n${cleanBody}\n`;
-}
-// Structure only: the closing fence tolerates trailing spaces/tabs but never
-// consumes the newlines or indentation that open the body. `parseFrontmatterGeneric`
-// closes on `\s*`, which eats them — fine for reading a doc, lossy for rewriting one.
-const LITERAL_FENCE_RE = /^---[ \t]*\r?\n[\s\S]*?\r?\n---[ \t]*(?:\r?\n|$)/;
-/** Everything after the closing frontmatter fence, byte for byte — leading blank
- *  lines and indentation intact. Source without a fence is all body. */
-export function literalBodySegment(source) {
-    const match = source.match(LITERAL_FENCE_RE);
-    return match ? source.slice(match[0].length) : source;
-}
-/** Serialize a document WITHOUT touching the body. `bodySegment` is everything
- *  after the closing frontmatter fence (leading blank line included), emitted
- *  byte for byte. This is the revision path: `edit` saves what it was given, so
- *  an unchanged doc round-trips identically and a supplied body reaches disk
- *  untransformed. Creation uses `serializeMemoryDoc`, which normalizes a first
- *  body into the canonical shape. */
-export function serializeMemoryDocLiteral(frontmatter, bodySegment) {
-    const ordered = {};
-    for (const key of FRONTMATTER_ORDER) {
-        if (frontmatter[key] !== undefined)
-            ordered[key] = frontmatter[key];
-    }
-    for (const key of Object.keys(frontmatter)) {
-        if (!(key in ordered) && frontmatter[key] !== undefined)
-            ordered[key] = frontmatter[key];
-    }
-    const yamlText = yamlStringify(ordered).replace(/\n+$/, '');
-    return `---\n${yamlText}\n---\n${bodySegment}`;
-}
-/** Resolve declarations at the same scope and path a document will use. The
- * catalog intentionally includes disabled plugins: they still authorize typed
- * edits to values that stay inert until their plugin is enabled again. */
-export function memoryExtensionCatalogForDoc(doc) {
-    return memoryExtensionValidationCatalog(doc);
-}
-function declarationValueDescription(declaration) {
-    if (declaration.type !== 'enum')
-        return declaration.type;
-    return `enum (${declaration.values.join('|')})`;
-}
-function extensionHelpValue(value) {
-    return typeof value === 'string' ? JSON.stringify(value) : String(value);
-}
-/** A bounded declaration catalog for the two authoring leaves. The manifest is
- * the source for both the type and operation-specific guidance. */
-export function memoryExtensionFieldCatalogHelp(operation) {
-    const scope = projectScopeRoot() === null ? 'user' : 'project';
-    const memoryDir = scopeMemoryDir(scope);
-    if (memoryDir === null)
-        return null;
-    const catalog = memoryExtensionCatalogForDoc({ scope, path: join(memoryDir, '.extension-help.md') });
-    const fields = Object.entries(catalog)
-        .flatMap(([namespace, declarations]) => Object.entries(declarations).map(([field, declaration]) => ({ namespace, field, declaration })))
-        .sort((left, right) => `${left.namespace}.${left.field}`.localeCompare(`${right.namespace}.${right.field}`));
-    if (fields.length === 0)
-        return null;
-    const maxRows = 50;
-    const rows = fields.slice(0, maxRows).map(({ namespace, field, declaration }) => {
-        const defaultValue = declaration.default === undefined ? '' : `; default ${extensionHelpValue(declaration.default)}`;
-        const help = operation === 'write' ? declaration.write_help : declaration.edit_help;
-        return `- \`extensions.${namespace}.${field}\` — ${declarationValueDescription(declaration)}${defaultValue}. ${help}`;
-    });
-    if (fields.length > maxRows)
-        rows.push(`- ${fields.length - maxRows} additional declared fields omitted from help.`);
-    return stateBlock('memory-extension-fields', { count: fields.length }, rows.join('\n'));
-}
-function parseExtensionPath(raw, flag) {
-    const match = /^extensions\.([^.]+)\.([^.]+)$/.exec(raw);
-    if (match === null)
-        return `${flag} requires the full path extensions.<plugin>.<field>: ${raw}`;
-    return { path: raw, namespace: match[1], field: match[2] };
-}
-function parseExtensionValue(path, raw, declaration) {
-    if (declaration.type === 'boolean') {
-        if (raw === 'true')
-            return true;
-        if (raw === 'false')
-            return false;
-        return `${path} expects boolean true or false, received ${JSON.stringify(raw)}`;
-    }
-    if (declaration.type === 'number') {
-        if (!/^[+-]?(?:\d+(?:\.\d*)?|\.\d+)(?:[eE][+-]?\d+)?$/.test(raw)) {
-            return `${path} expects finite numeric syntax, received ${JSON.stringify(raw)}`;
-        }
-        const value = Number(raw);
-        return Number.isFinite(value) ? value : `${path} expects a finite number, received ${JSON.stringify(raw)}`;
-    }
-    if (declaration.type === 'enum' && !declaration.values.includes(raw)) {
-        return `${path} expects one of ${declaration.values.join('|')}, received ${JSON.stringify(raw)}`;
-    }
-    return raw;
-}
-/** Parse every requested extension mutation before the caller constructs any
- * frontmatter. Set values are deliberately declaration-typed rather than YAML. */
-export function parseRequestedExtensionChanges(setRaw, unsetRaw, catalog) {
-    const errors = [];
-    const sets = [];
-    const unsets = [];
-    const setPaths = new Set();
-    const unsetPaths = new Set();
-    for (const raw of setRaw ?? []) {
-        const delimiter = raw.indexOf('=');
-        if (delimiter < 0) {
-            errors.push(`--extension requires extensions.<plugin>.<field>=VALUE: ${raw}`);
-            continue;
-        }
-        const parsedPath = parseExtensionPath(raw.slice(0, delimiter), '--extension');
-        if (typeof parsedPath === 'string') {
-            errors.push(parsedPath);
-            continue;
-        }
-        if (setPaths.has(parsedPath.path)) {
-            errors.push(`duplicate --extension path: ${parsedPath.path}`);
-            continue;
-        }
-        setPaths.add(parsedPath.path);
-        const declaration = catalog[parsedPath.namespace]?.[parsedPath.field];
-        if (declaration === undefined) {
-            errors.push(`${parsedPath.path} is not declared by an installed plugin`);
-            continue;
-        }
-        const value = parseExtensionValue(parsedPath.path, raw.slice(delimiter + 1), declaration);
-        if (typeof value === 'string' && declaration.type !== 'string' && declaration.type !== 'enum') {
-            errors.push(value);
-            continue;
-        }
-        if (typeof value === 'string' && declaration.type === 'enum' && !declaration.values.includes(value)) {
-            errors.push(`${parsedPath.path} expects one of ${declaration.values.join('|')}, received ${JSON.stringify(value)}`);
-            continue;
-        }
-        sets.push({ ...parsedPath, value });
-    }
-    for (const raw of unsetRaw ?? []) {
-        const parsedPath = parseExtensionPath(raw, '--unset-extension');
-        if (typeof parsedPath === 'string') {
-            errors.push(parsedPath);
-            continue;
-        }
-        if (unsetPaths.has(parsedPath.path)) {
-            errors.push(`duplicate --unset-extension path: ${parsedPath.path}`);
-            continue;
-        }
-        unsetPaths.add(parsedPath.path);
-        if (catalog[parsedPath.namespace]?.[parsedPath.field] === undefined) {
-            errors.push(`${parsedPath.path} is not declared by an installed plugin`);
-            continue;
-        }
-        unsets.push(parsedPath);
-    }
-    for (const path of setPaths) {
-        if (unsetPaths.has(path))
-            errors.push(`${path} was requested in both --extension and --unset-extension`);
-    }
-    if (errors.length > 0) {
-        throw usage(`invalid plugin memory extension request:\n- ${errors.join('\n- ')}`, {
-            received: [...(setRaw ?? []), ...(unsetRaw ?? [])].join(', '),
-            next: 'Run `crtr memory write -h` or `crtr memory edit -h` for the installed field catalog and value syntax.',
-        });
-    }
-    return { sets, unsets };
-}
-/** Apply only requested extension paths. Existing unknown namespaces remain
- * untouched; an unset prunes the empty namespace and empty root mapping. */
-export function applyExtensionChanges(frontmatter, sets, unsets) {
-    if (sets.length === 0 && unsets.length === 0)
-        return;
-    const current = frontmatter['extensions'];
-    if (current !== undefined && (current === null || typeof current !== 'object' || Array.isArray(current))) {
-        throw usage('existing extensions frontmatter must be a mapping before extension fields can be changed', {
-            received: JSON.stringify(current),
-            next: 'Repair the extensions mapping, or make a core-field-only edit that preserves it unchanged.',
-        });
-    }
-    const extensions = { ...(current ?? {}) };
-    for (const set of sets) {
-        const existing = extensions[set.namespace];
-        if (existing !== undefined && (existing === null || typeof existing !== 'object' || Array.isArray(existing))) {
-            throw usage(`existing ${`extensions.${set.namespace}`} frontmatter must be a mapping before ${set.path} can change`, {
-                received: JSON.stringify(existing),
-                next: 'Repair the namespace mapping, or make a core-field-only edit that preserves it unchanged.',
-            });
-        }
-        extensions[set.namespace] = { ...(existing ?? {}), [set.field]: set.value };
-    }
-    for (const unset of unsets) {
-        const existing = extensions[unset.namespace];
-        if (existing === undefined)
-            continue;
-        if (existing === null || typeof existing !== 'object' || Array.isArray(existing)) {
-            throw usage(`existing ${`extensions.${unset.namespace}`} frontmatter must be a mapping before ${unset.path} can change`, {
-                received: JSON.stringify(existing),
-                next: 'Repair the namespace mapping, or make a core-field-only edit that preserves it unchanged.',
-            });
-        }
-        const fields = { ...existing };
-        delete fields[unset.field];
-        if (Object.keys(fields).length === 0)
-            delete extensions[unset.namespace];
-        else
-            extensions[unset.namespace] = fields;
-    }
-    if (Object.keys(extensions).length === 0)
-        delete frontmatter['extensions'];
-    else
-        frontmatter['extensions'] = extensions;
-}
-// Help material shared by `write` and `edit`
-//
-// Single-sourced: both leaves compose these, so a wording fix lands on both.
-// Anything exclusive to one leaf (creation rules on `write`, the rationale
-// contract on `edit`) stays owned by that leaf.
-/** 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 (package-shipped documents and installed-plugin documents are managed outside this command, 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 function coerceLintIgnore(raw) {
-    if (raw === undefined)
-        return undefined;
-    const rules = Array.isArray(raw) ? raw : [raw];
-    if (rules.length === 0 || rules.some((rule) => typeof rule !== 'string' || !SUPPRESSIBLE_RULES.includes(rule))) {
-        throw usage(`invalid lint-ignore: ${JSON.stringify(raw)} (suppressible rules: ${SUPPRESSIBLE_RULES.map((rule) => `\`${rule}\``).join(', ')})`);
-    }
-    return rules.length === 1 ? rules[0] : rules;
-}
-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|pre-command; `at` is name|preview|content. `match` holds the event’s globs — required on read/memory-read/command/pre-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.' },
-    'lint-ignore': { kind: 'flag', name: 'lint-ignore', type: 'enum', choices: [...SUPPRESSIBLE_RULES], required: false, repeatable: true, constraint: 'Suppress one authoring lint rule for this document. Repeat for a list; valid rules: length, broad-memory-read, orphan.' },
-    '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.' },
-};
-/** One overlay flag, with leaf-specific prose appended to the shared
- *  constraint and any leaf-specific schema override applied. */
-export function overlayParam(name, overrides = {}, extraConstraint) {
-    const base = FRONTMATTER_OVERLAY_PARAMS[name];
-    if (base === undefined)
-        throw new Error(`unknown frontmatter overlay param: ${name}`);
-    const constraint = extraConstraint === undefined ? base.constraint : `${base.constraint} ${extraConstraint}`;
-    return { ...base, ...overrides, constraint };
-}
-/** The doc's standing `rationale` frontmatter field \u2014 the observed gap the doc
- *  exists to close. `write` takes it as `--rationale`; `edit` takes it as
- *  `--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’s full body is delivered, including an explicit 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 each shell segment of the command line — split on `&&`/`||`/`;`/`|`/newlines outside quotes, leading `VAR=value` assignments dropped — where `*` spans whole whitespace-separated tokens and never part of one, `?` is one character inside a token, and quoted argument text is opaque, so `*git commit*` fires for `cd x && git commit -m "…"` but not for `git commit-tree` or an `echo` that merely mentions it); `pre-command` fires BEFORE a matching bash command runs (same matching): when the memory has not been read yet, the command does not execute — the memory comes back as the tool result instead, and the agent re-issues the command, which then runs. Use it to guarantee a memory is seen before a sensitive action is taken. Requires `match`. 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, 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.';
+var U=Object.defineProperty;var a=(e,n)=>U(e,"name",{value:n,configurable:!0});import{envNodeId as R,envProfileId as Y}from"../../shared/env.js";import{existsSync as E,readdirSync as W,realpathSync as V,rmdirSync as B,statSync as G}from"node:fs";import{dirname as g,join as y,resolve as H}from"node:path";import{stringify as S,parse as k}from"yaml";import{stateBlock as X}from"../../core/help.js";import{loadStoreMemoryDocs as z,openProjectMemoryStore as x}from"../../core/memory-resolver.js";import{canonicalSegments as K,physicalRelativePathFor as j,stripNamespace as Q,validateExplicitLocalName as Z}from"../../core/memory/identity.js";import{pathExists as O,realpathOrSelf as b}from"../../core/fs-utils.js";import{usage as s}from"../../core/errors.js";import{memoryExtensionValidationCatalog as ee}from"../../core/memory/extensions.js";import{CRTR_DIR_NAME as te}from"../../types.js";import{NEUTRAL_PROJECT_MEMORY as ne,scopeMemoryDir as N,projectScopeRoot as A,ensureProjectScopeRoot as oe,resetScopeCache as re}from"../../core/scope.js";import{loadProfileManifest as ie,resolveProfileOperand as D,profileMemoryDir as _}from"../../core/profiles/manifest.js";import{memoryDir as se}from"../../core/runtime/memory.js";import{SURFACE_EVENTS as I,SURFACE_RUNGS as C}from"../../core/substrate/schema.js";import{SUPPRESSIBLE_RULES as v}from"../../core/substrate/frontmatter-validation.js";import{exposureTarget as ae,loadContextExposureState as ce,registerExposure as de,saveContextExposureState as le}from"../../core/substrate/injected-store.js";const me=["knowledge","preference"],q=["user","project","profile","node","builtin"],$=["user","project","profile","node"],Ue=$;function Ye(e){return e==="node"?-1:e==="project"?0:e==="profile"?1:e==="user"?2:3}a(Ye,"scopeRank");function We(e){const n=R();if(n===void 0||n==="")return;const t=ce(n);de(ae(t,"transcript"),e,"content"),le(n,t)}a(We,"registerMemoryListingExposure");function T(e){if(e.scope!==void 0&&e.scope!=="")throw s(`--dir selects the project store itself and cannot combine with --scope ${e.scope}`,{received:`--dir ${e.dir} --scope ${e.scope}`,next:"Drop --scope: --dir already pins the exact project store."});if(e.profile!==void 0&&e.profile!=="")throw s("--profile only applies to --scope profile; --dir selects a project store",{received:e.profile,next:"Drop --profile when using --dir."})}a(T,"rejectDirConflicts");function P(e){const n=H(e);if(!E(n)||!G(n).isDirectory())throw s(`--dir does not exist or is not a directory: ${e}`,{received:e,next:"Pass an existing project directory."});try{return V(n)}catch{return n}}a(P,"ownerDirFromArg");function M(e,n){if(!(e===void 0||e==="")){if(!n.includes(e))throw s(`invalid --scope: ${e} (expected ${n.join("|")})`);return e}}a(M,"parseScope");function w(e,n){return{scope:e,storeRoot:n,namespace:"",mountStatus:O(n)?"ready":"absent",projectMemory:ne}}a(w,"nativeStoreDescriptor");function Ve(e){if(e.dir!==void 0&&e.dir!=="")return T(e),{store:x(P(e.dir))};if(e.profile!==void 0&&e.profile!==""&&e.scope!=="profile")throw s(`--profile only applies to --scope profile (received scope: ${e.scope??"none"})`,{received:e.profile,next:"Drop --profile, or pass --scope profile to target a specific profile store."});const n=M(e.scope,q);if(e.profile!==void 0&&e.profile!==""){const{profileId:t}=D(e.profile);return{scope:"profile",store:w("profile",_(t))}}return{...n===void 0?{}:{scope:n},store:null}}a(Ve,"resolveReadSelector");function pe(e){if(e.dir!==void 0&&e.dir!==""){T(e);const r=P(e.dir);return re(),{scope:"project",memoryDir:y(r,te,"memory"),store:x(r)}}const t=M(e.scope,$)??(A()!==null?"project":"user");if(e.profile!==void 0&&e.profile!==""&&t!=="profile")throw s(`--profile only applies to --scope profile (resolved scope: ${t})`,{received:e.profile,next:"Drop --profile, or pass --scope profile to target a specific profile store."});if(t==="node"){const r=R()||"";if(r==="")throw s("node scope requires a running node (CRTR_NODE_ID unset); rerun inside a node");const i=se(r);return{scope:t,memoryDir:i,store:w(t,i)}}if(t==="profile"){const r=e.profile!==void 0&&e.profile!=="",i=r?e.profile:Y()||"";if(i==="")throw s("profile scope requires a selected profile; rerun inside a profiled node or pass --profile");const{profileId:c}=r?D(i):ie(i),l=_(c);return{scope:t,memoryDir:l,store:w(t,l)}}let o=N(t);if(!o&&t==="project"&&(o=y(oe(),"memory")),!o)throw s(`no ${t} scope available for writing memory documents`);return t==="project"?{scope:t,memoryDir:o,store:x(g(g(o)))}:{scope:t,memoryDir:o,store:w(t,o)}}a(pe,"resolveWriteSelector");function Be(e,n,t){const{scope:o,memoryDir:r}=pe({scope:e,profile:n,dir:t});return{scope:o,memoryDir:r}}a(Be,"resolveWriteTarget");function fe(e){if(e.scope!=="project"||e.mountStatus==="ready")return e;const n=e.ownerDir??e.storeRoot;if(e.mountStatus==="absent")throw s(`no memory store at ${e.storeRoot}`,{next:`Initialize it with \`crtr memory write <namespace> --dir ${n}\`, which declares the repository namespace.`});const t=e.repositoryRoot??n;throw s(e.diagnostic??`project memory store at ${e.storeRoot} does not declare a namespace`,{next:`Run \`crtr sys migrate --dir ${t}\`.`})}a(fe,"requireMountedStore");function L(e){const n=K(e.trim()).join("/");if(n==="")throw s("memory document name required");const t=Z(n);if(!t.ok)throw s(`invalid memory document name \`${e}\`: ${t.reason}`,{received:e,next:"Pass the full canonical name (a project document is <namespace>/<local name>); run `crtr memory find <leaf>` to look one up."});return n}a(L,"requireCanonicalName");function he(e,n){fe(e);const t=L(n);if(e.namespace==="")return t;const o=Q(t,e.namespace);if(o===null)throw s(`\`${t}\` is not in the namespace of the store at ${e.storeRoot} (\`${e.namespace}\`)`,{memory:t,next:`Every document there answers at \`${e.namespace}/<local name>\`; the store's own document answers at \`${e.namespace}\`.`});return o}a(he,"requireLocalNameInStore");function Ge(e,n,t,o){const r=he(e,n),i=L(n),c=t??z(e,!0),l=o===void 0?null:b(o.path),d=c.find(u=>u.name===i&&b(u.path)!==l);if(d!==void 0)throw s(`${i} already exists in ${e.storeRoot}`,{memory:i,path:d.path,next:`Revise it with \`crtr memory edit ${i}\`, which records the change, or move it with \`crtr memory move\`.`});const p=(r===""?["directory-index"]:["directory-index","leaf-file"]).map(u=>y(e.storeRoot,j(r,u))).filter(u=>O(u)&&b(u)!==l);if(p.length>0)throw s(`${i} cannot be created: ${p.join(" and ")} already exists`,{memory:i,path:p.join(", "),next:"Both `<name>.md` and `<name>/INDEX.md` carry that identity. Read the existing file, then edit, move, or delete it."});const f=r===""||c.some(u=>u.localName.startsWith(`${r}/`))?"directory-index":"leaf-file",h=j(r,f);return{store:e,canonicalName:i,localName:r,representation:f,physicalRelativePath:h,path:y(e.storeRoot,h)}}a(Ge,"planNewDocumentPlacement");function He(e){const n=e.winner,t=e.candidates.filter(o=>o.store.storeRoot===n.store.storeRoot);if(t.length>1)throw s(`${e.name} is owned by ${t.length} files in one store: ${t.map(o=>o.path).join(" and ")}`,{memory:e.name,path:t.map(o=>o.path).join(", "),next:`Recover the collision with \`crtr memory move ${e.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 n}a(He,"requireUnambiguousDoc");function Xe(e){const t=[...e.candidates.filter(o=>o.store.storeRoot===e.winner.store.storeRoot)].sort((o,r)=>{const i=o.physicalRelativePath.localeCompare(r.physicalRelativePath);return i!==0?i:o.path.localeCompare(r.path)});return{doc:t[0]??e.winner,collisionPaths:t.length>1?t.map(o=>o.path):[]}}a(Xe,"selectMutationDoc");function ze(e,n){let t=e;for(let r=0;r<n;r+=1)t=g(t);let o=g(e);for(;o!==t&&o.startsWith(t)&&E(o)&&W(o).length===0;)B(o),o=g(o)}a(ze,"pruneEmptyParents");function Ke(e,n){const t=n.split("/").filter(o=>o.length>0);if(t.length===0)throw s("memory document name required");if(t.some(o=>o==="."||o===".."))throw s(`invalid memory document name: ${n}`);return y(e,...t)+".md"}a(Ke,"memoryFilePath");function ue(e){const n=k(e);return n!==null&&typeof n=="object"&&!Array.isArray(n)?n:`expected an object, got ${JSON.stringify(n)}`}a(ue,"parseYamlObject");function Qe(e){const n=ue(e);if(typeof n=="string")throw s(`--gate must be a YAML/JSON object (field\u2192matcher map): ${n}. Example: --gate '{kind: design}' or --gate '{orchestration.depth: {gte: 2}}'`);return n}a(Qe,"coerceGate");const ye=new Set(["on","match","match-frontmatter","gate","at"]);function Ze(e){const n=k(e);if(n===null||typeof n!="object"||Array.isArray(n))throw s(`--surface must be a YAML/JSON object entry {on, at, match?, match-frontmatter?, gate?}, got ${JSON.stringify(n)}. Example: --surface '{on: read, match: "src/**", at: content}'`);const t=n;for(const d of Object.keys(t))if(!ye.has(d))throw s(`--surface: unknown key \`${d}\` (an entry carries only on, match, match-frontmatter, gate, at)`);const o=t.on;if(typeof o!="string"||!I.includes(o))throw s(`--surface: invalid \`on\`: ${JSON.stringify(o)} (expected ${I.join("|")})`);const r=t.at;if(typeof r!="string"||!C.includes(r))throw s(`--surface: invalid \`at\`: ${JSON.stringify(r)} (expected ${C.join("|")})`);let i;if(t.match!==void 0){if(o==="boot"||o==="workspace-open")throw s(`--surface: \`match\` is meaningless on \`${o}\` \u2014 the entry's presence is the match; drop it`);if(typeof t.match=="string"){const d=t.match.trim();if(d==="")throw s("--surface: `match` must be a non-empty glob or a non-empty glob list");i=d}else if(Array.isArray(t.match)){const d=t.match.map(m=>typeof m=="string"?m.trim():"");if(d.length===0||d.some(m=>m===""))throw s("--surface: `match` must be a non-empty glob or a non-empty glob list");i=d.length===1?d[0]:d}else throw s(`--surface: invalid \`match\`: ${JSON.stringify(t.match)} (expected a glob string or list)`)}const c=t["match-frontmatter"];if(c!==void 0){if(o!=="read")throw s("--surface: `match-frontmatter` is a `read`-event predicate only");if(c===null||typeof c!="object"||Array.isArray(c))throw s(`--surface: invalid \`match-frontmatter\`: ${JSON.stringify(c)} (expected a field\u2192matcher object)`)}if((o==="read"||o==="memory-read"||o==="command"||o==="pre-command")&&i===void 0&&c===void 0)throw s(`--surface: a \`${o}\` entry requires \`match\`${o==="read"?" or `match-frontmatter`":""}`);const l=t.gate;if(l!==void 0&&(l===null||typeof l!="object"||Array.isArray(l)))throw s(`--surface: invalid \`gate\`: ${JSON.stringify(l)} (expected a field\u2192matcher object)`);return{on:o,...i!==void 0?{match:i}:{},...c!==void 0?{"match-frontmatter":c}:{},...l!==void 0?{gate:l}:{},at:r}}a(Ze,"coerceSurface");const J=["kind","when-and-why-to-read","short-form","unlisted","surfaces","gate","slash","rationale","lint-ignore","last-updated","origin"];function et(){const e=process.env,n={created:new Date().toISOString(),cwd:e.CRTR_NODE_CWD??process.cwd()},t=e.CRTR_NODE_ID;return t!==void 0&&t!==""&&(n.node=t),n}a(et,"buildOrigin");function tt(e,n){const t={};for(const i of J)e[i]!==void 0&&(t[i]=e[i]);for(const i of Object.keys(e))!(i in t)&&e[i]!==void 0&&(t[i]=e[i]);const o=S(t).replace(/\n+$/,""),r=n.replace(/^\n+/,"").replace(/\s+$/,"");return`---
+${o}
+---
+
+${r}
+`}a(tt,"serializeMemoryDoc");const ge=/^---[ \t]*\r?\n[\s\S]*?\r?\n---[ \t]*(?:\r?\n|$)/;function nt(e){const n=e.match(ge);return n?e.slice(n[0].length):e}a(nt,"literalBodySegment");function ot(e,n){const t={};for(const r of J)e[r]!==void 0&&(t[r]=e[r]);for(const r of Object.keys(e))!(r in t)&&e[r]!==void 0&&(t[r]=e[r]);return`---
+${S(t).replace(/\n+$/,"")}
+---
+${n}`}a(ot,"serializeMemoryDocLiteral");function we(e){return ee(e)}a(we,"memoryExtensionCatalogForDoc");function xe(e){return e.type!=="enum"?e.type:`enum (${e.values.join("|")})`}a(xe,"declarationValueDescription");function be(e){return typeof e=="string"?JSON.stringify(e):String(e)}a(be,"extensionHelpValue");function rt(e){const n=A()===null?"user":"project",t=N(n);if(t===null)return null;const o=we({scope:n,path:y(t,".extension-help.md")}),r=Object.entries(o).flatMap(([l,d])=>Object.entries(d).map(([m,p])=>({namespace:l,field:m,declaration:p}))).sort((l,d)=>`${l.namespace}.${l.field}`.localeCompare(`${d.namespace}.${d.field}`));if(r.length===0)return null;const i=50,c=r.slice(0,i).map(({namespace:l,field:d,declaration:m})=>{const p=m.default===void 0?"":`; default ${be(m.default)}`,f=e==="write"?m.write_help:m.edit_help;return`- \`extensions.${l}.${d}\` \u2014 ${xe(m)}${p}. ${f}`});return r.length>i&&c.push(`- ${r.length-i} additional declared fields omitted from help.`),X("memory-extension-fields",{count:r.length},c.join(`
+`))}a(rt,"memoryExtensionFieldCatalogHelp");function F(e,n){const t=/^extensions\.([^.]+)\.([^.]+)$/.exec(e);return t===null?`${n} requires the full path extensions.<plugin>.<field>: ${e}`:{path:e,namespace:t[1],field:t[2]}}a(F,"parseExtensionPath");function ve(e,n,t){if(t.type==="boolean")return n==="true"?!0:n==="false"?!1:`${e} expects boolean true or false, received ${JSON.stringify(n)}`;if(t.type==="number"){if(!/^[+-]?(?:\d+(?:\.\d*)?|\.\d+)(?:[eE][+-]?\d+)?$/.test(n))return`${e} expects finite numeric syntax, received ${JSON.stringify(n)}`;const o=Number(n);return Number.isFinite(o)?o:`${e} expects a finite number, received ${JSON.stringify(n)}`}return t.type==="enum"&&!t.values.includes(n)?`${e} expects one of ${t.values.join("|")}, received ${JSON.stringify(n)}`:n}a(ve,"parseExtensionValue");function it(e,n,t){const o=[],r=[],i=[],c=new Set,l=new Set;for(const d of e??[]){const m=d.indexOf("=");if(m<0){o.push(`--extension requires extensions.<plugin>.<field>=VALUE: ${d}`);continue}const p=F(d.slice(0,m),"--extension");if(typeof p=="string"){o.push(p);continue}if(c.has(p.path)){o.push(`duplicate --extension path: ${p.path}`);continue}c.add(p.path);const f=t[p.namespace]?.[p.field];if(f===void 0){o.push(`${p.path} is not declared by an installed plugin`);continue}const h=ve(p.path,d.slice(m+1),f);if(typeof h=="string"&&f.type!=="string"&&f.type!=="enum"){o.push(h);continue}if(typeof h=="string"&&f.type==="enum"&&!f.values.includes(h)){o.push(`${p.path} expects one of ${f.values.join("|")}, received ${JSON.stringify(h)}`);continue}r.push({...p,value:h})}for(const d of n??[]){const m=F(d,"--unset-extension");if(typeof m=="string"){o.push(m);continue}if(l.has(m.path)){o.push(`duplicate --unset-extension path: ${m.path}`);continue}if(l.add(m.path),t[m.namespace]?.[m.field]===void 0){o.push(`${m.path} is not declared by an installed plugin`);continue}i.push(m)}for(const d of c)l.has(d)&&o.push(`${d} was requested in both --extension and --unset-extension`);if(o.length>0)throw s(`invalid plugin memory extension request:
+- ${o.join(`
+- `)}`,{received:[...e??[],...n??[]].join(", "),next:"Run `crtr memory write -h` or `crtr memory edit -h` for the installed field catalog and value syntax."});return{sets:r,unsets:i}}a(it,"parseRequestedExtensionChanges");function st(e,n,t){if(n.length===0&&t.length===0)return;const o=e.extensions;if(o!==void 0&&(o===null||typeof o!="object"||Array.isArray(o)))throw s("existing extensions frontmatter must be a mapping before extension fields can be changed",{received:JSON.stringify(o),next:"Repair the extensions mapping, or make a core-field-only edit that preserves it unchanged."});const r={...o??{}};for(const i of n){const c=r[i.namespace];if(c!==void 0&&(c===null||typeof c!="object"||Array.isArray(c)))throw s(`existing ${`extensions.${i.namespace}`} frontmatter must be a mapping before ${i.path} can change`,{received:JSON.stringify(c),next:"Repair the namespace mapping, or make a core-field-only edit that preserves it unchanged."});r[i.namespace]={...c??{},[i.field]:i.value}}for(const i of t){const c=r[i.namespace];if(c===void 0)continue;if(c===null||typeof c!="object"||Array.isArray(c))throw s(`existing ${`extensions.${i.namespace}`} frontmatter must be a mapping before ${i.path} can change`,{received:JSON.stringify(c),next:"Repair the namespace mapping, or make a core-field-only edit that preserves it unchanged."});const l={...c};delete l[i.field],Object.keys(l).length===0?delete r[i.namespace]:r[i.namespace]=l}Object.keys(r).length===0?delete e.extensions:e.extensions=r}a(st,"applyExtensionChanges");const $e={"scope-read":{kind:"flag",name:"scope",type:"enum",choices:[...q],required:!1,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:[...$],required:!1,constraint:"Store to write to (package-shipped documents and installed-plugin documents are managed outside this command, 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 \u2014 in a nested workspace that can be a parent\u2019s 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:!1,constraint:"Exact project directory to operate in \u2014 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\u2019s 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 \u2014 the repository namespace plus that store\u2019s 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:!1,constraint:"Profile id or name to target, for --scope profile. Names that profile\u2019s store exactly, whichever profile this process runs under. Default: the process CRTR_PROFILE_ID (the node\u2019s selected profile). Resolved through the same profile lookup as `crtr profile show`. Rejected (usage error) unless --scope profile is also selected \u2014 never silently ignored for another scope \u2014 and rejected with --dir."}};function at(e,n={},t){const o=$e[e];if(o===void 0)throw new Error(`unknown selector param: ${e}`);const r=t===void 0?o.constraint:`${o.constraint} ${t}`;return{...o,...n,constraint:r}}a(at,"selectorParam");function ct(e){if(e===void 0)return;const n=Array.isArray(e)?e:[e];if(n.length===0||n.some(t=>typeof t!="string"||!v.includes(t)))throw s(`invalid lint-ignore: ${JSON.stringify(e)} (suppressible rules: ${v.map(t=>`\`${t}\``).join(", ")})`);return n.length===1?n[0]:n}a(ct,"coerceLintIgnore");const Re={kind:{kind:"flag",name:"kind",type:"enum",choices:[...me],required:!1,constraint:"Document kind."},"when-and-why-to-read":{kind:"flag",name:"when-and-why-to-read",type:"string",required:!1,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:!1,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:!1,default:!1,constraint:"Suppress this doc from directory listings. Suppression only \u2014 explicit reads, [[links]], and surfaces entries still work."},surface:{kind:"flag",name:"surface",type:"string",required:!1,repeatable:!0,constraint:"One routing entry per occurrence, as a YAML/JSON object `{on, at, match?, match-frontmatter?, gate?}`; the flag set replaces the document\u2019s whole surfaces list. `on` is boot|workspace-open|read|memory-read|command|pre-command; `at` is name|preview|content. `match` holds the event\u2019s globs \u2014 required on read/memory-read/command/pre-command (a read entry may carry `match-frontmatter`, a predicate over the read file\u2019s 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\u2019s owning repo dir, for `memory-read` to this doc\u2019s routing anchor \u2014 its own canonical name when the doc is its directory\u2019s 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:!1,constraint:"Frontmatter gate \u2014 YAML/JSON object predicate over node config using the same field/matcher vocabulary described in the guide."},"lint-ignore":{kind:"flag",name:"lint-ignore",type:"enum",choices:[...v],required:!1,repeatable:!0,constraint:"Suppress one authoring lint rule for this document. Repeat for a list; valid rules: length, broad-memory-read, orphan."},slash:{kind:"flag",name:"slash",type:"bool",required:!1,default:!1,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."}};function dt(e,n={},t){const o=Re[e];if(o===void 0)throw new Error(`unknown frontmatter overlay param: ${e}`);const r=t===void 0?o.constraint:`${o.constraint} ${t}`;return{...o,...n,constraint:r}}a(dt,"overlayParam");const lt="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.",mt='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\u2019s full body is delivered, including an explicit 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 each shell segment of the command line \u2014 split on `&&`/`||`/`;`/`|`/newlines outside quotes, leading `VAR=value` assignments dropped \u2014 where `*` spans whole whitespace-separated tokens and never part of one, `?` is one character inside a token, and quoted argument text is opaque, so `*git commit*` fires for `cd x && git commit -m "\u2026"` but not for `git commit-tree` or an `echo` that merely mentions it); `pre-command` fires BEFORE a matching bash command runs (same matching): when the memory has not been read yet, the command does not execute \u2014 the memory comes back as the tool result instead, and the agent re-issues the command, which then runs. Use it to guarantee a memory is seen before a sensitive action is taken. Requires `match`. 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.',pt='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.',ft="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.",ht="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.",ut="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{lt as DOC_RATIONALE_CONSTRAINT,Re as FRONTMATTER_OVERLAY_PARAMS,ut as GUIDE_CANONICAL_NAMES,ht as GUIDE_DOC_LINKS,ft as GUIDE_PREDICATE_VOCABULARY,pt as GUIDE_ROUTING_LINE,mt as GUIDE_SURFACES,me as MEMORY_KINDS,q as MEMORY_READ_SCOPES,Ue as MEMORY_SCOPES,$ as MEMORY_WRITE_SCOPES,$e as SELECTOR_PARAMS,st as applyExtensionChanges,et as buildOrigin,Qe as coerceGate,ct as coerceLintIgnore,Ze as coerceSurface,nt as literalBodySegment,we as memoryExtensionCatalogForDoc,rt as memoryExtensionFieldCatalogHelp,Ke as memoryFilePath,dt as overlayParam,it as parseRequestedExtensionChanges,Ge as planNewDocumentPlacement,ze as pruneEmptyParents,We as registerMemoryListingExposure,L as requireCanonicalName,he as requireLocalNameInStore,fe as requireMountedStore,He as requireUnambiguousDoc,Ve as resolveReadSelector,pe as resolveWriteSelector,Be as resolveWriteTarget,Ye as scopeRank,Xe as selectMutationDoc,at as selectorParam,tt as serializeMemoryDoc,ot as serializeMemoryDocLiteral};