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

package/src/{contour.ts → entity.ts}

@@ -3,22 +3,22 @@ import { z } from 'zod';
 import type { Branded } from './branded.js';
 
 /**
- * Runtime options for a contour declaration.
+ * Runtime options for an entity declaration.
  */
-export interface ContourOptions<
+export interface EntityOptions<
   TShape extends z.ZodRawShape,
   TIdentity extends keyof TShape & string,
 > {
-  /** Field name that acts as the contour's primary identity. */
+  /** Field name that acts as the entity's primary identity. */
   readonly identity: TIdentity;
-  /** Example instances validated against the contour schema at declaration time. */
+  /** Example instances validated against the entity schema at declaration time. */
   readonly examples?: readonly z.output<z.ZodObject<TShape>>[] | undefined;
-  /** Reserved for future contour-specific design; trail versioning is trail-only. */
+  /** Reserved for future entity-specific design; trail versioning is trail-only. */
   readonly version?: never;
 }
 
-/** Type-level brand name applied to a contour's identity schema. */
-export type ContourIdBrand<TName extends string> = `${Capitalize<TName>}Id`;
+/** Type-level brand name applied to an entity's identity schema. */
+export type EntityIdBrand<TName extends string> = `${Capitalize<TName>}Id`;
 
 type BrandedSchema<
   TSchema extends z.core.$ZodType,
@@ -29,71 +29,71 @@ type BrandableSchema<TSchema extends z.core.$ZodType> = TSchema & {
   brand<TBrand extends string>(): BrandedSchema<TSchema, TBrand>;
 };
 
-/** Output value of a branded contour identity schema. */
-export type ContourIdValue<
+/** Output value of a branded entity identity schema. */
+export type EntityIdValue<
   TSchema extends z.core.$ZodType,
   TName extends string,
-> = Branded<z.output<TSchema>, ContourIdBrand<TName>>;
+> = Branded<z.output<TSchema>, EntityIdBrand<TName>>;
 
-/** Runtime metadata attached to schemas returned from `contour.id()`. */
-export interface ContourIdMetadata<
+/** Runtime metadata attached to schemas returned from `entity.id()`. */
+export interface EntityIdMetadata<
   TName extends string = string,
   TIdentity extends string = string,
 > {
-  readonly contour: TName;
+  readonly entity: TName;
   readonly identity: TIdentity;
 }
 
-/** A structural contour reference declared by another contour field schema. */
-export interface ContourReference<
+/** A structural entity reference declared by another entity field schema. */
+export interface EntityReference<
   TName extends string = string,
   TIdentity extends string = string,
-> extends ContourIdMetadata<TName, TIdentity> {
+> extends EntityIdMetadata<TName, TIdentity> {
   readonly field: string;
 }
 
-/** Symbol used to tag branded contour reference schemas at runtime. */
-export const CONTOUR_ID_METADATA = Symbol.for('@ontrails/core/contour-id');
+/** Symbol used to tag branded entity reference schemas at runtime. */
+export const ENTITY_ID_METADATA = Symbol.for('@ontrails/core/entity-id');
 
 /**
- * Module-level WeakMap storing contour identity metadata keyed by schema object.
+ * Module-level WeakMap storing entity identity metadata keyed by schema object.
  *
- * First-write-wins: when multiple contours share the same underlying schema
- * (e.g. `contour('admin', { id: user.shape.id }, ...)`), the first contour to
+ * First-write-wins: when multiple entities share the same underlying schema
+ * (e.g. `entity('admin', { id: user.shape.id }, ...)`), the first entity to
  * brand the schema claims it. Subsequent calls skip the write to prevent
  * silent metadata corruption.
  */
-const contourIdMetadata = new WeakMap<object, ContourIdMetadata>();
+const entityIdMetadata = new WeakMap<object, EntityIdMetadata>();
 
 /**
- * A contour identity schema branded for one contour and tagged with runtime
+ * An entity identity schema branded for one entity and tagged with runtime
  * metadata so the topo layer can recognize declared references later on.
  */
-export type ContourIdSchema<
+export type EntityIdSchema<
   TSchema extends z.core.$ZodType = z.core.$ZodType,
   TName extends string = string,
   TIdentity extends string = string,
-> = BrandedSchema<TSchema, ContourIdBrand<TName>> & {
-  /** @deprecated Use `getContourIdMetadata()` — metadata lives in a WeakMap, not on the schema. */
-  readonly [CONTOUR_ID_METADATA]?: ContourIdMetadata<TName, TIdentity>;
+> = BrandedSchema<TSchema, EntityIdBrand<TName>> & {
+  /** @deprecated Use `getEntityIdMetadata()` — metadata lives in a WeakMap, not on the schema. */
+  readonly [ENTITY_ID_METADATA]?: EntityIdMetadata<TName, TIdentity>;
 };
 
 /**
  * A first-class domain object with schema, identity metadata, and examples.
  *
- * A contour behaves like the `ZodObject` it wraps, so standard Zod composition
+ * An entity behaves like the `ZodObject` it wraps, so standard Zod composition
  * helpers such as `.pick()`, `.extend()`, and `.array()` continue to work.
  */
-export type Contour<
+export type Entity<
   TName extends string = string,
   TShape extends z.ZodRawShape = z.ZodRawShape,
   TIdentity extends keyof TShape & string = keyof TShape & string,
 > = z.ZodObject<TShape> & {
-  readonly kind: 'contour';
+  readonly kind: 'entity';
   readonly name: TName;
   readonly identity: TIdentity;
   readonly identitySchema: TShape[TIdentity];
-  readonly id: () => ContourIdSchema<TShape[TIdentity], TName, TIdentity>;
+  readonly id: () => EntityIdSchema<TShape[TIdentity], TName, TIdentity>;
   readonly examples?: readonly z.output<z.ZodObject<TShape>>[] | undefined;
 };
 
@@ -115,7 +115,7 @@ const assertIdentityField = <
 ): void => {
   if (!Object.hasOwn(shape, identity)) {
     throw new TypeError(
-      `contour("${name}") identity "${identity}" must match a declared field`
+      `entity("${name}") identity "${identity}" must match a declared field`
     );
   }
 };
@@ -129,7 +129,7 @@ const assertExamples = <TShape extends z.ZodRawShape>(
     const parsed = schema.safeParse(example);
     if (!parsed.success) {
       throw new TypeError(
-        `contour("${name}") example ${index} is invalid: ${formatExampleIssues(parsed.error.issues)}`
+        `entity("${name}") example ${index} is invalid: ${formatExampleIssues(parsed.error.issues)}`
       );
     }
   }
@@ -150,28 +150,28 @@ const brandIdentitySchema = <
   TName extends string,
   TIdentity extends string,
 >(
-  contour: TName,
+  entity: TName,
   identity: TIdentity,
   schema: TSchema
-): ContourIdSchema<TSchema, TName, TIdentity> => {
+): EntityIdSchema<TSchema, TName, TIdentity> => {
   const branded = (schema as BrandableSchema<TSchema>).brand<
-    ContourIdBrand<TName>
+    EntityIdBrand<TName>
   >();
 
-  // First-write-wins: if another contour already claimed this schema object
+  // First-write-wins: if another entity already claimed this schema object
   // (possible when Zod v4 brand() returns `this`), preserve the original
   // metadata rather than silently overwriting it.
-  if (!contourIdMetadata.has(branded)) {
-    contourIdMetadata.set(branded, {
-      contour,
+  if (!entityIdMetadata.has(branded)) {
+    entityIdMetadata.set(branded, {
+      entity,
       identity,
-    } satisfies ContourIdMetadata<TName, TIdentity>);
+    } satisfies EntityIdMetadata<TName, TIdentity>);
   }
 
-  return branded as ContourIdSchema<TSchema, TName, TIdentity>;
+  return branded as EntityIdSchema<TSchema, TName, TIdentity>;
 };
 
-const attachContourMetadata = <
+const attachEntityMetadata = <
   TName extends string,
   TShape extends z.ZodRawShape,
   TIdentity extends keyof TShape & string,
@@ -179,7 +179,7 @@ const attachContourMetadata = <
   schema: z.ZodObject<TShape>,
   metadata: {
     readonly examples?: readonly z.output<z.ZodObject<TShape>>[] | undefined;
-    readonly idSchema: ContourIdSchema<TShape[TIdentity], TName, TIdentity>;
+    readonly idSchema: EntityIdSchema<TShape[TIdentity], TName, TIdentity>;
     readonly identity: TIdentity;
     readonly identitySchema: TShape[TIdentity];
     readonly name: TName;
@@ -208,7 +208,7 @@ const attachContourMetadata = <
     },
     kind: {
       enumerable: true,
-      value: 'contour',
+      value: 'entity',
       writable: false,
     },
     name: {
@@ -219,10 +219,10 @@ const attachContourMetadata = <
   });
 };
 
-/** Read contour identity metadata from the module-level WeakMap, if present. */
-const readMetadata = (schema: unknown): ContourIdMetadata | undefined =>
+/** Read entity identity metadata from the module-level WeakMap, if present. */
+const readMetadata = (schema: unknown): EntityIdMetadata | undefined =>
   typeof schema === 'object' && schema !== null
-    ? contourIdMetadata.get(schema)
+    ? entityIdMetadata.get(schema)
     : undefined;
 
 /** Resolve the inner schema from a Zod wrapper (ZodOptional, ZodNullable, etc.). */
@@ -232,13 +232,13 @@ const unwrapInner = (schema: unknown): unknown => {
 };
 
 /**
- * Walk through Zod wrapper layers searching for `CONTOUR_ID_METADATA`.
+ * Walk through Zod wrapper layers searching for `ENTITY_ID_METADATA`.
  *
  * `.nullish()` produces `ZodOptional<ZodNullable<T>>` — two wrapper levels —
  * so a single-step unwrap is insufficient. This iterates until it finds the
  * metadata or exhausts all wrapper layers.
  */
-const unwrapToMetadata = (schema: unknown): ContourIdMetadata | undefined => {
+const unwrapToMetadata = (schema: unknown): EntityIdMetadata | undefined => {
   let current: unknown = schema;
   while (typeof current === 'object' && current !== null) {
     const inner = unwrapInner(current);
@@ -255,28 +255,28 @@ const unwrapToMetadata = (schema: unknown): ContourIdMetadata | undefined => {
 };
 
 /**
- * Read contour-reference metadata from a schema returned by `contour.id()`.
+ * Read entity-reference metadata from a schema returned by `entity.id()`.
  *
  * When the schema is wrapped by Zod combinators (`.optional()`, `.nullable()`,
- * `.default()`, `.nullish()`, etc.) the `CONTOUR_ID_METADATA` symbol lives on
+ * `.default()`, `.nullish()`, etc.) the `ENTITY_ID_METADATA` symbol lives on
  * the inner schema, not on the wrapper. The unwrap handles arbitrarily nested
  * wrapper levels.
  */
-export const getContourIdMetadata = (
+export const getEntityIdMetadata = (
   schema: unknown
-): ContourIdMetadata | undefined =>
+): EntityIdMetadata | undefined =>
   readMetadata(schema) ?? unwrapToMetadata(schema);
 
-/** Inspect a contour schema for fields that reference other contours via `.id()`. */
-export const getContourReferences = (
-  contour: AnyContour
-): readonly ContourReference[] =>
-  Object.entries(contour.shape)
+/** Inspect an entity schema for fields that reference other entities via `.id()`. */
+export const getEntityReferences = (
+  entity: AnyEntity
+): readonly EntityReference[] =>
+  Object.entries(entity.shape)
     .flatMap(([field, schema]) => {
-      if (field === contour.identity) {
+      if (field === entity.identity) {
         return [];
       }
-      const metadata = getContourIdMetadata(schema);
+      const metadata = getEntityIdMetadata(schema);
       if (metadata === undefined) {
         return [];
       }
@@ -285,16 +285,16 @@ export const getContourReferences = (
     })
     .toSorted((left, right) =>
       left.field === right.field
-        ? left.contour.localeCompare(right.contour)
+        ? left.entity.localeCompare(right.entity)
         : left.field.localeCompare(right.field)
     );
 
 /**
- * Create a contour definition from a raw Zod object shape.
+ * Create an entity definition from a raw Zod object shape.
  *
  * @example
  * ```typescript
- * const user = contour(
+ * const user = entity(
  *   'user',
  *   {
  *     id: z.string().uuid(),
@@ -305,15 +305,15 @@ export const getContourReferences = (
  * );
  * ```
  */
-export const contour = <
+export const entity = <
   TName extends string,
   TShape extends z.ZodRawShape,
   TIdentity extends keyof TShape & string,
 >(
   name: TName,
   shape: TShape,
-  options: ContourOptions<TShape, TIdentity>
-): Contour<TName, TShape, TIdentity> => {
+  options: EntityOptions<TShape, TIdentity>
+): Entity<TName, TShape, TIdentity> => {
   assertIdentityField(name, shape, options.identity);
 
   const schema = z.object(shape);
@@ -322,7 +322,7 @@ export const contour = <
   const identitySchema = shape[options.identity];
   if (!identitySchema) {
     throw new TypeError(
-      `contour("${name}") identity "${options.identity}" must resolve to a schema`
+      `entity("${name}") identity "${options.identity}" must resolve to a schema`
     );
   }
 
@@ -331,7 +331,7 @@ export const contour = <
     ? Object.freeze([...options.examples])
     : undefined;
 
-  attachContourMetadata(schema, {
+  attachEntityMetadata(schema, {
     examples,
     idSchema,
     identity: options.identity,
@@ -339,8 +339,8 @@ export const contour = <
     name,
   });
 
-  return schema as Contour<TName, TShape, TIdentity>;
+  return schema as Entity<TName, TShape, TIdentity>;
 };
 
-/** Existential type for heterogeneous contour collections. */
-export type AnyContour = Contour<string, z.ZodRawShape, string>;
+/** Existential type for heterogeneous entity collections. */
+export type AnyEntity = Entity<string, z.ZodRawShape, string>;

package/src/execute.ts

@@ -103,7 +103,7 @@ export interface ExecuteTrailOptions {
   /**
    * Typed layers supplied for this execution.
    *
-   * Layers compose around the blaze. Layers without `input`
+   * Layers compose around the implementation. Layers without `input`
    * schemas are surface-invisible wrappers for concerns such as tenant guards,
    * rate limiting, circuit breaking, or custom audit logging.
    */
@@ -113,7 +113,7 @@ export interface ExecuteTrailOptions {
    *
    * Surfaces (CLI, MCP, HTTP) forward their `layers` option here so they
    * compose around every trail dispatched through that surface. The final
-   * composition order is `topo → surface → trail → blaze` (outermost-first).
+   * composition order is `topo → surface → trail → implementation` (outermost-first).
    */
   readonly surfaceLayers?: readonly Layer[] | undefined;
   /**
@@ -121,7 +121,7 @@ export interface ExecuteTrailOptions {
    *
    * The CLI/MCP/HTTP surfaces typically forward `topo.layers` here so the
    * topo's declared layers wrap every trail invocation. The final
-   * composition order is `topo → surface → trail → blaze` (outermost-first).
+   * composition order is `topo → surface → trail → implementation` (outermost-first).
    */
   readonly topoLayers?: readonly Layer[] | undefined;
   /** Factory that produces a base TrailContext (takes precedence over defaults). */
@@ -1117,22 +1117,22 @@ const runDetourRecovery = async (
 };
 
 /**
- * Wrap a blaze with the detour recovery loop.
+ * Wrap an implementation with the detour recovery loop.
  *
- * If the trail has no detours, returns the blaze unchanged (no wrapper overhead).
- * The detour loop runs inside the layer stack, closest to the blaze.
+ * If the trail has no detours, returns the implementation unchanged (no wrapper overhead).
+ * The detour loop runs inside the layer stack, closest to the implementation.
  */
 const wrapWithDetours = (
-  blaze: Implementation<unknown, unknown>,
+  implementation: Implementation<unknown, unknown>,
   /* oxlint-disable-next-line no-explicit-any -- existential detour array from AnyTrail */
   detours: readonly Detour<any, any, TrailsError>[]
 ): Implementation<unknown, unknown> => {
   if (detours.length === 0) {
-    return blaze;
+    return implementation;
   }
 
   return async (input, ctx) => {
-    const result = await blaze(input, ctx);
+    const result = await implementation(input, ctx);
     if (result.isOk()) {
       return result;
     }
@@ -1189,11 +1189,11 @@ const prepareRunImpl = (
     options,
     trail.id
   );
-  // Detour loop wraps the blaze (inside layer stack, closest to blaze)
+  // Detour loop wraps the implementation (inside layer stack, closest to implementation)
   let impl = wrapWithDetours(
     bindFireAtLayerBoundary(
       bindComposeAtLayerBoundary(
-        trail.blaze as Implementation<unknown, unknown>,
+        trail.implementation as Implementation<unknown, unknown>,
         topo,
         options
       ),
@@ -1302,9 +1302,9 @@ const runTrail = async (
 /**
  * Compose the typed layers attached at topo, surface, and trail scope.
  *
- * Composition order is topo → surface → trail → execution-supplied → blaze
+ * Composition order is topo → surface → trail → execution-supplied → implementation
  * (outermost-first): trail-scope layers run inside surface/topo layers, and
- * `executeTrail({ layers })` layers wrap closest to the blaze for per-call
+ * `executeTrail({ layers })` layers wrap closest to the implementation for per-call
  * behavior.
  */
 const composeAttachedLayers = (
@@ -1352,7 +1352,7 @@ const createForkTrailVersion = (
   entry: TrailVersionForkEntry
 ): AnyTrail => {
   const {
-    blaze: _blaze,
+    implementation: _implementation,
     composeInput: _composeInput,
     composes: _composes,
     detours: _detours,
@@ -1366,12 +1366,12 @@ const createForkTrailVersion = (
 
   return Object.freeze({
     ...base,
-    blaze: entry.blaze,
     composes: Object.freeze([...(entry.composes ?? [])]),
     detours: Object.freeze([...(entry.detours ?? [])]),
     ...(entry.composeInput === undefined
       ? {}
       : { composeInput: entry.composeInput }),
+    implementation: entry.implementation,
     input: entry.input,
     output: entry.output,
     resources: Object.freeze([...(entry.resources ?? [])]),

package/src/fire.ts

@@ -98,6 +98,9 @@ const frameworkFireFns = new WeakSet<FireFn>();
 export const isFrameworkFireFn = (fire: FireFn | undefined): boolean =>
   fire !== undefined && frameworkFireFns.has(fire);
 
+const createFireId = (): string =>
+  typeof Bun === 'undefined' ? crypto.randomUUID() : Bun.randomUUIDv7();
+
 type FireDispatchTracker = Set<Promise<void>>;
 
 const getFireDispatchTracker = (
@@ -284,7 +287,7 @@ const deriveFireDiagnosticMetadata = (
 ): FireDiagnosticMetadata => {
   const trace = producerCtx ? getTraceContext(producerCtx) : undefined;
   const parent = getActivationProvenance(producerCtx);
-  const fireId = Bun.randomUUIDv7();
+  const fireId = createFireId();
   return {
     activation: {
       fireId,
@@ -978,7 +981,7 @@ export const createFireFn = (
     // Pre-bind fire on the consumer ctx as a safety net for direct
     // executeTrail calls that skip the topo-aware path. In the normal
     // fan-out flow below, bindFireToCtx in execute.ts rebinds fire to
-    // the fully-traced ctx before the blaze runs, so this assignment
+    // the fully-traced ctx before the implementation runs, so this assignment
     // is superseded — but keeping it makes consumerCtx self-sufficient
     // for any caller that inspects it pre-execution.
     fire: createFireFn(

package/src/index.ts

@@ -222,7 +222,7 @@ export {
 } from './version-resolution.js';
 export type {
   AnyTrail,
-  BlazeInput,
+  ImplementationInput,
   Intent,
   Trail,
   TrailVersionEntry,
@@ -300,6 +300,8 @@ export { inputOf, outputOf } from './type-utils.js';
 // Signal
 export { signal } from './signal.js';
 export type { AnySignal, Signal, SignalSpec } from './signal.js';
+export { queue, validateQueueSource } from './queue.js';
+export type { QueueSource, QueueSpec, QueueValidationIssue } from './queue.js';
 export { schedule, validateScheduleSource } from './schedule.js';
 export type {
   ScheduleSource,
@@ -398,23 +400,23 @@ export type {
   LateBoundSignalRef,
 } from './signal-ref.js';
 
-// Contour
-export { contour } from './contour.js';
+// Entity
+export { entity } from './entity.js';
 export {
-  CONTOUR_ID_METADATA,
-  getContourIdMetadata,
-  getContourReferences,
-} from './contour.js';
+  ENTITY_ID_METADATA,
+  getEntityIdMetadata,
+  getEntityReferences,
+} from './entity.js';
 export type {
-  AnyContour,
-  Contour,
-  ContourIdBrand,
-  ContourIdMetadata,
-  ContourIdSchema,
-  ContourIdValue,
-  ContourOptions,
-  ContourReference,
-} from './contour.js';
+  AnyEntity,
+  Entity,
+  EntityIdBrand,
+  EntityIdMetadata,
+  EntityIdSchema,
+  EntityIdValue,
+  EntityOptions,
+  EntityReference,
+} from './entity.js';
 
 // Topo
 export { topo } from './topo.js';
@@ -447,7 +449,7 @@ export type {
 
 // Generic trails-db helpers (shared framework infrastructure per ADR-0014).
 // The topo-store public API that previously lived here moved to
-// `@ontrails/topographer` per ADR-0042.
+// `@ontrails/topography` per ADR-0042.
 export {
   deriveTrailsDbPath,
   deriveTrailsDir,

package/src/layer.ts

@@ -8,7 +8,7 @@ import type { Implementation } from './types.js';
 // ---------------------------------------------------------------------------
 
 /**
- * A composable, named layer that wraps blazes.
+ * A composable, named layer that wraps implementations.
  *
  * Layers attach at trail, surface, or topo scope and may declare an object
  * `input` schema describing the configuration they need from the surrounding

package/src/observe.ts

@@ -28,7 +28,7 @@ export interface TopoOptions {
    * Layers declared here wrap every trail invoked through this topo, on every
    * surface. The execution pipeline composes topo-scope layers outermost —
    * around surface-scope and trail-scope layers — so the final order is
-   * `topo → surface → trail → blaze` (outermost-first).
+   * `topo → surface → trail → implementation` (outermost-first).
    */
   readonly layers?: readonly Layer[] | undefined;
 }