@north-light/crouter 0.3.227 → 0.3.229

package/dist/core/memory/identity.js

@@ -0,0 +1,185 @@
+// identity.ts — the ONE memory-identity rule. Every loader, placement helper,
+// linter, and migration derives names here rather than reproducing string
+// arithmetic: a document has a store-local name, its store declares a namespace
+// (a project's declaration, an installed plugin's mount prefix, or empty), and
+// its canonical name — the only address resolution accepts — is namespace ⊕
+// local. Pure and side-effect free.
+// ---------------------------------------------------------------------------
+// Segment normalization — the optional `NN-` ordering pin. A physical path may
+// carry a two-digit prefix on any segment (`00-runtime-base/`, `01-spine/`)
+// purely to pin structural order against natural sort. The prefix is NEVER part
+// of identity: only the physical path keeps it.
+// ---------------------------------------------------------------------------
+const NUMERIC_PREFIX_RE = /^\d{2}-/;
+const SEGMENT_RE = /^[A-Za-z0-9._-]+$/;
+/** The filename (and path segment) whose document fronts its directory. */
+export const INDEX_SEGMENT = 'INDEX';
+/** Strip an optional `NN-` ordering prefix from ONE segment. */
+export function normalizeNameSegment(segment) {
+    return segment.replace(NUMERIC_PREFIX_RE, '');
+}
+/** Slugify one authored or filesystem label into a canonical segment. */
+export function slugCanonicalSegment(raw) {
+    return normalizeNameSegment(raw.trim().toLowerCase().replace(/[^a-z0-9._-]+/g, '-').replace(/^-+|-+$/g, ''));
+}
+/** Slugify a derived label into canonical path segments. Empty segments are
+ * intentionally dropped; owner paths use slugCanonicalSegment directly. */
+export function slugCanonicalPath(raw) {
+    return raw
+        .replace(/\\/g, '/')
+        .replace(/\.md$/i, '')
+        .split('/')
+        .map(slugCanonicalSegment)
+        .filter(Boolean)
+        .join('/');
+}
+/** Strip the ordering prefix from EVERY segment of a slash-separated name:
+ *  `01-spine/00-has-manager` -> `spine/has-manager`. */
+export function normalizeDocName(name) {
+    return name.split('/').map(normalizeNameSegment).join('/');
+}
+/** Split a name into segments, dropping empties from `//`, a leading `/`, or an
+ *  empty name. */
+export function canonicalSegments(name) {
+    return name.split('/').filter((s) => s !== '');
+}
+/** The canonical directory containing `name`, or `''` at the top. */
+export function canonicalParent(name) {
+    const segments = canonicalSegments(name);
+    return segments.slice(0, -1).join('/');
+}
+/** Remove EXACTLY ONE trailing `INDEX` segment. `a/INDEX` -> `a`; `INDEX` ->
+ *  `''` (a store root); `a/INDEX/INDEX` -> `a/INDEX` (the inner segment is an
+ *  ordinary directory name). */
+export function collapseTrailingIndex(name) {
+    const segments = canonicalSegments(name);
+    if (segments[segments.length - 1] === INDEX_SEGMENT)
+        segments.pop();
+    return segments.join('/');
+}
+/** Normalized identity segments of a store-relative markdown path, extension
+ *  stripped. */
+function pathIdentitySegments(physicalRelativePath) {
+    return canonicalSegments(physicalRelativePath.replace(/\\/g, '/').replace(/\.md$/i, '')).map(normalizeNameSegment);
+}
+/** Which form a store-relative markdown path takes. */
+export function representationForPath(physicalRelativePath) {
+    const segments = pathIdentitySegments(physicalRelativePath);
+    return segments[segments.length - 1] === INDEX_SEGMENT ? 'directory-index' : 'leaf-file';
+}
+/** Store-local name derived from a store-relative markdown path: ordering
+ *  prefixes stripped from every segment and one trailing `INDEX` collapsed.
+ *  Empty only for a store root `INDEX.md`. */
+export function localNameFromPath(physicalRelativePath) {
+    return collapseTrailingIndex(pathIdentitySegments(physicalRelativePath).join('/'));
+}
+/** The store-relative markdown path a local name occupies in a given form.
+ *  Both forms are checked before any create or move, so occupancy never depends
+ *  on which one a store happens to use. */
+export function physicalRelativePathFor(localName, representation) {
+    const local = canonicalSegments(localName).join('/');
+    if (local === '') {
+        if (representation === 'leaf-file')
+            throw new Error('a store root document has no leaf-file representation');
+        return `${INDEX_SEGMENT}.md`;
+    }
+    return representation === 'directory-index' ? `${local}/${INDEX_SEGMENT}.md` : `${local}.md`;
+}
+// ---------------------------------------------------------------------------
+// Local name and canonical composition.
+// ---------------------------------------------------------------------------
+/** A document's explicit frontmatter `name` as a local name — normalized with
+ *  one trailing `INDEX` collapsed — or `null` when it carries none. */
+export function explicitLocalName(fm) {
+    const raw = fm?.['name'];
+    if (typeof raw !== 'string' || raw.trim() === '')
+        return null;
+    return collapseTrailingIndex(normalizeDocName(raw.trim()));
+}
+/** A document's store-local name: its explicit frontmatter `name` when present,
+ *  else the path-derived local name. Explicit names are local to their store —
+ *  they never carry the store's namespace. */
+export function resolveLocalName(fm, pathDerivedLocalName) {
+    return explicitLocalName(fm) ?? pathDerivedLocalName;
+}
+/** namespace ⊕ local — the only address. Composition is unconditional: a local
+ *  name that already looks namespace-prefixed is composed anyway, so identity
+ *  never depends on string coincidence. An empty result means a namespace-less
+ *  store root, which has no valid canonical identity. */
+export function composeCanonicalName(namespace, localName) {
+    const ns = canonicalSegments(namespace).join('/');
+    const local = canonicalSegments(localName).join('/');
+    if (ns === '')
+        return local;
+    return local === '' ? ns : `${ns}/${local}`;
+}
+/** The canonical directory a document's `./` memory-read entries match against:
+ *  a directory document anchors at its own name, an ordinary leaf at its
+ *  canonical parent. */
+export function routingAnchorFor(canonicalName, representation) {
+    return representation === 'directory-index' ? canonicalSegments(canonicalName).join('/') : canonicalParent(canonicalName);
+}
+/** The local name a canonical name has inside `namespace`, or `null` when it
+ *  falls outside it. Exact on segment boundaries: `a/bc` is not inside `a/b`.
+ *  The namespace itself yields `''` — the store root document. */
+export function stripNamespace(canonicalName, namespace) {
+    const name = canonicalSegments(canonicalName);
+    const ns = canonicalSegments(namespace);
+    for (let i = 0; i < ns.length; i++) {
+        if (name[i] !== ns[i])
+            return null;
+    }
+    return name.slice(ns.length).join('/');
+}
+function invalidSegmentReason(name) {
+    for (const segment of name.split('/')) {
+        if (segment === '')
+            return `empty segment in \`${name}\``;
+        if (segment === '.' || segment === '..')
+            return `relative segment \`${segment}\` in \`${name}\``;
+        if (!SEGMENT_RE.test(segment))
+            return `segment \`${segment}\` is not [A-Za-z0-9._-]`;
+        if (NUMERIC_PREFIX_RE.test(segment)) {
+            return `segment \`${segment}\` carries an \`NN-\` ordering prefix, which is physical-path-only — use \`${normalizeNameSegment(segment)}\``;
+        }
+    }
+    return null;
+}
+/** A project store's declared namespace, or an installed plugin's mount prefix:
+ *  one or more normalized segments, never ending in `INDEX`. */
+export function validateNamespace(namespace) {
+    if (namespace.trim() !== namespace)
+        return { ok: false, reason: 'namespace has surrounding whitespace' };
+    if (namespace === '')
+        return { ok: false, reason: 'namespace is empty' };
+    const badSegment = invalidSegmentReason(namespace);
+    if (badSegment !== null)
+        return { ok: false, reason: badSegment };
+    if (canonicalSegments(namespace).pop() === INDEX_SEGMENT) {
+        return { ok: false, reason: `namespace ends in \`${INDEX_SEGMENT}\`` };
+    }
+    return { ok: true };
+}
+/** An explicit non-root `name:`: a non-empty local name, never ending in
+ *  `INDEX` (its directory name is the identity) and never carrying its own
+ *  store's namespace. */
+export function validateExplicitLocalName(localName, namespace = '') {
+    if (localName.trim() !== localName)
+        return { ok: false, reason: 'name has surrounding whitespace' };
+    if (localName === '')
+        return { ok: false, reason: 'name is empty' };
+    const badSegment = invalidSegmentReason(localName);
+    if (badSegment !== null)
+        return { ok: false, reason: badSegment };
+    if (canonicalSegments(localName).pop() === INDEX_SEGMENT) {
+        const collapsed = collapseTrailingIndex(localName);
+        return {
+            ok: false,
+            reason: `name ends in \`${INDEX_SEGMENT}\` — a directory document answers at its directory name${collapsed === '' ? '' : `, so use \`${collapsed}\``}`,
+        };
+    }
+    if (namespace !== '' && stripNamespace(localName, namespace) !== null) {
+        return { ok: false, reason: `name repeats its store's namespace \`${namespace}\` — explicit names are store-local` };
+    }
+    return { ok: true };
+}

package/dist/core/memory/inline-ref-guidance.d.ts

@@ -1,5 +1,5 @@
 /**
- * Resolve every slash token in `text` against `names` (a
+ * Resolve every slash token in `text` against `names` (the exact canonical
  * `buildRefInventory().names` set), collapse duplicates, and return one
  * directive line per distinct resolved ref in FIRST-APPEARANCE order.
  * Returns `null` when no token resolves, so the broker sends no guidance

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

@@ -11,7 +11,7 @@
 import { findRefTokens } from './inline-ref-grammar.js';
 const GUIDANCE_HEADER = 'The user explicitly called out specific memories. Read the relevant mentioned memory files:';
 /**
- * Resolve every slash token in `text` against `names` (a
+ * Resolve every slash token in `text` against `names` (the exact canonical
  * `buildRefInventory().names` set), collapse duplicates, and return one
  * directive line per distinct resolved ref in FIRST-APPEARANCE order.
  * Returns `null` when no token resolves, so the broker sends no guidance

package/dist/core/memory/inline-ref-inventory.d.ts

@@ -1,14 +1,7 @@
 import type { RefMeta } from '../runtime/broker-protocol.js';
-/**
- * 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 declare function buildRefInventory(): {
     refs: RefMeta[];
     names: Set<string>;

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;