@north-light/crouter 0.3.222 → 0.3.224

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? */
@@ -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

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
@@ -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;
@@ -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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@north-light/crouter",
-  "version": "0.3.222",
+  "version": "0.3.224",
   "description": "crtr — agent runtime with memory, plugins, and marketplaces",
   "type": "module",
   "main": "dist/index.js",

package/runtime.lock.json

@@ -1,12 +1,12 @@
 {
   "name": "@north-light/crouter",
-  "version": "0.3.222",
+  "version": "0.3.224",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@north-light/crouter",
-      "version": "0.3.222",
+      "version": "0.3.224",
       "hasInstallScript": true,
       "license": "MIT",
       "dependencies": {