@ontrails/core 0.2.0

package/src/trails/index.ts

@@ -0,0 +1,9 @@
+export { deriveTrail } from './derive-trail.js';
+export type {
+  DeriveTrailInput,
+  DeriveTrailOperation,
+  DeriveTrailOutput,
+  DeriveTrailSpec,
+} from './derive-trail.js';
+export { ingest } from './ingest.js';
+export type { IngestOptions, IngestTransform } from './ingest.js';

package/src/trails/ingest.ts

@@ -0,0 +1,152 @@
+import { z } from 'zod';
+
+import { InternalError } from '../errors.js';
+import { composeLayers } from '../layer.js';
+import type { Layer } from '../layer.js';
+import { Result } from '../result.js';
+import type { Signal } from '../signal.js';
+import { trail } from '../trail.js';
+import type { Trail, TrailExample, TrailSpec } from '../trail.js';
+import type { TrailContext } from '../types.js';
+
+type SchemaValue<TSchema extends z.ZodType> = z.output<TSchema>;
+
+type ExampleBearingSchema<TSchema extends z.ZodType> = TSchema & {
+  readonly examples?: readonly Partial<SchemaValue<TSchema>>[] | undefined;
+};
+
+interface IngestBaseOptions<TSchema extends z.ZodType, TSignal> extends Omit<
+  TrailSpec<SchemaValue<TSchema>, void>,
+  | 'implementation'
+  | 'examples'
+  | 'fires'
+  | 'input'
+  | 'intent'
+  | 'output'
+  | 'pattern'
+> {
+  /** Override the derived trail id. Defaults to `${signal}.ingest`. */
+  readonly id?: string | undefined;
+  /** Validated external payload shape. */
+  readonly schema: TSchema;
+  /** 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;
+}
+
+export type IngestTransform<TInput, TSignal> = (
+  payload: TInput,
+  ctx: TrailContext
+) => TSignal | Promise<TSignal>;
+
+export interface IngestOptions<
+  TSchema extends z.ZodType,
+  TSignal,
+> extends IngestBaseOptions<TSchema, TSignal> {
+  readonly transform?:
+    | IngestTransform<SchemaValue<TSchema>, TSignal>
+    | undefined;
+}
+
+const deriveExampleName = (signalId: string, index: number): string =>
+  `Ingest ${signalId} ${index + 1}`;
+
+const deriveExamples = <TSchema extends z.ZodType>(
+  schema: ExampleBearingSchema<TSchema>,
+  signalId: string
+): readonly TrailExample<SchemaValue<TSchema>, void>[] | undefined => {
+  const { examples } = schema;
+  if (examples === undefined || examples.length === 0) {
+    return undefined;
+  }
+
+  return Object.freeze(
+    examples.map((example, index) => ({
+      input: example,
+      name: deriveExampleName(signalId, index),
+    }))
+  );
+};
+
+const createIngestImplementation =
+  <TSchema extends z.ZodType, TSignal>(
+    signalRef: Signal<TSignal>,
+    signalId: string,
+    trailId: string,
+    transform: IngestTransform<SchemaValue<TSchema>, TSignal> | undefined
+  ) =>
+  async (
+    input: SchemaValue<TSchema>,
+    ctx: TrailContext
+  ): Promise<Result<void, Error>> => {
+    if (ctx.fire === undefined) {
+      return Result.err(
+        new InternalError(
+          `ingest("${trailId}") requires topo-backed execution to fire "${signalId}"`
+        )
+      );
+    }
+
+    try {
+      const payload =
+        transform === undefined
+          ? (input as TSignal)
+          : await transform(input, ctx);
+      await ctx.fire(signalRef, payload);
+      return Result.ok();
+    } catch (error) {
+      const message = `ingest("${trailId}"): ${error instanceof Error ? error.message : String(error)}`;
+      return Result.err(
+        error instanceof Error
+          ? new InternalError(message, { cause: error })
+          : new InternalError(message)
+      );
+    }
+  };
+
+export const ingest = <
+  TSchema extends z.ZodType,
+  TSignal = SchemaValue<TSchema>,
+>(
+  options: IngestOptions<TSchema, TSignal>
+): Trail<SchemaValue<TSchema>, void> => {
+  const signalId = options.signal.id;
+  const id = options.id ?? `${signalId}.ingest`;
+  const { id: _id, schema, signal, transform, verify, ...trailSpec } = options;
+  const baseImplementation = createIngestImplementation<TSchema, TSignal>(
+    signal,
+    signalId,
+    id,
+    transform
+  );
+  const baseSpec = {
+    ...trailSpec,
+    examples: deriveExamples(schema as ExampleBearingSchema<TSchema>, signalId),
+    fires: [signal],
+    implementation: baseImplementation as TrailSpec<
+      unknown,
+      unknown
+    >['implementation'],
+    input: schema as z.ZodType<unknown>,
+    intent: 'write',
+    output: z.void(),
+    pattern: 'ingest',
+  } as TrailSpec<unknown, unknown>;
+  const baseTrail = trail(id, baseSpec) as Trail<SchemaValue<TSchema>, void>;
+
+  if (verify === undefined) {
+    return baseTrail;
+  }
+
+  // Verification is a per-factory concern, so compose it locally instead of
+  // mutating runner-wide layer configuration.
+  return Object.freeze({
+    ...baseTrail,
+    implementation: composeLayers(
+      [verify],
+      baseTrail,
+      baseTrail.implementation
+    ),
+  }) as Trail<SchemaValue<TSchema>, void>;
+};

package/src/trails-db.ts

@@ -0,0 +1,212 @@
+import type { Database } from 'bun:sqlite';
+
+import { NotFoundError } from './errors.js';
+import { loadRuntimeBuiltin } from './runtime-builtins.js';
+import { sha256Hex } from './sha256.js';
+
+// Altitude ruling (TRL-1198, ADR-0051 lens): trails-db stays core-owned
+// shared framework infrastructure (ADR-0014) and stays on the barrel —
+// topography, tracing, warden, wayfinder, and the operator app all
+// consume it from `@ontrails/core`. What it may NOT do is assume runtime
+// capabilities eagerly: `bun:sqlite` and the node builtins load lazily at
+// first use so the barrel's module graph stays execution-portable.
+const sqlite = () => loadRuntimeBuiltin('bun:sqlite');
+const fs = () => loadRuntimeBuiltin('node:fs');
+const os = () => loadRuntimeBuiltin('node:os');
+const nodePath = () => loadRuntimeBuiltin('node:path');
+
+const TRAILS_DIR = '.trails';
+const TRAILS_DB_FILE = 'trails.db';
+const TRAILS_STORE_DIR = 'trails';
+const TRAILS_PROJECTS_DIR = 'projects';
+const SCHEMA_VERSION_TABLE = 'meta_schema_versions';
+const SQLITE_BUSY_TIMEOUT_MS = 5000;
+const PROJECT_KEY_HASH_LENGTH = 16;
+const PROJECT_KEY_NAME_FALLBACK = 'project';
+
+/**
+ * Legacy no-op compatibility export.
+ *
+ * `.trails/` is committed project control, not disposable cache/state. New
+ * code should not write a `.trails/.gitignore`; keep this export available for
+ * older callers during the pre-1.0 cutover.
+ */
+export const WORKSPACE_GITIGNORE_LINES = [] as const;
+
+/**
+ * Legacy no-op compatibility export. See {@link WORKSPACE_GITIGNORE_LINES}.
+ */
+export const WORKSPACE_GITIGNORE_CONTENT = '';
+
+export interface TrailsDbLocationOptions {
+  readonly env?: Record<string, string | undefined>;
+  readonly path?: string;
+  readonly rootDir?: string;
+}
+
+export interface EnsureSubsystemSchemaOptions {
+  readonly migrate: (currentVersion: number) => void;
+  readonly subsystem: string;
+  readonly version: number;
+}
+
+interface SchemaVersionRow {
+  readonly version: number;
+}
+
+const deriveRootDir = (rootDir?: string): string =>
+  nodePath().resolve(rootDir ?? process.cwd());
+
+const sanitizeProjectKeyName = (name: string): string => {
+  const normalized = name.replaceAll(/[^a-zA-Z0-9._-]+/g, '-');
+  return normalized.length > 0 ? normalized : PROJECT_KEY_NAME_FALLBACK;
+};
+
+const projectHash = (rootDir: string): string =>
+  sha256Hex(rootDir).slice(0, PROJECT_KEY_HASH_LENGTH);
+
+export const deriveTrailsProjectKey = (
+  options?: TrailsDbLocationOptions
+): string => {
+  const rootDir = deriveRootDir(options?.rootDir);
+  return `${sanitizeProjectKeyName(nodePath().basename(rootDir))}-${projectHash(rootDir)}`;
+};
+
+export const deriveTrailsStateHome = (
+  options?: TrailsDbLocationOptions
+): string => {
+  const env = options?.env ?? process.env;
+  return nodePath().resolve(
+    env['TRAILS_STATE_HOME'] ??
+      env['XDG_STATE_HOME'] ??
+      nodePath().join(os().homedir(), '.local', 'state')
+  );
+};
+
+export const deriveTrailsStateDir = (
+  options?: TrailsDbLocationOptions
+): string =>
+  nodePath().join(
+    deriveTrailsStateHome(options),
+    TRAILS_STORE_DIR,
+    TRAILS_PROJECTS_DIR,
+    deriveTrailsProjectKey(options)
+  );
+
+export const deriveTrailsDir = (options?: TrailsDbLocationOptions): string =>
+  nodePath().join(deriveRootDir(options?.rootDir), TRAILS_DIR);
+
+export const deriveTrailsDbPath = (options?: TrailsDbLocationOptions): string =>
+  options?.path
+    ? nodePath().resolve(options.path)
+    : nodePath().join(deriveTrailsStateDir(options), TRAILS_DB_FILE);
+
+const ensureDbParentDir = (dbPath: string): void => {
+  fs().mkdirSync(nodePath().dirname(dbPath), { recursive: true });
+};
+
+/**
+ * Bootstrap the `.trails/` workspace at `rootDir`.
+ *
+ * Creates only the committed-control directory. Derived cache and observed
+ * state live in the per-user Trails store, so this helper intentionally does
+ * not create `.trails/cache`, `.trails/state`, or `.trails/.gitignore`.
+ */
+export const ensureTrailsWorkspace = (rootDir: string): void => {
+  const trailsDir = deriveTrailsDir({ rootDir });
+  fs().mkdirSync(trailsDir, { recursive: true });
+};
+
+const initializeWritePragmas = (db: Database): void => {
+  db.run(`PRAGMA busy_timeout = ${SQLITE_BUSY_TIMEOUT_MS.toString()}`);
+  db.run('PRAGMA journal_mode = WAL');
+  db.run('PRAGMA synchronous = NORMAL');
+  db.run('PRAGMA foreign_keys = ON');
+};
+
+const initializeReadPragmas = (db: Database): void => {
+  db.run(`PRAGMA busy_timeout = ${SQLITE_BUSY_TIMEOUT_MS.toString()}`);
+  db.run('PRAGMA foreign_keys = ON');
+};
+
+const ensureSchemaVersionTable = (db: Database): void => {
+  db.run(`CREATE TABLE IF NOT EXISTS ${SCHEMA_VERSION_TABLE} (
+    subsystem TEXT PRIMARY KEY,
+    version INTEGER NOT NULL,
+    updated_at TEXT NOT NULL
+  )`);
+};
+
+const readSubsystemVersion = (db: Database, subsystem: string): number => {
+  const row = db
+    .query<SchemaVersionRow, [string]>(
+      `SELECT version FROM ${SCHEMA_VERSION_TABLE} WHERE subsystem = ?`
+    )
+    .get(subsystem);
+  return row?.version ?? 0;
+};
+
+const writeSubsystemVersion = (
+  db: Database,
+  subsystem: string,
+  version: number
+): void => {
+  db.run(
+    `INSERT INTO ${SCHEMA_VERSION_TABLE} (subsystem, version, updated_at)
+     VALUES (?, ?, ?)
+     ON CONFLICT(subsystem) DO UPDATE SET
+       version = excluded.version,
+       updated_at = excluded.updated_at`,
+    [subsystem, version, new Date().toISOString()]
+  );
+};
+
+export const openWriteTrailsDb = (
+  options?: TrailsDbLocationOptions
+): Database => {
+  const rootDir = deriveRootDir(options?.rootDir);
+  const locationOptions: TrailsDbLocationOptions = {
+    ...(options?.env === undefined ? {} : { env: options.env }),
+    ...(options?.path === undefined ? {} : { path: options.path }),
+    rootDir,
+  };
+  const dbPath = deriveTrailsDbPath(locationOptions);
+
+  ensureDbParentDir(dbPath);
+
+  const db = new (sqlite().Database)(dbPath, { create: true });
+  initializeWritePragmas(db);
+  ensureSchemaVersionTable(db);
+  return db;
+};
+
+export const openReadTrailsDb = (
+  options?: TrailsDbLocationOptions
+): Database => {
+  const dbPath = deriveTrailsDbPath(options);
+  if (!fs().existsSync(dbPath)) {
+    throw new NotFoundError(
+      `Trails database not found at "${dbPath}". Run a write operation first to initialize it.`
+    );
+  }
+  const db = new (sqlite().Database)(dbPath, { readonly: true });
+  initializeReadPragmas(db);
+  return db;
+};
+
+export const ensureSubsystemSchema = (
+  db: Database,
+  options: EnsureSubsystemSchemaOptions
+): void => {
+  ensureSchemaVersionTable(db);
+
+  db.transaction(() => {
+    const currentVersion = readSubsystemVersion(db, options.subsystem);
+    if (currentVersion >= options.version) {
+      return;
+    }
+
+    options.migrate(currentVersion);
+    writeSubsystemVersion(db, options.subsystem, options.version);
+  })();
+};

package/src/transport-error-map.ts

@@ -0,0 +1,163 @@
+import type {
+  ErrorCategory,
+  ErrorCategoryCodes,
+  ErrorClassRegistryEntry,
+  FixedErrorClassRegistryEntry,
+  TrailsError,
+} from './errors.js';
+import {
+  codesByCategory,
+  errorClasses,
+  exitCodeMap,
+  jsonRpcCodeMap,
+  statusCodeMap,
+} from './errors.js';
+import { renderPublicError } from './error-rendering.js';
+
+const CLI_INTERNAL_ERROR_PUBLIC_MESSAGE = 'Internal error';
+
+export const surfaceNames = ['cli', 'http', 'jsonRpc', 'mcp'] as const;
+
+export type SurfaceName = (typeof surfaceNames)[number];
+
+const surfaceCodeKeys = {
+  cli: 'exit',
+  http: 'http',
+  jsonRpc: 'jsonRpc',
+  mcp: 'jsonRpc',
+} as const satisfies Record<SurfaceName, keyof ErrorCategoryCodes>;
+
+export type SurfaceErrorMapper<T> = (error: TrailsError) => T;
+
+export type SurfaceErrorMappings<T> = Record<ErrorCategory, T>;
+
+/**
+ * Union of every surface-specific error code emitted by {@link surfaceErrorMap}.
+ *
+ * @remarks
+ * 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-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 SurfaceErrorCode =
+  (typeof codesByCategory)[ErrorCategory][(typeof surfaceCodeKeys)[SurfaceName]];
+
+export interface SurfaceErrorRendering {
+  readonly category: ErrorCategory;
+  readonly code: SurfaceErrorCode;
+  readonly message: string;
+  readonly name: string;
+  readonly retryable: boolean;
+  readonly surface: SurfaceName;
+}
+
+export interface ErrorClassSurfaceRendering {
+  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 surfaceErrorMap = {
+  cli: exitCodeMap,
+  http: statusCodeMap,
+  jsonRpc: jsonRpcCodeMap,
+  mcp: jsonRpcCodeMap,
+} as const satisfies Record<SurfaceName, SurfaceErrorMappings<number>>;
+
+export const surfaceErrorRegistry = {
+  cli: {
+    map: createSurfaceErrorMapper(surfaceErrorMap.cli),
+    values: surfaceErrorMap.cli,
+  },
+  http: {
+    map: createSurfaceErrorMapper(surfaceErrorMap.http),
+    values: surfaceErrorMap.http,
+  },
+  jsonRpc: {
+    map: createSurfaceErrorMapper(surfaceErrorMap.jsonRpc),
+    values: surfaceErrorMap.jsonRpc,
+  },
+  mcp: {
+    map: createSurfaceErrorMapper(surfaceErrorMap.mcp),
+    values: surfaceErrorMap.mcp,
+  },
+} as const;
+
+export const mapSurfaceError = (
+  surface: SurfaceName,
+  error: TrailsError
+): SurfaceErrorCode =>
+  codesByCategory[error.category][surfaceCodeKeys[surface]];
+
+export const renderSurfaceError = (
+  surface: SurfaceName,
+  error: TrailsError
+): SurfaceErrorRendering => ({
+  category: error.category,
+  code: mapSurfaceError(surface, error),
+  message: error.message,
+  name: error.name,
+  retryable: error.retryable,
+  surface,
+});
+
+export const renderPublicSurfaceError = (
+  surface: SurfaceName,
+  error: Error
+): SurfaceErrorRendering => {
+  const rendering = renderPublicError(error);
+  return {
+    ...rendering,
+    code: codesByCategory[rendering.category][surfaceCodeKeys[surface]],
+    message:
+      surface === 'cli' && rendering.category === 'internal'
+        ? CLI_INTERNAL_ERROR_PUBLIC_MESSAGE
+        : rendering.message,
+    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]] : []
+    )
+  );
+
+/**
+ * Render 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 renderErrorClassSurface = (
+  surface: SurfaceName,
+  errorName: string
+): ErrorClassSurfaceRendering | 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/type-utils.ts

@@ -0,0 +1,87 @@
+/**
+ * Type utilities for extracting input/output types from trails.
+ */
+
+import type { Result } from './result.js';
+import type { AnyTrail, Trail } from './trail.js';
+import type { Implementation } from './types.js';
+import type { z } from 'zod';
+
+// ---------------------------------------------------------------------------
+// Utility types
+// ---------------------------------------------------------------------------
+
+/* oxlint-disable no-explicit-any -- `any` required for conditional type inference; `unknown` breaks inference */
+
+type SchemaInputOrFallback<TSchema extends z.ZodType, TFallback> =
+  unknown extends z.input<TSchema> ? TFallback : z.input<TSchema>;
+
+type ComposeSchemaOf<T extends AnyTrail> = T extends {
+  readonly composeInput?: (infer TComposeSchema) | undefined;
+}
+  ? NonNullable<TComposeSchema>
+  : never;
+
+type ComposeInputPart<T extends AnyTrail> =
+  ComposeSchemaOf<T> extends z.ZodType
+    ? T extends Trail<any, any, infer CI>
+      ? SchemaInputOrFallback<ComposeSchemaOf<T>, CI>
+      : z.input<ComposeSchemaOf<T>>
+    : T extends Trail<any, any, infer CI>
+      ? CI
+      : never;
+
+/** Extract the input type from a Trail. */
+export type TrailInput<T extends AnyTrail> = T extends {
+  readonly input: infer TInputSchema extends z.ZodType;
+}
+  ? T extends Trail<infer I, any, any>
+    ? SchemaInputOrFallback<TInputSchema, I>
+    : z.input<TInputSchema>
+  : never;
+
+/** Extract the output type from a Trail. */
+export type TrailOutput<T extends AnyTrail> = T extends {
+  readonly implementation: Implementation<any, infer O>;
+}
+  ? O
+  : never;
+
+/**
+ * Extract the compose-callable input type from a trail.
+ *
+ * When a trail declares `composeInput`, callers via `ctx.compose()` must pass
+ * both the public input fields and the composition-only fields. This type
+ * merges both schemas so the compiler enforces the full shape at the call
+ * site. Falls back to plain `TrailInput<T>` when no `composeInput` exists.
+ */
+export type ComposeInput<T extends AnyTrail> = [ComposeInputPart<T>] extends [
+  never,
+]
+  ? TrailInput<T>
+  : TrailInput<T> & ComposeInputPart<T>;
+
+/**
+ * Extracts the full `Result<Output, Error>` type from a trail definition.
+ *
+ * @example
+ * ```typescript
+ * type SearchResult = TrailResult<typeof searchTrail>;
+ * // Result<{ results: Item[]; count: number }, Error>
+ * ```
+ */
+export type TrailResult<T extends AnyTrail> = Result<TrailOutput<T>, Error>;
+
+/* oxlint-enable no-explicit-any */
+
+// ---------------------------------------------------------------------------
+// Runtime schema accessors
+// ---------------------------------------------------------------------------
+
+/** Get the input Zod schema from a trail, preserving the specific schema type. */
+export const inputOf = <T extends AnyTrail>(trail: T): T['input'] =>
+  trail.input;
+
+/** Get the output Zod schema from a trail, if defined, preserving the specific schema type. */
+export const outputOf = <T extends AnyTrail>(trail: T): T['output'] =>
+  trail.output;