@north-light/crouter 0.3.221 → 0.3.223

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

@@ -48,27 +48,6 @@ function attr(s) {
         .replace(/</g, '&lt;')
         .replace(/>/g, '&gt;');
 }
-function gitRootOf(p) {
-    let d = p;
-    const root = parse(d).root;
-    while (true) {
-        if (pathExists(`${d}${sep}.git`))
-            return d;
-        if (d === root)
-            return null;
-        const parent = dirname(d);
-        if (parent === d)
-            return null;
-        d = parent;
-    }
-}
-function disp(p) {
-    const root = gitRootOf(p);
-    if (!root)
-        return p;
-    const rel = relative(root, p);
-    return rel === '' ? '.' : rel;
-}
 function isJunkAncestor(dir) {
     return dir.split(sep).some((segment) => JUNK_DIRS.has(segment));
 }
@@ -184,16 +163,26 @@ function docContentKey(doc) {
         return null;
     return `content-sha256:${createHash('sha256').update(body).digest('hex')}`;
 }
+// Two shapes: element-with-body means the content is here; self-closing means
+// it is not — a preview carries its routing line as `readWhen` metadata so the
+// one-liner can never be mistaken for the document's content. No disk path:
+// agents address memory by name through the command surface, and the explicit
+// read leaf already returns `path`.
 function renderDocEnvelope(doc, rung) {
     if (rung === 'none')
         return null;
-    let body = '';
-    if (rung === 'content')
-        body = doc.body.trim();
-    else if (rung === 'preview')
-        body = previewLine(doc);
-    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>`;
+    let attrs = `kind="${attr(doc.kind)}" name="${attr(doc.name)}"`;
+    if (rung === 'content') {
+        const body = doc.body.trim();
+        if (body !== '')
+            return `<memory ${attrs}>\n${body}\n</memory>`;
+    }
+    else if (rung === 'preview') {
+        const pl = previewLine(doc);
+        if (pl !== '')
+            attrs += ` readWhen="${attr(pl)}"`;
+    }
+    return `<memory ${attrs} />`;
 }
 /** Render candidates at their matched rungs, gate-checked and deduped against
  *  the transcript set (higher rungs pierce lower; a delivery records at its
@@ -240,7 +229,7 @@ export function renderOnReadDocsForSubject(subject, readFilePath, seen = new Map
     const readFrontmatter = readFileFrontmatter(absReadFile);
     const candidates = dedupeByPhysicalPath([...enclosingProjectDocs(absReadFile), ...resolvedDocs()])
         .filter((doc) => realpathOrSelf(doc.path) !== absReadFile)
-        .map((doc) => ({ doc, rung: readDeliveryRung(doc, absReadFile, readFrontmatter) }))
+        .map((doc) => ({ doc, rung: readDeliveryRung(doc, subject, absReadFile, readFrontmatter) }))
         .filter(({ rung }) => rung !== 'none');
     return renderCandidates(subject, candidates, seen);
 }
@@ -265,7 +254,7 @@ export function renderWorkspaceOpenDocsForSubject(subject, cwd, profileId, seen
         return '';
     }
     const candidates = dedupeByPhysicalPath(docs)
-        .map((doc) => ({ doc, rung: minRung(workspaceOpenRung(doc), doc.projectMemory) }))
+        .map((doc) => ({ doc, rung: minRung(workspaceOpenRung(doc, subject), doc.projectMemory) }))
         .filter(({ rung }) => rung !== 'none')
         .sort((a, b) => {
         const aRoot = owningRootOf(a.doc) ?? '';
@@ -283,7 +272,7 @@ export function renderWorkspaceOpenDocsForSubject(subject, cwd, profileId, seen
 export function memoryReadDocBlocks(subject, excludeRealpath, targetNames, seen) {
     const candidates = dedupeByPhysicalPath(resolvedDocs())
         .filter((doc) => realpathOrSelf(doc.path) !== excludeRealpath)
-        .map((doc) => ({ doc, rung: memoryReadDeliveryRung(doc, targetNames) }))
+        .map((doc) => ({ doc, rung: memoryReadDeliveryRung(doc, subject, targetNames) }))
         .filter(({ rung }) => rung !== 'none');
     return renderCandidateBlocks(subject, candidates, seen);
 }
@@ -293,7 +282,7 @@ export function memoryReadDocBlocks(subject, excludeRealpath, targetNames, seen)
  * 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) }))
+        .map((doc) => ({ doc, rung: commandDeliveryRung(doc, subject, command) }))
         .filter(({ rung }) => rung !== 'none');
     return renderCandidates(subject, candidates, seen);
 }

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

@@ -1,6 +1,7 @@
 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
+/** The system-prompt substrate splice for `nodeId` — shipped-layer protocol
+ *  prose followed by the `<memory kind="preference">` block: assemble
+ *  the node's subject from the canvas-db, render the pure splice, then swap the
  *  literal `$CRTR_CONTEXT_DIR` env-var token for the node's real absolute path
  *  so agents don't paste it into the non-expanding Write tool (see
  *  interpolateNodePaths). A null subject (unknown id) still renders the

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

@@ -8,8 +8,9 @@
 import { interpolateNodePaths } from '../canvas/paths.js';
 import { assembleNodeSubject } from './subject.js';
 import { renderPreferencesForSubject, renderKnowledgeForSubject } from './render.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
+/** The system-prompt substrate splice for `nodeId` — shipped-layer protocol
+ *  prose followed by the `<memory kind="preference">` block: assemble
+ *  the node's subject from the canvas-db, render the pure splice, then swap the
  *  literal `$CRTR_CONTEXT_DIR` env-var token for the node's real absolute path
  *  so agents don't paste it into the non-expanding Write tool (see
  *  interpolateNodePaths). A null subject (unknown id) still renders the

package/dist/core/substrate/render.js

@@ -8,11 +8,10 @@
 // then the `preview`+`name` docs render as ONE catalog tree, each at its own
 // rung (preview → a `# read when:` routing line; name → a bare entry); a doc
 // with NO boot entry leaks only into its dir's `[+N more]` count, never a
-// name — EXCEPT a node-local doc, whose contract is "node-local rides into
-// knowledge" unconditionally: renderKnowledgeForSubject floors a bootless
-// node-local doc up to `name` so it still shows its bare name rather than
-// collapsing into a hidden count. Only gate evaluation removes a node-local
-// doc outright.
+// name — EXCEPT a node-local doc with no boot entry: renderKnowledgeForSubject
+// floors it up to `name` so it still shows its bare name rather than
+// collapsing into a hidden count. A node-local doc with boot entries remains
+// absent when none of those entries participates.
 //
 //   • the SYSTEM-PROMPT half — `<memory kind="preference">`
 //     (renderPreferencesSection) — the always-present memory-usage guidance plus
@@ -27,11 +26,11 @@
 //
 // The pipeline is explicitly TWO-STEP and must never run in the other order:
 //   1. SELECT WINNERS — MemoryDoc → parseSubstrateDoc → (null-filter
-//      non-substrate) → per-doc boot rung (`bootRung`, the max `at` over the
-//      doc's `on: boot` surfaces entries) → gatePasses → first-wins DEDUP by
+//      non-substrate) → per-doc boot rung (`bootRung`, the max `at` over
+//      participating `on: boot` surfaces entries) → gatePasses → first-wins DEDUP by
 //      name over the resolver's precedence order (nearest project > user >
 //      builtin). Node-local docs follow the same gate rule, but the
-//      knowledge-block render floors a bootless node-local doc's rung to
+//      knowledge-block render floors only a node-local doc with no boot entry to
 //      `name` — the one rung-floor exemption, scoped to the node-local store
 //      only.
 //   2. RENDER IN DISPLAY ORDER — split winners into content vs. the rest;
@@ -108,7 +107,7 @@ function selectWinners(subject, kind) {
         .filter((d) => d.kind === kind)
         .filter((d) => d.projectMemory !== 'none')
         .filter((d) => gatePasses(d, subject))
-        .map((d) => ({ ...d, bootRung: minRung(bootRung(d), d.projectMemory) }));
+        .map((d) => ({ ...d, bootRung: minRung(bootRung(d, subject), d.projectMemory) }));
     return dedupeFirstWins(eligible);
 }
 // ---------------------------------------------------------------------------
@@ -183,9 +182,16 @@ function compareTreePosition(a, b) {
     }
     return as.length - bs.length;
 }
+/** A doc the running agent can revise through `crtr memory edit`: any native
+ *  scope-store doc (user/profile/project/node). Shipped docs — builtin and
+ *  plugin-mounted — are not editable from a node; the preference render treats
+ *  them as operating protocol, not memory (see buildPreferencesBlock). */
+function isAgentEditable(doc) {
+    return doc.scope !== 'builtin' && doc.plugin === undefined;
+}
 /** STEP 2 — split deduped `winners` by rung and render each group in its
  *  display order: `content` docs first, as clean prose (general→specific,
- *  then tree position, then filename — no tree chrome, no name label); every
+ *  then tree position, then filename — no tree chrome); every
  *  other winner (preview/name/hidden-bootless) folds into ONE catalog tree
  *  exactly as before. `nodeLocalSet` marks which winners came from the
  *  node-local store (ranked most-specific in content ordering); omit it for a
@@ -216,13 +222,9 @@ function renderGrouped(winners, rootLabel, nodeLocalSet = new Set()) {
  *  Returned across ALL kinds — node-local is the catch-all this-node store and
  *  rides into the knowledge block.
  *
- *  Node-local docs follow the same GATE rule as every other store — gate
- *  evaluation is the only thing that removes a doc here. Rung is different:
- *  node-local's contract is "node-local rides into knowledge" unconditionally,
- *  so a doc with no boot entry is retained by this function — it is the caller
- *  (renderKnowledgeForSubject) that floors a bootless node-local doc up to
- *  `name` so it still shows its bare name instead of collapsing into a
- *  `[+N more]` count. */
+ *  Node-local docs follow the same GATE rule as every other store. A doc with
+ *  no boot entry is retained here; renderKnowledgeForSubject floors it to
+ *  `name` so it shows as a bare name instead of collapsing into `[+N more]`. */
 function nodeLocalDocs(nodeId, subject) {
     const dir = memoryDir(nodeId);
     if (!pathExists(dir))
@@ -489,37 +491,62 @@ function buildSubPersonaMenu(kind) {
         lines.join('\n'));
 }
 // ---------------------------------------------------------------------------
-// 1. Preferences — `<memory kind="preference">` (system prompt).
+// 1. Preferences — protocol prose + `<memory kind="preference">` (system prompt).
 // ---------------------------------------------------------------------------
-/** The system-prompt memory block: the always-present memory-usage guidance,
- *  then (when any are eligible) the `kind: preference` docs GROUPED by rung —
- *  content-rung docs first as clean prose (general→specific), then the
- *  preview/name catalog tree. ALWAYS returns a non-empty `<memory
- *  kind="preference">` block — the guidance frame is unconditional, so the
- *  system-prompt splice is never empty even when no preference is eligible. */
+/** The system-prompt substrate splice, TWO parts in one string.
+ *
+ *  1. The operating protocol: shipped (builtin/plugin) content-rung bodies as
+ *     bare prose, plus the sub-persona menu. No memory envelope — the protocol
+ *     is the rules of the node's world, and wrapping it as recalled "memory:
+ *     preference" content gave it softer epistemic status than the
+ *     instructions it is; the intro/outro sentences ("how the user wants you
+ *     to behave", "update the preference") were also false of it.
+ *  2. The `<memory kind="preference">` block: the always-present memory-usage
+ *     guidance, then (when any are eligible) each agent-editable doc wrapped
+ *     `<preference name="…">…</preference>` — the name is the edit handle the
+ *     outro's update directive needs — then the preview/name catalog tree.
+ *     Every frame sentence is true of everything inside it.
+ *
+ *  Ordering across the two parts is unchanged from the single-block render
+ *  (shipped→editable was already the scope sort), so the shared cache prefix
+ *  across nodes is preserved. ALWAYS returns a non-empty splice — the guidance
+ *  frame is unconditional, so it is never empty even when no preference is
+ *  eligible. */
 function buildPreferencesBlock(subject, seen) {
-    let body = MEMORY_USAGE_GUIDANCE;
     let contentDocs = [];
     let tree = '';
+    let protocol = '';
+    let memBody = MEMORY_USAGE_GUIDANCE;
     if (subject !== null) {
         const winners = selectWinners(subject, 'preference');
         seedBootDelivery(seen, winners);
         const grouped = renderGrouped(winners, 'preferences');
         contentDocs = grouped.contentDocs;
         tree = grouped.tree;
+        const shipped = contentDocs
+            .filter((d) => !isAgentEditable(d))
+            .map((d) => d.body.trim())
+            .filter((b) => b !== '');
+        const editable = contentDocs
+            .filter((d) => isAgentEditable(d))
+            .map((d) => {
+            const b = d.body.trim();
+            return b === '' ? '' : `<preference name="${d.name}">\n${b}\n</preference>`;
+        })
+            .filter((b) => b !== '');
         const subPersonaMenu = buildSubPersonaMenu(subject.kind);
-        if (grouped.contentProse !== '' || grouped.tree !== '' || subPersonaMenu !== '') {
-            body += `\n\n${PREFERENCES_INTRO}`;
-            if (grouped.contentProse !== '')
-                body += `\n\n${grouped.contentProse}`;
-            if (subPersonaMenu !== '')
-                body += `\n\n${subPersonaMenu}`;
-            if (grouped.tree !== '')
-                body += `\n\n${grouped.tree}`;
-            body += `\n\n${PREFERENCES_OUTRO}`;
+        protocol = [...shipped, ...(subPersonaMenu === '' ? [] : [subPersonaMenu])].join('\n\n');
+        if (editable.length > 0 || tree !== '') {
+            memBody += `\n\n${PREFERENCES_INTRO}`;
+            if (editable.length > 0)
+                memBody += `\n\n${editable.join('\n\n')}`;
+            if (tree !== '')
+                memBody += `\n\n${tree}`;
+            memBody += `\n\n${PREFERENCES_OUTRO}`;
         }
     }
-    return { block: `<memory kind="preference">\n${body}\n</memory>`, contentDocs, tree };
+    const memoryBlock = `<memory kind="preference">\n${memBody}\n</memory>`;
+    return { block: protocol === '' ? memoryBlock : `${protocol}\n\n${memoryBlock}`, contentDocs, tree };
 }
 export function renderPreferencesForSubject(subject, seen) {
     return buildPreferencesBlock(subject, seen);
@@ -542,8 +569,8 @@ export function renderPreferencesForSubject(subject, seen) {
  *  eligible. */
 export function renderKnowledgeForSubject(subject, nodeId, seen) {
     const nodeLocal = nodeLocalDocs(nodeId, subject).map((d) => {
-        const r = bootRung(d);
-        return { ...d, bootRung: isVisible(r) ? r : 'name' };
+        const r = bootRung(d, subject);
+        return { ...d, bootRung: isVisible(r) || d.surfaces.some((e) => e.on === 'boot') ? r : 'name' };
     });
     const nodeLocalSet = new Set(nodeLocal);
     // Resolver winners first: first-wins dedup keeps the resolver's copy over a

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

@@ -1,5 +1,6 @@
 import { type ProfileProjectMemory } from '../../api/dto/profiles.js';
 import type { MemoryDoc, MemoryScope } from '../memory-resolver.js';
+import type { NodeConfigSubject } from './subject-fields.js';
 export declare const KINDS: readonly ["knowledge", "preference"];
 export type DocKind = (typeof KINDS)[number];
 /** Is `v` one of the two valid document kinds? */
@@ -14,7 +15,7 @@ export declare function rungAtLeast(r: Rung, min: Rung): boolean;
  *  authored rung against its project relationship's cap. */
 export declare function minRung(a: Rung, b: Rung): Rung;
 /** Strip an optional `NN-` ordering prefix from ONE path segment (file or
- *  directory display name). `00-runtime-base` -> `runtime-base`; `spine` (no
+ *  directory display name). `00-runtime-base/00-authoring` -> `runtime-base/authoring`; `spine` (no
  *  prefix) is unchanged. */
 export declare function normalizeNameSegment(segment: string): string;
 /** Normalize a full slash-separated path-derived doc name by stripping the
@@ -34,10 +35,10 @@ export type SurfaceEvent = (typeof SURFACE_EVENTS)[number];
 export declare const SURFACE_RUNGS: readonly ["name", "preview", "content"];
 export type SurfaceRung = (typeof SURFACE_RUNGS)[number];
 /** One routing entry: when event `on` exposes a subject that fits `match`
- *  (and `matchFrontmatter`, `read` only), the doc delivers at rung `at`.
- *  Constraints within one entry AND together (each present constraint must
- *  fit; a `match` list is satisfied by any one glob); multiple entries per
- *  event OR together. */
+ *  (and `matchFrontmatter`, `read` only) and its optional node-config `gate`,
+ *  the doc delivers at rung `at`. Constraints within one entry AND together
+ *  (each present constraint must fit; a `match` list is satisfied by any one
+ *  glob); multiple entries per event OR together. */
 export interface SurfaceEntry {
     on: SurfaceEvent;
     /** Globs vs the event's subject namespace. Required on read/memory-read/
@@ -47,11 +48,15 @@ export interface SurfaceEntry {
     /** Predicate over the read file's own YAML frontmatter — `read` event only.
      *  Frontmatter key `match-frontmatter`. */
     matchFrontmatter?: GatePredicate;
+    /** Optional predicate over the current node config. Frontmatter key `gate`.
+     *  The document-level gate remains the hard eligibility check. */
+    gate?: GatePredicate;
     at: SurfaceRung;
 }
-/** A doc's boot rung: the highest `at` over its `boot` entries, `none` when
- *  it carries no boot entry. The boot render's per-doc selection input. */
-export declare function bootRung(doc: Pick<SubstrateSchema, 'surfaces'>): Rung;
+/** A doc's boot rung for `subject`: the highest `at` over participating
+ *  `boot` entries, `none` when it carries none. The boot render's per-doc
+ *  selection input. */
+export declare function bootRung(doc: Pick<SubstrateSchema, 'surfaces'>, subject: NodeConfigSubject): Rung;
 /** 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
@@ -111,6 +116,10 @@ export interface SubstrateDoc extends SubstrateSchema {
     name: string;
     /** The scope this doc resolved from. */
     scope: MemoryScope;
+    /** Owning plugin name when the doc is mounted from an installed plugin;
+     *  undefined for a native scope doc. Shipped (builtin/plugin) docs and
+     *  agent-editable scope docs render differently at boot (see renderGrouped). */
+    plugin?: string;
     /** Absolute path to the source .md. */
     path: string;
     /** Document body, frontmatter stripped. */

package/dist/core/substrate/schema.js

@@ -8,6 +8,7 @@
 // never throw): invalid `surfaces` entries are dropped rather than crashing a
 // render, and `crtr memory lint` owns strict authoring-time enforcement.
 import { PROFILE_PROJECT_MEMORY_VALUES } from '../../api/dto/profiles.js';
+import { surfaceEntryGatePasses } from './gate.js';
 // ---------------------------------------------------------------------------
 // Kinds — the two semantic kinds (design §3): `knowledge` (consult — procedural
 // playbooks + factual references merged) vs `preference` (behave — standing
@@ -43,18 +44,18 @@ export function minRung(a, b) {
 // ---------------------------------------------------------------------------
 // Display-name normalization — the optional `NN-` ordering pin. A doc's
 // physical path may carry a two-digit numeric prefix on a file or directory
-// segment (`00-runtime-base.md`, `01-spine/`) purely to pin structural order
+// segment (`00-runtime-base/`, `01-spine/`) purely to pin structural order
 // against natural sort (design: builtin prompt corpus, used sparingly). The
 // 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`. When a doc
+// `00-runtime-base/00-authoring` displays/dedups/resolves as `runtime-base/authoring`. 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
- *  directory display name). `00-runtime-base` -> `runtime-base`; `spine` (no
+ *  directory display name). `00-runtime-base/00-authoring` -> `runtime-base/authoring`; `spine` (no
  *  prefix) is unchanged. */
 export function normalizeNameSegment(segment) {
     return segment.replace(NUMERIC_PREFIX_RE, '');
@@ -95,12 +96,13 @@ export const SURFACE_EVENTS = ['boot', 'workspace-open', 'read', 'memory-read',
  *  absence of an entry. (`Rung`'s `none` survives only as the internal
  *  ranking floor, e.g. `bootRung` of a doc with no boot entry.) */
 export const SURFACE_RUNGS = ['name', 'preview', 'content'];
-/** A doc's boot rung: the highest `at` over its `boot` entries, `none` when
- *  it carries no boot entry. The boot render's per-doc selection input. */
-export function bootRung(doc) {
+/** A doc's boot rung for `subject`: the highest `at` over participating
+ *  `boot` entries, `none` when it carries none. The boot render's per-doc
+ *  selection input. */
+export function bootRung(doc, subject) {
     let r = 'none';
     for (const e of doc.surfaces) {
-        if (e.on !== 'boot')
+        if (e.on !== 'boot' || !surfaceEntryGatePasses(e, subject))
             continue;
         if (rungRank(e.at) > rungRank(r))
             r = e.at;
@@ -142,7 +144,7 @@ export function parseSubstrateDoc(doc) {
     const schema = parseSubstrateFrontmatter(doc.frontmatter);
     if (schema === null)
         return null;
-    return { ...schema, name: doc.name, scope: doc.scope, path: doc.path, body: doc.body, projectMemory: doc.projectMemory };
+    return { ...schema, name: doc.name, scope: doc.scope, plugin: doc.plugin, path: doc.path, body: doc.body, projectMemory: doc.projectMemory };
 }
 /** The kind a doc resolves to for `--kind` filtering/matching: the substrate
  *  kind when the frontmatter parses as a valid substrate doc, else the raw
@@ -194,8 +196,8 @@ function parseGate(v) {
  *  dropped (bad `on`, bad `at`, a read/memory-read/command entry left with
  *  neither `match` nor — read only — `match-frontmatter`). `match-frontmatter`
  *  on a non-read event is dropped from the entry, which survives iff it still
- *  carries a `match`. Lint owns strict enforcement; the runtime parser maps
- *  over many docs and must never throw. */
+ *  carries a `match`; an invalid entry `gate` is dropped. Lint owns strict
+ *  enforcement; the runtime parser maps over many docs and must never throw. */
 function parseSurfaces(v) {
     if (!Array.isArray(v))
         return [];
@@ -212,6 +214,7 @@ function parseSurfaces(v) {
             continue;
         const match = parseMatchGlobs(rec['match']);
         const matchFrontmatter = on === 'read' ? parseGate(rec['match-frontmatter']) : undefined;
+        const gate = parseGate(rec['gate']);
         if ((on === 'read' || on === 'memory-read' || on === 'command') &&
             match === undefined &&
             matchFrontmatter === undefined) {
@@ -222,6 +225,7 @@ function parseSurfaces(v) {
             at: at,
             ...(match !== undefined ? { match } : {}),
             ...(matchFrontmatter !== undefined ? { matchFrontmatter } : {}),
+            ...(gate !== undefined ? { gate } : {}),
         });
     }
     return out;

package/dist/core/substrate/surface-match.d.ts

@@ -1,4 +1,5 @@
 import { type Rung, type SubstrateDoc, type SurfaceEntry } from './schema.js';
+import type { NodeConfigSubject } from './subject-fields.js';
 /** The project directory owning a doc's store: the path segment stack above
  *  the doc's `.crouter` dir. `null` when the doc's path carries no `.crouter`
  *  segment (builtin docs). */
@@ -13,20 +14,20 @@ export declare function underOwningRoot(doc: Pick<SubstrateDoc, 'path'>, absFile
  *  realpathed. `readFrontmatter` is the read file's own parsed YAML (empty
  *  for non-markdown files); an empty record never satisfies
  *  `matchFrontmatter`. */
-export declare function matchesReadEntry(entry: SurfaceEntry, doc: Pick<SubstrateDoc, 'path' | 'scope'>, absReadFile: string, readFrontmatter: Record<string, unknown>): boolean;
+export declare function matchesReadEntry(entry: SurfaceEntry, doc: Pick<SubstrateDoc, 'path' | 'scope'>, subject: NodeConfigSubject, absReadFile: string, readFrontmatter: Record<string, unknown>): boolean;
 /** Does a `memory-read` entry on the doc named `carrierName` fit a resolved
  *  read of a doc known by `targetNames`? */
-export declare function matchesMemoryReadEntry(entry: SurfaceEntry, carrierName: string, targetNames: string[]): boolean;
+export declare function matchesMemoryReadEntry(entry: SurfaceEntry, carrierName: string, subject: NodeConfigSubject | null, targetNames: string[]): boolean;
 /** Does a `command` entry fit the executed command string? */
-export declare function matchesCommandEntry(entry: SurfaceEntry, command: string): boolean;
+export declare function matchesCommandEntry(entry: SurfaceEntry, subject: NodeConfigSubject, command: string): boolean;
 /** The doc's delivery rung for a read of `absReadFile` (already realpathed). */
-export declare function readDeliveryRung(doc: Pick<SubstrateDoc, 'surfaces' | 'path' | 'scope'>, absReadFile: string, readFrontmatter: Record<string, unknown>): Rung;
+export declare function readDeliveryRung(doc: Pick<SubstrateDoc, 'surfaces' | 'path' | 'scope'>, subject: NodeConfigSubject, absReadFile: string, readFrontmatter: Record<string, unknown>): Rung;
 /** The doc's workspace-open rung. Presence of an entry is the match; callers
  *  scope the corpus to project stores mounted by the subject's cwd/profile. */
-export declare function workspaceOpenRung(doc: Pick<SubstrateDoc, 'surfaces'>): Rung;
+export declare function workspaceOpenRung(doc: Pick<SubstrateDoc, 'surfaces'>, subject: NodeConfigSubject): Rung;
 /** The doc's delivery rung for a `crtr memory read` that resolved a doc
  *  known by `targetNames` (canonical name, plus the mount-stripped name for
  *  plugin-mounted docs). The doc's own `name` anchors `./` globs. */
-export declare function memoryReadDeliveryRung(doc: Pick<SubstrateDoc, 'surfaces' | 'name'>, targetNames: string[]): Rung;
+export declare function memoryReadDeliveryRung(doc: Pick<SubstrateDoc, 'surfaces' | 'name'>, subject: NodeConfigSubject | null, targetNames: string[]): Rung;
 /** The doc's delivery rung for an executed command string. */
-export declare function commandDeliveryRung(doc: Pick<SubstrateDoc, 'surfaces'>, command: string): Rung;
+export declare function commandDeliveryRung(doc: Pick<SubstrateDoc, 'surfaces'>, subject: NodeConfigSubject, command: string): Rung;

package/dist/core/substrate/surface-match.js

@@ -13,6 +13,7 @@ import { basename, isAbsolute, matchesGlob, relative, sep } from 'node:path';
 import { CRTR_DIR_NAME } from '../../types.js';
 import { realpathOrSelf } from '../fs-utils.js';
 import { evalCondition } from '../predicate.js';
+import { surfaceEntryGatePasses } from './gate.js';
 import { rungRank } from './schema.js';
 /** The project directory owning a doc's store: the path segment stack above
  *  the doc's `.crouter` dir. `null` when the doc's path carries no `.crouter`
@@ -62,8 +63,8 @@ function readGlobMatches(glob, doc, absReadFile) {
  *  realpathed. `readFrontmatter` is the read file's own parsed YAML (empty
  *  for non-markdown files); an empty record never satisfies
  *  `matchFrontmatter`. */
-export function matchesReadEntry(entry, doc, absReadFile, readFrontmatter) {
-    if (entry.on !== 'read')
+export function matchesReadEntry(entry, doc, subject, absReadFile, readFrontmatter) {
+    if (entry.on !== 'read' || !surfaceEntryGatePasses(entry, subject))
         return false;
     if (entry.match !== undefined && !entry.match.some((g) => readGlobMatches(g, doc, absReadFile))) {
         return false;
@@ -97,8 +98,8 @@ function memoryReadGlobMatches(glob, carrierName, targetNames) {
 }
 /** Does a `memory-read` entry on the doc named `carrierName` fit a resolved
  *  read of a doc known by `targetNames`? */
-export function matchesMemoryReadEntry(entry, carrierName, targetNames) {
-    if (entry.on !== 'memory-read' || entry.match === undefined)
+export function matchesMemoryReadEntry(entry, carrierName, subject, targetNames) {
+    if (entry.on !== 'memory-read' || entry.match === undefined || !surfaceEntryGatePasses(entry, subject))
         return false;
     return entry.match.some((g) => memoryReadGlobMatches(g, carrierName, targetNames));
 }
@@ -119,8 +120,8 @@ function commandGlobMatches(glob, command) {
     }
 }
 /** Does a `command` entry fit the executed command string? */
-export function matchesCommandEntry(entry, command) {
-    if (entry.on !== 'command' || entry.match === undefined)
+export function matchesCommandEntry(entry, subject, command) {
+    if (entry.on !== 'command' || entry.match === undefined || !surfaceEntryGatePasses(entry, subject))
         return false;
     return entry.match.some((g) => commandGlobMatches(g, command));
 }
@@ -131,10 +132,10 @@ export function matchesCommandEntry(entry, command) {
 // floor, never an authored rung).
 // ---------------------------------------------------------------------------
 /** The doc's delivery rung for a read of `absReadFile` (already realpathed). */
-export function readDeliveryRung(doc, absReadFile, readFrontmatter) {
+export function readDeliveryRung(doc, subject, absReadFile, readFrontmatter) {
     let r = 'none';
     for (const e of doc.surfaces) {
-        if (!matchesReadEntry(e, doc, absReadFile, readFrontmatter))
+        if (!matchesReadEntry(e, doc, subject, absReadFile, readFrontmatter))
             continue;
         if (rungRank(e.at) > rungRank(r))
             r = e.at;
@@ -143,10 +144,10 @@ export function readDeliveryRung(doc, absReadFile, readFrontmatter) {
 }
 /** The doc's workspace-open rung. Presence of an entry is the match; callers
  *  scope the corpus to project stores mounted by the subject's cwd/profile. */
-export function workspaceOpenRung(doc) {
+export function workspaceOpenRung(doc, subject) {
     let r = 'none';
     for (const e of doc.surfaces) {
-        if (e.on !== 'workspace-open')
+        if (e.on !== 'workspace-open' || !surfaceEntryGatePasses(e, subject))
             continue;
         if (rungRank(e.at) > rungRank(r))
             r = e.at;
@@ -156,10 +157,10 @@ export function workspaceOpenRung(doc) {
 /** The doc's delivery rung for a `crtr memory read` that resolved a doc
  *  known by `targetNames` (canonical name, plus the mount-stripped name for
  *  plugin-mounted docs). The doc's own `name` anchors `./` globs. */
-export function memoryReadDeliveryRung(doc, targetNames) {
+export function memoryReadDeliveryRung(doc, subject, targetNames) {
     let r = 'none';
     for (const e of doc.surfaces) {
-        if (!matchesMemoryReadEntry(e, doc.name, targetNames))
+        if (!matchesMemoryReadEntry(e, doc.name, subject, targetNames))
             continue;
         if (rungRank(e.at) > rungRank(r))
             r = e.at;
@@ -167,10 +168,10 @@ export function memoryReadDeliveryRung(doc, targetNames) {
     return r;
 }
 /** The doc's delivery rung for an executed command string. */
-export function commandDeliveryRung(doc, command) {
+export function commandDeliveryRung(doc, subject, command) {
     let r = 'none';
     for (const e of doc.surfaces) {
-        if (!matchesCommandEntry(e, command))
+        if (!matchesCommandEntry(e, subject, command))
             continue;
         if (rungRank(e.at) > rungRank(r))
             r = e.at;

package/dist/core/user-settings.d.ts

@@ -326,6 +326,10 @@ export declare const CONFIG_SETTINGS_COVERAGE: {
         surface: "specialized";
         owner: string;
     };
+    humanActions: {
+        surface: "specialized";
+        owner: string;
+    };
 };
 /** The exhaustive top-level key list used by config persistence and help. */
 export declare const SCOPE_CONFIG_KEYS: (keyof ScopeConfig)[];

package/dist/core/user-settings.js

@@ -389,6 +389,7 @@ export const CONFIG_SETTINGS_COVERAGE = {
     remoteCanvas: { surface: 'specialized', owner: 'canvas config commands' },
     spawnEnv: { surface: 'specialized', owner: 'spawn environment allow-list' },
     bin: { surface: 'specialized', owner: 'bare-binary contributions on every node PATH' },
+    humanActions: { surface: 'specialized', owner: 'scope-configured human completion actions' },
 };
 /** The exhaustive top-level key list used by config persistence and help. */
 export const SCOPE_CONFIG_KEYS = Object.keys(CONFIG_SETTINGS_COVERAGE);