@oatscenter/trellis 0.100.0-rc.1

package/provider.d.ts

@@ -0,0 +1,69 @@
+import type { AsyncResult, BaseError } from "@oatscenter/result";
+import { type CallerRuntime } from "./caller.ts";
+import { type GeneratedParticipant } from "./participant_runtime/participant.ts";
+import type { PascalActionName } from "./participant_runtime/surface_names.ts";
+import type { EventListenerContext } from "./session.ts";
+import type { InferSchemaType, RuntimeApi } from "./participant_runtime/api.ts";
+import type { ParticipantJobsMetadata, ParticipantKvMetadata } from "./participant_runtime/metadata.ts";
+import type { FeedHandler, GeneratedServiceParticipant, OperationHandler, RpcHandler } from "./service/runtime/service.ts";
+export declare const PROVIDER_CALLER: unique symbol;
+export type ProviderCaller = object;
+type ProviderBase<TService> = TService extends {
+    readonly health: infer THealth;
+    readonly connection: infer TConnection;
+    readonly name: infer TName;
+    readonly createSqlOutbox: infer TCreateSqlOutbox;
+    readonly createTransfer: infer TCreateTransfer;
+} ? {
+    readonly health: THealth;
+    readonly connection: TConnection;
+    readonly name: TName;
+    readonly createSqlOutbox: TCreateSqlOutbox;
+    readonly createTransfer: TCreateTransfer;
+    wait(): Promise<void>;
+    stop(): Promise<void>;
+} : {};
+type ProviderResources<TService> = TService extends {
+    readonly kv: infer TKv;
+    readonly store: infer TStore;
+    readonly jobs: infer TJobs;
+} ? {
+    readonly kv: TKv;
+    readonly store: TStore;
+    readonly jobs: TJobs;
+} : {};
+type ServiceContract<TContract extends GeneratedParticipant> = Extract<TContract, GeneratedServiceParticipant<RuntimeApi, RuntimeApi | undefined, ParticipantJobsMetadata, ParticipantKvMetadata>>;
+type OwnedApi<TContract extends GeneratedParticipant> = TContract extends {
+    readonly __runtimeTypes?: {
+        readonly ownedApi: infer TApi;
+    };
+} ? Extract<TApi, RuntimeApi> : never;
+type ProviderRegistrations<TContract extends GeneratedParticipant> = {
+    readonly [K in keyof OwnedApi<TContract>["rpc"] & string as `handle${PascalActionName<K>}`]: (handler: RpcHandler<ServiceContract<TContract>, K>) => unknown;
+} & {
+    readonly [K in keyof OwnedApi<TContract>["operations"] & string as `handle${PascalActionName<K>}`]: (handler: OperationHandler<ServiceContract<TContract>, K>) => unknown;
+} & {
+    readonly [K in keyof NonNullable<OwnedApi<TContract>["feeds"]> & string as `handle${PascalActionName<K>}`]: (handler: FeedHandler<ServiceContract<TContract>, K>) => unknown;
+} & {
+    readonly [K in keyof OwnedApi<TContract>["events"] & string as `on${PascalActionName<K>}`]: (handler: (args: {
+        event: InferSchemaType<OwnedApi<TContract>["events"][K]["event"]>;
+        context: EventListenerContext;
+        client: ProviderCallerSurface<TContract>;
+    }) => unknown | Promise<unknown>, subjectData?: Record<string, unknown>, options?: unknown) => AsyncResult<void, BaseError>;
+} & {
+    readonly [K in keyof OwnedApi<TContract>["events"] & string as `publish${PascalActionName<K>}`]: (event: InferSchemaType<OwnedApi<TContract>["events"][K]["event"]>) => AsyncResult<void, BaseError>;
+};
+type ProviderOwnedPublish<TContract extends GeneratedParticipant> = {
+    readonly [K in keyof OwnedApi<TContract>["events"] & string as `publish${PascalActionName<K>}`]: (event: InferSchemaType<OwnedApi<TContract>["events"][K]["event"]>) => AsyncResult<void, BaseError>;
+};
+type ProviderCallerSurface<TContract extends GeneratedParticipant> = Omit<CallerRuntime<TContract>, "connection" | "kv" | "state" | "store" | "wait" | Extract<keyof CallerRuntime<TContract>, `on${string}` | `publish${string}`>>;
+/** Caller and bound-resource surface available inside provider handlers. */
+export type ProviderHandlerClient<TContract extends GeneratedParticipant, TService> = ProviderCallerSurface<TContract> & ProviderOwnedPublish<TContract> & ProviderResources<TService> & (ProviderBase<TService> extends infer TBase ? TBase extends {
+    connection: unknown;
+    name: unknown;
+} ? Pick<TBase, "connection" | "name"> : {} : {});
+/** Connected provider facade for a generated service participant. */
+export type ProviderRuntime<TContract extends GeneratedParticipant, TService> = ProviderBase<TService> & ProviderResources<TService> & ProviderCallerSurface<TContract> & ProviderRegistrations<TContract>;
+/** Projects a connected service into its flat provider and caller vocabulary. */
+export declare function createProviderRuntime<TContract extends GeneratedParticipant, TService extends object>(connectedService: TService, contract: TContract): ProviderRuntime<TContract, TService>;
+export {};

package/provider.js

@@ -0,0 +1,68 @@
+import { createCallerRuntime } from "./caller.js";
+import { getParticipantRuntime, } from "./participant_runtime/participant.js";
+import { lowerCamelSurfaceName, pascalSurfaceName, } from "./participant_runtime/surface_names.js";
+export const PROVIDER_CALLER = Symbol("trellis.provider.caller");
+function surfacePath(name) {
+    const [head, ...tail] = name.split(".");
+    return [
+        lowerCamelSurfaceName(head),
+        lowerCamelSurfaceName(tail.length === 0 ? name : tail.join(".")),
+    ];
+}
+/** Projects a connected service into its flat provider and caller vocabulary. */
+export function createProviderRuntime(connectedService, contract) {
+    const service = connectedService;
+    const provider = {
+        kv: service.kv,
+        store: service.store,
+        health: service.health,
+        connection: service.connection,
+        name: service.name,
+        createSqlOutbox: service.createSqlOutbox.bind(service),
+        createTransfer: service.createTransfer.bind(service),
+        publishPrepared: service.publishPrepared.bind(service),
+        wait: service.wait.bind(service),
+        stop: service.stop.bind(service),
+    };
+    provider.jobs = Object.fromEntries(Object.entries(service.jobs).map(([name, queue]) => [name, {
+            ...queue,
+            handle: (handler, options) => queue.handle((args) => handler({ ...args, client: provider }), options),
+        }]));
+    const caller = createCallerRuntime(service[PROVIDER_CALLER], contract);
+    for (const action of getParticipantRuntime(contract).actions) {
+        const connected = caller[action.connectedName];
+        if (action.descriptor.kind === "event" && action.direction === "subscribe") {
+            provider[action.connectedName] = (handler, subjectData, options) => service[PROVIDER_CALLER].listenEvent(action.name, subjectData ?? {}, (message, context) => handler({ event: message, context, client: provider }), options);
+        }
+        else {
+            provider[action.connectedName] = connected;
+        }
+    }
+    for (const name of Object.keys(getParticipantRuntime(contract).ownedApi.rpc)) {
+        const [group, leaf] = surfacePath(name);
+        const register = service.handle.rpc[group][leaf];
+        provider[`handle${pascalSurfaceName(name)}`] = (handler) => register((args) => handler({ ...args, client: provider }));
+    }
+    for (const name of Object.keys(getParticipantRuntime(contract).ownedApi.operations)) {
+        const [group, leaf] = surfacePath(name);
+        const register = service.handle.operation[group][leaf];
+        const expose = (handler) => register((args) => handler({ ...args, client: provider }));
+        provider[`handle${pascalSurfaceName(name)}`] = Object.assign(expose, {
+            ...(register.accept ? { accept: register.accept.bind(register) } : {}),
+            ...(register.control ? { control: register.control.bind(register) } : {}),
+        });
+    }
+    for (const name of Object.keys(getParticipantRuntime(contract).ownedApi.feeds ?? {})) {
+        const [group, leaf] = surfacePath(name);
+        const register = service.handle.feed[group][leaf];
+        provider[`handle${pascalSurfaceName(name)}`] = (handler) => register((args) => handler(args));
+    }
+    for (const name of Object.keys(getParticipantRuntime(contract).ownedApi.events)) {
+        provider[`on${pascalSurfaceName(name)}`] = (handler, subjectData, options) => service[PROVIDER_CALLER].listenEvent(name, subjectData ?? {}, (message, context) => handler({ event: message, context, client: provider }), options);
+        const publish = Object.assign((event) => service[PROVIDER_CALLER].publish(name, event), {
+            prepare: (event) => service[PROVIDER_CALLER].prepare(name, event),
+        });
+        provider[`publish${pascalSurfaceName(name)}`] = publish;
+    }
+    return provider;
+}

package/runtime_transport.d.ts

@@ -0,0 +1,25 @@
+import type { Authenticator, NatsConnection } from "@nats-io/nats-core";
+type RuntimeTransportEndpoints = {
+    natsServers: string[];
+};
+type RuntimeTransports = {
+    native?: RuntimeTransportEndpoints;
+    websocket?: RuntimeTransportEndpoints;
+};
+export declare const DEFAULT_RUNTIME_MAX_RECONNECT_ATTEMPTS = -1;
+export declare const DEFAULT_SERVICE_RUNTIME_WAIT_ON_FIRST_CONNECT = true;
+export type RuntimeTransportConnectOptions = {
+    servers: string | string[];
+    token?: string;
+    authenticator?: Authenticator | Authenticator[];
+    inboxPrefix?: string;
+    maxReconnectAttempts?: number;
+    waitOnFirstConnect?: boolean;
+} & Record<string, unknown>;
+export type RuntimeTransport = {
+    connect(options: RuntimeTransportConnectOptions): Promise<NatsConnection>;
+};
+export declare function selectRuntimeTransportServers(transports: RuntimeTransports): string[];
+/** Loads WebSocket transport in browsers and native Node transport in Node/Deno. */
+export declare function loadDefaultRuntimeTransport(): Promise<RuntimeTransport>;
+export {};

package/runtime_transport.js

@@ -0,0 +1,48 @@
+import { wsconnect } from "@nats-io/nats-core";
+export const DEFAULT_RUNTIME_MAX_RECONNECT_ATTEMPTS = -1;
+export const DEFAULT_SERVICE_RUNTIME_WAIT_ON_FIRST_CONNECT = true;
+export function selectRuntimeTransportServers(transports) {
+    if (isBrowserRuntime()) {
+        if (transports.websocket?.natsServers?.length) {
+            return transports.websocket.natsServers;
+        }
+        if (transports.native?.natsServers?.length) {
+            return transports.native.natsServers;
+        }
+    }
+    else {
+        if (transports.native?.natsServers?.length) {
+            return transports.native.natsServers;
+        }
+        if (transports.websocket?.natsServers?.length) {
+            return transports.websocket.natsServers;
+        }
+    }
+    throw new Error("No supported NATS transport endpoints available");
+}
+function isBrowserRuntime() {
+    const browserGlobal = globalThis;
+    return typeof browserGlobal.window !== "undefined" &&
+        typeof browserGlobal.document !== "undefined";
+}
+function usesWebSocketTransport(servers) {
+    const values = Array.isArray(servers) ? servers : [servers];
+    return values.some((server) => server.startsWith("ws://") || server.startsWith("wss://"));
+}
+/** Loads WebSocket transport in browsers and native Node transport in Node/Deno. */
+export async function loadDefaultRuntimeTransport() {
+    if (isBrowserRuntime()) {
+        return {
+            connect: wsconnect,
+        };
+    }
+    return {
+        connect: async (options) => {
+            if (usesWebSocketTransport(options.servers)) {
+                return await wsconnect(options);
+            }
+            const { connect } = await import("@nats-io/transport-node");
+            return await connect(options);
+        },
+    };
+}

package/service/mod.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Trellis service authoring entry point.
+ *
+ * This subpath exposes the service wrapper and service-side helpers without the
+ * internal service runtime implementation.
+ *
+ * @module
+ */
+export { type HealthCheckResult, runAllServiceHealthChecks, runServiceHealthCheck, type ServiceHealth, type ServiceHealthCheck, type ServiceHealthCheckFn, type ServiceHealthInfo, type ServiceHealthInfoFn, } from "./runtime/health.ts";
+export { HealthCheckResultSchema, HealthInfoSchema, } from "./runtime/health_schemas.ts";
+export { type ConnectedTrellisService, type FeedHandler, type GeneratedServiceParticipant, type HealthCheckHandler, type HealthInfoHandler, type JobHandler, type OperationHandler, type OperationRegistration, type RpcHandler, type ServiceEventHandler, type SqlOutbox, type SqlOutboxEventEnqueueFacade, type SqlOutboxJobEnqueueFacade, type SqlOutboxJobSubmission, type SqlOutboxTransactionContext, type SqlOutboxTransactionRunner, TrellisService, type TrellisServiceConnectOpts, type TrellisServiceConnectTelemetryOpts, type TrellisServiceSqlOutboxCommonOptions, type TrellisServiceSqlOutboxExecutorOptions, type TrellisServiceSqlOutboxOptions, } from "./runtime/service.ts";
+export { createPostgresOutboxSchema, createSqliteOutboxSchema, createSqlOutboxAdapter, defaultSqlOutboxTables, dispatchOutbox, getSqlOutboxMigrations, type InboxRepository, type KvOutboxRecord, KvOutboxRecordSchema, MemoryInboxRepository, MemoryOutboxRepository, NatsKvInboxRepository, NatsKvOutboxRepository, OutboxDispatcher, type OutboxDispatcherOptions, type OutboxDispatchResult, type OutboxDispatchRuntime, type OutboxJobDispatchOutcome, type OutboxKvStore, type OutboxMessage, type OutboxMessageState, outboxMessageToPreparedEvent, type OutboxRecordKind, type OutboxRepository, type PreparedOutboxRecord, preparedTrellisEventToOutboxRecord, type SqlDialect, type SqlExecutor, SqlInboxRepository, type SqlOutboxAdapter, type SqlOutboxMigration, type SqlOutboxMigrationOptions, SqlOutboxRepository, type SqlOutboxTables, type SqlRow, } from "./outbox_inbox.ts";
+export { ActiveJob, decodeJobUpdateEnvelope, JobLogEntrySchema, JobProgressSchema, JobQueue, JobRef, JobWorkerHostAdapter, RetryJobError, } from "../jobs.ts";
+export type { Job, JobFilter, JobHandlerOptions, JobIdentity, JobLogEntry, JobProgress, JobsFacade, JobsFacadeOf, JobSnapshot, JobState, JobTypeMetadata, JobUpdateEnvelope, JobUpdatesOptions, JobUpdateSubscription, JobWorkerHost, RetryJobErrorData, ServiceInfo, TerminalJob, WorkerInfo, } from "../jobs.ts";

package/service/mod.js

@@ -0,0 +1,13 @@
+/**
+ * Trellis service authoring entry point.
+ *
+ * This subpath exposes the service wrapper and service-side helpers without the
+ * internal service runtime implementation.
+ *
+ * @module
+ */
+export { runAllServiceHealthChecks, runServiceHealthCheck, } from "./runtime/health.js";
+export { HealthCheckResultSchema, HealthInfoSchema, } from "./runtime/health_schemas.js";
+export { TrellisService, } from "./runtime/service.js";
+export { createPostgresOutboxSchema, createSqliteOutboxSchema, createSqlOutboxAdapter, defaultSqlOutboxTables, dispatchOutbox, getSqlOutboxMigrations, KvOutboxRecordSchema, MemoryInboxRepository, MemoryOutboxRepository, NatsKvInboxRepository, NatsKvOutboxRepository, OutboxDispatcher, outboxMessageToPreparedEvent, preparedTrellisEventToOutboxRecord, SqlInboxRepository, SqlOutboxRepository, } from "./outbox_inbox.js";
+export { ActiveJob, decodeJobUpdateEnvelope, JobLogEntrySchema, JobProgressSchema, JobQueue, JobRef, JobWorkerHostAdapter, RetryJobError, } from "../jobs.js";

package/service/outbox_inbox.d.ts

@@ -0,0 +1,259 @@
+import { type AsyncResult, type BaseError, type UnexpectedError } from "@oatscenter/result";
+import { type StaticDecode, Type } from "typebox";
+import type { TypedKV } from "../kv.ts";
+import type { PreparedTrellisEvent } from "../session.ts";
+export type OutboxMessageState = "pending" | "claimed" | "dispatched" | "failed";
+export type OutboxRecordKind = "event.publish" | "job.create" | "job.submit";
+export type PreparedOutboxRecord = {
+    readonly id: string;
+    readonly kind: OutboxRecordKind;
+    readonly name: string;
+    readonly subject: string;
+    readonly payload: string;
+    readonly headers: Readonly<Record<string, string>>;
+};
+export type OutboxMessage = {
+    id: string;
+    kind: OutboxRecordKind;
+    name: string;
+    subject: string;
+    payload: string;
+    headers: Record<string, string>;
+    state: OutboxMessageState;
+    attempts: number;
+    createdAt: string;
+    updatedAt: string;
+    nextAttemptAt?: string;
+    lastError?: string;
+    outcome?: unknown;
+};
+/** Raised when an outbox ID is reused for different immutable content. */
+export declare class OutboxDuplicateIdentityError extends Error {
+    readonly id: string;
+    constructor(id: string);
+}
+/** Raised when storage reports a duplicate but the winning row cannot be read. */
+export declare class OutboxStorageConflictError extends Error {
+    readonly id: string;
+    constructor(id: string);
+}
+export type OutboxDispatchResult = {
+    dispatched: number;
+    failed: number;
+};
+/** Queue-admission result persisted after a SQL-outboxed job is dispatched. */
+export type OutboxJobDispatchOutcome = {
+    readonly kind: string;
+    readonly [key: string]: unknown;
+};
+/** Options for {@link OutboxDispatcher}. */
+export type OutboxDispatcherOptions = {
+    /** Maximum number of messages claimed by each `dispatchOutbox` batch. */
+    limit?: number;
+    /** Delay before failed messages become eligible; values below 1ms become 1ms. */
+    retryDelayMs?: number;
+    /** Delay used to debounce `notify()` calls before starting a drain. */
+    debounceMs?: number;
+    /** Optional low-frequency wakeup for missed signals or process restarts. */
+    idleRetryMs?: number;
+    /** Receives repository or publish errors raised by background dispatch. */
+    onError?: (error: unknown) => void;
+};
+export type OutboxDispatchRuntime = {
+    /** Dispatches an event-publish outbox record. Returns Void on success, err on transient failure. */
+    publishPreparedEvent(event: PreparedTrellisEvent): AsyncResult<void, UnexpectedError>;
+    /** Dispatches a job create/submit outbox record and returns its queue-admission outcome. */
+    dispatchJobSubmission?(message: OutboxMessage): AsyncResult<OutboxJobDispatchOutcome, BaseError>;
+};
+export type OutboxRepository = {
+    enqueue(record: PreparedOutboxRecord): Promise<OutboxMessage>;
+    get(id: string): Promise<OutboxMessage | undefined>;
+    /** Claim due work for 30 seconds; the returned attempt fences completion. */
+    claimDue(limit: number, now: Date): Promise<OutboxMessage[]>;
+    /** Complete the returned claim; false means its ownership was superseded. */
+    markDispatched(claim: OutboxMessage, now: Date, outcome?: unknown): Promise<boolean>;
+    /** Retry the returned claim; false means its ownership was superseded. */
+    markFailed(claim: OutboxMessage, failure: {
+        error: string;
+        nextAttemptAt: Date;
+        now: Date;
+    }): Promise<boolean>;
+};
+export type InboxRepository = {
+    /** Insert a dedupe marker; true only when this call inserted it. */
+    record(messageId: string, now?: Date): Promise<boolean>;
+};
+/** SQL dialects supported by Trellis SQL outbox helpers. */
+export type SqlDialect = "sqlite" | "postgres";
+/** Table names used by Trellis SQL outbox and inbox helper tables. */
+export type SqlOutboxTables = {
+    outbox: string;
+    inbox: string;
+};
+/** Minimal SQL execution surface used by Trellis SQL outbox repositories. */
+export type SqlExecutor = {
+    query(sql: string, params: readonly unknown[]): Promise<readonly SqlRow[]>;
+    execute(sql: string, params: readonly unknown[]): Promise<void>;
+};
+/** Row shape returned by a {@link SqlExecutor}. */
+export type SqlRow = Record<string, unknown>;
+/** SQL outbox adapter bundle over caller-owned SQL execution. */
+export type SqlOutboxAdapter = {
+    outbox: SqlOutboxRepository;
+    inbox: SqlInboxRepository;
+    ddl: readonly string[];
+};
+/** Versioned Trellis-owned SQL outbox/inbox migration artifact. */
+export type SqlOutboxMigration = {
+    /** Stable migration identifier for the dialect and schema version. */
+    readonly id: string;
+    /** Monotonic Trellis helper-table schema version. */
+    readonly version: number;
+    /** SQL dialect targeted by this migration artifact. */
+    readonly dialect: SqlDialect;
+    /** SQL statements that apply this migration. */
+    readonly up: readonly string[];
+    /** SQL statements that revert this migration when supported by the runner. */
+    readonly down?: readonly string[];
+    /** Deterministic checksum over the canonical migration SQL. */
+    readonly checksum: string;
+};
+/** Options for generating Trellis SQL outbox/inbox migration artifacts. */
+export type SqlOutboxMigrationOptions = {
+    /** SQL dialect targeted by the generated migration artifacts. */
+    readonly dialect: SqlDialect;
+    /** Optional helper-table names; omitted names use Trellis defaults. */
+    readonly tables?: Partial<SqlOutboxTables>;
+};
+export type OutboxKvStore = Pick<TypedKV<KvOutboxRecord>, "create" | "getEntry" | "replace" | "keys">;
+/** Default Trellis helper-table names for SQL outbox and inbox storage. */
+export declare const defaultSqlOutboxTables: SqlOutboxTables;
+/**
+ * Creates SQL outbox/inbox repositories plus current helper-table DDL.
+ *
+ * Use {@link getSqlOutboxMigrations} when services need versioned Trellis-owned
+ * migration artifacts for their normal database migration tooling.
+ */
+export declare function createSqlOutboxAdapter(executor: SqlExecutor, dialect: SqlDialect, tables?: SqlOutboxTables): SqlOutboxAdapter;
+/**
+ * Returns Trellis-owned SQL outbox/inbox migration artifacts for a dialect.
+ *
+ * Trellis generates the helper-table SQL, but services remain responsible for
+ * running these artifacts through their normal database migration tooling.
+ */
+export declare function getSqlOutboxMigrations(options: SqlOutboxMigrationOptions): readonly SqlOutboxMigration[];
+/** Returns SQLite DDL for Trellis outbox and inbox tables. */
+export declare function createSqliteOutboxSchema(tables?: SqlOutboxTables): readonly string[];
+/** Returns Postgres DDL for Trellis outbox and inbox tables. */
+export declare function createPostgresOutboxSchema(tables?: SqlOutboxTables): readonly string[];
+/** In-memory outbox repository intended for tests and local process adapters. */
+export declare class MemoryOutboxRepository implements OutboxRepository {
+    #private;
+    enqueue(record: PreparedOutboxRecord): Promise<OutboxMessage>;
+    get(id: string): Promise<OutboxMessage | undefined>;
+    claimDue(limit: number, now: Date): Promise<OutboxMessage[]>;
+    markDispatched(claim: OutboxMessage, now: Date, outcome?: unknown): Promise<boolean>;
+    markFailed(claim: OutboxMessage, failure: {
+        error: string;
+        nextAttemptAt: Date;
+        now: Date;
+    }): Promise<boolean>;
+    snapshot(): readonly OutboxMessage[];
+}
+/** In-memory inbox repository intended for duplicate-suppression tests. */
+export declare class MemoryInboxRepository implements InboxRepository {
+    #private;
+    record(messageId: string): Promise<boolean>;
+}
+/** SQL-backed outbox repository over a caller-owned executor. */
+export declare class SqlOutboxRepository implements OutboxRepository {
+    readonly executor: SqlExecutor;
+    readonly dialect: SqlDialect;
+    readonly tables: SqlOutboxTables;
+    constructor(executor: SqlExecutor, dialect: SqlDialect, tables?: SqlOutboxTables);
+    enqueue(record: PreparedOutboxRecord): Promise<OutboxMessage>;
+    get(id: string): Promise<OutboxMessage | undefined>;
+    claimDue(limit: number, now: Date): Promise<OutboxMessage[]>;
+    markDispatched(claim: OutboxMessage, now: Date, outcome?: unknown): Promise<boolean>;
+    markFailed(claim: OutboxMessage, failure: {
+        error: string;
+        nextAttemptAt: Date;
+        now: Date;
+    }): Promise<boolean>;
+}
+/** SQL-backed inbox repository over a caller-owned executor. */
+export declare class SqlInboxRepository implements InboxRepository {
+    readonly executor: SqlExecutor;
+    readonly dialect: SqlDialect;
+    readonly tables: SqlOutboxTables;
+    constructor(executor: SqlExecutor, dialect: SqlDialect, tables?: SqlOutboxTables);
+    record(messageId: string, now?: Date): Promise<boolean>;
+}
+declare const KvInboxRecordSchema: Type.TObject<{
+    messageId: Type.TString;
+    receivedAt: Type.TString;
+}>;
+type KvInboxRecord = StaticDecode<typeof KvInboxRecordSchema>;
+export declare const KvOutboxRecordSchema: Type.TObject<{
+    id: Type.TString;
+    kind: Type.TString;
+    name: Type.TString;
+    subject: Type.TString;
+    payload: Type.TString;
+    headers: Type.TRecord<"^.*$", Type.TString>;
+    state: Type.TUnion<[Type.TLiteral<"pending">, Type.TLiteral<"dispatched">, Type.TLiteral<"failed">, Type.TLiteral<"claimed">]>;
+    attempts: Type.TNumber;
+    createdAt: Type.TString;
+    updatedAt: Type.TString;
+    nextAttemptAt: Type.TOptional<Type.TString>;
+    lastError: Type.TOptional<Type.TString>;
+    outcome: Type.TOptional<Type.TString>;
+}>;
+export type KvOutboxRecord = StaticDecode<typeof KvOutboxRecordSchema>;
+/** Durable NATS KV outbox repository for services without SQL state. */
+export declare class NatsKvOutboxRepository implements OutboxRepository {
+    readonly kv: OutboxKvStore;
+    constructor(kv: OutboxKvStore);
+    enqueue(rec: PreparedOutboxRecord): Promise<OutboxMessage>;
+    get(id: string): Promise<OutboxMessage | undefined>;
+    claimDue(limit: number, now: Date): Promise<OutboxMessage[]>;
+    markDispatched(claim: OutboxMessage, now: Date, outcome?: unknown): Promise<boolean>;
+    markFailed(claim: OutboxMessage, failure: {
+        error: string;
+        nextAttemptAt: Date;
+        now: Date;
+    }): Promise<boolean>;
+}
+/** Durable NATS KV inbox repository for event-id duplicate suppression. */
+export declare class NatsKvInboxRepository implements InboxRepository {
+    readonly kv: TypedKV<KvInboxRecord>;
+    constructor(kv: TypedKV<KvInboxRecord>);
+    record(messageId: string, now?: Date): Promise<boolean>;
+}
+/**
+ * Coalesces outbox wakeups and drains due messages through `dispatchOutbox`.
+ *
+ * The dispatcher is process-local coordination only. Callers should invoke
+ * `notify()` after committing outbox rows so dispatch does not observe rolled
+ * back work.
+ */
+export declare class OutboxDispatcher {
+    #private;
+    /** Creates a dispatcher over an existing outbox repository and runtime. */
+    constructor(repository: OutboxRepository, runtime: OutboxDispatchRuntime, options?: OutboxDispatcherOptions);
+    /** Signals that outbox work may be available and schedules a drain soon. */
+    notify(): void;
+    /** Cancels pending wakeups and prevents future dispatch work. */
+    stop(): void;
+}
+/** Dispatches due outbox messages through a dispatch runtime. */
+export declare function dispatchOutbox(repository: OutboxRepository, runtime: OutboxDispatchRuntime, options?: {
+    limit?: number;
+    now?: Date;
+    retryDelayMs?: number;
+}): Promise<OutboxDispatchResult>;
+/** Rehydrates a persisted outbox event row into a prepared event. */
+export declare function outboxMessageToPreparedEvent(message: OutboxMessage): PreparedTrellisEvent;
+/** Adapts a prepared Trellis event into a generic outbox record. */
+export declare function preparedTrellisEventToOutboxRecord(event: PreparedTrellisEvent): PreparedOutboxRecord;
+export {};