@mearl/daemon-core 3.0.0-beta.1 → 3.0.0-beta.10

package/README.md

@@ -1,79 +1,81 @@
 # @mearl/daemon-core
 
-Mearl 各 Node 包共享的守护进程生命周期原语：进程存活探测、JSON 记录注册表、日志滚动，以及一个 detached 守护进程管理器。
+[English](README.md) | [简体中文](README.zh-CN.md)
 
-把 `cloud-server`、`cloud-connector`、`native-host` 里原本各写一份、容易彼此漂移的 daemon 逻辑（`isAlive`、原子读写注册表、日志滚动、按 key 派生路径）收敛到这一处，确保「写方」和「读方」对**记录位置与格式**始终一致。
+Daemon lifecycle primitives shared by Mearl's Node packages: process liveness, JSON registration records, log rotation, and a detached daemon manager.
 
-此包只在 Node 中运行，可以作为普通依赖使用，也可以由执行宿主打包内联。
+`cloud-server`, `cloud-connector`, and `native-host` share daemon operations (`isAlive`, atomic registry reads and writes, log rotation, and keyed paths) here so all readers and writers agree on **record locations and formats**.
+
+This Node-only package can be used as a normal dependency or inlined into an execution host bundle.
 
 ## API
 
-### 进程存活
+### Process liveness
 
 ```typescript
 isAlive(pid: number | undefined | null): boolean
 isProcessGroupAlive(group: number): boolean
 ```
 
-用 signal-0 探测进程是否存活（`EPERM` 视为存活——进程存在但属于他人）。Linux 同时读取 `/proc/<pid>/stat`，将已退出、尚未回收的 zombie 和 dead 状态视为已停止；主线程退出但仍有其他线程时，以及无法读取状态时，保守视为存活。
+Uses signal-0 to probe liveness. `EPERM` counts as alive: the process exists but belongs to another user. On Linux, `/proc/<pid>/stat` identifies exited, unreaped zombie and dead processes as stopped. If other threads remain after the main thread exits, or status cannot be read, it conservatively treats the process as alive.
 
-POSIX 进程组检查包含根进程退出后仍存活的后代。Linux 只有在两次检查得到相同的已退出成员及创建身份时，才确认组内执行已停止；活跃后代、成员变化和权限或读取失败都会保留清理未确认状态。Windows 不使用 POSIX 进程组检查。
+POSIX process-group checks include descendants surviving the root process. Linux confirms execution has stopped only when two checks find the same exited members and creation identities. Active descendants, membership changes, permission errors, or read failures leave cleanup unconfirmed. Windows does not use POSIX process-group checks.
 
-### 路径派生（多实例）
+### Path derivation (multiple instances)
 
 ```typescript
 DAEMON_HOME                                 // ~/.mearl
-hashKey(key: string): string                // sha256(key) 前 16 位十六进制
+hashKey(key: string): string                // First 16 hexadecimal digits of sha256(key)
 keyedDir(subdir: string): string            // ~/.mearl/<subdir>
 keyedConfigFile(subdir, key): string        // ~/.mearl/<subdir>/<hash>.json
 keyedLogFile(subdir, key): string           // ~/.mearl/<subdir>/<hash>.log
 ```
 
-多实例子系统（如按 `serverUrl` 区分的连接器）用这些 helper 派生每实例的文件路径。**所有读写方都必须经由它们派生路径**，这样彼此才不会对记录位置产生分歧。
+Multi-instance subsystems, such as connectors keyed by `serverUrl`, derive per-instance paths with these helpers. **All readers and writers must use them** to agree on record locations.
 
-### 记录注册表
+### Record registry
 
 ```typescript
 interface DaemonRecord { pid: number; startedAt?: string; [k: string]: unknown }
 
 ensureDir(dir: string): void
-writeRecord(file: string, record: DaemonRecord): void   // 跨进程加锁，临时文件 + rename 原子写
-claimRecord(file: string, record: DaemonRecord): boolean // 仅在文件不存在时原子占用
+writeRecord(file: string, record: DaemonRecord): void   // Cross-process lock; atomic temporary file + rename
+claimRecord(file: string, record: DaemonRecord): boolean // Atomically claim only if absent
 readRecord<T>(file: string): T | null
 removeRecord(file: string): void
-removeRecordIfPid(file: string, pid: number): boolean   // 仅删除指定进程仍拥有的记录
+removeRecordIfPid(file: string, pid: number): boolean   // Remove only if still owned by this PID
 writeRecordIfPid(file: string, pid: number, record: DaemonRecord): boolean
-removeInvalidRecord(file: string): boolean              // 清理无法解析的残留记录
-listRecordFiles(dir: string): string[]                  // 目录下所有 *.json 绝对路径
-readLiveRecords<T>(dir: string): T[]                    // 读取存活记录，并顺带清理死记录
+removeInvalidRecord(file: string): boolean              // Clean up unparseable records
+listRecordFiles(dir: string): string[]                  // Absolute paths of all *.json files
+readLiveRecords<T>(dir: string): T[]                    // Read live records and clean up dead ones
 ```
 
-### 守护进程管理器
+### Daemon manager
 
 ```typescript
 createDaemon(opts: CreateDaemonOptions): Daemon
 ```
 
-围绕一对 `(configFile, logFile)` 构建单实例守护进程管理器。`start()` 先原子占用启动锁，
-再以 `--foreground` detached 方式拉起消费方 CLI，并立即写入带子进程 pid 的 `starting`
-记录。子进程就绪后覆盖该记录，父进程据此确认启动完成。并发 `start()` 会复用正在启动或
-已经运行的子进程。多实例子系统按实例 key 派生各自的 `configFile` / `logFile`。
+Builds a single-instance daemon manager around `(configFile, logFile)`. `start()` atomically claims a startup lock,
+launches the consumer CLI detached with `--foreground`, and immediately writes a `starting` record
+with the child PID. The ready child overwrites the record, allowing the parent to confirm startup. Concurrent `start()` calls reuse a starting
+or running child. Multi-instance subsystems derive their own `configFile` / `logFile` from the instance key.
 
 ```typescript
 interface CreateDaemonOptions {
-  name: string;            // 日志标签，如 'CloudServer' / 'CloudConnector'
-  scriptPath: string;      // 可重新拉起的 CLI 脚本绝对路径（消费方打包后的 cli.js）
-  configFile: string;      // 本实例的 JSON 记录文件（由前台子进程写入）
-  logFile: string;         // 本实例的日志文件
-  foregroundArgs?: string[];   // 追加在 `--foreground` 之后的 argv
-  readyTimeoutMs?: number;     // 等待子进程写记录的超时（默认 15000ms）
-  formatInfo?: (record: DaemonRecord) => string | null;  // 起来后额外打印的信息
+  name: string;            // Log label, e.g. 'CloudServer' / 'CloudConnector'
+  scriptPath: string;      // Absolute path to the consumer's bundled cli.js
+  configFile: string;      // Instance JSON record written by the foreground child
+  logFile: string;         // Instance log file
+  foregroundArgs?: string[];   // argv appended after `--foreground`
+  readyTimeoutMs?: number;     // Child record timeout, default 15000ms
+  formatInfo?: (record: DaemonRecord) => string | null;  // Additional startup information
   startingRecord?: (pid: number, startedAt: string) => DaemonRecord;
 }
 
 interface Daemon {
   start(): Promise<void>;
-  stop(expectedPid?: number): Promise<void>; // 指定 PID 时仅停止仍匹配的实例
+  stop(expectedPid?: number): Promise<void>; // Stop only the matching instance when PID is supplied
   restart(): Promise<void>;
   status(): void;
   logs(lines?: number): void;
@@ -81,20 +83,20 @@ interface Daemon {
 }
 ```
 
-> `scriptPath` 必须是消费方自己的 `cli.js`：用打包进 cli 入口的某个模块里的 `fileURLToPath(import.meta.url)` 计算。daemon-core 自身被独立解析时，它的 `import.meta.url` 指向 daemon-core，而不是 cli。
+> `scriptPath` must identify the consumer's own `cli.js`. Derive it with `fileURLToPath(import.meta.url)` in a module bundled into the CLI entry. If daemon-core is resolved separately, its `import.meta.url` points to daemon-core, not the CLI.
 
-### 日志
+### Logs
 
 ```typescript
-rotateLogIfNeeded(logFile: string, maxBytes?: number): void  // 超限则滚动为 <log>.1，默认 5MB
+rotateLogIfNeeded(logFile: string, maxBytes?: number): void  // Rotate to <log>.1 above limit; default 5MB
 tailFile(logFile: string, lines: number): string
 ```
 
-## 使用方
+## Consumers
 
-- **cloud-server** —— `createDaemon`（单实例，`~/.mearl/cloud-server.json`）
-- **cloud-connector** —— `createDaemon`（多实例，按 `serverUrl` 区分，`~/.mearl/connectors/<hash>.json`）+ `readLiveRecords` 列举
-- **native-host** —— 仅用原语（`isAlive` / `keyedConfigFile` / `readRecord` / `readLiveRecords` 等）读取连接器共享注册表，以发现/接管/列举连接器
+- **cloud-server** — `createDaemon`, single instance at `~/.mearl/cloud-server.json`.
+- **cloud-connector** — `createDaemon`, instances keyed by `serverUrl` at `~/.mearl/connectors/<hash>.json`, listed through `readLiveRecords`.
+- **native-host** — Uses primitives such as `isAlive` / `keyedConfigFile` / `readRecord` / `readLiveRecords` to discover, take over, and list connectors through their shared registry.
 
 
-`@mearl/daemon-core/capabilities` 的 `NodeCapabilityRegistry` 可在第三个构造参数传入 `hooks`，只加载这些绑定引用的模块。选择本身仍完整校验，目标模块字节按摘要验证，提交仍核对当前选择；忽略的模块不执行。该局部实例适用于安装 CLI 等只需要少量本机服务的宿主，不替代完整 Native Host 的激活与就绪回执。省略 `hooks` 时保持完整加载。
+`NodeCapabilityRegistry` from `@mearl/daemon-core/capabilities` accepts `hooks` in its third constructor argument to load only modules referenced by those bindings. The whole selection is still validated, target module bytes are digest-verified, and commits still check the current selection. Ignored modules do not execute. This partial instance suits hosts needing a few native services, such as the installer CLI; it does not replace full Native Host activation and readiness receipts. Omit `hooks` for full loading.

package/README.zh-CN.md

@@ -0,0 +1,102 @@
+# @mearl/daemon-core
+
+[English](README.md) | [简体中文](README.zh-CN.md)
+
+Mearl 各 Node 包共享的守护进程生命周期原语：进程存活探测、JSON 记录注册表、日志滚动，以及一个 detached 守护进程管理器。
+
+把 `cloud-server`、`cloud-connector`、`native-host` 里原本各写一份、容易彼此漂移的 daemon 逻辑（`isAlive`、原子读写注册表、日志滚动、按 key 派生路径）收敛到这一处，确保「写方」和「读方」对**记录位置与格式**始终一致。
+
+此包只在 Node 中运行，可以作为普通依赖使用，也可以由执行宿主打包内联。
+
+## API
+
+### 进程存活
+
+```typescript
+isAlive(pid: number | undefined | null): boolean
+isProcessGroupAlive(group: number): boolean
+```
+
+用 signal-0 探测进程是否存活（`EPERM` 视为存活——进程存在但属于他人）。Linux 同时读取 `/proc/<pid>/stat`，将已退出、尚未回收的 zombie 和 dead 状态视为已停止；主线程退出但仍有其他线程时，以及无法读取状态时，保守视为存活。
+
+POSIX 进程组检查包含根进程退出后仍存活的后代。Linux 只有在两次检查得到相同的已退出成员及创建身份时，才确认组内执行已停止；活跃后代、成员变化和权限或读取失败都会保留清理未确认状态。Windows 不使用 POSIX 进程组检查。
+
+### 路径派生（多实例）
+
+```typescript
+DAEMON_HOME                                 // ~/.mearl
+hashKey(key: string): string                // sha256(key) 前 16 位十六进制
+keyedDir(subdir: string): string            // ~/.mearl/<subdir>
+keyedConfigFile(subdir, key): string        // ~/.mearl/<subdir>/<hash>.json
+keyedLogFile(subdir, key): string           // ~/.mearl/<subdir>/<hash>.log
+```
+
+多实例子系统（如按 `serverUrl` 区分的连接器）用这些 helper 派生每实例的文件路径。**所有读写方都必须经由它们派生路径**，这样彼此才不会对记录位置产生分歧。
+
+### 记录注册表
+
+```typescript
+interface DaemonRecord { pid: number; startedAt?: string; [k: string]: unknown }
+
+ensureDir(dir: string): void
+writeRecord(file: string, record: DaemonRecord): void   // 跨进程加锁，临时文件 + rename 原子写
+claimRecord(file: string, record: DaemonRecord): boolean // 仅在文件不存在时原子占用
+readRecord<T>(file: string): T | null
+removeRecord(file: string): void
+removeRecordIfPid(file: string, pid: number): boolean   // 仅删除指定进程仍拥有的记录
+writeRecordIfPid(file: string, pid: number, record: DaemonRecord): boolean
+removeInvalidRecord(file: string): boolean              // 清理无法解析的残留记录
+listRecordFiles(dir: string): string[]                  // 目录下所有 *.json 绝对路径
+readLiveRecords<T>(dir: string): T[]                    // 读取存活记录，并顺带清理死记录
+```
+
+### 守护进程管理器
+
+```typescript
+createDaemon(opts: CreateDaemonOptions): Daemon
+```
+
+围绕一对 `(configFile, logFile)` 构建单实例守护进程管理器。`start()` 先原子占用启动锁，
+再以 `--foreground` detached 方式拉起消费方 CLI，并立即写入带子进程 pid 的 `starting`
+记录。子进程就绪后覆盖该记录，父进程据此确认启动完成。并发 `start()` 会复用正在启动或
+已经运行的子进程。多实例子系统按实例 key 派生各自的 `configFile` / `logFile`。
+
+```typescript
+interface CreateDaemonOptions {
+  name: string;            // 日志标签，如 'CloudServer' / 'CloudConnector'
+  scriptPath: string;      // 可重新拉起的 CLI 脚本绝对路径（消费方打包后的 cli.js）
+  configFile: string;      // 本实例的 JSON 记录文件（由前台子进程写入）
+  logFile: string;         // 本实例的日志文件
+  foregroundArgs?: string[];   // 追加在 `--foreground` 之后的 argv
+  readyTimeoutMs?: number;     // 等待子进程写记录的超时（默认 15000ms）
+  formatInfo?: (record: DaemonRecord) => string | null;  // 起来后额外打印的信息
+  startingRecord?: (pid: number, startedAt: string) => DaemonRecord;
+}
+
+interface Daemon {
+  start(): Promise<void>;
+  stop(expectedPid?: number): Promise<void>; // 指定 PID 时仅停止仍匹配的实例
+  restart(): Promise<void>;
+  status(): void;
+  logs(lines?: number): void;
+  running(): DaemonRecord | null;
+}
+```
+
+> `scriptPath` 必须是消费方自己的 `cli.js`：用打包进 cli 入口的某个模块里的 `fileURLToPath(import.meta.url)` 计算。daemon-core 自身被独立解析时，它的 `import.meta.url` 指向 daemon-core，而不是 cli。
+
+### 日志
+
+```typescript
+rotateLogIfNeeded(logFile: string, maxBytes?: number): void  // 超限则滚动为 <log>.1，默认 5MB
+tailFile(logFile: string, lines: number): string
+```
+
+## 使用方
+
+- **cloud-server** —— `createDaemon`（单实例，`~/.mearl/cloud-server.json`）
+- **cloud-connector** —— `createDaemon`（多实例，按 `serverUrl` 区分，`~/.mearl/connectors/<hash>.json`）+ `readLiveRecords` 列举
+- **native-host** —— 仅用原语（`isAlive` / `keyedConfigFile` / `readRecord` / `readLiveRecords` 等）读取连接器共享注册表，以发现/接管/列举连接器
+
+
+`@mearl/daemon-core/capabilities` 的 `NodeCapabilityRegistry` 可在第三个构造参数传入 `hooks`，只加载这些绑定引用的模块。选择本身仍完整校验，目标模块字节按摘要验证，提交仍核对当前选择；忽略的模块不执行。该局部实例适用于安装 CLI 等只需要少量本机服务的宿主，不替代完整 Native Host 的激活与就绪回执。省略 `hooks` 时保持完整加载。

package/dist/command.d.ts

@@ -41,6 +41,8 @@ export declare function resolveSpawnCommand(executable: string, args: string[],
 export declare function prependCommandPath(command: string, env?: NodeJS.ProcessEnv): NodeJS.ProcessEnv;
 export declare function prependNodePath(env?: NodeJS.ProcessEnv, nodeExecutable?: string): NodeJS.ProcessEnv;
 export declare function prependPathDirectory(directory: string, env?: NodeJS.ProcessEnv): NodeJS.ProcessEnv;
+/** npm exec's package selector belongs to its invocation, not nested package runners. */
+export declare function npmExecEnvironment(env?: NodeJS.ProcessEnv): NodeJS.ProcessEnv;
 export declare function findExecutable(name: string, options?: {
     env?: NodeJS.ProcessEnv;
     existsSync?: (filePath: string) => boolean;

package/dist/command.js

@@ -6,7 +6,16 @@ import { isProcessGroupAlive, isProcessOwnerAlive, processIdentity } from './pro
 const ownedCommands = new AsyncLocalStorage();
 /** Accepted installation commands retain process ownership until their complete process group exits. */
 export function withOwnedCommands(lifecycle, operation) {
-    return ownedCommands.run(lifecycle, operation);
+    const parent = ownedCommands.getStore();
+    return ownedCommands.run(parent ? {
+        started(owner) { parent.started(owner); lifecycle.started(owner); },
+        finished(owner) { try {
+            lifecycle.finished(owner);
+        }
+        finally {
+            parent.finished(owner);
+        } },
+    } : lifecycle, operation);
 }
 export function isCommandProcessAlive(owner) {
     if (!owner.group || process.platform === 'win32')
@@ -118,6 +127,10 @@ export function prependPathDirectory(directory, env = process.env) {
         return env;
     return { ...env, [pathKey]: [directory, ...entries].join(path.delimiter) };
 }
+/** npm exec's package selector belongs to its invocation, not nested package runners. */
+export function npmExecEnvironment(env = process.env) {
+    return Object.fromEntries(Object.entries(env).filter(([key]) => key.toLowerCase() !== 'npm_config_package'));
+}
 export function findExecutable(name, options = {}) {
     const env = options.env ?? process.env;
     const platform = options.platform ?? process.platform;

package/dist/node-capabilities.d.ts

@@ -14,6 +14,7 @@ export declare class NodeCapabilityRegistry<Host extends object = object> {
     get revision(): string | undefined;
     get installationRevision(): string | undefined;
     get<T extends NodeCapabilityHandler>(name: string): T | undefined;
+    entries(prefix?: string): Array<[string, NodeCapabilityHandler]>;
     require<T extends NodeCapabilityHandler>(name: string): T;
     refresh(): Promise<string | undefined>;
     private readSelection;

package/dist/node-capabilities.js

@@ -1,12 +1,13 @@
 import { createHash } from 'node:crypto';
 import { createRequire } from 'node:module';
 import { Script } from 'node:vm';
+import { isDeepStrictEqual } from 'node:util';
 import { constants } from 'node:fs';
 import { lstat, open } from 'node:fs/promises';
 import { join } from 'node:path';
 import { DAEMON_HOME } from './paths.js';
-import { verifyNodeCapabilityActivation, MAX_NODE_SELECTION_BYTES } from '@mearl/preset';
-const MAX_SELECTION_BYTES = MAX_NODE_SELECTION_BYTES + 128;
+import { verifyCapabilityActivation, MAX_CAPABILITY_SELECTION_BYTES } from '@mearl/preset';
+const MAX_SELECTION_BYTES = MAX_CAPABILITY_SELECTION_BYTES + 128;
 const handlerName = /^[a-z][a-zA-Z0-9_.-]{0,127}$/;
 async function readBoundedFile(file, limit) {
     const stat = await lstat(file);
@@ -50,6 +51,9 @@ export class NodeCapabilityRegistry {
     get revision() { return this.active?.snapshot.revision; }
     get installationRevision() { return this.active?.snapshot.installationRevision; }
     get(name) { return this.active && Object.hasOwn(this.active.handlers, name) ? this.active.handlers[name] : undefined; }
+    entries(prefix = "") {
+        return Object.entries(this.active?.handlers ?? {}).filter(([name]) => name.startsWith(prefix));
+    }
     require(name) {
         const handler = this.get(name);
         if (!handler)
@@ -84,7 +88,7 @@ export class NodeCapabilityRegistry {
                 return undefined;
             throw error;
         }
-        return verifyNodeCapabilityActivation(JSON.parse(bytes.toString('utf8')));
+        return verifyCapabilityActivation(JSON.parse(bytes.toString('utf8')));
     }
     async load(snapshot) {
         if (!snapshot) {
@@ -104,7 +108,7 @@ export class NodeCapabilityRegistry {
         const pointer = join(this.directory, 'active-node.json');
         const bytes = await readBoundedFile(pointer, MAX_SELECTION_BYTES);
         const requested = JSON.parse(bytes.toString('utf8'));
-        const current = await verifyNodeCapabilityActivation(requested).catch(() => undefined);
+        const current = await verifyCapabilityActivation(requested).catch(() => undefined);
         if (current && (current.revision !== failed?.revision || current.installationRevision !== failed?.installationRevision)) {
             try {
                 await this.load(current);
@@ -117,7 +121,7 @@ export class NodeCapabilityRegistry {
         const record = JSON.parse((await readBoundedFile(join(this.directory, 'rollback.json'), MAX_SELECTION_BYTES + 256)).toString('utf8'));
         if (record.candidate !== requested.installationRevision || !record.previous)
             return;
-        const previous = await verifyNodeCapabilityActivation(record.previous);
+        const previous = await verifyCapabilityActivation(record.previous);
         const expected = createHash('sha256').update(bytes).digest('hex');
         await this.prepareSelection(previous, async () => {
             const current = await readBoundedFile(pointer, MAX_SELECTION_BYTES);
@@ -138,6 +142,12 @@ export class NodeCapabilityRegistry {
         }
         const modules = new Map();
         for (const [id, resource] of entries) {
+            const previous = this.active?.snapshot.modules[id];
+            const reusable = this.active?.modules.get(id);
+            if (reusable && previous?.sha256 === resource.sha256 && previous.byteLength === resource.byteLength && isDeepStrictEqual(previous.config ?? {}, resource.config ?? {})) {
+                modules.set(id, reusable);
+                continue;
+            }
             const bytes = resources.get(id);
             // CommonJS wrappers can be reclaimed after their active and in-flight handlers are released.
             const module = { exports: {} };
@@ -163,7 +173,7 @@ export class NodeCapabilityRegistry {
         const current = await guard();
         if (!current)
             throw new Error('Node capability selection changed while preparing modules');
-        this.active = { snapshot: current, handlers: Object.freeze(handlers) };
+        this.active = { snapshot: current, handlers: Object.freeze(handlers), modules };
         return snapshot.revision;
     }
 }

package/dist/page-runtimes.d.ts

@@ -0,0 +1,27 @@
+import { type PageRuntimeBinding } from '@mearl/preset/bundles';
+export interface PageRuntimeOwner {
+    browser: string;
+    target: string;
+    pid?: number;
+    processIdentity?: string;
+}
+export declare const MAX_NODE_PAGE_CACHE_BYTES: number;
+export declare function capabilityDirectory(): string;
+/** Browser references survive host restarts; unavailable remote browsers retain their exact code. */
+export declare class NodePageRuntimeStore {
+    private readonly quota;
+    private readonly root;
+    private readonly index;
+    constructor(directory?: string, quota?: number);
+    resolve(binding: PageRuntimeBinding, provide?: (binding: PageRuntimeBinding) => string | undefined, owner?: PageRuntimeOwner): string;
+    release(owner: PageRuntimeOwner): void;
+    retain(owner: PageRuntimeOwner, binding?: PageRuntimeBinding): void;
+    /** A live target inventory is authoritative after a disconnected host lost close events. */
+    reconcile(browser: string, targets: ReadonlySet<string>): void;
+    private key;
+    private mutate;
+    private collect;
+    private read;
+    private write;
+    private verify;
+}

package/dist/page-runtimes.js

@@ -0,0 +1,163 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { closeSync, constants, existsSync, fstatSync, mkdirSync, openSync, readSync, readdirSync, renameSync, statSync, unlinkSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { DAEMON_HOME } from './paths.js';
+import { isProcessOwnerAlive } from './process.js';
+import { withRecordLock } from './registry.js';
+import { MAX_PAGE_RUNTIME_BYTES } from '@mearl/preset/bundles';
+const sha256 = /^[a-f0-9]{64}$/;
+export const MAX_NODE_PAGE_CACHE_BYTES = 64 * 1024 * 1024;
+export function capabilityDirectory() { return process.env.MEARL_CAPABILITY_DIR || join(DAEMON_HOME, 'capabilities'); }
+/** Browser references survive host restarts; unavailable remote browsers retain their exact code. */
+export class NodePageRuntimeStore {
+    quota;
+    root;
+    index;
+    constructor(directory = capabilityDirectory(), quota = MAX_NODE_PAGE_CACHE_BYTES) {
+        this.quota = quota;
+        this.root = join(directory, 'page-runtimes');
+        this.index = join(this.root, 'references.json');
+    }
+    resolve(binding, provide, owner) {
+        if (!/^[a-z][a-z0-9-]*\/[a-z][a-z0-9-]*$/.test(binding.id) || !sha256.test(binding.sha256))
+            throw new Error('Invalid page runtime binding');
+        return this.mutate(references => {
+            const file = join(this.root, `${binding.sha256}.cjs`);
+            let source;
+            if (existsSync(file))
+                source = this.verify(binding, this.read(file, MAX_PAGE_RUNTIME_BYTES));
+            else {
+                const provided = provide?.(binding);
+                if (typeof provided !== 'string' || !provided.trim())
+                    throw new Error(`Required page runtime is not installed: ${binding.id}@${binding.sha256}`);
+                const bytes = Buffer.from(provided);
+                source = this.verify(binding, bytes);
+                this.collect(references, bytes.byteLength, 1);
+                this.write(file, bytes);
+            }
+            if (owner) {
+                if (!sha256.test(owner.browser) || !owner.target || owner.target.length > 256)
+                    throw new Error('Invalid page runtime owner');
+                const key = this.key(owner);
+                const previous = references.owners[key];
+                if (!previous && Object.keys(references.owners).length >= 4096)
+                    throw new Error('Page runtime reference limit exceeded');
+                references.owners[key] = { ...owner, digests: [...new Set([...(previous?.digests ?? []), binding.sha256])] };
+            }
+            return source;
+        });
+    }
+    release(owner) {
+        if (!existsSync(this.index))
+            return;
+        this.mutate(references => { delete references.owners[this.key(owner)]; this.collect(references); });
+    }
+    retain(owner, binding) {
+        if (!existsSync(this.index))
+            return;
+        this.mutate(references => {
+            const previous = references.owners[this.key(owner)];
+            if (previous && binding && previous.digests.includes(binding.sha256))
+                previous.digests = [binding.sha256];
+            else if (!binding)
+                delete references.owners[this.key(owner)];
+            this.collect(references);
+        });
+    }
+    /** A live target inventory is authoritative after a disconnected host lost close events. */
+    reconcile(browser, targets) {
+        if (!existsSync(this.index))
+            return;
+        this.mutate(references => {
+            for (const [key, owner] of Object.entries(references.owners))
+                if (owner.browser === browser && !targets.has(owner.target))
+                    delete references.owners[key];
+            this.collect(references);
+        });
+    }
+    key(owner) { return createHash('sha256').update(JSON.stringify([owner.browser, owner.target])).digest('hex'); }
+    mutate(action) {
+        mkdirSync(this.root, { recursive: true, mode: 0o700 });
+        return withRecordLock(this.index, () => {
+            const references = existsSync(this.index) ? JSON.parse(this.read(this.index, 4 * 1024 * 1024).toString('utf8')) : { owners: {} };
+            if (!references || !references.owners || typeof references.owners !== 'object' || Array.isArray(references.owners) || Object.keys(references.owners).length > 4096)
+                throw new Error('Invalid page runtime reference index');
+            const liveness = new Map();
+            for (const [key, owner] of Object.entries(references.owners)) {
+                if (!owner || !sha256.test(owner.browser) || typeof owner.target !== 'string' || !Array.isArray(owner.digests) || owner.digests.length > 256 || owner.digests.some(digest => typeof digest !== 'string' || !sha256.test(digest)))
+                    throw new Error('Invalid page runtime reference');
+                if (owner.pid !== undefined) {
+                    const identity = JSON.stringify([owner.pid, owner.processIdentity]);
+                    if (!liveness.has(identity))
+                        liveness.set(identity, isProcessOwnerAlive({ pid: owner.pid, processIdentity: owner.processIdentity }));
+                    if (!liveness.get(identity))
+                        delete references.owners[key];
+                }
+            }
+            const result = action(references);
+            const bytes = Buffer.from(JSON.stringify(references));
+            if (bytes.byteLength > 4 * 1024 * 1024)
+                throw new Error('Page runtime reference index exceeds 4 MiB');
+            this.write(this.index, bytes);
+            return result;
+        });
+    }
+    collect(references, requiredBytes = 0, requiredEntries = 0) {
+        const protectedDigests = new Set(Object.values(references.owners).flatMap(owner => owner.digests));
+        const files = readdirSync(this.root).filter(name => /^[a-f0-9]{64}\.cjs$/.test(name)).map(name => ({ file: join(this.root, name), digest: name.slice(0, 64), info: statSync(join(this.root, name)) }));
+        let total = files.reduce((sum, file) => sum + file.info.size, 0);
+        let entries = files.length;
+        for (const file of files.sort((a, b) => a.info.mtimeMs - b.info.mtimeMs)) {
+            if (protectedDigests.has(file.digest))
+                continue;
+            // Explicit release/reconciliation reclaims unreferenced objects; insertions evict as needed.
+            if (requiredBytes && total + requiredBytes <= this.quota && entries + requiredEntries <= 256)
+                break;
+            unlinkSync(file.file);
+            total -= file.info.size;
+            entries--;
+        }
+        if (total + requiredBytes > this.quota || entries + requiredEntries > 256)
+            throw new Error('Page runtime cache is full of active browser references');
+    }
+    read(file, maximum) {
+        const handle = openSync(file, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0));
+        try {
+            const stat = fstatSync(handle);
+            if (!stat.isFile() || stat.size > maximum)
+                throw new Error('Stored page runtime exceeds its limit');
+            const bytes = Buffer.alloc(maximum + 1);
+            let length = 0;
+            while (length < bytes.length) {
+                const count = readSync(handle, bytes, length, bytes.length - length, null);
+                if (!count)
+                    break;
+                length += count;
+            }
+            if (length > maximum)
+                throw new Error('Stored page runtime exceeds its limit');
+            return bytes.subarray(0, length);
+        }
+        finally {
+            closeSync(handle);
+        }
+    }
+    write(file, bytes) {
+        const temporary = `${file}.${randomUUID()}.tmp`;
+        try {
+            writeFileSync(temporary, bytes, { mode: 0o600, flag: 'wx' });
+            renameSync(temporary, file);
+        }
+        finally {
+            try {
+                unlinkSync(temporary);
+            }
+            catch { /* Atomic replacement consumed the temporary file. */ }
+        }
+    }
+    verify(binding, bytes) {
+        if (bytes.byteLength > MAX_PAGE_RUNTIME_BYTES || createHash('sha256').update(bytes).digest('hex') !== binding.sha256)
+            throw new Error('Page runtime integrity check failed');
+        return new TextDecoder('utf-8', { fatal: true }).decode(bytes);
+    }
+}

package/dist/preset-installation.d.ts

@@ -0,0 +1,55 @@
+import { type JsonObject, type CapabilityActivation, type ResolvedPreset } from '@mearl/preset';
+import { type PreparedBundle, type PreparedPreset, type PresetSnapshot } from '@mearl/preset/bundles';
+export interface PresetInstallReceipt {
+    schemaVersion: 1;
+    snapshot: PresetSnapshot;
+    bundles: Array<Omit<PreparedBundle, 'resources'>>;
+    browserRevision: string;
+    nodeRevision: string;
+    managedModules: string[];
+    nodeSyncRequired: boolean;
+    browserSyncRequired?: boolean;
+    overrides: JsonObject;
+    revision: string;
+}
+interface SelectionState {
+    rawHash: string | null;
+    activation?: CapabilityActivation;
+    receipt?: PresetInstallReceipt;
+    prepared?: PreparedPreset;
+    preset?: ResolvedPreset;
+}
+/** One pointer binds the desired preset, user overrides and exact Node selection. */
+export declare class PresetInstallationStore {
+    readonly directory: string;
+    readonly mearlApiVersion: string;
+    private readonly pointer;
+    constructor(options?: {
+        directory?: string;
+        mearlApiVersion?: string;
+    });
+    private assertCurrent;
+    current(options?: {
+        verifyResources?: boolean;
+    }): Promise<SelectionState>;
+    apply(input: Pick<PreparedPreset, 'snapshot' | 'bundles'>, options: {
+        expectedRevision: string | null;
+        overrides?: JsonObject;
+        signal?: AbortSignal;
+        confirm?: () => Promise<void>;
+    }): Promise<PresetInstallReceipt>;
+    rollback(expectedRevision: string): Promise<void>;
+    collectGarbage(): Promise<void>;
+    private collectLocked;
+}
+export declare function presetSelectionRevision(state: SelectionState): string | null;
+/** Reads accepted local metadata without loading capability factories, browsers or network sources. */
+export declare function readInstallationManagement(options?: {
+    directory?: string;
+}): Promise<{
+    setup: import("@mearl/preset").SetupManagement | undefined;
+    source: string | undefined;
+    revision: string | undefined;
+}>;
+export { setupManagementCommand, setupRuntimeCompatible } from '@mearl/preset';
+export type { SetupManagement } from '@mearl/preset';

package/dist/preset-installation.js

@@ -0,0 +1,260 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { constants, closeSync, fstatSync, lstatSync, linkSync, mkdirSync, openSync, readSync, readdirSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join, resolve } from 'node:path';
+import { withRecordLock } from './registry.js';
+import { mergePresetDefaults, prepareNodeBundleSnapshot, prepareCapabilitySnapshot, verifyCapabilityActivation, resolveCapabilityConfig, MAX_CAPABILITY_SELECTION_BYTES, parseSetupManagement } from '@mearl/preset';
+import { BundleError, MAX_BROWSER_STORAGE_BYTES, presetRequiresBrowser, validateBundleManifest, verifyPreset, verifyBrowserPreset, verifyPreparedPreset } from '@mearl/preset/bundles';
+const digest = (bytes) => createHash('sha256').update(bytes).digest('hex');
+const hashPattern = /^[a-f0-9]{64}$/;
+const MAX_RECEIPT_BYTES = 16 * 1024 * 1024;
+const MAX_OVERRIDES_BYTES = 262_144;
+const POINTER_BYTES = MAX_CAPABILITY_SELECTION_BYTES + 128;
+function readBounded(file, limit) {
+    const before = lstatSync(file);
+    if (!before.isFile() || before.isSymbolicLink() || before.size > limit)
+        throw new Error('Invalid preset resource file or size');
+    const descriptor = openSync(file, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0));
+    try {
+        const stat = fstatSync(descriptor);
+        if (!stat.isFile() || stat.size > limit)
+            throw new Error('Invalid preset resource file or size');
+        const bytes = Buffer.alloc(Math.min(stat.size, limit) + 1);
+        let length = 0;
+        while (length < bytes.byteLength) {
+            const count = readSync(descriptor, bytes, length, bytes.byteLength - length, null);
+            if (count === 0)
+                break;
+            length += count;
+        }
+        if (length > stat.size)
+            throw new Error('Preset resource changed while reading');
+        return bytes.subarray(0, length);
+    }
+    finally {
+        closeSync(descriptor);
+    }
+}
+function optionalFile(file, limit) {
+    try {
+        return readBounded(file, limit);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return undefined;
+        throw error;
+    }
+}
+function atomicWrite(file, bytes) {
+    const temporary = `${file}.${process.pid}.${randomUUID()}.tmp`;
+    try {
+        writeFileSync(temporary, bytes, { flag: 'wx', mode: 0o600 });
+        renameSync(temporary, file);
+    }
+    finally {
+        rmSync(temporary, { force: true });
+    }
+}
+function revision(state) {
+    return state.activation?.installationRevision ?? (state.activation ? `node:${state.activation.revision}` : null);
+}
+function overrides(value) {
+    if (Object.hasOwn(value, 'management'))
+        throw new BundleError('BUNDLE_INVALID', 'Installation management cannot be overridden');
+    const accepted = mergePresetDefaults({}, value);
+    if (Buffer.byteLength(JSON.stringify(accepted)) > MAX_OVERRIDES_BYTES)
+        throw new BundleError('BUNDLE_QUOTA', 'User overrides exceed 256 KiB');
+    return accepted;
+}
+/** One pointer binds the desired preset, user overrides and exact Node selection. */
+export class PresetInstallationStore {
+    directory;
+    mearlApiVersion;
+    pointer;
+    constructor(options = {}) {
+        this.directory = resolve(options.directory ?? (process.env.MEARL_CAPABILITY_DIR || join(homedir(), '.mearl/capabilities')));
+        this.mearlApiVersion = options.mearlApiVersion ?? '1.0.0';
+        this.pointer = join(this.directory, 'active-node.json');
+    }
+    assertCurrent(expected) {
+        const bytes = optionalFile(this.pointer, POINTER_BYTES);
+        if ((bytes ? digest(bytes) : null) !== expected)
+            throw new BundleError('BUNDLE_CONFLICT', 'The installed preset changed during preparation');
+    }
+    async current(options = {}) {
+        const raw = optionalFile(this.pointer, POINTER_BYTES);
+        if (!raw)
+            return { rawHash: null };
+        const rawHash = digest(raw);
+        const activation = await verifyCapabilityActivation(JSON.parse(raw.toString('utf8')));
+        if (!activation.installationRevision)
+            return { rawHash, activation };
+        const captured = withRecordLock(this.pointer, () => {
+            this.assertCurrent(rawHash);
+            const receiptBytes = readBounded(join(this.directory, 'installations', `${activation.installationRevision}.json`), MAX_RECEIPT_BYTES);
+            const receipt = JSON.parse(receiptBytes.toString('utf8'));
+            const { revision: receiptRevision, ...data } = receipt;
+            if (receiptRevision !== activation.installationRevision || digest(JSON.stringify(data)) !== receiptRevision || data.schemaVersion !== 1 ||
+                Object.keys(data).some(key => !['schemaVersion', 'snapshot', 'bundles', 'browserRevision', 'nodeRevision', 'managedModules', 'nodeSyncRequired', 'browserSyncRequired', 'overrides'].includes(key)) || typeof data.nodeSyncRequired !== 'boolean' || (data.browserSyncRequired !== undefined && typeof data.browserSyncRequired !== 'boolean') ||
+                data.nodeRevision !== activation.revision || !Array.isArray(data.bundles) || data.bundles.length > 64 ||
+                !Array.isArray(data.managedModules) || new Set(data.managedModules).size !== data.managedModules.length || data.managedModules.some(id => typeof id !== 'string' || !Object.hasOwn(activation.modules, id))) {
+                throw new BundleError('BUNDLE_INTEGRITY', 'Installed preset receipt does not match its selection');
+            }
+            const acceptedOverrides = overrides(data.overrides);
+            let total = 0;
+            const metadata = data.bundles.map(bundle => {
+                if (Object.keys(bundle).some(key => !['source', 'manifest', 'revision'].includes(key)))
+                    throw new BundleError('BUNDLE_INVALID', 'Invalid installed package metadata');
+                const manifest = validateBundleManifest(bundle.manifest, this.mearlApiVersion);
+                total += Object.values(manifest.resources).reduce((sum, entry) => sum + entry.byteLength, 0);
+                return { ...bundle, manifest };
+            });
+            if (total > MAX_BROWSER_STORAGE_BYTES)
+                throw new BundleError('BUNDLE_QUOTA', 'Installed preset resources exceed 64 MiB');
+            const bundles = options.verifyResources === false ? [] : metadata.map(bundle => ({ ...bundle, resources: Object.fromEntries(Object.entries(bundle.manifest.resources).map(([name, entry]) => [name, readBounded(join(this.directory, 'blobs', `${entry.sha256}.bin`), entry.byteLength)])) }));
+            for (const entry of options.verifyResources === false ? [] : Object.values(activation.modules)) {
+                const bytes = readBounded(join(this.directory, 'objects', `${entry.sha256}.cjs`), entry.byteLength);
+                if (bytes.byteLength !== entry.byteLength || digest(bytes) !== entry.sha256)
+                    throw new BundleError('BUNDLE_INTEGRITY', 'Installed Node object is missing or corrupt');
+            }
+            return { receipt: { ...receipt, overrides: acceptedOverrides }, bundles };
+        });
+        if (options.verifyResources === false) {
+            const graph = await verifyPreset(captured.receipt.snapshot, this.mearlApiVersion);
+            await verifyBrowserPreset({ source: graph.snapshot.source, manifests: graph.snapshot.manifests, packageTargets: graph.snapshot.packageTargets,
+                bundleRevisions: Object.fromEntries(Object.entries(graph.snapshot.bundleRevisions).filter(([id]) => graph.preset.packages[id].targets?.includes('browser'))), revision: captured.receipt.browserRevision }, this.mearlApiVersion);
+            return { rawHash, activation, receipt: captured.receipt, preset: graph.preset };
+        }
+        const prepared = await verifyPreparedPreset({ snapshot: captured.receipt.snapshot, bundles: captured.bundles }, this.mearlApiVersion);
+        if (prepared.browser.snapshot.revision !== captured.receipt.browserRevision)
+            throw new BundleError('BUNDLE_INTEGRITY', 'Installed browser projection does not match');
+        const selected = await prepareNodeBundleSnapshot(prepared.bundles.filter(bundle => prepared.preset.packages[bundle.manifest.id].targets?.includes('node')), 'native-host', this.mearlApiVersion, resolveCapabilityConfig(mergePresetDefaults(prepared.preset.defaults, captured.receipt.overrides)));
+        if (Object.keys(selected.snapshot.modules).length !== captured.receipt.managedModules.length || captured.receipt.managedModules.some(id => !Object.hasOwn(selected.snapshot.modules, id)) ||
+            Object.entries(selected.snapshot.modules).some(([id, entry]) => JSON.stringify(entry) !== JSON.stringify(activation.modules[id])) ||
+            Object.entries(selected.snapshot.bindings).some(([hook, entry]) => JSON.stringify(entry) !== JSON.stringify(activation.bindings[hook])) ||
+            Object.values(activation.bindings).filter(entry => captured.receipt.managedModules.includes(entry.module)).length !== Object.keys(selected.snapshot.bindings).length) {
+            throw new BundleError('BUNDLE_INTEGRITY', 'Installed managed Node selection does not match its packages');
+        }
+        return { rawHash, activation, prepared, receipt: captured.receipt, preset: prepared.preset };
+    }
+    async apply(input, options) {
+        options.signal?.throwIfAborted();
+        const acceptedOverrides = options.overrides === undefined ? undefined : overrides(options.overrides);
+        const [current, prepared] = await Promise.all([this.current({ verifyResources: false }), verifyPreparedPreset(input, this.mearlApiVersion)]);
+        if (revision(current) !== options.expectedRevision)
+            throw new BundleError('BUNDLE_CONFLICT', 'The installed preset changed');
+        const selected = await prepareNodeBundleSnapshot(prepared.bundles.filter(bundle => prepared.preset.packages[bundle.manifest.id].targets?.includes('node')), 'native-host', this.mearlApiVersion, resolveCapabilityConfig(mergePresetDefaults(prepared.preset.defaults, acceptedOverrides ?? current.receipt?.overrides ?? {})));
+        const previousManaged = new Set(current.receipt?.managedModules ?? []);
+        const unmanaged = Object.fromEntries(Object.entries(current.activation?.modules ?? {}).filter(([id]) => !previousManaged.has(id)));
+        for (const entry of Object.values(unmanaged)) {
+            const bytes = readBounded(join(this.directory, 'objects', `${entry.sha256}.cjs`), entry.byteLength);
+            if (bytes.byteLength !== entry.byteLength || digest(bytes) !== entry.sha256)
+                throw new BundleError('BUNDLE_INTEGRITY', 'An independent Node module is corrupt');
+        }
+        if (Object.keys(selected.snapshot.modules).some(id => Object.hasOwn(unmanaged, id)))
+            throw new BundleError('BUNDLE_CONFLICT', 'A preset module conflicts with an independently installed Node module');
+        const bindings = Object.fromEntries(Object.entries(current.activation?.bindings ?? {}).filter(([, entry]) => Object.hasOwn(unmanaged, entry.module)));
+        if (Object.keys(selected.snapshot.bindings).some(hook => Object.hasOwn(bindings, hook)))
+            throw new BundleError('BUNDLE_CONFLICT', 'A preset hook conflicts with an independently installed Node module');
+        const snapshot = await prepareCapabilitySnapshot({ schemaVersion: 1, modules: { ...unmanaged, ...selected.snapshot.modules }, bindings: { ...bindings, ...selected.snapshot.bindings } });
+        const data = {
+            schemaVersion: 1, snapshot: prepared.snapshot,
+            bundles: prepared.bundles.map(({ source, revision, manifest }) => ({ source, revision, manifest })),
+            browserRevision: prepared.browser.snapshot.revision, nodeRevision: snapshot.revision,
+            managedModules: Object.keys(selected.snapshot.modules), overrides: acceptedOverrides ?? current.receipt?.overrides ?? {},
+            nodeSyncRequired: Boolean(current.receipt?.nodeSyncRequired || current.receipt?.managedModules.length || Object.values(prepared.preset.packages).some(entry => entry.enabled !== false && entry.targets?.includes('node'))),
+            browserSyncRequired: Boolean(current.receipt?.browserSyncRequired || presetRequiresBrowser(prepared.preset)),
+        };
+        const receipt = { ...data, revision: digest(JSON.stringify(data)) };
+        const receiptBytes = JSON.stringify(receipt);
+        if (Buffer.byteLength(receiptBytes) > MAX_RECEIPT_BYTES)
+            throw new BundleError('BUNDLE_QUOTA', 'Preset installation receipt exceeds 16 MiB');
+        const activation = { ...snapshot, installationRevision: receipt.revision };
+        await options.confirm?.();
+        withRecordLock(this.pointer, () => {
+            this.assertCurrent(current.rawHash);
+            options.signal?.throwIfAborted();
+            for (const child of ['blobs', 'objects', 'installations'])
+                mkdirSync(join(this.directory, child), { recursive: true, mode: 0o700 });
+            for (const bundle of prepared.bundles)
+                for (const [name, entry] of Object.entries(bundle.manifest.resources)) {
+                    atomicWrite(join(this.directory, 'blobs', `${entry.sha256}.bin`), bundle.resources[name]);
+                }
+            for (const entry of Object.values(selected.snapshot.modules)) {
+                const destination = join(this.directory, 'objects', `${entry.sha256}.cjs`);
+                const temporary = `${destination}.${randomUUID()}.tmp`;
+                try {
+                    linkSync(join(this.directory, 'blobs', `${entry.sha256}.bin`), temporary);
+                    renameSync(temporary, destination);
+                }
+                finally {
+                    rmSync(temporary, { force: true });
+                }
+            }
+            atomicWrite(join(this.directory, 'installations', `${receipt.revision}.json`), receiptBytes);
+            if (current.receipt?.revision !== receipt.revision)
+                atomicWrite(join(this.directory, 'rollback.json'), JSON.stringify({ candidate: receipt.revision, previous: current.activation ?? null }));
+            atomicWrite(this.pointer, JSON.stringify(activation));
+        });
+        return receipt;
+    }
+    async rollback(expectedRevision) {
+        const current = await this.current({ verifyResources: false });
+        if (current.activation?.installationRevision !== expectedRevision)
+            throw new BundleError('BUNDLE_CONFLICT', 'A newer preset installation cannot be rolled back');
+        const record = JSON.parse(readBounded(join(this.directory, 'rollback.json'), POINTER_BYTES + 256).toString('utf8'));
+        if (record.candidate !== expectedRevision)
+            throw new BundleError('BUNDLE_CONFLICT', 'The preset rollback record has changed');
+        const previous = record.previous === null ? undefined : await verifyCapabilityActivation(record.previous);
+        withRecordLock(this.pointer, () => {
+            this.assertCurrent(current.rawHash);
+            if (previous)
+                atomicWrite(this.pointer, JSON.stringify(previous));
+            else
+                rmSync(this.pointer, { force: true });
+            rmSync(join(this.directory, 'rollback.json'), { force: true });
+            this.collectLocked(previous);
+        });
+    }
+    async collectGarbage() {
+        const current = await this.current({ verifyResources: false });
+        const raw = optionalFile(join(this.directory, 'rollback.json'), POINTER_BYTES + 256);
+        const record = raw && JSON.parse(raw.toString('utf8'));
+        const previous = record?.candidate === current.activation?.installationRevision && record.previous !== null ? await verifyCapabilityActivation(record.previous) : undefined;
+        withRecordLock(this.pointer, () => {
+            this.assertCurrent(current.rawHash);
+            for (const child of ['blobs', 'objects', 'installations'])
+                mkdirSync(join(this.directory, child), { recursive: true, mode: 0o700 });
+            this.collectLocked(current.activation, previous);
+        });
+    }
+    collectLocked(active, previous) {
+        const receipts = new Set([active?.installationRevision, previous?.installationRevision].filter((value) => Boolean(value)));
+        const blobs = new Set();
+        const modules = new Set([active, previous].flatMap(selection => Object.values(selection?.modules ?? {}).map(entry => entry.sha256)));
+        for (const id of receipts) {
+            const record = JSON.parse(readBounded(join(this.directory, 'installations', `${id}.json`), MAX_RECEIPT_BYTES).toString('utf8'));
+            for (const bundle of record.bundles)
+                for (const entry of Object.values(bundle.manifest.resources))
+                    blobs.add(entry.sha256);
+        }
+        for (const [directory, extension, retained] of [['blobs', '.bin', blobs], ['objects', '.cjs', modules], ['installations', '.json', receipts]]) {
+            for (const name of readdirSync(join(this.directory, directory))) {
+                const id = name.slice(0, -extension.length);
+                if (name.endsWith(extension) && hashPattern.test(id) && !retained.has(id))
+                    rmSync(join(this.directory, directory, name), { force: true });
+            }
+        }
+    }
+}
+export function presetSelectionRevision(state) { return revision(state); }
+/** Reads accepted local metadata without loading capability factories, browsers or network sources. */
+export async function readInstallationManagement(options = {}) {
+    const current = await new PresetInstallationStore(options).current({ verifyResources: false });
+    return {
+        setup: parseSetupManagement(current.preset?.defaults.management),
+        source: current.receipt?.snapshot.source,
+        revision: current.receipt?.revision,
+    };
+}
+export { setupManagementCommand, setupRuntimeCompatible } from '@mearl/preset';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mearl/daemon-core",
-  "version": "3.0.0-beta.1",
+  "version": "3.0.0-beta.10",
   "description": "Shared Node daemon lifecycle primitives for Mearl — process liveness, JSON record registry, log rotation, and a detached daemon manager",
   "type": "module",
   "main": "dist/index.js",
@@ -13,6 +13,14 @@
     "./capabilities": {
       "types": "./dist/node-capabilities.d.ts",
       "import": "./dist/node-capabilities.js"
+    },
+    "./installation": {
+      "types": "./dist/preset-installation.d.ts",
+      "import": "./dist/preset-installation.js"
+    },
+    "./page-runtimes": {
+      "types": "./dist/page-runtimes.d.ts",
+      "import": "./dist/page-runtimes.js"
     }
   },
   "files": [
@@ -25,7 +33,7 @@
   ],
   "license": "Apache-2.0",
   "engines": {
-    "node": ">=22.12.0"
+    "node": ">=20.18.0"
   },
   "publishConfig": {
     "registry": "https://registry.npmjs.org"
@@ -35,11 +43,11 @@
     "typescript": "^5.8.3"
   },
   "dependencies": {
-    "@mearl/preset": "3.0.0-beta.1"
+    "@mearl/preset": "3.0.0-beta.10"
   },
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/F-loat/mearl.git",
+    "url": "git+https://github.com/mearlhq/mearl.git",
     "directory": "packages/daemon-core"
   },
   "scripts": {