@north-light/crouter 0.3.227 → 0.3.228

package/dist/core/memory/lint.js

@@ -0,0 +1,517 @@
+// lint.ts — the ONE memory validation engine. It checks a PHYSICAL store (every
+// markdown file it holds, whether or not the runtime will mount it) or a whole
+// TARGET VIEW (every store a cwd/profile/node sees, plus the cross-store
+// diagnostics only a view can produce), and returns structured findings. The
+// `memory lint` leaf, migration verification, the plugin candidate gate, and
+// the build's builtin-corpus gate all consume this module rather than
+// reimplementing a rule: a rule asserted in one caller holds only there.
+//
+// Severity is the contract: `error` fails an authoring/mount gate, `warning` is
+// a non-fatal authoring smell, `notice` is inspection data (duplicate stores are
+// legitimate, so equal-canonical candidates across stores are reported, never
+// failed).
+import { basename, join, matchesGlob, relative, sep } from 'node:path';
+import { pathExists, readText, realpathOrSelf, walkFiles } from '../fs-utils.js';
+import { parseFrontmatterGeneric } from '../frontmatter.js';
+import { descendantStoreRoots } from '../nested-stores.js';
+import { projectScopeRoots } from '../scope.js';
+import { associateRepository } from './repository-association.js';
+import { loadProfileManifest } from '../profiles/manifest.js';
+import { loadMemoryTargetView, loadStoreMemoryDocs, openProjectMemoryStore, } from '../memory-resolver.js';
+import { buildMemoryTree } from './tree.js';
+import { canonicalSegments, collapseTrailingIndex, INDEX_SEGMENT, localNameFromPath, normalizeDocName, validateExplicitLocalName, } from './identity.js';
+import { lintSubstrateFrontmatter, parsedSubstrateSurfaces } from '../substrate/frontmatter-validation.js';
+import { memoryExtensionValidationCatalog, validateMemoryExtensionValues } from './extensions.js';
+import { docLinkNames } from './doc-link-grammar.js';
+/** The rules that decide whether a corpus is COMPATIBLE with exact canonical
+ *  identity — what a plugin candidate gate, the builtin build gate, and
+ *  migration verification refuse a corpus on, independent of authoring-quality
+ *  rules such as length or routing lines. */
+export const MEMORY_LINT_IDENTITY_RULES = new Set([
+    'store-namespace',
+    'namespace-placement',
+    'owner-path-collision',
+    'root-name',
+    'root-index-unaddressable',
+    'local-name',
+    'canonical-collision',
+    'dangling-link',
+    'memory-read-route',
+]);
+function makeResult(findings, checked, documents, storesLinted) {
+    const errors = findings.filter((f) => f.severity === 'error');
+    return {
+        ok: errors.length === 0,
+        checked,
+        documents,
+        storesLinted,
+        findings,
+        errors,
+        warnings: findings.filter((f) => f.severity === 'warning'),
+        notices: findings.filter((f) => f.severity === 'notice'),
+    };
+}
+// ---------------------------------------------------------------------------
+// Body-length caps, measured in WORDS (frontmatter excluded). Words, not lines:
+// house style writes each paragraph as ONE logical line and lets the editor
+// soft-wrap, so a line count measures wrapping style rather than context cost.
+//
+// A `boot` entry at `content` inlines the whole body into every agent's system
+// prompt; a `content` entry on any other event surfaces the whole body whenever
+// the entry fires — both cap at 1000 words. A `boot` entry at `preview` routes a
+// deliberate reader into the whole body, so its cap is the longest doc worth
+// reading end to end. `name` entries and surface-less docs never cap: such a doc
+// is only reached deliberately, so its length is the reader's choice. The
+// strictest applicable cap wins.
+//
+// Persona layers — canonical names under `kinds/`, the docs the prompt render
+// composes into an agent's persona — are structurally exempt: an agent reads its
+// whole persona by construction. Suppression elsewhere is deliberate and
+// per-doc: `lint-ignore: length`, surfaced ONLY by the finding itself.
+// ---------------------------------------------------------------------------
+const BOOT_CONTENT_MAX_WORDS = 1000;
+const EVENT_CONTENT_MAX_WORDS = 1000;
+const BOOT_PREVIEW_MAX_WORDS = 3000;
+/** A routing line costs more than it saves for a short rule or fact. */
+const PREVIEW_TO_CONTENT_MAX_WORDS = 30;
+const LENGTH_REMEDY = 'Keep the load-bearing core here and split the depth into [[linked]] reference docs carrying no surfaces at all (the listing and the link are how they are found, so they cost nothing until followed). Split by subject: each leaf covers a different subject a task might need on its own; never split off “further evidence”, examples, or references — a references leaf is never followed, so supporting material stays next to the point it supports or gets cut. Keep it whole — `lint-ignore: length` in the frontmatter — only when every reader who surfaces this doc genuinely benefits from reading 100% of it, or it is one indivisible body of knowledge; then splitting just adds hops.';
+function ignoresRule(fm, rule) {
+    const v = fm['lint-ignore'];
+    return v === rule || (Array.isArray(v) && v.includes(rule));
+}
+function countBodyWords(body) {
+    const trimmed = body.trim();
+    return trimmed === '' ? 0 : trimmed.split(/\s+/).length;
+}
+/** The length rule. Caps come from the parsed entries — an invalid entry already
+ *  fails the schema check, so it simply matches no cap here. `docName` is the
+ *  doc's canonical identity; persona layers under `kinds/` are never capped. */
+export function lintBodyLength(fm, body, docName) {
+    if (ignoresRule(fm, 'length'))
+        return null;
+    if (docName === 'kinds' || docName.startsWith('kinds/'))
+        return null;
+    const entries = parsedSubstrateSurfaces(fm);
+    const words = countBodyWords(body);
+    if (entries.some((e) => e.on === 'boot' && e.at === 'content') && words > BOOT_CONTENT_MAX_WORDS) {
+        return `body is ${words} words but a boot entry at \`content\` inlines every word into every agent's system prompt — capped at ${BOOT_CONTENT_MAX_WORDS} words (boot preview gets ${BOOT_PREVIEW_MAX_WORDS}; name entries are never capped). ${LENGTH_REMEDY}`;
+    }
+    const contentEvents = [...new Set(entries.filter((e) => e.on !== 'boot' && e.at === 'content').map((e) => e.on))];
+    if (contentEvents.length > 0 && words > EVENT_CONTENT_MAX_WORDS) {
+        return `body is ${words} words, over the ${EVENT_CONTENT_MAX_WORDS}-word cap for a \`content\` entry on ${contentEvents.join('/')} (the whole body delivers every time the entry fires; name entries are never capped). ${LENGTH_REMEDY}`;
+    }
+    if (entries.some((e) => e.on === 'boot' && e.at === 'preview') && words > BOOT_PREVIEW_MAX_WORDS) {
+        return `body is ${words} words, over the ${BOOT_PREVIEW_MAX_WORDS}-word cap for boot preview (the routing line invites every reader into the whole body, so the cap is the longest doc worth reading end-to-end; boot content is capped at ${BOOT_CONTENT_MAX_WORDS} words; name entries are never capped). ${LENGTH_REMEDY}`;
+    }
+    return null;
+}
+/** Warn when a body short enough to inline still pays a routing line. */
+export function lintShortPreviewBody(fm, body) {
+    const words = countBodyWords(body);
+    if (words >= PREVIEW_TO_CONTENT_MAX_WORDS)
+        return null;
+    const previewEvents = [...new Set(parsedSubstrateSurfaces(fm).filter((e) => e.at === 'preview').map((e) => e.on))];
+    if (previewEvents.length === 0)
+        return null;
+    const noun = previewEvents.length === 1 ? 'entry delivers' : 'entries deliver';
+    return `body is ${words} words but the ${previewEvents.join('/')} ${noun} \`preview\`; use \`at: content\` so agents receive the whole rule without a separate memory read`;
+}
+// ---------------------------------------------------------------------------
+// Reference resolution: what a `[[link]]` or a `memory-read` route may name.
+// ---------------------------------------------------------------------------
+/** Every canonical name a reference may target in a corpus: each document's
+ *  exact identity plus every canonical directory, because reading a directory
+ *  answers with its own document and its listing. Derived from the canonical
+ *  tree, never from string prefixes of a name. */
+export function resolvableCanonicalNames(docs) {
+    const names = new Set();
+    const walk = (node) => {
+        if (node.name !== '')
+            names.add(node.name);
+        for (const child of node.childDirectories)
+            walk(child);
+        for (const child of node.childDocuments)
+            names.add(child.name);
+    };
+    walk(buildMemoryTree(docs).root);
+    return names;
+}
+const FRONT_DOOR_REMEDY = 'the store\'s root INDEX.md is the workspace front door: give it `surfaces: [{on: workspace-open, at: content}, {on: read, match: "./**", at: content}]` (run `crtr memory write -h` first)';
+const GLOB_META_RE = /[*?[\]{}]/;
+function safeGlob(target, glob) {
+    try {
+        return matchesGlob(target, glob);
+    }
+    catch {
+        return false;
+    }
+}
+/** The exact canonical name a WILDCARD-FREE `memory-read` glob names. A `./`
+ *  glob is relative to the carrier's routing anchor — its own canonical name
+ *  when it is its directory's document, else the canonical directory it sits
+ *  in. */
+function literalRouteTarget(glob, routingAnchor) {
+    const rest = glob.startsWith('./') ? glob.slice(2) : glob;
+    const absolute = glob.startsWith('./') ? `${routingAnchor}/${rest}` : rest;
+    return canonicalSegments(normalizeDocName(absolute)).join('/');
+}
+function routeMatchesAny(glob, routingAnchor, names) {
+    if (!glob.startsWith('./')) {
+        for (const name of names)
+            if (safeGlob(name, glob))
+                return true;
+        return false;
+    }
+    const rest = glob.slice(2);
+    const prefix = routingAnchor === '' ? '' : `${routingAnchor}/`;
+    for (const name of names) {
+        if (!name.startsWith(prefix))
+            continue;
+        if (safeGlob(name.slice(prefix.length), rest))
+            return true;
+    }
+    return false;
+}
+/** The tail a not-found reference should be searched by, plus the `/INDEX`
+ *  diagnostic when the reference still uses the retired directory spelling. */
+function missingNameDiagnostic(name) {
+    const segments = canonicalSegments(name);
+    const collapsedIndex = segments[segments.length - 1] === INDEX_SEGMENT;
+    const collapsed = collapseTrailingIndex(name);
+    const leaf = canonicalSegments(collapsed).pop() ?? name;
+    const indexNote = collapsedIndex
+        ? ` A directory's own document answers at the directory name, so name \`${collapsed}\` instead.`
+        : '';
+    return `${indexNote} Run \`crtr memory find ${leaf}\` for the canonical name, or drop the reference.`;
+}
+/** Files a store holds but the substrate never loads as documents: `SKILL.md`
+ *  is an Agent Skill bundle and `MEMORY.md` an index file. They are YAML-parsed
+ *  so a broken one is still caught, and nothing else applies to them. */
+const NON_DOCUMENT_FILES = new Set(['SKILL.md', 'MEMORY.md']);
+/** Lint ONE physical store, whether or not the runtime mounts it. An undeclared
+ *  or invalid project store still has its files checked — every store-local rule
+ *  holds before a namespace exists — but its references are deferred, because
+ *  the identities its links resolve against are undetermined until migration
+ *  declares the namespace. */
+export function lintMemoryStore(store, options = {}) {
+    const findings = [];
+    const base = {
+        scope: store.scope,
+        ...(store.storeRoot === '' ? {} : { storeRoot: store.storeRoot }),
+    };
+    const add = (severity, rule, path, message, extra = {}) => {
+        findings.push({ severity, rule, path, message, ...base, ...extra });
+    };
+    const mounted = store.mountStatus === 'ready';
+    if (store.mountFailure === 'collision') {
+        add('error', 'owner-path-collision', store.namespacePath ?? store.storeRoot, store.diagnostic ?? `project memory stores have owner directories that normalize to the same effective prefix \`${store.namespace}\` — rename one owner directory`);
+    }
+    else if (store.mountStatus === 'undeclared' || store.mountStatus === 'invalid') {
+        add('error', 'store-namespace', store.namespacePath ?? store.storeRoot, store.diagnostic ?? 'project memory store does not mount');
+    }
+    if (store.mountStatus === 'undeclared' || store.mountStatus === 'invalid') {
+        if (options.resolvable !== undefined) {
+            add('notice', 'reference-check-deferred', store.storeRoot, 'links and `memory-read` routes are not checked here: the canonical identities they resolve against are undetermined until this store declares its namespace');
+        }
+    }
+    const isProjectStore = store.scope === 'project' && store.plugin === undefined;
+    const frontDoorMode = options.frontDoor ?? 'ignore';
+    const frontDoors = [];
+    // Documents as the runtime loads them, keyed by absolute path: the walk below
+    // owns file-level checks (including the files loading drops), these own every
+    // identity-level one. Hidden dirs are excluded from both.
+    const docs = loadStoreMemoryDocs(store, true).filter((doc) => !doc.physicalRelativePath.split('/').some((segment) => segment.startsWith('.')));
+    const docsByPath = new Map(docs.map((doc) => [doc.path, doc]));
+    let checked = 0;
+    let documents = 0;
+    for (const file of walkFiles(store.storeRoot, (n) => n.endsWith('.md'), (d) => d.startsWith('.'))) {
+        const relPath = relative(store.storeRoot, file).split(sep).join('/');
+        if (relPath === '')
+            continue;
+        checked += 1;
+        let fm;
+        let body;
+        try {
+            ({ data: fm, body } = parseFrontmatterGeneric(readText(file)));
+        }
+        catch (e) {
+            add('error', 'yaml', file, `invalid YAML frontmatter: ${(e instanceof Error ? e.message : String(e)).split('\n')[0]}`);
+            continue;
+        }
+        if (NON_DOCUMENT_FILES.has(basename(file)))
+            continue;
+        documents += 1;
+        const isRootFile = localNameFromPath(relPath) === '';
+        const doc = docsByPath.get(file);
+        // A file the loader dropped (a root INDEX.md composing to the empty name)
+        // carries no canonical identity, but its frontmatter contract still holds —
+        // the field rules below run before the identity-dependent ones.
+        const named = doc === undefined ? {} : { name: doc.name };
+        const schemaError = lintSubstrateFrontmatter(fm);
+        if (schemaError !== null)
+            add('error', 'schema', file, schemaError, named);
+        if (fm !== null) {
+            const isRepositoryRootStore = isProjectStore && store.ownerRelativePath === '';
+            if (fm['namespace'] !== undefined && !(isRootFile && isRepositoryRootStore)) {
+                const message = isRootFile && isProjectStore && store.ownerRelativePath !== undefined && store.ownerRelativePath !== ''
+                    ? `\`namespace:\` belongs only on the repository-root store's ${INDEX_SEGMENT}.md (${store.namespacePath ?? store.storeRoot}) — a nested store's prefix is derived from its path under ${store.repositoryRoot ?? store.ownerDir ?? store.storeRoot}`
+                    : `\`namespace:\` belongs only on a project store's root ${INDEX_SEGMENT}.md, where it declares the whole store's prefix — drop it here (an explicit \`name:\` is store-LOCAL and never carries a namespace)`;
+                add('error', 'namespace-placement', file, message, named);
+            }
+            if (isRootFile && fm['name'] !== undefined) {
+                add('error', 'root-name', file, `a store's root ${INDEX_SEGMENT}.md carries no \`name:\` — its identity answers at \`${store.namespace}\`; drop the field`, named);
+            }
+        }
+        if (doc === undefined) {
+            // In a project store the missing/invalid declaration is already the finding.
+            if (isRootFile && !isProjectStore) {
+                add('error', 'root-index-unaddressable', file, `a root ${INDEX_SEGMENT}.md has no canonical name in a ${store.scope} store, which declares no namespace — only a project store's root document answers at its namespace, so rename this file to a named document (\`<topic>.md\`) or fold its content into the docs it introduces`);
+            }
+            continue;
+        }
+        if (fm !== null) {
+            if (!isRootFile && fm['name'] !== undefined) {
+                const raw = fm['name'];
+                if (typeof raw !== 'string' || raw.trim() === '') {
+                    add('error', 'local-name', file, `invalid name: ${JSON.stringify(raw)} (expected a non-empty store-local name)`, named);
+                }
+                else {
+                    // Validated as WRITTEN: normalizing first would silently accept an
+                    // `NN-` ordering prefix, which is physical-path-only. The suggestion
+                    // is the normalized spelling.
+                    const valid = validateExplicitLocalName(raw.trim(), store.namespace);
+                    if (!valid.ok) {
+                        const suggested = suggestedLocalName(normalizeDocName(raw.trim()), store.namespace, relPath);
+                        add('error', 'local-name', file, `invalid name \`${raw}\`: ${valid.reason} — ${suggested}`, named);
+                    }
+                }
+            }
+            for (const issue of validateMemoryExtensionValues(fm['extensions'], memoryExtensionValidationCatalog(doc))) {
+                add('error', 'extension', file, `${issue.path}: ${issue.message}`, named);
+            }
+            const lengthError = lintBodyLength(fm, body, doc.name);
+            if (lengthError !== null)
+                add('error', 'length', file, lengthError, named);
+            const shortPreview = lintShortPreviewBody(fm, body);
+            if (shortPreview !== null)
+                add('warning', 'short-preview', file, shortPreview, named);
+            const entries = parsedSubstrateSurfaces(fm);
+            if (options.nestedStore === true && entries.some((e) => e.on === 'boot')) {
+                add('warning', 'nested-store-boot', file, 'nested-store docs never ride the boot catalog, so its boot surfaces entries are inert — drop them', named);
+            }
+            if (isProjectStore && entries.some((e) => e.on === 'workspace-open' && e.at === 'content')) {
+                const complete = entries.some((entry) => {
+                    if (entry.on !== 'read' || entry.at !== 'content')
+                        return false;
+                    return entry.match?.includes('./**') === true;
+                });
+                frontDoors.push({ path: file, root: isRootFile, complete });
+            }
+            for (const entry of entries) {
+                if (entry.on !== 'memory-read')
+                    continue;
+                lintMemoryReadEntry(entry, doc, fm, options.resolvable, mounted, add);
+            }
+        }
+        if (options.resolvable !== undefined && mounted) {
+            for (const name of docLinkNames(body)) {
+                if (options.resolvable.has(name))
+                    continue;
+                add('error', 'dangling-link', file, `dangling doc link [[${name}]]: no memory document or directory in this target view has that exact canonical name.${missingNameDiagnostic(name)}`, named);
+            }
+        }
+    }
+    // Same-store canonical collisions. The loader already orders `foo/INDEX.md`
+    // ahead of `foo.md`, so the first candidate is the deterministic read winner.
+    const byName = new Map();
+    for (const doc of docs) {
+        const bucket = byName.get(doc.name);
+        if (bucket)
+            bucket.push(doc);
+        else
+            byName.set(doc.name, [doc]);
+    }
+    for (const [name, candidates] of byName) {
+        if (candidates.length < 2)
+            continue;
+        const paths = candidates.map((doc) => doc.path);
+        add('error', 'canonical-collision', paths[0], `${candidates.length} files in this store own canonical name \`${name}\` (${paths.join(', ')}); \`${candidates[0].physicalRelativePath}\` is the deterministic read winner. Recover the collision with \`crtr memory move ${name} --to <new-free-name>\`; move selects the first physical path in stable lexical order, and no filesystem surgery is needed.`, { name, paths });
+    }
+    if (isProjectStore) {
+        for (const door of frontDoors) {
+            if (door.root)
+                continue;
+            add('error', 'front-door', door.path, `a project store's workspace front door is its root ${INDEX_SEGMENT}.md, not this doc — a {on: workspace-open, at: content} entry here delivers a second whole document at every workspace open; fold it into the root document or lower this entry`);
+        }
+        const repositoryRoot = (store.ownerRelativePath ?? '') === '';
+        const hasRootDoor = frontDoors.some((door) => door.root && door.complete);
+        if (repositoryRoot && !hasRootDoor && frontDoorMode !== 'ignore') {
+            const owner = store.ownerDir ?? store.storeRoot;
+            const message = frontDoorMode === 'required'
+                ? `the selected profile manages this project but its store has no workspace front door — ${FRONT_DOOR_REMEDY}`
+                : `this project store has no workspace front door, so agents open the workspace blind — ${FRONT_DOOR_REMEDY}`;
+            add(frontDoorMode === 'required' ? 'error' : 'warning', 'front-door', owner, message);
+        }
+    }
+    return makeResult(findings, checked, documents, 1);
+}
+/** The local spelling an invalid explicit `name:` should use: dropping the field
+ *  entirely when the physical path already derives the same identity. */
+function suggestedLocalName(local, namespace, physicalRelativePath) {
+    let fixed = collapseTrailingIndex(local);
+    if (namespace !== '') {
+        const nsSegments = canonicalSegments(namespace);
+        const segments = canonicalSegments(fixed);
+        if (nsSegments.every((s, i) => segments[i] === s))
+            fixed = segments.slice(nsSegments.length).join('/');
+    }
+    if (fixed === '') {
+        return `remove the field: this document's identity would be the store root's, which only the root ${INDEX_SEGMENT}.md owns`;
+    }
+    return fixed === localNameFromPath(physicalRelativePath)
+        ? `drop the field — its physical path already derives \`${fixed}\``
+        : `use \`name: ${fixed}\``;
+}
+function lintMemoryReadEntry(entry, doc, fm, resolvable, mounted, add) {
+    for (const glob of entry.match ?? []) {
+        if ((glob === '**' || glob === '*') && !ignoresRule(fm, 'broad-memory-read')) {
+            add('warning', 'broad-memory-read', doc.path, `memory-read glob \`${glob}\` fires on every memory read — scope it to a name subtree`, { name: doc.name });
+            continue;
+        }
+        if (resolvable === undefined || !mounted)
+            continue;
+        if (!GLOB_META_RE.test(glob)) {
+            const target = literalRouteTarget(glob, doc.routingAnchor);
+            if (!resolvable.has(target)) {
+                add('error', 'memory-read-route', doc.path, `memory-read route \`${glob}\` names \`${target}\`, which is no document or directory in this target view, so the entry can never fire.${missingNameDiagnostic(target)}`, { name: doc.name });
+            }
+            continue;
+        }
+        if (!routeMatchesAny(glob, doc.routingAnchor, resolvable)) {
+            add('warning', 'memory-read-route', doc.path, `memory-read glob \`${glob}\`${glob.startsWith('./') ? ` (anchored at \`${doc.routingAnchor}\`)` : ''} matches no canonical name in this target view — a project document's name carries its store's namespace, so an unqualified subtree glob no longer matches`, { name: doc.name });
+        }
+    }
+}
+function ambientTarget() {
+    return {
+        cwd: process.cwd(),
+        profileId: process.env['CRTR_PROFILE_ID'] || null,
+        nodeId: process.env['CRTR_NODE_ID'] || null,
+    };
+}
+/** Lint every store a target sees, then the diagnostics only the merged view
+ *  produces: references resolved against the view's canonical names, and equal
+ *  canonical identities held by several stores. */
+export function lintMemoryTarget(options = {}) {
+    const target = options.target ?? ambientTarget();
+    const includeDescendants = options.includeDescendants ?? true;
+    const view = loadMemoryTargetView(target, {
+        ...(options.scope === undefined ? {} : { scope: options.scope }),
+        includeDescendants,
+        quiet: true,
+    });
+    const resolvable = resolvableCanonicalNames(view.docs);
+    const nestedStores = new Set(includeDescendants
+        ? descendantStoreRoots(projectScopeRoots(target.cwd, target.profileId)).map((root) => realpathOrSelf(join(root, 'memory')))
+        : []);
+    // Profile coverage: every project the selected profile manages carries a
+    // workspace front door. A managed project with no store at all still owes one.
+    const coverage = options.scope === undefined || options.scope === 'project';
+    const managed = new Set();
+    const managedRepositories = new Set();
+    if (coverage && target.profileId !== null && target.profileId !== '') {
+        try {
+            const { manifest } = loadProfileManifest(target.profileId);
+            for (const project of manifest.projects) {
+                const owner = realpathOrSelf(project.path);
+                managed.add(owner);
+                const association = associateRepository(owner);
+                managedRepositories.add(association.ok ? association.association.repositoryRoot : owner);
+            }
+        }
+        catch {
+            // Missing/deleted/invalid selected profile: no managed-project coverage.
+        }
+    }
+    const cwdReal = realpathOrSelf(target.cwd);
+    const findings = [];
+    let checked = 0;
+    let documents = 0;
+    let storesLinted = 0;
+    const linted = new Set();
+    for (const store of view.stores) {
+        const owner = store.ownerDir === undefined ? null : realpathOrSelf(store.ownerDir);
+        const repositoryRoot = store.repositoryRoot ?? owner;
+        if (repositoryRoot !== null && repositoryRoot !== undefined)
+            linted.add(repositoryRoot);
+        const nested = store.ownerRelativePath !== undefined && store.ownerRelativePath !== '';
+        const frontDoor = nested || !coverage || owner === null
+            ? 'ignore'
+            : managedRepositories.has(repositoryRoot ?? owner)
+                ? 'required'
+                : managed.size === 0 && owner === cwdReal
+                    ? 'advisory'
+                    : 'ignore';
+        const result = lintMemoryStore(store, {
+            resolvable,
+            frontDoor,
+            nestedStore: nestedStores.has(realpathOrSelf(store.storeRoot)),
+        });
+        findings.push(...result.findings);
+        checked += result.checked;
+        documents += result.documents;
+        storesLinted += result.storesLinted;
+    }
+    if (coverage) {
+        // A managed project whose directory holds no `.crouter/` never became a
+        // store in the view, and still owes a front door at its repository root.
+        for (const owner of managed) {
+            const association = associateRepository(owner);
+            const repositoryRoot = association.ok ? association.association.repositoryRoot : owner;
+            if (linted.has(repositoryRoot))
+                continue;
+            const result = lintMemoryStore(openProjectMemoryStore(repositoryRoot), { resolvable, frontDoor: 'required' });
+            findings.push(...result.findings);
+            checked += result.checked;
+            documents += result.documents;
+            storesLinted += result.storesLinted;
+            linted.add(repositoryRoot);
+        }
+        const cwdAssociation = associateRepository(cwdReal);
+        const cwdRepositoryRoot = cwdAssociation.ok ? cwdAssociation.association.repositoryRoot : cwdReal;
+        if (managed.size === 0 && !linted.has(cwdRepositoryRoot) && pathExists(join(target.cwd, '.crouter'))) {
+            const result = lintMemoryStore(openProjectMemoryStore(target.cwd), { resolvable, frontDoor: 'advisory' });
+            findings.push(...result.findings);
+            checked += result.checked;
+            documents += result.documents;
+            storesLinted += result.storesLinted;
+        }
+    }
+    // Equal canonical identities across stores are legitimate — a linked worktree
+    // and its main checkout declare one namespace on purpose — so they are
+    // reported with the view's winner and every ordered candidate, never failed.
+    const tree = buildMemoryTree(view.docs);
+    const walk = (node) => {
+        const candidates = node.documentCandidates;
+        if (candidates.length > 1 && new Set(candidates.map((doc) => doc.root)).size > 1) {
+            findings.push({
+                severity: 'notice',
+                rule: 'cross-store-candidates',
+                path: candidates[0].path,
+                name: node.name,
+                paths: candidates.map((doc) => doc.path),
+                message: `canonical name \`${node.name}\` is held by ${candidates.length} stores; this target view reads ${candidates[0].path} (${candidates[0].scope}) and the later candidates stay reachable with \`crtr memory read ${node.name} --dir <project>\``,
+            });
+        }
+        for (const child of node.childDirectories)
+            walk(child);
+        for (const child of node.childDocuments)
+            walk(child);
+    };
+    walk(tree.root);
+    return {
+        ...makeResult(findings, checked, documents, storesLinted),
+        stores: view.stores,
+        profileProjects: managed.size,
+    };
+}

package/dist/core/memory/project-namespace.d.ts

@@ -0,0 +1,31 @@
+export type ProjectNamespaceSource = 
+/** The store root's existing explicit `name`. */
+'root-name'
+/** Git common-repository label plus the owner's worktree-relative path. */
+ | 'git-worktree'
+/** H1 title of the store root's guide body. */
+ | 'root-guide-h1'
+/** The owner directory's own basename. */
+ | 'owner-basename';
+export type ProjectNamespaceDerivation = {
+    ok: true;
+    namespace: string;
+    source: ProjectNamespaceSource;
+} | {
+    ok: false;
+    reason: string;
+};
+export interface ProjectNamespaceInput {
+    /** The project directory containing `.crouter/` — not the memory dir. */
+    ownerDir: string;
+    /** Frontmatter of the store's root `INDEX.md`, when it has one. */
+    rootFrontmatter?: Record<string, unknown> | null;
+    /** Body of the store's root `INDEX.md`, when it has one. */
+    rootBody?: string;
+}
+/** Derive one project store's namespace: its existing root `name` first, else
+ *  the git repository label plus the owner's path within its worktree, else the
+ *  root guide's H1, else the owner basename. An existing root `name` that
+ *  cannot be a namespace fails rather than falling through — a declared
+ *  identity is never silently replaced. */
+export declare function deriveProjectNamespace(input: ProjectNamespaceInput): ProjectNamespaceDerivation;

package/dist/core/memory/project-namespace.js

@@ -0,0 +1,85 @@
+// project-namespace.ts — the ONE-TIME derivation of a project store's
+// namespace, used by migration and the guidance producers that may initialize a
+// store. The runtime NEVER calls this: it reads the `namespace:` declaration on
+// a store's root INDEX.md and refuses to mount a store that has none, so a
+// store's identity cannot depend on cwd, git state, or discovery order after it
+// has already delivered documents.
+import { basename, dirname, relative, resolve, sep } from 'node:path';
+import { realpathOrSelf } from '../fs-utils.js';
+import { gitSync } from '../git.js';
+import { collapseTrailingIndex, normalizeDocName, slugCanonicalPath, validateNamespace } from './identity.js';
+/** Derive one project store's namespace: its existing root `name` first, else
+ *  the git repository label plus the owner's path within its worktree, else the
+ *  root guide's H1, else the owner basename. An existing root `name` that
+ *  cannot be a namespace fails rather than falling through — a declared
+ *  identity is never silently replaced. */
+export function deriveProjectNamespace(input) {
+    const ownerDir = resolve(input.ownerDir);
+    const rootName = input.rootFrontmatter?.['name'];
+    if (typeof rootName === 'string' && rootName.trim() !== '') {
+        // Lifted verbatim (only ordering prefixes and a trailing INDEX removed) —
+        // an already-authored identity is an address, not a label to re-slug.
+        const lifted = collapseTrailingIndex(normalizeDocName(rootName.trim()));
+        const check = validateNamespace(lifted);
+        if (!check.ok)
+            return { ok: false, reason: `root \`name: ${rootName.trim()}\` cannot become a namespace: ${check.reason}` };
+        return { ok: true, namespace: lifted, source: 'root-name' };
+    }
+    const fromGit = gitNamespace(ownerDir);
+    if (fromGit !== null)
+        return validated(fromGit, 'git-worktree');
+    const h1 = input.rootBody === undefined ? undefined : h1Title(input.rootBody);
+    if (h1 !== undefined)
+        return validated(slugCanonicalPath(h1), 'root-guide-h1');
+    return validated(slugCanonicalPath(basename(ownerDir) || ownerDir), 'owner-basename');
+}
+function validated(namespace, source) {
+    const check = validateNamespace(namespace);
+    return check.ok ? { ok: true, namespace, source } : { ok: false, reason: `derived namespace \`${namespace}\` is invalid: ${check.reason}` };
+}
+/** `<repo-label>/<owner path within its worktree>`, or `null` outside a git
+ *  working tree. The label comes from `--git-common-dir`, which resolves a
+ *  LINKED WORKTREE to the shared repo storage, so a canvas worktree checked out
+ *  under a node-id path shares its main checkout's namespace. */
+function gitNamespace(ownerDir) {
+    const label = gitRepoLabel(ownerDir);
+    if (label === null)
+        return null;
+    const top = gitWorktreeRoot(ownerDir);
+    if (top === null)
+        return null;
+    // `--show-toplevel` resolves through symlinks (macOS /tmp -> /private/tmp);
+    // realpath both sides so a symlinked owner doesn't produce a `../..` suffix.
+    const rel = relative(realpathOrSelf(top), realpathOrSelf(ownerDir)).split(sep).join('/');
+    if (rel.startsWith('..'))
+        return null;
+    return rel === '' || rel === '.' ? slugCanonicalPath(label) : slugCanonicalPath(`${label}/${rel}`);
+}
+function gitRepoLabel(dir) {
+    const res = gitSync(['rev-parse', '--path-format=absolute', '--git-common-dir'], dir);
+    if (res.status !== 0)
+        return null;
+    const gitCommonDir = res.stdout.trim();
+    if (gitCommonDir === '')
+        return null;
+    return basename(dirname(gitCommonDir)) || null;
+}
+function gitWorktreeRoot(dir) {
+    const res = gitSync(['rev-parse', '--path-format=absolute', '--show-toplevel'], dir);
+    if (res.status !== 0)
+        return null;
+    const top = res.stdout.trim();
+    return top === '' ? null : resolve(top);
+}
+/** First Markdown H1 in a body, heading marker stripped. */
+function h1Title(body) {
+    for (const raw of body.split('\n')) {
+        const m = raw.match(/^#\s+(.+)$/);
+        if (m) {
+            const title = m[1].replace(/\s+/g, ' ').trim();
+            if (title !== '')
+                return title;
+        }
+    }
+    return undefined;
+}

package/dist/core/memory/repository-association.d.ts

@@ -0,0 +1,31 @@
+export type RepositoryKind = 'git' | 'non-git';
+export interface RepositoryAssociation {
+    kind: RepositoryKind;
+    repositoryRoot: string;
+    repositoryKey: string;
+    ownerRelativePath: string;
+    declarationPath: string;
+}
+export type RepositoryAssociationFailureCode = 'no-project-root' | 'git-lookup-failed' | 'owner-outside-root' | 'owner-path-invalid';
+export type RepositoryAssociationResult = {
+    ok: true;
+    association: RepositoryAssociation;
+} | {
+    ok: false;
+    code: RepositoryAssociationFailureCode;
+    ownerDir: string;
+    repositoryRoot?: string;
+    reason: string;
+};
+/** Normalize a POSIX-slash relative owner path into canonical segments. */
+export declare function normalizeOwnerRelativePath(relPosix: string): {
+    ok: true;
+    path: string;
+} | {
+    ok: false;
+    reason: string;
+};
+/** Associate one physical project-store owner with its repository identity. */
+export declare function associateRepository(ownerDir: string): RepositoryAssociationResult;
+/** Clear successful associations; failures are deliberately never cached. */
+export declare function resetRepositoryAssociationCache(): void;