@north-light/crouter 0.3.226 → 0.3.228

package/dist/core/memory/inline-ref-inventory.js

@@ -1,41 +1,13 @@
-// inline-ref-inventory.ts — the authoritative, broker-side inventory of
-// referenceable memory documents for inline memory references (design:
-// inline memory references, D2). Built from the SAME resolver + parse path
-// as every other memory surface (`listAllMemoryDocs` + `parseSubstrateDoc`,
-// via the session parse cache), reused verbatim rather than re-walked or
-// shelled out.
-//
-// This is deliberately NOT `crtr memory list`'s inventory:
-//   • listAllMemoryDocs() is called with NO scope arg, so inside a running
-//     node (CRTR_NODE_ID set) the corpus already includes node > project
-//     stack > profile > user > builtin, nearest first.
-//   • Dedup is first-wins by NAME alone (not `scope/name`) — a slash token
-//     maps to exactly one `crtr memory read <name>`, so two same-named docs
-//     at different scopes must collapse to one inventory row, and the
-//     winning (nearest) doc supplies the display fields.
-//   • No gate / visibility-rung / `slash` filtering. Referenceability is
-//     "resolves in this node's corpus," full stop — gates/rungs govern
-//     automatic boot/on-read surfacing only (spec §7.1), and `slash` governs
-//     command registration only (spec §4.3). An explicit human reference
-//     outranks both.
-//   • Directory names are referenceable too: a bare-dir `[[ref]]` opens the
-//     directory's listing through `crtr memory read <dir>`, so every proper
-//     name-prefix of a winning doc joins the resolution set — resolution
-//     only, never a display row.
-//   • A malformed doc (no valid `kind`) is already dropped by
-//     `parseSubstrateDoc` returning null, so it never reaches the winners map.
-//
-// `buildRefInventory` is called fresh per read-op / per submission by the
-// broker (src/core/runtime/broker.ts), which memoizes it and rebuilds on
-// `/reload` — this module itself holds no cache beyond the session parse
-// cache it reads through.
-import { listAllMemoryDocs } from '../memory-resolver.js';
+// Authoritative broker-side inventory for inline memory references. It uses one
+// target view, exact canonical winners, and the canonical tree for directory
+// browse names; gates, rungs, and slash flags do not affect referenceability.
+import { loadMemoryTargetView } from '../memory-resolver.js';
+import { buildMemoryTree } from './tree.js';
 import { memoryExtensionEffectiveCatalog, projectEffectiveMemoryExtensions } from './extensions.js';
 import { parseSubstrateDoc } from '../substrate/schema.js';
-import { cachedAllMemoryDocsInclusive, cachedSubstrateDocsInclusive } from '../substrate/session-cache.js';
 // Display-sort weight matching resolution precedence (node > project >
-// profile > user > builtin) — display-only; resolution itself is
-// name-only (`names.has(candidate)`), never scope-aware.
+// profile > user > builtin) — display-only; resolution itself is exact
+// canonical-name membership (`names.has(candidate)`).
 const SCOPE_SORT_RANK = {
     node: 0,
     project: 1,
@@ -43,28 +15,22 @@ const SCOPE_SORT_RANK = {
     user: 3,
     builtin: 4,
 };
-/**
- * Build the inline memory-reference inventory: every referenceable document
- * in this node's corpus, precedence-deduped first-wins by canonical name,
- * both kinds, no gate/rung/`slash` filtering. Returns display metadata
- * (`refs`, stably sorted by winning scope then name) plus the resolution set
- * (`names` — doc names plus every proper directory prefix, because a bare-dir
- * ref is a legal listing link) that both the broker's per-submission resolver
- * and `buildGuidance` test tokens against. `refs` additionally labels Gateway
- * eligibility; the terminal viewer still receives every referenceable row.
- */
+/** Build the inline inventory from exact target-view winners. `refs` carries
+ * metadata rows; `names` adds only canonical directory nodes with members for
+ * browse links. Gates, rungs, and `slash` do not affect referenceability. */
 export function buildRefInventory() {
-    const memoryDocs = cachedAllMemoryDocsInclusive(listAllMemoryDocs);
-    const substrateDocs = cachedSubstrateDocsInclusive(listAllMemoryDocs, parseSubstrateDoc);
-    const substrateDocsByPath = new Map(substrateDocs.map((doc) => [doc.path, doc]));
-    // First-wins by canonical name: docs arrive already in precedence order
-    // (listAllMemoryDocs' nearest-first source ordering), so the first doc seen
-    // for a name is the winner.
+    const target = {
+        cwd: process.cwd(),
+        profileId: process.env['CRTR_PROFILE_ID'] || null,
+        nodeId: process.env['CRTR_NODE_ID'] || null,
+    };
+    const view = loadMemoryTargetView(target, { quiet: true });
     const winners = new Map();
-    for (const memoryDoc of memoryDocs) {
-        const doc = substrateDocsByPath.get(memoryDoc.path);
-        if (doc !== undefined && !winners.has(doc.name))
-            winners.set(doc.name, { doc, memoryDoc });
+    for (const candidateSet of view.candidateSets()) {
+        const memoryDoc = candidateSet.winner;
+        const doc = parseSubstrateDoc(memoryDoc);
+        if (doc !== null)
+            winners.set(candidateSet.name, { doc, memoryDoc });
     }
     const refs = [];
     for (const [name, { doc, memoryDoc }] of winners) {
@@ -79,12 +45,14 @@ export function buildRefInventory() {
         return a.name.localeCompare(b.name);
     });
     const names = new Set(refs.map((r) => r.name));
-    // Directory names resolve as listing links, so they join the set — but not
-    // the display rows: a dir has no kind/short-form to show.
-    for (const name of winners.keys()) {
-        const segs = name.split('/');
-        for (let i = 1; i < segs.length; i++)
-            names.add(segs.slice(0, i).join('/'));
-    }
+    const tree = buildMemoryTree([...winners.values()].map(({ memoryDoc }) => memoryDoc));
+    const addDirectoryNames = (node) => {
+        if (node.name !== '' && (node.childDirectories.length > 0 || node.childDocuments.length > 0)) {
+            names.add(node.name);
+        }
+        for (const child of node.childDirectories)
+            addDirectoryNames(child);
+    };
+    addDirectoryNames(tree.root);
     return { refs, names };
 }

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

@@ -0,0 +1,129 @@
+import { type MemoryDoc, type MemoryScope, type MemoryStoreDescriptor, type MemoryTarget } from '../memory-resolver.js';
+export type MemoryLintSeverity = 'error' | 'warning' | 'notice';
+export type MemoryLintRule = 
+/** Frontmatter does not parse as YAML. */
+'yaml'
+/** Substrate frontmatter contract violation. */
+ | 'schema'
+/** A plugin-declared `extensions` value is invalid. */
+ | 'extension'
+/** Body longer than its delivery entries earn. */
+ | 'length'
+/** A body short enough to inline still pays a routing line. */
+ | 'short-preview'
+/** A `memory-read` glob that fires on every memory read. */
+ | 'broad-memory-read'
+/** A project store the runtime refuses to mount: no/invalid repository-root `namespace:`. */
+ | 'store-namespace'
+/** `namespace:` declared anywhere but the repository-root store's root INDEX.md. */
+ | 'namespace-placement'
+/** Two owner directories in one repository normalize to one effective prefix. */
+ | 'owner-path-collision'
+/** `name:` on a store's root INDEX.md, whose identity is the namespace. */
+ | 'root-name'
+/** A root INDEX.md in a store that declares no namespace — no address. */
+ | 'root-index-unaddressable'
+/** An explicit non-root `name:` that is not a valid store-local name. */
+ | 'local-name'
+/** Two files in ONE store owning the same canonical identity. */
+ | 'canonical-collision'
+/** One canonical identity held by several stores (inspection data). */
+ | 'cross-store-candidates'
+/** A `[[link]]` that resolves to no document or directory. */
+ | 'dangling-link'
+/** A `memory-read` route that matches no canonical name. */
+ | 'memory-read-route'
+/** A project store's workspace front door is missing or not its root doc. */
+ | 'front-door'
+/** Boot entries in a nested store, which never rides the boot catalog. */
+ | 'nested-store-boot'
+/** Reference checks skipped because the store's identities are undetermined. */
+ | 'reference-check-deferred';
+/** 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 declare const MEMORY_LINT_IDENTITY_RULES: ReadonlySet<MemoryLintRule>;
+export interface MemoryLintFinding {
+    severity: MemoryLintSeverity;
+    rule: MemoryLintRule;
+    /** The markdown file, store root, or project directory at fault. */
+    path: string;
+    message: string;
+    scope?: MemoryScope;
+    storeRoot?: string;
+    /** The canonical identity the finding is about, when it has one. */
+    name?: string;
+    /** Every physical path sharing a collided identity, read winner first. */
+    paths?: readonly string[];
+}
+export interface MemoryLintResult {
+    /** No `error` findings. */
+    ok: boolean;
+    /** Markdown files examined, including non-document files (`SKILL.md`,
+     *  `MEMORY.md`) that are YAML-checked but never loaded as documents. */
+    checked: number;
+    /** Of `checked`, the files the substrate actually loads as memory
+     *  documents — `checked` minus `SKILL.md`/`MEMORY.md`. */
+    documents: number;
+    storesLinted: number;
+    /** Every finding, in emission order. */
+    findings: readonly MemoryLintFinding[];
+    errors: readonly MemoryLintFinding[];
+    warnings: readonly MemoryLintFinding[];
+    notices: readonly MemoryLintFinding[];
+}
+export interface MemoryLintTargetResult extends MemoryLintResult {
+    /** Every store the target saw, mounted or not, in precedence order. */
+    stores: readonly MemoryStoreDescriptor[];
+    /** Projects the selected profile manages that were checked for a workspace
+     *  front door — zero under a scope filter that excludes project stores. */
+    profileProjects: number;
+}
+/** 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 declare function lintBodyLength(fm: Record<string, unknown>, body: string, docName: string): string | null;
+/** Warn when a body short enough to inline still pays a routing line. */
+export declare function lintShortPreviewBody(fm: Record<string, unknown>, body: string): string | null;
+/** 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 declare function resolvableCanonicalNames(docs: readonly MemoryDoc[]): Set<string>;
+export interface MemoryLintStoreOptions {
+    /** Canonical names a `[[link]]` or route may target — the target view the
+     *  store's documents are read in. Omit to skip reference checks entirely
+     *  (a store linted in isolation, such as the builtin corpus at build time,
+     *  passes only its own names). */
+    resolvable?: ReadonlySet<string>;
+    /** Whether a project store must carry a workspace front door: `required` for
+     *  a profile-managed project, `advisory` (warning) for an unmanaged one that
+     *  was asked about directly, `ignore` otherwise. A front door on any doc but
+     *  the store root is an error under every mode. */
+    frontDoor?: 'required' | 'advisory' | 'ignore';
+    /** A store discovered BELOW the mounted project roots: the boot catalog never
+     *  includes one, so its boot entries are inert. */
+    nestedStore?: boolean;
+}
+/** 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 declare function lintMemoryStore(store: MemoryStoreDescriptor, options?: MemoryLintStoreOptions): MemoryLintResult;
+export interface MemoryLintTargetOptions {
+    /** Whose view to lint. Default: the ambient process (cwd + CRTR_PROFILE_ID +
+     *  CRTR_NODE_ID). */
+    target?: MemoryTarget;
+    /** Restrict to one source class. Front-door coverage applies only to an
+     *  unfiltered or project-scoped view. */
+    scope?: MemoryScope;
+    /** Also lint `.crouter/memory` stores discovered below the mounted project
+     *  roots. Default true: they are addressable, so they are lintable. */
+    includeDescendants?: boolean;
+}
+/** 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 declare function lintMemoryTarget(options?: MemoryLintTargetOptions): MemoryLintTargetResult;