@ontrails/core 1.0.0-beta.5 → 1.0.0-beta.50

package/README.md

@@ -15,20 +15,20 @@ const greet = trail('greet', {
   examples: [
     { name: 'Hello', input: { name: 'World' }, expected: { message: 'Hello, World!' } },
   ],
-  run: (input) => Result.ok({ message: `Hello, ${input.name}!` }),
+  implementation: (input) => Result.ok({ message: `Hello, ${input.name}!` }),
 });
 
-const app = topo('myapp', { greet });
+const graph = topo('myapp', { greet });
 ```
 
-Trails compose other trails through `follow` and `ctx.follow()`:
+Trails compose other trails through `composes` and `ctx.compose()`:
 
 ```typescript
 const onboard = trail('entity.onboard', {
-  follow: ['entity.add', 'entity.relate'],
+  composes: ['entity.add', 'entity.relate'],
   input: z.object({ name: z.string(), type: z.string() }),
-  run: async (input, ctx) => {
-    const added = await ctx.follow('entity.add', input);
+  implementation: async (input, ctx) => {
+    const added = await ctx.compose('entity.add', input);
     if (added.isErr()) return added;
     return Result.ok({ entity: added.value });
   },
@@ -41,10 +41,42 @@ const onboard = trail('entity.onboard', {
 
 | Export | What it does |
 | --- | --- |
-| `trail(id, spec)` | Define a unit of work with typed input and `Result` output; use `follow` for composition |
-| `event(id, spec)` | Define a server-originated push with a typed data schema |
-| `topo(name, ...modules)` | Collect trail modules into a queryable topology |
-| `validateTopo(topo)` | Structural validation: follow targets exist, no cycles, examples parse, output schemas present |
+| `trail(id, spec)` | Define a unit of work with typed input and `Result` output; use `composes` for composition |
+| `signal(id, spec)` | Define a server-originated notification with a typed data schema |
+| `resource(id, spec)` | Define an infrastructure dependency with `create`, `dispose`, and optional `mock` |
+| `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(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 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
+// executeTrail — surfaces use this directly
+const surfaceResult = await executeTrail(greet, { name: 'Alice' });
+
+// run — headless execution by trail ID
+const runResult = await run(graph, 'greet', { name: 'Alice' });
+if (runResult.isOk()) console.log(runResult.value);
+```
+
+### Topo accessors
+
+Beyond the `trail(id, spec)` builder, `Topo` exposes these accessors:
+
+| Accessor | What it returns |
+| --- | --- |
+| `topo.ids()` | `string[]` of all registered trail IDs |
+| `topo.count` | Number of registered trails |
+| `topo.get(id)` | The `Trail` with that ID, or `undefined` |
+| `topo.has(id)` | Whether a trail ID is registered |
+| `topo.list()` | All registered trails as an array |
 
 ### Type utilities
 
@@ -52,9 +84,17 @@ const onboard = trail('entity.onboard', {
 | --- | --- |
 | `TrailInput<T>` | Extract the input type from a `Trail` |
 | `TrailOutput<T>` | Extract the output type from a `Trail` |
+| `TrailResult<T>` | `Result<TrailOutput<T>, Error>` -- the Result type for a trail's output |
 | `inputOf(trail)` | Get the input Zod schema from a trail instance |
 | `outputOf(trail)` | Get the output Zod schema (or `undefined`) from a trail instance |
 
+### Execution option types
+
+| Type | What it describes |
+| --- | --- |
+| `ExecuteTrailOptions` | Options for `executeTrail`: `ctx`, `abortSignal`, `layers`, `createContext` |
+| `RunOptions` | Same shape as `ExecuteTrailOptions`; forwarded by `run` |
+
 ### Result
 
 ```typescript
@@ -75,39 +115,74 @@ result.unwrapOr(fallback);   // Value or fallback
 
 ### Error taxonomy
 
-13 error classes across 10 categories. Each maps deterministically to exit codes, HTTP status, and JSON-RPC codes on every surface.
-
-| Category | Classes | HTTP | Retryable |
-| --- | --- | --- | --- |
-| `validation` | `ValidationError`, `AmbiguousError`, `AssertionError` | 400 | No |
-| `not_found` | `NotFoundError` | 404 | No |
-| `conflict` | `AlreadyExistsError`, `ConflictError` | 409 | No |
-| `permission` | `PermissionError` | 403 | No |
-| `timeout` | `TimeoutError` | 504 | Yes |
-| `rate_limit` | `RateLimitError` | 429 | Yes |
-| `network` | `NetworkError` | 502 | Yes |
-| `internal` | `InternalError` | 500 | No |
-| `auth` | `AuthError` | 401 | No |
-| `cancelled` | `CancelledError` | 499 | No |
+The current taxonomy is generated from the `errorClasses` owner registry and category code maps in `@ontrails/core`.
+
+<!-- error-taxonomy:start -->
+<!-- GENERATED: run `bun run error-taxonomy:sync`; check with `bun run error-taxonomy:check`. Variant: category. -->
+
+| Category | CLI Exit | HTTP | JSON-RPC | Retryable | Fixed Classes |
+| --- | --- | --- | --- | --- | --- |
+| `validation` | 1 | 400 | -32602 | No | `ValidationError`, `AmbiguousError` |
+| `not_found` | 2 | 404 | -32601 | No | `NotFoundError`, `VersionNotSupportedError` |
+| `conflict` | 3 | 409 | -32603 | No | `AlreadyExistsError`, `ConflictError` |
+| `permission` | 4 | 403 | -32600 | No | `PermissionError`, `PermitError` |
+| `timeout` | 5 | 504 | -32603 | Yes | `TimeoutError` |
+| `rate_limit` | 6 | 429 | -32603 | Yes | `RateLimitError` |
+| `network` | 7 | 502 | -32603 | Yes | `NetworkError` |
+| `shift` | 10 | 503 | -32603 | Yes | `WorkspaceShiftError` |
+| `internal` | 8 | 500 | -32603 | No | `AssertionError`, `InternalError`, `DerivationError`, `RecoverableCompletionError` |
+| `auth` | 9 | 401 | -32600 | No | `AuthError` |
+| `cancelled` | 130 | 499 | -32603 | No | `CancelledError` |
+
+Dynamic classes:
+
+- `RetryExhaustedError` inherits category and surface codes from its wrapped `TrailsError`; retryable is always No.
+<!-- error-taxonomy:end -->
+
+Public surfaces share one redacted rendering contract before applying surface codes. Sensitive substrings are removed from non-internal `TrailsError` messages. Internal-category `TrailsError` instances and unknown native errors remain opaque: HTTP, MCP, and library boundaries use `Internal server error`, while CLI uses the transport-neutral `Internal error`. Diagnostics and serialized payloads keep their useful structure while redacting messages, context, and stack strings.
 
 The developer returns `Result.err(new NotFoundError(...))`. The framework maps it to the right code on every surface.
 
 ### Other exports
 
-- **Schema derivation** -- `deriveFields(schema)` extracts field metadata from Zod for prompts and forms
+- **Schema derivation** -- `deriveFields(schema)` extracts faithfully
+  representable field metadata from Zod for prompts and forms
 - **Validation** -- `validateInput`, `formatZodIssues`, `zodToJsonSchema`
-- **Resilience** -- `retry`, `withTimeout`, `shouldRetry`, `getBackoffDelay`
+- **Resilience** -- `retry`, `withTimeout`, `shouldRetry`, `deriveBackoffDelay`
 - **Serialization** -- `serializeError`, `deserializeError`
 - **Branded types** -- `uuid`, `email`, `nonEmptyString`, `positiveInt`
-- **Layers** -- cross-cutting middleware via `composeLayers`
+- **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 entities without re-authoring IDs, schemas, examples, or intents
 - **Redaction** (`@ontrails/core/redaction`) -- strip sensitive data before logging
 
+### Public helper boundaries
+
+The root package also exposes a few low-level contracts that other framework packages build on:
+
+- **Intrinsic tracing** -- `TraceRecord`, `TraceSink`, `TraceContext`, and the sink registry helpers are the core-owned execution record shape shared by `@ontrails/observability` and adapters.
+- **Trails DB** -- `deriveTrailsDbPath`, `deriveTrailsStateDir`, `deriveTrailsStateHome`, `deriveTrailsProjectKey`, `deriveTrailsDir`, `ensureSubsystemSchema`, `openReadTrailsDb`, and `openWriteTrailsDb` are the generic database primitive used by framework subsystems.
+- **Surface rendering helpers** -- safe error rendering, layer field rendering, compose-batch validation, late-bound signal references, and Zod default-wrapper stripping are stable root exports for first-party surfaces, store helpers, and tests.
+
 See the [API Reference](../../docs/api-reference.md) for the full list.
 
+## Migration: topo-store moved to `@ontrails/topography`
+
+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/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/topography`. `StoredTopoExport` moves to `@ontrails/topography/backend-support`.
+
 ## Installation
 
 ```bash
-bun add @ontrails/core zod
+bun add @ontrails/core@beta zod
 ```

package/package.json

@@ -1,11 +1,26 @@
 {
   "name": "@ontrails/core",
-  "version": "1.0.0-beta.5",
+  "version": "1.0.0-beta.50",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/outfitter-dev/trails.git",
+    "directory": "packages/core"
+  },
+  "files": [
+    "src/**/*.ts",
+    "!src/**/__tests__/**",
+    "!src/**/*.test.ts",
+    "!src/**/*.test-d.ts",
+    "README.md",
+    "CHANGELOG.md"
+  ],
   "type": "module",
   "exports": {
     ".": "./src/index.ts",
     "./patterns": "./src/patterns/index.ts",
     "./redaction": "./src/redaction/index.ts",
+    "./store": "./src/store/index.ts",
+    "./trails": "./src/trails/index.ts",
     "./package.json": "./package.json"
   },
   "scripts": {

package/src/activation-provenance.ts

@@ -0,0 +1,116 @@
+import type {
+  ActivationSourceKind,
+  ActivationSourceMeta,
+} from './activation-source.js';
+
+export const ACTIVATION_PROVENANCE_KEY =
+  '__trails_activation_provenance' as const;
+
+export interface ActivationProvenanceSource {
+  readonly cron?: string | undefined;
+  readonly id: string;
+  readonly kind: ActivationSourceKind;
+  readonly meta?: ActivationSourceMeta | undefined;
+  readonly producerTrailId?: string | undefined;
+  readonly queue?: string | undefined;
+  readonly timezone?: string | undefined;
+}
+
+export interface ActivationProvenance {
+  readonly fireId: string;
+  readonly parentFireId?: string | undefined;
+  readonly rootFireId: string;
+  readonly source: ActivationProvenanceSource;
+}
+
+export interface ActivationProvenanceCarrier {
+  readonly activation?: ActivationProvenance | undefined;
+  readonly extensions?: Readonly<Record<string, unknown>> | undefined;
+}
+
+const isObjectRecord = (value: unknown): value is Record<string, unknown> =>
+  typeof value === 'object' && value !== null && !Array.isArray(value);
+
+const optionalString = (value: unknown): boolean =>
+  value === undefined || typeof value === 'string';
+
+const isActivationProvenanceSource = (
+  value: unknown
+): value is ActivationProvenanceSource =>
+  isObjectRecord(value) &&
+  typeof value['id'] === 'string' &&
+  typeof value['kind'] === 'string' &&
+  optionalString(value['cron']) &&
+  optionalString(value['producerTrailId']) &&
+  optionalString(value['queue']) &&
+  optionalString(value['timezone']) &&
+  (value['meta'] === undefined || isObjectRecord(value['meta']));
+
+const isActivationProvenance = (
+  value: unknown
+): value is ActivationProvenance =>
+  isObjectRecord(value) &&
+  typeof value['fireId'] === 'string' &&
+  optionalString(value['parentFireId']) &&
+  typeof value['rootFireId'] === 'string' &&
+  isActivationProvenanceSource(value['source']);
+
+export const getActivationProvenance = (
+  ctx: ActivationProvenanceCarrier | undefined
+): ActivationProvenance | undefined => {
+  if (isActivationProvenance(ctx?.activation)) {
+    return ctx.activation;
+  }
+  const fromExtensions = ctx?.extensions?.[ACTIVATION_PROVENANCE_KEY];
+  return isActivationProvenance(fromExtensions) ? fromExtensions : undefined;
+};
+
+export const withActivationProvenance = <
+  TCtx extends {
+    readonly extensions?: Readonly<Record<string, unknown>> | undefined;
+  },
+>(
+  ctx: TCtx,
+  activation: ActivationProvenance
+): TCtx & { readonly activation: ActivationProvenance } => ({
+  ...ctx,
+  activation,
+  extensions: {
+    ...ctx.extensions,
+    [ACTIVATION_PROVENANCE_KEY]: activation,
+  },
+});
+
+export const buildActivationProvenanceTraceAttrs = (
+  activation: ActivationProvenance | undefined
+): Readonly<Record<string, unknown>> => {
+  if (activation === undefined) {
+    return {};
+  }
+
+  const attrs: Record<string, unknown> = {
+    'trails.activation.fire_id': activation.fireId,
+    'trails.activation.root_fire_id': activation.rootFireId,
+    'trails.activation.source.id': activation.source.id,
+    'trails.activation.source.kind': activation.source.kind,
+  };
+
+  if (activation.parentFireId !== undefined) {
+    attrs['trails.activation.parent_fire_id'] = activation.parentFireId;
+  }
+  if (activation.source.producerTrailId !== undefined) {
+    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;
+  }
+  if (activation.source.timezone !== undefined) {
+    attrs['trails.activation.source.timezone'] = activation.source.timezone;
+  }
+
+  return attrs;
+};