@crouton-kit/crouter 0.3.49 → 0.3.50

package/dist/core/substrate/render.js

@@ -54,7 +54,7 @@ import { parseFrontmatterGeneric } from '../frontmatter.js';
 import { pathExists, readText, walkFiles } from '../fs-utils.js';
 import { memoryDir } from '../runtime/memory.js';
 import { projectScopeRoots } from '../scope.js';
-import { assembleNodeSubject, buildCeilingIndex, effectiveRung, gatePasses, indexDirOf, isIndexName, normalizeDocName, parseSubstrateDoc, parseSubstrateFrontmatter, previewLine, rungRank, } from './index.js';
+import { assembleNodeSubject, buildCeilingIndex, effectiveRung, gatePasses, indexDirOf, isIndexName, normalizeDocName, parseSubstrateDoc, parseSubstrateFrontmatter, previewLine, resolveDocName, rungRank, } from './index.js';
 import { cachedNodeSubject, cachedSubstrateDocs } from './session-cache.js';
 // ---------------------------------------------------------------------------
 // Step 1 — winner selection (ceiling + gate + first-wins dedup).
@@ -209,14 +209,18 @@ function nodeLocalDocs(nodeId, subject) {
     const out = [];
     for (const file of walkFiles(dir, (n) => n.endsWith('.md'))) {
         const raw = relative(dir, file).replace(/\.md$/i, '').split(sep).join('/');
-        const name = normalizeDocName(raw);
-        if (!name)
+        const fallbackName = normalizeDocName(raw);
+        if (!fallbackName)
             continue;
         try {
             const { data, body } = parseFrontmatterGeneric(readText(file));
             const schema = parseSubstrateFrontmatter(data);
             if (schema === null)
                 continue;
+            // ONE substrate-identity rule (schema.ts's resolveDocName), shared with
+            // the resolver and the on-read positional loader: explicit frontmatter
+            // `name` wins over the physical-path-derived fallback.
+            const name = resolveDocName(data, fallbackName);
             // node-local is NOT a resolver scope; `scope` is a placeholder never read
             // by gate eval (keyed off the NODE subject, not the doc) nor by the
             // renderers (keyed off name / body / rung).

package/dist/core/substrate/schema.d.ts

@@ -20,6 +20,10 @@ export declare function normalizeNameSegment(segment: string): string;
  *  `spine/has-manager`. This is the identity a doc displays, dedups, and
  *  resolves under — distinct from its physical path, which keeps the prefix. */
 export declare function normalizeDocName(name: string): string;
+/** Resolve a doc's identity from its raw frontmatter record: an explicit
+ *  `name` field wins (trimmed + normalized), else `fallbackName` (the
+ *  normalized path-derived name). */
+export declare function resolveDocName(fm: Record<string, unknown> | null | undefined, fallbackName: string): string;
 /** A gate predicate tree, evaluated by predicate.ts (`evalCondition`) against
  *  the node-config subject. Typed loosely on purpose — the matcher engine owns
  *  validation; structurally it is a field→matcher map with optional
@@ -75,10 +79,12 @@ export interface SubstrateSchema {
     rationale?: string;
 }
 /** A fully-resolved substrate document: the parsed schema PLUS the resolver's
- *  path-derived identity and body. This single object flows through the whole
+ *  identity (explicit frontmatter `name` when present, otherwise the normalized
+ *  path-derived fallback) and body. This single object flows through the whole
  *  pipeline (gate eval → boot/on-read render), so a renderer never re-parses. */
 export interface SubstrateDoc extends SubstrateSchema {
-    /** Path-derived identity, e.g. `taste/document-substrate` (resolver-supplied). */
+    /** Resolver-supplied identity, e.g. `taste/document-substrate` or an explicit
+     *  frontmatter name when one is present. */
     name: string;
     /** The scope this doc resolved from. */
     scope: MemoryScope;

package/dist/core/substrate/schema.js

@@ -51,8 +51,9 @@ export const FALLBACK_RUNG = 'none';
 // prefix is NEVER part of the doc's identity: every identity-facing surface —
 // MemoryDoc.name, direct lookup, leaf fallback, `crtr memory read`/`list`,
 // prompt render, on-read display — derives from the NORMALIZED segments, so
-// `00-runtime-base` displays/dedups/resolves as `runtime-base`. Only the
-// physical path keeps the prefix.
+// `00-runtime-base` displays/dedups/resolves as `runtime-base`. When a doc
+// sets an explicit frontmatter `name`, that normalized name wins instead of
+// the path-derived fallback. Only the physical path keeps the prefix.
 // ---------------------------------------------------------------------------
 const NUMERIC_PREFIX_RE = /^\d{2}-/;
 /** Strip an optional `NN-` ordering prefix from ONE path segment (file or
@@ -69,6 +70,22 @@ export function normalizeDocName(name) {
     return name.split('/').map(normalizeNameSegment).join('/');
 }
 // ---------------------------------------------------------------------------
+// Substrate identity — the ONE explicit-name-then-path-fallback rule. A doc's
+// resolver identity is its explicit frontmatter `name` when present (normalized),
+// otherwise the caller-supplied path-derived fallback. Every loader that turns a
+// physical .md file into a named doc (the resolver's `listMemoryDocsInDir`, the
+// on-read positional loader) calls this ONE helper, so a doc's identity never
+// depends on which path loaded it.
+// ---------------------------------------------------------------------------
+/** Resolve a doc's identity from its raw frontmatter record: an explicit
+ *  `name` field wins (trimmed + normalized), else `fallbackName` (the
+ *  normalized path-derived name). */
+export function resolveDocName(fm, fallbackName) {
+    const raw = fm?.['name'];
+    const explicit = typeof raw === 'string' && raw.trim() !== '' ? normalizeDocName(raw.trim()) : '';
+    return explicit !== '' ? explicit : fallbackName;
+}
+// ---------------------------------------------------------------------------
 // Parse / validate.
 // ---------------------------------------------------------------------------
 /** Parse a raw frontmatter record (from `parseFrontmatterGeneric`, via the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crouton-kit/crouter",
-  "version": "0.3.49",
+  "version": "0.3.50",
   "description": "crtr — agent runtime with memory, plugins, and marketplaces",
   "type": "module",
   "main": "dist/index.js",
@@ -33,7 +33,7 @@
     "prebuild": "rm -rf node_modules/@earendil-works/pi-coding-agent/node_modules/@earendil-works/pi-tui node_modules/@earendil-works/pi-coding-agent/node_modules/@earendil-works/pi-ai node_modules/@earendil-works/pi-coding-agent/node_modules/@earendil-works/pi-agent-core",
     "build": "rm -rf dist && tsc && cp -R src/builtin-views dist/builtin-views && cp -R src/builtin-memory dist/builtin-memory && cp -R src/builtin-pi-packages dist/builtin-pi-packages && npm run build:attach && vite build --config src/clients/web/web-client/vite.config.ts",
     "lint:web-px": "node scripts/lint-web-px.mjs",
-    "build:attach": "esbuild src/clients/attach/attach-cmd.ts --bundle --minify --format=esm --platform=node --target=node22 --alias:@earendil-works/pi-tui=$PWD/node_modules/@earendil-works/pi-tui --outfile=dist/clients/attach/attach-cmd.js --log-level=warning --banner:js=\"import{createRequire as __cr}from'node:module';const require=__cr(import.meta.url);\"",
+    "build:attach": "esbuild src/clients/attach/attach-cmd.ts --bundle --minify --format=esm --platform=node --target=node22 --alias:@earendil-works/pi-tui=$PWD/node_modules/@earendil-works/pi-tui --external:@crouton-kit/humanloop --outfile=dist/clients/attach/attach-cmd.js --log-level=warning --banner:js=\"import{createRequire as __cr}from'node:module';const require=__cr(import.meta.url);\"",
     "postinstall": "node scripts/postinstall.mjs",
     "dev": "tsx src/cli.ts",
     "link": "npm link",
@@ -47,7 +47,7 @@
   },
   "license": "MIT",
   "dependencies": {
-    "@crouton-kit/humanloop": "^0.3.27",
+    "@crouton-kit/humanloop": "^0.3.29",
     "@earendil-works/pi-agent-core": "0.80.2",
     "@earendil-works/pi-ai": "0.80.3",
     "@earendil-works/pi-coding-agent": "0.80.2",