@qlever-llc/trellis 0.10.22 → 0.11.0-rc.1

package/src/contract_support/runtime.ts

@@ -98,11 +98,18 @@ export type OperationDesc<
   I extends SchemaLike = SchemaLike,
   P extends SchemaLike | undefined = SchemaLike | undefined,
   O extends SchemaLike | undefined = SchemaLike | undefined,
+  E extends readonly string[] | undefined = readonly string[] | undefined,
+  TRuntimeErrors extends readonly RuntimeRpcErrorDesc[] | undefined =
+    | readonly RuntimeRpcErrorDesc[]
+    | undefined,
 > = {
   subject: string;
   input: I;
   progress?: P;
   output?: O;
+  errors?: E;
+  runtimeErrors?: TRuntimeErrors;
+  declaredErrorTypes?: readonly string[];
   transfer?: {
     direction: "send";
     store: string;

package/src/errors/SchemaValidationError.ts

@@ -0,0 +1,67 @@
+import Type, { type Static } from "typebox";
+import { TrellisError } from "./TrellisError.js";
+
+export const SchemaValidationIssueSchema = Type.Object({
+  path: Type.String(),
+  schemaPath: Type.Optional(Type.String()),
+  keyword: Type.String(),
+  code: Type.String(),
+  message: Type.String(),
+  label: Type.Optional(Type.String()),
+  note: Type.Optional(Type.String()),
+  i18nKey: Type.Optional(Type.String()),
+  severity: Type.Optional(Type.Union([
+    Type.Literal("error"),
+    Type.Literal("warning"),
+    Type.Literal("info"),
+  ])),
+  params: Type.Optional(Type.Record(Type.String(), Type.Unknown())),
+});
+export type SchemaValidationIssue = Static<typeof SchemaValidationIssueSchema>;
+
+export const SchemaValidationErrorDataSchema = Type.Object({
+  id: Type.String(),
+  type: Type.Literal("SchemaValidationError"),
+  message: Type.String(),
+  issues: Type.Array(SchemaValidationIssueSchema),
+  context: Type.Optional(Type.Record(Type.String(), Type.Unknown())),
+  traceId: Type.Optional(Type.String()),
+});
+export type SchemaValidationErrorData = Static<
+  typeof SchemaValidationErrorDataSchema
+>;
+
+export class SchemaValidationError
+  extends TrellisError<SchemaValidationErrorData> {
+  override readonly name = "SchemaValidationError" as const;
+  readonly #issues: SchemaValidationIssue[];
+
+  constructor(
+    options: {
+      issues: SchemaValidationIssue[];
+      context?: Record<string, unknown>;
+      cause?: unknown;
+      id?: string;
+    },
+  ) {
+    const { issues: rawIssues, ...baseOptions } = options;
+    const msg = rawIssues
+      .map((issue) => issue.message)
+      .join("\n");
+    super(msg.length ? msg : "Schema validation failed.", baseOptions);
+    this.#issues = rawIssues;
+  }
+
+  /** The validation issues that caused this error. */
+  get issues(): readonly SchemaValidationIssue[] {
+    return this.#issues;
+  }
+
+  override toSerializable(): SchemaValidationErrorData {
+    return {
+      ...this.baseSerializable(),
+      type: this.name,
+      issues: this.#issues,
+    } as SchemaValidationErrorData;
+  }
+}

package/src/errors/index.ts

@@ -11,6 +11,15 @@ import { AuthErrorDataSchema } from "./AuthError.js";
 import { ValidationError } from "./ValidationError.js";
 import type { ValidationErrorData } from "./ValidationError.js";
 import { ValidationErrorDataSchema } from "./ValidationError.js";
+import { SchemaValidationError } from "./SchemaValidationError.js";
+import type {
+  SchemaValidationErrorData,
+  SchemaValidationIssue,
+} from "./SchemaValidationError.js";
+import {
+  SchemaValidationErrorDataSchema,
+  SchemaValidationIssueSchema,
+} from "./SchemaValidationError.js";
 import { RemoteError } from "./RemoteError.js";
 import { KVError } from "./KVError.js";
 import type { KVErrorData } from "./KVError.js";
@@ -48,6 +57,7 @@ export { UnexpectedError } from "@qlever-llc/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 {
@@ -66,6 +76,12 @@ export {
   type ValidationIssue,
   ValidationIssueSchema,
 } from "./ValidationError.js";
+export {
+  type SchemaValidationErrorData,
+  SchemaValidationErrorDataSchema,
+  type SchemaValidationIssue,
+  SchemaValidationIssueSchema,
+} from "./SchemaValidationError.js";
 export { type RemoteErrorData, RemoteErrorDataSchema } from "./RemoteError.js";
 export { type KVErrorData, KVErrorDataSchema } from "./KVError.js";
 export {
@@ -95,6 +111,7 @@ const TRANSPORTABLE_TRELLIS_ERRORS = {
   TransportError,
   AuthError,
   ValidationError,
+  SchemaValidationError,
   KVError,
   OperationNotFoundError,
   OperationAlreadyTerminalError,
@@ -182,6 +199,17 @@ export const BUILTIN_RPC_ERRORS = {
       });
     },
   },
+  SchemaValidationError: {
+    type: "SchemaValidationError",
+    schema: schema<SchemaValidationErrorData>(SchemaValidationErrorDataSchema),
+    fromSerializable(data: SchemaValidationErrorData) {
+      return new SchemaValidationError({
+        issues: data.issues,
+        id: data.id,
+        context: data.context,
+      });
+    },
+  },
   KVError: {
     type: "KVError",
     schema: schema<KVErrorData>(KVErrorDataSchema),

package/src/health.ts

@@ -19,7 +19,6 @@ export {
 } from "./server/health.js";
 export {
   HealthCheckResultSchema,
-  HealthHeartbeatHeaderSchema,
   HealthHeartbeatSchema,
   HealthHeartbeatServiceSchema,
   HealthInfoSchema,

package/src/index.ts

@@ -43,7 +43,6 @@ export type {
 export {
   createHealthHeartbeat,
   HealthCheckResultSchema,
-  HealthHeartbeatHeaderSchema,
   HealthHeartbeatSchema,
   HealthHeartbeatServiceSchema,
   HealthInfoSchema,
@@ -55,7 +54,7 @@ export {
   runServiceHealthCheck,
   ServiceHealth,
 } from "./health.js";
-export { defineError } from "./contract_support/mod.js";
+export { defineError, withTrellisValidation } from "./contract_support/mod.js";
 export {
   buildCursorPage,
   buildPageResponse,
@@ -81,6 +80,8 @@ export type {
   RpcErrorClass,
   RuntimeRpcErrorDesc,
   SerializableErrorData,
+  TrellisValidationExtension,
+  TrellisValidationIssueHint,
 } from "./contract_support/mod.js";
 export {
   defineAgentContract,
@@ -212,7 +213,6 @@ export type {
   AcceptedOperation,
   ClientTrellis,
   ConnectedTrellisClient,
-  EventHandler,
   EventListenerContext,
   EventName,
   EventOpts,
@@ -229,25 +229,24 @@ export type {
   HandlerTrellisForContract,
   MapStateStoreClient,
   OperationHandlerContext,
+  OperationHandlerErrorOf,
   OperationRegistration,
   OperationRuntimeHandle,
   OperationTransferContextOf,
   OperationTransferHandle,
   PreparedTrellisEvent,
   RequestOpts,
-  RpcArgs,
   RpcHandlerContext,
-  RpcHandlerErrorOf,
-  RpcHandlerFn,
   RpcInputOf,
   RpcMethodNameOf,
   RpcOutputOf,
   RpcRequestErrorOf,
-  RpcResult,
   RuntimeStateStoresForContract,
   RuntimeStateStoreShape,
+  SessionCaller,
   StateFacade,
-  TrellisFor,
+  TrellisEventHeader,
+  TrellisEventMessage,
   ValueStateStoreClient,
 } from "./trellis.js";
 export type { TrellisDeviceConnection } from "./device.js";

package/src/jobs.ts

@@ -1,4 +1,4 @@
-import { AsyncResult, type BaseError, Result } from "@qlever-llc/result";
+import { AsyncResult, BaseError, Result } from "@qlever-llc/result";
 import { UnexpectedError } from "./errors/index.js";
 import { type StaticDecode, Type } from "typebox";
 
@@ -41,6 +41,8 @@ export type JobState =
   | "failed"
   | "cancelled"
   | "expired"
+  | "skipped"
+  | "stale"
   | "dead"
   | "dismissed";
 
@@ -50,6 +52,116 @@ export type JobIdentity = {
   id: string;
 };
 
+export type JobNotEnqueuedReason =
+  | "active-limit"
+  | "queue-depth"
+  | "stale-blocked"
+  | "coalesced";
+
+export type JobNotEnqueuedErrorData = {
+  id: string;
+  type: "JobNotEnqueuedError";
+  message: string;
+  reason: JobNotEnqueuedReason;
+  key: string;
+  active: number;
+  queued: number;
+  limit: number;
+  existingJobId?: string;
+  context?: Record<string, unknown>;
+  traceId?: string;
+};
+
+/** Error returned when keyed job admission does not create a new job. */
+export class JobNotEnqueuedError extends BaseError<JobNotEnqueuedErrorData> {
+  override readonly name = "JobNotEnqueuedError" as const;
+  readonly reason: JobNotEnqueuedReason;
+  readonly key: string;
+  readonly active: number;
+  readonly queued: number;
+  readonly limit: number;
+  readonly existingJobId?: string;
+
+  constructor(
+    options: ErrorOptions & {
+      reason: JobNotEnqueuedReason;
+      key: string;
+      active: number;
+      queued: number;
+      limit: number;
+      existingJobId?: string;
+      message?: string;
+      context?: Record<string, unknown>;
+      id?: string;
+      traceId?: string;
+    },
+  ) {
+    const {
+      reason,
+      key,
+      active,
+      queued,
+      limit,
+      existingJobId,
+      message,
+      ...baseOptions
+    } = options;
+    super(
+      message ?? `Job was not enqueued for key '${key}': ${reason}`,
+      baseOptions,
+    );
+    this.reason = reason;
+    this.key = key;
+    this.active = active;
+    this.queued = queued;
+    this.limit = limit;
+    this.existingJobId = existingJobId;
+  }
+
+  /** Serializes the admission error for transport or logging. */
+  override toSerializable(): JobNotEnqueuedErrorData {
+    const base = this.baseSerializable();
+    return {
+      id: base.id,
+      type: this.name,
+      message: base.message,
+      reason: this.reason,
+      key: this.key,
+      active: this.active,
+      queued: this.queued,
+      limit: this.limit,
+      ...(this.existingJobId !== undefined
+        ? { existingJobId: this.existingJobId }
+        : {}),
+      ...(base.context !== undefined ? { context: base.context } : {}),
+      ...(base.traceId !== undefined ? { traceId: base.traceId } : {}),
+    };
+  }
+}
+
+export type JobSubmitOutcome<TPayload, TResult> =
+  | { kind: "accepted"; ref: JobRef<TPayload, TResult>; key?: string }
+  | {
+    kind: "rejected";
+    key: string;
+    reason: "active-limit" | "queue-depth" | "stale-blocked";
+    active: number;
+    queued: number;
+    limit: number;
+  }
+  | {
+    kind: "coalesced";
+    key: string;
+    existing: JobIdentity;
+    reason: string;
+  }
+  | {
+    kind: "replaced";
+    key: string;
+    replaced: JobIdentity;
+    ref: JobRef<TPayload, TResult>;
+  };
+
 export type JobSnapshot<TPayload, TResult> = {
   id: string;
   service: string;
@@ -81,6 +193,8 @@ export type TerminalJob<TPayload, TResult> = JobSnapshot<TPayload, TResult> & {
     | "failed"
     | "cancelled"
     | "expired"
+    | "skipped"
+    | "stale"
     | "dead"
     | "dismissed";
 };
@@ -269,6 +383,9 @@ export class JobQueue<TPayload, TResult> {
       job: ActiveJob<TPayload, TResult>,
     ) => Promise<Result<TResult, BaseError>>,
   ) => void;
+  readonly #submit: (
+    payload: TPayload,
+  ) => AsyncResult<JobSubmitOutcome<TPayload, TResult>, BaseError>;
 
   constructor(impl: {
     create: (
@@ -279,9 +396,15 @@ export class JobQueue<TPayload, TResult> {
         job: ActiveJob<TPayload, TResult>,
       ) => Promise<Result<TResult, BaseError>>,
     ) => void;
+    submit?: (
+      payload: TPayload,
+    ) => AsyncResult<JobSubmitOutcome<TPayload, TResult>, BaseError>;
   }) {
     this.#create = impl.create;
     this.#handle = impl.handle;
+    this.#submit = impl.submit ??
+      ((payload) =>
+        impl.create(payload).map((ref) => ({ kind: "accepted", ref })));
   }
 
   create(payload: TPayload): AsyncResult<JobRef<TPayload, TResult>, BaseError> {
@@ -292,6 +415,20 @@ export class JobQueue<TPayload, TResult> {
     }
   }
 
+  /**
+   * Submits a job using queue policy outcomes for keyed queues.
+   * Unkeyed queues accept and return a new job reference.
+   */
+  submit(
+    payload: TPayload,
+  ): AsyncResult<JobSubmitOutcome<TPayload, TResult>, BaseError> {
+    try {
+      return this.#submit(payload);
+    } catch (cause) {
+      return AsyncResult.err(toUnexpectedError(cause));
+    }
+  }
+
   handle(
     handler: (
       job: ActiveJob<TPayload, TResult>,

package/src/sdk/_generated/auth/api.ts

@@ -1,12 +1,34 @@
 // Generated from ./generated/contracts/manifests/trellis.auth@v1.json
 import { OWNED_API } from "./owned_api.js";
+import { OWNED_API as HealthApi } from "../health/mod.js";
 
 export { OWNED_API };
 
+type __TrellisGeneratedOptionalOperationProgress<TDesc> = TDesc extends
+  { progress: infer TProgress } ? { progress?: TProgress }
+  : { progress?: undefined };
+type __TrellisGeneratedOptionalOperationOutput<TDesc> = TDesc extends
+  { output: infer TOutput } ? { output?: TOutput }
+  : { output?: undefined };
+type __TrellisGeneratedOptionalOperationIO<TDesc> = TDesc extends
+  { input: infer TInput } ?
+    & Omit<TDesc, "input" | "progress" | "output">
+    & {
+      input: TInput;
+    }
+    & __TrellisGeneratedOptionalOperationProgress<TDesc>
+    & __TrellisGeneratedOptionalOperationOutput<TDesc>
+  : TDesc;
+type __TrellisGeneratedOperationApi<TApi> = {
+  readonly [K in keyof TApi]: __TrellisGeneratedOptionalOperationIO<TApi[K]>;
+};
+
 export type UsedApi = {
   rpc: {};
   operations: {};
-  events: {};
+  events: {
+    readonly "Health.Heartbeat": typeof HealthApi.events["Health.Heartbeat"];
+  };
   feeds: {};
   subjects: {};
 };
@@ -14,12 +36,18 @@ export type UsedApi = {
 export const USED_API: UsedApi = {
   rpc: {},
   operations: {},
-  events: {},
+  events: {
+    get "Health.Heartbeat"() {
+      return HealthApi.events["Health.Heartbeat"];
+    },
+  },
   feeds: {},
   subjects: {},
 };
 
-export type OwnedApi = typeof OWNED_API;
+export type OwnedApi = Omit<typeof OWNED_API, "operations"> & {
+  operations: __TrellisGeneratedOperationApi<typeof OWNED_API["operations"]>;
+};
 export type Api = {
   rpc: OwnedApi["rpc"] & UsedApi["rpc"];
   operations: OwnedApi["operations"] & UsedApi["operations"];
@@ -28,9 +56,12 @@ export type Api = {
   subjects: OwnedApi["subjects"] & UsedApi["subjects"];
 };
 
-export const API = {
+export type ApiViews = {
+  owned: OwnedApi;
+  used: UsedApi;
+};
+
+export const API: ApiViews = {
   owned: OWNED_API,
   used: USED_API,
-} as const;
-
-export type ApiViews = typeof API;
+};