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

package/src/internal/tracing.ts

@@ -0,0 +1,187 @@
+/**
+ * Intrinsic tracing primitives.
+ *
+ * This module is the home for the trace record type, the sink interface,
+ * the sink registry, and the helpers `executeTrail` uses to create root
+ * trace records and child spans. It is intentionally framework-internal —
+ * the `@ontrails/tracing` package re-exports the public surface so callers
+ * can continue to import from there.
+ *
+ * Tracing is intrinsic: every `executeTrail` call automatically produces a
+ * root `TraceRecord`, and `ctx.trace(label, fn)` creates nested child spans
+ * underneath it. A default no-op sink is installed at module load so core
+ * never crashes when no real sink has been registered.
+ */
+
+/** Evidence of a single trail execution or manual span. */
+export interface TraceRecord {
+  readonly id: string;
+  readonly traceId: string;
+  readonly rootId: string;
+  readonly parentId?: string | undefined;
+  readonly kind: 'trail' | 'span';
+  readonly name: string;
+  readonly trailId?: string | undefined;
+  readonly trailhead?: 'cli' | 'mcp' | 'http' | 'ws' | undefined;
+  readonly intent?: 'read' | 'write' | 'destroy' | undefined;
+  readonly startedAt: number;
+  readonly endedAt?: number | undefined;
+  readonly status: 'ok' | 'err' | 'cancelled';
+  readonly errorCategory?: string | undefined;
+  readonly permit?:
+    | { readonly id: string; readonly tenantId?: string }
+    | undefined;
+  readonly attrs: Readonly<Record<string, unknown>>;
+}
+
+/**
+ * Minimal shape a tracing sink must satisfy.
+ *
+ * Kept intentionally tiny so adapters in `@ontrails/tracing`,
+ * `@ontrails/observe`, and user code can all satisfy it without
+ * additional dependencies.
+ */
+export interface TraceSink {
+  readonly write: (record: TraceRecord) => void | Promise<void>;
+}
+
+/** Trace context carried through trail execution via `ctx.extensions`. */
+export interface TraceContext {
+  readonly traceId: string;
+  readonly spanId: string;
+  readonly rootId: string;
+  readonly sampled: boolean;
+}
+
+/** Key used to store trace context in `ctx.extensions`. */
+export const TRACE_CONTEXT_KEY = '__trace_context';
+
+/** Read trace context from trail context extensions. */
+export const getTraceContext = (ctx: {
+  readonly extensions?: Readonly<Record<string, unknown>> | undefined;
+}): TraceContext | undefined =>
+  ctx.extensions?.[TRACE_CONTEXT_KEY] as TraceContext | undefined;
+
+// ---------------------------------------------------------------------------
+// Default no-op sink + sink registry
+// ---------------------------------------------------------------------------
+
+/** No-op sink installed by default so core never crashes without configuration. */
+export const NOOP_SINK: TraceSink = {
+  // oxlint-disable-next-line no-empty-function -- intentional no-op
+  write: () => {},
+};
+
+// oxlint-disable-next-line eslint-plugin-jest/require-hook -- module-level sink registry, not test setup
+let currentSink: TraceSink = NOOP_SINK;
+
+/**
+ * Register a trace sink globally.
+ *
+ * All trails executed via `executeTrail` will write their completed trace
+ * records to this sink, as will every `ctx.trace(label, fn)` child span.
+ * Registering `undefined` or calling {@link clearTraceSink} resets back to
+ * the default no-op sink.
+ */
+export const registerTraceSink = (sink: TraceSink | undefined): void => {
+  currentSink = sink ?? NOOP_SINK;
+};
+
+/** Retrieve the currently registered sink (never undefined). */
+export const getTraceSink = (): TraceSink => currentSink;
+
+/** True when tracing is effectively disabled and executeTrail should skip allocation. */
+export const isTracingDisabled = (sink: TraceSink = currentSink): boolean =>
+  sink === NOOP_SINK;
+
+/** Reset the sink registry back to the default no-op sink. */
+export const clearTraceSink = (): void => {
+  currentSink = NOOP_SINK;
+};
+
+// ---------------------------------------------------------------------------
+// Record + span helpers
+// ---------------------------------------------------------------------------
+
+/** Options for creating a trail-scoped {@link TraceRecord}. */
+interface CreateTraceRecordOptions {
+  readonly trailId: string;
+  readonly traceId?: string | undefined;
+  readonly parentId?: string | undefined;
+  readonly rootId?: string | undefined;
+  readonly trailhead?: TraceRecord['trailhead'];
+  readonly intent?: TraceRecord['intent'];
+  readonly permit?:
+    | { readonly id: string; readonly tenantId?: string }
+    | undefined;
+}
+
+/** Create a fresh trail-kind {@link TraceRecord}. */
+export const createTraceRecord = (
+  options: CreateTraceRecordOptions
+): TraceRecord => {
+  const id = Bun.randomUUIDv7();
+  const traceId = options.traceId ?? Bun.randomUUIDv7();
+
+  return {
+    attrs: {},
+    endedAt: undefined,
+    id,
+    intent: options.intent,
+    kind: 'trail',
+    name: options.trailId,
+    parentId: options.parentId,
+    permit: options.permit,
+    rootId: options.rootId ?? id,
+    startedAt: Date.now(),
+    status: 'ok',
+    traceId,
+    trailId: options.trailId,
+    trailhead: options.trailhead,
+  };
+};
+
+/** Build a span record from a parent trace context. */
+export const createSpanRecord = (
+  parent: TraceContext,
+  label: string
+): TraceRecord => ({
+  attrs: {},
+  endedAt: undefined,
+  errorCategory: undefined,
+  id: Bun.randomUUIDv7(),
+  intent: undefined,
+  kind: 'span',
+  name: label,
+  parentId: parent.spanId,
+  rootId: parent.rootId,
+  startedAt: Date.now(),
+  status: 'ok',
+  traceId: parent.traceId,
+  trailId: undefined,
+  trailhead: undefined,
+});
+
+/** Mark a record as completed with timing and status. */
+export const completeRecord = (
+  record: TraceRecord,
+  status: TraceRecord['status'],
+  errorCategory?: string | undefined
+): TraceRecord => ({
+  ...record,
+  endedAt: Date.now(),
+  errorCategory,
+  status,
+});
+
+/** Best-effort sink write that never throws. */
+export const writeToSink = async (
+  sink: TraceSink,
+  record: TraceRecord
+): Promise<void> => {
+  try {
+    await Promise.resolve(sink.write(record));
+  } catch {
+    // Sink failures must never affect trail result delivery.
+  }
+};

package/src/internal/trails-db.ts

@@ -0,0 +1,187 @@
+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';
+
+const TRAILS_DIR = '.trails';
+const TRAILS_DB_FILE = 'trails.db';
+const SCHEMA_VERSION_TABLE = 'meta_schema_versions';
+const WORKSPACE_SUBDIRS = ['config', 'dev', 'generated'] as const;
+const REQUIRED_GITIGNORE_LINES = [
+  '# Local config overrides',
+  'config/',
+  '',
+  '# Development state',
+  'dev/',
+  '',
+  '# Generated artifacts',
+  'generated/',
+  '',
+  '# Shared Trails database',
+  'trails.db',
+  'trails.db-shm',
+  'trails.db-wal',
+  '',
+];
+
+export interface TrailsDbLocationOptions {
+  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 =>
+  resolve(rootDir ?? process.cwd());
+
+export const deriveTrailsDir = (options?: TrailsDbLocationOptions): string =>
+  join(deriveRootDir(options?.rootDir), TRAILS_DIR);
+
+export const deriveTrailsDbPath = (options?: TrailsDbLocationOptions): string =>
+  options?.path
+    ? resolve(options.path)
+    : join(deriveTrailsDir(options), 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(
+    (line) => line !== '' && !existingLines.has(line)
+  );
+
+  if (missing.length === 0) {
+    return;
+  }
+
+  const next = `${content.trimEnd()}\n\n${missing.join('\n')}`;
+  writeFileSync(gitignorePath, `${next.trimEnd()}\n`);
+};
+
+const ensureWorkspaceGitignore = (trailsDir: string): void => {
+  const gitignorePath = join(trailsDir, '.gitignore');
+
+  if (!existsSync(gitignorePath)) {
+    writeFileSync(gitignorePath, GITIGNORE_TEMPLATE);
+    return;
+  }
+
+  appendMissingGitignoreLines(
+    gitignorePath,
+    readFileSync(gitignorePath, 'utf8')
+  );
+};
+
+const ensureWorkspaceDir = (rootDir: string): void => {
+  const trailsDir = deriveTrailsDir({ rootDir });
+  mkdirSync(trailsDir, { recursive: true });
+  for (const subdir of WORKSPACE_SUBDIRS) {
+    mkdirSync(join(trailsDir, subdir), { recursive: true });
+  }
+  ensureWorkspaceGitignore(trailsDir);
+};
+
+const initializeWritePragmas = (db: Database): void => {
+  db.run('PRAGMA journal_mode = WAL');
+  db.run('PRAGMA synchronous = NORMAL');
+  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 dbPath = deriveTrailsDbPath(
+    options?.path ? { path: options.path, rootDir } : { rootDir }
+  );
+
+  if (options?.path === undefined) {
+    ensureWorkspaceDir(rootDir);
+  } else {
+    ensureDbParentDir(dbPath);
+  }
+
+  const db = new Database(dbPath, { create: true });
+  initializeWritePragmas(db);
+  ensureSchemaVersionTable(db);
+  return db;
+};
+
+export const openReadTrailsDb = (
+  options?: TrailsDbLocationOptions
+): Database => {
+  const dbPath = deriveTrailsDbPath(options);
+  if (!existsSync(dbPath)) {
+    throw new NotFoundError(
+      `Trails database not found at "${dbPath}". Run a write operation first to initialize it.`
+    );
+  }
+  const db = new Database(dbPath, { readonly: true });
+  db.run('PRAGMA foreign_keys = ON');
+  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/internal/zod-wrappers.ts

@@ -0,0 +1,78 @@
+/**
+ * Shared Zod wrapper helpers.
+ *
+ * These helpers walk the wrapper layers of a Zod schema (default, optional,
+ * nullable) and rebuild the schema without any default wrappers so that
+ * downstream `.partial()` calls do not silently re-materialize defaults during
+ * validation. Both `@ontrails/core/trails/derive-trail.ts` and
+ * `@ontrails/store/src/store.ts` previously shipped near-identical copies of
+ * this walk — extracting them here keeps the wrapper semantics authored in one
+ * place so the two call sites cannot drift.
+ *
+ * Canonical behavior: `optional` wrappers are intentionally dropped. Every
+ * current call site applies `.partial()` to the stripped schema, which
+ * re-introduces `optional` across the whole shape. Preserving `optional` here
+ * would be redundant at best and would produce an `OptionalOptional<T>` shape
+ * in edge cases at worst. `nullable` wrappers are preserved because nullability
+ * is a semantic constraint that `.partial()` does not reintroduce.
+ *
+ * @internal
+ */
+
+import type { z } from 'zod';
+
+const isWrapperType = (
+  type: string
+): type is 'default' | 'nullable' | 'optional' =>
+  type === 'default' || type === 'nullable' || type === 'optional';
+
+const readInnerType = (schema: z.ZodType): z.ZodType =>
+  (schema.def as unknown as { innerType: z.ZodType }).innerType;
+
+/**
+ * Strip `default` wrappers from a Zod type so that partial update schemas do
+ * not silently re-materialize defaults. Walks through all wrapper layers
+ * (`default`, `optional`, `nullable`), drops defaults, drops `optional` (the
+ * downstream `.partial()` reintroduces it across the whole shape), and
+ * preserves `nullable` so explicit nullability survives.
+ *
+ * @internal
+ */
+export const stripDefaultWrappers = (schema: z.ZodType): z.ZodType => {
+  let current = schema;
+  let isNullable = false;
+
+  while (isWrapperType(current.def.type)) {
+    if (current.def.type === 'nullable') {
+      isNullable = true;
+    }
+    current = readInnerType(current);
+  }
+
+  return isNullable ? current.nullable() : current;
+};
+
+type AnyObjectSchema = z.ZodObject<Record<string, z.ZodType>>;
+
+const asObjectSchema = (schema: z.ZodType): AnyObjectSchema =>
+  schema as unknown as AnyObjectSchema;
+
+/**
+ * Apply {@link stripDefaultWrappers} to every field in a Zod object shape and
+ * return the resulting shape record. Callers typically feed the result to
+ * `.extend()` + `.partial()`.
+ *
+ * @internal
+ */
+export const stripDefaultsFromShape = (
+  schema: z.ZodType
+): Record<string, z.ZodType> => {
+  const stripped: Record<string, z.ZodType> = {};
+  const objectSchema = asObjectSchema(schema);
+
+  for (const [field, value] of Object.entries(objectSchema.shape)) {
+    stripped[field] = stripDefaultWrappers(value);
+  }
+
+  return stripped;
+};

package/src/layer.ts

@@ -0,0 +1,50 @@
+import type { AnyTrail } from './trail.js';
+import type { Implementation } from './types.js';
+
+// ---------------------------------------------------------------------------
+// Layer interface
+// ---------------------------------------------------------------------------
+
+/** A composable layer that wraps trail implementations. */
+export interface Layer {
+  readonly name: string;
+  readonly description?: string | undefined;
+
+  /**
+   * Wrap a trail's implementation, returning a new implementation.
+   *
+   * The trail is passed for metadata inspection (intent, schema, etc.).
+   * The implementation and return type are generic over the input/output
+   * types so layers remain type-safe when composed.
+   */
+  wrap<I, O>(
+    trail: AnyTrail,
+    implementation: Implementation<I, O>
+  ): Implementation<I, O>;
+}
+
+// ---------------------------------------------------------------------------
+// Composition
+// ---------------------------------------------------------------------------
+
+/**
+ * Apply layers outermost-first: layers[0] wraps layers[1] wraps ... wraps
+ * the base implementation.
+ *
+ * An empty layers array returns the implementation unchanged.
+ */
+export const composeLayers = <I, O>(
+  layers: readonly Layer[],
+  trail: AnyTrail,
+  implementation: Implementation<I, O>
+): Implementation<I, O> => {
+  // Fold right so layers[0] is the outermost wrapper.
+  let result = implementation;
+  for (let i = layers.length - 1; i >= 0; i -= 1) {
+    const layer = layers[i];
+    if (layer) {
+      result = layer.wrap(trail, result);
+    }
+  }
+  return result;
+};

package/src/path-security.ts

@@ -70,7 +70,7 @@ export const isPathSafe = (basePath: string, userPath: string): boolean => {
  * Joins multiple path segments, resolves them against `basePath`, and
  * validates the result stays within the base directory.
  */
-export const resolveSafePath = (
+export const deriveSafePath = (
   basePath: string,
   ...segments: string[]
 ): Result<string, PermissionError> => {

package/src/resilience.ts

@@ -61,11 +61,11 @@ const sleep = (ms: number, signal?: AbortSignal): Promise<void> =>
 export const shouldRetry = (error: Error): boolean => isRetryable(error);
 
 // ---------------------------------------------------------------------------
-// getBackoffDelay
+// deriveBackoffDelay
 // ---------------------------------------------------------------------------
 
 /** Compute exponential backoff delay with full jitter. */
-export const getBackoffDelay = (
+export const deriveBackoffDelay = (
   attempt: number,
   options?: Pick<RetryOptions, 'baseDelay' | 'maxDelay' | 'backoffFactor'>
 ): number => {
@@ -108,7 +108,7 @@ const tryAttempt = async <T>(
   if (isLast || !retryPredicate(result.error)) {
     return { done: true, result };
   }
-  const delay = getBackoffDelay(attempt, options);
+  const delay = deriveBackoffDelay(attempt, options);
   if (delay > 0) {
     await sleep(delay, options?.signal);
   }