@north-light/crouter 0.3.208 → 0.3.210

package/dist/core/substrate/on-read.js

@@ -1,45 +1,41 @@
-// on-read.ts — the pure file-context delivery functions for the document
-// substrate. Both take a caller-supplied subject; the canvas-db wrappers that
-// resolve one from a node id live in on-read-node.ts, so a consumer that
-// already holds a subject imports this module WITHOUT pulling subject.js's
-// canvas-db reach (the same split as render.ts / render-node.ts).
+// on-read.ts — the pure event-delivery renderers for the document substrate.
+// Each takes a caller-supplied subject; the canvas-db wrappers that resolve
+// one from a node id live in on-read-node.ts, so a consumer that already
+// holds a subject imports this module WITHOUT pulling subject.js's canvas-db
+// reach (the same split as render.ts / render-node.ts).
 //
-// A memory with file-read visibility participates only through an explicit
-// `applies-to` path glob (authoring lint requires one). Two events use that one
-// routing mechanism:
+// A doc participates through its `surfaces` entries (surface-match.ts owns
+// the per-entry matchers; this module folds them per doc and renders):
 //
-//   • A successful `read` tool call evaluates the read file against every
-//     visible substrate doc. Project stores encountered between that file and
-//     the filesystem root join the resolved cwd/profile corpus, so a nested
-//     workspace can contribute guidance exactly when a file beneath it is read.
-//     On this event the reserved `applies-to: "."` target means "the read file
-//     is under the doc's store's owning directory" — a nested store's front
-//     door surfaces on the first read beneath it, delivery driven purely by
-//     filesystem truth.
-//   • Opening a workspace evaluates the reserved `applies-to: "."` target for
-//     every project store mounted by the cwd and selected profile. This happens
-//     while the first-message bearings are assembled, so workspace-wide context
-//     arrives before the task rather than waiting for an arbitrary first file.
-//     Both hooks share one transcript-scoped dedup set, so a doc delivered at
-//     workspace open never re-delivers on a later matching read.
+//   • `read` — a successful read tool call evaluates the read file against
+//     every doc's `read` entries: path globs vs the absolute path and
+//     basename, `./`-anchored globs vs the path relative to the doc's store's
+//     owning repo dir (project stores only), `match-frontmatter` vs the read
+//     file's own YAML. Project stores encountered between the file and the
+//     filesystem root join the resolved cwd/profile corpus, so a nested
+//     workspace contributes guidance exactly when a file beneath it is read.
+//   • `workspace-open` — opening a workspace delivers docs carrying a
+//     `workspace-open` entry from every project store mounted by the cwd and
+//     selected profile, while the first-message bearings are assembled — so
+//     workspace-wide context arrives before the task rather than waiting for
+//     an arbitrary first file.
+//   • `command` — a `bash` tool call evaluates the executed command string
+//     against every doc's `command` entries (string globs, `*` crossing `/`).
 //
-// `read-when` remains an additional OR trigger over a read markdown file's own
-// frontmatter. It does not replace `applies-to`: every non-none file-read rung
-// still declares its path boundary explicitly.
-//
-// Every candidate renders at its own fileReadVisibility rung. Explicit routing
-// is the whole on-read model, so directory INDEX ceilings remain a boot-catalog
-// concern and do not cap a deliberately matched document.
+// All channels share one transcript-scoped (realpath → rung rank) dedup set,
+// so a doc delivered by one never re-delivers at the same or lower rung
+// through another. Each candidate renders at its matched rung — the highest
+// `at` over its matching entries for the event.
 import { homedir } from 'node:os';
-import { basename, dirname, isAbsolute, matchesGlob, parse, relative, sep } from 'node:path';
+import { dirname, parse, relative, sep } from 'node:path';
 import { CRTR_DIR_NAME } from '../../types.js';
 import { pathExists, readText, walkFiles } from '../fs-utils.js';
 import { parseFrontmatterGeneric } from '../frontmatter.js';
-import { evalCondition } from '../predicate.js';
 import { listAllMemoryDocs, listProjectMemoryDocs } from '../memory-resolver.js';
 import { userScopeRoot } from '../scope.js';
-import { displayName } from './ceiling.js';
 import { gatePasses } from './gate.js';
+import { commandDeliveryRung, memoryReadDeliveryRung, owningRootOf, readDeliveryRung, workspaceOpenRung } from './surface-match.js';
+import { deliveredAtOrAbove, recordDelivery } from './injected-store.js';
 import { normalizeDocName, parseSubstrateDoc, parseSubstrateFrontmatter, previewLine, resolveDocName } from './schema.js';
 import { cachedSubstrateDocs } from './session-cache.js';
 import { realpathOrSelf } from '../fs-utils.js';
@@ -75,13 +71,6 @@ function disp(p) {
 function isJunkAncestor(dir) {
     return dir.split(sep).some((segment) => JUNK_DIRS.has(segment));
 }
-function owningRootOf(doc) {
-    const parts = doc.path.split(sep);
-    const idx = parts.lastIndexOf(CRTR_DIR_NAME);
-    if (idx <= 0)
-        return null;
-    return parts.slice(0, idx).join(sep) || sep;
-}
 function loadProjectDoc(file, memoryDir) {
     try {
         const raw = relative(memoryDir, file)
@@ -168,31 +157,6 @@ function dedupeByPhysicalPath(docs) {
     }
     return out;
 }
-function globMatches(glob, absReadFile, owningRoot) {
-    const targets = [absReadFile, basename(absReadFile)];
-    if (owningRoot !== null)
-        targets.push(relative(owningRoot, absReadFile));
-    return targets.some((target) => {
-        try {
-            return matchesGlob(target, glob);
-        }
-        catch {
-            return false;
-        }
-    });
-}
-/** True when the read file sits beneath the doc's store's owning directory —
- *  the read-event meaning of the reserved `applies-to: "."` target. Callers
- *  additionally guard on `doc.scope === 'project'`: a profile store's path
- *  computes an owning root of `~`, and user/builtin/node docs likewise have no
- *  project-owning dir, so `.` outside a project store must never match. */
-function underOwningRoot(doc, absReadFile) {
-    const root = owningRootOf(doc);
-    if (root === null)
-        return false;
-    const rel = relative(realpathOrSelf(root), absReadFile);
-    return rel !== '' && !rel.startsWith('..') && !isAbsolute(rel);
-}
 function readFileFrontmatter(absReadFile) {
     if (!/\.(md|mdx|markdown)$/i.test(absReadFile))
         return {};
@@ -203,24 +167,7 @@ function readFileFrontmatter(absReadFile) {
         return {};
     }
 }
-function matchesReadEvent(doc, absReadFile, readFrontmatter) {
-    const pathMatch = doc.appliesTo?.some((glob) => glob.trim() === '.'
-        ? doc.scope === 'project' && underOwningRoot(doc, absReadFile)
-        : globMatches(glob, absReadFile, owningRootOf(doc))) === true;
-    const frontmatterMatch = doc.readWhen !== undefined &&
-        Object.keys(readFrontmatter).length > 0 &&
-        evalCondition(doc.readWhen, readFrontmatter);
-    return pathMatch || frontmatterMatch;
-}
-function envelopeName(doc) {
-    const displayed = displayName(doc.name);
-    if (displayed !== '')
-        return displayed;
-    const root = owningRootOf(doc);
-    return root === null ? doc.name : basename(root);
-}
-function renderDocEnvelope(doc) {
-    const rung = doc.fileReadVisibility;
+function renderDocEnvelope(doc, rung) {
     if (rung === 'none')
         return null;
     let body = '';
@@ -228,47 +175,56 @@ function renderDocEnvelope(doc) {
         body = doc.body.trim();
     else if (rung === 'preview')
         body = previewLine(doc);
-    const attrs = `kind="${attr(doc.kind)}" name="${attr(envelopeName(doc))}" src="${attr(disp(doc.path))}"`;
+    const attrs = `kind="${attr(doc.kind)}" name="${attr(doc.name)}" src="${attr(disp(doc.path))}"`;
     return body === '' ? `<memory ${attrs} />` : `<memory ${attrs}>\n${body}\n</memory>`;
 }
-function renderCandidates(subject, docs, seen) {
+/** Render candidates at their matched rungs, gate-checked and deduped against
+ *  the transcript set (higher rungs pierce lower; a delivery records at its
+ *  rendered rung). A `null` subject means no node identity is available for
+ *  gate evaluation: gated docs are skipped, ungated docs still deliver. */
+export function renderCandidateBlocks(subject, candidates, seen) {
     const rendered = [];
-    for (const doc of docs) {
+    for (const { doc, rung } of candidates) {
         const real = realpathOrSelf(doc.path);
-        if (seen.has(real))
+        if (deliveredAtOrAbove(seen, real, rung))
             continue;
         try {
-            if (!gatePasses(doc, subject))
+            if (subject === null ? doc.gate !== undefined : !gatePasses(doc, subject))
                 continue;
-            const block = renderDocEnvelope(doc);
+            const block = renderDocEnvelope(doc, rung);
             if (block === null)
                 continue;
-            seen.add(real);
+            recordDelivery(seen, real, rung);
             rendered.push(block);
         }
         catch {
             continue;
         }
     }
+    return rendered;
+}
+function renderCandidates(subject, candidates, seen) {
+    const rendered = renderCandidateBlocks(subject, candidates, seen);
     return rendered.length === 0
         ? ''
         : `<auto-loaded-context>\n${rendered.join('\n')}\n</auto-loaded-context>`;
 }
-/** Surface docs matched by a successful read tool call using the caller-supplied
- * daemon snapshot subject. */
-export function renderOnReadDocsForSubject(subject, readFilePath, seen = new Set()) {
+/** Surface docs whose `read` entries match a successfully read file, using
+ * the caller-supplied daemon snapshot subject. */
+export function renderOnReadDocsForSubject(subject, readFilePath, seen = new Map()) {
     const absReadFile = realpathOrSelf(readFilePath);
     const readFrontmatter = readFileFrontmatter(absReadFile);
-    const docs = dedupeByPhysicalPath([...enclosingProjectDocs(absReadFile), ...resolvedDocs()])
+    const candidates = dedupeByPhysicalPath([...enclosingProjectDocs(absReadFile), ...resolvedDocs()])
         .filter((doc) => realpathOrSelf(doc.path) !== absReadFile)
-        .filter((doc) => matchesReadEvent(doc, absReadFile, readFrontmatter));
-    return renderCandidates(subject, docs, seen);
+        .map((doc) => ({ doc, rung: readDeliveryRung(doc, absReadFile, readFrontmatter) }))
+        .filter(({ rung }) => rung !== 'none');
+    return renderCandidates(subject, candidates, seen);
 }
 /** Workspace boot docs using the snapshot's cwd/profile instead of a canvas
  * lookup. `seen` is the transcript-scoped dedup set shared with the on-read
  * hook, so a front door delivered here never re-delivers on a later read
  * beneath its store. */
-export function renderWorkspaceOpenDocsForSubject(subject, cwd, profileId, seen = new Set()) {
+export function renderWorkspaceOpenDocsForSubject(subject, cwd, profileId, seen = new Map()) {
     let docs;
     try {
         docs = listProjectMemoryDocs(cwd, profileId)
@@ -278,13 +234,36 @@ export function renderWorkspaceOpenDocsForSubject(subject, cwd, profileId, seen
     catch {
         return '';
     }
-    docs = dedupeByPhysicalPath(docs)
-        .filter((doc) => doc.appliesTo?.some((glob) => glob.trim() === '.') === true)
+    const candidates = dedupeByPhysicalPath(docs)
+        .map((doc) => ({ doc, rung: workspaceOpenRung(doc) }))
+        .filter(({ rung }) => rung !== 'none')
         .sort((a, b) => {
-        const aRoot = owningRootOf(a) ?? '';
-        const bRoot = owningRootOf(b) ?? '';
+        const aRoot = owningRootOf(a.doc) ?? '';
+        const bRoot = owningRootOf(b.doc) ?? '';
         const depth = aRoot.split(sep).filter(Boolean).length - bRoot.split(sep).filter(Boolean).length;
-        return depth || aRoot.localeCompare(bRoot) || a.path.localeCompare(b.path);
+        return depth || aRoot.localeCompare(bRoot) || a.doc.path.localeCompare(b.doc.path);
     });
-    return renderCandidates(subject, docs, seen);
+    return renderCandidates(subject, candidates, seen);
+}
+/** Inner `<memory>` blocks for the memory-read event: docs whose
+ * `memory-read` entries match the doc a `crtr memory read` just resolved
+ * (known by `targetNames`; `excludeRealpath` keeps the resolved doc from
+ * delivering itself). Returns unwrapped blocks — the read leaf composes one
+ * `<auto-loaded-context>` envelope from these plus the directory listings. */
+export function memoryReadDocBlocks(subject, excludeRealpath, targetNames, seen) {
+    const candidates = dedupeByPhysicalPath(resolvedDocs())
+        .filter((doc) => realpathOrSelf(doc.path) !== excludeRealpath)
+        .map((doc) => ({ doc, rung: memoryReadDeliveryRung(doc, targetNames) }))
+        .filter(({ rung }) => rung !== 'none');
+    return renderCandidateBlocks(subject, candidates, seen);
+}
+/** Surface docs whose `command` entries match an executed bash command
+ * string. The corpus is the resolved cwd/profile set only — a command has no
+ * file to walk enclosing stores from. `seen` is the same transcript-scoped
+ * dedup set as the other channels. */
+export function renderOnCommandDocsForSubject(subject, command, seen = new Map()) {
+    const candidates = dedupeByPhysicalPath(resolvedDocs())
+        .map((doc) => ({ doc, rung: commandDeliveryRung(doc, command) }))
+        .filter(({ rung }) => rung !== 'none');
+    return renderCandidates(subject, candidates, seen);
 }

package/dist/core/substrate/render-node.d.ts

@@ -1,3 +1,4 @@
+import type { InjectedDocs } from './injected-store.js';
 /** The system-prompt `<memory kind="preference">` block for `nodeId`: assemble
  *  the node's subject from the canvas-db, render the pure block, then swap the
  *  literal `$CRTR_CONTEXT_DIR` env-var token for the node's real absolute path
@@ -7,5 +8,7 @@
 export declare function renderPreferencesSection(nodeId: string): string;
 /** The first-message `<memory kind="knowledge">` block for `nodeId`: assemble
  *  the node's subject from the canvas-db and render the consultable catalog.
- *  Returns '' for an unknown id or when nothing is eligible. */
-export declare function renderKnowledgeBlock(nodeId: string): string;
+ *  Returns '' for an unknown id or when nothing is eligible. `seen` (optional,
+ *  write-only) receives each rendered doc at its displayed rung — boot
+ *  delivery seeding for the transcript dedup map. */
+export declare function renderKnowledgeBlock(nodeId: string, seen?: InjectedDocs): string;

package/dist/core/substrate/render-node.js

@@ -20,10 +20,12 @@ export function renderPreferencesSection(nodeId) {
 }
 /** The first-message `<memory kind="knowledge">` block for `nodeId`: assemble
  *  the node's subject from the canvas-db and render the consultable catalog.
- *  Returns '' for an unknown id or when nothing is eligible. */
-export function renderKnowledgeBlock(nodeId) {
+ *  Returns '' for an unknown id or when nothing is eligible. `seen` (optional,
+ *  write-only) receives each rendered doc at its displayed rung — boot
+ *  delivery seeding for the transcript dedup map. */
+export function renderKnowledgeBlock(nodeId, seen) {
     const subject = assembleNodeSubject(nodeId);
     if (subject === null)
         return '';
-    return renderKnowledgeForSubject(subject, nodeId);
+    return renderKnowledgeForSubject(subject, nodeId, seen);
 }

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

@@ -1,6 +1,7 @@
+import { type InjectedDocs } from './injected-store.js';
 import { type SubstrateDoc } from './schema.js';
 import type { NodeConfigSubject } from './subject-fields.js';
-export declare function renderPreferencesForSubject(subject: NodeConfigSubject | null): {
+export declare function renderPreferencesForSubject(subject: NodeConfigSubject | null, seen?: InjectedDocs): {
     block: string;
     contentDocs: SubstrateDoc[];
     tree: string;
@@ -12,10 +13,10 @@ export declare function renderPreferencesForSubject(subject: NodeConfigSubject |
  *  first-wins dedup over a same-named node-local doc. GROUPED by rung exactly
  *  like the preference block: content prose first (general→specific,
  *  node-local last), then the preview/name catalog tree. Node-local docs are
- *  floored HERE — a rung-none node-local doc's effective rung is bumped to
- *  `name` before grouping, so it still surfaces as a bare-name tree entry
- *  rather than collapsing into a `[+N more]` count (its body still never
- *  renders: floored docs never reach the `content` rung). Procedural guidance
- *  and factual references both live here as `knowledge`. Returns '' when
- *  nothing is eligible. */
-export declare function renderKnowledgeForSubject(subject: NodeConfigSubject, nodeId: string): string;
+ *  floored HERE — a bootless node-local doc's rung is bumped to `name` before
+ *  grouping, so it still surfaces as a bare-name tree entry rather than
+ *  collapsing into a `[+N more]` count (its body still never renders: floored
+ *  docs never reach the `content` rung). Procedural guidance and factual
+ *  references both live here as `knowledge`. Returns '' when nothing is
+ *  eligible. */
+export declare function renderKnowledgeForSubject(subject: NodeConfigSubject, nodeId: string, seen?: InjectedDocs): string;