@vibesdotdev/kernel-rpc 0.0.0-stage → 1.0.0-rc.2

package/dist/core/protocol/references/ref-table.js

@@ -0,0 +1,136 @@
+import { CapabilityError } from '@vibesdotdev/kernel';
+import { isString } from "../wire/value-kinds.js";
+import { RPC_ERROR, throwRpcError, throwWireError } from "../wire/verbs.js";
+export { RUNTIME_PROJECTION_ROOT_METHODS, RUNTIME_ROOT_METHODS, validateRootMethods } from "./root-methods.js";
+export { RootMethodSchema } from "../../../schemas/contracts/protocol/references/ref-table.js";
+/** Whether each live proxy has been disposed; read through {@link isDisposed}. */
+const proxyDisposed = new WeakMap();
+export /** Keys a proxy never exposes: awaiting or inspecting it must not reach the owner. */ const NEVER_REMOTE_KEYS = new Set(['then', 'catch', 'finally', 'constructor', 'toJSON']);
+/**
+ * Build a consumer-side proxy for a `RefId` received on the wire.
+ *
+ * Every property access that yields a (declared) method returns a function that,
+ * when called, sends `invoke(refId, method, args)` and resolves to the decoded
+ * result. `Symbol.dispose` releases the ref locally (which drives the wire
+ * `release` verb via the L1 table's release sink). A `FinalizationRegistry`
+ * (owned by the L1 table) releases the ref if this proxy is GC'd undisposed.
+ *
+ * @param refId   the far-side object id
+ * @param kind    the L1 RefKind (object | function | stream)
+ * @param methods declared callable method names; only these reach the
+ *                owner (an empty set exposes none).
+ * @param unlisted how an unlisted property reads: `absent` (a ref: undefined,
+ *                like a local object) or `refused` (the root: a function that
+ *                rejects typed `rpc-root-method-unlisted`, so a caller learns why).
+ *                `then` and symbol keys are always absent.
+ * @param deps    transport-supplied send/openStream/decode/table
+ * @param streamChannel  when set, the ref is stream-capable on this channel
+ */
+export function makeRemoteProxy(refId, kind, methods, deps, streamChannel, unlisted = 'absent', channels = []) {
+    let disposed = false;
+    const methodSet = new Set(methods);
+    const releaseLocal = () => {
+        if (disposed)
+            return;
+        disposed = true;
+        // Tell the OWNER to drop the entry it retained for this proxy (the `release`
+        // verb). This proxy is not a local table entry — it is a handle to a far-side
+        // object — so we must reach across, not just delete locally.
+        deps.releaseRef(refId);
+    };
+    const invokeMethod = async (method, args) => {
+        if (disposed) {
+            throwRpcError(RPC_ERROR.DISCONNECTED, `Proxy for ref '${refId}' is disposed`);
+        }
+        const req = {
+            verb: 'invoke',
+            id: deps.nextId(),
+            targetRef: refId,
+            method,
+            // Args are encoded by the consumer's send (it owns the encoder so a
+            // callback arg is retained in the right table). We pass local values here.
+            args
+        };
+        const res = await deps.send(req);
+        if (res.error) {
+            throwWireError(res.error);
+        }
+        return deps.decode(res);
+    };
+    const openStream = (channel) => {
+        if (disposed) {
+            throwRpcError(RPC_ERROR.DISCONNECTED, `Proxy for ref '${refId}' is disposed`);
+        }
+        return deps.openStream(refId, channel);
+    };
+    // For a function ref, the proxy IS callable (a remote callback).
+    const target = kind === 'function'
+        ? Object.assign(function () { }, { __refId: refId })
+        : { __refId: refId };
+    const handler = {
+        get(_t, prop) {
+            if (prop === '__refId')
+                return refId;
+            if (prop === Symbol.dispose)
+                return releaseLocal;
+            // Intrinsic, not advertised methods (Codex 12:08, limit 2). They are
+            // local handles or protocol verbs, never a remote method call:
+            //  - `__refId` and `Symbol.dispose` read local state only;
+            //  - `__openStream` sends the `stream` verb. It exists only on an
+            //    object or stream ref; a function ref has no channels. The owner
+            //    admits it only for a ref it advertised as such, and its
+            //    `bindChannel` decides whether the named channel exists;
+            //  - calling a function ref sends `invoke(…, 'call')` via `apply`
+            //    below; only a function ref is callable, and the owner admits
+            //    `call` only on a ref it advertised as a function.
+            if (prop === '__openStream') {
+                if (kind === 'function')
+                    return undefined;
+                return (channel) => openStream(channel ?? streamChannel ?? 'default');
+            }
+            if (prop === '__channels')
+                return kind === 'function' ? [] : [...channels];
+            if (!isString(prop))
+                return undefined;
+            // Only listed methods reach the owner. A thenable key is never remote,
+            // so `await proxy` resolves locally instead of sending a call.
+            if (NEVER_REMOTE_KEYS.has(prop))
+                return undefined;
+            if (!methodSet.has(prop)) {
+                // A ref reads like a local object: the property is absent. The root
+                // refuses typed, so a call outside its contract says why.
+                if (unlisted === 'absent')
+                    return undefined;
+                return () => Promise.reject(new CapabilityError(`The remote root does not serve '${prop}' (not in its method list).`, 'UNAVAILABLE', { reason: 'rpc-root-method-unlisted', retryable: false, details: { method: prop } }));
+            }
+            return (...args) => invokeMethod(prop, args);
+        },
+        has(t, prop) {
+            // `in` agrees with `get` (the runtime's invoke gate reads a member only
+            // after `prop in impl`): a key this proxy answers is present and every
+            // other key is absent, except a non-configurable own key of the target
+            // (a function ref's `prototype`), which the Proxy invariant keeps present.
+            return handler.get?.(t, prop, t) !== undefined || Object.getOwnPropertyDescriptor(t, prop)?.configurable === false;
+        },
+        apply(_t, _this, args) {
+            // A function ref invoked directly: call its canonical 'call' method.
+            return invokeMethod('call', args);
+        }
+    };
+    // SAFETY: the get trap above answers `__refId` and `Symbol.dispose` for every
+    // ref, and `__openStream` and `__channels` for an object or stream ref: exactly
+    // the members of RemoteProxy. The advertised methods are served by name and
+    // typed by whoever declared them.
+    const proxy = new Proxy(target, handler);
+    proxyDisposed.set(proxy, () => disposed);
+    return proxy;
+}
+/** Whether a proxy built by {@link makeRemoteProxy} has been disposed. */
+export function isDisposed(proxy) {
+    return proxyDisposed.get(proxy)?.() ?? false;
+}
+/** Read the ref id off a proxy built by {@link makeRemoteProxy}. */
+export function refIdOf(proxy) {
+    return proxy?.__refId;
+}
+//# sourceMappingURL=ref-table.js.map

package/dist/core/protocol/references/ref-table.js.map

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

package/dist/core/protocol/references/root-methods.d.ts

@@ -0,0 +1,14 @@
+/**
+ * The runtime root API (C19): the methods a runtime root serves and a
+ * consumer's root proxy exposes when the root it wires is the runtime's own
+ * (the runtime daemon's RPC root implements exactly these). It never holds
+ * `then` or any thenable or symbol key, so awaiting a root proxy never sends a
+ * call. A root of another shape (PM's, a worker's, a projection) declares its
+ * own list to `wireConsumer` through `ConsumerTransport.rootMethods`.
+ */
+export declare const RUNTIME_ROOT_METHODS: readonly ["query", "resolve", "read", "write", "invoke", "health", "doctor", "command"];
+/** The runtime projection root's API (`RuntimeProjectionRoot`): its snapshot, then resolve. */
+export declare const RUNTIME_PROJECTION_ROOT_METHODS: readonly ["snapshot", "resolve"];
+/** A root method list, validated: string names only, never a thenable key. */
+export declare function validateRootMethods(methods: readonly string[]): readonly string[];
+//# sourceMappingURL=root-methods.d.ts.map

package/dist/core/protocol/references/root-methods.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"root-methods.d.ts","sourceRoot":"","sources":["../../../../src/core/protocol/references/root-methods.ts"],"names":[],"mappings":"AAIA;;;;;;;GAOG;AACH,eAAO,MAAM,oBAAoB,yFASvB,CAAC;AAEX,+FAA+F;AAC/F,eAAO,MAAM,+BAA+B,kCAAmC,CAAC;AAEhF,8EAA8E;AAC9E,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,MAAM,EAAE,CAWjF"}

package/dist/core/protocol/references/root-methods.js

@@ -0,0 +1,33 @@
+import { CapabilityError } from '@vibesdotdev/kernel';
+import { RootMethodSchema } from "../../../schemas/contracts/protocol/references/ref-table.js";
+import { NEVER_REMOTE_KEYS } from "./ref-table.js";
+/**
+ * The runtime root API (C19): the methods a runtime root serves and a
+ * consumer's root proxy exposes when the root it wires is the runtime's own
+ * (the runtime daemon's RPC root implements exactly these). It never holds
+ * `then` or any thenable or symbol key, so awaiting a root proxy never sends a
+ * call. A root of another shape (PM's, a worker's, a projection) declares its
+ * own list to `wireConsumer` through `ConsumerTransport.rootMethods`.
+ */
+export const RUNTIME_ROOT_METHODS = [
+    'query',
+    'resolve',
+    'read',
+    'write',
+    'invoke',
+    'health',
+    'doctor',
+    'command'
+];
+/** The runtime projection root's API (`RuntimeProjectionRoot`): its snapshot, then resolve. */
+export const RUNTIME_PROJECTION_ROOT_METHODS = ['snapshot', 'resolve'];
+/** A root method list, validated: string names only, never a thenable key. */
+export function validateRootMethods(methods) {
+    for (const method of methods) {
+        if (!RootMethodSchema.safeParse(method).success || NEVER_REMOTE_KEYS.has(method)) {
+            throw new CapabilityError(`A root method list names '${String(method)}', which a remote root may not expose.`, 'INVALID_INPUT', { reason: 'rpc-root-methods-invalid', retryable: false, details: { method: String(method) } });
+        }
+    }
+    return methods;
+}
+//# sourceMappingURL=root-methods.js.map

package/dist/core/protocol/references/root-methods.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"root-methods.js","sourceRoot":"","sources":["../../../../src/core/protocol/references/root-methods.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AACtD,OAAO,EAAE,gBAAgB,EAAE,MAAM,6DAA6D,CAAC;AAC/F,OAAO,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AAEnD;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG;IACnC,OAAO;IACP,SAAS;IACT,MAAM;IACN,OAAO;IACP,QAAQ;IACR,QAAQ;IACR,QAAQ;IACR,SAAS;CACA,CAAC;AAEX,+FAA+F;AAC/F,MAAM,CAAC,MAAM,+BAA+B,GAAG,CAAC,UAAU,EAAE,SAAS,CAAU,CAAC;AAEhF,8EAA8E;AAC9E,MAAM,UAAU,mBAAmB,CAAC,OAA0B;IAC7D,KAAK,MAAM,MAAM,IAAI,OAAO,EAAE,CAAC;QAC9B,IAAI,CAAC,gBAAgB,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,OAAO,IAAI,iBAAiB,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC;YAClF,MAAM,IAAI,eAAe,CACxB,6BAA6B,MAAM,CAAC,MAAM,CAAC,wCAAwC,EACnF,eAAe,EACf,EAAE,MAAM,EAAE,0BAA0B,EAAE,SAAS,EAAE,KAAK,EAAE,OAAO,EAAE,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,CAAC,EAAE,EAAE,CAC7F,CAAC;QACH,CAAC;IACF,CAAC;IACD,OAAO,OAAO,CAAC;AAChB,CAAC"}

package/dist/core/protocol/transport/failure-describer.d.ts

@@ -0,0 +1,56 @@
+import type { DescribedFailure, HostErrorFields } from "../../../schemas/contracts/protocol/failure-describer.ts";
+export { HostErrorFieldsSchema, IdentifierSchema, ReasonSchema } from "../../../schemas/contracts/protocol/failure-describer.ts";
+export type { DescribedFailure, HostErrorFields } from "../../../schemas/contracts/protocol/failure-describer.ts";
+/**
+ * The one failure describer (class checklist 2 and 3). Every failure runtime-rpc keeps, reports, returns or ends a
+ * channel with (a fetch rejection, a body or stream read error, a `Headers` construction error, a handshake refusal,
+ * a server error body, a leg failure, a channel end's cause) passes through {@link FailureDescriber.describe} before
+ * it is kept or handed out. A described failure keeps only what is typed: the `code`, `reason`, retryability and
+ * `name`, this package's own message and details, and the described cause chain. A host error (a `TypeError` from
+ * `fetch`, a stream's read error, anything not typed by runtime-rpc or the kernel) keeps only its `name` and string
+ * `code`, never its message: hosts quote request URLs and header values in their messages. Every configured secret
+ * value (a relay `sessionToken`, a bearer or connection token, a caller header value) is removed from every text the
+ * described failure keeps, wherever it appears.
+ */
+import { type CaughtFailure } from '@vibesdotdev/kernel';
+import { type RpcError } from '../wire/verbs.ts';
+/** The reason a host error (one runtime-rpc did not type) is described with. */
+export declare const RPC_HOST_FAILED = "rpc-host-failed";
+/** What replaces a configured secret in a kept text. */
+export declare const REDACTED = "[redacted]";
+export declare class FailureDescriber {
+    #private;
+    constructor(secrets?: Iterable<string | undefined>);
+    /** `text` with every configured secret removed, bounded. */
+    scrub(text: string): string;
+    /**
+     * A peer's wire error with every configured secret removed from every field: its `code` scrubbed like its message
+     * and details, its `reason` kept only when it is a reason identifier holding no configured secret (a lowercase-hex
+     * bearer passes the identifier grammar, so the grammar alone is not enough).
+     */
+    describeWireError(error: RpcError): RpcError;
+    /** `reason` when it is a reason identifier that holds no configured secret; otherwise nothing. */
+    reasonOf(reason: string | undefined): string | undefined;
+    /**
+     * The described failure: typed fields, scrubbed text, described cause; never a raw host error. Never throws: a
+     * failure whose fields cannot be read is described by what reading it threw, as a host failure.
+     */
+    describe(failure: CaughtFailure, depth?: number): DescribedFailure;
+    /** A host error's name and code, when they are short identifiers; nothing else of it. */
+    hostFields(failure: CaughtFailure): HostErrorFields;
+    private removeSecrets;
+    private describeReadable;
+    /** A host error: its name and code only. */
+    private hostFailure;
+    private causeOf;
+    /** Details as a JSON object with every configured secret removed; anything else is dropped. */
+    private detailsOf;
+    /**
+     * `value` as JSON with every configured secret removed: serialized once (bounded), scrubbed as text, parsed back
+     * by the JSON schema. A value that does not serialize (a cycle, a `bigint`, a throwing getter) is dropped.
+     */
+    private json;
+}
+/** The describer for a leg with no configured secret: it still never keeps a host error's text. */
+export declare const HOST_FAILURES: FailureDescriber;
+//# sourceMappingURL=failure-describer.d.ts.map

package/dist/core/protocol/transport/failure-describer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"failure-describer.d.ts","sourceRoot":"","sources":["../../../../src/core/protocol/transport/failure-describer.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,0DAA0D,CAAC;AAElH,OAAO,EAAE,qBAAqB,EAAE,gBAAgB,EAAE,YAAY,EAAE,MAAM,0DAA0D,CAAC;AACjI,YAAY,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,0DAA0D,CAAC;AAClH;;;;;;;;;;GAUG;AACH,OAAO,EAAwF,KAAK,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAI/I,OAAO,EAA4B,KAAK,QAAQ,EAAmB,MAAM,kBAAkB,CAAC;AAE5F,gFAAgF;AAChF,eAAO,MAAM,eAAe,oBAAoB,CAAC;AAEjD,wDAAwD;AACxD,eAAO,MAAM,QAAQ,eAAe,CAAC;AAuBrC,qBAAa,gBAAgB;;gBAIhB,OAAO,GAAE,QAAQ,CAAC,MAAM,GAAG,SAAS,CAAM;IAUtD,4DAA4D;IAC5D,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM;IAK3B;;;;OAIG;IACH,iBAAiB,CAAC,KAAK,EAAE,QAAQ,GAAG,QAAQ;IAS5C,kGAAkG;IAClG,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS;IAKxD;;;OAGG;IACH,QAAQ,CAAC,OAAO,EAAE,aAAa,EAAE,KAAK,SAAI,GAAG,gBAAgB;IAK7D,yFAAyF;IACzF,UAAU,CAAC,OAAO,EAAE,aAAa,GAAG,eAAe;IASnD,OAAO,CAAC,aAAa;IAMrB,OAAO,CAAC,gBAAgB;IAyBxB,4CAA4C;IAC5C,OAAO,CAAC,WAAW;IAUnB,OAAO,CAAC,OAAO;IAKf,+FAA+F;IAC/F,OAAO,CAAC,SAAS;IAOjB;;;OAGG;IACH,OAAO,CAAC,IAAI;CAQZ;AAED,mGAAmG;AACnG,eAAO,MAAM,aAAa,kBAAyB,CAAC"}

package/dist/core/protocol/transport/failure-describer.js

@@ -0,0 +1,157 @@
+import { HostErrorFieldsSchema, ReasonSchema } from "../../../schemas/contracts/protocol/failure-describer.js";
+export { HostErrorFieldsSchema, IdentifierSchema, ReasonSchema } from "../../../schemas/contracts/protocol/failure-describer.js";
+/**
+ * The one failure describer (class checklist 2 and 3). Every failure runtime-rpc keeps, reports, returns or ends a
+ * channel with (a fetch rejection, a body or stream read error, a `Headers` construction error, a handshake refusal,
+ * a server error body, a leg failure, a channel end's cause) passes through {@link FailureDescriber.describe} before
+ * it is kept or handed out. A described failure keeps only what is typed: the `code`, `reason`, retryability and
+ * `name`, this package's own message and details, and the described cause chain. A host error (a `TypeError` from
+ * `fetch`, a stream's read error, anything not typed by runtime-rpc or the kernel) keeps only its `name` and string
+ * `code`, never its message: hosts quote request URLs and header values in their messages. Every configured secret
+ * value (a relay `sessionToken`, a bearer or connection token, a caller header value) is removed from every text the
+ * described failure keeps, wherever it appears.
+ */
+import { CapabilityError, CaughtFailureSchema, isCapabilityError } from '@vibesdotdev/kernel';
+import { JsonObjectSchema, JsonValueSchema } from '@vibesdotdev/kernel/schemas/json';
+import * as z from 'zod/v4';
+import { attempt } from "../lifecycle/attempt.js";
+import { isRpcFailure, rpcFailure } from "../wire/verbs.js";
+/** The reason a host error (one runtime-rpc did not type) is described with. */
+export const RPC_HOST_FAILED = 'rpc-host-failed';
+/** What replaces a configured secret in a kept text. */
+export const REDACTED = '[redacted]';
+/** How deep a cause chain is described; deeper links are dropped. */
+const MAX_DEPTH = 4;
+/** How long a kept text may be, and how much serialized details are kept. */
+const MAX_TEXT = 2048;
+const MAX_DETAILS_JSON = 16_384;
+/** How many errors of an aggregate are described. */
+const MAX_LIST = 64;
+export class FailureDescriber {
+    /** Longest first, so a secret containing another is removed whole; each also in its JSON-escaped form. */
+    #secrets;
+    constructor(secrets = []) {
+        const kept = new Set();
+        for (const secret of secrets) {
+            if (secret === undefined || secret === '')
+                continue;
+            kept.add(secret);
+            kept.add(JSON.stringify(secret).slice(1, -1));
+        }
+        this.#secrets = [...kept].sort((a, b) => b.length - a.length);
+    }
+    /** `text` with every configured secret removed, bounded. */
+    scrub(text) {
+        const out = this.removeSecrets(text);
+        return out.length > MAX_TEXT ? `${out.slice(0, MAX_TEXT)}…` : out;
+    }
+    /**
+     * A peer's wire error with every configured secret removed from every field: its `code` scrubbed like its message
+     * and details, its `reason` kept only when it is a reason identifier holding no configured secret (a lowercase-hex
+     * bearer passes the identifier grammar, so the grammar alone is not enough).
+     */
+    describeWireError(error) {
+        const described = { code: this.scrub(error.code), message: this.scrub(error.message) };
+        const details = this.json(error.details);
+        if (details !== undefined)
+            described.details = details;
+        const reason = this.reasonOf(error.reason);
+        if (reason !== undefined)
+            described.reason = reason;
+        return described;
+    }
+    /** `reason` when it is a reason identifier that holds no configured secret; otherwise nothing. */
+    reasonOf(reason) {
+        if (reason === undefined || !ReasonSchema.safeParse(reason).success)
+            return undefined;
+        return this.removeSecrets(reason) === reason ? reason : undefined;
+    }
+    /**
+     * The described failure: typed fields, scrubbed text, described cause; never a raw host error. Never throws: a
+     * failure whose fields cannot be read is described by what reading it threw, as a host failure.
+     */
+    describe(failure, depth = 0) {
+        const read = attempt(() => this.describeReadable(failure, depth));
+        return read.ok ? read.value : this.hostFailure(read.failure);
+    }
+    /** A host error's name and code, when they are short identifiers; nothing else of it. */
+    hostFields(failure) {
+        const read = attempt(() => HostErrorFieldsSchema.safeParse(failure instanceof Error ? failure : undefined));
+        if (!read.ok || !read.value.success)
+            return {};
+        const fields = {};
+        if (read.value.data.name !== undefined)
+            fields.name = this.scrub(read.value.data.name);
+        if (read.value.data.code !== undefined)
+            fields.code = this.scrub(read.value.data.code);
+        return fields;
+    }
+    removeSecrets(text) {
+        let out = text;
+        for (const secret of this.#secrets)
+            if (out.includes(secret))
+                out = out.split(secret).join(REDACTED);
+        return out;
+    }
+    describeReadable(failure, depth) {
+        if (isCapabilityError(failure)) {
+            return new CapabilityError(this.scrub(failure.message), failure.code, {
+                reason: this.reasonOf(failure.reason),
+                retryable: failure.retryable,
+                recoveryHint: failure.recoveryHint,
+                details: this.detailsOf(failure.details),
+                cause: this.causeOf(failure, depth)
+            });
+        }
+        if (isRpcFailure(failure)) {
+            const described = rpcFailure(this.scrub(failure.code), this.scrub(failure.message), this.detailsOf(failure.details), this.reasonOf(failure.reason));
+            const cause = this.causeOf(failure, depth);
+            return cause === undefined ? described : Object.assign(described, { cause });
+        }
+        if (failure instanceof AggregateError && depth < MAX_DEPTH) {
+            const errors = z.array(z.unknown()).catch([]).parse(failure.errors);
+            return new AggregateError(errors.slice(0, MAX_LIST).map((error) => this.describe(CaughtFailureSchema.parse(error), depth + 1)), this.scrub(failure.message));
+        }
+        return this.hostFailure(failure);
+    }
+    /** A host error: its name and code only. */
+    hostFailure(failure) {
+        const fields = this.hostFields(failure);
+        const label = [fields.name, fields.code].filter((part) => part !== undefined).join(' ');
+        return new CapabilityError(`A host operation failed${label ? ` (${label})` : ''}.`, 'UNAVAILABLE', {
+            reason: RPC_HOST_FAILED,
+            retryable: false,
+            details: { ...fields }
+        });
+    }
+    causeOf(failure, depth) {
+        if (failure.cause === undefined || depth >= MAX_DEPTH)
+            return undefined;
+        return this.describe(CaughtFailureSchema.parse(failure.cause), depth + 1);
+    }
+    /** Details as a JSON object with every configured secret removed; anything else is dropped. */
+    detailsOf(details) {
+        const json = this.json(details);
+        if (json === undefined)
+            return undefined;
+        const object = JsonObjectSchema.safeParse(json);
+        return object.success ? { ...object.data } : undefined;
+    }
+    /**
+     * `value` as JSON with every configured secret removed: serialized once (bounded), scrubbed as text, parsed back
+     * by the JSON schema. A value that does not serialize (a cycle, a `bigint`, a throwing getter) is dropped.
+     */
+    json(value) {
+        if (value === undefined)
+            return undefined;
+        const text = attempt(() => JSON.stringify(value));
+        if (!text.ok || text.value === undefined || text.value.length > MAX_DETAILS_JSON)
+            return undefined;
+        const scrubbed = this.removeSecrets(text.value);
+        const parsed = attempt(() => JsonValueSchema.safeParse(JSON.parse(scrubbed)));
+        return parsed.ok && parsed.value.success ? parsed.value.data : undefined;
+    }
+}
+/** The describer for a leg with no configured secret: it still never keeps a host error's text. */
+export const HOST_FAILURES = new FailureDescriber();
+//# sourceMappingURL=failure-describer.js.map

package/dist/core/protocol/transport/failure-describer.js.map

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

package/dist/core/protocol/transport/fetch-failure.d.ts

@@ -0,0 +1,9 @@
+import type { GuardedFetch } from "../../../schemas/contracts/protocol/fetch-failure.ts";
+export type { GuardedFetch } from "../../../schemas/contracts/protocol/fetch-failure.ts";
+import { FailureDescriber } from './failure-describer.ts';
+export declare const RPC_FETCH_FAILED = "rpc-fetch-failed";
+/** The URL with userinfo, query and fragment removed: what an output path may show. */
+export declare function scrubbedUrl(input: URL | string): string;
+/** Wrap a fetch so every rejection is {@link RPC_FETCH_FAILED}, value-free. A guarded fetch's own failure passes through. */
+export declare function guardFetch(fetchImpl: GuardedFetch, describer?: FailureDescriber): GuardedFetch;
+//# sourceMappingURL=fetch-failure.d.ts.map

package/dist/core/protocol/transport/fetch-failure.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fetch-failure.d.ts","sourceRoot":"","sources":["../../../../src/core/protocol/transport/fetch-failure.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,sDAAsD,CAAC;AACzF,YAAY,EAAE,YAAY,EAAE,MAAM,sDAAsD,CAAC;AAazF,OAAO,EAAE,gBAAgB,EAAiB,MAAM,wBAAwB,CAAC;AAEzE,eAAO,MAAM,gBAAgB,qBAAqB,CAAC;AAEnD,uFAAuF;AACvF,wBAAgB,WAAW,CAAC,KAAK,EAAE,GAAG,GAAG,MAAM,GAAG,MAAM,CAGvD;AAkBD,6HAA6H;AAC7H,wBAAgB,UAAU,CAAC,SAAS,EAAE,YAAY,EAAE,SAAS,GAAE,gBAAgC,GAAG,YAAY,CAO7G"}

package/dist/core/protocol/transport/fetch-failure.js

@@ -0,0 +1,45 @@
+/**
+ * Credentials never ride a fetch failure out of this package. A host's fetch rejection can echo the request: Bun's
+ * carries the full URL as `path` and quotes it in its message, and a `Headers` construction error quotes the header
+ * name and value it refused (a bearer with a newline, a header value outside Latin-1). The HTTP and relay legs put
+ * credentials in that URL (the relay's `sessionToken` query) and in headers (the bearer, caller headers), so every
+ * fetch they make goes through {@link guardFetch}. Every rejection becomes `UNAVAILABLE` `rpc-fetch-failed` naming
+ * only the URL's origin and path and the host error's `name` and `code` (through the connection's
+ * {@link FailureDescriber}, which also removes every configured secret); the host's message and the raw error are
+ * never carried.
+ */
+import { CapabilityError } from '@vibesdotdev/kernel';
+import { attemptAsync, rethrow } from "../lifecycle/attempt.js";
+import { FailureDescriber, HOST_FAILURES } from "./failure-describer.js";
+export const RPC_FETCH_FAILED = 'rpc-fetch-failed';
+/** The URL with userinfo, query and fragment removed: what an output path may show. */
+export function scrubbedUrl(input) {
+    const parsed = URL.canParse(String(input)) ? new URL(String(input)) : undefined;
+    return parsed ? `${parsed.origin}${parsed.pathname}` : '(unparseable url)';
+}
+function isFetchFailure(failure) {
+    return failure instanceof CapabilityError && failure.reason === RPC_FETCH_FAILED;
+}
+/** The typed fetch failure: the scrubbed URL, and the host error's name and code as the describer keeps them. */
+function fetchFailed(input, failure, describer) {
+    const url = describer.scrub(scrubbedUrl(input));
+    const fields = describer.hostFields(failure);
+    const label = [fields.name, fields.code].filter((part) => part !== undefined).join(' ');
+    return new CapabilityError(`The fetch to ${url} failed${label ? ` (${label})` : ''}.`, 'UNAVAILABLE', {
+        reason: RPC_FETCH_FAILED,
+        retryable: true,
+        details: { url, ...fields }
+    });
+}
+/** Wrap a fetch so every rejection is {@link RPC_FETCH_FAILED}, value-free. A guarded fetch's own failure passes through. */
+export function guardFetch(fetchImpl, describer = HOST_FAILURES) {
+    return async (input, init) => {
+        const fetched = await attemptAsync(() => fetchImpl(input, init));
+        if (fetched.ok)
+            return fetched.value;
+        if (isFetchFailure(fetched.failure))
+            return rethrow(fetched.failure);
+        throw fetchFailed(input, fetched.failure, describer);
+    };
+}
+//# sourceMappingURL=fetch-failure.js.map

package/dist/core/protocol/transport/fetch-failure.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fetch-failure.js","sourceRoot":"","sources":["../../../../src/core/protocol/transport/fetch-failure.ts"],"names":[],"mappings":"AAEA;;;;;;;;;GASG;AACH,OAAO,EAAE,eAAe,EAAsB,MAAM,qBAAqB,CAAC;AAC1E,OAAO,EAAE,YAAY,EAAE,OAAO,EAAE,MAAM,yBAAyB,CAAC;AAChE,OAAO,EAAE,gBAAgB,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AAEzE,MAAM,CAAC,MAAM,gBAAgB,GAAG,kBAAkB,CAAC;AAEnD,uFAAuF;AACvF,MAAM,UAAU,WAAW,CAAC,KAAmB;IAC9C,MAAM,MAAM,GAAG,GAAG,CAAC,QAAQ,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,GAAG,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;IAChF,OAAO,MAAM,CAAC,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,GAAG,MAAM,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,mBAAmB,CAAC;AAC5E,CAAC;AAED,SAAS,cAAc,CAAC,OAAsB;IAC7C,OAAO,OAAO,YAAY,eAAe,IAAI,OAAO,CAAC,MAAM,KAAK,gBAAgB,CAAC;AAClF,CAAC;AAED,iHAAiH;AACjH,SAAS,WAAW,CAAC,KAAmB,EAAE,OAAsB,EAAE,SAA2B;IAC5F,MAAM,GAAG,GAAG,SAAS,CAAC,KAAK,CAAC,WAAW,CAAC,KAAK,CAAC,CAAC,CAAC;IAChD,MAAM,MAAM,GAAG,SAAS,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC;IAC7C,MAAM,KAAK,GAAG,CAAC,MAAM,CAAC,IAAI,EAAE,MAAM,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC,CAAC,IAAI,EAAkB,EAAE,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IACxG,OAAO,IAAI,eAAe,CAAC,gBAAgB,GAAG,UAAU,KAAK,CAAC,CAAC,CAAC,KAAK,KAAK,GAAG,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,aAAa,EAAE;QACrG,MAAM,EAAE,gBAAgB;QACxB,SAAS,EAAE,IAAI;QACf,OAAO,EAAE,EAAE,GAAG,EAAE,GAAG,MAAM,EAAE;KAC3B,CAAC,CAAC;AACJ,CAAC;AAED,6HAA6H;AAC7H,MAAM,UAAU,UAAU,CAAC,SAAuB,EAAE,YAA8B,aAAa;IAC9F,OAAO,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,EAAE;QAC5B,MAAM,OAAO,GAAG,MAAM,YAAY,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC,CAAC;QACjE,IAAI,OAAO,CAAC,EAAE;YAAE,OAAO,OAAO,CAAC,KAAK,CAAC;QACrC,IAAI,cAAc,CAAC,OAAO,CAAC,OAAO,CAAC;YAAE,OAAO,OAAO,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;QACrE,MAAM,WAAW,CAAC,KAAK,EAAE,OAAO,CAAC,OAAO,EAAE,SAAS,CAAC,CAAC;IACtD,CAAC,CAAC;AACH,CAAC"}

package/dist/core/protocol/transport/local-attestation.d.ts

@@ -0,0 +1,67 @@
+import type { AttestedCallerCarrier, LocalAttestationPresentation, LocalAttestationVerifier, SocketAttestationEnvelope, SocketAttestationRecord } from "../../../schemas/contracts/protocol/local-attestation.ts";
+export { constantTimeEqual, LOCAL_ATTESTATION_SECRET_PATTERN, LocalAttestationToken, revealLocalAttestation } from '@vibesdotdev/kernel/credentials';
+export { SocketAttestationEnvelopeSchema } from "../../../schemas/contracts/protocol/local-attestation.ts";
+export type { AttestedCallerCarrier, LocalAttestationPresentation, LocalAttestationVerifier, SocketAttestationEnvelope, SocketAttestationRecord } from "../../../schemas/contracts/protocol/local-attestation.ts";
+/**
+ * Local attestation (RC08): the one way a same-user local peer proves it was
+ * launched by the host that owns a runtime daemon, so the identity that launch
+ * established is admitted instead of refused.
+ *
+ * The trust boundary is the OS user. A daemon writes a fresh random secret to a
+ * 0600 claim file each time it starts (`@vibesdotdev/secrets/attestation`); only a
+ * process running as that user can read it. A client presents the secret in
+ * its transport handshake together with its declared launch identity, and a
+ * listen session that verifies the secret sets
+ * `remotePeer.verified = { source: 'local-attested', caller }`. Without a
+ * verified secret it sets nothing, and the kernel refuses every declared
+ * identity field (`caller-identity-unverified`).
+ *
+ * This module is universal: the verifier contract and the handshake record,
+ * with the kernel's token and constant-time compare re-exported (not
+ * redefined). The claim file is the secrets package's, on the runtime's
+ * filesystem adapter.
+ *
+ * The secret never appears in a log, an error, argv or env: the token redacts
+ * itself from every string, JSON and inspect form, and failures name only the
+ * claim path.
+ */
+import { CapabilityError, type CaughtFailure } from '@vibesdotdev/kernel';
+import { type RuntimeInvokeCaller, type VerifiedTransportIdentity } from '@vibesdotdev/kernel/schemas';
+import { type RpcDeclaredCaller } from '../wire/schemas.ts';
+import type { RpcRequest, RpcResponse } from '../wire/verbs.ts';
+/** The `VerifiedTransportIdentity.source` a verified local attestation sets. */
+export declare const LOCAL_ATTESTED_SOURCE = "local-attested";
+/**
+ * The identity a listen session admits for a presented attestation: the
+ * declared launch identity when the secret verifies, `undefined` otherwise
+ * (no verifier, no secret, a wrong or rotated secret).
+ */
+export declare function attestedIdentity(verifier: LocalAttestationVerifier | undefined, presented: string | undefined, declaredCaller: RpcDeclaredCaller | undefined): VerifiedTransportIdentity | undefined;
+/** Build the socket handshake's attestation record. */
+export declare function socketAttestationRecord(presentation: LocalAttestationPresentation): SocketAttestationRecord;
+/** Whether a decoded socket message is the attestation envelope (the codec already parsed it whole). */
+export declare function isSocketAttestationRecord(message: RpcRequest | RpcResponse | SocketAttestationEnvelope): message is SocketAttestationEnvelope;
+/** The HTTP handshake header carrying the declared launch identity (base64url JSON). */
+export declare const LOCAL_ATTESTATION_CALLER_HEADER = "x-rpc-attested-caller";
+/** Encode a declared caller for {@link LOCAL_ATTESTATION_CALLER_HEADER}. */
+export declare function encodeAttestedCaller(caller: RuntimeInvokeCaller): string;
+/** The reason a malformed attested-caller header is refused. */
+export declare const ATTESTED_CALLER_INVALID = "rpc-attested-caller-invalid";
+/**
+ * Decode {@link LOCAL_ATTESTATION_CALLER_HEADER}. An absent header declares no
+ * identity (`undefined`). A present one that is not base64url JSON naming a
+ * caller fails closed: `INVALID_INPUT` `rpc-attested-caller-invalid`, so an
+ * attested connection is never admitted with an identity it did not state.
+ */
+export declare function decodeAttestedCaller(header: string | null): RuntimeInvokeCaller | undefined;
+/**
+ * The declared launch identity of an attested handshake, validated. A plain
+ * object whose fields parse (an empty one declares nothing) is admitted; any
+ * other shape fails closed: `INVALID_INPUT` `rpc-attested-caller-invalid`
+ * (a caller that is not such an object never reaches here: parse it with
+ * `RpcDeclaredCallerSchema` and refuse with {@link attestedCallerInvalid}).
+ */
+export declare function validateAttestedCaller(declared: RpcDeclaredCaller, carrier?: AttestedCallerCarrier): RuntimeInvokeCaller;
+/** The typed refusal of a declared launch identity that is not a plain object of caller fields, naming where it arrived. */
+export declare function attestedCallerInvalid(cause?: CaughtFailure, carrier?: AttestedCallerCarrier): CapabilityError;
+//# sourceMappingURL=local-attestation.d.ts.map

package/dist/core/protocol/transport/local-attestation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"local-attestation.d.ts","sourceRoot":"","sources":["../../../../src/core/protocol/transport/local-attestation.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,qBAAqB,EAAE,4BAA4B,EAAE,wBAAwB,EAAE,yBAAyB,EAAE,uBAAuB,EAAE,MAAM,0DAA0D,CAAC;AAClN,OAAO,EAAE,iBAAiB,EAAE,gCAAgC,EAAE,qBAAqB,EAAE,sBAAsB,EAAE,MAAM,iCAAiC,CAAC;AACrJ,OAAO,EAAE,+BAA+B,EAAE,MAAM,0DAA0D,CAAC;AAC3G,YAAY,EAAE,qBAAqB,EAAE,4BAA4B,EAAE,wBAAwB,EAAE,yBAAyB,EAAE,uBAAuB,EAAE,MAAM,0DAA0D,CAAC;AAClN;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,EAAE,eAAe,EAAE,KAAK,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAE1E,OAAO,EAA0B,KAAK,mBAAmB,EAAE,KAAK,yBAAyB,EAAE,MAAM,6BAA6B,CAAC;AAE/H,OAAO,EAA2B,KAAK,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AACrF,OAAO,KAAK,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAEhE,gFAAgF;AAChF,eAAO,MAAM,qBAAqB,mBAAmB,CAAC;AAEtD;;;;GAIG;AACH,wBAAgB,gBAAgB,CAC/B,QAAQ,EAAE,wBAAwB,GAAG,SAAS,EAC9C,SAAS,EAAE,MAAM,GAAG,SAAS,EAC7B,cAAc,EAAE,iBAAiB,GAAG,SAAS,GAC3C,yBAAyB,GAAG,SAAS,CAIvC;AAED,uDAAuD;AACvD,wBAAgB,uBAAuB,CAAC,YAAY,EAAE,4BAA4B,GAAG,uBAAuB,CAK3G;AAED,wGAAwG;AACxG,wBAAgB,yBAAyB,CACxC,OAAO,EAAE,UAAU,GAAG,WAAW,GAAG,yBAAyB,GAC3D,OAAO,IAAI,yBAAyB,CAEtC;AAED,wFAAwF;AACxF,eAAO,MAAM,+BAA+B,0BAA0B,CAAC;AAEvE,4EAA4E;AAC5E,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,mBAAmB,GAAG,MAAM,CAKxE;AAED,gEAAgE;AAChE,eAAO,MAAM,uBAAuB,gCAAgC,CAAC;AAErE;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,GAAG,mBAAmB,GAAG,SAAS,CAU3F;AAED;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CAAC,QAAQ,EAAE,iBAAiB,EAAE,OAAO,GAAE,qBAAqC,GAAG,mBAAmB,CAKvI;AAED,4HAA4H;AAC5H,wBAAgB,qBAAqB,CAAC,KAAK,CAAC,EAAE,aAAa,EAAE,OAAO,GAAE,qBAAqC,GAAG,eAAe,CAK5H"}