@oatscenter/trellis 0.100.0-rc.1

package/errors/index.js

@@ -0,0 +1,238 @@
+import { UnexpectedError, UnexpectedErrorDataSchema, } from "@oatscenter/result";
+import { AuthError } from "./AuthError.js";
+import { AuthErrorDataSchema } from "./AuthError.js";
+import { ValidationError } from "./ValidationError.js";
+import { ValidationErrorDataSchema } from "./ValidationError.js";
+import { SchemaValidationError } from "./SchemaValidationError.js";
+import { SchemaValidationErrorDataSchema, SchemaValidationIssueSchema, } from "./SchemaValidationError.js";
+import { RemoteError } from "./RemoteError.js";
+import { KVError } from "./KVError.js";
+import { KVErrorDataSchema } from "./KVError.js";
+import { OperationAlreadyTerminalError, OperationAlreadyTerminalErrorDataSchema, OperationMismatchError, OperationMismatchErrorDataSchema, OperationNotFoundError, OperationNotFoundErrorDataSchema, } from "./OperationLifecycleError.js";
+import { StoreError } from "./StoreError.js";
+import { StoreErrorDataSchema } from "./StoreError.js";
+import { TransportError } from "./TransportError.js";
+import { TransportErrorDataSchema } from "./TransportError.js";
+import { TransferError } from "./TransferError.js";
+import { TransferErrorDataSchema } from "./TransferError.js";
+export { UnexpectedError } from "@oatscenter/result";
+export { TrellisError } from "./TrellisError.js";
+export { AuthError } from "./AuthError.js";
+export { ValidationError } from "./ValidationError.js";
+export { SchemaValidationError } from "./SchemaValidationError.js";
+export { RemoteError } from "./RemoteError.js";
+export { KVError } from "./KVError.js";
+export { OperationAlreadyTerminalError, OperationMismatchError, OperationNotFoundError, } from "./OperationLifecycleError.js";
+export { StoreError } from "./StoreError.js";
+export { TransportError } from "./TransportError.js";
+export { TransferError } from "./TransferError.js";
+export { AuthErrorDataSchema } from "./AuthError.js";
+export { ValidationErrorDataSchema, ValidationIssueSchema, } from "./ValidationError.js";
+export { SchemaValidationErrorDataSchema, SchemaValidationIssueSchema, } from "./SchemaValidationError.js";
+export { RemoteErrorDataSchema } from "./RemoteError.js";
+export { KVErrorDataSchema } from "./KVError.js";
+export { OperationAlreadyTerminalErrorDataSchema, OperationMismatchErrorDataSchema, OperationNotFoundErrorDataSchema, } from "./OperationLifecycleError.js";
+export { StoreErrorDataSchema } from "./StoreError.js";
+export { TransportErrorDataSchema, } from "./TransportError.js";
+export { TransferErrorDataSchema, } from "./TransferError.js";
+/**
+ * Single source of truth for all Trellis errors.
+ * This object is used for compile-time type inference.
+ */
+const TRANSPORTABLE_TRELLIS_ERRORS = {
+    UnexpectedError,
+    TransportError,
+    AuthError,
+    ValidationError,
+    SchemaValidationError,
+    KVError,
+    OperationNotFoundError,
+    OperationAlreadyTerminalError,
+    OperationMismatchError,
+    StoreError,
+    TransferError,
+};
+const TRELLIS_ERRORS = {
+    ...TRANSPORTABLE_TRELLIS_ERRORS,
+    RemoteError,
+};
+export const BUILTIN_RPC_ERRORS = {
+    UnexpectedError: {
+        type: "UnexpectedError",
+        schema: UnexpectedErrorDataSchema,
+        fromSerializable(data) {
+            return new UnexpectedError({
+                id: data.id,
+                context: data.context,
+                traceId: data.traceId,
+            });
+        },
+    },
+    AuthError: {
+        type: "AuthError",
+        schema: AuthErrorDataSchema,
+        fromSerializable(data) {
+            return new AuthError({
+                reason: data.reason,
+                message: data.message,
+                id: data.id,
+                context: data.context,
+            });
+        },
+    },
+    TransportError: {
+        type: "TransportError",
+        schema: TransportErrorDataSchema,
+        fromSerializable(data) {
+            return new TransportError({
+                code: data.code,
+                message: data.message,
+                hint: data.hint,
+                id: data.id,
+                context: data.context,
+                traceId: data.traceId,
+            });
+        },
+    },
+    ValidationError: {
+        type: "ValidationError",
+        schema: ValidationErrorDataSchema,
+        fromSerializable(data) {
+            return new ValidationError({
+                errors: data.issues.map((issue) => ({
+                    path: issue.path,
+                    message: issue.message,
+                })),
+                id: data.id,
+                context: data.context,
+            });
+        },
+    },
+    SchemaValidationError: {
+        type: "SchemaValidationError",
+        schema: SchemaValidationErrorDataSchema,
+        fromSerializable(data) {
+            return new SchemaValidationError({
+                issues: data.issues,
+                id: data.id,
+                context: data.context,
+            });
+        },
+    },
+    KVError: {
+        type: "KVError",
+        schema: KVErrorDataSchema,
+        fromSerializable(data) {
+            return new KVError({
+                operation: data.operation,
+                id: data.id,
+                context: data.context,
+            });
+        },
+    },
+    OperationNotFoundError: {
+        type: "OperationNotFoundError",
+        schema: OperationNotFoundErrorDataSchema,
+        fromSerializable(data) {
+            return new OperationNotFoundError({
+                operationId: data.operationId,
+                message: data.message,
+                id: data.id,
+                context: data.context,
+                traceId: data.traceId,
+            });
+        },
+    },
+    OperationAlreadyTerminalError: {
+        type: "OperationAlreadyTerminalError",
+        schema: OperationAlreadyTerminalErrorDataSchema,
+        fromSerializable(data) {
+            return new OperationAlreadyTerminalError({
+                operationId: data.operationId,
+                state: data.state,
+                operation: data.operation,
+                service: data.service,
+                message: data.message,
+                id: data.id,
+                context: data.context,
+                traceId: data.traceId,
+            });
+        },
+    },
+    OperationMismatchError: {
+        type: "OperationMismatchError",
+        schema: OperationMismatchErrorDataSchema,
+        fromSerializable(data) {
+            return new OperationMismatchError({
+                operationId: data.operationId,
+                expectedService: data.expectedService,
+                expectedOperation: data.expectedOperation,
+                actualService: data.actualService,
+                actualOperation: data.actualOperation,
+                message: data.message,
+                id: data.id,
+                context: data.context,
+                traceId: data.traceId,
+            });
+        },
+    },
+    StoreError: {
+        type: "StoreError",
+        schema: StoreErrorDataSchema,
+        fromSerializable(data) {
+            return new StoreError({
+                operation: data.operation,
+                id: data.id,
+                context: data.context,
+            });
+        },
+    },
+    TransferError: {
+        type: "TransferError",
+        schema: TransferErrorDataSchema,
+        fromSerializable(data) {
+            return new TransferError({
+                operation: data.operation,
+                id: data.id,
+                context: data.context,
+            });
+        },
+    },
+};
+export function getBuiltinRpcError(type) {
+    return BUILTIN_RPC_ERRORS[type];
+}
+/**
+ * Reads the machine-readable failure code from any Trellis error shape.
+ *
+ * Declared RPC errors reconstruct into generated error classes that carry the
+ * code under `data`, built-in errors carry `reason`, and undecoded remote
+ * failures carry it under `remoteError`. Callers that must branch on a specific
+ * server code use this instead of matching one historical shape.
+ */
+export function machineErrorCode(error) {
+    if (!error || typeof error !== "object")
+        return undefined;
+    const record = error;
+    if (typeof record.code === "string")
+        return record.code;
+    if (typeof record.reason === "string")
+        return record.reason;
+    const data = record.data;
+    if (data && typeof data === "object") {
+        const dataRecord = data;
+        if (typeof dataRecord.code === "string")
+            return dataRecord.code;
+        if (typeof dataRecord.reason === "string")
+            return dataRecord.reason;
+    }
+    const remote = record.remoteError;
+    if (remote && typeof remote === "object") {
+        const remoteRecord = remote;
+        if (typeof remoteRecord.code === "string")
+            return remoteRecord.code;
+        if (typeof remoteRecord.reason === "string")
+            return remoteRecord.reason;
+    }
+    return undefined;
+}

package/generated.d.ts

@@ -0,0 +1,4 @@
+/** Portable runtime support for generated Trellis packages. */
+export { TrellisError } from "./errors/TrellisError.ts";
+export { apiDescriptor, type Codec, codecs, participantDescriptor, type SerializableErrorData, } from "./generated_support.ts";
+export type { ParticipantJobsFromResources, ParticipantKvFromResources, RuntimeApiFromGenerated, } from "./participant_runtime/participant.ts";

package/generated.js

@@ -0,0 +1,3 @@
+/** Portable runtime support for generated Trellis packages. */
+export { TrellisError } from "./errors/TrellisError.js";
+export { apiDescriptor, codecs, participantDescriptor, } from "./generated_support.js";

package/generated_support.d.ts

@@ -0,0 +1,120 @@
+/** A runtime codec emitted and composed by generated Trellis packages. */
+export type Codec<T> = Readonly<{
+    decode(value: unknown): T;
+    encode(value: T): unknown;
+}>;
+/** Serializable fields shared by generated declared errors. */
+export type SerializableErrorData = {
+    id: string;
+    type: string;
+    message: string;
+    context?: Record<string, unknown>;
+    traceId?: string;
+} & Record<string, unknown>;
+type CodecValue<C> = C extends {
+    decode(value: unknown): infer T;
+} ? T : never;
+type OpenEnum<T extends string> = T | (string & {
+    readonly __openEnum?: never;
+});
+type Timestamp = string & {
+    readonly __timestamp: unique symbol;
+};
+type Ulid = string & {
+    readonly __ulid: unique symbol;
+};
+type OptionalCodec<T> = Codec<T | undefined> & Readonly<{
+    optional: true;
+}>;
+type ModelField = Codec<unknown> | OptionalCodec<unknown>;
+type ModelValue<F extends Readonly<Record<string, ModelField>>> = {
+    [K in keyof F as F[K] extends OptionalCodec<unknown> ? never : K]: CodecValue<F[K]>;
+} & {
+    [K in keyof F as F[K] extends OptionalCodec<unknown> ? K : never]?: Exclude<CodecValue<F[K]>, undefined>;
+};
+/** Browser-safe codec vocabulary consumed by generated TypeScript packages. */
+export declare const codecs: Readonly<{
+    string: Readonly<{
+        decode(value: unknown): string;
+        encode(value: string): unknown;
+    }>;
+    bool: Readonly<{
+        decode(value: unknown): boolean;
+        encode(value: boolean): unknown;
+    }>;
+    i32: Readonly<{
+        decode(value: unknown): number;
+        encode(value: number): unknown;
+    }>;
+    u32: Readonly<{
+        decode(value: unknown): number;
+        encode(value: number): unknown;
+    }>;
+    i64: Readonly<{
+        decode(value: unknown): bigint;
+        encode(value: bigint): unknown;
+    }>;
+    u64: Readonly<{
+        decode(value: unknown): bigint;
+        encode(value: bigint): unknown;
+    }>;
+    f64: Readonly<{
+        decode(value: unknown): number;
+        encode(value: number): unknown;
+    }>;
+    bytes: Readonly<{
+        decode(value: unknown): Uint8Array<ArrayBufferLike>;
+        encode(value: Uint8Array<ArrayBufferLike>): unknown;
+    }>;
+    timestamp: Readonly<{
+        decode(value: unknown): Timestamp;
+        encode(value: Timestamp): unknown;
+    }>;
+    ulid: Readonly<{
+        decode(value: unknown): Ulid;
+        encode(value: Ulid): unknown;
+    }>;
+    openEnum<const T extends string>(values: readonly T[]): Codec<OpenEnum<T>>;
+    model<const F extends Readonly<Record<string, ModelField>>>(fields: F): Codec<ModelValue<F>>;
+    named<T, Named extends T>(_name: string, value: Codec<T>): Codec<Named>;
+    list<T>(item: Codec<T>): Codec<T[]>;
+    map<T>(item: Codec<T>): Codec<Record<string, T>>;
+    nullable<T>(value: Codec<T>): Codec<T | null>;
+    optional<T>(value: Codec<T>): OptionalCodec<T>;
+    ref<T>(get: () => Codec<T>): Codec<T>;
+    recursive<T>(build: (self: Codec<T>) => Codec<T>): Codec<T>;
+}>;
+type ApiDescriptorInput = Readonly<{
+    identity: string;
+    actions: Readonly<Record<string, Readonly<Record<string, unknown>>>>;
+}>;
+type PackageEvidenceInput = Readonly<{
+    rootPackage: string;
+    rootDigest: string;
+    packages: readonly Readonly<{
+        name: string;
+        version: string;
+        digest: string;
+        source: string;
+    }>[];
+}>;
+type ParticipantDescriptorInput = Readonly<{
+    kind: "service" | "device" | "app" | "agent";
+    id: string;
+    identity: string;
+    path: string;
+    implements: readonly ApiDescriptorInput[];
+    uses: readonly Readonly<Record<string, unknown>>[];
+    actionNames: Readonly<Record<string, string>>;
+    resources: Readonly<Record<string, Readonly<Record<string, unknown>>>>;
+    companion?: Readonly<{
+        participant: ParticipantDescriptorInput;
+        availability: "required" | "optional";
+    }>;
+    packageEvidence: PackageEvidenceInput;
+}>;
+/** Validate and retain generated API evidence without deriving authority from it. */
+export declare function apiDescriptor<const T extends ApiDescriptorInput>(descriptor: T): T;
+/** Validate and retain generated participant evidence without resolving grants or authority. */
+export declare function participantDescriptor<const T extends ParticipantDescriptorInput>(descriptor: T): T;
+export {};