@north-light/crouter 0.3.221 → 0.3.223

package/dist/core/runtime/chat-inventory-rows.js

@@ -0,0 +1,105 @@
+import { isDeterministicCommandExpansion } from './command-expansion.js';
+const MEMORY_KINDS = new Set(['knowledge', 'preference']);
+const MEMORY_SCOPES = new Set(['node', 'project', 'profile', 'user', 'builtin']);
+function nonEmptyString(value) {
+    return typeof value === 'string' && value !== '';
+}
+/** Keep the command rows a Gateway can use. Malformed registrations are
+ * discarded individually so one producer cannot take down the inventory. */
+export function gatewayCommandRows(rows) {
+    if (!Array.isArray(rows))
+        return [];
+    const out = [];
+    for (const row of rows) {
+        if (typeof row !== 'object' || row === null)
+            continue;
+        const record = row;
+        if (record['gatewayCapable'] !== true)
+            continue;
+        const source = record['source'];
+        if (source !== 'command' && source !== 'template')
+            continue;
+        if (!nonEmptyString(record['name']) || typeof record['description'] !== 'string')
+            continue;
+        const expansion = record['expansion'];
+        const template = record['template'];
+        const argumentHint = record['argumentHint'];
+        out.push({
+            name: record['name'],
+            description: record['description'],
+            source,
+            ...(nonEmptyString(argumentHint) ? { argument_hint: argumentHint } : {}),
+            ...(isDeterministicCommandExpansion(expansion) ? { expansion } : {}),
+            ...(typeof template === 'string' ? { template } : {}),
+        });
+    }
+    return out;
+}
+export function chatInventoryCommandRows(rows) {
+    if (!Array.isArray(rows))
+        return [];
+    return rows.filter((row) => {
+        if (typeof row !== 'object' || row === null)
+            return false;
+        const record = row;
+        if (!nonEmptyString(record['name']) || typeof record['description'] !== 'string')
+            return false;
+        if (record['source'] !== 'command' && record['source'] !== 'template')
+            return false;
+        if (record['argument_hint'] !== undefined && !nonEmptyString(record['argument_hint']))
+            return false;
+        if (record['template'] !== undefined && typeof record['template'] !== 'string')
+            return false;
+        return record['expansion'] === undefined || isDeterministicCommandExpansion(record['expansion']);
+    });
+}
+export function gatewayCommandRowsFromDetail(detail) {
+    if (detail === undefined)
+        return [];
+    try {
+        return gatewayCommandRows(JSON.parse(detail));
+    }
+    catch {
+        return [];
+    }
+}
+export function chatInventoryMemoryRows(rows) {
+    if (!Array.isArray(rows))
+        return [];
+    return rows.filter((row) => {
+        if (typeof row !== 'object' || row === null)
+            return false;
+        const record = row;
+        return nonEmptyString(record['name'])
+            && typeof record['shortForm'] === 'string'
+            && typeof record['kind'] === 'string'
+            && MEMORY_KINDS.has(record['kind'])
+            && typeof record['scope'] === 'string'
+            && MEMORY_SCOPES.has(record['scope']);
+    });
+}
+export function gatewayMemoryRows(refs) {
+    if (!Array.isArray(refs))
+        return [];
+    const out = [];
+    for (const row of refs) {
+        if (typeof row !== 'object' || row === null)
+            continue;
+        const record = row;
+        if (record['gatewayVisible'] !== true)
+            continue;
+        if (!nonEmptyString(record['name']) || typeof record['shortForm'] !== 'string')
+            continue;
+        if (typeof record['kind'] !== 'string' || !MEMORY_KINDS.has(record['kind']))
+            continue;
+        if (typeof record['scope'] !== 'string' || !MEMORY_SCOPES.has(record['scope']))
+            continue;
+        out.push({
+            name: record['name'],
+            kind: record['kind'],
+            scope: record['scope'],
+            shortForm: record['shortForm'],
+        });
+    }
+    return out;
+}

package/dist/core/runtime/command-surface.d.ts

@@ -25,9 +25,14 @@ export declare function registrationChatSurface(command: unknown): ChatCommandSu
  *  is pi's already-parsed `argument-hint`. A missing file, unreadable path, or
  *  invalid YAML is not chat-capable. */
 export declare function capturePromptTemplateChatSurfaces(templates: unknown): void;
-/** Capture every prompt template a session currently exposes. A broken getter
- *  leaves its templates uncaptured and therefore fail-closed. */
-export declare function captureSessionPromptTemplateChatSurfaces(session: unknown): void;
+/** Capture the Gateway capabilities declared by one completed resource load. */
+export declare function captureChatCapabilities(input: {
+    commands: unknown;
+    templates: unknown;
+}): void;
+/** Capture every startup-declared command and prompt template a session
+ *  currently exposes. A broken getter leaves that surface fail-closed. */
+export declare function captureSessionChatCapabilities(session: unknown): void;
 /** Read the chat surface captured for this loaded template. An uncaptured
  *  template is not disclosed to chat surfaces. */
 export declare function templateChatSurface(template: unknown): ChatCommandSurface;

package/dist/core/runtime/command-surface.js

@@ -18,6 +18,10 @@
 import { readFileSync } from 'node:fs';
 import { parseFrontmatterGeneric } from '../frontmatter.js';
 const NOT_CAPABLE = { gatewayCapable: false };
+// One resource load declares Gateway capability by extension identity and pi's
+// collision-resolved invocation name. Later registrations from that extension
+// retain only names the load declared.
+let startupGatewayNames = new WeakMap();
 // Pi drops unknown prompt frontmatter keys. This cache restores crouter's
 // metadata without re-reading a template during command disclosure.
 const templateChatSurfaces = new WeakMap();
@@ -31,10 +35,33 @@ export function registrationChatSurface(command) {
     if (typeof command !== 'object' || command === null)
         return NOT_CAPABLE;
     const record = command;
-    if (record['gateway'] !== true)
+    const { sourceInfo, invocationName } = record;
+    if (typeof sourceInfo !== 'object' ||
+        sourceInfo === null ||
+        typeof invocationName !== 'string' ||
+        !startupGatewayNames.get(sourceInfo)?.has(invocationName))
         return NOT_CAPABLE;
     return { gatewayCapable: true, ...hintOf(record['argumentHint']) };
 }
+function captureExtensionCommandSurfaces(commands) {
+    startupGatewayNames = new WeakMap();
+    if (!Array.isArray(commands))
+        return;
+    for (const command of commands) {
+        if (typeof command !== 'object' || command === null)
+            continue;
+        const record = command;
+        const { sourceInfo, invocationName } = record;
+        if (record['gateway'] !== true ||
+            typeof sourceInfo !== 'object' ||
+            sourceInfo === null ||
+            typeof invocationName !== 'string')
+            continue;
+        const names = startupGatewayNames.get(sourceInfo) ?? new Set();
+        names.add(invocationName);
+        startupGatewayNames.set(sourceInfo, names);
+    }
+}
 /** Capture prompt-template chat metadata immediately after pi loads or reloads
  *  its templates. The opt-in is the template file's own frontmatter; the hint
  *  is pi's already-parsed `argument-hint`. A missing file, unreadable path, or
@@ -60,16 +87,25 @@ export function capturePromptTemplateChatSurfaces(templates) {
         templateChatSurfaces.set(template, surface);
     }
 }
-/** Capture every prompt template a session currently exposes. A broken getter
- *  leaves its templates uncaptured and therefore fail-closed. */
-export function captureSessionPromptTemplateChatSurfaces(session) {
+/** Capture the Gateway capabilities declared by one completed resource load. */
+export function captureChatCapabilities(input) {
+    captureExtensionCommandSurfaces(input.commands);
+    capturePromptTemplateChatSurfaces(input.templates);
+}
+/** Capture every startup-declared command and prompt template a session
+ *  currently exposes. A broken getter leaves that surface fail-closed. */
+export function captureSessionChatCapabilities(session) {
     try {
         if (typeof session !== 'object' || session === null)
             return;
-        capturePromptTemplateChatSurfaces(session.promptTemplates);
+        const value = session;
+        captureChatCapabilities({
+            commands: value.extensionRunner?.getRegisteredCommands?.(),
+            templates: value.promptTemplates,
+        });
     }
     catch {
-        // Fail closed when an engine cannot expose its prompt templates.
+        // Fail closed when an engine cannot expose its loaded resources.
     }
 }
 /** Read the chat surface captured for this loaded template. An uncaptured

package/dist/core/runtime/launch-target.d.ts

@@ -0,0 +1,25 @@
+import type { CreateNodeRequest } from '../../api/dto/nodes.js';
+import type { Mode } from '../canvas/types.js';
+import { type ProfileEntry } from '../profiles/manifest.js';
+import { buildLaunchSpecAsync } from './launch.js';
+export interface ResolvedLaunchTarget {
+    profileId: string | null;
+    profile: ProfileEntry | null;
+    kind: string;
+    mode: Mode;
+    cwd: string;
+    launch: Awaited<ReturnType<typeof buildLaunchSpecAsync>>['launch'];
+}
+export declare function resolveCreateKind(kind: string | undefined, profile: ProfileEntry | null): string;
+/** Validate a kind against the same cwd/profile configuration used to build its launch.
+ *  Resolution is subprocess-isolated: crtrd is single-threaded and a config read can
+ *  block indefinitely on a network filesystem. */
+export declare function assertLaunchKind(kind: string, cwd?: string, profileId?: string | null): Promise<void>;
+/** Resolve the exact profile, kind, cwd, mode and launch recipe a create will use. */
+export declare function resolveLaunchTarget(req: CreateNodeRequest, options?: {
+    readOnlyProfileSelection?: boolean;
+    /** Preserve an existing caller's validation boundary before target resolution. */
+    validateKind?: (kind: string) => void | Promise<void>;
+}): Promise<ResolvedLaunchTarget>;
+/** The directory a new node is pinned to. */
+export declare function resolveNodeCwd(req: CreateNodeRequest, parent: string | undefined, profileId: string | null, contextCwd: string): string;

package/dist/core/runtime/launch-target.js

@@ -0,0 +1,54 @@
+import { resolve } from 'node:path';
+import { getNode } from '../canvas/canvas.js';
+import { usage } from '../errors.js';
+import { assertProfileActive, profileHome } from '../profiles/manifest.js';
+import { buildLaunchSpecAsync, readMergedLaunchConfigAsync } from './launch.js';
+import { resolveProfileId } from './spawn.js';
+export function resolveCreateKind(kind, profile) {
+    return kind ?? profile?.manifest.default_kind ?? 'general';
+}
+/** Validate a kind against the same cwd/profile configuration used to build its launch.
+ *  Resolution is subprocess-isolated: crtrd is single-threaded and a config read can
+ *  block indefinitely on a network filesystem. */
+export async function assertLaunchKind(kind, cwd = process.cwd(), profileId = process.env['CRTR_PROFILE_ID'] || null) {
+    const kinds = Object.keys((await readMergedLaunchConfigAsync(cwd, profileId)).kinds);
+    if (!kinds.includes(kind)) {
+        throw usage(`unknown kind: ${kind}`, { received: kind, next: `Valid kinds: ${kinds.sort().join(', ')}.` });
+    }
+}
+/** Resolve the exact profile, kind, cwd, mode and launch recipe a create will use. */
+export async function resolveLaunchTarget(req, options = {}) {
+    const parent = req.parent ?? undefined;
+    const contextCwd = req.cwd ?? process.cwd();
+    const profileId = await resolveProfileId(req.profile, parent ?? null, contextCwd, {
+        readOnlySelection: options.readOnlyProfileSelection,
+    });
+    const profile = assertProfileActive(profileId);
+    const kind = resolveCreateKind(req.kind, profile);
+    await options.validateKind?.(kind);
+    const cwd = resolveNodeCwd({ ...req, kind }, parent, profileId, contextCwd);
+    if (options.validateKind === undefined)
+        await assertLaunchKind(kind, cwd, profileId);
+    const mode = (req.mode ?? 'base');
+    const launch = (await buildLaunchSpecAsync(kind, mode, {
+        lifecycle: req.root === true ? (req.root_lifecycle ?? 'resident') : 'terminal',
+        hasManager: req.root !== true,
+        ...(req.model !== undefined ? { model: req.model } : {}),
+        cwd,
+        profileId,
+    })).launch;
+    return { profileId, profile, kind, mode, cwd, launch };
+}
+/** The directory a new node is pinned to. */
+export function resolveNodeCwd(req, parent, profileId, contextCwd) {
+    if (req.pin_cwd !== undefined && req.pin_cwd !== '')
+        return resolve(req.pin_cwd);
+    if (parent != null) {
+        const spawner = getNode(parent);
+        if (spawner !== null)
+            return spawner.cwd;
+    }
+    if (req.cwd !== undefined && req.cwd !== '')
+        return resolve(req.cwd);
+    return profileHome(profileId) ?? contextCwd;
+}

package/dist/core/runtime/persona.js

@@ -79,15 +79,15 @@ function baseModeGuidance() {
 }
 // The lifecycle transition prose is the SAME contract that's baked into the
 // static system prompt at birth — so both load from the one source
-// (`personas/lifecycle/{terminal,resident}.md`) and can never drift. The flip
+// (`turn-lifecycle/{terminal,resident}.md`) and can never drift. The flip
 // only re-delivers that fragment as the node's new-state steer.
 /** terminal → resident: interactable, never forced to submit. */
 function residentLifecycleGuidance() {
-    return loadMemoryBody('lifecycle/resident');
+    return loadMemoryBody('turn-lifecycle/resident');
 }
 /** resident → terminal: owes a final, reaps when done. */
 function terminalLifecycleGuidance() {
-    return loadMemoryBody('lifecycle/terminal');
+    return loadMemoryBody('turn-lifecycle/terminal');
 }
 /** Build the injected transition prompt for a `from → to` persona change.
  *  Concatenates the relevant section per changed axis (both when both changed).

package/dist/core/runtime/prospective-inventory-cli.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/core/runtime/prospective-inventory-cli.js

@@ -0,0 +1,61 @@
+import { readFileSync, writeFileSync } from 'node:fs';
+import { DefaultResourceLoader, ExtensionRunner, getAgentDir, } from '@earendil-works/pi-coding-agent';
+import { buildRefInventory } from '../memory/inline-ref-inventory.js';
+import { gatewayCommandRows, gatewayMemoryRows } from './chat-inventory-rows.js';
+import { captureChatCapabilities, registrationChatSurface, templateChatSurface, } from './command-surface.js';
+function parseInput() {
+    const parsed = JSON.parse(readFileSync(0, 'utf8'));
+    if (typeof parsed !== 'object' || parsed === null)
+        throw new Error('preflight input must be an object');
+    const extensions = parsed.extensions;
+    if (!Array.isArray(extensions) || !extensions.every((value) => typeof value === 'string')) {
+        throw new Error('preflight input extensions must be strings');
+    }
+    return { extensions };
+}
+async function main() {
+    const { extensions } = parseInput();
+    const cwd = process.cwd();
+    const loader = new DefaultResourceLoader({
+        cwd,
+        agentDir: getAgentDir(),
+        additionalExtensionPaths: extensions,
+        noContextFiles: true,
+    });
+    await loader.reload();
+    const loaded = loader.getExtensions();
+    const templates = loader.getPrompts().prompts;
+    // getRegisteredCommands only reads extension maps and applies pi's collision
+    // naming. The unbound placeholders make every action path unavailable.
+    const runner = new ExtensionRunner(loaded.extensions, loaded.runtime, cwd, undefined, undefined);
+    const commands = runner.getRegisteredCommands();
+    captureChatCapabilities({ commands, templates });
+    const disclosures = [
+        ...commands.map((command) => {
+            const expansion = command.expansion;
+            return {
+                name: command.invocationName,
+                description: command.description ?? '',
+                source: 'command',
+                ...(expansion !== undefined ? { expansion } : {}),
+                ...registrationChatSurface(command),
+            };
+        }),
+        ...templates.map((template) => ({
+            name: template.name,
+            description: template.description,
+            source: 'template',
+            template: template.content,
+            ...templateChatSurface(template),
+        })),
+    ];
+    const memory = buildRefInventory();
+    writeFileSync(3, `${JSON.stringify({
+        commands: gatewayCommandRows(disclosures),
+        memory_refs: gatewayMemoryRows(memory.refs),
+    })}\n`);
+}
+main().catch((error) => {
+    process.stderr.write(`${error instanceof Error ? error.stack ?? error.message : String(error)}\n`);
+    process.exitCode = 1;
+});

package/dist/core/runtime/prospective-inventory.d.ts

@@ -0,0 +1,10 @@
+import type { ChatInventoryCommandDTO, ChatInventoryMemoryRefDTO } from '../../api/dto/chat-inventory.js';
+export interface ProspectiveInventoryRows {
+    commands: ChatInventoryCommandDTO[];
+    memory_refs: ChatInventoryMemoryRefDTO[];
+}
+export declare function runProspectiveInventory(input: {
+    cwd: string;
+    profileId: string | null;
+    extensions: string[];
+}): Promise<ProspectiveInventoryRows>;

package/dist/core/runtime/prospective-inventory.js

@@ -0,0 +1,88 @@
+import { spawn } from 'node:child_process';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { chatInventoryCommandRows, chatInventoryMemoryRows } from './chat-inventory-rows.js';
+import { FRONT_DOOR_ENV } from './front-door-env.js';
+const PREFLIGHT_TIMEOUT_MS = 15_000;
+function entryPath() {
+    return join(dirname(fileURLToPath(import.meta.url)), 'prospective-inventory-cli.js');
+}
+function parseDocument(response) {
+    const parsed = JSON.parse(response.trim());
+    if (typeof parsed !== 'object' || parsed === null)
+        throw new Error('preflight output must be an object');
+    const record = parsed;
+    if (!Array.isArray(record['commands']) || !Array.isArray(record['memory_refs'])) {
+        throw new Error('preflight output must contain command and memory-ref arrays');
+    }
+    return {
+        commands: chatInventoryCommandRows(record['commands']),
+        memory_refs: chatInventoryMemoryRows(record['memory_refs']),
+    };
+}
+export function runProspectiveInventory(input) {
+    return new Promise((resolve, reject) => {
+        const env = {
+            ...process.env,
+            CRTR_PROFILE_ID: input.profileId ?? '',
+            [FRONT_DOOR_ENV]: '1',
+        };
+        delete env['CRTR_NODE_ID'];
+        const child = spawn(process.execPath, [entryPath()], {
+            cwd: input.cwd,
+            env,
+            stdio: ['pipe', 'pipe', 'pipe', 'pipe'],
+        });
+        let stdout = '';
+        let stderr = '';
+        let response = '';
+        let settled = false;
+        const timer = setTimeout(() => {
+            if (settled)
+                return;
+            settled = true;
+            child.kill('SIGKILL');
+            reject(new Error('prospective inventory preflight timed out'));
+        }, PREFLIGHT_TIMEOUT_MS);
+        timer.unref?.();
+        child.stdout.setEncoding('utf8');
+        child.stderr.setEncoding('utf8');
+        const responseStream = child.stdio[3];
+        if (responseStream === null || responseStream === undefined || !('setEncoding' in responseStream)) {
+            clearTimeout(timer);
+            child.kill('SIGKILL');
+            reject(new Error('prospective inventory preflight response channel unavailable'));
+            return;
+        }
+        responseStream.setEncoding('utf8');
+        child.stdout.on('data', (chunk) => { stdout += chunk; });
+        child.stderr.on('data', (chunk) => { stderr += chunk; });
+        responseStream.on('data', (chunk) => { response += chunk; });
+        child.on('error', (error) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            reject(error);
+        });
+        child.on('close', (code, signal) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            const diagnostics = [stderr.trim(), stdout.trim()].filter(Boolean).join('\n');
+            if (code !== 0) {
+                reject(new Error(`prospective inventory preflight exited ${code ?? signal ?? 'unknown'}${diagnostics === '' ? '' : `: ${diagnostics}`}`));
+                return;
+            }
+            try {
+                resolve(parseDocument(response));
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                reject(new Error(`${message}${diagnostics === '' ? '' : `: ${diagnostics}`}`));
+            }
+        });
+        child.stdin.end(JSON.stringify({ extensions: input.extensions }));
+    });
+}

package/dist/core/runtime/spawn.d.ts

@@ -88,7 +88,9 @@ export declare function resolveForkSource(value: string): string;
  *  shell, not from inside a node — there is no profile to inherit, so this runs
  *  the same startup selector the front door uses (MRU covering `cwd`, else the
  *  root-profile prompt/default). */
-export declare function resolveProfileId(explicit: string | null | undefined, spawner: string | null, cwd: string): Promise<string | null>;
+export declare function resolveProfileId(explicit: string | null | undefined, spawner: string | null, cwd: string, options?: {
+    readOnlySelection?: boolean;
+}): Promise<string | null>;
 /** Reject a permanently invalid launch recipe against the registry that will
  * serve it. Registered-but-unauthenticated/cooling requests intentionally pass
  * this authoring check so broker policy for transient availability is unchanged. */

package/dist/core/runtime/spawn.js

@@ -13,7 +13,7 @@ import { accessSync, constants, cpSync, readdirSync, existsSync, rmSync } from '
 import { isAbsolute, resolve, join } from 'node:path';
 import { spawnNode, currentNodeContext, rootOfSpine, newNodeId, preflightNodeId } from './nodes.js';
 import { loadProfileManifest } from '../profiles/manifest.js';
-import { selectProfileForCwd } from '../profiles/select.js';
+import { selectProfileForCwd, selectProfileForCwdReadOnly } from '../profiles/select.js';
 import { buildLaunchSpecAsync, buildPiArgv } from './launch.js';
 import { createManagedWorktree, rollbackManagedWorktree } from '../worktree.js';
 import { usage, brokerLaunchFailed } from '../errors.js';
@@ -153,7 +153,7 @@ export function resolveForkSource(value) {
  *  shell, not from inside a node — there is no profile to inherit, so this runs
  *  the same startup selector the front door uses (MRU covering `cwd`, else the
  *  root-profile prompt/default). */
-export async function resolveProfileId(explicit, spawner, cwd) {
+export async function resolveProfileId(explicit, spawner, cwd, options = {}) {
     if (explicit === null)
         return null;
     if (explicit !== undefined && explicit !== '') {
@@ -161,7 +161,9 @@ export async function resolveProfileId(explicit, spawner, cwd) {
     }
     if (spawner !== null)
         return getNode(spawner)?.profile_id ?? null;
-    return selectProfileForCwd(cwd);
+    return options.readOnlySelection === true
+        ? selectProfileForCwdReadOnly(cwd)
+        : selectProfileForCwd(cwd);
 }
 function requestFromLaunch(launch) {
     const intent = launch.modelIntent === undefined

package/dist/core/substrate/frontmatter-validation.d.ts

@@ -1,3 +1,4 @@
+import { type SurfaceEntry } from './schema.js';
 /** Strict validation of one raw routing entry. Runtime parsing deliberately
  * tolerates malformed docs; this authoring/preflight contract does not. */
 export declare function lintSubstrateSurfaces(value: unknown): string | null;
@@ -6,8 +7,4 @@ export declare function lintSubstrateFrontmatter(fm: Record<string, unknown> | n
 /** Compatibility name for consumers that adopted lint's former export. */
 export declare const lintSubstrateSchema: typeof lintSubstrateFrontmatter;
 /** Parsed routing entries for checks that run after strict validation. */
-export declare function parsedSubstrateSurfaces(fm: Record<string, unknown>): {
-    on: string;
-    at: string;
-    match?: string[];
-}[];
+export declare function parsedSubstrateSurfaces(fm: Record<string, unknown>): SurfaceEntry[];

package/dist/core/substrate/frontmatter-validation.js

@@ -1,6 +1,6 @@
 import { isDocKind, parseSubstrateFrontmatter, SURFACE_EVENTS, SURFACE_RUNGS } from './schema.js';
 const RETIRED_FIELDS = ['system-prompt-visibility', 'file-read-visibility', 'applies-to', 'read-when'];
-const SURFACE_ENTRY_KEYS = ['on', 'match', 'match-frontmatter', 'at'];
+const SURFACE_ENTRY_KEYS = ['on', 'match', 'match-frontmatter', 'gate', 'at'];
 const SUPPRESSIBLE_RULES = ['length', 'broad-memory-read'];
 /** Strict validation of one raw routing entry. Runtime parsing deliberately
  * tolerates malformed docs; this authoring/preflight contract does not. */
@@ -8,15 +8,15 @@ export function lintSubstrateSurfaces(value) {
     if (value === undefined)
         return null;
     if (!Array.isArray(value))
-        return `invalid surfaces: ${JSON.stringify(value)} (expected a list of {on, at, match?, match-frontmatter?} entries)`;
+        return `invalid surfaces: ${JSON.stringify(value)} (expected a list of {on, at, match?, match-frontmatter?, gate?} entries)`;
     for (const raw of value) {
         if (raw === null || typeof raw !== 'object' || Array.isArray(raw)) {
-            return `invalid surfaces entry: ${JSON.stringify(raw)} (expected an {on, at, match?, match-frontmatter?} object)`;
+            return `invalid surfaces entry: ${JSON.stringify(raw)} (expected an {on, at, match?, match-frontmatter?, gate?} object)`;
         }
         const entry = raw;
         for (const key of Object.keys(entry)) {
             if (!SURFACE_ENTRY_KEYS.includes(key)) {
-                return `invalid surfaces entry: unknown key \`${key}\` (an entry carries only on, match, match-frontmatter, at)`;
+                return `invalid surfaces entry: unknown key \`${key}\` (an entry carries only on, match, match-frontmatter, gate, at)`;
             }
         }
         const on = entry['on'];
@@ -50,6 +50,10 @@ export function lintSubstrateSurfaces(value) {
         if ((on === 'read' || on === 'memory-read' || on === 'command') && !hasMatch && matchFrontmatter === undefined) {
             return `invalid surfaces entry: a \`${on}\` entry requires \`match\`${on === 'read' ? ' or `match-frontmatter`' : ''}`;
         }
+        const gate = entry['gate'];
+        if (gate !== undefined && (gate === null || typeof gate !== 'object' || Array.isArray(gate))) {
+            return `invalid surfaces entry \`gate\`: ${JSON.stringify(gate)} (expected a field→matcher object)`;
+        }
     }
     return null;
 }

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

@@ -1,4 +1,4 @@
-import type { SubstrateDoc } from './schema.js';
+import type { SubstrateDoc, SurfaceEntry } from './schema.js';
 import type { NodeConfigSubject } from './subject-fields.js';
 /** Does `doc` pass its gate for `subject`?
  *
@@ -11,3 +11,6 @@ import type { NodeConfigSubject } from './subject-fields.js';
  *  for this node; it remains findable by `crtr memory find` (search ignores
  *  gate + rung). */
 export declare function gatePasses(doc: SubstrateDoc, subject: NodeConfigSubject): boolean;
+/** Does a surface entry participate for `subject`? A missing subject cannot
+ * satisfy an entry gate; entries without one remain eligible. */
+export declare function surfaceEntryGatePasses(entry: Pick<SurfaceEntry, 'gate'>, subject: NodeConfigSubject | null): boolean;

package/dist/core/substrate/gate.js

@@ -19,3 +19,8 @@ export function gatePasses(doc, subject) {
         return true;
     return evalCondition(doc.gate, subject);
 }
+/** Does a surface entry participate for `subject`? A missing subject cannot
+ * satisfy an entry gate; entries without one remain eligible. */
+export function surfaceEntryGatePasses(entry, subject) {
+    return entry.gate === undefined || (subject !== null && evalCondition(entry.gate, subject));
+}