@ontrails/core 1.0.0-beta.15 → 1.0.0-beta.16

package/src/trails/ingest.ts

@@ -10,7 +10,6 @@ import type { Trail, TrailExample, TrailSpec } from '../trail.js';
 import type { TrailContext } from '../types.js';
 
 type SchemaValue<TSchema extends z.ZodType> = z.output<TSchema>;
-type SignalRef<TSignal> = string | Signal<TSignal>;
 
 type ExampleBearingSchema<TSchema extends z.ZodType> = TSchema & {
   readonly examples?: readonly Partial<SchemaValue<TSchema>>[] | undefined;
@@ -24,8 +23,8 @@ interface IngestBaseOptions<TSchema extends z.ZodType, TSignal> extends Omit<
   readonly id?: string | undefined;
   /** Validated external payload shape. */
   readonly schema: TSchema;
-  /** Signal to emit after verification and optional transformation. */
-  readonly signal: SignalRef<TSignal>;
+  /** Signal to fire after verification and optional transformation. */
+  readonly signal: Signal<TSignal>;
   /** Optional per-trail verification layer, e.g. HMAC signature checks. */
   readonly verify?: Layer | undefined;
 }
@@ -44,9 +43,6 @@ export interface IngestOptions<
     | undefined;
 }
 
-const resolveSignalId = <TSignal>(signalRef: SignalRef<TSignal>): string =>
-  typeof signalRef === 'string' ? signalRef : signalRef.id;
-
 const deriveExampleName = (signalId: string, index: number): string =>
   `Ingest ${signalId} ${index + 1}`;
 
@@ -69,7 +65,7 @@ const deriveExamples = <TSchema extends z.ZodType>(
 
 const createIngestBlaze =
   <TSchema extends z.ZodType, TSignal>(
-    signalRef: SignalRef<TSignal>,
+    signalRef: Signal<TSignal>,
     signalId: string,
     trailId: string,
     transform: IngestTransform<SchemaValue<TSchema>, TSignal> | undefined
@@ -81,7 +77,7 @@ const createIngestBlaze =
     if (ctx.fire === undefined) {
       return Result.err(
         new InternalError(
-          `ingest("${trailId}") requires topo-backed execution to emit "${signalId}"`
+          `ingest("${trailId}") requires topo-backed execution to fire "${signalId}"`
         )
       );
     }
@@ -91,12 +87,8 @@ const createIngestBlaze =
         transform === undefined
           ? (input as TSignal)
           : await transform(input, ctx);
-      const fired =
-        typeof signalRef === 'string'
-          ? await ctx.fire(signalRef, payload as unknown)
-          : await ctx.fire(signalRef as Signal<unknown>, payload as unknown);
-
-      return fired.isErr() ? Result.err(fired.error) : Result.ok();
+      await ctx.fire(signalRef, payload);
+      return Result.ok();
     } catch (error) {
       const message = `ingest("${trailId}"): ${error instanceof Error ? error.message : String(error)}`;
       return Result.err(
@@ -113,7 +105,7 @@ export const ingest = <
 >(
   options: IngestOptions<TSchema, TSignal>
 ): Trail<SchemaValue<TSchema>, void> => {
-  const signalId = resolveSignalId(options.signal);
+  const signalId = options.signal.id;
   const id = options.id ?? `${signalId}.ingest`;
   const { id: _id, schema, signal, transform, verify, ...trailSpec } = options;
   const baseBlaze = createIngestBlaze<TSchema, TSignal>(

package/src/{internal/trails-db.ts → trails-db.ts}

@@ -2,28 +2,41 @@ import { Database } from 'bun:sqlite';
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { dirname, join, resolve } from 'node:path';
 
-import { NotFoundError } from '../errors.js';
+import { NotFoundError } from './errors.js';
 
 const TRAILS_DIR = '.trails';
 const TRAILS_DB_FILE = 'trails.db';
+const TRAILS_CACHE_DIR = 'cache';
+const TRAILS_STATE_DIR = 'state';
 const SCHEMA_VERSION_TABLE = 'meta_schema_versions';
-const WORKSPACE_SUBDIRS = ['config', 'dev', 'generated'] as const;
-const REQUIRED_GITIGNORE_LINES = [
+const WORKSPACE_SUBDIRS = [TRAILS_CACHE_DIR, TRAILS_STATE_DIR] as const;
+
+/**
+ * The canonical lines written to a freshly-bootstrapped
+ * `.trails/.gitignore`. Kept as the source of truth for every consumer that
+ * needs to either write the file (scaffold) or audit its content (tests).
+ *
+ * @see {@link WORKSPACE_GITIGNORE_CONTENT} for the rendered string form.
+ */
+export const WORKSPACE_GITIGNORE_LINES = [
   '# Local config overrides',
-  'config/',
+  'config.local.js',
+  'config.local.ts',
   '',
-  '# Development state',
-  'dev/',
+  '# Rebuildable cache',
+  'cache/',
   '',
-  '# Generated artifacts',
-  'generated/',
+  '# Mutable runtime state',
+  'state/',
   '',
-  '# Shared Trails database',
-  'trails.db',
-  'trails.db-shm',
-  'trails.db-wal',
-  '',
-];
+] as const;
+
+/**
+ * The canonical rendered `.trails/.gitignore` content. Use this when writing
+ * the file eagerly (e.g. during `trails create` scaffolding) or when asserting
+ * on the workspace bootstrap output.
+ */
+export const WORKSPACE_GITIGNORE_CONTENT = `${WORKSPACE_GITIGNORE_LINES.join('\n').trimEnd()}\n`;
 
 export interface TrailsDbLocationOptions {
   readonly path?: string;
@@ -49,20 +62,18 @@ export const deriveTrailsDir = (options?: TrailsDbLocationOptions): string =>
 export const deriveTrailsDbPath = (options?: TrailsDbLocationOptions): string =>
   options?.path
     ? resolve(options.path)
-    : join(deriveTrailsDir(options), TRAILS_DB_FILE);
+    : join(deriveTrailsDir(options), TRAILS_STATE_DIR, TRAILS_DB_FILE);
 
 const ensureDbParentDir = (dbPath: string): void => {
   mkdirSync(dirname(dbPath), { recursive: true });
 };
 
-const GITIGNORE_TEMPLATE = `${REQUIRED_GITIGNORE_LINES.join('\n').trimEnd()}\n`;
-
 const appendMissingGitignoreLines = (
   gitignorePath: string,
   content: string
 ): void => {
   const existingLines = new Set(content.split('\n').map((l) => l.trim()));
-  const missing = REQUIRED_GITIGNORE_LINES.filter(
+  const missing = WORKSPACE_GITIGNORE_LINES.filter(
     (line) => line !== '' && !existingLines.has(line)
   );
 
@@ -78,7 +89,7 @@ const ensureWorkspaceGitignore = (trailsDir: string): void => {
   const gitignorePath = join(trailsDir, '.gitignore');
 
   if (!existsSync(gitignorePath)) {
-    writeFileSync(gitignorePath, GITIGNORE_TEMPLATE);
+    writeFileSync(gitignorePath, WORKSPACE_GITIGNORE_CONTENT);
     return;
   }
 
@@ -88,7 +99,17 @@ const ensureWorkspaceGitignore = (trailsDir: string): void => {
   );
 };
 
-const ensureWorkspaceDir = (rootDir: string): void => {
+/**
+ * Bootstrap the `.trails/` workspace at `rootDir`.
+ *
+ * Creates the workspace directory plus the canonical `cache/` and `state/`
+ * subdirectories, then either writes a fresh `.gitignore` matching
+ * {@link WORKSPACE_GITIGNORE_CONTENT} or appends any missing canonical lines
+ * to an existing one. Safe to call repeatedly. This is the single canonical
+ * source of truth for workspace layout — scaffolding, configuration loading,
+ * and runtime DB initialization all flow through here.
+ */
+export const ensureTrailsWorkspace = (rootDir: string): void => {
   const trailsDir = deriveTrailsDir({ rootDir });
   mkdirSync(trailsDir, { recursive: true });
   for (const subdir of WORKSPACE_SUBDIRS) {
@@ -144,7 +165,7 @@ export const openWriteTrailsDb = (
   );
 
   if (options?.path === undefined) {
-    ensureWorkspaceDir(rootDir);
+    ensureTrailsWorkspace(rootDir);
   } else {
     ensureDbParentDir(dbPath);
   }

package/src/transport-error-map.ts

@@ -1,56 +1,174 @@
-import type { ErrorCategory, TrailsError } from './errors.js';
-import { exitCodeMap, jsonRpcCodeMap, statusCodeMap } from './errors.js';
+import type {
+  ErrorCategory,
+  ErrorCategoryCodes,
+  ErrorClassRegistryEntry,
+  FixedErrorClassRegistryEntry,
+  TrailsError,
+} from './errors.js';
+import {
+  codesByCategory,
+  errorClasses,
+  exitCodeMap,
+  isTrailsError,
+  jsonRpcCodeMap,
+  statusCodeMap,
+} from './errors.js';
+import {
+  INTERNAL_ERROR_PUBLIC_MESSAGE,
+  redactErrorString,
+} from './error-projection.js';
 
-export const transportNames = ['cli', 'http', 'mcp'] as const;
+export const surfaceNames = ['cli', 'http', 'jsonRpc', 'mcp'] as const;
 
-export type TransportName = (typeof transportNames)[number];
+export type SurfaceName = (typeof surfaceNames)[number];
 
-export type TransportErrorMapper<T> = (error: TrailsError) => T;
+const surfaceCodeKeys = {
+  cli: 'exit',
+  http: 'http',
+  jsonRpc: 'jsonRpc',
+  mcp: 'jsonRpc',
+} as const satisfies Record<SurfaceName, keyof ErrorCategoryCodes>;
 
-export type TransportErrorMappings<T> = Record<ErrorCategory, T>;
+export type SurfaceErrorMapper<T> = (error: TrailsError) => T;
+
+export type SurfaceErrorMappings<T> = Record<ErrorCategory, T>;
 
 /**
- * Union of every transport-specific error code emitted by {@link transportErrorMap}.
+ * Union of every surface-specific error code emitted by {@link surfaceErrorMap}.
  *
  * @remarks
- * Previously parameterised by transport (`TransportErrorCode<'cli'>` etc.), but
+ * Previously parameterized by surface (`SurfaceErrorCode<'cli'>` etc.), but
  * the generic collapsed to `number` because the underlying maps were typed as
  * `Record<ErrorCategory, number>`. With `as const satisfies` on the maps the
- * per-transport literals are now observable, but TypeScript cannot narrow
- * `transportErrorMap[transport][error.category]` through a generic
- * `TTransport` without an unsound cast. The non-generic union honestly reflects
- * what `mapTransportError` returns at the call site.
+ * per-surface literals are now observable, but TypeScript cannot narrow
+ * `surfaceErrorMap[surface][error.category]` through a generic `TSurface`
+ * without an unsound cast. The non-generic union honestly reflects what
+ * `mapSurfaceError` returns at the call site.
  */
-export type TransportErrorCode =
-  (typeof transportErrorMap)[TransportName][ErrorCategory];
+export type SurfaceErrorCode =
+  (typeof codesByCategory)[ErrorCategory][(typeof surfaceCodeKeys)[SurfaceName]];
+
+export interface SurfaceErrorProjection {
+  readonly category: ErrorCategory;
+  readonly code: SurfaceErrorCode;
+  readonly message: string;
+  readonly name: string;
+  readonly retryable: boolean;
+  readonly surface: SurfaceName;
+}
 
-export const createTransportErrorMapper =
-  <T>(mappings: TransportErrorMappings<T>): TransportErrorMapper<T> =>
+export interface ErrorClassSurfaceProjection {
+  readonly category: ErrorCategory;
+  readonly code: SurfaceErrorCode;
+  readonly name: string;
+  readonly retryable: boolean;
+  readonly surface: SurfaceName;
+}
+
+export const createSurfaceErrorMapper =
+  <T>(mappings: SurfaceErrorMappings<T>): SurfaceErrorMapper<T> =>
   (error) =>
     mappings[error.category];
 
-export const transportErrorMap = {
+export const surfaceErrorMap = {
   cli: exitCodeMap,
   http: statusCodeMap,
+  jsonRpc: jsonRpcCodeMap,
   mcp: jsonRpcCodeMap,
-} as const satisfies Record<TransportName, TransportErrorMappings<number>>;
+} as const satisfies Record<SurfaceName, SurfaceErrorMappings<number>>;
 
-export const transportErrorRegistry = {
+export const surfaceErrorRegistry = {
   cli: {
-    map: createTransportErrorMapper(transportErrorMap.cli),
-    values: transportErrorMap.cli,
+    map: createSurfaceErrorMapper(surfaceErrorMap.cli),
+    values: surfaceErrorMap.cli,
   },
   http: {
-    map: createTransportErrorMapper(transportErrorMap.http),
-    values: transportErrorMap.http,
+    map: createSurfaceErrorMapper(surfaceErrorMap.http),
+    values: surfaceErrorMap.http,
+  },
+  jsonRpc: {
+    map: createSurfaceErrorMapper(surfaceErrorMap.jsonRpc),
+    values: surfaceErrorMap.jsonRpc,
   },
   mcp: {
-    map: createTransportErrorMapper(transportErrorMap.mcp),
-    values: transportErrorMap.mcp,
+    map: createSurfaceErrorMapper(surfaceErrorMap.mcp),
+    values: surfaceErrorMap.mcp,
   },
 } as const;
 
-export const mapTransportError = (
-  transport: TransportName,
+export const mapSurfaceError = (
+  surface: SurfaceName,
   error: TrailsError
-): TransportErrorCode => transportErrorMap[transport][error.category];
+): SurfaceErrorCode =>
+  codesByCategory[error.category][surfaceCodeKeys[surface]];
+
+export const projectSurfaceError = (
+  surface: SurfaceName,
+  error: TrailsError
+): SurfaceErrorProjection => ({
+  category: error.category,
+  code: mapSurfaceError(surface, error),
+  message: error.message,
+  name: error.name,
+  retryable: error.retryable,
+  surface,
+});
+
+export const projectPublicSurfaceError = (
+  surface: SurfaceName,
+  error: Error
+): SurfaceErrorProjection => {
+  if (isTrailsError(error)) {
+    const projection = projectSurfaceError(surface, error);
+    return {
+      ...projection,
+      message:
+        projection.category === 'internal'
+          ? INTERNAL_ERROR_PUBLIC_MESSAGE
+          : redactErrorString(projection.message),
+    };
+  }
+
+  return {
+    category: 'internal',
+    code: codesByCategory.internal[surfaceCodeKeys[surface]],
+    message: INTERNAL_ERROR_PUBLIC_MESSAGE,
+    name: 'InternalError',
+    retryable: false,
+    surface,
+  };
+};
+
+const isFixedErrorClassEntry = (
+  entry: ErrorClassRegistryEntry
+): entry is FixedErrorClassRegistryEntry => entry.category !== 'dynamic';
+
+const fixedErrorClassByName: ReadonlyMap<string, FixedErrorClassRegistryEntry> =
+  new Map(
+    errorClasses.flatMap((entry): [string, FixedErrorClassRegistryEntry][] =>
+      isFixedErrorClassEntry(entry) ? [[entry.name, entry]] : []
+    )
+  );
+
+/**
+ * Project a known error class name onto a surface without constructing it.
+ *
+ * Dynamic-category errors such as `RetryExhaustedError` return `undefined`
+ * because their surface code depends on the wrapped runtime error.
+ */
+export const projectErrorClassSurface = (
+  surface: SurfaceName,
+  errorName: string
+): ErrorClassSurfaceProjection | undefined => {
+  const entry = fixedErrorClassByName.get(errorName);
+  if (entry === undefined) {
+    return undefined;
+  }
+  return {
+    category: entry.category,
+    code: codesByCategory[entry.category][surfaceCodeKeys[surface]],
+    name: entry.name,
+    retryable: entry.retryable,
+    surface,
+  };
+};

package/src/types.ts

@@ -1,8 +1,10 @@
 import type { TrailsError } from './errors.js';
+import type { BasePermit } from './permits.js';
 import type { Result } from './result.js';
 import type { Signal } from './signal.js';
 import type { AnyTrail } from './trail.js';
 import type { CrossInput, TrailOutput } from './type-utils.js';
+import type { ActivationProvenance } from './activation-provenance.js';
 
 // ---------------------------------------------------------------------------
 // Detour
@@ -102,28 +104,17 @@ export interface CrossFn {
  * Emit a signal — used for signal-driven activation.
  *
  * Fan-out to consumer trails (those with the signal in their `on:` array) is
- * the framework's responsibility. Producers get `Result.ok(undefined)` unless
- * the signal id is unknown or the payload fails schema validation. Consumer
- * errors are logged but do not propagate back to the producer. Consumers fan
- * out in parallel, each with its own derived context. Runtime cycle
- * suppression is still signal-id-based against the current fire stack: it
- * prevents re-entrant loops but can over-suppress legitimate diamond
- * re-fires, with a debug breadcrumb and a warn emitted when suppression happens.
- *
- * Two call shapes are supported:
- *
- * - **By id** (base shape): `ctx.fire('order.placed', { ... })`. Matches
- *   the shape of `ctx.cross`; payload is typed as `unknown` and validated
- *   against the signal's schema at the fire boundary.
- * - **By signal value** (progressive disclosure): `ctx.fire(orderPlaced, payload)`
- *   where `orderPlaced` is a `Signal<T>`. The compiler enforces that
- *   `payload` matches the signal's declared schema type at the call site,
- *   on top of the runtime validation.
+ * the framework's responsibility. Producers call with a `Signal<T>` value and
+ * get best-effort `Promise<void>` semantics: payload validation, missing topo
+ * entries, guard suppression, and consumer failures are observable through
+ * diagnostics/logging but do not become producer-facing `Result` plumbing.
+ * Consumers fan out in parallel, each with its own derived context. Runtime
+ * cycle suppression is still signal-id-based against the current fire stack:
+ * it prevents re-entrant loops but can over-suppress legitimate diamond
+ * re-fires, with a debug breadcrumb and a warn emitted when suppression
+ * happens.
  */
-export interface FireFn {
-  <T>(signal: Signal<T>, payload: T): Promise<Result<void, Error>>;
-  (signalId: string, payload: unknown): Promise<Result<void, Error>>;
-}
+export type FireFn = <T>(signal: Signal<T>, payload: T) => Promise<void>;
 
 /** Resolve a resource instance from the current trail context. */
 export type ResourceLookup = <T = unknown>(
@@ -167,22 +158,64 @@ export interface Logger {
   child(context: Record<string, unknown>): Logger;
 }
 
-/** Context extension key for the invoking trailhead name. */
-export const TRAILHEAD_KEY = '__trails_trailhead' as const;
+export type LogLevel =
+  | 'debug'
+  | 'error'
+  | 'fatal'
+  | 'info'
+  | 'silent'
+  | 'trace'
+  | 'warn';
+
+export interface LogRecord {
+  readonly category: string;
+  readonly level: LogLevel;
+  readonly message: string;
+  readonly metadata: Record<string, unknown>;
+  readonly timestamp: Date;
+}
+
+export interface LogSink {
+  readonly name: string;
+  readonly write: (record: LogRecord) => void;
+  readonly flush?: (() => Promise<void>) | undefined;
+}
 
-/** Minimal permit shape available on TrailContext. Permits extends this. */
-export interface BasePermit {
-  readonly id: string;
-  readonly scopes: readonly string[];
+export interface LogFormatter {
+  format(record: LogRecord): string;
 }
 
+/**
+ * Context extension key for the invoking surface name.
+ */
+export const SURFACE_KEY = '__trails_surface' as const;
+
+/**
+ * Context extension key for the layer names attached by the invoking surface.
+ */
+export const SURFACE_LAYER_NAMES_KEY = '__trails_surface_layer_names' as const;
+
+/**
+ * Context extension key carrying per-layer runtime input.
+ *
+ * Surfaces (CLI, MCP, HTTP) project each typed layer's `input` schema onto
+ * their native idioms (flags, tool params, query strings). At execute time
+ * the parsed values are partitioned per layer and stored under this key as
+ * `Record<layerName, unknown>`. Layers that need runtime input read their
+ * own slot via `ctx.extensions?.[LAYER_INPUTS_KEY]?.[layer.name]`.
+ *
+ * @see TRL-473 for the CLI projection contract.
+ */
+export const LAYER_INPUTS_KEY = '__trails_layer_inputs' as const;
+
 /** Runtime context threaded through every trail execution */
 export interface TrailContext {
+  readonly activation?: ActivationProvenance | undefined;
   readonly requestId: string;
   readonly abortSignal: AbortSignal;
   readonly cross?: CrossFn | undefined;
   /**
-   * Emit a signal by id. Fans out to every trail with the signal in its
+   * Emit a typed signal. Fans out to every trail with the signal in its
    * `on:` declaration. Bound by the runner that holds the topo (typically
    * `run()`); undefined when a context is constructed without topo access.
    */
@@ -195,6 +228,27 @@ export interface TrailContext {
   readonly env?: Record<string, string | undefined> | undefined;
   readonly extensions?: Readonly<Record<string, unknown>> | undefined;
   readonly resource?: ResourceLookup | undefined;
+  /**
+   * Whether the current invocation is a dry run.
+   *
+   * Defaults to `false`. Trails that don't read this field are unaffected.
+   * Trails that do read it decide what dry-run means for their domain — for
+   * example: preview the change without committing, validate inputs without
+   * performing side effects, or return what would happen without actually
+   * doing it.
+   *
+   * The framework only carries the flag from the surface (e.g. CLI
+   * `--dry-run`) into the context. It never short-circuits trail execution
+   * on its own based on this field.
+   *
+   * Pair this runtime signal with `TrailSpec.dryRun`, which declares whether a
+   * trail supports dry-run semantics for governance, derivation, and surface
+   * tooling.
+   *
+   * @remarks Always defined on contexts produced by `executeTrail` or
+   * `createTrailContext` (normalized to `false` when not provided).
+   */
+  readonly dryRun?: boolean | undefined;
   /**
    * Wrap a callback in a child trace span.
    *

package/src/validate-established-topo.ts

@@ -9,7 +9,13 @@ const PROJECTION_BLOCKING_RULES = new Set([
   'cross-cycle',
   'cross-exists',
   'no-self-cross',
+  'activation-source-definition-unique',
+  'activation-source-edge-unique',
+  'activation-source-kind-known',
+  'activation-schedule-valid',
   'resource-exists',
+  'signal-fire-exists',
+  'signal-on-exists',
   'signal-origin-exists',
 ]);