@aster-rpc/aster 0.1.2

package/dist/service.js

@@ -0,0 +1,98 @@
+/**
+ * Service metadata types and registry.
+ *
+ * These types describe the structure of an Aster RPC service at runtime.
+ * They are populated by the decorators in decorators.ts.
+ */
+/** Attribute key used to store ServiceInfo on decorated classes. */
+export const SERVICE_INFO_KEY = Symbol.for('aster.service_info');
+/** Attribute key used to store MethodInfo on decorated methods. */
+export const METHOD_INFO_KEY = Symbol.for('aster.method_info');
+/** Get ServiceInfo from a decorated class or instance. */
+export function getServiceInfo(target) {
+    if (target === null || target === undefined)
+        return undefined;
+    // Check on the class itself
+    const info = target[SERVICE_INFO_KEY];
+    if (info)
+        return info;
+    // Check on the constructor (if target is an instance)
+    const ctor = target.constructor;
+    if (ctor)
+        return ctor[SERVICE_INFO_KEY];
+    return undefined;
+}
+/**
+ * Registry for looking up registered services and dispatching RPC calls.
+ */
+export class ServiceRegistry {
+    _services = new Map(); // key: "name/version"
+    _servicesByName = new Map(); // key: name (latest)
+    /** Register a service instance. */
+    register(serviceInstance) {
+        const info = getServiceInfo(serviceInstance);
+        if (!info) {
+            throw new TypeError(`${serviceInstance.constructor.name} is not decorated with @Service. ` +
+                `Use @Service({ name: ..., version: ... }) before registering.`);
+        }
+        const key = `${info.name}/${info.version}`;
+        if (this._services.has(key)) {
+            throw new Error(`Service ${info.name} v${info.version} is already registered.`);
+        }
+        // Attach the instance
+        info.instance = serviceInstance;
+        this._services.set(key, info);
+        this._servicesByName.set(info.name, info);
+        return info;
+    }
+    /** Look up a service by name and optional version. */
+    lookup(serviceName, version) {
+        if (version !== undefined) {
+            return this._services.get(`${serviceName}/${version}`);
+        }
+        return this._servicesByName.get(serviceName);
+    }
+    /** Look up a specific method in a service. */
+    lookupMethod(serviceName, methodName, version) {
+        const svc = this.lookup(serviceName, version);
+        if (!svc)
+            return undefined;
+        const method = svc.methods.get(methodName);
+        if (!method)
+            return undefined;
+        return [svc, method];
+    }
+    /** All registered services. */
+    services() {
+        return this._services.values();
+    }
+    /** Number of registered services. */
+    get size() {
+        return this._services.size;
+    }
+    /** Get all registered services as an array. */
+    getAllServices() {
+        return [...this._services.values()];
+    }
+}
+/** Look up a method on a service info object. */
+export function getMethod(serviceInfo, methodName) {
+    return serviceInfo.methods.get(methodName);
+}
+/** Check if a service has a method. */
+export function hasMethod(serviceInfo, methodName) {
+    return serviceInfo.methods.has(methodName);
+}
+// ── Default registry singleton ────────────────────────────────────────────────
+let _defaultRegistry;
+/** Get the process-wide default registry (creates one if not set). */
+export function getDefaultRegistry() {
+    if (!_defaultRegistry)
+        _defaultRegistry = new ServiceRegistry();
+    return _defaultRegistry;
+}
+/** Set the process-wide default registry. */
+export function setDefaultRegistry(registry) {
+    _defaultRegistry = registry;
+}
+//# sourceMappingURL=service.js.map

package/dist/service.js.map

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

package/dist/session.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Session-scoped services -- multiplexed calls on a single QUIC stream.
+ *
+ * Spec reference: Aster-session-scoped-services.md
+ *
+ * Instead of opening a new stream per RPC, session-scoped services
+ * keep a single bidirectional stream open. Each call is demarcated
+ * by CALL/CANCEL frames:
+ *
+ *   Stream: [StreamHeader] [CALL + CallHeader] [request] [response] [TRAILER] ...
+ *
+ * The StreamHeader has an empty method ("") to indicate session mode.
+ * Each CALL frame carries a CallHeader with the method name and call ID.
+ */
+import type { Codec } from './codec.js';
+import { StreamHeader } from './protocol.js';
+import type { ServiceInfo } from './service.js';
+import { type Interceptor } from './interceptors/base.js';
+/**
+ * Server-side session handler.
+ *
+ * Reads CALL frames from a single stream, dispatches to the appropriate
+ * method handler on a per-session service instance, and writes responses.
+ */
+export declare class SessionServer {
+    private codec;
+    private interceptors;
+    constructor(codec?: Codec, interceptors?: Interceptor[]);
+    /**
+     * Handle a session stream. Creates a fresh service instance, then reads
+     * CALL frames in a loop, dispatching each to the appropriate method
+     * handler until the stream ends.
+     */
+    handleSession(recv: {
+        readExact(n: number): Promise<Uint8Array>;
+    }, send: {
+        writeAll(data: Uint8Array): Promise<void>;
+    }, serviceInfo: ServiceInfo, _streamHeader: StreamHeader, peer?: string, attributes?: Record<string, string>): Promise<void>;
+    private getDeadlineMs;
+    private withDeadline;
+    private handleUnary;
+    private handleServerStream;
+    private handleClientStream;
+    private handleBidiStream;
+    private writeOkTrailer;
+    private drainRequestFrame;
+}
+/**
+ * Client-side session stub -- tracks an active session-scoped RPC stream.
+ */
+export declare class SessionStub {
+    private readonly transport;
+    readonly sessionId: string;
+    private _cancelled;
+    constructor(transport: {
+        close?(): Promise<void>;
+    }, sessionId: string);
+    cancel(): Promise<void>;
+    get cancelled(): boolean;
+}
+export declare function createSession(transport: {
+    close?(): Promise<void>;
+}, sessionId?: string): Promise<SessionStub>;
+//# sourceMappingURL=session.d.ts.map

package/dist/session.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.d.ts","sourceRoot":"","sources":["../src/session.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAUxC,OAAO,EAAyB,YAAY,EAAE,MAAM,eAAe,CAAC;AAEpE,OAAO,KAAK,EAAE,WAAW,EAAc,MAAM,cAAc,CAAC;AAE5D,OAAO,EACL,KAAK,WAAW,EAIjB,MAAM,wBAAwB,CAAC;AAGhC;;;;;GAKG;AACH,qBAAa,aAAa;IACxB,OAAO,CAAC,KAAK,CAAQ;IACrB,OAAO,CAAC,YAAY,CAAgB;gBAExB,KAAK,CAAC,EAAE,KAAK,EAAE,YAAY,CAAC,EAAE,WAAW,EAAE;IAKvD;;;;OAIG;IACG,aAAa,CACjB,IAAI,EAAE;QAAE,SAAS,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CAAA;KAAE,EACnD,IAAI,EAAE;QAAE,QAAQ,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;KAAE,EACnD,WAAW,EAAE,WAAW,EACxB,aAAa,EAAE,YAAY,EAC3B,IAAI,CAAC,EAAE,MAAM,EACb,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAClC,OAAO,CAAC,IAAI,CAAC;IAqHhB,OAAO,CAAC,aAAa;YASP,YAAY;YAyBZ,WAAW;YAwBX,kBAAkB;YA6BlB,kBAAkB;YAwDlB,gBAAgB;YA+ChB,cAAc;YAKd,iBAAiB;CAQhC;AAID;;GAEG;AACH,qBAAa,WAAW;IAIpB,OAAO,CAAC,QAAQ,CAAC,SAAS;IAC1B,QAAQ,CAAC,SAAS,EAAE,MAAM;IAJ5B,OAAO,CAAC,UAAU,CAAS;gBAGR,SAAS,EAAE;QAAE,KAAK,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;KAAE,EAC9C,SAAS,EAAE,MAAM;IAGtB,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC;IAK7B,IAAI,SAAS,IAAI,OAAO,CAEvB;CACF;AAID,wBAAsB,aAAa,CACjC,SAAS,EAAE;IAAE,KAAK,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;CAAE,EACtC,SAAS,CAAC,EAAE,MAAM,GACjB,OAAO,CAAC,WAAW,CAAC,CAGtB"}

package/dist/session.js

@@ -0,0 +1,350 @@
+/**
+ * Session-scoped services -- multiplexed calls on a single QUIC stream.
+ *
+ * Spec reference: Aster-session-scoped-services.md
+ *
+ * Instead of opening a new stream per RPC, session-scoped services
+ * keep a single bidirectional stream open. Each call is demarcated
+ * by CALL/CANCEL frames:
+ *
+ *   Stream: [StreamHeader] [CALL + CallHeader] [request] [response] [TRAILER] ...
+ *
+ * The StreamHeader has an empty method ("") to indicate session mode.
+ * Each CALL frame carries a CallHeader with the method name and call ID.
+ */
+import { JsonCodec } from './codec.js';
+import { writeFrame, readFrame, TRAILER, CALL, CANCEL, COMPRESSED, } from './framing.js';
+import { RpcStatus } from './protocol.js';
+import { StatusCode, RpcError } from './status.js';
+import { RpcPattern } from './types.js';
+import { buildCallContext, applyRequestInterceptors, applyResponseInterceptors, } from './interceptors/base.js';
+import { MAX_HANDLER_TIMEOUT_S, MAX_CLIENT_STREAM_ITEMS, validateMetadata, LimitExceeded } from './limits.js';
+/**
+ * Server-side session handler.
+ *
+ * Reads CALL frames from a single stream, dispatches to the appropriate
+ * method handler on a per-session service instance, and writes responses.
+ */
+export class SessionServer {
+    codec;
+    interceptors;
+    constructor(codec, interceptors) {
+        this.codec = codec ?? new JsonCodec();
+        this.interceptors = interceptors ?? [];
+    }
+    /**
+     * Handle a session stream. Creates a fresh service instance, then reads
+     * CALL frames in a loop, dispatching each to the appropriate method
+     * handler until the stream ends.
+     */
+    async handleSession(recv, send, serviceInfo, _streamHeader, peer, attributes) {
+        // Create a fresh service instance per session so each client gets
+        // its own state (matches Python SessionServer behaviour).
+        let instance;
+        try {
+            const ctor = serviceInfo.instance.constructor;
+            instance = new ctor();
+        }
+        catch {
+            instance = serviceInfo.instance;
+        }
+        // Read CALL frames in a loop
+        while (true) {
+            const frame = await readFrame(recv, 0);
+            if (!frame)
+                break; // stream ended
+            const [payload, flags] = frame;
+            if (flags & CANCEL) {
+                const status = new RpcStatus({ code: StatusCode.CANCELLED, message: 'cancelled' });
+                await writeFrame(send, this.codec.encode(status), TRAILER);
+                continue;
+            }
+            if (!(flags & CALL)) {
+                const status = new RpcStatus({ code: StatusCode.INTERNAL, message: 'expected CALL frame in session stream' });
+                await writeFrame(send, this.codec.encode(status), TRAILER);
+                break;
+            }
+            // Decode CallHeader
+            const callHeader = this.codec.decode(payload);
+            // Validate per-call metadata (G3/G11)
+            try {
+                validateMetadata(callHeader.metadataKeys ?? [], callHeader.metadataValues ?? []);
+            }
+            catch (e) {
+                if (e instanceof LimitExceeded) {
+                    const status = new RpcStatus({ code: StatusCode.RESOURCE_EXHAUSTED, message: e.message });
+                    await writeFrame(send, this.codec.encode(status), TRAILER);
+                    continue;
+                }
+                throw e;
+            }
+            const methodInfo = serviceInfo.methods.get(callHeader.method);
+            if (!methodInfo) {
+                const status = new RpcStatus({
+                    code: StatusCode.NOT_FOUND,
+                    message: `method ${callHeader.method} not found`,
+                });
+                await writeFrame(send, this.codec.encode(status), TRAILER);
+                continue;
+            }
+            // Build per-call context with peer attributes for auth interceptors
+            const callCtx = buildCallContext({
+                service: serviceInfo.name,
+                method: callHeader.method,
+                callId: callHeader.callId || undefined,
+                peer,
+                pattern: methodInfo.pattern,
+                idempotent: methodInfo.idempotent,
+                attributes,
+                deadlineEpochMs: callHeader.deadlineEpochMs || 0,
+            });
+            // Run auth interceptors before reading the request
+            try {
+                await applyRequestInterceptors(this.interceptors, callCtx, null);
+            }
+            catch (e) {
+                if (e instanceof RpcError) {
+                    const status = new RpcStatus({ code: e.code, message: e.message });
+                    await writeFrame(send, this.codec.encode(status), TRAILER);
+                    // Drain the request frame(s) so the stream stays in sync
+                    await this.drainRequestFrame(recv);
+                    continue;
+                }
+                throw e;
+            }
+            // Dispatch based on pattern
+            try {
+                switch (methodInfo.pattern) {
+                    case RpcPattern.UNARY:
+                        await this.handleUnary(instance, methodInfo, callCtx, send, recv);
+                        break;
+                    case RpcPattern.SERVER_STREAM:
+                        await this.handleServerStream(instance, methodInfo, callCtx, send, recv);
+                        break;
+                    case RpcPattern.CLIENT_STREAM:
+                        await this.handleClientStream(instance, methodInfo, callCtx, send, recv);
+                        break;
+                    case RpcPattern.BIDI_STREAM:
+                        await this.handleBidiStream(instance, methodInfo, callCtx, send, recv);
+                        break;
+                    default: {
+                        const status = new RpcStatus({
+                            code: StatusCode.UNIMPLEMENTED,
+                            message: `unsupported pattern: ${methodInfo.pattern}`,
+                        });
+                        await writeFrame(send, this.codec.encode(status), TRAILER);
+                    }
+                }
+            }
+            catch (e) {
+                const err = e instanceof RpcError ? e : new RpcError(StatusCode.INTERNAL, String(e));
+                const status = new RpcStatus({ code: err.code, message: err.message });
+                try {
+                    await writeFrame(send, this.codec.encode(status), TRAILER);
+                }
+                catch { /* stream may be gone */ }
+            }
+        }
+    }
+    // -- Helpers ----------------------------------------------------------------
+    getDeadlineMs(callCtx) {
+        const maxMs = MAX_HANDLER_TIMEOUT_S * 1000;
+        const deadline = callCtx?.deadline;
+        if (deadline == null || deadline <= 0)
+            return Date.now() + maxMs;
+        const clientMs = deadline * 1000;
+        const serverMax = Date.now() + maxMs;
+        return Math.min(clientMs, serverMax);
+    }
+    async withDeadline(callCtx, fn) {
+        const deadlineMs = this.getDeadlineMs(callCtx);
+        const remaining = deadlineMs - Date.now();
+        if (remaining <= 0)
+            throw new RpcError(StatusCode.DEADLINE_EXCEEDED, 'deadline exceeded');
+        let timer;
+        try {
+            return await Promise.race([
+                fn(),
+                new Promise((_, reject) => {
+                    timer = setTimeout(() => reject(new RpcError(StatusCode.DEADLINE_EXCEEDED, 'deadline exceeded')), remaining);
+                }),
+            ]);
+        }
+        finally {
+            if (timer !== undefined)
+                clearTimeout(timer);
+        }
+    }
+    // -- Pattern handlers -------------------------------------------------------
+    async handleUnary(instance, methodInfo, callCtx, send, recv) {
+        const reqFrame = await readFrame(recv, 0);
+        if (!reqFrame)
+            return;
+        const [reqPayload, reqFlags] = reqFrame;
+        const compressed = !!(reqFlags & COMPRESSED);
+        let request = compressed
+            ? this.codec.decodeCompressed(reqPayload, true)
+            : this.codec.decode(reqPayload);
+        request = await applyRequestInterceptors(this.interceptors, callCtx, request);
+        let response = await this.withDeadline(callCtx, () => methodInfo.handler.call(instance, request));
+        response = await applyResponseInterceptors(this.interceptors, callCtx, response);
+        const [respPayload, respCompressed] = this.codec.encodeCompressed(response);
+        await writeFrame(send, respPayload, respCompressed ? COMPRESSED : 0);
+    }
+    async handleServerStream(instance, methodInfo, callCtx, send, recv) {
+        const reqFrame = await readFrame(recv, 0);
+        if (!reqFrame)
+            return;
+        const [reqPayload, reqFlags] = reqFrame;
+        const compressed = !!(reqFlags & COMPRESSED);
+        let request = compressed
+            ? this.codec.decodeCompressed(reqPayload, true)
+            : this.codec.decode(reqPayload);
+        request = await applyRequestInterceptors(this.interceptors, callCtx, request);
+        const gen = methodInfo.handler.call(instance, request);
+        const deadlineMs = this.getDeadlineMs(callCtx);
+        for await (let response of gen) {
+            if (deadlineMs != null && Date.now() > deadlineMs) {
+                throw new RpcError(StatusCode.DEADLINE_EXCEEDED, 'deadline exceeded');
+            }
+            response = await applyResponseInterceptors(this.interceptors, callCtx, response);
+            const [respPayload, respCompressed] = this.codec.encodeCompressed(response);
+            await writeFrame(send, respPayload, respCompressed ? COMPRESSED : 0);
+        }
+        await this.writeOkTrailer(send);
+    }
+    async handleClientStream(instance, methodInfo, callCtx, send, recv) {
+        const requests = [];
+        while (true) {
+            const frame = await readFrame(recv, 0);
+            if (!frame)
+                break;
+            const [p, f] = frame;
+            if (f & TRAILER) {
+                // Validate EoI: must be status=OK (G4)
+                try {
+                    const eoi = this.codec.decode(p);
+                    if (eoi.code !== StatusCode.OK) {
+                        const status = new RpcStatus({
+                            code: StatusCode.INTERNAL,
+                            message: `client sent non-OK EoI trailer (code=${eoi.code})`,
+                        });
+                        await writeFrame(send, this.codec.encode(status), TRAILER);
+                        return;
+                    }
+                }
+                catch {
+                    const status = new RpcStatus({ code: StatusCode.INTERNAL, message: 'malformed EoI trailer' });
+                    await writeFrame(send, this.codec.encode(status), TRAILER);
+                    return;
+                }
+                break;
+            }
+            if (f & CANCEL)
+                continue;
+            if (requests.length >= MAX_CLIENT_STREAM_ITEMS) {
+                const status = new RpcStatus({
+                    code: StatusCode.RESOURCE_EXHAUSTED,
+                    message: `client stream exceeded ${MAX_CLIENT_STREAM_ITEMS} items`,
+                });
+                await writeFrame(send, this.codec.encode(status), TRAILER);
+                return;
+            }
+            const compressed = !!(f & COMPRESSED);
+            const req = compressed
+                ? this.codec.decodeCompressed(p, true)
+                : this.codec.decode(p);
+            requests.push(await applyRequestInterceptors(this.interceptors, callCtx, req));
+        }
+        async function* requestIter() { for (const r of requests)
+            yield r; }
+        let response = await this.withDeadline(callCtx, () => methodInfo.handler.call(instance, requestIter()));
+        response = await applyResponseInterceptors(this.interceptors, callCtx, response);
+        const [respPayload, respCompressed] = this.codec.encodeCompressed(response);
+        await writeFrame(send, respPayload, respCompressed ? COMPRESSED : 0);
+        await this.writeOkTrailer(send);
+    }
+    async handleBidiStream(instance, methodInfo, callCtx, send, recv) {
+        const self = this;
+        // Wrap the error in an object so TS doesn't narrow it to `never`
+        // after the for-await loop (closure mutations to a local var aren't
+        // visible to the flow analyzer; property access through one is).
+        const errBox = { value: null };
+        async function* requestIter() {
+            try {
+                while (true) {
+                    const frame = await readFrame(recv, 0);
+                    if (!frame)
+                        break;
+                    const [p, f] = frame;
+                    if (f & TRAILER)
+                        break;
+                    if (f & CANCEL)
+                        continue;
+                    const compressed = !!(f & COMPRESSED);
+                    const req = compressed
+                        ? self.codec.decodeCompressed(p, true)
+                        : self.codec.decode(p);
+                    yield req;
+                }
+            }
+            catch (e) {
+                errBox.value = e instanceof Error ? e : new Error(String(e));
+            }
+        }
+        const gen = methodInfo.handler.call(instance, requestIter());
+        const deadlineMs = this.getDeadlineMs(callCtx);
+        for await (const response of gen) {
+            if (Date.now() > deadlineMs) {
+                throw new RpcError(StatusCode.DEADLINE_EXCEEDED, 'deadline exceeded');
+            }
+            const [respPayload, respCompressed] = this.codec.encodeCompressed(response);
+            await writeFrame(send, respPayload, respCompressed ? COMPRESSED : 0);
+        }
+        if (errBox.value !== null) {
+            throw new RpcError(StatusCode.INTERNAL, `bidi stream reader error: ${errBox.value.message}`);
+        }
+        await this.writeOkTrailer(send);
+    }
+    // -- Helpers ----------------------------------------------------------------
+    async writeOkTrailer(send) {
+        const status = new RpcStatus({ code: StatusCode.OK });
+        await writeFrame(send, this.codec.encode(status), TRAILER);
+    }
+    async drainRequestFrame(recv) {
+        try {
+            const frame = await readFrame(recv, 0);
+            // Just discard -- we needed to consume it so the next CALL frame
+            // is properly aligned on the stream.
+            void frame;
+        }
+        catch { /* ignore */ }
+    }
+}
+// ── Session stub (client-side) ───────────────────────────────────────────────
+/**
+ * Client-side session stub -- tracks an active session-scoped RPC stream.
+ */
+export class SessionStub {
+    transport;
+    sessionId;
+    _cancelled = false;
+    constructor(transport, sessionId) {
+        this.transport = transport;
+        this.sessionId = sessionId;
+    }
+    async cancel() {
+        this._cancelled = true;
+        if (this.transport.close)
+            await this.transport.close();
+    }
+    get cancelled() {
+        return this._cancelled;
+    }
+}
+// ── Factory functions ────────────────────────────────────────────────────────
+export async function createSession(transport, sessionId) {
+    const id = sessionId ?? crypto.randomUUID?.() ?? `session-${Date.now()}`;
+    return new SessionStub(transport, id);
+}
+//# sourceMappingURL=session.js.map

package/dist/session.js.map

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

package/dist/status.d.ts

@@ -0,0 +1,113 @@
+/**
+ * Aster RPC status codes and error hierarchy.
+ *
+ * Spec reference: S6.5 (status codes).
+ *
+ * Codes 0-16 mirror gRPC's google.rpc.Code semantically. Codes 100+
+ * are Aster-native and have no gRPC equivalent. The 17-99 range is
+ * reserved as a buffer in case gRPC ever extends its enum.
+ *
+ * A common gripe with gRPC's status codes is that there are too few
+ * to express the variety of failures real services actually hit.
+ * The 100+ space gives Aster room to mint more precise codes over
+ * time, signalling clearly that they are intentionally separate
+ * from the gRPC vocabulary.
+ */
+export declare const StatusCode: {
+    readonly OK: 0;
+    readonly CANCELLED: 1;
+    readonly UNKNOWN: 2;
+    readonly INVALID_ARGUMENT: 3;
+    readonly DEADLINE_EXCEEDED: 4;
+    readonly NOT_FOUND: 5;
+    readonly ALREADY_EXISTS: 6;
+    readonly PERMISSION_DENIED: 7;
+    readonly RESOURCE_EXHAUSTED: 8;
+    readonly FAILED_PRECONDITION: 9;
+    readonly ABORTED: 10;
+    readonly OUT_OF_RANGE: 11;
+    readonly UNIMPLEMENTED: 12;
+    readonly INTERNAL: 13;
+    readonly UNAVAILABLE: 14;
+    readonly DATA_LOSS: 15;
+    readonly UNAUTHENTICATED: 16;
+    /**
+     * The wire payload doesn't match the published contract: e.g. the
+     * JSON dict has fields the receiver's @WireType class doesn't
+     * declare, or vice versa. Distinct from INVALID_ARGUMENT because
+     * the violation is about data SHAPE, not value, and shape
+     * violations can occur at any nesting depth (a top-level
+     * INVALID_ARGUMENT label doesn't apply when the bad field is two
+     * objects deep). The producer owns the contract; consumers must
+     * use the field names defined by the producer's manifest.
+     */
+    readonly CONTRACT_VIOLATION: 101;
+};
+export type StatusCode = (typeof StatusCode)[keyof typeof StatusCode];
+export declare function statusName(code: StatusCode): string;
+/** Base error class for Aster RPC errors. */
+export declare class RpcError extends Error {
+    readonly code: StatusCode;
+    readonly details: Record<string, string>;
+    constructor(code: StatusCode, message?: string, details?: Record<string, string>);
+    /** Create the most specific RpcError subclass for a status code. */
+    static fromStatus(code: StatusCode, message?: string, details?: Record<string, string>): RpcError;
+}
+export declare class CancelledError extends RpcError {
+    constructor(message?: string, details?: Record<string, string>);
+}
+export declare class UnknownRpcError extends RpcError {
+    constructor(message?: string, details?: Record<string, string>);
+}
+export declare class InvalidArgumentError extends RpcError {
+    constructor(message?: string, details?: Record<string, string>);
+}
+export declare class DeadlineExceededError extends RpcError {
+    constructor(message?: string, details?: Record<string, string>);
+}
+export declare class NotFoundError extends RpcError {
+    constructor(message?: string, details?: Record<string, string>);
+}
+export declare class AlreadyExistsError extends RpcError {
+    constructor(message?: string, details?: Record<string, string>);
+}
+export declare class PermissionDeniedError extends RpcError {
+    constructor(message?: string, details?: Record<string, string>);
+}
+export declare class ResourceExhaustedError extends RpcError {
+    constructor(message?: string, details?: Record<string, string>);
+}
+export declare class FailedPreconditionError extends RpcError {
+    constructor(message?: string, details?: Record<string, string>);
+}
+export declare class AbortedError extends RpcError {
+    constructor(message?: string, details?: Record<string, string>);
+}
+export declare class OutOfRangeError extends RpcError {
+    constructor(message?: string, details?: Record<string, string>);
+}
+export declare class UnimplementedError extends RpcError {
+    constructor(message?: string, details?: Record<string, string>);
+}
+export declare class InternalError extends RpcError {
+    constructor(message?: string, details?: Record<string, string>);
+}
+export declare class UnavailableError extends RpcError {
+    constructor(message?: string, details?: Record<string, string>);
+}
+export declare class DataLossError extends RpcError {
+    constructor(message?: string, details?: Record<string, string>);
+}
+export declare class UnauthenticatedError extends RpcError {
+    constructor(message?: string, details?: Record<string, string>);
+}
+/**
+ * Raised when the wire payload doesn't match the published contract.
+ *
+ * Carries the offending field names in `details.unexpected_fields`
+ * (comma-separated, repr-sanitized).
+ */
+export declare class ContractViolationError extends RpcError {
+    constructor(message?: string, details?: Record<string, string>);
+}
+//# sourceMappingURL=status.d.ts.map

package/dist/status.d.ts.map

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