@oatscenter/trellis 0.100.0-rc.1

package/service/runtime/service.d.ts

@@ -0,0 +1,372 @@
+import type { StoreError } from "../../errors/index.ts";
+import { TypedKV } from "../../kv.ts";
+import { type StoreWaitOptions, TypedStore, type TypedStoreEntry } from "../../store.ts";
+import { type TrellisAuth as SessionAuth } from "../../auth.ts";
+import type { InferSchemaType } from "../../participant.ts";
+import type { PermissionAtom, RuntimeApi } from "../../participant_runtime/api.ts";
+import type { ParticipantJobsMetadata, ParticipantKvMetadata } from "../../participant_runtime/metadata.ts";
+import { type GeneratedParticipant } from "../../participant_runtime/participant.ts";
+import { type ConnectedActionName } from "../../participant_runtime/surface_names.ts";
+import { AsyncResult, type BaseError, type MaybeAsync, Result } from "@oatscenter/result";
+import { type ServiceHealth, type ServiceHealthCheckFn, type ServiceHealthInfoFn } from "./health.ts";
+import type { EventDesc } from "../../participant.ts";
+import type { ActiveEventFacade, EventListenerContext, FeedEventOf, FeedHandlerContext, FeedInputOf, FeedRegistration as RootFeedRegistration, FeedsOf, HandlerTrellis, OperationHandlerContext, OperationHandlerErrorOf, OperationOutputOf, OperationProgressOf, OperationTransferContextOf, OperationUpdateOf, PreparedTrellisEvent, RpcHandlerContext, RpcHandlerErrorOf } from "../../session.ts";
+import { type LoggerLike } from "../../globals.ts";
+import { PROVIDER_CALLER, type ProviderCaller, type ProviderHandlerClient, type ProviderRuntime } from "../../provider.ts";
+import { type TransferError, TransportError, UnexpectedError, ValidationError } from "../../errors/index.ts";
+import type { ReceiveTransferGrant } from "../../transfer.ts";
+import { ActiveJob as PublicActiveJob, type JobHandlerOptions, JobRef, type JobSubmitOutcome, type JobUpdatesOptions, type JobUpdateSubscription } from "../../jobs.ts";
+import type { JobKeyConcurrencyBinding, JobQueuePolicyBinding } from "./internal_jobs/key-coordinator.ts";
+import { type TrellisConnection } from "../../connection.ts";
+import { type OutboxDispatcherOptions, type OutboxJobDispatchOutcome, type OutboxMessage, type SqlDialect, type SqlExecutor, type SqlOutboxTables } from "../outbox_inbox.ts";
+type ResourceBindingJobsQueue = {
+    queueType: string;
+    publishPrefix: string;
+    workSubject: string;
+    consumerName: string;
+    payload: {
+        schema: string;
+    };
+    update?: {
+        schema: string;
+    };
+    updatesPrefix?: string;
+    result?: {
+        schema: string;
+    };
+    maxDeliver: number;
+    backoffMs: number[];
+    ackWaitMs: number;
+    defaultDeadlineMs?: number;
+    keyConcurrency?: JobKeyConcurrencyBinding;
+    queue?: JobQueuePolicyBinding;
+};
+type ResourceBindingJobs = {
+    serviceName: string;
+    namespace: string;
+    workStream?: string;
+    queues: Record<string, ResourceBindingJobsQueue>;
+};
+type ResourceBindingEventConsumer = {
+    stream: string;
+    consumerName: string;
+    resourceId: string;
+    filterSubjects: string[];
+    replay: "new" | "all";
+    concurrency: number;
+    ackWaitMs: number;
+    maxDeliver: number;
+    backoffMs: number[];
+    replayBinding: {
+        stream: string;
+        consumerName: string;
+    };
+};
+type RpcMethodName<TA extends RuntimeApi> = keyof TA["rpc"] & string;
+type RpcMethodInput<TA extends RuntimeApi, M extends RpcMethodName<TA>> = InferSchemaType<TA["rpc"][M]["input"]>;
+type RpcMethodOutput<TA extends RuntimeApi, M extends RpcMethodName<TA>> = InferSchemaType<TA["rpc"][M]["output"]>;
+export type TrellisServiceHealthOpts = {
+    publishIntervalMs?: number;
+};
+export type TrellisServiceRuntimeOpts = {
+    log?: LoggerLike | false;
+    timeout?: number;
+    stream?: string;
+    noResponderRetry?: {
+        maxAttempts?: number;
+        baseDelayMs?: number;
+    };
+    version?: string;
+    health?: TrellisServiceHealthOpts;
+};
+export type ResourceBindingKV = {
+    bucket: string;
+    history: number;
+    ttlMs: number;
+    maxValueBytes?: number;
+};
+export type ResourceBindingStore = {
+    name: string;
+    ttlMs: number;
+    maxObjectBytes?: number;
+    maxTotalBytes?: number;
+};
+export type ResourceBindings = {
+    kv: Record<string, ResourceBindingKV>;
+    store: Record<string, ResourceBindingStore>;
+    jobs?: ResourceBindingJobs;
+    eventConsumers?: Record<string, ResourceBindingEventConsumer>;
+};
+export declare abstract class StoreHandle {
+    abstract readonly binding: ResourceBindingStore;
+    abstract open(): AsyncResult<TypedStore, StoreError>;
+    /**
+     * Waits for a staged object to appear in the bound store and returns its entry.
+     */
+    abstract waitFor(key: string, options?: StoreWaitOptions): AsyncResult<TypedStoreEntry, StoreError>;
+}
+export type TrellisServiceConnectOpts<TOwnedApi extends RuntimeApi = RuntimeApi, TTrellisApi extends RuntimeApi | undefined = TOwnedApi> = {
+    trellisUrl: string;
+    participant: GeneratedServiceParticipant<TOwnedApi, TTrellisApi>;
+    name?: string;
+    /** Immutable provisioned service identity. */
+    seed: string;
+    /** Controls automatic telemetry initialization. Enabled by default. */
+    telemetry?: TrellisServiceConnectTelemetryOpts;
+    /** Configures the connected service runtime. */
+    runtime?: TrellisServiceRuntimeOpts;
+};
+/** Controls automatic telemetry initialization for `TrellisService.connect()`. */
+export type TrellisServiceConnectTelemetryOpts = false | {
+    /** Whether automatic telemetry initialization is enabled. Defaults to `true`. */
+    enabled?: boolean;
+};
+type ServiceKvFacade<TKv extends ParticipantKvMetadata> = {
+    [K in keyof TKv]: TKv[K]["required"] extends false ? TypedKV<TKv[K]["value"]> | undefined : TypedKV<TKv[K]["value"]>;
+};
+type ServiceHandlerResources<TKv extends ParticipantKvMetadata, TJobs extends ParticipantJobsMetadata, TTrellisApi extends RuntimeApi> = {
+    kv: ServiceKvFacade<TKv>;
+    store: Record<string, StoreHandle>;
+    jobs: JobsFacadeOf<TJobs, TTrellisApi, TKv>;
+};
+export type Trellis<TTrellisApi extends RuntimeApi, TKv extends ParticipantKvMetadata = ParticipantKvMetadata, TJobs extends ParticipantJobsMetadata = ParticipantJobsMetadata> = HandlerTrellis<TTrellisApi> & ServiceHandlerResources<TKv, TJobs, TTrellisApi>;
+export type GeneratedServiceParticipant<TOwnedApi extends RuntimeApi, TTrellisApi extends RuntimeApi | undefined, TJobs extends ParticipantJobsMetadata = ParticipantJobsMetadata, TKv extends ParticipantKvMetadata = ParticipantKvMetadata> = GeneratedParticipant & {
+    readonly __runtimeTypes?: {
+        ownedApi: TOwnedApi;
+        api: TTrellisApi;
+        jobs: TJobs;
+        kv: TKv;
+    };
+};
+type ParticipantOwnedApi<TContract extends GeneratedServiceParticipant<RuntimeApi, RuntimeApi | undefined, ParticipantJobsMetadata>> = TContract extends {
+    readonly __runtimeTypes?: {
+        ownedApi: infer TOwnedApi;
+    };
+} ? Extract<TOwnedApi, RuntimeApi> : RuntimeApi;
+type ParticipantTrellisApi<TContract extends GeneratedServiceParticipant<RuntimeApi, RuntimeApi | undefined, ParticipantJobsMetadata>> = TContract extends {
+    readonly __runtimeTypes?: {
+        api: infer TApi;
+    };
+} ? Extract<TApi, RuntimeApi> : ParticipantOwnedApi<TContract>;
+type ParticipantJobsOf<TContract extends GeneratedServiceParticipant<RuntimeApi, RuntimeApi | undefined, ParticipantJobsMetadata, ParticipantKvMetadata>> = TContract extends {
+    readonly __runtimeTypes?: {
+        jobs: infer TJobs;
+    };
+} ? Extract<TJobs, ParticipantJobsMetadata> : Record<string, never>;
+type ParticipantKvOf<TContract extends GeneratedServiceParticipant<RuntimeApi, RuntimeApi | undefined, ParticipantJobsMetadata, ParticipantKvMetadata>> = TContract extends {
+    readonly __runtimeTypes?: {
+        kv: infer TKv;
+    };
+} ? Extract<TKv, ParticipantKvMetadata> : Record<string, never>;
+type ServiceHandlerClient<TContract extends GeneratedServiceParticipant<RuntimeApi, RuntimeApi | undefined, ParticipantJobsMetadata, ParticipantKvMetadata>> = ProviderHandlerClient<TContract, TrellisServiceSession<ParticipantOwnedApi<TContract>, ParticipantTrellisApi<TContract>, ParticipantJobsOf<TContract>, ParticipantKvOf<TContract>>>;
+type ParticipantEventName<TContract extends GeneratedServiceParticipant<RuntimeApi, RuntimeApi | undefined, ParticipantJobsMetadata>> = ServiceEventName<ParticipantTrellisApi<TContract>>;
+type ContractOperationName<TContract extends GeneratedServiceParticipant<RuntimeApi, RuntimeApi | undefined, ParticipantJobsMetadata>> = keyof ParticipantOwnedApi<TContract>["operations"] & string;
+type ContractFeedName<TContract extends GeneratedServiceParticipant<RuntimeApi, RuntimeApi | undefined, ParticipantJobsMetadata>> = FeedsOf<ParticipantOwnedApi<TContract>>;
+type ContractJobName<TContract extends GeneratedServiceParticipant<RuntimeApi, RuntimeApi | undefined, ParticipantJobsMetadata, ParticipantKvMetadata>> = keyof ParticipantJobsOf<TContract> & string;
+/** Typed RPC handler function for an extracted Trellis service handler. */
+export type RpcHandler<TContract extends GeneratedServiceParticipant<RuntimeApi, RuntimeApi | undefined, ParticipantJobsMetadata, ParticipantKvMetadata>, M extends RpcMethodName<ParticipantOwnedApi<TContract>>> = ({ input, context, client, }: {
+    input: RpcMethodInput<ParticipantOwnedApi<TContract>, M>;
+    context: RpcHandlerContext;
+    client: ServiceHandlerClient<TContract>;
+}) => Promise<Result<RpcMethodOutput<ParticipantOwnedApi<TContract>, M>, RpcHandlerErrorOf<ParticipantOwnedApi<TContract>, M>>> | Result<RpcMethodOutput<ParticipantOwnedApi<TContract>, M>, RpcHandlerErrorOf<ParticipantOwnedApi<TContract>, M>>;
+/** Typed event listener function for an extracted Trellis service listener. */
+export type ServiceEventHandler<TContract extends GeneratedServiceParticipant<RuntimeApi, RuntimeApi | undefined, ParticipantJobsMetadata, ParticipantKvMetadata>, E extends ParticipantEventName<TContract>> = (args: {
+    event: ServiceEventOf<ParticipantTrellisApi<TContract>, E>;
+    context: EventListenerContext;
+    client: ServiceHandlerClient<TContract>;
+}) => MaybeAsync<void, BaseError>;
+/** Typed operation handler function for an extracted Trellis service handler. */
+export type OperationHandler<TContract extends GeneratedServiceParticipant<RuntimeApi, RuntimeApi | undefined, ParticipantJobsMetadata, ParticipantKvMetadata>, O extends ContractOperationName<TContract>> = (args: OperationHandlerContext<InferSchemaType<ParticipantOwnedApi<TContract>["operations"][O]["input"]>, OperationProgressOf<ParticipantOwnedApi<TContract>, O>, OperationOutputOf<ParticipantOwnedApi<TContract>, O>, OperationTransferContextOf<ParticipantOwnedApi<TContract>, O>, OperationHandlerErrorOf<ParticipantOwnedApi<TContract>, O>, OperationUpdateOf<ParticipantOwnedApi<TContract>, O>> & {
+    client: ServiceHandlerClient<TContract>;
+}) => unknown | Promise<unknown>;
+/** Typed feed handler function for an extracted Trellis service handler. */
+export type FeedHandler<TContract extends GeneratedServiceParticipant<RuntimeApi, RuntimeApi | undefined, ParticipantJobsMetadata, ParticipantKvMetadata>, F extends ContractFeedName<TContract>> = (context: FeedHandlerContext<FeedInputOf<ParticipantOwnedApi<TContract>, F>, FeedEventOf<ParticipantOwnedApi<TContract>, F>>) => unknown | Promise<unknown>;
+/** Typed job handler function for an extracted Trellis service job. */
+export type JobHandler<TContract extends GeneratedServiceParticipant<RuntimeApi, RuntimeApi | undefined, ParticipantJobsMetadata, ParticipantKvMetadata>, K extends ContractJobName<TContract>> = (args: {
+    job: PublicActiveJob<ParticipantJobsOf<TContract>[K]["payload"], ParticipantJobsOf<TContract>[K]["result"], ParticipantJobsOf<TContract>[K]["update"]>;
+    client: ServiceHandlerClient<TContract>;
+}) => Promise<Result<ParticipantJobsOf<TContract>[K]["result"], BaseError>>;
+/** Typed health info function for an extracted service health handler. */
+export type HealthInfoHandler = ServiceHealthInfoFn;
+/** Typed health check function for an extracted service health handler. */
+export type HealthCheckHandler = ServiceHealthCheckFn;
+export type JobQueue<TPayload, TResult, TTrellisApi extends RuntimeApi, TKv extends ParticipantKvMetadata = ParticipantKvMetadata, TJobs extends ParticipantJobsMetadata = ParticipantJobsMetadata, TUpdate = never> = {
+    create(payload: TPayload): AsyncResult<JobRef<TPayload, TResult, TUpdate>, BaseError>;
+    submit(payload: TPayload): AsyncResult<JobSubmitOutcome<TPayload, TResult, TUpdate>, BaseError>;
+    updates(jobId: string, options?: JobUpdatesOptions): AsyncResult<JobUpdateSubscription<TUpdate>, BaseError>;
+    handle(handler: (args: {
+        job: PublicActiveJob<TPayload, TResult, TUpdate>;
+        client: Trellis<TTrellisApi, TKv, TJobs>;
+    }) => Promise<Result<TResult, BaseError>>, options?: JobHandlerOptions): void;
+};
+export type JobsFacadeOf<TJobs extends ParticipantJobsMetadata, TTrellisApi extends RuntimeApi, TKv extends ParticipantKvMetadata = ParticipantKvMetadata> = {
+    [K in keyof TJobs]: JobQueue<TJobs[K]["payload"], TJobs[K]["result"], TTrellisApi, TKv, TJobs, TJobs[K]["update"]>;
+};
+type ServiceEventName<TA extends RuntimeApi> = keyof TA["events"] & string;
+type ServiceEventOf<TA extends RuntimeApi, E extends ServiceEventName<TA>> = TA["events"][E] extends EventDesc<infer TEvent> ? InferSchemaType<TEvent> : never;
+type ServiceEventPayloadOf<TA extends RuntimeApi, E extends ServiceEventName<TA>> = ServiceEventOf<TA, E> & Record<string, unknown>;
+/** Runs SQL outbox work inside a caller-owned service database transaction. */
+export type SqlOutboxTransactionRunner<TTx> = <TResult>(work: (context: {
+    tx: TTx;
+    executor: SqlExecutor;
+}) => Promise<TResult> | TResult) => Promise<TResult>;
+/** Options shared by all Trellis SQL outbox service bindings. */
+export type TrellisServiceSqlOutboxCommonOptions = {
+    /** SQL dialect used by the Trellis helper tables. */
+    readonly dialect: SqlDialect;
+    /** Optional Trellis helper-table names; omitted names use Trellis defaults. */
+    readonly tables?: Partial<SqlOutboxTables>;
+    /** Optional process-local dispatcher tuning. */
+    readonly dispatcher?: OutboxDispatcherOptions;
+};
+/** Options for binding a Trellis service to generic caller-owned SQL storage. */
+export type TrellisServiceSqlOutboxExecutorOptions<TTx> = TrellisServiceSqlOutboxCommonOptions & {
+    /** Non-transactional executor used by the process-local dispatcher. */
+    readonly executor: SqlExecutor;
+    /** Service-owned transaction runner for handler-scoped work. */
+    readonly transaction: SqlOutboxTransactionRunner<TTx>;
+};
+/** Options for binding a Trellis service to caller-owned SQL outbox storage. */
+export type TrellisServiceSqlOutboxOptions<TTx> = TrellisServiceSqlOutboxExecutorOptions<TTx>;
+/** Typed transaction-scoped event facade that enqueues prepared events. */
+export type SqlOutboxEventEnqueueFacade<TEventApi extends RuntimeApi = RuntimeApi> = {
+    readonly [TGroup in SurfaceGroupName<ServiceEventName<TEventApi>>]: {
+        readonly [E in SurfaceKeysForGroup<ServiceEventName<TEventApi>, TGroup> as SurfaceLeafName<E>]: {
+            enqueue(event: ServiceEventPayloadOf<TEventApi, E>): AsyncResult<OutboxMessage, ValidationError | UnexpectedError>;
+        };
+    };
+};
+/** Returned by outbox.job.<queue>.create/submit inside a transaction. */
+export type SqlOutboxJobSubmission = {
+    readonly submissionId: string;
+    readonly jobId: string;
+    readonly queue: string;
+    readonly mode: "create" | "submit";
+};
+/** Transaction-scoped facade for enqueuing job creation/submission intents. */
+export type SqlOutboxJobEnqueueFacade<TJobs extends ParticipantJobsMetadata> = {
+    readonly [K in keyof TJobs]: {
+        create(payload: TJobs[K]["payload"]): AsyncResult<SqlOutboxJobSubmission, ValidationError | UnexpectedError>;
+        submit(payload: TJobs[K]["payload"]): AsyncResult<SqlOutboxJobSubmission, ValidationError | UnexpectedError>;
+    };
+};
+/** Context supplied to `outbox.transaction(...)` work callbacks. */
+export type SqlOutboxTransactionContext<TTx, TEventApi extends RuntimeApi = RuntimeApi, TJobs extends ParticipantJobsMetadata = ParticipantJobsMetadata> = {
+    /** Service-owned transaction object supplied by the configured runner. */
+    readonly tx: TTx;
+    /** Transaction-scoped typed event enqueue facade. */
+    readonly event: SqlOutboxEventEnqueueFacade<TEventApi>;
+    /** Transaction-scoped typed job enqueue facade. */
+    readonly job: SqlOutboxJobEnqueueFacade<TJobs>;
+};
+/** Startup-created SQL outbox dependency for transactional event/job enqueue. */
+export type SqlOutbox<TTx, TEventApi extends RuntimeApi = RuntimeApi, TJobs extends ParticipantJobsMetadata = ParticipantJobsMetadata> = {
+    /**
+     * Runs service DB work and typed event/job enqueue operations in one SQL
+     * transaction, notifying the dispatcher once after a successful commit.
+     */
+    transaction<TResult>(work: (context: SqlOutboxTransactionContext<TTx, TEventApi, TJobs>) => Promise<TResult> | TResult): AsyncResult<TResult, ValidationError | UnexpectedError>;
+    /** Returns the durable queue-admission outcome once a job submission dispatches. */
+    jobSubmissionOutcome(submissionId: string): AsyncResult<OutboxJobDispatchOutcome | undefined, UnexpectedError>;
+};
+type SurfaceGroupName<T extends string> = T extends `${infer Head}.${string}` ? ConnectedActionName<Head> : ConnectedActionName<T>;
+type SurfaceLeafName<T extends string> = T extends `${string}.${infer Tail}` ? ConnectedActionName<Tail> : ConnectedActionName<T>;
+type SurfaceKeysForGroup<TKeys extends string, TGroup extends string> = TKeys extends string ? SurfaceGroupName<TKeys> extends TGroup ? TKeys : never : never;
+type TypedServiceHandleFacade<TOwnedApi extends RuntimeApi, TTrellisApi extends RuntimeApi, TKv extends ParticipantKvMetadata, TJobs extends ParticipantJobsMetadata> = {
+    readonly rpc: {
+        readonly [TGroup in SurfaceGroupName<RpcMethodName<TOwnedApi>>]: {
+            readonly [M in SurfaceKeysForGroup<RpcMethodName<TOwnedApi>, TGroup> as SurfaceLeafName<M>]: (handler: RpcHandleFn<TOwnedApi, TTrellisApi, M, TKv, TJobs>) => Promise<void>;
+        };
+    };
+    readonly feed: {
+        readonly [TGroup in SurfaceGroupName<keyof TOwnedApi["feeds"] & string>]: {
+            readonly [F in SurfaceKeysForGroup<keyof TOwnedApi["feeds"] & string, TGroup> as SurfaceLeafName<F>]: (handler: FeedHandleFn<TOwnedApi, TTrellisApi, F, TKv, TJobs>) => Promise<void>;
+        };
+    };
+    readonly operation: {
+        readonly [TGroup in SurfaceGroupName<keyof TOwnedApi["operations"] & string>]: {
+            readonly [O in SurfaceKeysForGroup<keyof TOwnedApi["operations"] & string, TGroup> as SurfaceLeafName<O>]: OperationHandleFn<TOwnedApi, TTrellisApi, O, TKv, TJobs>;
+        };
+    };
+};
+type RpcHandleFn<TOwnedApi extends RuntimeApi, TTrellisApi extends RuntimeApi, M extends RpcMethodName<TOwnedApi>, TKv extends ParticipantKvMetadata, TJobs extends ParticipantJobsMetadata> = (args: {
+    input: RpcMethodInput<TOwnedApi, M>;
+    context: RpcHandlerContext;
+    client: Trellis<TTrellisApi, TKv, TJobs>;
+}) => Promise<Result<RpcMethodOutput<TOwnedApi, M>, RpcHandlerErrorOf<TOwnedApi, M>>> | Result<RpcMethodOutput<TOwnedApi, M>, RpcHandlerErrorOf<TOwnedApi, M>>;
+type FeedHandleFn<TOwnedApi extends RuntimeApi, TTrellisApi extends RuntimeApi, F extends keyof TOwnedApi["feeds"] & string, TKv extends ParticipantKvMetadata, TJobs extends ParticipantJobsMetadata> = (context: {
+    input: FeedInputOf<TOwnedApi, F>;
+    caller: unknown;
+    signal: AbortSignal;
+    emit(event: FeedEventOf<TOwnedApi, F>): AsyncResult<void, ValidationError | UnexpectedError>;
+    client: Trellis<TTrellisApi, TKv, TJobs>;
+}) => unknown | Promise<unknown>;
+type OperationHandleFn<TOwnedApi extends RuntimeApi, TTrellisApi extends RuntimeApi, O extends keyof TOwnedApi["operations"] & string, TKv extends ParticipantKvMetadata, TJobs extends ParticipantJobsMetadata> = (handler: (context: OperationHandlerContext<InferSchemaType<TOwnedApi["operations"][O]["input"]>, OperationProgressOf<TOwnedApi, O>, OperationOutputOf<TOwnedApi, O>, OperationTransferContextOf<TOwnedApi, O>, OperationHandlerErrorOf<TOwnedApi, O>, OperationUpdateOf<TOwnedApi, O>> & {
+    client: Trellis<TTrellisApi, TKv, TJobs>;
+}) => unknown | Promise<unknown>) => Promise<void>;
+export type OperationRegistration<TOwnedApi extends RuntimeApi, TTrellisApi extends RuntimeApi, O extends keyof TOwnedApi["operations"] & string, TKv extends ParticipantKvMetadata = ParticipantKvMetadata, TJobs extends ParticipantJobsMetadata = ParticipantJobsMetadata> = {
+    handle(handler: (args: OperationHandlerContext<InferSchemaType<TOwnedApi["operations"][O]["input"]>, OperationProgressOf<TOwnedApi, O>, OperationOutputOf<TOwnedApi, O>, OperationTransferContextOf<TOwnedApi, O>, OperationHandlerErrorOf<TOwnedApi, O>, OperationUpdateOf<TOwnedApi, O>> & {
+        client: Trellis<TTrellisApi, TKv, TJobs>;
+    }) => unknown | Promise<unknown>): Promise<void>;
+};
+export type FeedRegistration<TOwnedApi extends RuntimeApi, F extends keyof TOwnedApi["feeds"] & string> = RootFeedRegistration<FeedInputOf<TOwnedApi, F>, FeedEventOf<TOwnedApi, F>>;
+export type TrellisServiceConnectArgs<TContract extends GeneratedServiceParticipant<RuntimeApi, RuntimeApi | undefined, ParticipantJobsMetadata, ParticipantKvMetadata>> = {
+    trellisUrl: string;
+    participant: TContract;
+    name?: string;
+    /** Immutable provisioned service identity. */
+    seed: string;
+    /** Controls automatic telemetry initialization. Enabled by default. */
+    telemetry?: TrellisServiceConnectTelemetryOpts;
+    /** Configures the connected service runtime. */
+    runtime?: TrellisServiceRuntimeOpts;
+};
+/** Connected provider runtime inferred from a service contract. */
+export type ConnectedTrellisService<TContract extends GeneratedServiceParticipant<RuntimeApi, RuntimeApi | undefined, ParticipantJobsMetadata, ParticipantKvMetadata>> = ProviderRuntime<TContract, TrellisServiceSession<ParticipantOwnedApi<TContract>, ParticipantTrellisApi<TContract>, ParticipantJobsOf<TContract>, ParticipantKvOf<TContract>>>;
+/** Connected session implementation backing the public service type. */
+export declare class TrellisServiceSession<TOwnedApi extends RuntimeApi = RuntimeApi, TTrellisApi extends RuntimeApi = TOwnedApi, TJobs extends ParticipantJobsMetadata = ParticipantJobsMetadata, TKv extends ParticipantKvMetadata = ParticipantKvMetadata> {
+    #private;
+    readonly name: string;
+    readonly auth: SessionAuth;
+    readonly [PROVIDER_CALLER]: ProviderCaller;
+    /** Event lifecycle surface for service startup listeners and publishers. */
+    readonly event: ActiveEventFacade<TTrellisApi>;
+    readonly kv: ServiceKvFacade<TKv>;
+    readonly store: Record<string, StoreHandle>;
+    readonly jobs: JobsFacadeOf<TJobs, TTrellisApi, TKv>;
+    readonly health: ServiceHealth;
+    readonly handle: TypedServiceHandleFacade<TOwnedApi, TTrellisApi, TKv, TJobs>;
+    /** Framework-neutral lifecycle handle for the service runtime connection. */
+    readonly connection: TrellisConnection;
+    private constructor();
+    /**
+     * Creates an explicit SQL outbox helper for service-owned transactions.
+     * Services should create this at startup and close over it in handlers.
+     */
+    createSqlOutbox<TTx>(options: TrellisServiceSqlOutboxExecutorOptions<TTx>): SqlOutbox<TTx, TTrellisApi, TJobs>;
+    /** Publishes a prepared event through the service runtime connection. */
+    publishPrepared(event: PreparedTrellisEvent): AsyncResult<void, UnexpectedError>;
+    /**
+     * Creates a short-lived receive transfer grant for a caller session.
+     */
+    createTransfer(args: {
+        direction: "receive";
+        store: string;
+        key: string;
+        sessionKey: string;
+        permission: PermissionAtom;
+        requiredCapabilities?: readonly string[];
+        inboxPrefix: string;
+        expiresInMs?: number;
+    }): AsyncResult<ReceiveTransferGrant, TransferError>;
+    static connect<const TContract extends GeneratedServiceParticipant<RuntimeApi, RuntimeApi | undefined, ParticipantJobsMetadata, ParticipantKvMetadata>>(args: TrellisServiceConnectArgs<TContract>): AsyncResult<ConnectedTrellisService<TContract>, TransportError | UnexpectedError>;
+    wait(): Promise<void>;
+    stop(): Promise<void>;
+}
+/** Public factory for connecting a descriptor-defined Trellis service. */
+export declare class TrellisService {
+    private constructor();
+    /** Connects a service and returns its provider-only runtime facade. */
+    static connect<const TContract extends GeneratedServiceParticipant<RuntimeApi, RuntimeApi | undefined, ParticipantJobsMetadata, ParticipantKvMetadata>>(args: TrellisServiceConnectArgs<TContract>): AsyncResult<ConnectedTrellisService<TContract>, TransportError | UnexpectedError>;
+}
+export {};