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

package/CHANGELOG.md

@@ -1,5 +1,63 @@
 # @ontrails/core
 
+## 1.0.0-beta.41
+
+## 1.0.0-beta.40
+
+### Minor Changes
+
+- [`1e64ee7`](https://github.com/outfitter-dev/trails/commit/1e64ee7bc270901486c5bb51ac38bf045c924adc): Add first-class queue activation sources with `queue()` in `@ontrails/core`.
+  Queue sources validate their runtime queue name and parse contract, project the
+  queue name into durable topo facts, participate in activation input
+  compatibility, and block established outputs when malformed.
+
+  Add `@ontrails/cloudflare/queues` with `cloudflareQueue`, `createMemoryQueue`,
+  and `createQueueHandler`. Cloudflare Workers now expose both `fetch` and
+  `queue` entrypoints from `createWorkersHandler`, resolve env-bound resources for
+  queue-activated trails, acknowledge successful/skipped/cancelled messages, and
+  acknowledge traced non-retryable Trails errors so permanently invalid messages
+  do not churn through the queue. Failures explicitly marked retryable enter
+  Cloudflare's retry and DLQ flow, with rate-limit delays preserved.
+
+  `@ontrails/warden` now treats queue activation sources as materialized and
+  requires `cloudflareQueue` public export example coverage.
+
+- [`5adb995`](https://github.com/outfitter-dev/trails/commit/5adb99551c2dda6190d46cce7f60bb08d63c99aa): Complete the v1 hard cutover from the authored `blaze` field to
+  `implementation` across trail contracts, surface projections, tests, examples,
+  and public source-analysis helpers. Existing applications must rename authored
+  trail behavior fields and direct trail-object access before upgrading.
+- [`6712075`](https://github.com/outfitter-dev/trails/commit/67120754df3f614c7f4dd98be1fa0ba9d69b7765): Complete the v1 hard cutover from the `contour` domain-object declaration
+  vocabulary to `entity` across contracts, topo facts, store helpers, Warden,
+  Wayfinder, operator surfaces, examples, and generated locks. Existing
+  applications must rename contour APIs, run `trails dev reset --yes` to discard
+  pre-cutover local Topographer snapshots, and then recompile committed
+  `trails.lock` artifacts before upgrading. Those derived snapshots are
+  intentionally not read through a compatibility layer.
+  The entity-shaped wire contract advances `TopoGraph` and split lock manifests
+  from schema version 3 to 4; old split artifacts fail with regeneration guidance,
+  while the canonical root `trails.lock` remains schema version 5.
+  Wayfinder reports those stale rows as topo-store drift while keeping current
+  committed lock facts available for inspection.
+
+### Patch Changes
+
+- [`9874e0b`](https://github.com/outfitter-dev/trails/commit/9874e0bb034c0f98edeb19833d9d3519c2a07a4c): Add `@ontrails/cloudflare/d1`, an env-bound Cloudflare D1 store resource for `@ontrails/store` definitions. The new subpath exports `cloudflareD1` and `connectD1`, supports the backend-agnostic store accessor contract (`get`, `list`, `upsert`, `remove`), versioned-table optimistic concurrency, fixture/mock seeding, store-derived write signals, Miniflare-backed conformance tests, and Worker env-bridge integration.
+
+  `@ontrails/core` and `@ontrails/store` no longer require the Bun global for signal fire ids or late-bound store signal tokens, so store definitions and store-derived signal emission work inside Worker modules. `@ontrails/warden` now treats `cloudflareD1` as a required Cloudflare public export with `@example` coverage.
+
+- [`3a65ae3`](https://github.com/outfitter-dev/trails/commit/3a65ae363e05b7589f4a9876da4346886353b48c): Rename the durable graph substrate package from `@ontrails/topographer` to
+  `@ontrails/topography` after folding Wayfind graph queries into that owner.
+
+  Update imports to `@ontrails/topography` or
+  `@ontrails/topography/backend-support`. The pre-1.0 cutover does not ship a
+  compatibility package. TopoGraph, lock, topo-store, semantic diff, and Wayfind
+  APIs keep their existing contracts, and the `trails wayfind` CLI and MCP names
+  remain unchanged.
+
+  The governed package-route transition moves legacy `@ontrails/wayfinder`
+  imports directly to `@ontrails/topography`; it does not emit the retired
+  intermediate `@ontrails/topographer` route.
+
 ## 1.0.0-beta.39
 
 ### Patch Changes

package/README.md

@@ -15,7 +15,7 @@ const greet = trail('greet', {
   examples: [
     { name: 'Hello', input: { name: 'World' }, expected: { message: 'Hello, World!' } },
   ],
-  blaze: (input) => Result.ok({ message: `Hello, ${input.name}!` }),
+  implementation: (input) => Result.ok({ message: `Hello, ${input.name}!` }),
 });
 
 const graph = topo('myapp', { greet });
@@ -27,7 +27,7 @@ Trails compose other trails through `composes` and `ctx.compose()`:
 const onboard = trail('entity.onboard', {
   composes: ['entity.add', 'entity.relate'],
   input: z.object({ name: z.string(), type: z.string() }),
-  blaze: async (input, ctx) => {
+  implementation: async (input, ctx) => {
     const added = await ctx.compose('entity.add', input);
     if (added.isErr()) return added;
     return Result.ok({ entity: added.value });
@@ -47,14 +47,14 @@ const onboard = trail('entity.onboard', {
 | `drainResources(resources, ctx, configValues?)` | Evict and dispose cached resource singletons for surface/test shutdown |
 | `blobRefSchema` / `createBlobRef(...)` | Declare and create binary output references with a shared descriptor contract |
 | `topo(name, ...modules, options?)` | Collect trail modules into a queryable topology with optional `observe:` sinks |
-| `deriveTrail(contour, operation, spec)` | Derive CRUD-shaped trail contracts from a contour on the `@ontrails/core/trails` subpath |
+| `deriveTrail(entity, operation, spec)` | Derive CRUD-shaped trail contracts from a entity on the `@ontrails/core/trails` subpath |
 | `validateTopo(topo)` | Structural validation: compose targets exist, no cycles, examples parse, output schemas present |
 
 ### Execution
 
 | Export | What it does |
 | --- | --- |
-| `executeTrail(trail, rawInput, options?)` | Centralized execution pipeline: validates input, builds context, composes layers, runs the blazed trail. Never throws -- exceptions become `Result.err(InternalError)`. |
+| `executeTrail(trail, rawInput, options?)` | Centralized execution pipeline: validates input, builds context, composes layers, runs the trail. Never throws -- exceptions become `Result.err(InternalError)`. |
 | `run(topo, id, input, options?)` | Headless trail execution by ID. Looks up the trail in the topo, then delegates to `executeTrail`. Returns `Result.err(NotFoundError)` if the ID is not registered. |
 
 ```typescript
@@ -154,7 +154,7 @@ The developer returns `Result.err(new NotFoundError(...))`. The framework maps i
 - **Execution layers** -- low-level pipeline wrappers via `composeLayers`
 - **Guards and collections** -- `isDefined`, `chunk`, `dedupe`, `groupBy`, `sortBy`
 - **Patterns** (`@ontrails/core/patterns`) -- reusable Zod schemas for pagination, bulk ops, timestamps, sorting
-- **Trail factories** (`@ontrails/core/trails`) -- derive CRUD-shaped trail contracts from contours without re-authoring IDs, schemas, examples, or intents
+- **Trail factories** (`@ontrails/core/trails`) -- derive CRUD-shaped trail contracts from entities without re-authoring IDs, schemas, examples, or intents
 - **Redaction** (`@ontrails/core/redaction`) -- strip sensitive data before logging
 
 ### Public helper boundaries
@@ -167,19 +167,19 @@ The root package also exposes a few low-level contracts that other framework pac
 
 See the [API Reference](../../docs/api-reference.md) for the full list.
 
-## Migration: topo-store moved to `@ontrails/topographer`
+## Migration: topo-store moved to `@ontrails/topography`
 
-Per [ADR-0042](../../docs/adr/0042-core-topographer-boundary-doctrine.md), the topo-store public API previously exported from `@ontrails/core` now lives in `@ontrails/topographer`. Generic `trails-db` helpers (`openReadTrailsDb`, `openWriteTrailsDb`, `ensureSubsystemSchema`, `deriveTrailsDbPath`, `deriveTrailsStateDir`, `deriveTrailsStateHome`, `deriveTrailsProjectKey`, `deriveTrailsDir`) stay in core because tracing and other subsystems share them.
+Per [ADR-0042](../../docs/adr/0042-core-topography-boundary-doctrine.md), the topo-store public API previously exported from `@ontrails/core` now lives in `@ontrails/topography`. Generic `trails-db` helpers (`openReadTrailsDb`, `openWriteTrailsDb`, `ensureSubsystemSchema`, `deriveTrailsDbPath`, `deriveTrailsStateDir`, `deriveTrailsStateHome`, `deriveTrailsProjectKey`, `deriveTrailsDir`) stay in core because tracing and other subsystems share them.
 
 Update consumer imports:
 
 ```diff
 - import { topoStore, createTopoStore, createMockTopoStore, createTopoSnapshot, listTopoSnapshots, pinTopoSnapshot, unpinTopoSnapshot, createStoredTopoSnapshot, getStoredTopoExport, countTopoSnapshots, countPinnedSnapshots, countPrunableSnapshots, pruneUnpinnedSnapshots } from '@ontrails/core';
-+ import { topoStore, createTopoStore, createMockTopoStore, createTopoSnapshot, listTopoSnapshots, pinTopoSnapshot, unpinTopoSnapshot } from '@ontrails/topographer';
-+ import { createStoredTopoSnapshot, getStoredTopoExport, countTopoSnapshots, countPinnedSnapshots, countPrunableSnapshots, pruneUnpinnedSnapshots } from '@ontrails/topographer/backend-support';
++ import { topoStore, createTopoStore, createMockTopoStore, createTopoSnapshot, listTopoSnapshots, pinTopoSnapshot, unpinTopoSnapshot } from '@ontrails/topography';
++ import { createStoredTopoSnapshot, getStoredTopoExport, countTopoSnapshots, countPinnedSnapshots, countPrunableSnapshots, pruneUnpinnedSnapshots } from '@ontrails/topography/backend-support';
 ```
 
-Types `ReadOnlyTopoStore`, `MockTopoStoreSeed`, `TopoSnapshot`, `TopoStoreRef`, `TopoStoreExportRecord`, `TopoStoreResourceRecord`, `TopoStoreTrailRecord`, `TopoStoreTrailDetailRecord`, `CreateTopoSnapshotInput`, and `ListTopoSnapshotsOptions` move to `@ontrails/topographer`. `StoredTopoExport` moves to `@ontrails/topographer/backend-support`.
+Types `ReadOnlyTopoStore`, `MockTopoStoreSeed`, `TopoSnapshot`, `TopoStoreRef`, `TopoStoreExportRecord`, `TopoStoreResourceRecord`, `TopoStoreTrailRecord`, `TopoStoreTrailDetailRecord`, `CreateTopoSnapshotInput`, and `ListTopoSnapshotsOptions` move to `@ontrails/topography`. `StoredTopoExport` moves to `@ontrails/topography/backend-support`.
 
 ## Installation
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ontrails/core",
-  "version": "1.0.0-beta.39",
+  "version": "1.0.0-beta.41",
   "files": [
     "src/**/*.ts",
     "!src/**/__tests__/**",

package/src/activation-provenance.ts

@@ -12,6 +12,7 @@ export interface ActivationProvenanceSource {
   readonly kind: ActivationSourceKind;
   readonly meta?: ActivationSourceMeta | undefined;
   readonly producerTrailId?: string | undefined;
+  readonly queue?: string | undefined;
   readonly timezone?: string | undefined;
 }
 
@@ -41,6 +42,7 @@ const isActivationProvenanceSource = (
   typeof value['kind'] === 'string' &&
   optionalString(value['cron']) &&
   optionalString(value['producerTrailId']) &&
+  optionalString(value['queue']) &&
   optionalString(value['timezone']) &&
   (value['meta'] === undefined || isObjectRecord(value['meta']));
 
@@ -100,6 +102,9 @@ export const buildActivationProvenanceTraceAttrs = (
     attrs['trails.activation.source.producer_trail.id'] =
       activation.source.producerTrailId;
   }
+  if (activation.source.queue !== undefined) {
+    attrs['trails.activation.source.queue'] = activation.source.queue;
+  }
   if (activation.source.cron !== undefined) {
     attrs['trails.activation.source.cron'] = activation.source.cron;
   }

package/src/activation-source-projection.ts

@@ -159,6 +159,12 @@ export const projectActivationSourceDeclaration = (
       record['payloadSchema'] = toSortedJsonSchema(source.payload);
     }
   }
+  if (source.queue !== undefined) {
+    record['queue'] =
+      typeof source.queue === 'string'
+        ? source.queue.trim()
+        : canonicalize(source.queue);
+  }
   if (source.timezone !== undefined) {
     record['timezone'] = source.timezone;
   }

package/src/activation-source.ts

@@ -3,6 +3,7 @@ import type { z } from 'zod';
 import type { AnySignal } from './signal.js';
 
 export const activationSourceKinds = Object.freeze([
+  'queue',
   'signal',
   'schedule',
   'webhook',
@@ -31,6 +32,7 @@ export interface ActivationSource {
   readonly parse?: ActivationSourceParse | undefined;
   readonly path?: string | undefined;
   readonly payload?: z.ZodType<unknown> | undefined;
+  readonly queue?: string | undefined;
   readonly timezone?: string | undefined;
   readonly verify?: unknown;
 }

package/src/compose-batch.ts

@@ -43,7 +43,7 @@ export const normalizeComposeBatchConcurrency = (
 /**
  * Produce one validation-error result per call, preserving the original
  * call order. Used when `normalizeComposeBatchConcurrency` fails so the caller
- * can surface a uniform batch shape to the blaze.
+ * can surface a uniform batch shape to the implementation.
  */
 export const createComposeBatchValidationResults = <TCall>(
   calls: readonly TCall[],

package/src/draft.ts

@@ -1,5 +1,5 @@
-import type { AnyContour } from './contour.js';
-import { getContourReferences } from './contour.js';
+import type { AnyEntity } from './entity.js';
+import { getEntityReferences } from './entity.js';
 import { ValidationError } from './errors.js';
 import type { AnySignal } from './signal.js';
 import type { AnyResource } from './resource.js';
@@ -11,7 +11,7 @@ export const DRAFT_ID_PREFIX = '_draft.';
 
 export type DraftDependencyKind =
   | 'compose'
-  | 'contour'
+  | 'entity'
   | 'resource'
   | 'replaced-by'
   | 'schema-reference'
@@ -27,7 +27,7 @@ export interface DraftDependency {
 
 export interface DraftDiagnostic {
   readonly id: string;
-  readonly kind: 'contour' | 'resource' | 'signal' | 'trail' | 'unknown';
+  readonly kind: 'entity' | 'resource' | 'signal' | 'trail' | 'unknown';
   readonly message: string;
   readonly rule: 'draft-contamination' | 'draft-id';
   readonly via?: DraftDependencyKind | undefined;
@@ -54,7 +54,7 @@ interface DraftReason {
   readonly via: DraftDependencyKind;
 }
 
-type TopoNode = AnyContour | AnyResource | AnySignal | AnyTrail;
+type TopoNode = AnyEntity | AnyResource | AnySignal | AnyTrail;
 
 const replacedByTarget = (value: TopoNode): string | undefined => {
   const raw = value as unknown as { replacedBy?: unknown };
@@ -93,8 +93,8 @@ const dependencyFromTarget = (
 const trailDependencies = (trail: AnyTrail): DraftDependency[] => [
   ...dependenciesFromIds(
     trail.id,
-    (trail.contours ?? []).map((contour) => contour.name),
-    'contour'
+    (trail.entities ?? []).map((entity) => entity.name),
+    'entity'
   ),
   ...dependenciesFromIds(trail.id, trail.composes, 'compose'),
   ...dependenciesFromIds(
@@ -107,10 +107,10 @@ const trailDependencies = (trail: AnyTrail): DraftDependency[] => [
   ...dependencyFromTarget(trail.id, replacedByTarget(trail), 'replaced-by'),
 ];
 
-const contourDependencies = (contour: AnyContour): DraftDependency[] =>
+const entityDependencies = (entity: AnyEntity): DraftDependency[] =>
   dependenciesFromIds(
-    contour.name,
-    getContourReferences(contour).map((reference) => reference.contour),
+    entity.name,
+    getEntityReferences(entity).map((reference) => reference.entity),
     'schema-reference'
   );
 
@@ -124,13 +124,13 @@ const resourceDependencies = (resource: AnyResource): DraftDependency[] =>
 
 const nodeKind = (
   id: string,
-  contours: ReadonlyMap<string, AnyContour>,
+  entities: ReadonlyMap<string, AnyEntity>,
   trails: ReadonlyMap<string, AnyTrail>,
   signals: ReadonlyMap<string, AnySignal>,
   resources: ReadonlyMap<string, AnyResource>
 ): DraftDiagnostic['kind'] => {
-  if (contours.has(id)) {
-    return 'contour';
+  if (entities.has(id)) {
+    return 'entity';
   }
   if (trails.has(id)) {
     return 'trail';
@@ -152,7 +152,7 @@ const draftIdsFromKeys = (keys: Iterable<string>): string[] =>
 
 const collectDeclaredDraftIds = (topo: Topo): ReadonlySet<string> =>
   new Set([
-    ...draftIdsFromKeys(topo.contours.keys()),
+    ...draftIdsFromKeys(topo.entities.keys()),
     ...draftIdsFromKeys(topo.trails.keys()),
     ...draftIdsFromKeys(topo.signals.keys()),
     ...draftIdsFromKeys(topo.resources.keys()),
@@ -248,7 +248,7 @@ const contaminationFindingForId = (
   id: string,
   declaredDraftIds: ReadonlySet<string>,
   reasons: ReadonlyMap<string, DraftReason>,
-  contours: ReadonlyMap<string, AnyContour>,
+  entities: ReadonlyMap<string, AnyEntity>,
   trails: ReadonlyMap<string, AnyTrail>,
   signals: ReadonlyMap<string, AnySignal>,
   resources: ReadonlyMap<string, AnyResource>
@@ -264,7 +264,7 @@ const contaminationFindingForId = (
 
   return findingForContamination(
     id,
-    nodeKind(id, contours, trails, signals, resources),
+    nodeKind(id, entities, trails, signals, resources),
     reason
   );
 };
@@ -273,7 +273,7 @@ const collectFindings = (
   declaredDraftIds: ReadonlySet<string>,
   contaminatedIds: ReadonlySet<string>,
   reasons: ReadonlyMap<string, DraftReason>,
-  contours: ReadonlyMap<string, AnyContour>,
+  entities: ReadonlyMap<string, AnyEntity>,
   trails: ReadonlyMap<string, AnyTrail>,
   signals: ReadonlyMap<string, AnySignal>,
   resources: ReadonlyMap<string, AnyResource>
@@ -281,14 +281,14 @@ const collectFindings = (
   ...[...declaredDraftIds]
     .toSorted()
     .map((id) =>
-      findingForDraftId(id, nodeKind(id, contours, trails, signals, resources))
+      findingForDraftId(id, nodeKind(id, entities, trails, signals, resources))
     ),
   ...[...contaminatedIds].toSorted().flatMap((id) => {
     const finding = contaminationFindingForId(
       id,
       declaredDraftIds,
       reasons,
-      contours,
+      entities,
       trails,
       signals,
       resources
@@ -299,7 +299,7 @@ const collectFindings = (
 ];
 
 const collectDependencies = (topo: Topo): DraftDependency[] => [
-  ...[...topo.contours.values()].flatMap(contourDependencies),
+  ...[...topo.entities.values()].flatMap(entityDependencies),
   ...[...topo.trails.values()].flatMap(trailDependencies),
   ...[...topo.signals.values()].flatMap(signalDependencies),
   ...[...topo.resources.values()].flatMap(resourceDependencies),
@@ -316,7 +316,7 @@ export const deriveDraftReport = (topo: Topo): DraftReport => {
     declaredDraftIds,
     contaminatedIds,
     reasons,
-    topo.contours,
+    topo.entities,
     topo.trails,
     topo.signals,
     topo.resources