@oatscenter/trellis 0.100.0-rc.1

package/session.d.ts

@@ -0,0 +1,862 @@
+import { type JetStreamClient } from "@nats-io/jetstream";
+import { type Msg, type NatsConnection } from "@nats-io/nats-core";
+import type { EventDesc, FeedDesc, InferSchemaType } from "./participant.ts";
+import { type PermissionAtom as DescriptorPermissionAtom, type RuntimeApi } from "./participant_runtime/api.ts";
+import type { Codec } from "./generated.ts";
+import type { ParticipantKvMetadata } from "./participant_runtime/metadata.ts";
+import { AuthorizationProviderCache } from "./auth/authorization_context.ts";
+import { AsyncResult, BaseError, type MaybeAsync, Result } from "@oatscenter/result";
+import { Type } from "typebox";
+import { type JsonValue } from "./codec.ts";
+import { AuthError, SchemaValidationError, type StoreError, TransferError, TransportError, type TrellisErrorInstance, type TrellisErrorMap, type TrellisErrorName, UnexpectedError, ValidationError } from "./errors/index.ts";
+import { RemoteError } from "./errors/RemoteError.ts";
+import { type LoggerLike } from "./globals.ts";
+import { type KvRepresentation, type ResourceMigrations, TypedKV } from "./kv.ts";
+import type { ActiveJob, JobRef, JobTypeMetadata, JobUpdatesOptions, JobUpdateSubscription } from "./jobs.ts";
+import type { StoreWaitOptions, TypedStore, TypedStoreEntry } from "./store.ts";
+import { OperationInvoker, type OperationRefData } from "./operations.ts";
+import { type DeleteOutput as StateDeleteResponse, type GetOutput as StateGetResponse, type PutOutput as StateSetResponse } from "./internal_sdk/generated/apis/state/mod.js";
+import { type FileInfo, type ReceiveTransferGrant, type ReceiveTransferHandle, type SendTransferGrant, type SendTransferHandle } from "./transfer.ts";
+import { TrellisConnection } from "./connection.ts";
+export type { NatsConnection } from "@nats-io/nats-core";
+type InferRuntimeRpcError<T> = T extends {
+    fromSerializable(data: unknown): infer TError;
+} ? TError : never;
+/** Caller projection returned after a context-bound proof is verified locally. */
+export type VerifiedCaller = {
+    type: "verified";
+    sessionKey: string;
+    principalId: string;
+    principalKind: "user" | "service" | "device";
+    participantId: string;
+    contextDigest: string;
+    connectionId: string;
+    loginSessionId: string | null;
+    identityKeyId: string | null;
+    deploymentId: string | null;
+    instanceId: string | null;
+    grantRevision: number;
+    platformPrivileges: ("trellis.auth::admin")[];
+    inboxPrefix: string;
+};
+/** Internal system caller used only by explicitly unauthenticated surfaces. */
+export type InternalCaller = {
+    type: "internal";
+    capabilities: readonly [];
+};
+/** Caller data exposed to Trellis handlers. */
+export type SessionCaller = VerifiedCaller | InternalCaller;
+type LocalAuthorizationRequestMessage = Pick<Msg, "data" | "headers" | "reply" | "subject">;
+type LocalAuthorizationEventMessage = Pick<Msg, "data" | "headers" | "subject">;
+type LocalAuthorizationArgs = {
+    kind: "request";
+    cache: AuthorizationProviderCache | undefined;
+    message: LocalAuthorizationRequestMessage;
+    proofPayload?: Uint8Array;
+    permission: DescriptorPermissionAtom | undefined;
+    requiredCapabilities: readonly string[];
+    identityOnly?: boolean;
+} | {
+    kind: "event";
+    cache: AuthorizationProviderCache | undefined;
+    message: LocalAuthorizationEventMessage;
+    permission: DescriptorPermissionAtom | undefined;
+    descriptorIdentity: string;
+    requiredCapabilities: readonly string[];
+};
+/** Verifies one received request or event through the provider-local WASM cache. */
+export declare function verifyLocalAuthorization(args: LocalAuthorizationArgs): Promise<Result<VerifiedCaller, AuthError>>;
+/**
+ * Safely extract JSON from a NATS message.
+ * The .json() method can throw if the message data is not valid JSON.
+ */
+export declare function safeJson(msg: Msg): Result<JsonValue, UnexpectedError>;
+/** Creates the existing typed transport error for an unavailable optional action. */
+export declare function createActionUnavailableError(action: string, capabilities: readonly string[]): TransportError;
+export declare function base64urlEncode(data: Uint8Array): string;
+export declare function base64urlDecode(s: string): Uint8Array;
+export declare function toArrayBuffer(data: Uint8Array): ArrayBuffer;
+export declare function sha256(data: Uint8Array): Promise<Uint8Array>;
+export declare function buildProofInput(contextDigest: string, subject: string, reply: string, payloadHash: Uint8Array, iat: number, requestId: string): Uint8Array;
+export type TrellisSigner = (data: Uint8Array) => Promise<Uint8Array> | Uint8Array;
+export type TrellisAuth = {
+    sessionKey: string;
+    sign: TrellisSigner;
+    currentIat?: () => number;
+    /** Current authorization-context digest bound into v1 request and event proofs. */
+    contextDigest?: string | (() => string);
+    /** Provider-only local verifier for service request and event handling. */
+    authorizationProviderCache?: AuthorizationProviderCache;
+};
+export type TrellisMode = "client" | "service";
+type OwnedApiFor<TContract> = TContract extends {
+    implements: readonly unknown[];
+} ? RuntimeApi : never;
+type ContractKvFor<TContract> = TContract extends {
+    resources: infer TResources extends Readonly<Record<string, unknown>>;
+} ? {
+    [K in keyof TResources as TResources[K] extends {
+        kind: "kv";
+    } ? K : never]: TResources[K] extends {
+        codec: infer TCodec;
+        availability: infer TAvailability;
+    } ? {
+        value: TCodec extends Codec<infer TValue> ? TValue : unknown;
+        schema: TCodec;
+        required: TAvailability extends "required" ? true : false;
+    } : never;
+} : {};
+type ContractJobsFor<TContract> = TContract extends {
+    resources: infer TResources extends Readonly<Record<string, unknown>>;
+} ? {
+    [K in keyof TResources as TResources[K] extends {
+        kind: "job";
+    } ? K : never]: TResources[K] extends {
+        payload: infer TPayload;
+        result: infer TResult;
+        update: infer TUpdate;
+    } ? {
+        payload: TPayload extends Codec<infer TValue> ? TValue : unknown;
+        result: TResult extends Codec<infer TValue> ? TValue : void;
+        update: TUpdate extends Codec<infer TValue> ? TValue : never;
+    } : never;
+} : {};
+export type RuntimeStateStoreShape = {
+    kind: "value";
+    value: unknown;
+    codec: Codec<unknown>;
+    version: number;
+    migrations: Readonly<Record<number, Codec<unknown>>>;
+};
+export type RuntimeStateStores = Record<string, RuntimeStateStoreShape>;
+export type RuntimeStateStoresForContract<TContract> = TContract extends {
+    resources: infer TResources extends Readonly<Record<string, unknown>>;
+} ? {
+    [K in keyof TResources as TResources[K] extends {
+        kind: "state";
+    } ? K : never]: TResources[K] extends {
+        codec: infer TCodec;
+    } ? {
+        kind: "value";
+        value: TCodec extends Codec<infer TValue> ? TValue : unknown;
+        codec: TCodec;
+        version: TResources[K] extends {
+            version: infer TVersion;
+        } ? TVersion : number;
+        migrations: TResources[K] extends {
+            migrations: infer TMigrations;
+        } ? TMigrations : {};
+    } : never;
+} : {};
+type TrellisApiFor<TContract> = OwnedApiFor<TContract>;
+type RpcMethodsOf<TA extends RuntimeApi> = TA["rpc"];
+export type MethodsOf<TA extends RuntimeApi> = keyof RpcMethodsOf<TA> & string;
+export type RpcMethodNameOf<TA extends RuntimeApi> = MethodsOf<TA>;
+export type OperationsOf<TA extends RuntimeApi> = keyof TA["operations"] & string;
+type EventsOf<TA extends RuntimeApi> = keyof TA["events"] & string;
+export type FeedsOf<TA extends RuntimeApi> = keyof NonNullable<TA["feeds"]> & string;
+type RpcMethodOf<TA extends RuntimeApi, M extends keyof TA["rpc"] & string> = RpcMethodsOf<TA>[M];
+type MethodInputOf<TA extends RuntimeApi, M extends keyof TA["rpc"] & string> = RpcMethodOf<TA, M> extends {
+    input: infer TInput;
+} ? InferSchemaType<TInput> : never;
+export type RpcInputOf<TA extends RuntimeApi, M extends RpcMethodNameOf<TA>> = MethodInputOf<TA, M>;
+type MethodOutputOf<TA extends RuntimeApi, M extends keyof TA["rpc"] & string> = RpcMethodOf<TA, M> extends {
+    output: infer TOutput;
+} ? InferSchemaType<TOutput> : never;
+export type RpcOutputOf<TA extends RuntimeApi, M extends RpcMethodNameOf<TA>> = MethodOutputOf<TA, M>;
+type RpcRequestShapes<TA extends RuntimeApi> = {
+    [M in keyof TA["rpc"] & string]: {
+        input: MethodInputOf<TA, M>;
+        output: MethodOutputOf<TA, M>;
+    };
+};
+type RequestMethodOf<TRequests> = keyof TRequests & string;
+type RequestInputOf<TRequests, M extends RequestMethodOf<TRequests>> = TRequests[M] extends {
+    input: infer TInput;
+} ? TInput : never;
+type RequestOutputOf<TRequests, M extends RequestMethodOf<TRequests>> = TRequests[M] extends {
+    output: infer TOutput;
+} ? TOutput : never;
+type RpcDescriptorOf<TA extends RuntimeApi, M extends keyof TA["rpc"] & string> = RpcMethodOf<TA, M> extends {
+    input: infer TInput;
+    output: infer TOutput;
+    errors?: infer TErrors;
+    runtimeErrors?: infer TRuntimeErrors;
+    declaredErrorTypes?: infer TDeclaredErrorTypes;
+} ? {
+    input: TInput;
+    output: TOutput;
+    errors?: TErrors;
+    runtimeErrors?: TRuntimeErrors;
+    declaredErrorTypes?: TDeclaredErrorTypes;
+} & RpcMethodOf<TA, M> : never;
+type DeclaredBuiltinErrorOf<TNames> = TNames extends readonly (infer TName)[] ? TName extends TrellisErrorName ? TrellisErrorMap[TName] : never : never;
+type DeclaredRuntimeErrorOf<TRuntimeErrors> = TRuntimeErrors extends readonly (infer TRuntimeError)[] ? InferRuntimeRpcError<TRuntimeError> : never;
+type MethodDeclaredErrorOf<TA extends RuntimeApi, M extends keyof TA["rpc"] & string> = RpcDescriptorOf<TA, M> extends {
+    errors?: infer TErrors;
+    runtimeErrors?: infer TRuntimeErrors;
+} ? DeclaredBuiltinErrorOf<TErrors> | DeclaredRuntimeErrorOf<TRuntimeErrors> : never;
+type RequestErrorOf<TA extends RuntimeApi, M extends MethodsOf<TA>> = MethodDeclaredErrorOf<TA, M> | RemoteError | TransportError | ValidationError | UnexpectedError;
+type HandlerErrorOf<TA extends RuntimeApi, M extends MethodsOf<TA>> = MethodDeclaredErrorOf<TA, M> | TrellisErrorInstance;
+type OperationDescriptorOf<TA extends RuntimeApi, O extends OperationsOf<TA>> = TA["operations"][O] extends {
+    input: infer TInput;
+    progress?: infer TProgress;
+    output?: infer TOutput;
+    errors?: infer TErrors;
+    runtimeErrors?: infer TRuntimeErrors;
+    declaredErrorTypes?: infer TDeclaredErrorTypes;
+} ? {
+    input: TInput;
+    progress?: TProgress;
+    output?: TOutput;
+    errors?: TErrors;
+    runtimeErrors?: TRuntimeErrors;
+    declaredErrorTypes?: TDeclaredErrorTypes;
+} & TA["operations"][O] : never;
+type OperationDeclaredErrorOf<TA extends RuntimeApi, O extends OperationsOf<TA>> = OperationDescriptorOf<TA, O> extends {
+    errors?: infer TErrors;
+    runtimeErrors?: infer TRuntimeErrors;
+} ? DeclaredBuiltinErrorOf<TErrors> | DeclaredRuntimeErrorOf<TRuntimeErrors> : never;
+export type OperationHandlerErrorOf<TA extends RuntimeApi, O extends OperationsOf<TA>> = OperationDeclaredErrorOf<TA, O> | TrellisErrorInstance;
+type EventMessageOf<TA extends RuntimeApi, E extends EventsOf<TA>> = TA["events"][E] extends EventDesc<infer TEvent> ? InferSchemaType<TEvent> : never;
+type EventOf<TA extends RuntimeApi, E extends EventsOf<TA>> = EventMessageOf<TA, E>;
+type EventPayloadOf<TA extends RuntimeApi, E extends EventsOf<TA>> = EventOf<TA, E> & Record<string, unknown>;
+/** Runtime metadata assigned to every Trellis event message. */
+export type TrellisEventHeader = Readonly<{
+    /** Stable event id used for event identity and JetStream de-duplication. */
+    id: string;
+    /** Event creation time in ISO-8601 format. */
+    time: string;
+}>;
+/** Event body plus Trellis runtime event metadata. */
+export type TrellisEventMessage<TBody extends Record<string, unknown> = Record<string, unknown>> = Readonly<{
+    /** User-authored contract event body. */
+    body: Readonly<TBody>;
+    /** Runtime metadata assigned by Trellis. */
+    header: TrellisEventHeader;
+}>;
+/** A fully encoded event whose subject, payload, and headers are stable. */
+export type PreparedTrellisEvent<TPayload extends Record<string, unknown> = Record<string, unknown>> = Readonly<{
+    event: string;
+    descriptorIdentity: string;
+    subject: string;
+    /** Runtime event metadata assigned when the event was prepared. */
+    header: TrellisEventHeader;
+    payload: Readonly<TPayload>;
+    encodedPayload: string;
+    headers: Readonly<Record<string, string>>;
+}>;
+export type FeedInputOf<TA extends RuntimeApi, F extends FeedsOf<TA>> = NonNullable<TA["feeds"]>[F] extends FeedDesc<infer TInput, infer _TEvent> ? InferSchemaType<TInput> : never;
+export type FeedEventOf<TA extends RuntimeApi, F extends FeedsOf<TA>> = NonNullable<TA["feeds"]>[F] extends FeedDesc<infer _TInput, infer TEvent> ? InferSchemaType<TEvent> : never;
+export type OperationInputOf<TA extends RuntimeApi, O extends OperationsOf<TA>> = TA["operations"][O] extends {
+    input: infer TInput;
+} ? InferSchemaType<TInput> : never;
+export type OperationProgressOf<TA extends RuntimeApi, O extends OperationsOf<TA>> = TA["operations"][O] extends {
+    progress?: infer TProgress;
+} ? TProgress extends undefined ? unknown : InferSchemaType<NonNullable<TProgress>> : unknown;
+/** Infers the transient update payload for an operation descriptor. */
+export type OperationUpdateOf<TA extends RuntimeApi, O extends OperationsOf<TA>> = TA["operations"][O] extends {
+    update?: infer TUpdate;
+} ? TUpdate extends undefined ? unknown : InferSchemaType<NonNullable<TUpdate>> : unknown;
+export type OperationOutputOf<TA extends RuntimeApi, O extends OperationsOf<TA>> = TA["operations"][O] extends {
+    output?: infer TOutput;
+} ? TOutput extends undefined ? unknown : InferSchemaType<NonNullable<TOutput>> : unknown;
+export type OperationRuntimeHandle<TProgress, TOutput, TError extends BaseError, TUpdate = unknown> = {
+    id: string;
+    started(): AsyncResult<RuntimeOperationSnapshot, BaseError>;
+    progress(value: TProgress): AsyncResult<RuntimeOperationSnapshot, BaseError>;
+    /** Emits a transient update without changing the persisted snapshot. */
+    emitUpdate(value: TUpdate): AsyncResult<void, BaseError>;
+    complete(value: TOutput): AsyncResult<RuntimeOperationSnapshot, BaseError>;
+    fail(error: TError): AsyncResult<RuntimeOperationSnapshot, BaseError>;
+    cancel(): AsyncResult<RuntimeOperationSnapshot, BaseError>;
+    attach(job: {
+        wait(): AsyncResult<unknown, BaseError>;
+    }): AsyncResult<RuntimeOperationSnapshot, BaseError>;
+    signals(): AsyncIterable<RuntimeOperationSignal>;
+    nextSignal(name?: string): AsyncResult<RuntimeOperationSignal, BaseError>;
+    /** Durably acknowledges a signal after its side effects have been accepted. */
+    acknowledgeSignal(sequence: number): AsyncResult<void, BaseError>;
+    defer(): OperationDeferred;
+};
+export type OperationDeferred = {
+    kind: "deferred";
+};
+/**
+ * Returns true when a handler result explicitly leaves operation completion to
+ * an external control path.
+ */
+export declare function isOperationDeferred(value: unknown): value is OperationDeferred;
+export type AcceptedOperation<TProgress, TOutput, TError extends BaseError, TUpdate = unknown> = OperationRuntimeHandle<TProgress, TOutput, TError, TUpdate> & {
+    ref: OperationRefData;
+    snapshot: RuntimeOperationSnapshot & {
+        progress?: TProgress;
+        output?: TOutput;
+    };
+};
+export type OperationTransferHandle = {
+    updates(): AsyncIterable<RuntimeOperationTransferProgress>;
+    completed(): AsyncResult<FileInfo, TransferError>;
+};
+/** Decoded current State value and its opaque storage revision. */
+export type StateValue<T> = Readonly<{
+    value: T;
+    revision: string;
+    createdAt: string;
+    updatedAt: string;
+}>;
+/** State CAS failure with the authoritative current value, when present. */
+export declare class StateConflictError<T> extends BaseError {
+    readonly name: "StateConflictError";
+    readonly current?: StateValue<T>;
+    constructor(current?: StateValue<T>);
+    toSerializable(): {
+        context?: Record<string, unknown> | undefined;
+        traceId?: string | undefined;
+        type: string;
+        message: string;
+        id: string;
+    };
+}
+/** Raised when an optional participant resource is not installed. */
+export declare class ResourceUnavailableError extends BaseError {
+    readonly kind: string;
+    readonly resourceName: string;
+    readonly name: "ResourceUnavailableError";
+    /** Construct an unavailable-resource failure. */
+    constructor(kind: string, resourceName: string);
+    toSerializable(): {
+        context?: Record<string, unknown> | undefined;
+        traceId?: string | undefined;
+        type: string;
+        message: string;
+        id: string;
+    };
+}
+/** Typed single-value State handle. */
+export type ValueStateStoreClient<TValue> = StateHandle<TValue>;
+export type StateFacade<TState extends RuntimeStateStores> = {
+    [K in keyof TState]: ValueStateStoreClient<TState[K]["value"]>;
+};
+export type OperationHandlerContext<TInput, TProgress, TOutput, TTransfer, TError extends BaseError, TUpdate = unknown> = {
+    input: TInput;
+    op: OperationRuntimeHandle<TProgress, TOutput, TError, TUpdate>;
+    caller: SessionCaller;
+    /** Aborted when cancellation is committed or this executor loses ownership. */
+    signal: AbortSignal;
+    /** Whether this handler invocation reclaimed an expired executor lease. */
+    resuming: boolean;
+    /** Last durably persisted progress available to a resumed handler. */
+    progress?: TProgress;
+} & (TTransfer extends undefined ? {} : {
+    transfer: TTransfer;
+});
+export type OperationRegistration<TInput, TProgress, TOutput, TTransfer, TError extends BaseError, TUpdate = unknown> = {
+    /**
+     * Loads an existing operation by id and returns a service-side control handle.
+     * The operation must belong to this service and registration name.
+     */
+    control(operationId: string): AsyncResult<OperationRuntimeHandle<TProgress, TOutput, TError, TUpdate>, BaseError>;
+    handle(handler: (context: OperationHandlerContext<TInput, TProgress, TOutput, TTransfer, TError, TUpdate>) => unknown | Promise<unknown>): Promise<void>;
+};
+export type OperationTransferContextOf<TA extends RuntimeApi, O extends OperationsOf<TA>> = TA["operations"][O] extends {
+    transfer: infer TTransfer;
+} ? TTransfer extends undefined ? undefined : OperationTransferHandle : undefined;
+export type OperationSurface<TA extends RuntimeApi, TMode extends TrellisMode, O extends OperationsOf<TA>> = TMode extends "service" ? OperationRegistration<OperationInputOf<TA, O>, OperationProgressOf<TA, O>, OperationOutputOf<TA, O>, OperationTransferContextOf<TA, O>, OperationHandlerErrorOf<TA, O>, OperationUpdateOf<TA, O>> : OperationInvoker<TA["operations"][O] & RuntimeOperationDesc>;
+export declare function isResultLike(value: unknown): value is Result<unknown, BaseError>;
+type SerializableRuntimeError = {
+    id?: string;
+    type: string;
+    message: string;
+    context?: Record<string, unknown>;
+    traceId?: string;
+} & Record<string, unknown>;
+export type HandlerErrorAnnotationContext = {
+    method?: string;
+    event?: string;
+    feed?: string;
+    operation?: string;
+    jobType?: string;
+    requestId?: string;
+    service?: string;
+    contractId?: string;
+    contractDigest?: string;
+    traceId?: string;
+};
+export declare function annotateHandlerBoundaryError(cause: unknown, context: HandlerErrorAnnotationContext): BaseError;
+export type RuntimeOperationDesc = {
+    subject: string;
+    input: unknown;
+    revision: number;
+    progress?: unknown;
+    update?: unknown;
+    output?: unknown;
+    signals?: Record<string, {
+        input: unknown;
+    }>;
+    cancelCapabilities?: readonly string[];
+    controlCapabilities?: readonly string[];
+    transfer?: {
+        store: string;
+        key: `/${string}`;
+        contentType?: `/${string}`;
+        metadata?: `/${string}`;
+        expiresInMs?: number;
+        maxBytes?: number;
+    };
+    cancel?: boolean;
+};
+export type RuntimeOperationSignal = {
+    operationId: string;
+    sequence: number;
+    requestId: string;
+    signal: string;
+    input?: JsonValue;
+    acceptedAt: string;
+    acknowledged: boolean;
+};
+export type RuntimeOperationSignalWaiter = (result: Result<RuntimeOperationSignal, BaseError>) => void;
+export type RuntimeOperationTransferProgress = {
+    chunkIndex: number;
+    chunkBytes: number;
+    transferredBytes: number;
+};
+export type RuntimeOperationState = "pending" | "running" | "completed" | "failed" | "cancelled";
+export type RuntimeOperationSnapshot = {
+    id: string;
+    service: string;
+    operation: string;
+    revision: number;
+    state: RuntimeOperationState;
+    createdAt: string;
+    updatedAt: string;
+    completedAt?: string;
+    progress?: unknown;
+    transfer?: RuntimeOperationTransferProgress;
+    output?: unknown;
+    error?: SerializableRuntimeError;
+};
+export type RuntimeOperationRecord = {
+    id: string;
+    service: string;
+    operation: string;
+    callerSessionKey: string;
+    invocationDigest: string;
+    caller: VerifiedCaller;
+    creatorPrincipalId: string;
+    creatorParticipantId: string;
+    apiId: string;
+    input: unknown;
+    revision: number;
+    ownerInstanceId: string;
+    ownerConnectionId: string;
+    ownerEpoch: number;
+    leaseExpiresAt: string;
+    cancelRequestedAt?: string;
+    transferGrant?: SendTransferGrant;
+    snapshot: RuntimeOperationSnapshot;
+    sequence: number;
+    signalSequence: number;
+    signals: RuntimeOperationSignal[];
+    terminal: boolean;
+    watchers: Map<string, {
+        includeUpdates: boolean;
+    }>;
+    frameQueue: Promise<void>;
+    signalWaiters: Set<RuntimeOperationSignalWaiter>;
+    cancellation: AbortController;
+    reclaimed?: boolean;
+};
+export type DurableOperationRecord = {
+    invocationId: string;
+    callerSessionKey: string;
+    invocationDigest: string;
+    caller: VerifiedCaller;
+    creatorPrincipalId: string;
+    creatorParticipantId: string;
+    apiId: string;
+    operation: string;
+    input: unknown;
+    revision: number;
+    ownerInstanceId: string;
+    ownerConnectionId: string;
+    ownerEpoch: number;
+    leaseExpiresAt: string;
+    cancelRequestedAt?: string;
+    transferGrant?: SendTransferGrant;
+    sequence: number;
+    signalSequence: number;
+    signals: RuntimeOperationSignal[];
+    snapshot: RuntimeOperationSnapshot;
+};
+export declare const DurableOperationRecordSchema: Type.TObject<{
+    invocationId: Type.TString;
+    callerSessionKey: Type.TString;
+    apiId: Type.TString;
+    operation: Type.TString;
+    input: Type.TAny;
+    ownerInstanceId: Type.TString;
+    ownerConnectionId: Type.TString;
+    ownerEpoch: Type.TNumber;
+    leaseExpiresAt: Type.TString;
+    cancelRequestedAt: Type.TOptional<Type.TString>;
+    transferGrant: Type.TOptional<Type.TAny>;
+    sequence: Type.TNumber;
+    signalSequence: Type.TNumber;
+    signals: Type.TArray<Type.TObject<{
+        operationId: Type.TString;
+        sequence: Type.TNumber;
+        requestId: Type.TString;
+        signal: Type.TString;
+        input: Type.TOptional<Type.TAny>;
+        acceptedAt: Type.TString;
+        acknowledged: Type.TBoolean;
+    }>>;
+    snapshot: Type.TObject<{
+        id: Type.TString;
+        service: Type.TString;
+        operation: Type.TString;
+        revision: Type.TNumber;
+        state: Type.TUnion<[Type.TLiteral<"pending">, Type.TLiteral<"running">, Type.TLiteral<"completed">, Type.TLiteral<"failed">, Type.TLiteral<"cancelled">]>;
+        createdAt: Type.TString;
+        updatedAt: Type.TString;
+        completedAt: Type.TOptional<Type.TString>;
+        progress: Type.TOptional<Type.TAny>;
+        transfer: Type.TOptional<Type.TObject<{
+            chunkIndex: Type.TNumber;
+            chunkBytes: Type.TNumber;
+            transferredBytes: Type.TNumber;
+        }>>;
+        output: Type.TOptional<Type.TAny>;
+        error: Type.TOptional<Type.TObject<{
+            id: Type.TOptional<Type.TString>;
+            type: Type.TString;
+            message: Type.TString;
+            context: Type.TOptional<Type.TRecord<"^.*$", Type.TUnknown>>;
+            traceId: Type.TOptional<Type.TString>;
+        }>>;
+    }>;
+}>;
+export type RuntimeOperationAcceptedEnvelope = {
+    kind: "accepted";
+    ref: OperationRefData;
+    snapshot: RuntimeOperationSnapshot;
+    transfer?: SendTransferGrant;
+};
+export type RuntimeOperationControlRequest = {
+    action: "get" | "cancel";
+    operationId: string;
+} | {
+    action: "watch";
+    operationId: string;
+    includeUpdates?: boolean;
+} | {
+    action: "signal";
+    operationId: string;
+    signal: string;
+    input?: JsonValue;
+};
+export type RuntimeOperationController = {
+    get(operationId: string): AsyncResult<RuntimeOperationSnapshot, BaseError>;
+    started(operationId: string): AsyncResult<RuntimeOperationSnapshot, BaseError>;
+    progress(operationId: string, progress: unknown): AsyncResult<RuntimeOperationSnapshot, BaseError>;
+    complete(operationId: string, output: unknown): AsyncResult<RuntimeOperationSnapshot, BaseError>;
+    fail(operationId: string, error: BaseError): AsyncResult<RuntimeOperationSnapshot, BaseError>;
+    cancel(operationId: string): AsyncResult<RuntimeOperationSnapshot, BaseError>;
+    signals(operationId: string): AsyncIterable<RuntimeOperationSignal>;
+    nextSignal(operationId: string, name?: string): AsyncResult<RuntimeOperationSignal, BaseError>;
+};
+export declare function buildRuntimeOperationSnapshot(runtime: Pick<RuntimeOperationRecord, "id" | "service" | "operation" | "snapshot">, state: RuntimeOperationState, patch?: Partial<RuntimeOperationSnapshot>): RuntimeOperationSnapshot;
+export declare function isTerminalRuntimeOperationSnapshot(value: unknown): value is RuntimeOperationSnapshot;
+type NoResponderRetryOpts = {
+    maxAttempts?: number;
+    baseDelayMs?: number;
+};
+export type TrellisOpts<TA extends RuntimeApi> = {
+    log?: LoggerLike;
+    timeout?: number;
+    stream?: string;
+    noResponderRetry?: NoResponderRetryOpts;
+    api?: TA;
+    state?: RuntimeStateStores;
+    stateMigrations?: Readonly<Record<string, ResourceMigrations<unknown> | undefined>>;
+    resourceGeneration?: () => number;
+    resourceAvailability?: (name: string) => boolean;
+    connection?: TrellisConnection;
+    onSessionNotFound?: () => MaybePromise<void>;
+    contractId?: string;
+    contractDigest?: string;
+};
+export type RequestOpts = {
+    timeout?: number;
+    signal?: AbortSignal;
+};
+export type EventOpts = {
+    mode?: "durable" | "ephemeral";
+    /**
+     * Contract event consumer group to use for durable service listeners when an
+     * event is declared in more than one group.
+     */
+    group?: string;
+    signal?: AbortSignal;
+};
+/** Context provided to event listener callbacks. */
+export type EventListenerContext = {
+    /** Stable event id from the Trellis event header. */
+    id: string;
+    /** Event creation time from the Trellis event header. */
+    time: Date;
+    /** NATS subject that delivered the event. */
+    subject: string;
+    /** Runtime listener mode that delivered the event. */
+    mode: "durable" | "ephemeral";
+    /** Durable event consumer group, when delivered through a group. */
+    group?: string;
+    /** JetStream sequence number, when available. */
+    sequence?: number;
+};
+export type FeedSubscribeOpts = {
+    signal?: AbortSignal;
+};
+export type FeedSubscription<TEvent> = AsyncIterable<TEvent>;
+export type FeedInputBuilder<TInput, TEvent> = {
+    input(input: TInput): {
+        subscribe(opts?: FeedSubscribeOpts): AsyncResult<FeedSubscription<TEvent>, BaseError>;
+    };
+};
+export type FeedHandlerContext<TInput, TEvent> = {
+    input: TInput;
+    caller: SessionCaller;
+    signal: AbortSignal;
+    emit(event: TEvent): AsyncResult<void, SchemaValidationError | ValidationError | UnexpectedError>;
+};
+export type FeedRegistration<TInput, TEvent> = {
+    handle(handler: (context: FeedHandlerContext<TInput, TEvent>) => unknown | Promise<unknown>): Promise<void>;
+};
+type PascalSurfaceName<T extends string> = T extends `${infer Head}.${infer Tail}` ? `${Capitalize<Head>}${PascalSurfaceName<Tail>}` : Capitalize<T>;
+type LowerCamelSurfaceName<T extends string> = Uncapitalize<PascalSurfaceName<T>>;
+type SurfaceGroupName<T extends string> = T extends `${infer Head}.${string}` ? LowerCamelSurfaceName<Head> : LowerCamelSurfaceName<T>;
+type SurfaceLeafName<T extends string> = T extends `${string}.${infer Tail}` ? LowerCamelSurfaceName<Tail> : LowerCamelSurfaceName<T>;
+type SurfaceKeysForGroup<TKeys extends string, TGroup extends string> = TKeys extends string ? SurfaceGroupName<TKeys> extends TGroup ? TKeys : never : never;
+export type ActiveRpcFacade<TA extends RuntimeApi = RuntimeApi> = {
+    readonly [TGroup in SurfaceGroupName<MethodsOf<TA>>]: {
+        readonly [M in SurfaceKeysForGroup<MethodsOf<TA>, TGroup> as SurfaceLeafName<M>]: (input: RpcInputOf<TA, M>, opts?: RequestOpts) => AsyncResult<RpcOutputOf<TA, M>, BaseError>;
+    };
+};
+export type ActiveEventFacade<TA extends RuntimeApi = RuntimeApi> = {
+    readonly [TGroup in SurfaceGroupName<EventsOf<TA>>]: {
+        readonly [E in SurfaceKeysForGroup<EventsOf<TA>, TGroup> as SurfaceLeafName<E>]: {
+            prepare(event: EventPayloadOf<TA, E>): Result<PreparedTrellisEvent<EventPayloadOf<TA, E>>, ValidationError | UnexpectedError>;
+            publish(event: EventPayloadOf<TA, E>): AsyncResult<void, ValidationError | UnexpectedError>;
+            listen(handler: EventCallback<EventOf<TA, E>>, subjectData?: Record<string, unknown>, opts?: EventOpts): AsyncResult<void, ValidationError | UnexpectedError>;
+        };
+    };
+};
+export type ActiveEventPublishFacade<TA extends RuntimeApi = RuntimeApi> = {
+    readonly [TGroup in SurfaceGroupName<EventsOf<TA>>]: {
+        readonly [E in SurfaceKeysForGroup<EventsOf<TA>, TGroup> as SurfaceLeafName<E>]: {
+            prepare(event: EventPayloadOf<TA, E>): Result<PreparedTrellisEvent<EventPayloadOf<TA, E>>, ValidationError | UnexpectedError>;
+            publish(event: EventPayloadOf<TA, E>): AsyncResult<void, ValidationError | UnexpectedError>;
+        };
+    };
+};
+export type ActiveFeedFacade<TA extends RuntimeApi = RuntimeApi> = {
+    readonly [TGroup in SurfaceGroupName<FeedsOf<TA>>]: {
+        readonly [F in SurfaceKeysForGroup<FeedsOf<TA>, TGroup> as SurfaceLeafName<F>]: (input: FeedInputOf<TA, F>, opts?: FeedSubscribeOpts) => AsyncResult<FeedSubscription<FeedEventOf<TA, F>>, BaseError>;
+    };
+};
+export type ActiveOperationFacade<TA extends RuntimeApi = RuntimeApi> = {
+    readonly [TGroup in SurfaceGroupName<OperationsOf<TA>>]: {
+        readonly [O in SurfaceKeysForGroup<OperationsOf<TA>, TGroup> as SurfaceLeafName<O>]: OperationInvoker<TA["operations"][O] & RuntimeOperationDesc>;
+    };
+};
+export type ActiveRpcHandleFacade<TA extends RuntimeApi = RuntimeApi, TRequests = RpcRequestShapes<TA>> = {
+    readonly [TGroup in SurfaceGroupName<MethodsOf<TA>>]: {
+        readonly [M in SurfaceKeysForGroup<MethodsOf<TA>, TGroup> as SurfaceLeafName<M>]: (handler: HandlerFn<TA, M, TA, HandlerTrellis<TA, TRequests>>) => Promise<void>;
+    };
+};
+export type FeedSurface<TA extends RuntimeApi, TMode extends TrellisMode, F extends FeedsOf<TA>> = TMode extends "service" ? FeedRegistration<FeedInputOf<TA, F>, FeedEventOf<TA, F>> : FeedInputBuilder<FeedInputOf<TA, F>, FeedEventOf<TA, F>>;
+type MaybePromise<T> = T | Promise<T>;
+type EventCallback<TMessage> = {
+    bivarianceHack(message: TMessage, context: EventListenerContext): MaybeAsync<void, BaseError>;
+}["bivarianceHack"];
+export type RpcHandlerContext = {
+    caller: SessionCaller;
+    sessionKey: string;
+    inboxPrefix: string;
+    /** Exact permission verified for this request. */
+    permission: DescriptorPermissionAtom;
+    /** Capabilities required by this request surface. */
+    requiredCapabilities: readonly string[];
+    requestId?: string;
+    traceId?: string;
+    /** Schedules work after the successful RPC response has reached NATS. */
+    afterReply(task: () => MaybePromise<void>): void;
+};
+export type HandlerTrellis<TA extends RuntimeApi, TRequests = RpcRequestShapes<TA>> = {
+    readonly rpc: ActiveRpcFacade<TA>;
+    readonly event: ActiveEventPublishFacade<TA>;
+    readonly feed: ActiveFeedFacade<TA>;
+    readonly operation: ActiveOperationFacade<TA>;
+    request<const M extends RequestMethodOf<TRequests>>(method: M, input: RequestInputOf<TRequests, M>, opts?: RequestOpts): AsyncResult<RequestOutputOf<TRequests, M>, BaseError>;
+    publish(event: string, data: Record<string, unknown>): AsyncResult<void, ValidationError | UnexpectedError>;
+    prepare(event: string, data: Record<string, unknown>): Result<PreparedTrellisEvent, ValidationError | UnexpectedError>;
+    publishPrepared(event: PreparedTrellisEvent): AsyncResult<void, UnexpectedError>;
+    /** Stops durable event listener loops owned by this handler runtime. */
+    stopEventListeners(): void;
+};
+export type HandlerKvFacade<TKv extends ParticipantKvMetadata> = {
+    [K in keyof TKv]: TKv[K]["required"] extends false ? TypedKV<TKv[K]["value"]> | undefined : TypedKV<TKv[K]["value"]>;
+};
+export type HandlerStoreHandle = {
+    open(): AsyncResult<TypedStore, StoreError>;
+    waitFor(key: string, options?: StoreWaitOptions): AsyncResult<TypedStoreEntry, StoreError>;
+};
+export type HandlerJobQueue<TPayload, TResult, TTrellis, TUpdate = never> = {
+    create(payload: TPayload): AsyncResult<JobRef<TPayload, TResult, TUpdate>, BaseError>;
+    updates(jobId: string, options?: JobUpdatesOptions): AsyncResult<JobUpdateSubscription<TUpdate>, BaseError>;
+    handle(handler: (args: {
+        job: ActiveJob<TPayload, TResult, TUpdate>;
+        client: TTrellis;
+    }) => Promise<Result<TResult, BaseError>>): void;
+};
+export type HandlerJobsFacade<TJobs extends Record<string, JobTypeMetadata>, TTrellis> = {
+    [K in keyof TJobs]: HandlerJobQueue<TJobs[K]["payload"], TJobs[K]["result"], TTrellis, TJobs[K]["update"]>;
+};
+export type HandlerTrellisForContract<TContract> = HandlerTrellis<TrellisApiFor<TContract>> & {
+    kv: HandlerKvFacade<ContractKvFor<TContract>>;
+    store: Record<string, HandlerStoreHandle>;
+    jobs: HandlerJobsFacade<ContractJobsFor<TContract>, HandlerTrellisForContract<TContract>>;
+};
+export type HandlerFn<TMountApi extends RuntimeApi, M extends MethodsOf<TMountApi>, TOutboundApi extends RuntimeApi = TMountApi, TTrellis = HandlerTrellis<TOutboundApi>> = (args: {
+    input: MethodInputOf<TMountApi, M>;
+    context: RpcHandlerContext;
+    client: TTrellis;
+}) => MaybePromise<Result<MethodOutputOf<TMountApi, M>, HandlerErrorOf<TMountApi, M>>>;
+/** Transport calls consumed by a typed State handle. */
+export type StateResourceCalls = Readonly<{
+    get(input: {
+        resourceName: string;
+    }): PromiseLike<Result<StateGetResponse, BaseError>>;
+    set(input: {
+        resourceName: string;
+        representationVersion: bigint;
+        value: Uint8Array;
+        mode: "create" | "set" | "replace";
+        revision?: string;
+    }): PromiseLike<Result<StateSetResponse, BaseError>>;
+    delete(input: {
+        resourceName: string;
+        revision?: string;
+    }): PromiseLike<Result<StateDeleteResponse, BaseError>>;
+}>;
+/** Typed handle for one generated single-value State resource. */
+export declare class StateHandle<T> {
+    #private;
+    /** Construct a handle from generated metadata and settled State transport calls. */
+    constructor(args: {
+        resourceName: string;
+        definition: KvRepresentation<T>;
+        migrations?: ResourceMigrations<T>;
+        isCurrent?: () => boolean;
+        isAvailable?: () => boolean;
+        calls: StateResourceCalls;
+    });
+    /** Read the current value, migrating only in memory when required. */
+    get(): AsyncResult<StateValue<T> | undefined, BaseError>;
+    /** Create the value only when no live value exists. */
+    create(value: T): AsyncResult<StateValue<T>, BaseError>;
+    /** Unconditionally replace the current value. */
+    set(value: T): AsyncResult<StateValue<T>, BaseError>;
+    /** Replace the value only while `revision` remains current. */
+    replace(revision: string, value: T): AsyncResult<StateValue<T>, BaseError>;
+    /** Delete unconditionally or only while `revision` remains current. */
+    delete(revision?: string): AsyncResult<boolean, BaseError>;
+}
+export type RpcRequestErrorOf<TA extends RuntimeApi, M extends RpcMethodNameOf<TA>> = RequestErrorOf<TA, M>;
+export type RpcHandlerErrorOf<TA extends RuntimeApi, M extends RpcMethodNameOf<TA>> = HandlerErrorOf<TA, M>;
+export type EventName<TContract> = EventsOf<OwnedApiFor<TContract>>;
+export type EventType<TContract, E extends EventName<TContract>> = EventOf<OwnedApiFor<TContract>, E>;
+export type EventPayload<TContract, E extends EventName<TContract>> = EventPayloadOf<OwnedApiFor<TContract>, E>;
+export declare class Trellis<TA extends RuntimeApi = RuntimeApi, TMode extends TrellisMode = "client", TState extends RuntimeStateStores = {}, TRequests = RpcRequestShapes<TA>> {
+    #private;
+    readonly name: string;
+    readonly timeout: number;
+    readonly stream: string;
+    readonly state: StateFacade<TState>;
+    readonly rpc: ActiveRpcFacade<TA>;
+    readonly event: ActiveEventFacade<TA>;
+    readonly feed: ActiveFeedFacade<TA>;
+    readonly operation: ActiveOperationFacade<TA>;
+    readonly handle: {
+        readonly rpc: ActiveRpcHandleFacade<TA, TRequests>;
+    };
+    /** Framework-neutral lifecycle handle for this Trellis runtime connection. */
+    readonly connection: TrellisConnection;
+    readonly contractId?: string;
+    readonly contractDigest?: string;
+    readonly api: TA;
+    constructor(name: string, // Must be unique for a service
+    nats: NatsConnection, auth: TrellisAuth, opts?: TrellisOpts<TA>, inboxPrefix?: string);
+    protected get nats(): NatsConnection;
+    protected get js(): JetStreamClient;
+    protected get auth(): TrellisAuth;
+    operationStoreHandle(): Promise<TypedKV<DurableOperationRecord>>;
+    protected setOperationDeploymentId(id: string): void;
+    protected setFeedOwnerId(id: string): void;
+    loadOperationRecord(operationId: string): Promise<DurableOperationRecord | null>;
+    protected listNonterminalOperationRecords(): Promise<DurableOperationRecord[]>;
+    saveOperationRecord(runtime: RuntimeOperationRecord): Promise<void>;
+    /**
+     * Makes an authenticated request to a Trellis RPC method.
+     *
+     * @template M The specific RPC method being called.
+     * @param method The name of the RPC method to call.
+     * @param input The input data for the method, conforming to its schema.
+     * @param opts Optional request-specific options.
+     * @returns An `AsyncResult` containing either the method's output or an error.
+     * @returns A `Result` object after awaiting:
+     *              ok: A validated response for method M
+     *              err: declared RPC errors | RemoteError | ValidationError | UnexpectedError
+     */
+    request<const M extends RequestMethodOf<TRequests>>(method: M, input: RequestInputOf<TRequests, M>, opts?: RequestOpts): AsyncResult<RequestOutputOf<TRequests, M>, BaseError>;
+    feedHandle<F extends FeedsOf<TA>>(feed: F): FeedInputBuilder<FeedInputOf<TA, F>, FeedEventOf<TA, F>> & FeedRegistration<FeedInputOf<TA, F>, FeedEventOf<TA, F>>;
+    operationHandle<O extends OperationsOf<TA>>(operation: O, unavailable?: () => TransportError | undefined): OperationSurface<TA, TMode, O>;
+    /**
+     * Creates a helper for a short-lived Trellis transfer grant.
+     */
+    transfer(grant: SendTransferGrant): SendTransferHandle;
+    transfer(grant: ReceiveTransferGrant): ReceiveTransferHandle;
+    mount(method: string, fn: (args: {
+        input: unknown;
+        context: RpcHandlerContext;
+        client: HandlerTrellis<TA, TRequests>;
+    }) => MaybePromise<Result<unknown, BaseError>>): Promise<void>;
+    respondWithError(msg: Msg, error: Error | BaseError): void;
+    /**
+     * Builds a stable event subject, encoded payload, and publish headers.
+     *
+     * The prepared event intentionally carries no contract id or digest so callers
+     * can persist it in a service-owned outbox without coupling storage to the
+     * publisher's current deployment metadata.
+     */
+    prepare(event: string, data: Record<string, unknown>): Result<PreparedTrellisEvent, ValidationError | UnexpectedError>;
+    /**
+     * Publishes a previously prepared event without regenerating its id, time,
+     * subject, payload, or headers.
+     */
+    publishPrepared(event: PreparedTrellisEvent): AsyncResult<void, UnexpectedError>;
+    publish(event: string, data: Record<string, unknown>): AsyncResult<void, ValidationError | UnexpectedError>;
+    listenEvent<E extends EventsOf<TA>>(event: E, subjectData: Record<string, unknown>, fn: EventCallback<EventOf<TA, E>>, opts?: EventOpts): AsyncResult<void, ValidationError | UnexpectedError>;
+    wait(): AsyncResult<void, BaseError>;
+    /** Stops durable event listener loops without closing the underlying transport. */
+    stopEventListeners(): void;
+    template(subject: string, data: unknown, allowWildcards?: boolean): Result<string, ValidationError>;
+    /** Creates a context-bound request proof for an exact subject, payload, and reply. */
+    protected createRequestProof(subject: string, payload: string, reply: string): Promise<{
+        proof: string;
+        iat: number;
+        requestId: string;
+        contextDigest: string;
+    }>;
+}