@oatscenter/trellis 0.100.0-rc.1

package/kv.d.ts

@@ -0,0 +1,85 @@
+import { type KV } from "@nats-io/kv";
+import type { NatsConnection } from "@nats-io/nats-core/internal";
+import { AsyncResult, type BaseError, Result } from "@oatscenter/result";
+import type { Codec } from "./generated.ts";
+import { KVError, ValidationError } from "./errors/index.ts";
+declare const resourceRevisionBrand: unique symbol;
+/** Opaque storage revision returned by State and KV resources. */
+export type ResourceRevision = number & {
+    readonly [resourceRevisionBrand]: "ResourceRevision";
+};
+/** A direct historical-to-current representation migration. */
+export type KvMigration<TCurrent, THistoric = unknown> = (value: THistoric) => TCurrent | Result<TCurrent, BaseError> | Promise<TCurrent | Result<TCurrent, BaseError>>;
+/** Runtime representation metadata emitted by a generated participant. */
+export type KvRepresentation<T> = Readonly<{
+    codec: Codec<T>;
+    version: number;
+    migrations: Readonly<Record<number, Codec<unknown>>>;
+}>;
+/** Caller-supplied direct migrations keyed by historical representation version. */
+export type ResourceMigrations<T> = Readonly<Record<number, KvMigration<T>>>;
+/** The operation represented by one retained KV revision. */
+export type KvOperation = "put" | "delete";
+/** Immutable value and storage metadata for one KV revision. */
+export type TypedKvEntry<T> = Readonly<{
+    key: string;
+    value?: T;
+    revision: ResourceRevision;
+    timestamp: Date;
+    operation: KvOperation;
+}>;
+/** A fallible entry yielded by a KV watcher. */
+export type KvWatchItem<T> = Result<TypedKvEntry<T>, KVError | ValidationError>;
+/** Options used to open a typed KV resource. */
+export type KvOpenOptions<T = unknown> = Readonly<{
+    history?: number;
+    ttl?: number;
+    bindOnly?: boolean;
+    maxValueBytes?: number;
+    replicas?: number;
+    migrations?: ResourceMigrations<T>;
+    isCurrent?: () => boolean;
+}>;
+type ExistingBucketStatus = Pick<Awaited<ReturnType<KV["status"]>>, "bucket" | "history" | "ttl" | "maxValueSize" | "max_bytes">;
+/** Verifies that an existing physical bucket satisfies the requested limits. */
+export declare function ensureExistingBucketOptions(kv: {
+    status(): Promise<ExistingBucketStatus>;
+}, name: string, options: KvOpenOptions): Promise<void>;
+/** Encode a current value in the strict TRKV envelope. */
+export declare function encodeResourceValue<T>(representation: KvRepresentation<T>, value: T): Uint8Array<ArrayBuffer>;
+/** Decode and optionally migrate one envelope without writing it back. */
+export declare function decodeResourceValue<T>(representation: KvRepresentation<T>, migrations: ResourceMigrations<T>, bytes: Uint8Array): Promise<T>;
+/** Typed access to a generated, versioned KV resource. */
+export declare class TypedKV<T> {
+    #private;
+    readonly representation: KvRepresentation<T>;
+    readonly kv: KV;
+    readonly migrations: ResourceMigrations<T>;
+    readonly isCurrent: () => boolean;
+    private constructor();
+    /** Opens or creates a typed KV bucket. */
+    static open<T>(nats: NatsConnection, name: string, representation: KvRepresentation<T>, options?: KvOpenOptions<T>): AsyncResult<TypedKV<T>, KVError>;
+    /** Returns the current value, or `undefined` when absent or deleted. */
+    get(key: string): AsyncResult<T | undefined, KVError | ValidationError>;
+    /** Returns the latest value or tombstone with authoritative revision metadata. */
+    getEntry(key: string): AsyncResult<TypedKvEntry<T> | undefined, KVError | ValidationError>;
+    /** Creates a value only when the key has no current value. */
+    create(key: string, value: T): AsyncResult<TypedKvEntry<T>, KVError>;
+    /** Writes a value without a revision precondition. */
+    put(key: string, value: T): AsyncResult<TypedKvEntry<T>, KVError>;
+    /** Replaces a value only when its current revision matches. */
+    replace(key: string, revision: ResourceRevision, value: T): AsyncResult<TypedKvEntry<T>, KVError>;
+    /** Deletes a key, optionally requiring its current revision. */
+    delete(key: string, revision?: ResourceRevision): AsyncResult<void, KVError>;
+    /** Returns all retained revisions for a key, including tombstones. */
+    history(key: string): AsyncResult<readonly TypedKvEntry<T>[], KVError | ValidationError>;
+    /** Watches retained initialization and subsequent revisions for one key. */
+    watch(key: string): AsyncResult<AsyncIterable<KvWatchItem<T>>, KVError>;
+    /** Lists live keys using the backend's bounded iterator. */
+    keys(filter?: string | string[]): AsyncResult<AsyncIterable<string>, KVError>;
+    /** Returns the backend live-value count. */
+    status(): AsyncResult<{
+        values: number;
+    }, KVError>;
+}
+export {};

package/kv.js

@@ -0,0 +1,330 @@
+import { Kvm } from "@nats-io/kv";
+import { AsyncResult, Result } from "@oatscenter/result";
+import { KVError, ValidationError } from "./errors/index.js";
+import { decodeSubject, escapeKvKey } from "./helpers.js";
+const KV_MAGIC = new Uint8Array([0x54, 0x52, 0x4b, 0x56]);
+const KV_ENVELOPE_FORMAT = 1;
+const KV_ENVELOPE_HEADER_BYTES = 9;
+const textEncoder = new TextEncoder();
+const textDecoder = new TextDecoder("utf-8", { fatal: true });
+function revisionFromBackend(revision) {
+    return revision;
+}
+/** Verifies that an existing physical bucket satisfies the requested limits. */
+export async function ensureExistingBucketOptions(kv, name, options) {
+    const status = await kv.status();
+    const history = options.history ?? 1;
+    const ttl = options.ttl ?? 0;
+    if (status.bucket !== name) {
+        throw new Error(`KV bucket '${name}' opened physical bucket '${status.bucket}'`);
+    }
+    if (status.history < history) {
+        throw new Error(`KV bucket '${name}' history ${status.history} is less than requested ${history}`);
+    }
+    if (status.ttl !== ttl) {
+        throw new Error(`KV bucket '${name}' TTL does not match requested TTL`);
+    }
+    if (status.max_bytes > 0) {
+        throw new Error(`KV bucket '${name}' has an uncommitted provider total size limit`);
+    }
+    const maxValueBytes = options.maxValueBytes;
+    if (maxValueBytes === undefined && status.maxValueSize > 0) {
+        throw new Error(`KV bucket '${name}' has an uncommitted provider value size limit`);
+    }
+    if (maxValueBytes !== undefined &&
+        status.maxValueSize > 0 && status.maxValueSize < maxValueBytes) {
+        throw new Error(`KV bucket '${name}' provider size limit is less than requested`);
+    }
+}
+function kvError(operation, key, cause) {
+    return new KVError({
+        operation,
+        cause,
+        context: key === undefined ? undefined : { key },
+    });
+}
+function validationError(entry, message, cause) {
+    return new ValidationError({
+        errors: [{ path: "", message }],
+        cause,
+        context: {
+            key: decodeSubject(entry.key),
+            revision: entry.revision,
+        },
+    });
+}
+/** Encode a current value in the strict TRKV envelope. */
+export function encodeResourceValue(representation, value) {
+    if (!Number.isInteger(representation.version) || representation.version <= 0 ||
+        representation.version > 0xffff_ffff) {
+        throw new RangeError("KV representation version must be a positive u32");
+    }
+    const body = textEncoder.encode(JSON.stringify(representation.codec.encode(value)));
+    const bytes = new Uint8Array(KV_ENVELOPE_HEADER_BYTES + body.length);
+    bytes.set(KV_MAGIC);
+    bytes[4] = KV_ENVELOPE_FORMAT;
+    new DataView(bytes.buffer).setUint32(5, representation.version);
+    bytes.set(body, KV_ENVELOPE_HEADER_BYTES);
+    return bytes;
+}
+/** Decode and optionally migrate one envelope without writing it back. */
+export async function decodeResourceValue(representation, migrations, bytes) {
+    if (bytes.length < KV_ENVELOPE_HEADER_BYTES ||
+        KV_MAGIC.some((byte, index) => bytes[index] !== byte) ||
+        bytes[4] !== KV_ENVELOPE_FORMAT)
+        throw new Error("Invalid TRKV envelope");
+    const version = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength).getUint32(5);
+    const encoded = JSON.parse(textDecoder.decode(bytes.subarray(KV_ENVELOPE_HEADER_BYTES)));
+    if (version === representation.version) {
+        return representation.codec.decode(encoded);
+    }
+    const historicCodec = representation.migrations[version];
+    const migrate = migrations[version];
+    if (!historicCodec || !migrate) {
+        throw new Error(`Unsupported resource representation version ${version}`);
+    }
+    const migrated = await migrate(historicCodec.decode(encoded));
+    if (migrated instanceof Result) {
+        if (migrated.isErr())
+            throw migrated.error;
+        return representation.codec.decode(representation.codec.encode(migrated.unwrapOrElse(() => {
+            throw new Error("Resource migration unexpectedly failed");
+        })));
+    }
+    return representation.codec.decode(representation.codec.encode(migrated));
+}
+async function decodeEntry(representation, migrations, entry) {
+    const base = {
+        key: decodeSubject(entry.key),
+        revision: revisionFromBackend(entry.revision),
+        timestamp: entry.created,
+    };
+    if (entry.operation === "DEL" || entry.operation === "PURGE") {
+        return Result.ok({ ...base, operation: "delete" });
+    }
+    const bytes = entry.value;
+    if (bytes.length < KV_ENVELOPE_HEADER_BYTES ||
+        KV_MAGIC.some((byte, index) => bytes[index] !== byte) ||
+        bytes[4] !== KV_ENVELOPE_FORMAT) {
+        return Result.err(validationError(entry, "Invalid TRKV envelope"));
+    }
+    try {
+        const value = await decodeResourceValue(representation, migrations, bytes);
+        return Result.ok({ ...base, operation: "put", value });
+    }
+    catch (cause) {
+        return Result.err(validationError(entry, "Failed to decode or migrate KV value", cause));
+    }
+}
+/** Typed access to a generated, versioned KV resource. */
+export class TypedKV {
+    representation;
+    kv;
+    migrations;
+    isCurrent;
+    constructor(representation, kv, migrations, isCurrent) {
+        this.representation = representation;
+        this.kv = kv;
+        this.migrations = migrations;
+        this.isCurrent = isCurrent;
+    }
+    /** Opens or creates a typed KV bucket. */
+    static open(nats, name, representation, options = {}) {
+        return AsyncResult.from((async () => {
+            try {
+                const kvm = new Kvm(nats);
+                const kv = options.bindOnly
+                    ? await kvm.open(name)
+                    : await kvm.create(name, {
+                        history: options.history ?? 1,
+                        ttl: options.ttl ?? 0,
+                        ...(options.replicas === undefined
+                            ? {}
+                            : { replicas: options.replicas }),
+                        ...(options.maxValueBytes === undefined
+                            ? {}
+                            : { maxValueSize: options.maxValueBytes }),
+                    });
+                await ensureExistingBucketOptions(kv, name, options);
+                return Result.ok(new TypedKV(representation, kv, options.migrations ?? {}, options.isCurrent ?? (() => true)));
+            }
+            catch (cause) {
+                return Result.err(kvError("open", undefined, cause));
+            }
+        })());
+    }
+    /** Returns the current value, or `undefined` when absent or deleted. */
+    get(key) {
+        return this.getEntry(key).map((entry) => entry?.operation === "put" ? entry.value : undefined);
+    }
+    /** Returns the latest value or tombstone with authoritative revision metadata. */
+    getEntry(key) {
+        return AsyncResult.from((async () => {
+            try {
+                this.#assertCurrent();
+                const entry = await this.kv.get(escapeKvKey(key));
+                return entry
+                    ? await decodeEntry(this.representation, this.migrations, entry)
+                    : Result.ok(undefined);
+            }
+            catch (cause) {
+                return Result.err(kvError("get", key, cause));
+            }
+        })());
+    }
+    /** Creates a value only when the key has no current value. */
+    create(key, value) {
+        return AsyncResult.from((async () => {
+            try {
+                this.#assertCurrent();
+                const revision = await this.kv.create(escapeKvKey(key), encodeResourceValue(this.representation, value));
+                return Result.ok({
+                    key,
+                    value,
+                    revision: revisionFromBackend(revision),
+                    timestamp: new Date(),
+                    operation: "put",
+                });
+            }
+            catch (cause) {
+                return Result.err(kvError("create", key, cause));
+            }
+        })());
+    }
+    /** Writes a value without a revision precondition. */
+    put(key, value) {
+        return AsyncResult.from((async () => {
+            try {
+                this.#assertCurrent();
+                const revision = await this.kv.put(escapeKvKey(key), encodeResourceValue(this.representation, value));
+                return Result.ok({
+                    key,
+                    value,
+                    revision: revisionFromBackend(revision),
+                    timestamp: new Date(),
+                    operation: "put",
+                });
+            }
+            catch (cause) {
+                return Result.err(kvError("put", key, cause));
+            }
+        })());
+    }
+    /** Replaces a value only when its current revision matches. */
+    replace(key, revision, value) {
+        return AsyncResult.from((async () => {
+            try {
+                this.#assertCurrent();
+                const nextRevision = await this.kv.update(escapeKvKey(key), encodeResourceValue(this.representation, value), revision);
+                return Result.ok({
+                    key,
+                    value,
+                    revision: revisionFromBackend(nextRevision),
+                    timestamp: new Date(),
+                    operation: "put",
+                });
+            }
+            catch (cause) {
+                return Result.err(kvError("replace", key, cause));
+            }
+        })());
+    }
+    /** Deletes a key, optionally requiring its current revision. */
+    delete(key, revision) {
+        return AsyncResult.from((async () => {
+            try {
+                this.#assertCurrent();
+                await this.kv.delete(escapeKvKey(key), revision === undefined ? {} : { previousSeq: revision });
+                return Result.ok(undefined);
+            }
+            catch (cause) {
+                return Result.err(kvError("delete", key, cause));
+            }
+        })());
+    }
+    /** Returns all retained revisions for a key, including tombstones. */
+    history(key) {
+        return AsyncResult.from((async () => {
+            try {
+                this.#assertCurrent();
+                const history = await this.kv.history({ key: escapeKvKey(key) });
+                const entries = [];
+                for await (const entry of history) {
+                    this.#assertCurrent();
+                    const decoded = await decodeEntry(this.representation, this.migrations, entry);
+                    if (decoded.isErr())
+                        return decoded;
+                    entries.push(decoded.unwrapOrElse(() => {
+                        throw new Error("KV history decode unexpectedly failed");
+                    }));
+                }
+                entries.sort((left, right) => left.revision - right.revision);
+                return Result.ok(entries);
+            }
+            catch (cause) {
+                return Result.err(kvError("history", key, cause));
+            }
+        })());
+    }
+    /** Watches retained initialization and subsequent revisions for one key. */
+    watch(key) {
+        return AsyncResult.from((async () => {
+            try {
+                this.#assertCurrent();
+                const watcher = await this.kv.watch({
+                    key: escapeKvKey(key),
+                    include: "history",
+                });
+                const representation = this.representation;
+                const migrations = this.migrations;
+                const isCurrent = this.isCurrent;
+                return Result.ok({
+                    async *[Symbol.asyncIterator]() {
+                        try {
+                            for await (const entry of watcher) {
+                                if (!isCurrent()) {
+                                    throw new Error("KV resource binding is stale");
+                                }
+                                yield await decodeEntry(representation, migrations, entry);
+                            }
+                        }
+                        finally {
+                            watcher.stop();
+                        }
+                    },
+                });
+            }
+            catch (cause) {
+                return Result.err(kvError("watch", key, cause));
+            }
+        })());
+    }
+    /** Lists live keys using the backend's bounded iterator. */
+    keys(filter = ">") {
+        return AsyncResult.from((async () => {
+            try {
+                this.#assertCurrent();
+                return Result.ok(await this.kv.keys(filter));
+            }
+            catch (cause) {
+                return Result.err(kvError("keys", undefined, cause));
+            }
+        })());
+    }
+    /** Returns the backend live-value count. */
+    status() {
+        return AsyncResult.from((async () => {
+            try {
+                this.#assertCurrent();
+                return Result.ok({ values: (await this.kv.status()).values });
+            }
+            catch (cause) {
+                return Result.err(kvError("status", undefined, cause));
+            }
+        })());
+    }
+    #assertCurrent() {
+        if (!this.isCurrent())
+            throw new Error("KV resource binding is stale");
+    }
+}

package/operations.d.ts

@@ -0,0 +1,189 @@
+import { AsyncResult, type Result } from "@oatscenter/result";
+import { type JsonValue } from "./codec.ts";
+import type { InferSchemaType } from "./participant.ts";
+import { OperationAlreadyTerminalError, OperationMismatchError, OperationNotFoundError, TransferError, TransportError, UnexpectedError } from "./errors/index.ts";
+import type { FileInfo, SendTransferGrant, TransferBody } from "./transfer.ts";
+export type OperationState = "pending" | "running" | "completed" | "failed" | "cancelled";
+export type OperationRefData = {
+    id: string;
+    service: string;
+    operation: string;
+};
+export type OperationSnapshot<TProgress = unknown, TOutput = unknown> = {
+    id: string;
+    service: string;
+    operation: string;
+    revision: number;
+    state: OperationState;
+    createdAt: string;
+    updatedAt: string;
+    completedAt?: string;
+    progress?: TProgress;
+    transfer?: OperationTransferProgress;
+    output?: TOutput;
+    error?: {
+        type: string;
+        message: string;
+    };
+};
+export type OperationTransferProgress = {
+    chunkIndex: number;
+    chunkBytes: number;
+    transferredBytes: number;
+};
+/** Errors returned when an operation control request violates lifecycle state. */
+export type OperationLifecycleError = OperationNotFoundError | OperationAlreadyTerminalError | OperationMismatchError;
+/** Errors returned when an operation control request fails before producing a snapshot or ack. */
+export type OperationControlError = TransportError | OperationLifecycleError;
+export type TerminalOperation<TProgress = unknown, TOutput = unknown> = (OperationSnapshot<TProgress, TOutput> & {
+    state: "completed";
+}) | (OperationSnapshot<TProgress, TOutput> & {
+    state: "failed";
+}) | (OperationSnapshot<TProgress, TOutput> & {
+    state: "cancelled";
+});
+export type OperationSignalAck<TProgress = unknown, TOutput = unknown> = {
+    kind: "signal-accepted";
+    operationId: string;
+    signal: string;
+    signalSequence: number;
+    acceptedAt: string;
+    snapshot: OperationSnapshot<TProgress, TOutput>;
+};
+export type CompletedTransfer<TDesc extends OperationShape, TProgress = OperationProgressOf<TDesc>, TOutput = OperationOutputOf<TDesc>> = {
+    transferred: FileInfo;
+    terminal: TerminalOperation<TProgress, TOutput>;
+};
+export type StartedTransfer<TDesc extends OperationShape, TProgress = OperationProgressOf<TDesc>, TOutput = OperationOutputOf<TDesc>, TUpdate = OperationUpdateOf<TDesc>> = {
+    operation: OperationRef<TDesc, TProgress, TOutput, TUpdate>;
+    wait(): AsyncResult<CompletedTransfer<TDesc, TProgress, TOutput>, OperationControlError | UnexpectedError | TransferError>;
+};
+export type OperationRef<TDesc extends OperationShape, TProgress = OperationProgressOf<TDesc>, TOutput = OperationOutputOf<TDesc>, TUpdate = OperationUpdateOf<TDesc>> = {
+    id: string;
+    service: string;
+    operation: string;
+    get(): AsyncResult<OperationSnapshot<TProgress, TOutput>, OperationControlError | UnexpectedError>;
+    wait(): AsyncResult<TerminalOperation<TProgress, TOutput>, OperationControlError | UnexpectedError>;
+    watch(options?: OperationWatchOptions): AsyncResult<AsyncIterable<OperationEvent<TProgress, TOutput, TUpdate>>, OperationControlError | UnexpectedError>;
+    cancel(): AsyncResult<OperationSnapshot<TProgress, TOutput>, OperationControlError | UnexpectedError>;
+    signal(signal: string, input?: unknown): AsyncResult<OperationSignalAck<TProgress, TOutput>, OperationControlError | UnexpectedError>;
+};
+/** Options controlling optional operation watch event classes. */
+export type OperationWatchOptions = {
+    /** Include transient typed update events. */
+    updates?: boolean;
+};
+/** Options that identify an idempotent operation invocation. */
+export type OperationStartOptions = {
+    invocationId?: string;
+};
+export type AcceptedOperationEvent<TProgress = unknown, TOutput = unknown> = {
+    type: "accepted";
+    snapshot: OperationSnapshot<TProgress, TOutput>;
+};
+export type StartedOperationEvent<TProgress = unknown, TOutput = unknown> = {
+    type: "started";
+    snapshot: OperationSnapshot<TProgress, TOutput>;
+};
+export type TransferOperationSnapshot<TProgress = unknown, TOutput = unknown> = OperationSnapshot<TProgress, TOutput> & {
+    transfer: OperationTransferProgress;
+};
+export type TransferOperationEvent<TProgress = unknown, TOutput = unknown> = {
+    type: "transfer";
+    snapshot: TransferOperationSnapshot<TProgress, TOutput>;
+    transfer: OperationTransferProgress;
+};
+export type ProgressOperationSnapshot<TProgress = unknown, TOutput = unknown> = OperationSnapshot<TProgress, TOutput> & {
+    progress: TProgress;
+};
+export type ProgressOperationEvent<TProgress = unknown, TOutput = unknown> = {
+    type: "progress";
+    snapshot: ProgressOperationSnapshot<TProgress, TOutput>;
+    progress: TProgress;
+};
+/** A transient operation update paired with the unchanged current snapshot. */
+export type UpdateOperationEvent<TProgress = unknown, TOutput = unknown, TUpdate = unknown> = {
+    type: "update";
+    update: TUpdate;
+    snapshot: OperationSnapshot<TProgress, TOutput>;
+};
+export type CompletedOperationEvent<TProgress = unknown, TOutput = unknown> = {
+    type: "completed";
+    snapshot: TerminalOperation<TProgress, TOutput>;
+};
+export type FailedOperationEvent<TProgress = unknown, TOutput = unknown> = {
+    type: "failed";
+    snapshot: TerminalOperation<TProgress, TOutput>;
+};
+export type CancelledOperationEvent<TProgress = unknown, TOutput = unknown> = {
+    type: "cancelled";
+    snapshot: TerminalOperation<TProgress, TOutput>;
+};
+export type OperationEvent<TProgress = unknown, TOutput = unknown, TUpdate = unknown> = AcceptedOperationEvent<TProgress, TOutput> | StartedOperationEvent<TProgress, TOutput> | TransferOperationEvent<TProgress, TOutput> | ProgressOperationEvent<TProgress, TOutput> | UpdateOperationEvent<TProgress, TOutput, TUpdate> | CompletedOperationEvent<TProgress, TOutput> | FailedOperationEvent<TProgress, TOutput> | CancelledOperationEvent<TProgress, TOutput>;
+export type OperationObserverCallbacks<TProgress = unknown, TOutput = unknown, TUpdate = unknown> = {
+    onAccepted?: (event: AcceptedOperationEvent<TProgress, TOutput>) => void | Promise<void>;
+    onStarted?: (event: StartedOperationEvent<TProgress, TOutput>) => void | Promise<void>;
+    onTransfer?: (event: TransferOperationEvent<TProgress, TOutput>) => void | Promise<void>;
+    onProgress?: (event: ProgressOperationEvent<TProgress, TOutput>) => void | Promise<void>;
+    onUpdate?: (event: UpdateOperationEvent<TProgress, TOutput, TUpdate>) => void | Promise<void>;
+    onCompleted?: (event: CompletedOperationEvent<TProgress, TOutput>) => void | Promise<void>;
+    onFailed?: (event: FailedOperationEvent<TProgress, TOutput>) => void | Promise<void>;
+    onCancelled?: (event: CancelledOperationEvent<TProgress, TOutput>) => void | Promise<void>;
+    onEvent?: (event: OperationEvent<TProgress, TOutput, TUpdate>) => void | Promise<void>;
+};
+interface OperationObserverBuilderBase<TBuilder, TProgress = unknown, TOutput = unknown, TUpdate = unknown> {
+    onAccepted(handler: NonNullable<OperationObserverCallbacks<TProgress, TOutput>["onAccepted"]>): TBuilder;
+    onStarted(handler: NonNullable<OperationObserverCallbacks<TProgress, TOutput>["onStarted"]>): TBuilder;
+    onProgress(handler: NonNullable<OperationObserverCallbacks<TProgress, TOutput>["onProgress"]>): TBuilder;
+    onUpdate(handler: NonNullable<OperationObserverCallbacks<TProgress, TOutput, TUpdate>["onUpdate"]>): TBuilder;
+    onCompleted(handler: NonNullable<OperationObserverCallbacks<TProgress, TOutput>["onCompleted"]>): TBuilder;
+    onFailed(handler: NonNullable<OperationObserverCallbacks<TProgress, TOutput>["onFailed"]>): TBuilder;
+    onCancelled(handler: NonNullable<OperationObserverCallbacks<TProgress, TOutput>["onCancelled"]>): TBuilder;
+    onEvent(handler: NonNullable<OperationObserverCallbacks<TProgress, TOutput, TUpdate>["onEvent"]>): TBuilder;
+}
+interface OperationInputBuilderBase<TDesc extends OperationShape, TProgress, TOutput, TUpdate, TBuilder> extends OperationObserverBuilderBase<TBuilder, TProgress, TOutput, TUpdate> {
+    start(callbacks?: OperationObserverCallbacks<TProgress, TOutput, TUpdate>, options?: OperationStartOptions): AsyncResult<OperationRef<TDesc, TProgress, TOutput, TUpdate>, OperationControlError | UnexpectedError>;
+}
+export interface TransferOperationBuilder<TDesc extends OperationShape, TProgress = OperationProgressOf<TDesc>, TOutput = OperationOutputOf<TDesc>, TUpdate = OperationUpdateOf<TDesc>> extends OperationObserverBuilderBase<TransferOperationBuilder<TDesc, TProgress, TOutput, TUpdate>, TProgress, TOutput, TUpdate> {
+    onTransfer(handler: NonNullable<OperationObserverCallbacks<TProgress, TOutput>["onTransfer"]>): TransferOperationBuilder<TDesc, TProgress, TOutput, TUpdate>;
+    start(callbacks?: OperationObserverCallbacks<TProgress, TOutput, TUpdate>, options?: OperationStartOptions): AsyncResult<StartedTransfer<TDesc, TProgress, TOutput, TUpdate>, OperationControlError | UnexpectedError | TransferError>;
+}
+export interface OperationInputBuilder<TDesc extends OperationShape, TProgress = OperationProgressOf<TDesc>, TOutput = OperationOutputOf<TDesc>, TUpdate = OperationUpdateOf<TDesc>> extends OperationInputBuilderBase<TDesc, TProgress, TOutput, TUpdate, OperationInputBuilder<TDesc, TProgress, TOutput, TUpdate>> {
+}
+export interface TransferCapableOperationInputBuilder<TDesc extends OperationShape, TProgress = OperationProgressOf<TDesc>, TOutput = OperationOutputOf<TDesc>, TUpdate = OperationUpdateOf<TDesc>> extends OperationInputBuilderBase<TDesc, TProgress, TOutput, TUpdate, TransferCapableOperationInputBuilder<TDesc, TProgress, TOutput, TUpdate>> {
+    transfer(body: TransferBody): TransferOperationBuilder<TDesc, TProgress, TOutput>;
+}
+type OperationShape = {
+    subject: string;
+    input: unknown;
+    progress?: unknown;
+    update?: unknown;
+    output?: unknown;
+    transfer?: {
+        store?: string;
+        key?: `/${string}`;
+        contentType?: `/${string}`;
+        metadata?: `/${string}`;
+        expiresInMs?: number;
+        maxBytes?: number;
+    };
+    cancel?: boolean;
+};
+type OperationInputOf<TDesc extends OperationShape> = InferSchemaType<TDesc["input"]>;
+type OperationProgressOf<TDesc extends OperationShape> = TDesc["progress"] extends undefined ? unknown : InferSchemaType<NonNullable<TDesc["progress"]>>;
+type OperationUpdateOf<TDesc extends OperationShape> = TDesc["update"] extends undefined ? unknown : InferSchemaType<NonNullable<TDesc["update"]>>;
+type OperationOutputOf<TDesc extends OperationShape> = TDesc["output"] extends undefined ? unknown : InferSchemaType<NonNullable<TDesc["output"]>>;
+export interface OperationTransport {
+    requestJson(subject: string, body: JsonValue): AsyncResult<JsonValue, TransportError | UnexpectedError>;
+    watchJson(subject: string, body: JsonValue): AsyncResult<AsyncIterable<Result<JsonValue, TransportError | UnexpectedError>>, TransportError | UnexpectedError>;
+    putTransfer(grant: SendTransferGrant, body: TransferBody): AsyncResult<FileInfo, TransferError>;
+}
+export declare function controlSubject(subject: string): string;
+export declare class OperationInvoker<TDesc extends OperationShape, TInput = OperationInputOf<TDesc>, TProgress = OperationProgressOf<TDesc>, TOutput = OperationOutputOf<TDesc>, TUpdate = OperationUpdateOf<TDesc>> {
+    #private;
+    constructor(transport: OperationTransport, descriptor: TDesc);
+    resume(ref: OperationRefData): OperationRef<TDesc, TProgress, TOutput, TUpdate>;
+    start(input: TInput, callbacks?: OperationObserverCallbacks<TProgress, TOutput, TUpdate>): AsyncResult<OperationRef<TDesc, TProgress, TOutput, TUpdate>, OperationControlError | UnexpectedError>;
+    input(input: TInput): TDesc["transfer"] extends undefined ? OperationInputBuilder<TDesc, TProgress, TOutput, TUpdate> : TransferCapableOperationInputBuilder<TDesc, TProgress, TOutput, TUpdate>;
+}
+export {};