@oatscenter/trellis 0.100.0-rc.1

package/participant_runtime/schemas.d.ts

@@ -0,0 +1,347 @@
+import Type, { type Static, type TArray, type TObject, type TSchema } from "typebox";
+export declare const ContractEventConsumersSchema: Type.TRecord<"^.*$", Type.TObject<{
+    uses: Type.TOptional<Type.TRecord<"^.*$", Type.TArray<Type.TString>>>;
+    self: Type.TOptional<Type.TArray<Type.TString>>;
+    replay: Type.TOptional<Type.TUnion<[Type.TLiteral<"new">, Type.TLiteral<"all">]>>;
+    concurrency: Type.TOptional<Type.TInteger>;
+}>>;
+export type ContractEventConsumers = Static<typeof ContractEventConsumersSchema>;
+export declare const KvResourceBindingSchema: Type.TObject<{
+    bucket: Type.TString;
+    history: Type.TInteger;
+    ttlMs: Type.TInteger;
+    maxValueBytes: Type.TOptional<Type.TInteger>;
+}>;
+export type KvResourceBinding = Static<typeof KvResourceBindingSchema>;
+export declare const StoreResourceBindingSchema: Type.TObject<{
+    name: Type.TString;
+    ttlMs: Type.TInteger;
+    maxObjectBytes: Type.TOptional<Type.TInteger>;
+    maxTotalBytes: Type.TOptional<Type.TInteger>;
+}>;
+export type StoreResourceBinding = Static<typeof StoreResourceBindingSchema>;
+export declare const JobsQueueKeyConcurrencyBindingSchema: Type.TObject<{
+    key: Type.TArray<Type.TString>;
+    maxActive: Type.TInteger;
+    heartbeatIntervalMs: Type.TInteger;
+    heartbeatTtlMs: Type.TInteger;
+    stalePolicy: Type.TUnion<[Type.TLiteral<"fail-stale">, Type.TLiteral<"block">]>;
+}>;
+export type JobsQueueKeyConcurrencyBinding = Static<typeof JobsQueueKeyConcurrencyBindingSchema>;
+export declare const JobsQueueDepthBindingSchema: Type.TObject<{
+    maxQueuedPerKey: Type.TInteger;
+    whenFull: Type.TUnion<[Type.TLiteral<"reject">, Type.TLiteral<"coalesce">, Type.TLiteral<"replace-oldest">]>;
+}>;
+export type JobsQueueDepthBinding = Static<typeof JobsQueueDepthBindingSchema>;
+export declare const JobsQueueBindingSchema: Type.TObject<{
+    queueType: Type.TString;
+    publishPrefix: Type.TString;
+    workSubject: Type.TString;
+    consumerName: Type.TString;
+    payload: Type.TObject<{
+        schema: Type.TString;
+    }>;
+    update: Type.TOptional<Type.TObject<{
+        schema: Type.TString;
+    }>>;
+    updatesPrefix: Type.TOptional<Type.TString>;
+    result: Type.TOptional<Type.TObject<{
+        schema: Type.TString;
+    }>>;
+    maxDeliver: Type.TInteger;
+    backoffMs: Type.TArray<Type.TInteger>;
+    ackWaitMs: Type.TInteger;
+    defaultDeadlineMs: Type.TOptional<Type.TInteger>;
+    keyConcurrency: Type.TOptional<Type.TObject<{
+        key: Type.TArray<Type.TString>;
+        maxActive: Type.TInteger;
+        heartbeatIntervalMs: Type.TInteger;
+        heartbeatTtlMs: Type.TInteger;
+        stalePolicy: Type.TUnion<[Type.TLiteral<"fail-stale">, Type.TLiteral<"block">]>;
+    }>>;
+    queue: Type.TOptional<Type.TObject<{
+        maxQueuedPerKey: Type.TInteger;
+        whenFull: Type.TUnion<[Type.TLiteral<"reject">, Type.TLiteral<"coalesce">, Type.TLiteral<"replace-oldest">]>;
+    }>>;
+}>;
+export type JobsQueueBinding = Static<typeof JobsQueueBindingSchema>;
+export declare const JobsResourceBindingSchema: Type.TObject<{
+    serviceName: Type.TString;
+    namespace: Type.TString;
+    workStream: Type.TOptional<Type.TString>;
+    queues: Type.TRecord<"^.*$", Type.TObject<{
+        queueType: Type.TString;
+        publishPrefix: Type.TString;
+        workSubject: Type.TString;
+        consumerName: Type.TString;
+        payload: Type.TObject<{
+            schema: Type.TString;
+        }>;
+        update: Type.TOptional<Type.TObject<{
+            schema: Type.TString;
+        }>>;
+        updatesPrefix: Type.TOptional<Type.TString>;
+        result: Type.TOptional<Type.TObject<{
+            schema: Type.TString;
+        }>>;
+        maxDeliver: Type.TInteger;
+        backoffMs: Type.TArray<Type.TInteger>;
+        ackWaitMs: Type.TInteger;
+        defaultDeadlineMs: Type.TOptional<Type.TInteger>;
+        keyConcurrency: Type.TOptional<Type.TObject<{
+            key: Type.TArray<Type.TString>;
+            maxActive: Type.TInteger;
+            heartbeatIntervalMs: Type.TInteger;
+            heartbeatTtlMs: Type.TInteger;
+            stalePolicy: Type.TUnion<[Type.TLiteral<"fail-stale">, Type.TLiteral<"block">]>;
+        }>>;
+        queue: Type.TOptional<Type.TObject<{
+            maxQueuedPerKey: Type.TInteger;
+            whenFull: Type.TUnion<[Type.TLiteral<"reject">, Type.TLiteral<"coalesce">, Type.TLiteral<"replace-oldest">]>;
+        }>>;
+    }>>;
+}>;
+export type JobsResourceBinding = Static<typeof JobsResourceBindingSchema>;
+export declare const EventConsumerResourceBindingSchema: Type.TObject<{
+    resourceId: Type.TString;
+    stream: Type.TString;
+    consumerName: Type.TString;
+    filterSubjects: Type.TArray<Type.TString>;
+    replay: Type.TUnion<[Type.TLiteral<"new">, Type.TLiteral<"all">]>;
+    concurrency: Type.TInteger;
+    ackWaitMs: Type.TInteger;
+    maxDeliver: Type.TInteger;
+    backoffMs: Type.TArray<Type.TInteger>;
+    replayBinding: Type.TObject<{
+        stream: Type.TString;
+        consumerName: Type.TString;
+    }>;
+}>;
+export type EventConsumerResourceBinding = Static<typeof EventConsumerResourceBindingSchema>;
+export declare const ContractResourceBindingsSchema: Type.TObject<{
+    kv: Type.TOptional<Type.TRecord<"^.*$", Type.TObject<{
+        bucket: Type.TString;
+        history: Type.TInteger;
+        ttlMs: Type.TInteger;
+        maxValueBytes: Type.TOptional<Type.TInteger>;
+    }>>>;
+    store: Type.TOptional<Type.TRecord<"^.*$", Type.TObject<{
+        name: Type.TString;
+        ttlMs: Type.TInteger;
+        maxObjectBytes: Type.TOptional<Type.TInteger>;
+        maxTotalBytes: Type.TOptional<Type.TInteger>;
+    }>>>;
+    jobs: Type.TOptional<Type.TObject<{
+        serviceName: Type.TString;
+        namespace: Type.TString;
+        workStream: Type.TOptional<Type.TString>;
+        queues: Type.TRecord<"^.*$", Type.TObject<{
+            queueType: Type.TString;
+            publishPrefix: Type.TString;
+            workSubject: Type.TString;
+            consumerName: Type.TString;
+            payload: Type.TObject<{
+                schema: Type.TString;
+            }>;
+            update: Type.TOptional<Type.TObject<{
+                schema: Type.TString;
+            }>>;
+            updatesPrefix: Type.TOptional<Type.TString>;
+            result: Type.TOptional<Type.TObject<{
+                schema: Type.TString;
+            }>>;
+            maxDeliver: Type.TInteger;
+            backoffMs: Type.TArray<Type.TInteger>;
+            ackWaitMs: Type.TInteger;
+            defaultDeadlineMs: Type.TOptional<Type.TInteger>;
+            keyConcurrency: Type.TOptional<Type.TObject<{
+                key: Type.TArray<Type.TString>;
+                maxActive: Type.TInteger;
+                heartbeatIntervalMs: Type.TInteger;
+                heartbeatTtlMs: Type.TInteger;
+                stalePolicy: Type.TUnion<[Type.TLiteral<"fail-stale">, Type.TLiteral<"block">]>;
+            }>>;
+            queue: Type.TOptional<Type.TObject<{
+                maxQueuedPerKey: Type.TInteger;
+                whenFull: Type.TUnion<[Type.TLiteral<"reject">, Type.TLiteral<"coalesce">, Type.TLiteral<"replace-oldest">]>;
+            }>>;
+        }>>;
+    }>>;
+    eventConsumers: Type.TOptional<Type.TRecord<"^.*$", Type.TObject<{
+        resourceId: Type.TString;
+        stream: Type.TString;
+        consumerName: Type.TString;
+        filterSubjects: Type.TArray<Type.TString>;
+        replay: Type.TUnion<[Type.TLiteral<"new">, Type.TLiteral<"all">]>;
+        concurrency: Type.TInteger;
+        ackWaitMs: Type.TInteger;
+        maxDeliver: Type.TInteger;
+        backoffMs: Type.TArray<Type.TInteger>;
+        replayBinding: Type.TObject<{
+            stream: Type.TString;
+            consumerName: Type.TString;
+        }>;
+    }>>>;
+}>;
+export type ContractResourceBindings = Static<typeof ContractResourceBindingsSchema>;
+export declare const InstalledGeneratedServiceParticipantSchema: Type.TObject<{
+    contractId: Type.TString;
+    digest: Type.TString;
+    resources: Type.TObject<{
+        kv: Type.TOptional<Type.TRecord<"^.*$", Type.TObject<{
+            bucket: Type.TString;
+            history: Type.TInteger;
+            ttlMs: Type.TInteger;
+            maxValueBytes: Type.TOptional<Type.TInteger>;
+        }>>>;
+        store: Type.TOptional<Type.TRecord<"^.*$", Type.TObject<{
+            name: Type.TString;
+            ttlMs: Type.TInteger;
+            maxObjectBytes: Type.TOptional<Type.TInteger>;
+            maxTotalBytes: Type.TOptional<Type.TInteger>;
+        }>>>;
+        jobs: Type.TOptional<Type.TObject<{
+            serviceName: Type.TString;
+            namespace: Type.TString;
+            workStream: Type.TOptional<Type.TString>;
+            queues: Type.TRecord<"^.*$", Type.TObject<{
+                queueType: Type.TString;
+                publishPrefix: Type.TString;
+                workSubject: Type.TString;
+                consumerName: Type.TString;
+                payload: Type.TObject<{
+                    schema: Type.TString;
+                }>;
+                update: Type.TOptional<Type.TObject<{
+                    schema: Type.TString;
+                }>>;
+                updatesPrefix: Type.TOptional<Type.TString>;
+                result: Type.TOptional<Type.TObject<{
+                    schema: Type.TString;
+                }>>;
+                maxDeliver: Type.TInteger;
+                backoffMs: Type.TArray<Type.TInteger>;
+                ackWaitMs: Type.TInteger;
+                defaultDeadlineMs: Type.TOptional<Type.TInteger>;
+                keyConcurrency: Type.TOptional<Type.TObject<{
+                    key: Type.TArray<Type.TString>;
+                    maxActive: Type.TInteger;
+                    heartbeatIntervalMs: Type.TInteger;
+                    heartbeatTtlMs: Type.TInteger;
+                    stalePolicy: Type.TUnion<[Type.TLiteral<"fail-stale">, Type.TLiteral<"block">]>;
+                }>>;
+                queue: Type.TOptional<Type.TObject<{
+                    maxQueuedPerKey: Type.TInteger;
+                    whenFull: Type.TUnion<[Type.TLiteral<"reject">, Type.TLiteral<"coalesce">, Type.TLiteral<"replace-oldest">]>;
+                }>>;
+            }>>;
+        }>>;
+        eventConsumers: Type.TOptional<Type.TRecord<"^.*$", Type.TObject<{
+            resourceId: Type.TString;
+            stream: Type.TString;
+            consumerName: Type.TString;
+            filterSubjects: Type.TArray<Type.TString>;
+            replay: Type.TUnion<[Type.TLiteral<"new">, Type.TLiteral<"all">]>;
+            concurrency: Type.TInteger;
+            ackWaitMs: Type.TInteger;
+            maxDeliver: Type.TInteger;
+            backoffMs: Type.TArray<Type.TInteger>;
+            replayBinding: Type.TObject<{
+                stream: Type.TString;
+                consumerName: Type.TString;
+            }>;
+        }>>>;
+    }>;
+}>;
+export type InstalledGeneratedServiceParticipant = Static<typeof InstalledGeneratedServiceParticipantSchema>;
+export declare const IsoDateSchema: Type.TCodec<Type.TString, Date>;
+/** Schema for a bounded pagination request. */
+export declare const PageRequestSchema: Type.TObject<{
+    offset: Type.TOptional<Type.TInteger>;
+    limit: Type.TInteger;
+}>;
+/** Bounded pagination request. */
+export type PageRequest = Static<typeof PageRequestSchema>;
+/** Create a schema for a bounded page response with typed entries. */
+export declare function PageResponseSchema<TEntry extends TSchema>(entry: TEntry): Type.TObject<{
+    entries: Type.TArray<TEntry>;
+    count: Type.TInteger;
+    offset: Type.TInteger;
+    limit: Type.TInteger;
+    nextOffset: Type.TOptional<Type.TInteger>;
+}>;
+/** Bounded pagination response with typed entries. */
+export type PageResponse<TEntry> = {
+    entries: TEntry[];
+    count: number;
+    offset: number;
+    limit: number;
+    nextOffset?: number;
+};
+/**
+ * Validates and normalizes an offset pagination query.
+ *
+ * Ensures `offset` and `limit` are non-negative integers within bounds. Throws
+ * `RangeError` on invalid input.
+ */
+export declare function normalizePageQuery(query: PageRequest, maxLimit?: number): Required<PageRequest>;
+/**
+ * Builds a {@link PageResponse} from a pre-sliced offset page.
+ *
+ * @param entries - The entries for the current page, already sliced by the caller.
+ * @param totalCount - Total number of matching entries before slicing.
+ * @param query - The original pagination query used to produce the page.
+ * @param maxLimit - Optional maximum limit accepted by the endpoint.
+ */
+export declare function buildPageResponse<T>(entries: T[], totalCount: number, query: PageRequest, maxLimit?: number): PageResponse<T>;
+/** Schema for a cursor pagination query. */
+export declare const CursorQuerySchema: Type.TObject<{
+    cursor: Type.TOptional<Type.TString>;
+    limit: Type.TOptional<Type.TInteger>;
+}>;
+/** Cursor pagination query. */
+export type CursorQuery = Static<typeof CursorQuerySchema>;
+/** Schema for cursor pagination response metadata. */
+export declare const CursorPageInfoSchema: Type.TObject<{
+    nextCursor: Type.TOptional<Type.TString>;
+}>;
+/** Cursor pagination response metadata. */
+export type CursorPageInfo = Static<typeof CursorPageInfoSchema>;
+/** TypeBox schema for a cursor page response with typed items. */
+export type CursorPageResponseSchema<TItem extends TSchema> = TObject<{
+    items: TArray<TItem>;
+    page: typeof CursorPageInfoSchema;
+}>;
+/** Create a schema for a cursor page response with typed items. */
+export declare function CursorPageSchema<TItem extends TSchema>(item: TItem): CursorPageResponseSchema<TItem>;
+/** Cursor pagination response with typed items. */
+export type CursorPage<TItem> = {
+    items: TItem[];
+    page: CursorPageInfo;
+};
+/** Options for normalizing a cursor pagination query. */
+export type CursorQueryOptions = {
+    /** Limit used when the query does not specify one. Defaults to `100`. */
+    defaultLimit?: number;
+    /** Service-owned maximum accepted limit, when one applies. */
+    maxLimit?: number;
+};
+/** Cursor query after defaults and validation have been applied. */
+export type NormalizedCursorQuery = {
+    cursor?: string;
+    limit: number;
+};
+/**
+ * Validates and normalizes a cursor pagination query.
+ *
+ * Defaults `limit` to `100`, applies an optional service-owned maximum, and
+ * preserves a non-empty optional cursor.
+ */
+export declare function normalizeCursorQuery(query: CursorQuery, options?: CursorQueryOptions): NormalizedCursorQuery;
+/**
+ * Builds a {@link CursorPage} from items and an optional next cursor.
+ *
+ * @param items - The items for the current page.
+ * @param nextCursor - Cursor clients can use to request the next page.
+ */
+export declare function buildCursorPage<T>(items: T[], nextCursor?: string): CursorPage<T>;

package/participant_runtime/schemas.js

@@ -0,0 +1,211 @@
+import Type, {} from "typebox";
+function parseIsoDate(value) {
+    const parsed = new Date(value);
+    if (Number.isNaN(parsed.getTime()) || parsed.toISOString() !== value) {
+        throw new TypeError(`Expected canonical ISO 8601 UTC date-time string, received '${value}'`);
+    }
+    return parsed;
+}
+function formatIsoDate(value) {
+    if (!(value instanceof Date) || Number.isNaN(value.getTime())) {
+        throw new TypeError("Expected a valid Date instance");
+    }
+    return value.toISOString();
+}
+const ContractSchemaRefSchema = Type.Object({
+    schema: Type.String({ minLength: 1 }),
+});
+export const ContractEventConsumersSchema = Type.Record(Type.String({ minLength: 1 }), Type.Object({
+    uses: Type.Optional(Type.Record(Type.String({ minLength: 1 }), Type.Array(Type.String({ minLength: 1 }), { minItems: 1 }))),
+    self: Type.Optional(Type.Array(Type.String({ minLength: 1 }))),
+    replay: Type.Optional(Type.Union([
+        Type.Literal("new"),
+        Type.Literal("all"),
+    ])),
+    concurrency: Type.Optional(Type.Integer({ minimum: 1 })),
+}));
+export const KvResourceBindingSchema = Type.Object({
+    bucket: Type.String({ minLength: 1 }),
+    history: Type.Integer({ minimum: 1 }),
+    ttlMs: Type.Integer({ minimum: 0 }),
+    maxValueBytes: Type.Optional(Type.Integer({ minimum: 1 })),
+});
+export const StoreResourceBindingSchema = Type.Object({
+    name: Type.String({ minLength: 1 }),
+    ttlMs: Type.Integer({ minimum: 0 }),
+    maxObjectBytes: Type.Optional(Type.Integer({ minimum: 1 })),
+    maxTotalBytes: Type.Optional(Type.Integer({ minimum: 1 })),
+});
+export const JobsQueueKeyConcurrencyBindingSchema = Type.Object({
+    key: Type.Array(Type.String({ minLength: 1 }), { minItems: 1 }),
+    maxActive: Type.Integer({ minimum: 1 }),
+    heartbeatIntervalMs: Type.Integer({ minimum: 1 }),
+    heartbeatTtlMs: Type.Integer({ minimum: 1 }),
+    stalePolicy: Type.Union([
+        Type.Literal("fail-stale"),
+        Type.Literal("block"),
+    ]),
+});
+export const JobsQueueDepthBindingSchema = Type.Object({
+    maxQueuedPerKey: Type.Integer({ minimum: 0 }),
+    whenFull: Type.Union([
+        Type.Literal("reject"),
+        Type.Literal("coalesce"),
+        Type.Literal("replace-oldest"),
+    ]),
+});
+export const JobsQueueBindingSchema = Type.Object({
+    queueType: Type.String({ minLength: 1 }),
+    publishPrefix: Type.String({ minLength: 1 }),
+    workSubject: Type.String({ minLength: 1 }),
+    consumerName: Type.String({ minLength: 1 }),
+    payload: ContractSchemaRefSchema,
+    update: Type.Optional(ContractSchemaRefSchema),
+    updatesPrefix: Type.Optional(Type.String({ minLength: 1 })),
+    result: Type.Optional(ContractSchemaRefSchema),
+    maxDeliver: Type.Integer({ minimum: 1 }),
+    backoffMs: Type.Array(Type.Integer({ minimum: 0 })),
+    ackWaitMs: Type.Integer({ minimum: 1 }),
+    defaultDeadlineMs: Type.Optional(Type.Integer({ minimum: 1 })),
+    keyConcurrency: Type.Optional(JobsQueueKeyConcurrencyBindingSchema),
+    queue: Type.Optional(JobsQueueDepthBindingSchema),
+});
+export const JobsResourceBindingSchema = Type.Object({
+    serviceName: Type.String({ minLength: 1 }),
+    namespace: Type.String({ minLength: 1 }),
+    workStream: Type.Optional(Type.String({ minLength: 1 })),
+    queues: Type.Record(Type.String({ minLength: 1 }), JobsQueueBindingSchema),
+});
+export const EventConsumerResourceBindingSchema = Type.Object({
+    resourceId: Type.String({ minLength: 1 }),
+    stream: Type.String({ minLength: 1 }),
+    consumerName: Type.String({ minLength: 1 }),
+    filterSubjects: Type.Array(Type.String({ minLength: 1 })),
+    replay: Type.Union([Type.Literal("new"), Type.Literal("all")]),
+    concurrency: Type.Integer({ minimum: 1 }),
+    ackWaitMs: Type.Integer({ minimum: 1 }),
+    maxDeliver: Type.Integer({ minimum: 1 }),
+    backoffMs: Type.Array(Type.Integer({ minimum: 0 })),
+    replayBinding: Type.Object({
+        stream: Type.String({ minLength: 1 }),
+        consumerName: Type.String({ minLength: 1 }),
+    }),
+});
+export const ContractResourceBindingsSchema = Type.Object({
+    kv: Type.Optional(Type.Record(Type.String({ minLength: 1 }), KvResourceBindingSchema)),
+    store: Type.Optional(Type.Record(Type.String({ minLength: 1 }), StoreResourceBindingSchema)),
+    jobs: Type.Optional(JobsResourceBindingSchema),
+    eventConsumers: Type.Optional(Type.Record(Type.String({ minLength: 1 }), EventConsumerResourceBindingSchema)),
+});
+export const InstalledGeneratedServiceParticipantSchema = Type.Object({
+    contractId: Type.String({ minLength: 1 }),
+    digest: Type.String({ pattern: "^[A-Za-z0-9_-]+$" }),
+    resources: ContractResourceBindingsSchema,
+});
+export const IsoDateSchema = Type.Codec(Type.String({ format: "date-time" }))
+    .Decode((value) => parseIsoDate(value))
+    .Encode((value) => formatIsoDate(value));
+/** Schema for a bounded pagination request. */
+export const PageRequestSchema = Type.Object({
+    offset: Type.Optional(Type.Integer({ minimum: 0 })),
+    limit: Type.Integer({ minimum: 0 }),
+});
+/** Create a schema for a bounded page response with typed entries. */
+export function PageResponseSchema(entry) {
+    return Type.Object({
+        entries: Type.Array(entry, { default: [] }),
+        count: Type.Integer({ minimum: 0 }),
+        offset: Type.Integer({ minimum: 0 }),
+        limit: Type.Integer({ minimum: 0 }),
+        nextOffset: Type.Optional(Type.Integer({ minimum: 0 })),
+    });
+}
+/**
+ * Validates and normalizes an offset pagination query.
+ *
+ * Ensures `offset` and `limit` are non-negative integers within bounds. Throws
+ * `RangeError` on invalid input.
+ */
+export function normalizePageQuery(query, maxLimit = Number.MAX_SAFE_INTEGER) {
+    if (!Number.isInteger(query.limit) || query.limit < 0) {
+        throw new RangeError("list limit must be a non-negative integer");
+    }
+    if (query.limit > maxLimit) {
+        throw new RangeError(`list limit must be <= ${maxLimit}`);
+    }
+    const offset = query.offset ?? 0;
+    if (!Number.isInteger(offset) || offset < 0) {
+        throw new RangeError("list offset must be a non-negative integer");
+    }
+    return { offset, limit: query.limit };
+}
+/**
+ * Builds a {@link PageResponse} from a pre-sliced offset page.
+ *
+ * @param entries - The entries for the current page, already sliced by the caller.
+ * @param totalCount - Total number of matching entries before slicing.
+ * @param query - The original pagination query used to produce the page.
+ * @param maxLimit - Optional maximum limit accepted by the endpoint.
+ */
+export function buildPageResponse(entries, totalCount, query, maxLimit) {
+    const { offset, limit } = normalizePageQuery(query, maxLimit);
+    return {
+        entries,
+        count: totalCount,
+        offset,
+        limit,
+        nextOffset: limit <= 0 || offset + limit >= totalCount
+            ? undefined
+            : offset + limit,
+    };
+}
+/** Schema for a cursor pagination query. */
+export const CursorQuerySchema = Type.Object({
+    cursor: Type.Optional(Type.String({ minLength: 1 })),
+    limit: Type.Optional(Type.Integer({ minimum: 1 })),
+});
+/** Schema for cursor pagination response metadata. */
+export const CursorPageInfoSchema = Type.Object({
+    nextCursor: Type.Optional(Type.String({ minLength: 1 })),
+});
+/** Create a schema for a cursor page response with typed items. */
+export function CursorPageSchema(item) {
+    return Type.Object({
+        items: Type.Array(item, { default: [] }),
+        page: CursorPageInfoSchema,
+    });
+}
+/**
+ * Validates and normalizes a cursor pagination query.
+ *
+ * Defaults `limit` to `100`, applies an optional service-owned maximum, and
+ * preserves a non-empty optional cursor.
+ */
+export function normalizeCursorQuery(query, options = {}) {
+    const limit = query.limit ?? options.defaultLimit ?? 100;
+    if (!Number.isFinite(limit) || !Number.isInteger(limit) || limit <= 0) {
+        throw new RangeError("list limit must be a positive finite integer");
+    }
+    if (options.maxLimit !== undefined && limit > options.maxLimit) {
+        throw new RangeError(`list limit must be <= ${options.maxLimit}`);
+    }
+    if (query.cursor === undefined) {
+        return { limit };
+    }
+    if (query.cursor.length === 0) {
+        throw new RangeError("list cursor must be a non-empty string");
+    }
+    return { cursor: query.cursor, limit };
+}
+/**
+ * Builds a {@link CursorPage} from items and an optional next cursor.
+ *
+ * @param items - The items for the current page.
+ * @param nextCursor - Cursor clients can use to request the next page.
+ */
+export function buildCursorPage(items, nextCursor) {
+    return {
+        items,
+        page: nextCursor === undefined ? {} : { nextCursor },
+    };
+}

package/participant_runtime/surface_names.d.ts

@@ -0,0 +1,16 @@
+type Digit = "0" | "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9";
+type CharacterKind = "upper" | "lower" | "digit" | "separator";
+type KindOf<TChar extends string> = TChar extends Digit ? "digit" : TChar extends Lowercase<TChar> ? TChar extends Uppercase<TChar> ? "separator" : "lower" : "upper";
+type FirstKind<TValue extends string> = TValue extends `${infer TChar}${infer _Rest}` ? KindOf<TChar> : "separator";
+type AppendSeparator<TValue extends string> = TValue extends "" ? "" : TValue extends `${string}_` ? TValue : `${TValue}_`;
+type SnakeSurfaceName<TValue extends string, TPrevious extends CharacterKind = "separator", TOutput extends string = ""> = TValue extends `${infer TChar}${infer TRest}` ? KindOf<TChar> extends infer TKind extends CharacterKind ? TKind extends "separator" ? SnakeSurfaceName<TRest, "separator", AppendSeparator<TOutput>> : TKind extends "upper" ? SnakeSurfaceName<TRest, "upper", `${TOutput}${TOutput extends "" ? "" : TPrevious extends "separator" ? "" : TPrevious extends "lower" | "digit" ? "_" : FirstKind<TRest> extends "lower" ? "_" : ""}${Lowercase<TChar>}`> : SnakeSurfaceName<TRest, TKind, `${TOutput}${TChar}`> : never : TOutput extends `${infer TTrimmed}_` ? TTrimmed : TOutput;
+type PascalFromSnake<TValue extends string> = TValue extends `${infer THead}_${infer TTail}` ? `${Capitalize<THead>}${PascalFromSnake<TTail>}` : Capitalize<TValue>;
+/** The deterministic PascalCase identifier for a canonical surface name. */
+export type PascalActionName<TName extends string> = PascalFromSnake<SnakeSurfaceName<TName>>;
+/** The deterministic lowerCamelCase identifier for a canonical surface name. */
+export type ConnectedActionName<TName extends string> = Uncapitalize<PascalActionName<TName>>;
+/** Converts a canonical surface name to its acronym-aware PascalCase identifier. */
+export declare function pascalSurfaceName(value: string): string;
+/** Converts a canonical surface name to its acronym-aware lowerCamelCase identifier. */
+export declare function lowerCamelSurfaceName(value: string): string;
+export {};

package/participant_runtime/surface_names.js

@@ -0,0 +1,34 @@
+function snakeSurfaceName(value) {
+    const chars = [...value];
+    let output = "";
+    let previousWasSeparator = false;
+    for (let index = 0; index < chars.length; index++) {
+        const char = chars[index];
+        if (/^[A-Za-z0-9]$/.test(char)) {
+            const previous = chars[index - 1];
+            const next = chars[index + 1];
+            const startsNewWord = /^[A-Z]$/.test(char) && output !== "" &&
+                !previousWasSeparator &&
+                (previous !== undefined && /^[a-z0-9]$/.test(previous) ||
+                    next !== undefined && /^[a-z]$/.test(next));
+            if (startsNewWord)
+                output += "_";
+            output += char.toLowerCase();
+            previousWasSeparator = false;
+        }
+        else if (output !== "" && !previousWasSeparator) {
+            output += "_";
+            previousWasSeparator = true;
+        }
+    }
+    return output.replace(/_$/, "");
+}
+/** Converts a canonical surface name to its acronym-aware PascalCase identifier. */
+export function pascalSurfaceName(value) {
+    return snakeSurfaceName(value).split("_").filter(Boolean).map((word) => word[0].toUpperCase() + word.slice(1)).join("");
+}
+/** Converts a canonical surface name to its acronym-aware lowerCamelCase identifier. */
+export function lowerCamelSurfaceName(value) {
+    const pascal = pascalSurfaceName(value);
+    return pascal[0] ? pascal[0].toLowerCase() + pascal.slice(1) : "";
+}

package/portable.d.ts

@@ -0,0 +1,30 @@
+/** Shared portable application API for native and browser entrypoints. */
+export { classifyBrowserAuthError, createAuth, isRecoverableBrowserAuthError, } from "./auth.ts";
+export type { BrowserAuthRecoveryClassification, BrowserAuthRecoveryKind, NatsConnectOptions, } from "./auth.ts";
+export { isJsonValue } from "./participant.ts";
+export type { InferSchemaType, JsonValue } from "./participant.ts";
+export { TrellisConnection } from "./connection.ts";
+export type { TrellisConnectionStatus } from "./connection.ts";
+export { buildCursorPage, buildPageResponse, CursorPageInfoSchema, CursorPageSchema, CursorQuerySchema, normalizeCursorQuery, normalizePageQuery, PageRequestSchema, PageResponseSchema, } from "./participant.ts";
+export type { CursorPage, CursorPageInfo, CursorPageResponseSchema, CursorQuery, CursorQueryOptions, InferRuntimeRpcError, NormalizedCursorQuery, PageRequest, PageResponse, RpcErrorClass, RuntimeRpcErrorDesc, SerializableErrorData, TrellisValidationExtension, TrellisValidationIssueHint, } from "./participant.ts";
+export { AsyncResult, BaseError, err, isErr, isOk, ok, Result, } from "@oatscenter/result";
+export type { MaybeAsync } from "@oatscenter/result";
+export type { ClientOpts } from "./client.ts";
+export type { CallerParticipant, CallerRuntime } from "./caller.ts";
+export { PaginationError } from "./pagination.ts";
+export { decodePaginationCursor, encodePaginationCursor, paginationQueryDigest, } from "./auth/protocol_wasm.ts";
+export type { PaginationErrorData } from "./pagination.ts";
+export type { ClientAuthContinuation, ClientAuthOptions, ClientAuthRequiredContext, ClientResourceMigrations, ConnectedTrellisClient, TrellisClientConnectArgs, } from "./client_connect.ts";
+export { ClientAuthHandledError, TrellisClient } from "./client_connect.ts";
+export type { KvWatchItem, ResourceRevision, TypedKvEntry } from "./kv.ts";
+export type { TrellisErrorInstance } from "./errors/index.ts";
+export { AuthError, KVError, OperationAlreadyTerminalError, OperationMismatchError, OperationNotFoundError, RemoteError, StoreError, TransferError, TransportError, TrellisError, UnexpectedError, ValidationError, } from "./errors/index.ts";
+export { TypedStoreEntry } from "./store_entry.ts";
+export type { StoreBody, StoreInfo, StoreListOptions, StoreListPage, StoreOpenOptions, StorePutOptions, StoreStatus, StoreWaitOptions, } from "./store.ts";
+export { FileInfoSchema, TransferGrantSchema } from "./transfer.ts";
+export type { FileInfo, ReceiveTransferGrant, ReceiveTransferHandle, SendTransferGrant, SendTransferHandle, TransferBody, TransferGrant, } from "./transfer.ts";
+export type { AcceptedOperationEvent, CancelledOperationEvent, CompletedOperationEvent, CompletedTransfer, FailedOperationEvent, OperationControlError, OperationEvent, OperationInputBuilder, OperationLifecycleError, OperationObserverCallbacks, OperationRef, OperationRefData, OperationSignalAck, OperationSnapshot, OperationStartOptions, OperationState, OperationTransferProgress, OperationWatchOptions, ProgressOperationEvent, ProgressOperationSnapshot, StartedOperationEvent, StartedTransfer, TerminalOperation, TransferCapableOperationInputBuilder, TransferOperationBuilder, TransferOperationEvent, TransferOperationSnapshot, UpdateOperationEvent, } from "./operations.ts";
+export { controlSubject, OperationInvoker } from "./operations.ts";
+export type { AcceptedOperation, EventListenerContext, EventName, EventOpts, EventPayload, EventType, FeedInputBuilder, FeedSubscribeOpts, FeedSubscription, HandlerJobQueue, HandlerJobsFacade, HandlerKvFacade, HandlerStoreHandle, HandlerTrellis, HandlerTrellisForContract, InternalCaller, OperationHandlerContext, OperationHandlerErrorOf, OperationRegistration, OperationRuntimeHandle, OperationTransferContextOf, OperationTransferHandle, OperationUpdateOf, PreparedTrellisEvent, RequestOpts, RpcHandlerContext, RpcInputOf, RpcMethodNameOf, RpcOutputOf, RpcRequestErrorOf, RuntimeStateStoresForContract, RuntimeStateStoreShape, SessionCaller, StateFacade, TrellisEventHeader, TrellisEventMessage, ValueStateStoreClient, VerifiedCaller, } from "./session.ts";
+export { ResourceUnavailableError, StateConflictError } from "./session.ts";
+export type { TrellisAuth } from "./session.ts";

package/portable.js

@@ -0,0 +1,14 @@
+/** Shared portable application API for native and browser entrypoints. */
+export { classifyBrowserAuthError, createAuth, isRecoverableBrowserAuthError, } from "./auth.js";
+export { isJsonValue } from "./participant.js";
+export { TrellisConnection } from "./connection.js";
+export { buildCursorPage, buildPageResponse, CursorPageInfoSchema, CursorPageSchema, CursorQuerySchema, normalizeCursorQuery, normalizePageQuery, PageRequestSchema, PageResponseSchema, } from "./participant.js";
+export { AsyncResult, BaseError, err, isErr, isOk, ok, Result, } from "@oatscenter/result";
+export { PaginationError } from "./pagination.js";
+export { decodePaginationCursor, encodePaginationCursor, paginationQueryDigest, } from "./auth/protocol_wasm.js";
+export { ClientAuthHandledError, TrellisClient } from "./client_connect.js";
+export { AuthError, KVError, OperationAlreadyTerminalError, OperationMismatchError, OperationNotFoundError, RemoteError, StoreError, TransferError, TransportError, TrellisError, UnexpectedError, ValidationError, } from "./errors/index.js";
+export { TypedStoreEntry } from "./store_entry.js";
+export { FileInfoSchema, TransferGrantSchema } from "./transfer.js";
+export { controlSubject, OperationInvoker } from "./operations.js";
+export { ResourceUnavailableError, StateConflictError } from "./session.js";