@crouter/api 0.3.387 → 0.3.389

package/dist/core/runtime/broker/daemon-ops.js

@@ -0,0 +1,177 @@
+// Broker-to-daemon operation client. A broker is launched by crtrd, so a cold
+// daemon socket must fail loud — it must never use the CLI factory that can
+// autostart another daemon.
+import { localClient } from '../../../api/node-transport.js';
+import { ApiError } from '../../../api/errors.js';
+import { envExecutionId } from '../../../shared/env.js';
+import { brokerSignalClient } from './signal-stream.js';
+import { cachedBrokerNodeFields } from '../../../daemon/broker-signals/bus.js';
+import { reportRefNodeId } from '../../../shared/inbox-entry-body.js';
+function daemonClient() {
+    return localClient({ autostart: false });
+}
+export function appendBrokerLog(nodeId, record) {
+    return daemonClient().appendNodeLog(nodeId, { record, expected_execution_id: brokerExecutionId() });
+}
+export function putBrokerTelemetry(nodeId, telemetry) {
+    return daemonClient().putNodeTelemetry(nodeId, { ...telemetry, expected_execution_id: brokerExecutionId() });
+}
+export function putBrokerRecap(nodeId, briefing) {
+    return daemonClient().putNodeRecap(nodeId, { briefing, expected_execution_id: brokerExecutionId() });
+}
+/** The body of a direct message the daemon spilled into this node's records. */
+export function readBrokerPassiveMessage(nodeId, ref) {
+    return daemonClient().readNodePassiveMessage(nodeId, ref);
+}
+export function clearBrokerPushedFinal(nodeId) {
+    return daemonClient().nodePushedFinal(nodeId, { action: 'clear', expected_execution_id: brokerExecutionId() });
+}
+export function consumeBrokerPushedFinal(nodeId) {
+    return daemonClient().nodePushedFinal(nodeId, { action: 'consume', expected_execution_id: brokerExecutionId() });
+}
+export function startBrokerBashJob(nodeId, request) {
+    return daemonClient().request('POST', `/v1/nodes/${encodeURIComponent(nodeId)}/jobs/start`, {
+        ...request, expected_execution_id: brokerExecutionId(),
+    });
+}
+/** Record a command the valve just backgrounded as this node's job object. */
+export function recordBackgroundedJob(nodeId, jobId, request) {
+    return daemonClient().recordBackgroundedJob(nodeId, jobId, request);
+}
+export function stopBrokerBashJob(nodeId, jobId) {
+    return daemonClient().request('DELETE', `/v1/nodes/${encodeURIComponent(nodeId)}/jobs/${encodeURIComponent(jobId)}?foreground=1`, {
+        expected_execution_id: brokerExecutionId(),
+    });
+}
+export function brokerExecutionId() {
+    const id = envExecutionId();
+    if (id === undefined || id === '')
+        throw new Error('broker launch is missing CRTR_EXECUTION_ID');
+    return id;
+}
+export function bindBrokerSession(nodeId, request) {
+    return daemonClient().bindBrokerSession(nodeId, { ...request, executionId: brokerExecutionId() });
+}
+export function settleBroker(nodeId, request) {
+    return daemonClient().settleBroker(nodeId, { ...request, expected_execution_id: brokerExecutionId() });
+}
+export function completeBrokerPark(nodeId, request) {
+    return daemonClient().completeBrokerPark(nodeId, { ...request, expected_execution_id: brokerExecutionId() });
+}
+export function recordBrokerParkActivity(nodeId) {
+    return daemonClient().recordBrokerParkActivity(nodeId, { expected_execution_id: brokerExecutionId() });
+}
+export function recordBrokerTelemetry(nodeId, request) {
+    return daemonClient().recordBrokerTelemetry(nodeId, { ...request, expected_execution_id: brokerExecutionId() });
+}
+export async function claimBrokerMail(nodeId, channel, reportBodies) {
+    const client = daemonClient();
+    const executionId = brokerExecutionId();
+    const result = await client.claimNodeMail(nodeId, { execution_id: executionId, channel });
+    if (result.action === 'hold')
+        return result;
+    const deliveries = await Promise.all(result.deliveries.map(async (delivery) => {
+        const ref = delivery.entry.ref;
+        if (ref === undefined || reportRefNodeId(ref) === undefined)
+            return delivery;
+        try {
+            // A claim includes mail already handed to this execution on every poll.
+            // Reports are immutable; share even concurrent lookups for the same ref.
+            let pending = reportBodies.get(ref);
+            if (pending === undefined) {
+                pending = client.readNodeInboxReport(nodeId, ref, executionId).then(({ content }) => content);
+                reportBodies.set(ref, pending);
+            }
+            const content = await pending;
+            return { ...delivery, entry: { ...delivery.entry, data: { ...delivery.entry.data, report_body: content } } };
+        }
+        catch (error) {
+            // Failed reads are retryable; a missing report still renders its ref.
+            reportBodies.delete(ref);
+            if (error instanceof ApiError && error.status === 404)
+                return delivery;
+            throw error;
+        }
+    }));
+    // A hold, error, or transient empty result cannot invalidate the ref cache.
+    // Once a non-held claim returns deliveries, retain only refs still claimed.
+    if (deliveries.length > 0) {
+        const activeRefs = new Set(deliveries.map(({ entry }) => entry.ref).filter((ref) => ref !== undefined));
+        for (const ref of reportBodies.keys())
+            if (!activeRefs.has(ref))
+                reportBodies.delete(ref);
+    }
+    return { ...result, deliveries };
+}
+export function acknowledgeBrokerMail(nodeId, deliveries) {
+    return daemonClient().acknowledgeNodeMail(nodeId, { execution_id: brokerExecutionId(), deliveries });
+}
+export function recordBrokerTurn(nodeId, request) {
+    return daemonClient().recordBrokerTurn(nodeId, { ...request, expected_execution_id: brokerExecutionId() });
+}
+export function mutateBrokerProviderRetry(nodeId, request) {
+    return daemonClient().mutateBrokerProviderRetry(nodeId, { ...request, expected_execution_id: brokerExecutionId() });
+}
+export function mutateBrokerFault(nodeId, request) {
+    return daemonClient().mutateBrokerFault(nodeId, { ...request, expected_execution_id: brokerExecutionId() });
+}
+export function brokerRecovery(nodeId) {
+    return daemonClient().getBrokerRecovery(nodeId, brokerExecutionId());
+}
+/** Node-scoped fault writes are for non-broker clients such as attach transport.
+ * Broker-owned recovery mutations use the execution-fenced wrappers above. */
+export function recordNodeFault(nodeId, input) {
+    return daemonClient().recordNodeFault(nodeId, input);
+}
+export function clearNodeFault(nodeId, opts = {}) {
+    return daemonClient().clearNodeFault(nodeId, {
+        ...(opts.link === undefined ? {} : { link: opts.link }),
+        ...(opts.preserveEpisode === undefined ? {} : { preserve_episode: opts.preserveEpisode }),
+    }).then((result) => result.cleared);
+}
+/** Fixed canvas projection for broker extension rendering. It deliberately
+ * exposes no generic node/database facade. */
+export function commitBrokerModel(nodeId, request) {
+    return daemonClient().commitBrokerModel(nodeId, { ...request, expected_execution_id: brokerExecutionId() });
+}
+export function brokerExtensionState(nodeId) {
+    return daemonClient().brokerExtensionState(nodeId);
+}
+/** Only node-owned fields are cached. A disconnected or stopped stream cannot
+ * guarantee freshness, so events at those boundaries read the daemon instead. */
+export async function cachedBrokerNode(nodeId) {
+    const client = brokerSignalClient();
+    if (client.state === 'connected' && client.latestNode !== undefined) {
+        return cachedBrokerNodeFields(client.latestNode);
+    }
+    return cachedBrokerNodeFields((await brokerExtensionState(nodeId)).node);
+}
+/** The node's one delivery route: every rule-driven document delivery the
+ *  broker applies, recorded by crtrd in the same request. */
+export function brokerDelivery(nodeId, request) {
+    return daemonClient().nodeDelivery(nodeId, { ...request, expected_execution_id: brokerExecutionId() });
+}
+export function commitBrokerGeneratedName(nodeId, request) {
+    return daemonClient().commitBrokerGeneratedName(nodeId, { ...request, expected_execution_id: brokerExecutionId() });
+}
+export function commitBrokerPersonaAck(nodeId, request) {
+    return daemonClient().commitBrokerPersonaAck(nodeId, { ...request, expected_execution_id: brokerExecutionId() });
+}
+/** Reports still use the canonical daemon report handler; this broker adapter
+ * only preserves terminal structured output's idempotent finalization result. */
+export async function publishBrokerReport(nodeId, request) {
+    try {
+        await daemonClient().pushReport(nodeId, request);
+    }
+    catch (error) {
+        if (request.tier === 'final' && error instanceof ApiError && error.code === 'already_finalized')
+            return;
+        throw error;
+    }
+}
+/** Root `/new` remains on the dedicated relaunch operation because it launches
+ * a replacement broker and tears down this broker. Callers must not await it
+ * from Pi's session-start dispatch. */
+export function relaunchBrokerRoot(nodeId) {
+    return daemonClient().relaunchRoot(nodeId);
+}

package/dist/core/runtime/broker/signal-stream.d.ts

@@ -0,0 +1,30 @@
+import type { BrokerExtensionNodeDTO } from '../../../api/dto/broker-ops.js';
+export type BrokerSignalState = 'disconnected' | 'connected' | 'unsupported' | 'stopped';
+export type BrokerSignalEvent = 'mail' | 'resync' | 'node' | 'fault-retry';
+type Listener = () => void;
+export declare class BrokerSignalClient {
+    private stateValue;
+    private latestNodeValue;
+    private readonly listeners;
+    private controller;
+    private retryTimer;
+    private heartbeatTimer;
+    private retryMs;
+    private running;
+    private nodeId;
+    private executionId;
+    get state(): BrokerSignalState;
+    /** The last hello/node projection; not an authoritative delivery or settlement read. */
+    get latestNode(): BrokerExtensionNodeDTO | undefined;
+    subscribe(event: BrokerSignalEvent | 'state', listener: Listener): () => void;
+    start(nodeId: string, executionId: string): void;
+    stop(): void;
+    private emit;
+    private setState;
+    private clearTimers;
+    private armHeartbeat;
+    private connect;
+    private handleLine;
+}
+export declare function brokerSignalClient(): BrokerSignalClient;
+export {};

package/dist/core/runtime/broker/signal-stream.js

@@ -0,0 +1,149 @@
+// Process-wide broker signal connection. Pi's Jiti loader evaluates extensions in
+// another module graph, so a module-local singleton would open duplicate streams.
+import { localClient } from '../../../api/node-transport.js';
+import { ApiError } from '../../../api/errors.js';
+const KEY = Symbol.for('@crouton-kit/crtr:broker-signal-client');
+export class BrokerSignalClient {
+    stateValue = 'disconnected';
+    latestNodeValue;
+    listeners = new Map();
+    controller;
+    retryTimer;
+    heartbeatTimer;
+    retryMs = 250;
+    running = false;
+    nodeId;
+    executionId;
+    get state() { return this.stateValue; }
+    /** The last hello/node projection; not an authoritative delivery or settlement read. */
+    get latestNode() { return this.latestNodeValue; }
+    subscribe(event, listener) {
+        let set = this.listeners.get(event);
+        if (!set) {
+            set = new Set();
+            this.listeners.set(event, set);
+        }
+        set.add(listener);
+        // A late subscriber cannot miss the hello that established this connection.
+        if (event === 'state' || (event === 'resync' && this.stateValue === 'connected') ||
+            (event === 'node' && this.latestNodeValue !== undefined))
+            listener();
+        return () => { set.delete(listener); };
+    }
+    start(nodeId, executionId) {
+        if (this.running) {
+            if (this.nodeId === nodeId && this.executionId === executionId)
+                return;
+            this.stop();
+        }
+        this.nodeId = nodeId;
+        this.executionId = executionId;
+        this.running = true;
+        this.retryMs = 250;
+        this.connect();
+    }
+    stop() {
+        this.running = false;
+        this.controller?.abort();
+        this.controller = undefined;
+        this.clearTimers();
+        this.setState('stopped');
+    }
+    emit(event) {
+        for (const listener of this.listeners.get(event) ?? []) {
+            try {
+                listener();
+            }
+            catch { /* a subscriber cannot kill the connection */ }
+        }
+    }
+    setState(state) {
+        if (this.stateValue === state)
+            return;
+        this.stateValue = state;
+        this.emit('state');
+    }
+    clearTimers() {
+        if (this.retryTimer)
+            clearTimeout(this.retryTimer);
+        if (this.heartbeatTimer)
+            clearTimeout(this.heartbeatTimer);
+        this.retryTimer = this.heartbeatTimer = undefined;
+    }
+    armHeartbeat(controller) {
+        if (this.heartbeatTimer)
+            clearTimeout(this.heartbeatTimer);
+        // The server emits ping every 15 seconds. Two missed beats mean reconnect.
+        this.heartbeatTimer = setTimeout(() => controller.abort(), 35_000);
+        this.heartbeatTimer.unref?.();
+    }
+    connect() {
+        if (!this.running || !this.nodeId || !this.executionId)
+            return;
+        const controller = new AbortController();
+        this.controller = controller;
+        void (async () => {
+            try {
+                for await (const line of localClient({ autostart: false }).getBrokerSignals(this.nodeId, this.executionId, { signal: controller.signal, maxRetries: 0 })) {
+                    if (!this.running || this.controller !== controller)
+                        return;
+                    this.armHeartbeat(controller);
+                    this.handleLine(line);
+                }
+            }
+            catch (error) {
+                if (!this.running || this.controller !== controller)
+                    return;
+                if (error instanceof ApiError && (error.status === 404 || error.status === 405)) {
+                    this.clearTimers();
+                    this.controller = undefined;
+                    this.setState('unsupported');
+                    return;
+                }
+                if (error instanceof ApiError && error.status === 409) {
+                    this.stop();
+                    return;
+                }
+            }
+            if (!this.running || this.controller !== controller)
+                return;
+            this.controller = undefined;
+            this.clearTimers();
+            this.setState('disconnected');
+            const delay = Math.round(this.retryMs * (0.8 + Math.random() * 0.4));
+            this.retryMs = Math.min(this.retryMs * 2, 5_000);
+            this.retryTimer = setTimeout(() => { this.retryTimer = undefined; this.connect(); }, delay);
+            this.retryTimer.unref?.();
+        })();
+    }
+    handleLine(line) {
+        switch (line.type) {
+            case 'hello':
+                if (line.execution_id !== this.executionId) {
+                    this.stop();
+                    return;
+                }
+                this.retryMs = 250;
+                this.latestNodeValue = line.node;
+                this.setState('connected');
+                this.emit('node');
+                this.emit('resync');
+                break;
+            case 'mail':
+                this.emit('mail');
+                break;
+            case 'node':
+                this.latestNodeValue = line.node;
+                this.emit('node');
+                break;
+            case 'fault-retry':
+                this.emit('fault-retry');
+                break;
+            case 'ping': break;
+        }
+    }
+}
+export function brokerSignalClient() {
+    const globals = globalThis;
+    return (globals[KEY] ??= new BrokerSignalClient());
+}

package/dist/core/scope.d.ts

@@ -0,0 +1,32 @@
+import type { InstalledPlugin, Scope } from '../types.js';
+export declare function builtinMemoryRoot(): string;
+export declare function builtinPiPackagesDir(): string;
+export declare function builtinPiPackageDir(name: string): string;
+export declare function userScopeRoot(): string;
+export declare function findProjectScopeRoot(startDir?: string): string | null;
+/** Every project scope root visible from `startDir`, nearest first — now a
+ *  PROFILE-AWARE pointer walk, not a single-pointer ancestor walk. Pointers are
+ *  `[startDir]` plus, when `profileId` resolves to a manifest, each of its
+ *  `projects` in manifest order; each pointer independently walks upward
+ *  collecting every ancestor `.crouter/` dir, the pointers' contributions
+ *  concatenate in pointer order, and the combined list dedupes to first
+ *  occurrence — so a `.crouter/` shared by two pointers contributes once, at
+ *  whichever pointer reached it first. `profileId` defaults to the process's
+ *  selected profile (`CRTR_PROFILE_ID`); a null/unresolvable profile collapses
+ *  to the single `[startDir]` pointer, reproducing today's behavior exactly.
+ *  Outside a Linux node sandbox, roots are discovered on each call so profile
+ *  edits and deleted project directories do not leave a stale pointer. A node
+ *  sandbox has no profile store to read and uses only its cwd pointer. */
+export declare function findProjectScopeRoots(startDir?: string, profileId?: string | null): string[];
+export declare function projectScopeRoot(startDir?: string): string | null;
+export declare function projectScopeRoots(startDir?: string, profileId?: string | null): string[];
+export declare function scopeRoot(scope: Scope): string | null;
+export declare function requireScopeRoot(scope: Scope): string;
+export declare function ensureProjectScopeRoot(startDir?: string): string;
+export declare function pluginsDir(scope: Scope): string | null;
+export declare function marketplacesDir(scope: Scope): string | null;
+/** Where a plugin's substrate memory documents live: `<plugin.root>/memory`.
+ *  The resolver mounts these under the virtual `<pluginName>/` namespace. */
+export declare function pluginMemoryDir(plugin: InstalledPlugin): string;
+export declare function resolveScopeArg(scopeArg: string | undefined): Scope | 'all';
+export declare function listScopes(scopeArg: string | undefined): Scope[];

package/dist/core/scope.js

@@ -0,0 +1,184 @@
+import { envProfileId, isSandboxedNode } from '../shared/env.js';
+import { homedir } from 'node:os';
+import { existsSync, statSync } from 'node:fs';
+import { join, resolve, dirname, sep } from 'node:path';
+import { CRTR_DIR_NAME } from '../types.js';
+import { assetRoot } from './asset-root.js';
+import { usage } from './errors.js';
+import { loadProfileManifest } from './profiles/manifest.js';
+import { realpathOrSelf } from './fs-utils.js';
+import { appsRoot, layoutRoot, runtimeRoot } from './layout.js';
+export function builtinMemoryRoot() {
+    // Builtin memory is the only content the builtin scope carries — the scope
+    // has no scopeRoot (scopeRoot('builtin') is null).
+    return join(assetRoot(), 'builtin-memory');
+}
+export function builtinPiPackagesDir() {
+    return join(assetRoot(), 'builtin-pi-packages');
+}
+export function builtinPiPackageDir(name) {
+    return join(builtinPiPackagesDir(), name);
+}
+export function userScopeRoot() {
+    return join(runtimeRoot(), 'scope');
+}
+function isProjectScopeDir(candidate, userRoot) {
+    if (!existsSync(candidate))
+        return false;
+    // Compare realpaths, not raw strings: on macOS `$HOME` is commonly under a
+    // symlinked prefix (`/tmp` -> `/private/tmp`) while `process.cwd()` (the
+    // walk's start point, resolved by the OS) is already realpath'd. A raw
+    // string compare then fails to recognize the user root one level up from a
+    // project dir nested under HOME, leaking the user scope in as a bogus
+    // project scope root.
+    if (realpathOrSelf(candidate) === realpathOrSelf(join(homedir(), CRTR_DIR_NAME)))
+        return false;
+    // App homes are mounted as HOME inside brokers; an old .crouter there is
+    // not a project scope even when the daemon resolves a node's target cwd.
+    if (realpathOrSelf(candidate).startsWith(`${realpathOrSelf(appsRoot())}${sep}`) && candidate.endsWith(`${sep}home${sep}${CRTR_DIR_NAME}`))
+        return false;
+    if (!isSandboxedNode() && (realpathOrSelf(candidate) === realpathOrSelf(userRoot) || realpathOrSelf(candidate) === realpathOrSelf(layoutRoot())))
+        return false;
+    try {
+        return statSync(candidate).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+export function findProjectScopeRoot(startDir = process.cwd()) {
+    return findProjectScopeRoots(startDir)[0] ?? null;
+}
+/** Walk `startDir` upward collecting every ancestor `.crouter/` dir (nearest
+ *  first). The user-global `~/.crouter/` is excluded because it is the separate
+ *  user scope, not a project ancestor.
+ *
+ *  The walk is FENCED at `homedir()`: it must never climb at or above HOME.
+ *  Home's own `.crouter/` is the user scope (already excluded), and nothing at
+ *  or above HOME is a project ancestor. Without this fence, a relocated HOME
+ *  nested under a directory tree that itself contains a `.crouter/` (e.g. a
+ *  mock-VM home under the real host home) would sweep the host's `~/.crouter`
+ *  (and any other above-HOME `.crouter`) in as a bogus project ancestor,
+ *  leaking one machine's user-global memory into a nested-HOME node. A read whose start dir is outside HOME (e.g. a production VM
+ *  with HOME=/root and no ancestor `.crouter`) walks to the filesystem root. */
+function collectAncestorScopeRoots(startDir, userRoot) {
+    const roots = [];
+    const home = realpathOrSelf(homedir());
+    let dir = resolve(startDir);
+    while (true) {
+        const candidate = join(dir, CRTR_DIR_NAME);
+        if (isProjectScopeDir(candidate, userRoot))
+            roots.push(candidate);
+        if (realpathOrSelf(dir) === home)
+            return roots;
+        const parent = dirname(dir);
+        if (parent === dir)
+            return roots;
+        dir = parent;
+    }
+}
+/** Every project scope root visible from `startDir`, nearest first — now a
+ *  PROFILE-AWARE pointer walk, not a single-pointer ancestor walk. Pointers are
+ *  `[startDir]` plus, when `profileId` resolves to a manifest, each of its
+ *  `projects` in manifest order; each pointer independently walks upward
+ *  collecting every ancestor `.crouter/` dir, the pointers' contributions
+ *  concatenate in pointer order, and the combined list dedupes to first
+ *  occurrence — so a `.crouter/` shared by two pointers contributes once, at
+ *  whichever pointer reached it first. `profileId` defaults to the process's
+ *  selected profile (`CRTR_PROFILE_ID`); a null/unresolvable profile collapses
+ *  to the single `[startDir]` pointer, reproducing today's behavior exactly.
+ *  Outside a Linux node sandbox, roots are discovered on each call so profile
+ *  edits and deleted project directories do not leave a stale pointer. A node
+ *  sandbox has no profile store to read and uses only its cwd pointer. */
+export function findProjectScopeRoots(startDir = process.cwd(), profileId = envProfileId() || null) {
+    return resolveProjectScopeRoots(startDir, profileId);
+}
+function resolveProjectScopeRoots(startDir, profileId) {
+    const resolvedStart = resolve(startDir);
+    const userRoot = userScopeRoot();
+    const pointers = [resolvedStart];
+    if (!isSandboxedNode() && profileId !== null && profileId !== '') {
+        try {
+            const { manifest } = loadProfileManifest(profileId);
+            for (const project of manifest.projects)
+                pointers.push(project.path);
+        }
+        catch {
+            // Missing/deleted/invalid profile: this is a hot path every
+            // launch-config resolve runs through, so fall back to the bare
+            // `[startDir]` pointer rather than throwing.
+        }
+    }
+    const seen = new Set();
+    const roots = [];
+    for (const pointer of pointers) {
+        for (const root of collectAncestorScopeRoots(pointer, userRoot)) {
+            if (!seen.has(root)) {
+                seen.add(root);
+                roots.push(root);
+            }
+        }
+    }
+    return roots;
+}
+export function projectScopeRoot(startDir) {
+    return findProjectScopeRoot(startDir);
+}
+export function projectScopeRoots(startDir, profileId) {
+    return findProjectScopeRoots(startDir, profileId);
+}
+export function scopeRoot(scope) {
+    // The builtin scope has no scope-root dir; its content lives in dedicated
+    // package directories such as builtinMemoryRoot().
+    if (scope === 'builtin')
+        return null;
+    return scope === 'user' ? userScopeRoot() : projectScopeRoot();
+}
+export function requireScopeRoot(scope) {
+    const root = scopeRoot(scope);
+    if (!root) {
+        throw usage(`no ${scope} scope available — run \`crtr init\` here or use --scope user`);
+    }
+    return root;
+}
+export function ensureProjectScopeRoot(startDir = process.cwd()) {
+    const found = findProjectScopeRoot(startDir);
+    if (found)
+        return found;
+    // The caller explicitly initializes this project scope; discovery never
+    // creates it, and the next read sees it directly from disk.
+    return join(resolve(startDir), CRTR_DIR_NAME);
+}
+export function pluginsDir(scope) {
+    const root = scope === 'user' ? runtimeRoot() : scopeRoot(scope);
+    return root ? join(root, 'plugins') : null;
+}
+export function marketplacesDir(scope) {
+    const root = scope === 'user' ? runtimeRoot() : scopeRoot(scope);
+    return root ? join(root, 'marketplaces') : null;
+}
+/** Where a plugin's substrate memory documents live: `<plugin.root>/memory`.
+ *  The resolver mounts these under the virtual `<pluginName>/` namespace. */
+export function pluginMemoryDir(plugin) {
+    return join(plugin.root, 'memory');
+}
+export function resolveScopeArg(scopeArg) {
+    if (scopeArg === undefined)
+        return 'all';
+    const value = scopeArg.toLowerCase();
+    if (value === 'user' || value === 'project' || value === 'builtin' || value === 'all')
+        return value;
+    throw usage(`invalid --scope: ${scopeArg} (expected user|project|builtin|all)`);
+}
+export function listScopes(scopeArg) {
+    const v = resolveScopeArg(scopeArg);
+    if (v === 'all') {
+        const out = [];
+        if (projectScopeRoot())
+            out.push('project');
+        out.push('user');
+        out.push('builtin');
+        return out;
+    }
+    return [v];
+}

package/dist/core/scoped-state/db.d.ts

@@ -0,0 +1,17 @@
+import { DatabaseSync } from 'node:sqlite';
+import { type ScopedStore } from './paths.js';
+export declare const PROFILE_ID_SHAPE: RegExp;
+export declare function writeOwnerRoot(db: DatabaseSync, key: string, root: string): void;
+export declare function assertScopedStoreReady(store: ScopedStore): void;
+export declare function discardIncompleteScopedStore(store: ScopedStore): void;
+export declare function withProjectStateLock<T>(root: string, run: () => T): T;
+export declare function scopedStoreExists(store: ScopedStore): boolean;
+export declare function legacyScopedStorePaths(store: ScopedStore): string[];
+export declare function initializeFreshScopedStore(input: {
+    kind: 'user' | 'project' | 'provider';
+    root: string;
+}): void;
+export declare function openScopedStore(store: ScopedStore): DatabaseSync;
+export declare function createScopedStore(store: ScopedStore, create: (db: DatabaseSync) => void): void;
+export declare function withScopedWrite<T>(store: ScopedStore, run: (db: DatabaseSync) => T): T;
+export declare function closeScopedStores(): void;