@north-light/crouter 0.3.226 → 0.3.228

package/dist/core/memory/repository-association.js

@@ -0,0 +1,129 @@
+import { existsSync, statSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
+import { gitSync } from '../git.js';
+import { realpathOrSelf } from '../fs-utils.js';
+import { CRTR_DIR_NAME } from '../../types.js';
+import { INDEX_SEGMENT, slugCanonicalSegment, validateNamespace } from './identity.js';
+const associationCache = new Map();
+const GIT_LOOKUP_TIMEOUT_MS = 5000;
+/** Normalize a POSIX-slash relative owner path into canonical segments. */
+export function normalizeOwnerRelativePath(relPosix) {
+    const normalizedSeparators = relPosix.replace(/\\/g, '/');
+    if (normalizedSeparators === '' || normalizedSeparators === '.')
+        return { ok: true, path: '' };
+    const rawSegments = normalizedSeparators.split('/');
+    for (const segment of rawSegments) {
+        if (segment === '' || segment === '.' || segment === '..') {
+            return { ok: false, reason: `owner path contains invalid segment \`${segment}\`` };
+        }
+    }
+    const segments = rawSegments.map(slugCanonicalSegment);
+    for (let i = 0; i < segments.length; i++) {
+        if (segments[i] === '') {
+            return { ok: false, reason: `directory \`${rawSegments[i]}\` normalizes to an empty name segment` };
+        }
+    }
+    const path = segments.join('/');
+    if (segments[segments.length - 1].toLowerCase() === INDEX_SEGMENT.toLowerCase()) {
+        return { ok: false, reason: `owner path ends in reserved segment \`${INDEX_SEGMENT}\`` };
+    }
+    const check = validateNamespace(path);
+    return check.ok ? { ok: true, path } : { ok: false, reason: check.reason };
+}
+/** Associate one physical project-store owner with its repository identity. */
+export function associateRepository(ownerDir) {
+    const owner = realpathOrSelf(resolve(ownerDir));
+    const cached = associationCache.get(owner);
+    if (cached !== undefined)
+        return { ok: true, association: cached };
+    const git = gitSync(['rev-parse', '--path-format=absolute', '--show-toplevel', '--git-common-dir'], owner, undefined, { timeoutMs: GIT_LOOKUP_TIMEOUT_MS });
+    if (git.status === 0 || git.timedOut === true || !/not a git repository/i.test(git.stderr)) {
+        if (git.timedOut === true) {
+            return failure('git-lookup-failed', owner, `git lookup timed out after ${GIT_LOOKUP_TIMEOUT_MS}ms`);
+        }
+        if (git.status !== 0) {
+            const detail = git.stderr.trim() || `git rev-parse exited with status ${git.status}`;
+            return failure('git-lookup-failed', owner, `git lookup failed: ${detail}`);
+        }
+        const lines = git.stdout.split(/\r?\n/);
+        const rootLine = lines[0]?.trim() ?? '';
+        const commonLine = lines[1]?.trim() ?? '';
+        if (rootLine === '' || commonLine === '') {
+            return failure('git-lookup-failed', owner, 'git lookup returned an empty repository root or common directory');
+        }
+        const repositoryRoot = realpathOrSelf(resolve(rootLine));
+        const repositoryKey = `git:${realpathOrSelf(resolve(commonLine))}`;
+        const rel = relative(repositoryRoot, owner).split(sep).join('/');
+        if (isAbsolute(rel) || rel === '..' || rel.startsWith('../')) {
+            return failure('owner-outside-root', owner, `owner ${owner} is outside repository root ${repositoryRoot}`, repositoryRoot);
+        }
+        const ownerPath = normalizeOwnerRelativePath(rel);
+        if (!ownerPath.ok)
+            return failure('owner-path-invalid', owner, ownerPath.reason, repositoryRoot);
+        return remember({
+            kind: 'git',
+            repositoryRoot,
+            repositoryKey,
+            ownerRelativePath: ownerPath.path,
+            declarationPath: join(repositoryRoot, CRTR_DIR_NAME, 'memory', 'INDEX.md'),
+        }, owner);
+    }
+    const repositoryRoot = nonGitRepositoryRoot(owner);
+    if (repositoryRoot === null)
+        return failure('no-project-root', owner, `no ancestor ${CRTR_DIR_NAME}/memory store found for ${owner}`);
+    const ownerPath = normalizeOwnerRelativePath(relative(repositoryRoot, owner).split(sep).join('/'));
+    if (!ownerPath.ok)
+        return failure('owner-path-invalid', owner, ownerPath.reason, repositoryRoot);
+    return remember({
+        kind: 'non-git',
+        repositoryRoot,
+        repositoryKey: `path:${repositoryRoot}`,
+        ownerRelativePath: ownerPath.path,
+        declarationPath: join(repositoryRoot, CRTR_DIR_NAME, 'memory', 'INDEX.md'),
+    }, owner);
+}
+/** Clear successful associations; failures are deliberately never cached. */
+export function resetRepositoryAssociationCache() {
+    associationCache.clear();
+}
+function remember(association, owner) {
+    associationCache.set(owner, association);
+    return { ok: true, association };
+}
+function failure(code, ownerDir, reason, repositoryRoot) {
+    return repositoryRoot === undefined
+        ? { ok: false, code, ownerDir, reason }
+        : { ok: false, code, ownerDir, repositoryRoot, reason };
+}
+function nonGitRepositoryRoot(owner) {
+    const home = realpathOrSelf(homedir());
+    const ownerIsUnderHome = isWithin(owner, home);
+    let dir = owner;
+    let outermost = null;
+    while (true) {
+        // The user's own .crouter/memory is a separate scope, never a project root.
+        if ((!ownerIsUnderHome || dir !== home) && hasProjectMemoryStore(dir))
+            outermost = dir;
+        if (ownerIsUnderHome && dir === home)
+            break;
+        const parent = dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    return outermost;
+}
+function hasProjectMemoryStore(owner) {
+    const memory = join(owner, CRTR_DIR_NAME, 'memory');
+    try {
+        return existsSync(memory) && statSync(memory).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+function isWithin(child, parent) {
+    const rel = relative(parent, child);
+    return rel === '' || (rel !== '..' && !rel.startsWith(`..${sep}`) && !isAbsolute(rel));
+}

package/dist/core/memory/tree.d.ts

@@ -0,0 +1,39 @@
+import type { MemoryDoc } from '../memory-resolver.js';
+/** One canonical directory row: its own document (when it has one) plus its
+ *  immediate members. */
+export interface MemoryTreeNode {
+    /** Exact canonical identity. `''` is the corpus root, which holds no
+     *  document — every store's documents merge beneath it. */
+    name: string;
+    /** Sort key among siblings: the stored physical path segment, `NN-` ordering
+     *  prefix retained, or this node's canonical segment when no physical
+     *  segment aligns. */
+    order: string;
+    /** The winning document attached to this row, or null for a directory that
+     *  carries none. */
+    document: MemoryDoc | null;
+    /** Every physical document sharing this identity, in source order. */
+    documentCandidates: readonly MemoryDoc[];
+    /** Immediate children that have members of their own, ordered. Each may also
+     *  carry its own `document`. */
+    childDirectories: readonly MemoryTreeNode[];
+    /** Immediate childless members, ordered. A node's own document never appears
+     *  among its children. */
+    childDocuments: readonly MemoryTreeDocumentNode[];
+}
+/** A childless node: it exists only because a document landed on it. */
+export interface MemoryTreeDocumentNode extends MemoryTreeNode {
+    document: MemoryDoc;
+}
+export interface MemoryTree {
+    root: MemoryTreeNode;
+    /** The node at an exact canonical name, or null when nothing lives there. */
+    node(name: string): MemoryTreeNode | null;
+    /** Does this canonical name have members? True for the corpus root when the
+     *  corpus is non-empty. */
+    isDirectory(name: string): boolean;
+}
+/** Merge a precedence-ordered corpus into the canonical tree. Documents sharing
+ *  one identity stay in source order behind that node, so its `document` is the
+ *  address winner. */
+export declare function buildMemoryTree(docs: readonly MemoryDoc[]): MemoryTree;

package/dist/core/memory/tree.js

@@ -0,0 +1,93 @@
+// tree.ts — the ONE canonical directory model. A canonical name is a path in a
+// tree whose nodes merge across stores: a node holds the winning document at
+// that exact identity (with every physical candidate behind it) AND its
+// immediate children, so a directory that carries its own document is one row,
+// never a document plus a separate directory of the same name. Listing
+// generation, boot render, inline inventory, and lint all read structure from
+// here instead of scanning name prefixes.
+import { canonicalSegments, normalizeNameSegment } from './identity.js';
+/** The stored physical segments a document supplies as ordering keys for itself
+ *  and its canonical ancestors. Both names are walked from the TAIL and stop at
+ *  the first mismatch, because no canonical segment index addresses a physical
+ *  one: a store's namespace has no physical counterpart at all, and an explicit
+ *  `name:` detaches identity from the path entirely. */
+function physicalOrderSegments(doc) {
+    const canonical = canonicalSegments(doc.name);
+    const physical = canonicalSegments(doc.physicalRelativePath.replace(/\.md$/i, ''));
+    // The INDEX filename names its directory, not a segment of its own.
+    if (doc.representation === 'directory-index')
+        physical.pop();
+    const keys = [];
+    for (let i = canonical.length - 1, j = physical.length - 1; i >= 0 && j >= 0; i--, j--) {
+        const segment = physical[j];
+        if (normalizeNameSegment(segment) !== canonical[i])
+            break;
+        keys.push([canonical.slice(0, i + 1).join('/'), segment]);
+    }
+    return keys;
+}
+function hasMembers(node) {
+    return node.childDirectories.length > 0 || node.childDocuments.length > 0;
+}
+function compareNodes(a, b) {
+    return a.order.localeCompare(b.order) || a.name.localeCompare(b.name);
+}
+function asDocumentNode(node) {
+    if (node.document === null)
+        throw new Error(`memory tree: ${node.name} has neither a document nor members`);
+    return node;
+}
+function finalize(pending, order, index) {
+    const children = [...pending.children.values()]
+        .map((child) => finalize(child, order, index))
+        .sort(compareNodes);
+    const segments = canonicalSegments(pending.name);
+    const node = {
+        name: pending.name,
+        order: order.get(pending.name) ?? segments[segments.length - 1] ?? '',
+        document: pending.documents[0] ?? null,
+        documentCandidates: pending.documents,
+        childDirectories: children.filter(hasMembers),
+        childDocuments: children.filter((child) => !hasMembers(child)).map(asDocumentNode),
+    };
+    index.set(node.name, node);
+    return node;
+}
+/** Merge a precedence-ordered corpus into the canonical tree. Documents sharing
+ *  one identity stay in source order behind that node, so its `document` is the
+ *  address winner. */
+export function buildMemoryTree(docs) {
+    const root = { name: '', documents: [], children: new Map() };
+    const order = new Map();
+    for (const doc of docs) {
+        const segments = canonicalSegments(doc.name);
+        if (segments.length === 0)
+            continue;
+        let node = root;
+        for (let i = 0; i < segments.length; i++) {
+            const segment = segments[i];
+            let child = node.children.get(segment);
+            if (child === undefined) {
+                child = { name: segments.slice(0, i + 1).join('/'), documents: [], children: new Map() };
+                node.children.set(segment, child);
+            }
+            node = child;
+        }
+        node.documents.push(doc);
+        for (const [name, segment] of physicalOrderSegments(doc)) {
+            if (!order.has(name))
+                order.set(name, segment);
+        }
+    }
+    const index = new Map();
+    const rootNode = finalize(root, order, index);
+    const lookup = (name) => index.get(canonicalSegments(name).join('/')) ?? null;
+    return {
+        root: rootNode,
+        node: lookup,
+        isDirectory: (name) => {
+            const node = lookup(name);
+            return node !== null && hasMembers(node);
+        },
+    };
+}

package/dist/core/memory-resolver.d.ts

@@ -1,79 +1,144 @@
 import { type InstalledPlugin, type Scope } from '../types.js';
 import type { ProfileProjectMemory } from '../api/dto/profiles.js';
+import { type DocRepresentation } from './memory/identity.js';
 /**
- * Thin memory-document resolver for the document substrate. Resolution has
- * two passes. First, scopes/sources are tried NEAREST-FIRST (node > project
- * stack nearest > ... > profile > user > builtin) for strong matches: (1) exact
- * substrate identity (`doc.name === query` — the explicit frontmatter `name`,
- * or its path-derived fallback), then (2) direct `memory/<name>.md` physical
- * path. A directory name resolves to NO doc — the read leaf answers it with
- * the directory's listing. Only when no source has a strong
- * match does a second nearest-first pass try bare leaf-name fallback (final
- * path segment only). Thus scope precedence resolves competing strong matches,
- * while a nearer nested doc's coincidental leaf can never shadow a farther
- * canonical identity. It returns the raw parsed frontmatter + body;
- * it does NOT interpret the schema, kind, gate, or rungs — that is the
- * schema/gate layer's job (callers filter by `frontmatter.kind`). Project
- * resolution is a nearest-first stack of every ancestor `.crouter/` (widened by
- * a selected profile's `projects` manifest entries — see `findProjectScopeRoots`
- * in scope.ts), profile is the selected profile's own singleton `memory/` store
- * (from `CRTR_PROFILE_ID`), and user/builtin remain singleton scopes.
+ * Memory-document loading and resolution for the document substrate.
  *
- * Every doc also carries its project store's profile relationship ceiling
- * (`projectMemory`) for the automatic delivery paths to clamp against.
- * Resolution itself never consults it: the full corpus resolves and lists
- * regardless of the ceiling.
+ * Every document belongs to exactly one physical STORE. A store declares a
+ * namespace — a project's `namespace:` on its root `INDEX.md`, an installed
+ * plugin's mount prefix, or empty for user/profile/node/builtin — and every
+ * document's CANONICAL name is that namespace composed with the document's
+ * store-local name (see memory/identity.ts). The canonical name is the only
+ * address: resolution compares the normalized query with canonical identities
+ * and nothing else. There is no physical-path pass, no bare-leaf pass, no
+ * scope-prefixed spelling, and no `<dir>/INDEX` address — a trailing `INDEX`
+ * segment collapses, so a directory's own document answers at the directory
+ * name and `memory find` is the discovery surface when the name is unknown.
+ *
+ * A project store whose repository root carries no valid `namespace:` does not mount: its
+ * documents are absent from every target view, and its descriptor carries the
+ * `crtr sys migrate --dir <repository root>` remedy. Exact-store inspection
+ * (`openProjectMemoryStore` + `loadMemoryStoreView`) still loads it, which is
+ * what lint and migration diagnose an unmounted store through.
+ *
+ * Two views exist over the same loader:
+ *   - a TARGET view — the ordered source stack of one cwd/profile/node
+ *     (node > project stores nearest-first > profile > user > builtin, native
+ *     documents before enabled-plugin documents within each source). Alternate
+ *     physical stores legitimately expose the same canonical identity (a linked
+ *     worktree, a generated copy), so a name yields an ordered CANDIDATE set:
+ *     source order picks the address winner, every later candidate stays
+ *     inspectable.
+ *   - an exact STORE view — one physical project store selected by owner
+ *     directory, which still requires the full canonical query.
+ *
+ * Resolution never consults a project store's profile memory ceiling
+ * (`projectMemory`); the full corpus resolves and lists regardless, and only
+ * automatic delivery clamps against it.
  */
+/** The memory-only scope union: the global `Scope` (`user|project|builtin`)
+ *  plus `profile` and `node`. Confined to the memory resolver/list/read/write/
+ *  render paths — deliberately NOT folded into the global `Scope` union, because
+ *  that would leak these into config, plugin, marketplace, and sys-config
+ *  surfaces the spec does not extend. `node` is the this-node store
+ *  (`nodes/<id>/context/memory/`), available only inside a running node
+ *  (`CRTR_NODE_ID`), and it is the NEAREST scope — a node doc overrides a
+ *  same-named doc at any wider scope. */
+export type MemoryScope = Scope | 'profile' | 'node';
+/** Whether a store contributes to target views.
+ *  `absent` — no `memory/` dir on disk (silent, the ordinary case).
+ *  `undeclared`/`invalid` — a project store the runtime refuses to mount until
+ *  its namespace is declared; `diagnostic` carries the migration remedy. */
+export type MemoryStoreMountStatus = 'ready' | 'absent' | 'undeclared' | 'invalid';
+/** One physical memory store: where its documents live, what namespace their
+ *  canonical names compose under, and whether it mounts. */
+export interface MemoryStoreDescriptor {
+    scope: MemoryScope;
+    /** Absolute path of the physical `memory/` dir. Store identity (and the
+     *  dedup of one real store reached twice) uses its realpath. */
+    storeRoot: string;
+    /** The project directory containing `.crouter/`, for project stores only. */
+    ownerDir?: string;
+    /** Effective project prefix, repository-root namespace composed with the
+     *  owner-relative path; installed-plugin mount prefix, or `''`. */
+    namespace: string;
+    /** The repository-root `INDEX.md` a project namespace is declared on, when
+     *  association succeeds — present even for an undeclared/invalid store so
+     *  lint and migration can point at it. */
+    namespacePath?: string;
+    /** Absolute realpath of the associated repository root, for project stores. */
+    repositoryRoot?: string;
+    /** Linked-worktree/non-Git grouping key, for project stores. */
+    repositoryKey?: string;
+    /** Valid namespace read from the repository-root declaration. */
+    repositoryNamespace?: string;
+    /** Canonical owner path relative to the repository root, empty at the root. */
+    ownerRelativePath?: string;
+    /** Structured cause for a project store that does not mount. */
+    mountFailure?: 'association' | 'collision' | 'undeclared-root' | 'invalid-root';
+    /** The owning plugin's name for a plugin-mounted store. Plugin docs surface
+     *  within a source scope but live under the plugins dir and are managed by
+     *  `crtr pkg`, so consumers that mutate the store gate on this. */
+    plugin?: string;
+    mountStatus: MemoryStoreMountStatus;
+    /** Why a non-`ready` store does not mount, with its actionable remedy. */
+    diagnostic?: string;
+    /** The selected profile relationship's ceiling for this store: the maximum
+     *  rung AUTOMATIC boot and workspace-open delivery may disclose it at.
+     *  Neutral (`content`) for every non-project store. */
+    projectMemory: ProfileProjectMemory;
+}
 export interface MemoryDoc {
-    /** Resolver identity: the doc's explicit frontmatter `name` when present,
-     *  otherwise its normalized path under the scope's memory/ root — e.g.
-     *  memory/taste/foo.md → "taste/foo". */
+    /** Canonical identity — the store's namespace composed with `localName`, and
+     *  the only address resolution accepts. */
     name: string;
+    /** Store-local identity: the explicit frontmatter `name` when present, else
+     *  derived from the store-relative path with ordering prefixes stripped and
+     *  one trailing `INDEX` collapsed. Empty for a store's root document. */
+    localName: string;
     scope: MemoryScope;
     /** Absolute path to the resolved .md file. */
     path: string;
     /** Absolute path of the `memory/` dir this doc loaded from — the store root
-     *  its identity is relative to. Sidecar trees that mirror the doc tree (the
-     *  revision-history log) are derived from `path` relative to this. For a
-     *  plugin doc it is that plugin's own memory dir. */
+     *  its physical path is relative to. Sidecar trees that mirror the doc tree
+     *  (the revision-history log) are derived from `path` relative to this. */
     root: string;
+    /** Store-relative markdown path, kept exactly: placement, ordering, origin,
+     *  and history depend on the physical form, never on segment counts of the
+     *  canonical name. */
+    physicalRelativePath: string;
+    /** Which physical form owns this identity — `foo.md` or `foo/INDEX.md`. */
+    representation: DocRepresentation;
+    /** The canonical directory this doc's `./` memory-read entries match against:
+     *  its own name for a directory document, its parent for a leaf. */
+    routingAnchor: string;
+    store: MemoryStoreDescriptor;
     /** Raw, uncoerced frontmatter record (null when the doc has no frontmatter). */
     frontmatter: Record<string, unknown> | null;
     /** Document body, with the frontmatter block stripped. */
     body: string;
-    /** Set to the owning plugin's name when this doc is mounted from an installed
-     *  plugin (under `<pluginName>/`), undefined for a native scope doc. Plugin
-     *  docs surface within a source scope but live under the plugins dir and are
-     *  managed by `crtr pkg`, not writable/deletable as scope docs — consumers
-     *  that mutate the store gate on this. */
     plugin?: string;
-    /** The selected profile relationship's ceiling for the project store this doc
-     *  came from: the maximum rung AUTOMATIC boot and workspace-open delivery may
-     *  disclose it at. Always present; `content` (neutral, i.e. uncapped) for
-     *  every non-project scope and for a project root no profile entry
-     *  contributes. Resolution, listing, and targeted reads ignore it entirely. */
     projectMemory: ProfileProjectMemory;
 }
-/** The memory-only scope union: the global `Scope` (`user|project|builtin`)
- *  plus `profile` and `node`. Confined to the memory resolver/list/read/write/
- *  render paths — deliberately NOT folded into the global `Scope` union, because
- *  that would leak these into config, plugin, marketplace, and sys-config
- *  surfaces the spec does not extend. `node` is the this-node store
- *  (`nodes/<id>/context/memory/`), available only inside a running node
- *  (`CRTR_NODE_ID`), and it is the NEAREST scope — a node doc overrides a
- *  same-named doc at any wider scope. */
-export type MemoryScope = Scope | 'profile' | 'node';
-export interface MemoryResolutionOpts {
-    /** Restrict resolution to a single scope. Conflicts with a scope prefix on
-     *  the identifier (e.g. `user/foo` with scope=project) throw. */
-    scope?: MemoryScope;
-    /** Restrict resolution to docs whose resolved kind matches. Threaded INTO
-     *  precedence, not applied as a post-resolution filter: within each source,
-     *  a doc whose kind doesn't match is skipped (not returned), so a nearer
-     *  source's wrong-kind doc can no longer shadow a farther source's
-     *  matching-kind doc into a false not_found — resolution simply continues
-     *  to the next source. See `effectiveDocKind` for the kind coercion. */
+/** Every physical document sharing one canonical identity in a view, in source
+ *  order. `winner` is the address a deliberate read resolves to; automatic
+ *  delivery filters the ordered candidates for its own event eligibility. */
+export interface MemoryCandidateSet {
+    name: string;
+    winner: MemoryDoc;
+    candidates: readonly MemoryDoc[];
+}
+/** Restrict resolution to docs whose resolved kind matches. Threaded INTO
+ *  candidate selection, not applied as a post-filter: a wrong-kind candidate is
+ *  skipped so a nearer one cannot shadow a farther matching-kind document into
+ *  a false not_found. */
+export interface MemoryCandidateOpts {
     kind?: string;
+}
+export interface MemoryResolutionOpts extends MemoryCandidateOpts {
+    /** Restrict resolution to a single scope. Narrows the source stack only — the
+     *  query is still the full canonical name. */
+    scope?: MemoryScope;
     /** Also consult `.crouter/memory` stores discovered BELOW the mounted
      *  project roots (bounded discovery — see nested-stores.ts). Opt-in for the
      *  addressing surfaces (`memory read/list/find/lint/delete/origin`); OFF for
@@ -81,17 +146,26 @@ export interface MemoryResolutionOpts {
      *  persona resolution, which stay on the flat ancestor+profile stack. */
     includeDescendants?: boolean;
 }
-/** The native (non-plugin) store dirs in resolution precedence — node >
- *  project stack > profile > user, builtin excluded as a read-only corpus.
- *  Addresses a store directly when the document itself may be absent, which is
- *  how a DELETED doc's revision log is still found: history outlives the doc,
- *  so its lookup cannot go through document resolution. */
-export declare function nativeMemoryStoresInPrecedence(scope?: MemoryScope, includeDescendants?: boolean): {
-    scope: MemoryScope;
-    memoryDir: string;
-}[];
-/** Canonical, unambiguous identifier for a memory document: `<scope>/<name>`. */
-export declare function memoryDocId(doc: MemoryDoc): string;
+/** A loaded corpus and the exact-identity queries over it. */
+export interface MemoryView {
+    /** Every store the view discovered, mounted or not, in precedence order. */
+    stores: readonly MemoryStoreDescriptor[];
+    /** Every document of every MOUNTED store, in source order — candidates
+     *  included, so a first-wins dedup by name yields the winners. */
+    docs: readonly MemoryDoc[];
+    /** The ordered candidate set for one exact canonical name, or null. */
+    candidates(name: string, opts?: MemoryCandidateOpts): MemoryCandidateSet | null;
+    /** One entry per canonical identity, sorted by name. */
+    candidateSets(opts?: MemoryCandidateOpts): MemoryCandidateSet[];
+    /** The address winner for one exact canonical name; throws not_found. */
+    resolve(name: string, opts?: MemoryCandidateOpts): MemoryDoc;
+}
+export interface MemoryTargetView extends MemoryView {
+    target: MemoryTarget;
+}
+export interface MemoryStoreView extends MemoryView {
+    store: MemoryStoreDescriptor;
+}
 /** Whose memory view is being resolved: the workspace dir, profile, and node
  *  id that decide which stores exist and in what order. Ambient resolution
  *  builds this from the process (`process.cwd()`, `CRTR_PROFILE_ID`,
@@ -110,16 +184,41 @@ export interface MemoryTarget {
      *  or null outside a node. */
     nodeId: string | null;
 }
-/** All native memory docs for a scope. Project scope is a nearest-first stack of
- *  every ancestor `.crouter/memory/` (widened by a selected profile's project
- *  stack); profile is the selected profile's own singleton store, resolved
- *  through `loadProfileManifest`; user and builtin are singleton stores. */
-export declare function listMemoryDocs(scope: MemoryScope, quiet?: boolean): MemoryDoc[];
-/** All of one plugin's substrate docs, mounted under the virtual `<pluginName>/`
- *  namespace. Walks `pluginMemoryDir(plugin)` recursively for *.md, deriving each
- *  doc's name exactly as `listMemoryDocs` does (path-relative, no extension,
- *  slash-separated) then prefixing the plugin name. Builtin has no plugins. */
+/** The exact project store owned by `ownerDir` — the `--dir` selector's store,
+ *  loaded whatever its mount status so lint and migration can inspect a store
+ *  the runtime refuses to mount. */
+export declare function openProjectMemoryStore(ownerDir: string): MemoryStoreDescriptor;
+/** Every store a target sees, in precedence order: node, each project store
+ *  nearest-first (its enabled plugins after it), then profile, user, builtin.
+ *  One real store reached twice contributes once, at its first position. */
+export declare function memoryStoresInPrecedence(target: MemoryTarget, scope?: MemoryScope, includeDescendants?: boolean): MemoryStoreDescriptor[];
+/** The native (non-plugin) MOUNTED store dirs in resolution precedence.
+ *  Addresses a store directly when the document itself may be absent, which is
+ *  how a DELETED doc's revision log is still found: history outlives the doc,
+ *  so its lookup cannot go through document resolution. */
+export declare function nativeMemoryStoresInPrecedence(scope?: MemoryScope, includeDescendants?: boolean): {
+    scope: MemoryScope;
+    memoryDir: string;
+    store: MemoryStoreDescriptor;
+}[];
+/** Every document in one store, sorted by canonical identity. SKILL.md bundles
+ *  are Agent Skills, not memory docs. Enumeration stops at a nested `.crouter/`:
+ *  that is another store's mount point, never this store's content. */
+export declare function loadStoreMemoryDocs(store: MemoryStoreDescriptor, quiet?: boolean): MemoryDoc[];
+/** All of one plugin's substrate docs, mounted under the plugin's own name:
+ *  each doc's store-local name (explicit or path-derived) composes under that
+ *  mount prefix. */
 export declare function listPluginMemoryDocs(plugin: InstalledPlugin, scope: MemoryScope, quiet?: boolean, projectMemory?: ProfileProjectMemory): MemoryDoc[];
+/** Load one target's whole corpus: every mounted store's documents in source
+ *  order. A project store that does not mount is reported once (unless quiet)
+ *  with its migration remedy and contributes nothing. */
+export declare function loadMemoryTargetView(target: MemoryTarget, opts?: MemoryResolutionOpts & {
+    quiet?: boolean;
+}): MemoryTargetView;
+/** Load ONE exact physical store. An undeclared/invalid project store loads
+ *  under the empty namespace so lint and migration can inspect what it holds;
+ *  no target view ever sees those documents. */
+export declare function loadMemoryStoreView(store: MemoryStoreDescriptor, quiet?: boolean): MemoryStoreView;
 /** All project-scoped docs visible from an explicit node workspace/profile — the
  *  project-only slice of a `MemoryTarget` view, used where only workspace docs
  *  are wanted (a workspace-open render). For a full-precedence target-addressed
@@ -128,31 +227,22 @@ export declare function listProjectMemoryDocs(startDir?: string, profileId?: str
 /** All memory docs across the resolved sources, in precedence order: each
  *  ancestor project `.crouter/` from nearest to farthest, then the selected
  *  profile's memory (if any), then user, then builtin. Within each source,
- *  native docs are emitted before enabled-plugin docs, so native wins on the
- *  caller's first-wins dedup. */
+ *  native docs are emitted before enabled-plugin docs, and equal-canonical
+ *  candidates stay in source order, so a caller's first-wins dedup yields the
+ *  address winners. */
 export declare function listAllMemoryDocs(scope?: MemoryScope, quiet?: boolean, includeDescendants?: boolean): MemoryDoc[];
-/** Resolve a document NAME against a `.history` tree, which mirrors the doc
- *  tree segment for segment with `.jsonl` in place of `.md`. Reuses the doc
- *  resolution rules so a log outlives its doc under the same name the doc had:
- *  numeric prefixes stay prefix-blind (`00-topic.md` logged at
- *  `.history/00-topic.jsonl` still answers to `topic`). Returns null when
- *  nothing resolves. */
-export declare function resolveHistoryLogPath(historyDir: string, segments: string[]): string | null;
 export interface MemoryDocSnapshot {
     /** Every document in default scope precedence order, loaded once. */
     docs: readonly MemoryDoc[];
     /** Resolve names against that source snapshot; failures are omitted so
      * callers can retain their own per-document error behavior. */
     resolve(names: readonly string[]): Map<string, MemoryDoc>;
-    /** Frozen pre-cut resolution used only by the surfaces migration: return the
-     * explicit INDEX spelling when a bare directory/plugin ref and that spelling
-     * resolve to the same file in this target corpus. */
-    legacyDirectoryIndex(name: string): string | null;
 }
 export declare function createMemoryDocSnapshot(target?: MemoryTarget): MemoryDocSnapshot;
-/** Resolve several unqualified names over one memory-source snapshot. Failed
+/** Resolve several canonical names over one memory-source snapshot. Failed
  * names are omitted so callers can preserve their per-document error behavior. */
 export declare function resolveMemoryDocs(names: readonly string[]): Map<string, MemoryDoc>;
+/** The address winner for an exact canonical name in the ambient target. */
 export declare function resolveMemoryDoc(rawName: string, opts?: MemoryResolutionOpts): MemoryDoc;
 /** Resolve a memory document as ANOTHER node would see it — the same precedence
  *  chain (node-local > project stack > profile > user > builtin), read from the
@@ -160,3 +250,16 @@ export declare function resolveMemoryDoc(rawName: string, opts?: MemoryResolutio
  *  resolves a `[[name]]` link through: the daemon's own cwd and env name no
  *  node, and the same name can be a different document for two nodes. */
 export declare function resolveMemoryDocForTarget(rawName: string, target: MemoryTarget, opts?: MemoryResolutionOpts): MemoryDoc;
+/** Every physical candidate for an exact canonical name in the ambient target,
+ *  in source order — what path-aware inventory, diagnostics, and automatic
+ *  event eligibility consume instead of the winner alone. */
+export declare function resolveMemoryCandidates(rawName: string, opts?: MemoryResolutionOpts): MemoryCandidateSet;
+export declare function resolveMemoryCandidatesForTarget(rawName: string, target: MemoryTarget, opts?: MemoryResolutionOpts): MemoryCandidateSet;
+/** The address winner for an exact canonical name inside ONE project store —
+ *  the `--dir` selector's resolution. The query is still the full canonical
+ *  name, including that store's namespace. */
+export declare function resolveMemoryDocInStore(rawName: string, store: MemoryStoreDescriptor, opts?: MemoryCandidateOpts): MemoryDoc;
+/** Resolve PHYSICAL path segments against a `.history` tree, which mirrors the
+ *  doc tree segment for segment with `.jsonl` in place of `.md`. A log outlives
+ *  its document, so this lookup cannot go through document resolution. */
+export declare function resolveHistoryLogPath(historyDir: string, segments: string[]): string | null;