@ontrails/core 1.0.0-beta.39 → 1.0.0-beta.41

package/src/queue.ts

@@ -0,0 +1,163 @@
+import type {
+  ActivationSource,
+  ActivationSourceMeta,
+  ActivationSourceParse,
+} from './activation-source.js';
+import { ValidationError } from './errors.js';
+
+export interface QueueSpec<TOutput = unknown> {
+  readonly meta?: ActivationSourceMeta | undefined;
+  readonly parse: ActivationSourceParse<TOutput>;
+  readonly payload?: ActivationSource['payload'] | undefined;
+  /**
+   * Runtime queue name. Defaults to the source id, so authored queue
+   * contracts can stay stable while host bindings choose their own names.
+   */
+  readonly queue?: string | undefined;
+  /** Reserved for future queue-specific design; trail versioning is trail-only. */
+  readonly version?: never;
+}
+
+export interface QueueSource<TOutput = unknown> extends ActivationSource {
+  readonly kind: 'queue';
+  readonly meta?: ActivationSourceMeta | undefined;
+  readonly parse: ActivationSourceParse<TOutput>;
+  readonly payload?: ActivationSource['payload'] | undefined;
+  readonly queue: string;
+}
+
+export interface QueueValidationIssue {
+  readonly field: 'parse' | 'queue';
+  readonly message: string;
+}
+
+const normalizeQueueName = (queueName: string): string => queueName.trim();
+
+const isObjectRecord = (value: unknown): value is Record<string, unknown> =>
+  typeof value === 'object' && value !== null && !Array.isArray(value);
+
+const isZodSchema = (value: unknown): boolean =>
+  isObjectRecord(value) && typeof value['safeParse'] === 'function';
+
+const validateQueueName = (queueName: unknown): QueueValidationIssue[] =>
+  typeof queueName === 'string' && queueName.trim().length > 0
+    ? []
+    : [
+        {
+          field: 'queue',
+          message: 'Queue source must define a non-empty queue name',
+        },
+      ];
+
+const validateRequiredParse = (parse: unknown): QueueValidationIssue[] =>
+  parse === undefined
+    ? [
+        {
+          field: 'parse',
+          message: 'Queue sources must define parse',
+        },
+      ]
+    : [];
+
+const validateParseShape = (parse: unknown): QueueValidationIssue[] => {
+  if (parse === undefined || isZodSchema(parse)) {
+    return [];
+  }
+  if (isObjectRecord(parse) && isZodSchema(parse['output'])) {
+    return [];
+  }
+  return [
+    {
+      field: 'parse',
+      message: 'Queue parse must be a Zod schema or define parse.output',
+    },
+  ];
+};
+
+const queueIssuesMessage = (
+  id: string,
+  issues: readonly QueueValidationIssue[]
+): string =>
+  `queue("${id}") is invalid: ${issues.map((issue) => `${issue.field}: ${issue.message}`).join('; ')}`;
+
+const assertQueueSpec = <TOutput>(
+  id: string,
+  spec: QueueSpec<TOutput>
+): {
+  readonly queue: string;
+} => {
+  const queueName = spec.queue === undefined ? id : spec.queue;
+  const issues = [
+    ...validateQueueName(queueName),
+    ...validateRequiredParse(spec.parse),
+    ...validateParseShape(spec.parse),
+  ];
+
+  if (issues.length > 0) {
+    throw new ValidationError(queueIssuesMessage(id, issues), {
+      context: { issues },
+    });
+  }
+
+  return { queue: normalizeQueueName(queueName) };
+};
+
+export const validateQueueSource = (
+  source: ActivationSource
+): readonly QueueValidationIssue[] => {
+  if (source.kind !== 'queue') {
+    return [];
+  }
+
+  return [
+    ...validateQueueName(source.queue),
+    ...validateRequiredParse(source.parse),
+    ...validateParseShape(source.parse),
+  ];
+};
+
+/**
+ * Define a queue activation source.
+ *
+ * Queue sources are inert contract data: they describe which runtime queue
+ * wakes a trail and how the message body becomes trail input. A host adapter
+ * such as `@ontrails/cloudflare/workers` owns delivery.
+ *
+ * @example
+ * ```ts
+ * import { queue } from '@ontrails/core';
+ * import { z } from 'zod';
+ *
+ * const source = queue('queue.email.outbox', {
+ *   queue: 'email-outbox',
+ *   parse: z.object({ messageId: z.string() }),
+ * });
+ * ```
+ */
+export function queue<TOutput>(
+  id: string,
+  spec: QueueSpec<TOutput>
+): QueueSource<TOutput>;
+export function queue<TOutput>(
+  spec: QueueSpec<TOutput> & { readonly id: string }
+): QueueSource<TOutput>;
+export function queue<TOutput>(
+  idOrSpec: string | (QueueSpec<TOutput> & { readonly id: string }),
+  maybeSpec?: QueueSpec<TOutput>
+): QueueSource<TOutput> {
+  const id = typeof idOrSpec === 'string' ? idOrSpec : idOrSpec.id;
+  // oxlint-disable-next-line no-non-null-assertion -- overload guarantees maybeSpec when idOrSpec is string
+  const spec = typeof idOrSpec === 'string' ? maybeSpec! : idOrSpec;
+  const normalized = assertQueueSpec(id, spec);
+
+  return Object.freeze({
+    id,
+    kind: 'queue' as const,
+    parse: spec.parse,
+    queue: normalized.queue,
+    ...(spec.meta === undefined
+      ? {}
+      : { meta: Object.freeze({ ...spec.meta }) }),
+    ...(spec.payload === undefined ? {} : { payload: spec.payload }),
+  });
+}

package/src/signal-ref.ts

@@ -11,6 +11,7 @@ export interface LateBoundSignalMarker {
 }
 
 const LATE_BOUND_SIGNAL_REF = Symbol('trails.late-bound-signal-ref');
+const LATE_BOUND_SIGNAL_BOUND = Symbol('trails.late-bound-signal-bound');
 const LATE_BOUND_SIGNAL_MARKER_PREFIX = '@@trails:late-bound-signal-ref:';
 
 const defineLateBoundSignalRef = <T extends object>(
@@ -26,6 +27,22 @@ const defineLateBoundSignalRef = <T extends object>(
   return value;
 };
 
+const defineLateBoundSignalBound = <T extends object>(value: T): T => {
+  Object.defineProperty(value, LATE_BOUND_SIGNAL_BOUND, {
+    configurable: false,
+    enumerable: false,
+    value: true,
+    writable: false,
+  });
+  return value;
+};
+
+export const isBoundLateBoundSignal = (
+  signal: Pick<AnySignal, 'id'> | undefined
+): boolean =>
+  signal !== undefined &&
+  (signal as Record<PropertyKey, unknown>)[LATE_BOUND_SIGNAL_BOUND] === true;
+
 export const getLateBoundSignalRef = (
   signal: Pick<AnySignal, 'id'> | undefined
 ): LateBoundSignalRef | undefined =>
@@ -58,14 +75,17 @@ export const cloneSignalWithId = <T>(
   };
   const ref = getLateBoundSignalRef(signal);
   return Object.freeze(
-    ref ? defineLateBoundSignalRef(clone, ref) : clone
+    ref
+      ? defineLateBoundSignalBound(defineLateBoundSignalRef(clone, ref))
+      : clone
   ) as Signal<T>;
 };
 
 export const createLateBoundSignalMarker = (
   ref: LateBoundSignalRef,
   displayId: string
-): string => `${LATE_BOUND_SIGNAL_MARKER_PREFIX}${ref.token}:${displayId}`;
+): string =>
+  `${LATE_BOUND_SIGNAL_MARKER_PREFIX}${encodeURIComponent(ref.token)}:${displayId}`;
 
 export const parseLateBoundSignalMarker = (
   value: string
@@ -80,8 +100,12 @@ export const parseLateBoundSignalMarker = (
     return null;
   }
 
-  return {
-    displayId: remainder.slice(separator + 1),
-    token: remainder.slice(0, separator),
-  };
+  try {
+    const token = decodeURIComponent(remainder.slice(0, separator));
+    return token.length === 0
+      ? null
+      : { displayId: remainder.slice(separator + 1), token };
+  } catch {
+    return null;
+  }
 };

package/src/store/accessor-protocol.ts

@@ -1,6 +1,6 @@
 /**
  * Structural accessor protocol used by `deriveTrail()` to synthesize default
- * blazes for standard CRUD operations without depending on `@ontrails/store`.
+ * implementations for standard CRUD operations without depending on `@ontrails/store`.
  *
  * @remarks
  * This type is intentionally minimal and structural. `@ontrails/store`'s
@@ -35,21 +35,21 @@ export interface StoreAccessorProtocol<
   remove(id: TId): Promise<{ readonly deleted: boolean }>;
   /**
    * Optional insert — available on tabular adapters that distinguish
-   * create from update. When absent, synthesized blazes fall back to
+   * create from update. When absent, synthesized implementations fall back to
    * `upsert`.
    */
   insert?(input: TInput): Promise<TEntity>;
   /**
    * Optional patch-by-identity — available on tabular adapters. Returns
    * `null` when no row with the given identity exists. When absent,
-   * synthesized update blazes fall back to `get` + merge + `upsert`.
+   * synthesized update implementations fall back to `get` + merge + `upsert`.
    */
   update?(id: TId, patch: Partial<TInput>): Promise<TEntity | null>;
 }
 
 /**
  * Record shape returned by a resource's `from(ctx)` call, keyed by accessor
- * name. Used by `deriveTrail()` to resolve an accessor by contour name.
+ * name. Used by `deriveTrail()` to resolve an accessor by entity name.
  */
 export type StoreAccessorRecord = Readonly<
   Record<string, StoreAccessorProtocol<unknown, unknown, unknown, unknown>>

package/src/surface-overlay.ts

@@ -577,7 +577,7 @@ const assertMcpSynonymBindingName = (name: string): void => {
  * Derive the deterministic default description for an MCP grouped entry
  * projected from the `surfaces` overlay.
  *
- * Both the MCP surface (the runtime tool description) and Topographer (the
+ * Both the MCP surface (the runtime tool description) and Topography (the
  * lock's trailhead entry description) read this helper, so the authored
  * binding projects one description everywhere.
  *

package/src/topo.ts

@@ -2,7 +2,7 @@
  * Application entry point — scans module exports to build a topology graph.
  */
 
-import type { AnyContour } from './contour.js';
+import type { AnyEntity } from './entity.js';
 import { ValidationError } from './errors.js';
 import type { ActivationEntry } from './activation-source.js';
 import {
@@ -39,7 +39,7 @@ export interface Topo {
   readonly name: string;
   readonly version?: string;
   readonly description?: string;
-  readonly contours: ReadonlyMap<string, AnyContour>;
+  readonly entities: ReadonlyMap<string, AnyEntity>;
   readonly trails: ReadonlyMap<string, AnyTrail>;
   readonly signals: ReadonlyMap<string, AnySignal>;
   readonly resources: ReadonlyMap<string, AnyResource>;
@@ -49,23 +49,23 @@ export interface Topo {
    *
    * The CLI/MCP/HTTP surfaces forward these into `executeTrail` as
    * `topoLayers`, where they are composed outermost in the layer chain.
-   * The final composition order is `topo → surface → trail → blaze`
+   * The final composition order is `topo → surface → trail → implementation`
    * (outermost-first).
    */
   readonly layers: readonly Layer[];
   readonly count: number;
-  readonly contourCount: number;
+  readonly entityCount: number;
   readonly resourceCount: number;
-  getContour(name: string): AnyContour | undefined;
+  getEntity(name: string): AnyEntity | undefined;
   get(id: string): AnyTrail | undefined;
   getResource(id: string): AnyResource | undefined;
-  hasContour(name: string): boolean;
+  hasEntity(name: string): boolean;
   has(id: string): boolean;
   hasResource(id: string): boolean;
-  contourIds(): string[];
+  entityIds(): string[];
   ids(): string[];
   resourceIds(): string[];
-  listContours(): AnyContour[];
+  listEntities(): AnyEntity[];
   list(): AnyTrail[];
   listSignals(): AnySignal[];
   listResources(): AnyResource[];
@@ -75,14 +75,14 @@ export interface Topo {
 // Kind discriminant check
 // ---------------------------------------------------------------------------
 
-type Registrable = AnyContour | AnyTrail | AnySignal | AnyResource;
+type Registrable = AnyEntity | AnyTrail | AnySignal | AnyResource;
 
 const isRegistrable = (value: unknown): value is Registrable => {
   if (typeof value !== 'object' || value === null) {
     return false;
   }
   const { kind } = value as Record<string, unknown>;
-  return kind === 'contour' || kind === 'trail' || kind === 'signal';
+  return kind === 'entity' || kind === 'trail' || kind === 'signal';
 };
 
 // ---------------------------------------------------------------------------
@@ -91,24 +91,24 @@ const isRegistrable = (value: unknown): value is Registrable => {
 
 const createTopo = (
   identity: TopoIdentity,
-  contours: ReadonlyMap<string, AnyContour>,
+  entities: ReadonlyMap<string, AnyEntity>,
   trails: ReadonlyMap<string, AnyTrail>,
   signals: ReadonlyMap<string, AnySignal>,
   resources: ReadonlyMap<string, AnyResource>,
   observe: ObserveConfig | undefined,
   layers: readonly Layer[]
 ): Topo => ({
-  contourCount: contours.size,
-  contourIds(): string[] {
-    return [...contours.keys()];
-  },
-  contours,
   count: trails.size,
+  entities,
+  entityCount: entities.size,
+  entityIds(): string[] {
+    return [...entities.keys()];
+  },
   get(id: string): AnyTrail | undefined {
     return trails.get(id);
   },
-  getContour(contourName: string): AnyContour | undefined {
-    return contours.get(contourName);
+  getEntity(entityName: string): AnyEntity | undefined {
+    return entities.get(entityName);
   },
   getResource(id: string): AnyResource | undefined {
     return resources.get(id);
@@ -116,8 +116,8 @@ const createTopo = (
   has(id: string): boolean {
     return trails.has(id);
   },
-  hasContour(contourName: string): boolean {
-    return contours.has(contourName);
+  hasEntity(entityName: string): boolean {
+    return entities.has(entityName);
   },
   hasResource(id: string): boolean {
     return resources.has(id);
@@ -129,8 +129,8 @@ const createTopo = (
   list(): AnyTrail[] {
     return [...trails.values()];
   },
-  listContours(): AnyContour[] {
-    return [...contours.values()];
+  listEntities(): AnyEntity[] {
+    return [...entities.values()];
   },
   listResources(): AnyResource[] {
     return [...resources.values()];
@@ -176,15 +176,15 @@ const registerUnique = <T>(
   collection.set(id, value);
 };
 
-const registerContour = (
-  contour: AnyContour,
-  contours: Map<string, AnyContour>
+const registerEntity = (
+  entity: AnyEntity,
+  entities: Map<string, AnyEntity>
 ): void => {
   registerUnique(
-    contours,
-    contour.name,
-    contour,
-    `Duplicate contour name: "${contour.name}"`
+    entities,
+    entity.name,
+    entity,
+    `Duplicate entity name: "${entity.name}"`
   );
 };
 
@@ -395,14 +395,14 @@ const finalizeTrailSignals = (
 /** Register a single registrable value into the appropriate map. */
 const register = (
   value: Registrable,
-  contours: Map<string, AnyContour>,
+  entities: Map<string, AnyEntity>,
   trails: Map<string, AnyTrail>,
   signals: Map<string, AnySignal>,
   resources: Map<string, AnyResource>
 ): void => {
   switch (value.kind) {
-    case 'contour': {
-      registerContour(value as AnyContour, contours);
+    case 'entity': {
+      registerEntity(value as AnyEntity, entities);
       break;
     }
     case 'resource': {
@@ -423,15 +423,15 @@ const register = (
   }
 };
 
-const registerTrailContours = (
+const registerTrailEntities = (
   trail: AnyTrail,
-  contours: Map<string, AnyContour>,
+  entities: Map<string, AnyEntity>,
   trails: Map<string, AnyTrail>,
   signals: Map<string, AnySignal>,
   resources: Map<string, AnyResource>
 ): void => {
-  for (const contour of trail.contours ?? []) {
-    register(contour, contours, trails, signals, resources);
+  for (const entity of trail.entities ?? []) {
+    register(entity, entities, trails, signals, resources);
   }
 };
 
@@ -451,13 +451,13 @@ const markUniqueObject = (
 
 const registerModuleValue = (
   value: unknown,
-  contours: Map<string, AnyContour>,
+  entities: Map<string, AnyEntity>,
   trails: Map<string, AnyTrail>,
   signals: Map<string, AnySignal>,
   resources: Map<string, AnyResource>
 ): void => {
   if (isResource(value) || isRegistrable(value)) {
-    register(value, contours, trails, signals, resources);
+    register(value, entities, trails, signals, resources);
   }
 
   if (isResource(value)) {
@@ -469,9 +469,9 @@ const registerModuleValue = (
     value !== null &&
     (value as { kind?: unknown }).kind === 'trail'
   ) {
-    registerTrailContours(
+    registerTrailEntities(
       value as AnyTrail,
-      contours,
+      entities,
       trails,
       signals,
       resources
@@ -481,7 +481,7 @@ const registerModuleValue = (
 
 const registerModuleValues = (
   mod: Record<string, unknown>,
-  contours: Map<string, AnyContour>,
+  entities: Map<string, AnyEntity>,
   trails: Map<string, AnyTrail>,
   signals: Map<string, AnySignal>,
   resources: Map<string, AnyResource>
@@ -491,7 +491,7 @@ const registerModuleValues = (
     if (!markUniqueObject(value, seenValues)) {
       continue;
     }
-    registerModuleValue(value, contours, trails, signals, resources);
+    registerModuleValue(value, entities, trails, signals, resources);
   }
 };
 
@@ -535,7 +535,7 @@ const hasRegistrableKind = (value: unknown): boolean => {
   }
   const { kind } = value as { kind?: unknown };
   return (
-    kind === 'contour' ||
+    kind === 'entity' ||
     kind === 'trail' ||
     kind === 'signal' ||
     kind === 'resource'
@@ -583,7 +583,7 @@ const disambiguateBrandedObserve = (options: TopoOptions): TopoOptions => {
  *   2. The shape does not look like `TopoOptions` (mixed keys or no
  *      keys) → module.
  *   3. The trailing arg is a registrable module export
- *      (`kind: 'trail' | 'contour' | …`) under a known option key →
+ *      (`kind: 'trail' | 'entity' | …`) under a known option key →
  *      module. Preserves the "module exporting a single trail named
  *      `observe`" case that the warden and existing apps rely on.
  *   4. The `observe` value is a bare `LogSink` or `TraceSink` (a sink
@@ -810,18 +810,18 @@ const topoImpl = (
   const observe = normalizeObserve(options?.observe);
   const layers = Object.freeze([...(options?.layers ?? [])]);
 
-  const contours = new Map<string, AnyContour>();
+  const entities = new Map<string, AnyEntity>();
   const trails = new Map<string, AnyTrail>();
   const signals = new Map<string, AnySignal>();
   const resources = new Map<string, AnyResource>();
 
   for (const mod of modules) {
-    registerModuleValues(mod, contours, trails, signals, resources);
+    registerModuleValues(mod, entities, trails, signals, resources);
   }
 
   return createTopo(
     identity,
-    contours,
+    entities,
     finalizeTrailSignals(trails, resources),
     signals,
     resources,

package/src/tracing.ts

@@ -28,6 +28,7 @@ export type SignalTraceRecordName =
 /** Activation boundary records emitted by runtime materializers. */
 export type ActivationTraceRecordName =
   | 'activation.cycle_detected'
+  | 'activation.queue'
   | 'activation.scheduled'
   | 'activation.webhook'
   | 'activation.webhook.invalid';