@north-light/crouter 0.3.180 → 0.3.181

package/dist/core/command-manifests/manifest.js

@@ -37,17 +37,17 @@ export function validateCommandManifest(raw, options) {
     };
     // Top-level structure check
     if (!isRecord(raw)) {
-        issue('command_manifest_invalid', 'manifest must be an object', typeName(raw), options.transport === 'http' ? '{ schemaVersion, baseUrl?, timeouts?, mounts }' : '{ schemaVersion, mounts }', 'Provide a valid JSON manifest object.');
+        issue('command_manifest_invalid', 'manifest must be an object', typeName(raw), options.transport === 'http' ? '{ schemaVersion, baseUrl?, timeouts?, mounts, helpAddenda? }' : '{ schemaVersion, mounts, helpAddenda? }', 'Provide a valid JSON manifest object.');
         return { issues };
     }
     // Check for unknown top-level keys
     const topKeys = Object.keys(raw);
     const allowedTopKeys = options.transport === 'http'
-        ? new Set(['schemaVersion', 'baseUrl', 'timeouts', 'mounts'])
-        : new Set(['schemaVersion', 'mounts']);
+        ? new Set(['schemaVersion', 'baseUrl', 'timeouts', 'mounts', 'helpAddenda'])
+        : new Set(['schemaVersion', 'mounts', 'helpAddenda']);
     const unknownKeys = topKeys.filter((k) => !allowedTopKeys.has(k));
     if (unknownKeys.length > 0) {
-        issue('command_manifest_invalid', `unknown top-level keys`, unknownKeys.join(', '), options.transport === 'http' ? 'only: schemaVersion, baseUrl, timeouts, mounts' : 'only: schemaVersion, mounts', 'Remove the unknown keys.');
+        issue('command_manifest_invalid', `unknown top-level keys`, unknownKeys.join(', '), options.transport === 'http' ? 'only: schemaVersion, baseUrl, timeouts, mounts, helpAddenda' : 'only: schemaVersion, mounts, helpAddenda', 'Remove the unknown keys.');
         return { issues };
     }
     // Validate schemaVersion
@@ -83,6 +83,15 @@ export function validateCommandManifest(raw, options) {
             return { issues };
         timeouts = t;
     }
+    // Validate optional helpAddenda (both transports)
+    let helpAddenda;
+    if (raw['helpAddenda'] !== undefined) {
+        const h = validateHelpAddenda(raw['helpAddenda'], options.coreCommandPaths, issue);
+        if (h === null)
+            return { issues };
+        if (Object.keys(h).length > 0)
+            helpAddenda = h;
+    }
     // Validate mounts (required, non-empty)
     const mounts = raw['mounts'];
     if (!Array.isArray(mounts)) {
@@ -112,6 +121,7 @@ export function validateCommandManifest(raw, options) {
                 schemaVersion: 1,
                 ...(baseUrl !== undefined ? { baseUrl } : {}),
                 ...(timeouts !== undefined ? { timeouts } : {}),
+                ...(helpAddenda !== undefined ? { helpAddenda } : {}),
                 roots,
             },
             issues: [],
@@ -146,6 +156,37 @@ function validateTimeouts(raw, issue) {
     }
     return out;
 }
+// ---------------------------------------------------------------------------
+// Help addenda validation
+// ---------------------------------------------------------------------------
+/** Validate the optional top-level `helpAddenda` map: core command path →
+ *  addendum text rendered as an attributed block beneath that core command's
+ *  help. When the caller supplies the core command path set, a key naming no
+ *  existing core path is rejected outright — a typo fails at the gate, never
+ *  silently at render. */
+function validateHelpAddenda(raw, coreCommandPaths, issue) {
+    if (!isRecord(raw)) {
+        issue('command_manifest_invalid', 'helpAddenda must be an object', typeName(raw), 'a map of core command path → addendum text', 'Fix helpAddenda.', 'helpAddenda');
+        return null;
+    }
+    const out = {};
+    for (const [key, value] of Object.entries(raw)) {
+        if (key.split(' ').some((t) => !KEBAB.test(t))) {
+            issue('command_help_addendum_invalid', 'helpAddenda key must be a space-separated core command path', key, 'kebab tokens separated by single spaces (e.g. "cron" or "cron add")', 'Fix the helpAddenda key.', `helpAddenda.${key}`);
+            return null;
+        }
+        if (typeof value !== 'string' || value.length === 0) {
+            issue('command_manifest_invalid', 'helpAddenda value must be a non-empty string', typeof value === 'string' ? 'empty string' : typeName(value), 'non-empty addendum text', 'Fix the helpAddenda value.', `helpAddenda.${key}`);
+            return null;
+        }
+        if (coreCommandPaths !== undefined && !coreCommandPaths.has(key)) {
+            issue('command_help_addendum_invalid', 'helpAddenda key names no crtr core command path', key, 'an existing core command path (e.g. "cron", "cron add")', 'Fix the key or remove the addendum.', `helpAddenda.${key}`);
+            return null;
+        }
+        out[key] = value;
+    }
+    return out;
+}
 function validateMount(raw, index, transport, issue) {
     const path = `mounts[${index}]`;
     if (!isRecord(raw)) {

package/dist/core/command-manifests/schema.d.ts

@@ -78,7 +78,7 @@ export interface CommandManifestIssue {
     expected: string;
     next: string;
 }
-export type CommandIssueCode = 'command_manifest_unreadable' | 'command_manifest_invalid' | 'command_schema_version' | 'command_path_unsafe' | 'command_not_executable' | 'command_parent_invalid' | 'command_node_invalid' | 'command_collision' | 'command_rest_invalid';
+export type CommandIssueCode = 'command_manifest_unreadable' | 'command_manifest_invalid' | 'command_schema_version' | 'command_path_unsafe' | 'command_not_executable' | 'command_parent_invalid' | 'command_node_invalid' | 'command_collision' | 'command_help_addendum_invalid' | 'command_rest_invalid';
 type IssueFn = (code: CommandIssueCode, message: string, received: string, expected: string, next: string, path?: string) => void;
 export type TransportKind = 'exec' | 'http';
 export declare function validateCommandNode(raw: unknown, path: string[], topLevel: boolean, transport: TransportKind, issue: IssueFn): DeclBranch<DeclLeaf> | DeclLeaf | null;

package/dist/core/command-plugins/bundle.d.ts

@@ -26,4 +26,5 @@ export interface PluginBundleValidation {
 /** Validate a Core-served plugin directory archive entirely in memory. */
 export declare function validatePluginBundle(archive: Uint8Array, options: {
     reservedCoreNames: ReadonlySet<string>;
+    coreCommandPaths?: ReadonlySet<string>;
 }): Promise<PluginBundleValidation>;

package/dist/core/command-plugins/bundle.js

@@ -141,7 +141,7 @@ function parseBundleMetadata(bytes) {
     }
     return undefined;
 }
-function parseCommands(bytes, reservedCoreNames) {
+function parseCommands(bytes, reservedCoreNames, coreCommandPaths) {
     let raw;
     try {
         raw = JSON.parse(Buffer.from(bytes).toString('utf8'));
@@ -151,7 +151,7 @@ function parseCommands(bytes, reservedCoreNames) {
             issues: [bundleInvalid('commands.json is not valid JSON', 'invalid JSON', 'a valid command-manifest JSON object', 'Regenerate commands.json.', 'commands.json')],
         };
     }
-    const validation = validateCommandManifest(raw, { transport: 'http', reservedCoreNames });
+    const validation = validateCommandManifest(raw, { transport: 'http', reservedCoreNames, ...(coreCommandPaths !== undefined ? { coreCommandPaths } : {}) });
     return {
         ...(validation.manifest !== undefined ? { commands: validation.manifest } : {}),
         issues: validation.issues,
@@ -178,7 +178,7 @@ export async function validatePluginBundle(archive, options) {
     const metadataIssue = parseBundleMetadata(bundle.bytes);
     if (metadataIssue !== undefined)
         return { issues: [metadataIssue] };
-    const commandValidation = parseCommands(commands.bytes, options.reservedCoreNames);
+    const commandValidation = parseCommands(commands.bytes, options.reservedCoreNames, options.coreCommandPaths);
     if (commandValidation.commands === undefined)
         return { issues: commandValidation.issues };
     return {

package/dist/core/command-plugins/discovery.d.ts

@@ -19,13 +19,16 @@ export interface PluginCommandValidation {
     plugin: InstalledPlugin;
     manifestPath: string;
     transport?: PluginTransport;
+    /** The validated manifest — present only when validation fully passed.
+     *  Carries `helpAddenda` for the help-render lookup. */
+    manifest?: ValidatedCommandManifest;
     contributions: ValidatedContribution[];
     issues: CommandDiscoveryIssue[];
 }
 export declare function effectiveCommandPlugins(startDir?: string, profileId?: string | null): InstalledPlugin[];
-export declare function validatePluginCommands(plugin: InstalledPlugin, reservedNames?: ReadonlySet<string>): PluginCommandValidation;
+export declare function validatePluginCommands(plugin: InstalledPlugin, reservedNames?: ReadonlySet<string>, coreCommandPaths?: ReadonlySet<string>): PluginCommandValidation;
 export declare function discoverPluginCommandCandidates(startDir?: string, profileId?: string | null): PluginCommandValidation[];
-export declare function validateEffectiveCommandPlugins(reservedNames: ReadonlySet<string>, startDir?: string, profileId?: string | null): PluginCommandValidation[];
+export declare function validateEffectiveCommandPlugins(reservedNames: ReadonlySet<string>, startDir?: string, profileId?: string | null, coreCommandPaths?: ReadonlySet<string>): PluginCommandValidation[];
 export declare function discoverCommandContributions(reservedNames: ReadonlySet<string>, startDir?: string, profileId?: string | null): {
     contributions: ValidatedContribution[];
     issues: CommandDiscoveryIssue[];

package/dist/core/command-plugins/discovery.js

@@ -81,7 +81,7 @@ function validateExecExecutable(plugin, transport, manifest, issues) {
     }
     return { kind: 'exec', executable };
 }
-export function validatePluginCommands(plugin, reservedNames = new Set()) {
+export function validatePluginCommands(plugin, reservedNames = new Set(), coreCommandPaths) {
     const issues = [];
     const commands = plugin.manifest.commands;
     const transportRaw = plugin.manifest.transport;
@@ -120,7 +120,7 @@ export function validatePluginCommands(plugin, reservedNames = new Set()) {
         issues.push({ code: 'command_manifest_invalid', plugin: plugin.name, message: 'commands.json is not valid JSON', received: safe, expected: 'a JSON object', next: 'Regenerate commands.json.' });
         return { plugin, manifestPath, transport, contributions: [], issues };
     }
-    const validation = validateCommandManifest(raw, { transport: transport.kind, reservedCoreNames: reservedNames });
+    const validation = validateCommandManifest(raw, { transport: transport.kind, reservedCoreNames: reservedNames, ...(coreCommandPaths !== undefined ? { coreCommandPaths } : {}) });
     if (validation.manifest === undefined) {
         validation.issues.forEach(issueFor(plugin, issues));
         return { plugin, manifestPath, transport, contributions: [], issues };
@@ -130,13 +130,13 @@ export function validatePluginCommands(plugin, reservedNames = new Set()) {
         : transport;
     if (resolvedTransport === undefined)
         return { plugin, manifestPath, transport, contributions: [], issues };
-    return { plugin, manifestPath, transport: resolvedTransport, contributions: validation.manifest.roots.map((node) => ({ plugin, transport: resolvedTransport, node, manifest: validation.manifest })), issues };
+    return { plugin, manifestPath, transport: resolvedTransport, manifest: validation.manifest, contributions: validation.manifest.roots.map((node) => ({ plugin, transport: resolvedTransport, node, manifest: validation.manifest })), issues };
 }
 export function discoverPluginCommandCandidates(startDir = process.cwd(), profileId) {
     return effectiveCommandPlugins(startDir, profileId).map((plugin) => validatePluginCommands(plugin));
 }
-export function validateEffectiveCommandPlugins(reservedNames, startDir = process.cwd(), profileId) {
-    const validations = effectiveCommandPlugins(startDir, profileId).map((plugin) => validatePluginCommands(plugin, reservedNames));
+export function validateEffectiveCommandPlugins(reservedNames, startDir = process.cwd(), profileId, coreCommandPaths) {
+    const validations = effectiveCommandPlugins(startDir, profileId).map((plugin) => validatePluginCommands(plugin, reservedNames, coreCommandPaths));
     const claims = new Map();
     for (const validation of validations)
         for (const contribution of validation.contributions)

package/dist/core/command-plugins/help-addenda.d.ts

@@ -0,0 +1,12 @@
+export interface HelpAddendum {
+    plugin: string;
+    text: string;
+}
+/** Collect every enabled plugin's addendum targeting `commandPath` (the
+ *  space-joined walked path, e.g. "cron add"), in plugin-name order. `gate`
+ *  carries the strict-validation inputs the install/bundle gates use; the
+ *  help renderer already holds both (build-root exports them). */
+export declare function collectHelpAddenda(commandPath: string, gate: {
+    reservedCoreNames: ReadonlySet<string>;
+    coreCommandPaths: ReadonlySet<string>;
+}, startDir?: string, profileId?: string | null): HelpAddendum[];

package/dist/core/command-plugins/help-addenda.js

@@ -0,0 +1,30 @@
+// Plugin help addenda: a command plugin may append attributed product guidance
+// beneath a CORE command's help (`helpAddenda` in its command manifest).
+// Append-only, never replace — a plugin cannot alter substrate contract text.
+//
+// This module is the help-render lookup. It loads only on the help path
+// (dynamic import from runCli) and reads stored manifest bytes only (no
+// network). The caller supplies the SAME inputs the install/bundle gates pass
+// to `validateCommandManifest` — the reserved core names and the full core
+// command path set — so this lookup reproduces the gate's exact verdict: a
+// manifest whose `helpAddenda` was rejected at ingress (reported there as a
+// typed issue, e.g. `command_help_addendum_invalid`) contributes nothing at
+// render either. Ingress report and render can never disagree; nothing
+// disappears here that was not already loudly rejected at the gate.
+import { effectiveCommandPlugins, validatePluginCommands } from './discovery.js';
+/** Collect every enabled plugin's addendum targeting `commandPath` (the
+ *  space-joined walked path, e.g. "cron add"), in plugin-name order. `gate`
+ *  carries the strict-validation inputs the install/bundle gates use; the
+ *  help renderer already holds both (build-root exports them). */
+export function collectHelpAddenda(commandPath, gate, startDir, profileId) {
+    if (commandPath.length === 0)
+        return [];
+    const out = [];
+    for (const plugin of effectiveCommandPlugins(startDir, profileId)) {
+        const text = validatePluginCommands(plugin, gate.reservedCoreNames, gate.coreCommandPaths).manifest?.helpAddenda?.[commandPath];
+        if (text !== undefined)
+            out.push({ plugin: plugin.name, text });
+    }
+    out.sort((a, b) => a.plugin.localeCompare(b.plugin));
+    return out;
+}

package/dist/core/command.js

@@ -187,6 +187,29 @@ function renderNode(node) {
         return renderBranch(node.help);
     return renderLeafArgv(node.help);
 }
+/** Render a node's help plus any plugin help addenda targeting its walked
+ *  command path — append-only, attributed blocks a plugin adds beneath core
+ *  contract text, never inside it. Plugin discovery loads only here (dynamic
+ *  import on the help path), so the dispatch path's module graph and cold
+ *  start are unchanged; the lookup reads stored manifest bytes only. The
+ *  lookup receives the install gate's exact strict-validation inputs (reserved
+ *  core names + the full core command path set, both from build-root), so a
+ *  manifest rejected at ingress contributes nothing here either — loading
+ *  every subtree for that path set is a help-path-only cost. */
+async function renderNodeWithAddenda(node, path) {
+    const body = renderNode(node);
+    if (path.length === 0)
+        return body;
+    const [{ collectHelpAddenda }, { SUBTREE_NAMES, coreCommandPaths }] = await Promise.all([
+        import('./command-plugins/help-addenda.js'),
+        import('../build-root.js'),
+    ]);
+    const addenda = collectHelpAddenda(path.join(' '), {
+        reservedCoreNames: new Set(SUBTREE_NAMES),
+        coreCommandPaths: await coreCommandPaths(),
+    });
+    return body + addenda.map((a) => `\n\n<plugin-help plugin="${a.plugin}">\n${a.text}\n</plugin-help>`).join('');
+}
 function helpRequested(remaining) {
     return remaining.some((t) => t === '-h' || t === '--help');
 }
@@ -599,13 +622,13 @@ export async function runCli(root, argv) {
         }
         // Help anywhere in remaining tokens → print node help and exit
         if (helpRequested(remaining)) {
-            process.stdout.write(renderNode(node) + '\n');
+            process.stdout.write(await renderNodeWithAddenda(node, path) + '\n');
             process.exitCode = ExitCode.SUCCESS;
             return;
         }
         // Bare branch or bare root (no -h, remaining fully consumed) → help surface
         if (node.kind === 'root' || node.kind === 'branch') {
-            process.stdout.write(renderNode(node) + '\n');
+            process.stdout.write(await renderNodeWithAddenda(node, path) + '\n');
             process.exitCode = ExitCode.SUCCESS;
             return;
         }

package/dist/core/config.js

@@ -50,7 +50,6 @@ export function readState(scope) {
         marketplaces: existing.marketplaces ?? {},
         plugins: existing.plugins ?? {},
         last_self_check: existing.last_self_check,
-        bootstrap_done: existing.bootstrap_done,
         activeCanvas: existing.activeCanvas ?? null,
     };
 }

package/dist/core/human/convention.d.ts

@@ -10,7 +10,6 @@ export declare function isResolved(dir: string): boolean;
 export declare function isClaimed(dir: string): boolean;
 /** Resolve and verify a ticket directory without a registry. */
 export declare function requireTicket(dir: string): string;
-export declare function stampCanvasNode(deck: Deck): void;
 export declare function atomicWriteJson(path: string, value: unknown): void;
 /** Publish one immutable JSON record without replacing an existing winner. */
 export declare function publishJsonExclusive(path: string, value: unknown): boolean;

package/dist/core/human/convention.js

@@ -23,12 +23,6 @@ export function requireTicket(dir) {
     }
     return canonicalDir;
 }
-export function stampCanvasNode(deck) {
-    const id = process.env['CRTR_NODE_ID'];
-    if (id === undefined || id.trim() === '' || deck.source?.nodeId)
-        return;
-    deck.source = { ...(deck.source ?? {}), nodeId: id };
-}
 export function atomicWriteJson(path, value) {
     const tmp = `${path}.${process.pid}.${Math.random().toString(16).slice(2)}.tmp`;
     mkdirSync(dirname(path), { recursive: true });

package/dist/core/keybindings/inbox.d.ts

@@ -8,13 +8,11 @@ import type { BindingResolution } from './types.js';
  *  current state; callers holding a live snapshot (e.g. the attach viewer) pass
  *  it so a `/reload` rebind is honored. */
 export declare function inboxShortcut(bindings?: BindingResolution<BindingId>): string | null;
-/** Closed-inbox footer affordance: "<shortcut> inbox", or the CLI fallback
+/** The shortcut belongs to surfaces that actually own the key — the viewer
+ *  footer and the settings surface. Agent-facing command output never names it:
+ *  an agent repeats the gesture back to a human who may be reading on a screen
+ *  where it means nothing.
+ *
+ *  Closed-inbox footer affordance: "<shortcut> inbox", or the CLI fallback
  *  `crtr human list` when the binding is disabled. */
 export declare function inboxOpenHint(bindings?: BindingResolution<BindingId>): string;
-/** Bare token naming the inbox affordance for a parenthetical — the resolved
- *  shortcut (e.g. `Alt+I`), or the backtick-quoted CLI form when disabled. */
-export declare function inboxHint(bindings?: BindingResolution<BindingId>): string;
-/** Imperative clause telling the human how to open the inbox — "press
- *  <shortcut> in a node viewer (or run `crtr human list` for the queue)", or just
- *  the CLI form when the binding is disabled. */
-export declare function inboxOpenInstruction(bindings?: BindingResolution<BindingId>): string;

package/dist/core/keybindings/inbox.js

@@ -12,23 +12,14 @@ export function inboxShortcut(bindings = resolveUserKeybindings()) {
     const gestures = bindings.gestures(INBOX_TOGGLE);
     return gestures.length > 0 ? gestures.map(formatGesture).join(' / ') : null;
 }
-/** Closed-inbox footer affordance: "<shortcut> inbox", or the CLI fallback
+/** The shortcut belongs to surfaces that actually own the key — the viewer
+ *  footer and the settings surface. Agent-facing command output never names it:
+ *  an agent repeats the gesture back to a human who may be reading on a screen
+ *  where it means nothing.
+ *
+ *  Closed-inbox footer affordance: "<shortcut> inbox", or the CLI fallback
  *  `crtr human list` when the binding is disabled. */
 export function inboxOpenHint(bindings) {
     const shortcut = inboxShortcut(bindings);
     return shortcut !== null ? `${shortcut} inbox` : 'crtr human list';
 }
-/** Bare token naming the inbox affordance for a parenthetical — the resolved
- *  shortcut (e.g. `Alt+I`), or the backtick-quoted CLI form when disabled. */
-export function inboxHint(bindings) {
-    return inboxShortcut(bindings) ?? '`crtr human list`';
-}
-/** Imperative clause telling the human how to open the inbox — "press
- *  <shortcut> in a node viewer (or run `crtr human list` for the queue)", or just
- *  the CLI form when the binding is disabled. */
-export function inboxOpenInstruction(bindings) {
-    const shortcut = inboxShortcut(bindings);
-    return shortcut !== null
-        ? `press ${shortcut} in a node viewer (or run \`crtr human list\` for the queue)`
-        : 'run `crtr human list` for the queue';
-}

package/dist/core/keybindings/index.d.ts

@@ -1,7 +1,7 @@
 export { BINDING_CATALOG, BINDING_IDS, SAFETY_REQUIREMENTS, isAttachPaneBinding, type BindingId, } from './catalog.js';
 export { GestureSyntaxError, KeybindingValidationError, normalizeGesture, normalizeSparseOverrides, normalizeStroke, resolveKeybindings, resolveUserKeybindingSettings, resolveUserKeybindings, splitGestureExpression, type UserKeybindingSettings, } from './resolve.js';
 export { canonicalTerminalStroke, formatBinding, formatGesture, formatStroke, matchesPiTuiInput, matchesTerminalInput, type PiTuiMatcher, type RawTerminalInput, } from './match.js';
-export { inboxOpenHint, inboxHint, inboxOpenInstruction, inboxShortcut, } from './inbox.js';
+export { inboxOpenHint, inboxShortcut, } from './inbox.js';
 export { backgroundBashHint, backgroundBashShortcut, } from './background-bash.js';
 export { ATTACH_CONTROL_BINDINGS, decodeAttachControlInput, encodeAttachControlInput, extractAttachControlInput, type AttachBindingId, type AttachMenuBindingId, type ExtractedAttachControlInput, } from './attach-control.js';
 export { KeybindingConcurrentEditError, persistUserKeybindings, type PersistedKeybindings, type PersistKeybindingsOptions, } from './persistence.js';

package/dist/core/keybindings/index.js

@@ -1,7 +1,7 @@
 export { BINDING_CATALOG, BINDING_IDS, SAFETY_REQUIREMENTS, isAttachPaneBinding, } from './catalog.js';
 export { GestureSyntaxError, KeybindingValidationError, normalizeGesture, normalizeSparseOverrides, normalizeStroke, resolveKeybindings, resolveUserKeybindingSettings, resolveUserKeybindings, splitGestureExpression, } from './resolve.js';
 export { canonicalTerminalStroke, formatBinding, formatGesture, formatStroke, matchesPiTuiInput, matchesTerminalInput, } from './match.js';
-export { inboxOpenHint, inboxHint, inboxOpenInstruction, inboxShortcut, } from './inbox.js';
+export { inboxOpenHint, inboxShortcut, } from './inbox.js';
 export { backgroundBashHint, backgroundBashShortcut, } from './background-bash.js';
 export { ATTACH_CONTROL_BINDINGS, decodeAttachControlInput, encodeAttachControlInput, extractAttachControlInput, } from './attach-control.js';
 export { KeybindingConcurrentEditError, persistUserKeybindings, } from './persistence.js';

package/dist/core/memory/doc-link-grammar.js

@@ -1,7 +1,10 @@
 // doc-link-grammar.ts — the single source of truth for the `[[canonical/name]]`
 // memory-document link grammar. Zero imports, pure string ops, browser-safe —
 // any surface that highlights, resolves, or lints doc links imports THIS module
-// rather than re-implementing the bracket scan or the name shape.
+// rather than re-implementing the bracket scan or the name shape. It ships to
+// external consumers as `@north-light/crouter-api/doc-link-grammar`, so a
+// browser UI rendering a node's transcript scans with the same grammar crtrd
+// validates `/v1/memory/resolve` names with.
 //
 // A doc link is a durable cross-reference written INSIDE a memory document's
 // body, pointing at another memory document by its exact canonical name (the

package/dist/core/memory-resolver.d.ts

@@ -60,6 +60,24 @@ export interface MemoryResolutionOpts {
 }
 /** Canonical, unambiguous identifier for a memory document: `<scope>/<name>`. */
 export declare function memoryDocId(doc: MemoryDoc): string;
+/** Whose memory view is being resolved: the workspace dir, profile, and node
+ *  id that decide which stores exist and in what order. Ambient resolution
+ *  builds this from the process (`process.cwd()`, `CRTR_PROFILE_ID`,
+ *  `CRTR_NODE_ID`); a TARGET-ADDRESSED caller passes another node's, which is
+ *  what one process serving several nodes needs — crtrd resolving a link on
+ *  behalf of a node, or a warm-spare claim building a node's first-message
+ *  context. The same name can name different documents for different nodes, so
+ *  every scope in the chain (node-local, project stack, profile, user, builtin)
+ *  reads from the target rather than the host process. */
+export interface MemoryTarget {
+    /** The workspace dir the project-scope stack walks up from. */
+    cwd: string;
+    /** The selected profile id, or null when none. */
+    profileId: string | null;
+    /** The node whose `nodes/<id>/context/memory/` store is the nearest scope,
+     *  or null outside a node. */
+    nodeId: string | null;
+}
 /** All native memory docs for a scope. Project scope is a nearest-first stack of
  *  every ancestor `.crouter/memory/` (widened by a selected profile's project
  *  stack); profile is the selected profile's own singleton store, resolved
@@ -70,10 +88,10 @@ export declare function listMemoryDocs(scope: MemoryScope, quiet?: boolean): Mem
  *  doc's name exactly as `listMemoryDocs` does (path-relative, no extension,
  *  slash-separated) then prefixing the plugin name. Builtin has no plugins. */
 export declare function listPluginMemoryDocs(plugin: InstalledPlugin, scope: MemoryScope, quiet?: boolean): MemoryDoc[];
-/** All project-scoped docs visible from an explicit node workspace/profile.
- *  This target-addressed form is used when one process serves several nodes
- *  (notably warm-spare claims), where ambient cwd/profile belong to the host
- *  process rather than the node whose first-message context is being built. */
+/** All project-scoped docs visible from an explicit node workspace/profile — the
+ *  project-only slice of a `MemoryTarget` view, used where only workspace docs
+ *  are wanted (a workspace-open render). For a full-precedence target-addressed
+ *  lookup, use `resolveMemoryDocForTarget`. */
 export declare function listProjectMemoryDocs(startDir?: string, profileId?: string | null, quiet?: boolean): MemoryDoc[];
 /** All memory docs across the resolved sources, in precedence order: each
  *  ancestor project `.crouter/` from nearest to farthest, then the selected
@@ -93,3 +111,9 @@ export declare function createMemoryDocSnapshot(): MemoryDocSnapshot;
  * names are omitted so callers can preserve their per-document error behavior. */
 export declare function resolveMemoryDocs(names: readonly string[]): Map<string, MemoryDoc>;
 export declare function resolveMemoryDoc(rawName: string, opts?: MemoryResolutionOpts): MemoryDoc;
+/** Resolve a memory document as ANOTHER node would see it — the same precedence
+ *  chain (node-local > project stack > profile > user > builtin), read from the
+ *  target's cwd/profile/node rather than the host process's. This is what crtrd
+ *  resolves a `[[name]]` link through: the daemon's own cwd and env name no
+ *  node, and the same name can be a different document for two nodes. */
+export declare function resolveMemoryDocForTarget(rawName: string, target: MemoryTarget, opts?: MemoryResolutionOpts): MemoryDoc;