@microsandbox/control-client 0.7.0

package/README.md

@@ -0,0 +1,115 @@
+# TypeScript control client
+
+`ControlClient` is `Client<ControlProtocol>` over the shared framed engine. It sends a bounded `control.hello` directly, negotiates generation and limits, and exposes the original welcome frame. Use it when the peer is known to support framed control. It does not probe JSON or downgrade after failure.
+
+The root entry is browser-safe and accepts a caller-owned byte transport or reconnectable connector. The `/node` entry accepts an existing Unix socket or Windows named-pipe path without renaming it.
+
+```ts
+import { GetMemoryState, MiB, SetMemoryTarget, typedMessage } from "@microsandbox/control-client";
+import { connectFramedControl } from "@microsandbox/control-client/node";
+
+async function inspectAndResize(path: string) {
+  const client = await connectFramedControl(path, { setupTimeoutMs: 10_000 });
+  try {
+    const response = await client.request(typedMessage("control.memory.state", {}));
+    console.log(response.type, response.raw.body);
+    const before = await client.requestTyped(new GetMemoryState());
+    const accepted = await client.requestTyped(new SetMemoryTarget(MiB(2048)));
+    console.log(before.target_mib, accepted.target_mib); // bigint, even for small values
+  } finally {
+    await client.close();
+  }
+}
+```
+
+Checked helpers cover capabilities, memory state/target, CPU state/target, and ordered secret updates. They validate replies and retain the actual response on `ControlClientError`. Generic message requests return peer error frames directly. A target reply reports acceptance and observation; it does not establish guest convergence. Secret batches stop at the first failure and retain earlier completed changes.
+
+Use `connectControl` for automatic discovery on the same endpoint. It sends the existing read-only JSON capabilities request, closes that exchange, and opens a fresh framed connection only after an affirmative CBOR advertisement. Setup has one total deadline across both connections. Malformed discovery, timeout, EOF without a reply, or a failed welcome never trigger fallback or replay.
+
+```text
+connectControl(path)
+    |
+    +-- JSON capabilities --> valid legacy reply --> fresh JSON exchange per operation
+    |
+    +-- JSON capabilities --> advertises CBOR -----> fresh hello/welcome --> shared framed client
+```
+
+```ts
+import { GetMemoryState, MiB, SetMemoryTarget, typedMessage } from "@microsandbox/control-client";
+import { connectControl } from "@microsandbox/control-client/node";
+
+async function compatibleResize(path: string) {
+  const connection = await connectControl(path);
+  try {
+    const reply = await connection.request(typedMessage("control.memory.state", {}));
+    if (reply.kind === "cbor") console.log(reply.frame.raw.body);
+    else console.log(reply.reply.raw, reply.reply.value.get("memory"));
+    const before = await connection.requestTyped(new GetMemoryState());
+    const accepted = await connection.requestTyped(new SetMemoryTarget(MiB(2048)));
+    return { before, accepted };
+  } finally {
+    await connection.close();
+  }
+}
+```
+
+`ControlConnection.connectConnector` accepts a repeatable caller connector from the browser-safe root. The connection exposes the read-only `capabilities` discovery snapshot, `mode`, `clone()`, `isClosed()`, `close()`, `request()`, and `requestTyped()`. `framed()` returns the complete generic surface in CBOR mode and fails locally with `unsupported_mode` in JSON mode. Encoded messages likewise fail locally in JSON mode; the adapter translates only known, validated native operations.
+
+`JsonReply` contains the original response line, including its delimiter and whitespace, and a lossless `Map` of fields. `JsonNumber.token` retains each original numeric token; checked memory observations become `bigint` without passing through a JavaScript number. Ordinary requests return `ok:false` replies. Checked helpers raise `legacy_remote` with the original reply and unknown batch progress. Neither arbitrary diagnostic strings nor legacy errors are converted into structured CBOR errors.
+
+For explicit legacy access, construction is inert and performs no discovery:
+
+```ts
+import { GetCpuState } from "@microsandbox/control-client";
+import { jsonControl } from "@microsandbox/control-client/node";
+
+async function inspectLegacy(path: string) {
+  const client = jsonControl(path);
+  try {
+    return await client.requestTyped(new GetCpuState());
+  } finally {
+    await client.close();
+  }
+}
+```
+
+The equivalent root API is `JsonControlClient.fromConnector(connector, options?)`. Ordinary legacy request and response lines keep their existing size contract; only automatic discovery replies have a 64 KiB limit. Preparing a secret batch snapshots its entries without imposing the framed 4 MiB ceiling on JSON. JavaScript strings remain subject to garbage collection; explicit buffer clearing is not a guarantee that all copies have been erased.
+
+A standalone automatic JSON connection rediscovers before each fresh operation because an endpoint path cannot establish process identity. `ControlConnection.connectVerifiedConnector` permits discovery reuse when the caller supplies a `VerifiedControlConnector`: `connect` must verify every connected peer against the saved OS process birth identity, and `verifySession` must check the active run and process before each operation. Both receive a deadline and cancellation context. Runtime replacement raises `runtime_changed` before mutation admission and closes the shared handle. This extension point does not implement an SDK database or OS identity verifier by itself.
+
+`MiB`, `GiB`, `KiB`, `TiB`, and `Mebibytes` are exported from `@microsandbox/types/size`. Their arithmetic matches the SDK helpers. `SetMemoryTarget` validates integer precision and range before converting to the wire quantity; it also accepts `bigint` for full-width values.
+
+All generic operations remain available:
+
+| Need | Method |
+|---|---|
+| Native or encoded payload | `request(typedMessage(...))`, `request(encodedMessage(...))` |
+| Exact opaque envelope | `requestRaw(flags, body)` |
+| Message or raw subscription | `openStream(...)`, `openStreamRaw(...)` |
+| Owned sender and receiver | `stream.split()` |
+| Follow-up using an owned ID | `sendOnStream(id, ...)`, `sendRaw(id, ...)` |
+| Exact packet without a subscription | `writeUnchecked(bytes)` |
+| Optional checked unary operation | `requestTyped(request)` |
+| Shared connection ownership | `clone()`, `close()` |
+
+```ts
+import { ControlClient, encodedMessage, type ByteTransport } from "@microsandbox/control-client";
+
+async function inspectExtension(transport: ByteTransport, payload: Uint8Array) {
+  const client = await ControlClient.connectTransport(transport);
+  try {
+    const reply = await client.request(encodedMessage("extension.inspect", payload));
+    return { name: reply.type, payload: reply.payload, original: reply.raw };
+  } finally {
+    await client.close();
+  }
+}
+```
+
+The default control request deadline is 30 seconds. Expiry abandons the local wait; it does not cancel remote work or retry it. `ClientError.delivery` distinguishes requests that were not admitted from unknown outcomes. Complete idle connections do not expire automatically. Explicit close closes every clone; JavaScript finalization is only best-effort cleanup.
+
+From `packages`, run `npm run build`, `npm run typecheck`, and `npm test`. Live validation is deliberately opt-in: set `MSB_CONTROL_TEST_SOCKET` to a disposable framed runtime's socket and run `npm test -w @microsandbox/control-client`. Add `MSB_CONTROL_TEST_MODE=cbor` to run automatic discovery as well. The package serializes test files because live files mutate and restore the same VM's targets. A skipped live test is not platform or runtime compatibility evidence.
+
+For a historical JSON-only runtime, set `MSB_CONTROL_TEST_MODE=json` and run only the compatibility live file with `npm exec -w @microsandbox/control-client -- vitest run tests/compatibility-live.test.ts`. It checks automatic and explicit JSON access, concurrent reads, full-width result types, and accepted memory/CPU targets, then restores the original targets. These running-runtime tests do not establish SDK launch compatibility.
+
+The additional secret test requires `MSB_CONTROL_TEST_SECRET` naming a dummy fixture initially set to `before` and allowed for `example.invalid`. It exercises partial completion, malformed batches, and legacy JSON failures, then restores those fixture values.

package/dist/attempt.d.ts

@@ -0,0 +1,19 @@
+import { ClientError, type ByteTransport, type ConnectContext, type Connector } from "@microsandbox/protocol-client";
+import { ControlClientError } from "./error.js";
+/** An absolute control-operation scope, including dial, verification, and I/O. */
+export declare class ControlAttempt {
+    #private;
+    readonly deadlineMs: number;
+    get signal(): AbortSignal;
+    get context(): ConnectContext;
+    constructor(timeoutMs: number, signals?: readonly (AbortSignal | undefined)[]);
+    check(): void;
+    remaining(): number;
+    run<T>(work: () => Promise<T>): Promise<T>;
+    connect(connector: Connector): Promise<ByteTransport>;
+    dispose(): void;
+}
+export declare function validateTimeout(value: number): void;
+export declare function controlError(error: unknown): ClientError | ControlClientError;
+export declare function closeTransport(transport: ByteTransport): Promise<void>;
+//# sourceMappingURL=attempt.d.ts.map

package/dist/attempt.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"attempt.d.ts","sourceRoot":"","sources":["../src/attempt.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,KAAK,aAAa,EAAE,KAAK,cAAc,EAAE,KAAK,SAAS,EAAE,MAAM,+BAA+B,CAAC;AACrH,OAAO,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAEhD,kFAAkF;AAClF,qBAAa,cAAc;;IAGzB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,IAAI,MAAM,IAAI,WAAW,CAAoC;IAC7D,IAAI,OAAO,IAAI,cAAc,CAAiE;gBAElF,SAAS,EAAE,MAAM,EAAE,OAAO,GAAE,SAAS,CAAC,WAAW,GAAG,SAAS,CAAC,EAAO;IAgBjF,KAAK,IAAI,IAAI;IAIb,SAAS,IAAI,MAAM;IACb,GAAG,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;IAU1C,OAAO,CAAC,SAAS,EAAE,SAAS,GAAG,OAAO,CAAC,aAAa,CAAC;IAQ3D,OAAO,IAAI,IAAI;CAChB;AAED,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAEnD;AACD,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,WAAW,GAAG,kBAAkB,CAE7E;AACD,wBAAsB,cAAc,CAAC,SAAS,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC,CAE5E"}

package/dist/attempt.js

@@ -0,0 +1,79 @@
+import { ClientError } from "@microsandbox/protocol-client";
+import { ControlClientError } from "./error.js";
+/** An absolute control-operation scope, including dial, verification, and I/O. */
+export class ControlAttempt {
+    #controller = new AbortController();
+    #cleanup = [];
+    deadlineMs;
+    get signal() { return this.#controller.signal; }
+    get context() { return { deadlineMs: this.deadlineMs, signal: this.signal }; }
+    constructor(timeoutMs, signals = []) {
+        validateTimeout(timeoutMs);
+        this.deadlineMs = performance.now() + timeoutMs;
+        for (const signal of signals) {
+            if (!signal)
+                continue;
+            const abort = () => this.#controller.abort(signal.reason instanceof ClientError ? signal.reason : new ClientError("cancelled"));
+            if (signal.aborted)
+                abort();
+            else {
+                signal.addEventListener("abort", abort, { once: true });
+                this.#cleanup.push(() => signal.removeEventListener("abort", abort));
+            }
+        }
+        if (timeoutMs === 0)
+            this.#controller.abort(new ClientError("timeout"));
+        else {
+            const timer = setTimeout(() => this.#controller.abort(new ClientError("timeout")), timeoutMs);
+            this.#cleanup.push(() => clearTimeout(timer));
+        }
+    }
+    check() {
+        if (performance.now() >= this.deadlineMs && !this.signal.aborted)
+            this.#controller.abort(new ClientError("timeout"));
+        if (this.signal.aborted)
+            throw this.signal.reason;
+    }
+    remaining() { this.check(); return Math.max(0, this.deadlineMs - performance.now()); }
+    async run(work) {
+        this.check();
+        return new Promise((resolve, reject) => {
+            const abort = () => reject(this.signal.reason);
+            this.signal.addEventListener("abort", abort, { once: true });
+            Promise.resolve().then(() => { this.check(); return work(); }).then(resolve, reject)
+                .finally(() => this.signal.removeEventListener("abort", abort));
+            if (this.signal.aborted)
+                abort();
+        });
+    }
+    async connect(connector) {
+        return this.run(() => connector.connect(this.context).then(transport => {
+            // Even a connector that ignores cancellation transfers ownership. Close
+            // its late result instead of leaving an unobserved live socket behind.
+            try {
+                this.check();
+            }
+            catch (error) {
+                void closeTransport(transport);
+                throw error;
+            }
+            return transport;
+        }));
+    }
+    dispose() { for (const cleanup of this.#cleanup.splice(0))
+        cleanup(); }
+}
+export function validateTimeout(value) {
+    if (!Number.isFinite(value) || value < 0 || value > 0x7fffffff)
+        throw new ClientError("invalid_options");
+}
+export function controlError(error) {
+    return error instanceof ClientError || error instanceof ControlClientError ? error : new ClientError("io");
+}
+export async function closeTransport(transport) {
+    try {
+        await transport.close();
+    }
+    catch { /* Preserve the exchange's original outcome. */ }
+}
+//# sourceMappingURL=attempt.js.map

package/dist/attempt.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"attempt.js","sourceRoot":"","sources":["../src/attempt.ts"],"names":[],"mappings":"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"}

package/dist/client.d.ts

@@ -0,0 +1,9 @@
+import { Client, type ByteTransport, type Connector, type ConnectOptions } from "@microsandbox/protocol-client";
+import { ControlProtocol } from "./protocol.js";
+/** The full generic native/encoded/raw/stream/packet API, specialized for control. */
+export type ControlClient = Client<ControlProtocol>;
+export declare const ControlClient: {
+    connectTransport(transport: ByteTransport, options?: ConnectOptions): Promise<ControlClient>;
+    connectConnector(connector: Connector, options?: ConnectOptions): Promise<ControlClient>;
+};
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,KAAK,aAAa,EAAE,KAAK,SAAS,EAAE,KAAK,cAAc,EAAE,MAAM,+BAA+B,CAAC;AAChH,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAEhD,sFAAsF;AACtF,MAAM,MAAM,aAAa,GAAG,MAAM,CAAC,eAAe,CAAC,CAAC;AACpD,eAAO,MAAM,aAAa;gCACI,aAAa,YAAY,cAAc,GAAG,OAAO,CAAC,aAAa,CAAC;gCAGhE,SAAS,YAAY,cAAc,GAAG,OAAO,CAAC,aAAa,CAAC;CAGzF,CAAC"}

package/dist/client.js

@@ -0,0 +1,11 @@
+import { Client } from "@microsandbox/protocol-client";
+import { ControlProtocol } from "./protocol.js";
+export const ControlClient = {
+    connectTransport(transport, options) {
+        return Client.connectTransport(transport, new ControlProtocol(), options);
+    },
+    connectConnector(connector, options) {
+        return Client.connectConnector(connector, new ControlProtocol(), options);
+    },
+};
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAA2D,MAAM,+BAA+B,CAAC;AAChH,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAIhD,MAAM,CAAC,MAAM,aAAa,GAAG;IAC3B,gBAAgB,CAAC,SAAwB,EAAE,OAAwB;QACjE,OAAO,MAAM,CAAC,gBAAgB,CAAC,SAAS,EAAE,IAAI,eAAe,EAAE,EAAE,OAAO,CAAC,CAAC;IAC5E,CAAC;IACD,gBAAgB,CAAC,SAAoB,EAAE,OAAwB;QAC7D,OAAO,MAAM,CAAC,gBAAgB,CAAC,SAAS,EAAE,IAAI,eAAe,EAAE,EAAE,OAAO,CAAC,CAAC;IAC5E,CAAC;CACF,CAAC"}

package/dist/connection.d.ts

@@ -0,0 +1,32 @@
+import { type ConnectOptions, type Connector, type InboundFrame, type OutboundMessage, type RequestOptions } from "@microsandbox/protocol-client";
+import type { ControlClient } from "./client.js";
+import type { VerifiedControlConnector } from "./dialer.js";
+import type { ControlMode, JsonReply } from "./json-reply.js";
+import { type CheckedControlRequest } from "./legacy-request.js";
+import { type Capabilities } from "./records.js";
+export type ControlReply = {
+    kind: "cbor";
+    frame: InboundFrame;
+} | {
+    kind: "json";
+    reply: JsonReply;
+};
+/** Shared automatic discovery; JSON and CBOR keep their actual reply formats. */
+export declare class ControlConnection {
+    private readonly session;
+    private constructor();
+    static connectConnector(connector: Connector, options?: ConnectOptions): Promise<ControlConnection>;
+    static connectVerifiedConnector(connector: VerifiedControlConnector, options?: ConnectOptions): Promise<ControlConnection>;
+    private static establish;
+    clone(): ControlConnection;
+    get mode(): ControlMode;
+    /** Validated discovery snapshot; GetCapabilities explicitly requests a fresh observation. */
+    get capabilities(): Readonly<Capabilities>;
+    isClosed(): boolean;
+    framed(): ControlClient;
+    close(): Promise<void>;
+    request(message: OutboundMessage, options?: RequestOptions): Promise<ControlReply>;
+    requestTyped<T>(request: CheckedControlRequest<T>, options?: RequestOptions): Promise<T>;
+    private framedOperation;
+}
+//# sourceMappingURL=connection.d.ts.map

package/dist/connection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"connection.d.ts","sourceRoot":"","sources":["../src/connection.ts"],"names":[],"mappings":"AAAA,OAAO,EAA0D,KAAK,cAAc,EAAE,KAAK,SAAS,EAAE,KAAK,YAAY,EAAE,KAAK,eAAe,EAAE,KAAK,cAAc,EAAE,MAAM,+BAA+B,CAAC;AAE1M,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AACjD,OAAO,KAAK,EAAiB,wBAAwB,EAAE,MAAM,aAAa,CAAC;AAG3E,OAAO,KAAK,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAC9D,OAAO,EAAqB,KAAK,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AACpF,OAAO,EAAwD,KAAK,YAAY,EAAE,MAAM,cAAc,CAAC;AAGvG,MAAM,MAAM,YAAY,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,YAAY,CAAA;CAAE,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,SAAS,CAAA;CAAE,CAAC;AAGtG,iFAAiF;AACjF,qBAAa,iBAAiB;IACR,OAAO,CAAC,QAAQ,CAAC,OAAO;IAA5C,OAAO;IACP,MAAM,CAAC,gBAAgB,CAAC,SAAS,EAAE,SAAS,EAAE,OAAO,GAAE,cAAmB,GAAG,OAAO,CAAC,iBAAiB,CAAC;IAGvG,MAAM,CAAC,wBAAwB,CAAC,SAAS,EAAE,wBAAwB,EAAE,OAAO,GAAE,cAAmB,GAAG,OAAO,CAAC,iBAAiB,CAAC;mBAGzG,SAAS;IA2B9B,KAAK,IAAI,iBAAiB;IAC1B,IAAI,IAAI,IAAI,WAAW,CAAkD;IACzE,6FAA6F;IAC7F,IAAI,YAAY,IAAI,QAAQ,CAAC,YAAY,CAAC,CAAsC;IAChF,QAAQ,IAAI,OAAO;IACnB,MAAM,IAAI,aAAa;IAIjB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAItB,OAAO,CAAC,OAAO,EAAE,eAAe,EAAE,OAAO,GAAE,cAAmB,GAAG,OAAO,CAAC,YAAY,CAAC;IAItF,YAAY,CAAC,CAAC,EAAE,OAAO,EAAE,qBAAqB,CAAC,CAAC,CAAC,EAAE,OAAO,GAAE,cAAmB,GAAG,OAAO,CAAC,CAAC,CAAC;YAIpF,eAAe;CAiB9B"}

package/dist/connection.js

@@ -0,0 +1,103 @@
+import { Client, ClientError, defaultLimits } from "@microsandbox/protocol-client";
+import { closeTransport, ControlAttempt, controlError } from "./attempt.js";
+import { ControlClientError } from "./error.js";
+import { JsonSession } from "./json-session.js";
+import { nativeJsonRequest } from "./legacy-request.js";
+import { DEFAULT_REQUEST_TIMEOUT_MS, DEFAULT_SETUP_TIMEOUT_MS } from "./records.js";
+import { ControlProtocol } from "./protocol.js";
+/** Shared automatic discovery; JSON and CBOR keep their actual reply formats. */
+export class ControlConnection {
+    session;
+    constructor(session) {
+        this.session = session;
+    }
+    static connectConnector(connector, options = {}) {
+        return this.establish({ connector }, options);
+    }
+    static connectVerifiedConnector(connector, options = {}) {
+        return this.establish({ connector, verifier: connector }, options);
+    }
+    static async establish(dialer, options) {
+        const json = new JsonSession(dialer, options, true);
+        const attempt = new ControlAttempt(options.setupTimeoutMs ?? DEFAULT_SETUP_TIMEOUT_MS, [options.signal]);
+        let framed;
+        let transport;
+        try {
+            const { mode, capabilities } = await json.discover(attempt);
+            if (mode === "cbor") {
+                // Discovery finishes and closes its JSON stream. Positive advertisement
+                // requires a fresh framed handshake; failures must never downgrade.
+                transport = await attempt.connect(dialer.connector);
+                if (dialer.verifier)
+                    await attempt.run(() => dialer.verifier.verifySession(attempt.context));
+                const protocol = new ControlProtocol(), owned = transport;
+                const established = await attempt.run(() => protocol.establish(owned, { ...attempt.context, limits: defaultLimits(json.options.limits) }));
+                attempt.check();
+                framed = await Client.fromEstablished(protocol, established);
+                transport = undefined; // The generic reader/writer now own the stream.
+            }
+            attempt.check();
+            return new ControlConnection({ dialer, options: json.options, json, framed, closed: new AbortController(), capabilities: Object.freeze(capabilities) });
+        }
+        catch (error) {
+            if (transport)
+                await closeTransport(transport);
+            await framed?.close();
+            await json.close();
+            const failure = controlError(error);
+            throw failure instanceof ClientError ? failure.withDelivery("not_sent") : failure;
+        }
+        finally {
+            attempt.dispose();
+        }
+    }
+    clone() { return new ControlConnection(this.session); }
+    get mode() { return this.session.framed ? "cbor" : "json"; }
+    /** Validated discovery snapshot; GetCapabilities explicitly requests a fresh observation. */
+    get capabilities() { return this.session.capabilities; }
+    isClosed() { return this.session.json.isClosed() || (this.session.framed?.isClosed() ?? false); }
+    framed() {
+        if (!this.session.framed)
+            throw new ControlClientError("unsupported_mode");
+        return this.session.framed;
+    }
+    async close() {
+        this.session.closed.abort(new ClientError("closed"));
+        await Promise.all([this.session.json.close(), this.session.framed?.close()]);
+    }
+    async request(message, options = {}) {
+        if (!this.session.framed)
+            return { kind: "json", reply: await this.session.json.operation(nativeJsonRequest(message), options) };
+        return { kind: "cbor", frame: await this.framedOperation(options, remaining => this.session.framed.request(message, remaining)) };
+    }
+    async requestTyped(request, options = {}) {
+        if (!this.session.framed)
+            return request.decodeJson(await this.session.json.operation(request.jsonRequest(), options));
+        return this.framedOperation(options, remaining => this.session.framed.requestTyped(request, remaining));
+    }
+    async framedOperation(options, operation) {
+        if (this.isClosed())
+            throw new ClientError("closed");
+        const attempt = new ControlAttempt(options.requestTimeoutMs ?? this.session.options.limits?.requestTimeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS, [options.signal, this.session.closed.signal]);
+        try {
+            try {
+                const verifier = this.session.dialer.verifier;
+                if (verifier)
+                    await attempt.run(() => verifier.verifySession(attempt.context));
+                attempt.check();
+                if (this.isClosed())
+                    throw new ClientError("closed");
+            }
+            catch (error) {
+                await this.close();
+                const failure = controlError(error);
+                throw failure instanceof ClientError ? failure.withDelivery("not_sent") : failure;
+            }
+            return await operation({ ...options, signal: attempt.signal, requestTimeoutMs: attempt.remaining() });
+        }
+        finally {
+            attempt.dispose();
+        }
+    }
+}
+//# sourceMappingURL=connection.js.map

package/dist/connection.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"connection.js","sourceRoot":"","sources":["../src/connection.ts"],"names":[],"mappings":"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"}

package/dist/dialer.d.ts

@@ -0,0 +1,16 @@
+import type { ConnectContext, Connector } from "@microsandbox/protocol-client";
+/**
+ * Backend-owned identity seam. connect must verify each connected peer against
+ * the saved OS process birth token. verifySession must recheck the active run
+ * and process before an operation; a PID or endpoint path alone is insufficient.
+ * Both methods reject runtime replacement before returning an owned transport
+ * or permitting operation admission, using ControlClientError/runtime_changed.
+ */
+export interface VerifiedControlConnector extends Connector {
+    verifySession(context: ConnectContext): Promise<void>;
+}
+export type ControlDialer = {
+    connector: Connector;
+    verifier?: VerifiedControlConnector;
+};
+//# sourceMappingURL=dialer.d.ts.map

package/dist/dialer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dialer.d.ts","sourceRoot":"","sources":["../src/dialer.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,SAAS,EAAE,MAAM,+BAA+B,CAAC;AAE/E;;;;;;GAMG;AACH,MAAM,WAAW,wBAAyB,SAAQ,SAAS;IACzD,aAAa,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACvD;AAED,MAAM,MAAM,aAAa,GAAG;IAAE,SAAS,EAAE,SAAS,CAAC;IAAC,QAAQ,CAAC,EAAE,wBAAwB,CAAA;CAAE,CAAC"}

package/dist/dialer.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=dialer.js.map

package/dist/dialer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dialer.js","sourceRoot":"","sources":["../src/dialer.ts"],"names":[],"mappings":""}

package/dist/error.d.ts

@@ -0,0 +1,13 @@
+import type { InboundFrame } from "@microsandbox/protocol-client";
+import type { ControlError } from "./records.js";
+import type { JsonReply } from "./json-reply.js";
+export type ControlErrorCode = "peer" | "invalid_response" | "unsupported_mode" | "runtime_changed" | "legacy_remote" | "invalid_json_response";
+/** Checked-operation failures retain the real response, without logging its data. */
+export declare class ControlClientError extends Error {
+    readonly code: ControlErrorCode;
+    readonly response?: (InboundFrame | JsonReply) | undefined;
+    readonly peerError?: ControlError | undefined;
+    constructor(code: ControlErrorCode, response?: (InboundFrame | JsonReply) | undefined, peerError?: ControlError | undefined);
+    get delivery(): "not_sent" | "unknown";
+}
+//# sourceMappingURL=error.d.ts.map

package/dist/error.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"error.d.ts","sourceRoot":"","sources":["../src/error.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,+BAA+B,CAAC;AAClE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AACjD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAEjD,MAAM,MAAM,gBAAgB,GAAG,MAAM,GAAG,kBAAkB,GAAG,kBAAkB,GAAG,iBAAiB,GAAG,eAAe,GAAG,uBAAuB,CAAC;AAQhJ,qFAAqF;AACrF,qBAAa,kBAAmB,SAAQ,KAAK;IAEzC,QAAQ,CAAC,IAAI,EAAE,gBAAgB;IAC/B,QAAQ,CAAC,QAAQ,CAAC,GAAE,YAAY,GAAG,SAAS;IAC5C,QAAQ,CAAC,SAAS,CAAC,EAAE,YAAY;gBAFxB,IAAI,EAAE,gBAAgB,EACtB,QAAQ,CAAC,GAAE,YAAY,GAAG,SAAS,aAAA,EACnC,SAAS,CAAC,EAAE,YAAY,YAAA;IAKnC,IAAI,QAAQ,IAAI,UAAU,GAAG,SAAS,CAErC;CAEF"}

package/dist/error.js

@@ -0,0 +1,23 @@
+const descriptions = {
+    peer: "control operation rejected by peer", invalid_response: "invalid control operation response",
+    unsupported_mode: "operation requires framed control", runtime_changed: "runtime session changed",
+    legacy_remote: "legacy control operation failed; batch progress is unknown", invalid_json_response: "invalid legacy control response",
+};
+/** Checked-operation failures retain the real response, without logging its data. */
+export class ControlClientError extends Error {
+    code;
+    response;
+    peerError;
+    constructor(code, response, peerError) {
+        super(descriptions[code]);
+        this.code = code;
+        this.response = response;
+        this.peerError = peerError;
+        this.name = "ControlClientError";
+    }
+    get delivery() {
+        return this.code === "unsupported_mode" || this.code === "runtime_changed" ? "not_sent" : "unknown";
+    }
+    [Symbol.for("nodejs.util.inspect.custom")]() { return "ControlClientError: " + this.message; }
+}
+//# sourceMappingURL=error.js.map

package/dist/error.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"error.js","sourceRoot":"","sources":["../src/error.ts"],"names":[],"mappings":"AAMA,MAAM,YAAY,GAAqC;IACrD,IAAI,EAAE,oCAAoC,EAAE,gBAAgB,EAAE,oCAAoC;IAClG,gBAAgB,EAAE,mCAAmC,EAAE,eAAe,EAAE,yBAAyB;IACjG,aAAa,EAAE,4DAA4D,EAAE,qBAAqB,EAAE,iCAAiC;CACtI,CAAC;AAEF,qFAAqF;AACrF,MAAM,OAAO,kBAAmB,SAAQ,KAAK;IAEhC;IACA;IACA;IAHX,YACW,IAAsB,EACtB,QAAmC,EACnC,SAAwB;QAEjC,KAAK,CAAC,YAAY,CAAC,IAAI,CAAC,CAAC,CAAC;QAJjB,SAAI,GAAJ,IAAI,CAAkB;QACtB,aAAQ,GAAR,QAAQ,CAA2B;QACnC,cAAS,GAAT,SAAS,CAAe;QAGjC,IAAI,CAAC,IAAI,GAAG,oBAAoB,CAAC;IACnC,CAAC;IACD,IAAI,QAAQ;QACV,OAAO,IAAI,CAAC,IAAI,KAAK,kBAAkB,IAAI,IAAI,CAAC,IAAI,KAAK,iBAAiB,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,SAAS,CAAC;IACtG,CAAC;IACD,CAAC,MAAM,CAAC,GAAG,CAAC,4BAA4B,CAAC,CAAC,KAAa,OAAO,sBAAsB,GAAG,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC;CACvG"}

package/dist/index.d.ts

@@ -0,0 +1,15 @@
+/** Browser-safe control protocol; native transport entry points live in /node. */
+export * from "./client.js";
+export * from "./protocol.js";
+export * from "./records.js";
+export * from "./request.js";
+export * from "./error.js";
+export * from "./connection.js";
+export * from "./json-client.js";
+export { JsonReply, type ControlMode } from "./json-reply.js";
+export { JsonNumber, type JsonObject, type JsonValue } from "./json-value.js";
+export type { CheckedControlRequest, LegacyControlRequest } from "./legacy-request.js";
+export type { VerifiedControlConnector } from "./dialer.js";
+export * from "@microsandbox/types/size";
+export { Client, ClientError, InboundFrame, typedMessage, encodedMessage, type ByteTransport, type Connector, type ConnectOptions, type RequestOptions, type RawFrame, type TypedMessage, type EncodedMessage, type Request, } from "@microsandbox/protocol-client";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,kFAAkF;AAClF,cAAc,aAAa,CAAC;AAC5B,cAAc,eAAe,CAAC;AAC9B,cAAc,cAAc,CAAC;AAC7B,cAAc,cAAc,CAAC;AAC7B,cAAc,YAAY,CAAC;AAC3B,cAAc,iBAAiB,CAAC;AAChC,cAAc,kBAAkB,CAAC;AACjC,OAAO,EAAE,SAAS,EAAE,KAAK,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAC9D,OAAO,EAAE,UAAU,EAAE,KAAK,UAAU,EAAE,KAAK,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAC9E,YAAY,EAAE,qBAAqB,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AACvF,YAAY,EAAE,wBAAwB,EAAE,MAAM,aAAa,CAAC;AAC5D,cAAc,0BAA0B,CAAC;AACzC,OAAO,EACL,MAAM,EAAE,WAAW,EAAE,YAAY,EAAE,YAAY,EAAE,cAAc,EAC/D,KAAK,aAAa,EAAE,KAAK,SAAS,EAAE,KAAK,cAAc,EAAE,KAAK,cAAc,EAC5E,KAAK,QAAQ,EAAE,KAAK,YAAY,EAAE,KAAK,cAAc,EAAE,KAAK,OAAO,GACpE,MAAM,+BAA+B,CAAC"}

package/dist/index.js

@@ -0,0 +1,13 @@
+/** Browser-safe control protocol; native transport entry points live in /node. */
+export * from "./client.js";
+export * from "./protocol.js";
+export * from "./records.js";
+export * from "./request.js";
+export * from "./error.js";
+export * from "./connection.js";
+export * from "./json-client.js";
+export { JsonReply } from "./json-reply.js";
+export { JsonNumber } from "./json-value.js";
+export * from "@microsandbox/types/size";
+export { Client, ClientError, InboundFrame, typedMessage, encodedMessage, } from "@microsandbox/protocol-client";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,kFAAkF;AAClF,cAAc,aAAa,CAAC;AAC5B,cAAc,eAAe,CAAC;AAC9B,cAAc,cAAc,CAAC;AAC7B,cAAc,cAAc,CAAC;AAC7B,cAAc,YAAY,CAAC;AAC3B,cAAc,iBAAiB,CAAC;AAChC,cAAc,kBAAkB,CAAC;AACjC,OAAO,EAAE,SAAS,EAAoB,MAAM,iBAAiB,CAAC;AAC9D,OAAO,EAAE,UAAU,EAAmC,MAAM,iBAAiB,CAAC;AAG9E,cAAc,0BAA0B,CAAC;AACzC,OAAO,EACL,MAAM,EAAE,WAAW,EAAE,YAAY,EAAE,YAAY,EAAE,cAAc,GAGhE,MAAM,+BAA+B,CAAC"}

package/dist/json-client.d.ts

@@ -0,0 +1,15 @@
+import type { ConnectOptions, Connector, OutboundMessage, RequestOptions } from "@microsandbox/protocol-client";
+import { type CheckedControlRequest } from "./legacy-request.js";
+import type { JsonReply } from "./json-reply.js";
+/** Explicit JSON unary adapter. Construction is inert and never probes. */
+export declare class JsonControlClient {
+    private readonly session;
+    private constructor();
+    static fromConnector(connector: Connector, options?: ConnectOptions): JsonControlClient;
+    clone(): JsonControlClient;
+    isClosed(): boolean;
+    close(): Promise<void>;
+    request(message: OutboundMessage, options?: RequestOptions): Promise<JsonReply>;
+    requestTyped<T>(request: CheckedControlRequest<T>, options?: RequestOptions): Promise<T>;
+}
+//# sourceMappingURL=json-client.d.ts.map

package/dist/json-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"json-client.d.ts","sourceRoot":"","sources":["../src/json-client.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,SAAS,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,+BAA+B,CAAC;AAEhH,OAAO,EAAqB,KAAK,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AACpF,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAEjD,2EAA2E;AAC3E,qBAAa,iBAAiB;IACR,OAAO,CAAC,QAAQ,CAAC,OAAO;IAA5C,OAAO;IACP,MAAM,CAAC,aAAa,CAAC,SAAS,EAAE,SAAS,EAAE,OAAO,GAAE,cAAmB,GAAG,iBAAiB;IAG3F,KAAK,IAAI,iBAAiB;IAC1B,QAAQ,IAAI,OAAO;IACnB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAChB,OAAO,CAAC,OAAO,EAAE,eAAe,EAAE,OAAO,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,SAAS,CAAC;IAG/E,YAAY,CAAC,CAAC,EAAE,OAAO,EAAE,qBAAqB,CAAC,CAAC,CAAC,EAAE,OAAO,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,CAAC,CAAC;CAG/F"}

package/dist/json-client.js

@@ -0,0 +1,22 @@
+import { JsonSession } from "./json-session.js";
+import { nativeJsonRequest } from "./legacy-request.js";
+/** Explicit JSON unary adapter. Construction is inert and never probes. */
+export class JsonControlClient {
+    session;
+    constructor(session) {
+        this.session = session;
+    }
+    static fromConnector(connector, options = {}) {
+        return new JsonControlClient(new JsonSession({ connector }, options, false));
+    }
+    clone() { return new JsonControlClient(this.session); }
+    isClosed() { return this.session.isClosed(); }
+    close() { return this.session.close(); }
+    async request(message, options) {
+        return this.session.operation(nativeJsonRequest(message), options);
+    }
+    async requestTyped(request, options) {
+        return request.decodeJson(await this.session.operation(request.jsonRequest(), options));
+    }
+}
+//# sourceMappingURL=json-client.js.map

package/dist/json-client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"json-client.js","sourceRoot":"","sources":["../src/json-client.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,EAAE,iBAAiB,EAA8B,MAAM,qBAAqB,CAAC;AAGpF,2EAA2E;AAC3E,MAAM,OAAO,iBAAiB;IACS;IAArC,YAAqC,OAAoB;QAApB,YAAO,GAAP,OAAO,CAAa;IAAG,CAAC;IAC7D,MAAM,CAAC,aAAa,CAAC,SAAoB,EAAE,UAA0B,EAAE;QACrE,OAAO,IAAI,iBAAiB,CAAC,IAAI,WAAW,CAAC,EAAE,SAAS,EAAE,EAAE,OAAO,EAAE,KAAK,CAAC,CAAC,CAAC;IAC/E,CAAC;IACD,KAAK,KAAwB,OAAO,IAAI,iBAAiB,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;IAC1E,QAAQ,KAAc,OAAO,IAAI,CAAC,OAAO,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC;IACvD,KAAK,KAAoB,OAAO,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC;IACvD,KAAK,CAAC,OAAO,CAAC,OAAwB,EAAE,OAAwB;QAC9D,OAAO,IAAI,CAAC,OAAO,CAAC,SAAS,CAAC,iBAAiB,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC,CAAC;IACrE,CAAC;IACD,KAAK,CAAC,YAAY,CAAI,OAAiC,EAAE,OAAwB;QAC/E,OAAO,OAAO,CAAC,UAAU,CAAC,MAAM,IAAI,CAAC,OAAO,CAAC,SAAS,CAAC,OAAO,CAAC,WAAW,EAAE,EAAE,OAAO,CAAC,CAAC,CAAC;IAC1F,CAAC;CACF"}

package/dist/json-reply.d.ts

@@ -0,0 +1,18 @@
+import { type JsonObject, type JsonValue } from "./json-value.js";
+import type { Capabilities, CpuState, MemoryState } from "./records.js";
+export type ControlMode = "cbor" | "json";
+/** Actual legacy bytes and an inspectable lossless object; no fabricated frame. */
+export declare class JsonReply {
+    #private;
+    constructor(raw: Uint8Array);
+    get raw(): Uint8Array;
+    get value(): JsonObject;
+    /** Only a valid affirmative capabilities reply is evidence of a legacy peer. */
+    discoveryMode(): ControlMode;
+    /** Only checked helpers turn ok:false into an error; progress stays unknown. */
+    checked<T>(decode: (value: JsonObject) => T): T;
+}
+export declare function jsonCapabilities(value: JsonValue | undefined): Capabilities;
+export declare function jsonMemory(value: JsonValue | undefined): MemoryState;
+export declare function jsonCpu(value: JsonValue | undefined): CpuState;
+//# sourceMappingURL=json-reply.d.ts.map

package/dist/json-reply.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"json-reply.d.ts","sourceRoot":"","sources":["../src/json-reply.ts"],"names":[],"mappings":"AAEA,OAAO,EAAmC,KAAK,UAAU,EAAE,KAAK,SAAS,EAAE,MAAM,iBAAiB,CAAC;AACnG,OAAO,KAAK,EAAE,YAAY,EAAE,QAAQ,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAExE,MAAM,MAAM,WAAW,GAAG,MAAM,GAAG,MAAM,CAAC;AAE1C,mFAAmF;AACnF,qBAAa,SAAS;;gBAGR,GAAG,EAAE,UAAU;IAI3B,IAAI,GAAG,IAAI,UAAU,CAAsB;IAC3C,IAAI,KAAK,IAAI,UAAU,CAAwB;IAG/C,gFAAgF;IAChF,aAAa,IAAI,WAAW;IAW5B,gFAAgF;IAChF,OAAO,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,KAAK,EAAE,UAAU,KAAK,CAAC,GAAG,CAAC;CAMhD;AAED,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,SAAS,GAAG,SAAS,GAAG,YAAY,CAQ3E;AACD,wBAAgB,UAAU,CAAC,KAAK,EAAE,SAAS,GAAG,SAAS,GAAG,WAAW,CAGpE;AACD,wBAAgB,OAAO,CAAC,KAAK,EAAE,SAAS,GAAG,SAAS,GAAG,QAAQ,CAG9D"}