@qlever-llc/trellis 0.10.12 → 0.10.14

package/src/contract_support/mod.ts

@@ -57,7 +57,6 @@ import {
   type SubjectParam,
 } from "./schema_pointers.js";
 import {
-  type ContractEventConsumerEvent,
   type ContractEventConsumerGroup,
   type ContractEventConsumers,
   ContractEventConsumersSchema,
@@ -70,12 +69,14 @@ import {
 export {
   buildCursorPage,
   buildPageResponse,
-  type ContractEventConsumerEvent,
-  ContractEventConsumerEventSchema,
   type ContractEventConsumerGroup,
   ContractEventConsumerGroupSchema,
   type ContractEventConsumers,
+  type ContractEventConsumerSelf,
+  ContractEventConsumerSelfSchema,
   ContractEventConsumersSchema,
+  type ContractEventConsumerUses,
+  ContractEventConsumerUsesSchema,
   ContractJobQueueSchema,
   ContractJobsSchema,
   ContractKvResourceSchema,
@@ -115,6 +116,10 @@ export {
   type StoreResourceBinding,
   StoreResourceBindingSchema,
 } from "./protocol.js";
+export {
+  assertDataPointersExistAndAreTokenable,
+  getSubschemaAtDataPointer,
+} from "./schema_pointers.js";
 
 export const CONTRACT_FORMAT_V1 = "trellis.contract.v1" as const;
 export const CATALOG_FORMAT_V1 = "trellis.catalog.v1" as const;
@@ -964,13 +969,9 @@ export type ContractSourceJobs<TSchemaName extends string = string> = Record<
   ContractSourceJobQueue<TSchemaName>
 >;
 
-export type ContractSourceEventConsumerEvent = {
-  use: string;
-  event: string;
-};
-
 export type ContractSourceEventConsumerGroup = {
-  events: readonly ContractSourceEventConsumerEvent[];
+  uses?: Record<string, readonly string[]>;
+  self?: readonly string[];
   replay?: "new" | "all";
   ordering?: "strict";
   concurrency?: number;
@@ -2637,7 +2638,9 @@ function projectDigestJobs(
 function projectDigestEventConsumers(
   eventConsumers: ContractEventConsumers | undefined,
 ): ContractEventConsumers | undefined {
-  return eventConsumers ? mapValues(eventConsumers, omitDocs) : undefined;
+  return eventConsumers
+    ? mapValues(eventConsumers, projectDigestEventConsumerGroup)
+    : undefined;
 }
 
 function projectDigestUsesFlat(
@@ -3068,25 +3071,31 @@ function feed(feed: ContractFeed): ContractFeed {
   };
 }
 
-function eventConsumerEvent(
-  event: ContractEventConsumerEvent,
-): ContractEventConsumerEvent {
-  return { use: event.use, event: event.event };
+function sortEventConsumerUses(
+  uses: Record<string, readonly string[]> | undefined,
+): Record<string, string[]> | undefined {
+  if (!uses) {
+    return undefined;
+  }
+  return Object.fromEntries(
+    Object.entries(uses)
+      .sort(([left], [right]) => left.localeCompare(right))
+      .map(([alias, events]) => [alias, sortedUnique(events)]),
+  );
 }
 
-function sortEventConsumerEvents(
-  events: readonly ContractEventConsumerEvent[],
-): ContractEventConsumerEvent[] {
-  return events.map(eventConsumerEvent).sort((left, right) =>
-    left.use.localeCompare(right.use) || left.event.localeCompare(right.event)
-  );
+function sortEventConsumerSelf(
+  self: readonly string[] | undefined,
+): string[] | undefined {
+  return self ? sortedUnique(self) : undefined;
 }
 
 function eventConsumerGroup(
-  group: ContractEventConsumerGroup,
+  group: ContractSourceEventConsumerGroup,
 ): ContractEventConsumerGroup {
   return {
-    events: sortEventConsumerEvents(group.events),
+    ...(group.uses ? { uses: sortEventConsumerUses(group.uses) } : {}),
+    ...(group.self ? { self: sortEventConsumerSelf(group.self) } : {}),
     replay: group.replay ?? "new",
     ordering: group.ordering ?? "strict",
     concurrency: group.concurrency ?? 1,
@@ -3097,6 +3106,12 @@ function eventConsumerGroup(
   };
 }
 
+function projectDigestEventConsumerGroup(
+  group: ContractEventConsumerGroup,
+): ContractEventConsumerGroup {
+  return omitDocs(eventConsumerGroup(group));
+}
+
 function errorDecl(error: ContractErrorDecl): ContractErrorDecl {
   return {
     type: error.type,
@@ -3240,7 +3255,11 @@ export function parseContractManifest(value: unknown): TrellisContractV1 {
     );
   }
   const contract = normalizeContractManifest(parsed);
-  assertValidEventConsumers(contract.eventConsumers, contract.uses);
+  assertValidEventConsumers(
+    contract.eventConsumers,
+    contract.uses,
+    contract.events,
+  );
   return contract;
 }
 
@@ -3408,20 +3427,7 @@ function emitEventConsumers(
   return Object.fromEntries(
     Object.entries(eventConsumers).map(([groupName, group]) => [
       groupName,
-      {
-        events: sortEventConsumerEvents(group.events),
-        replay: group.replay ?? "new",
-        ordering: group.ordering ?? "strict",
-        concurrency: group.concurrency ?? 1,
-        ...(group.ackWaitMs !== undefined
-          ? { ackWaitMs: group.ackWaitMs }
-          : {}),
-        ...(group.maxDeliver !== undefined
-          ? { maxDeliver: group.maxDeliver }
-          : {}),
-        ...(group.backoffMs ? { backoffMs: [...group.backoffMs] } : {}),
-        ...(group.docs ? { docs: contractDocs(group.docs) } : {}),
-      } satisfies ContractEventConsumerGroup,
+      eventConsumerGroup(group),
     ]),
   );
 }
@@ -3840,7 +3846,7 @@ function emitContract(source: TrellisContractSource): TrellisContractV1 {
   const state = emitState(source.state);
   const resources = emitResources(source.resources);
   const uses = emitUses(source.uses);
-  assertValidEventConsumers(eventConsumers, uses);
+  assertValidEventConsumers(eventConsumers, uses, events);
 
   return {
     format: CONTRACT_FORMAT_V1,
@@ -4151,15 +4157,20 @@ function contractUseByAlias(
 function assertValidEventConsumers(
   eventConsumers: ContractEventConsumers | undefined,
   uses: ContractUses | undefined,
+  ownedEvents: Record<string, ContractEvent> | undefined,
 ): void {
   if (!eventConsumers) {
     return;
   }
 
   for (const [groupName, group] of Object.entries(eventConsumers)) {
-    if (group.events.length === 0) {
+    const hasDependencyEvents = Object.values(group.uses ?? {}).some(
+      (eventNames) => eventNames.length > 0,
+    );
+    const hasSelfEvents = (group.self?.length ?? 0) > 0;
+    if (!hasDependencyEvents && !hasSelfEvents) {
       throw new Error(
-        `event consumer group '${groupName}' must declare events`,
+        `event consumer group '${groupName}' must declare at least one dependency or self event`,
       );
     }
     if ((group.ordering ?? "strict") === "strict" && group.concurrency !== 1) {
@@ -4168,16 +4179,33 @@ function assertValidEventConsumers(
       );
     }
 
-    for (const eventRef of group.events) {
-      const use = contractUseByAlias(uses, eventRef.use);
+    for (const [alias, eventNames] of Object.entries(group.uses ?? {})) {
+      if (eventNames.length === 0) {
+        throw new Error(
+          `event consumer group '${groupName}' use '${alias}' must declare events`,
+        );
+      }
+
+      const use = contractUseByAlias(uses, alias);
       if (!use) {
         throw new Error(
-          `event consumer group '${groupName}' references unknown use '${eventRef.use}'`,
+          `event consumer group '${groupName}' references unknown use '${alias}'`,
         );
       }
-      if (!use.events?.subscribe?.includes(eventRef.event)) {
+
+      for (const eventName of eventNames) {
+        if (!use.events?.subscribe?.includes(eventName)) {
+          throw new Error(
+            `event consumer group '${groupName}' references event '${eventName}' that use '${alias}' does not subscribe to`,
+          );
+        }
+      }
+    }
+
+    for (const eventName of group.self ?? []) {
+      if (!ownedEvents || !Object.hasOwn(ownedEvents, eventName)) {
         throw new Error(
-          `event consumer group '${groupName}' references event '${eventRef.event}' that use '${eventRef.use}' does not subscribe to`,
+          `event consumer group '${groupName}' references unknown owned event '${eventName}'`,
         );
       }
     }

package/src/contract_support/protocol.ts

@@ -99,17 +99,26 @@ export const ContractJobsSchema = Type.Record(
 
 export type ContractJobs = Static<typeof ContractJobsSchema>;
 
-export const ContractEventConsumerEventSchema = Type.Object({
-  use: Type.String({ minLength: 1 }),
-  event: Type.String({ minLength: 1 }),
-});
+export const ContractEventConsumerUsesSchema = Type.Record(
+  Type.String({ minLength: 1 }),
+  Type.Array(Type.String({ minLength: 1 }), { minItems: 1 }),
+);
+
+export type ContractEventConsumerUses = Static<
+  typeof ContractEventConsumerUsesSchema
+>;
+
+export const ContractEventConsumerSelfSchema = Type.Array(
+  Type.String({ minLength: 1 }),
+);
 
-export type ContractEventConsumerEvent = Static<
-  typeof ContractEventConsumerEventSchema
+export type ContractEventConsumerSelf = Static<
+  typeof ContractEventConsumerSelfSchema
 >;
 
 export const ContractEventConsumerGroupSchema = Type.Object({
-  events: Type.Array(ContractEventConsumerEventSchema, { minItems: 1 }),
+  uses: Type.Optional(ContractEventConsumerUsesSchema),
+  self: Type.Optional(ContractEventConsumerSelfSchema),
   replay: Type.Optional(Type.Union([
     Type.Literal("new"),
     Type.Literal("all"),

package/src/contract_support/schema_pointers.ts

@@ -62,7 +62,71 @@ function decodeJsonPointerSegment(segment: string): string {
   return segment.replaceAll("~1", "/").replaceAll("~0", "~");
 }
 
-function resolveSubschema(
+type PointerResolution = {
+  found: boolean;
+  schemas: unknown[];
+};
+
+function pointerResolution(
+  found: boolean,
+  schemas: unknown[],
+): PointerResolution {
+  return { found, schemas };
+}
+
+function collectSubschemas(
+  schema: unknown,
+  segments: readonly string[],
+): PointerResolution {
+  if (segments.length === 0) return pointerResolution(true, [schema]);
+  if (!isJsonObject(schema)) return pointerResolution(false, []);
+
+  const resolved: unknown[] = [];
+  let found = false;
+
+  const properties = schema.properties;
+  const segment = segments[0];
+  if (
+    segment !== undefined && isJsonObject(properties) &&
+    Object.hasOwn(properties, segment)
+  ) {
+    const direct = collectSubschemas(properties[segment], segments.slice(1));
+    found = found || direct.found;
+    resolved.push(...direct.schemas);
+  }
+
+  const allOf = schema.allOf;
+  if (Array.isArray(allOf)) {
+    for (const branch of allOf) {
+      const branchResult = collectSubschemas(branch, segments);
+      found = found || branchResult.found;
+      resolved.push(...branchResult.schemas);
+    }
+  }
+
+  for (const key of ["anyOf", "oneOf"] as const) {
+    const variants = schema[key];
+    if (!Array.isArray(variants) || variants.length === 0) continue;
+
+    const variantSchemas: unknown[] = [];
+    let everyVariantResolved = true;
+    for (const variant of variants) {
+      const variantResult = collectSubschemas(variant, segments);
+      if (!variantResult.found) {
+        everyVariantResolved = false;
+        break;
+      }
+      variantSchemas.push(...variantResult.schemas);
+    }
+
+    if (everyVariantResolved) found = true;
+    resolved.push(...variantSchemas);
+  }
+
+  return pointerResolution(found, resolved);
+}
+
+function resolveFirstSubschema(
   schema: unknown,
   segments: readonly string[],
 ): unknown | undefined {
@@ -73,7 +137,7 @@ function resolveSubschema(
     const variants = schema[key];
     if (!Array.isArray(variants)) continue;
     for (const variant of variants) {
-      const resolved = resolveSubschema(variant, segments);
+      const resolved = resolveFirstSubschema(variant, segments);
       if (resolved !== undefined) return resolved;
     }
   }
@@ -85,7 +149,7 @@ function resolveSubschema(
   if (!isJsonObject(properties) || !Object.hasOwn(properties, segment)) {
     return undefined;
   }
-  return resolveSubschema(properties[segment], segments.slice(1));
+  return resolveFirstSubschema(properties[segment], segments.slice(1));
 }
 
 function isTokenableSchema(schema: unknown): boolean {
@@ -131,30 +195,39 @@ function isTokenableSchema(schema: unknown): boolean {
   return false;
 }
 
+/**
+ * Returns the first schema node reachable by following a payload JSON Pointer.
+ */
 export function getSubschemaAtDataPointer(
   schema: unknown,
   pointer: string,
 ): unknown | undefined {
-  return resolveSubschema(
+  return resolveFirstSubschema(
     schema,
     pointer.slice(1).split("/").map(decodeJsonPointerSegment),
   );
 }
 
+/**
+ * Verifies that event subject parameter pointers resolve to tokenable schemas.
+ */
 export function assertDataPointersExistAndAreTokenable(
   name: string,
   schema: unknown,
   pointers: readonly string[],
 ): void {
   for (const pointer of pointers) {
-    const node = getSubschemaAtDataPointer(schema, pointer);
-    if (node === undefined) {
+    const resolved = collectSubschemas(
+      schema,
+      pointer.slice(1).split("/").map(decodeJsonPointerSegment),
+    );
+    if (!resolved.found) {
       throw new Error(
         `Invalid event subject param pointer '${pointer}' for event '${name}' (path not found in schema)`,
       );
     }
 
-    if (!isTokenableSchema(node)) {
+    if (!resolved.schemas.every(isTokenableSchema)) {
       throw new Error(
         `Invalid event subject param pointer '${pointer}' for event '${name}' (must resolve to string/number schema)`,
       );

package/src/device.ts

@@ -140,7 +140,6 @@ export type TrellisDeviceConnection<
   readonly stream: string;
   readonly api: TApi;
   readonly connection: TrellisConnection;
-  readonly natsConnection: NatsConnection;
   readonly health: ServiceHealth;
 };
 
@@ -717,6 +716,9 @@ async function fetchDeviceBootstrap(args: {
   });
 }
 
+/**
+ * @internal Exported for focused tests and platform-specific wrappers.
+ */
 export async function startDeviceActivationWithDeps<
   TContract extends DeviceContract<TrellisAPI, {
     state?: Readonly<Record<string, unknown>>;
@@ -758,6 +760,9 @@ export async function startDeviceActivationWithDeps<
   });
 }
 
+/**
+ * @internal Exported for focused tests and platform-specific wrappers.
+ */
 export async function resumeDeviceActivationWithDeps<
   TLocalState extends TrellisDeviceLocalActivationState,
   TContract extends DeviceContract<TrellisAPI, {
@@ -783,6 +788,10 @@ export async function resumeDeviceActivationWithDeps<
   });
 }
 
+/**
+ * @internal Exported for focused tests; applications should use
+ * `TrellisDevice.connect`.
+ */
 export async function connectDeviceWithDeps<
   TContract extends DeviceContract<TrellisAPI, {
     state?: Readonly<Record<string, unknown>>;
@@ -965,7 +974,6 @@ export async function connectDeviceWithDeps<
     stream: trellis.stream,
     api: trellis.api,
     connection: trellis.connection,
-    natsConnection: trellis.natsConnection,
     health,
   };
 }

package/src/index.ts

@@ -158,9 +158,9 @@ export type {
   TerminalJob,
   WorkerInfo,
 } from "./jobs.js";
-export { TypedKV, TypedKVEntry } from "./kv.js";
+export { TypedKVEntry } from "./kv.js";
 export type { WatchEvent, WatchOptions } from "./kv.js";
-export { TypedStore, TypedStoreEntry } from "./store.js";
+export { TypedStoreEntry } from "./store.js";
 export type {
   StoreBody,
   StoreInfo,
@@ -169,7 +169,7 @@ export type {
   StoreStatus,
   StoreWaitOptions,
 } from "./store.js";
-export { createTransferHandle, FileInfoSchema } from "./transfer.js";
+export { FileInfoSchema } from "./transfer.js";
 export type {
   FileInfo,
   ReceiveTransferGrant,
@@ -249,5 +249,4 @@ export type {
   TrellisFor,
   ValueStateStoreClient,
 } from "./trellis.js";
-export { Trellis } from "./trellis.js";
 export type { TrellisDeviceConnection } from "./device.js";

package/src/runtime_transport.ts

@@ -29,6 +29,8 @@ export type RuntimeTransport = {
 
 type NativeGlobalThis = typeof dntShim.dntGlobalThis & {
   Deno?: { version?: { deno?: string } };
+  document?: unknown;
+  window?: unknown;
 };
 
 export function selectRuntimeTransportServers(
@@ -54,7 +56,10 @@ export function selectRuntimeTransportServers(
 }
 
 function isBrowserRuntime(): boolean {
-  return typeof dntShim.dntGlobalThis !== "undefined" && typeof document !== "undefined";
+  const load = new Function("return globalThis") as () => NativeGlobalThis;
+  const browserGlobal = load();
+  return typeof browserGlobal.window !== "undefined" &&
+    typeof browserGlobal.document !== "undefined";
 }
 
 function isDenoRuntime(): boolean {

package/src/server/health_rpc.ts

@@ -10,7 +10,7 @@ import {
 type HealthRpcServer = {
   name: string;
   api: TrellisAPI;
-  natsConnection: { isClosed(): boolean };
+  connection?: { status: { phase: string } };
   mount<M extends keyof TrellisAPI["rpc"] & string>(
     method: M,
     handler: (...args: unknown[]) => unknown,
@@ -40,10 +40,15 @@ export async function mountStandardHealthRpc(
 
   const method = rpcName as keyof TrellisAPI["rpc"] & string;
   await server.mount(method, async () => {
+    const connection = server.connection;
     const response = opts?.response
       ? await opts.response()
       : await runAllHealthChecks(server.name, {
-        nats: async () => Result.ok(!server.natsConnection.isClosed()),
+        ...(connection
+          ? {
+            nats: async () => Result.ok(connection.status.phase !== "closed"),
+          }
+          : {}),
         ...(opts?.checks ?? {}),
       });
     return Result.ok(response);