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

package/src/internal/tracing.ts

@@ -1,187 +0,0 @@
-/**
- * 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/topo-store.ts

@@ -1,510 +0,0 @@
-import type { SQLQueryBindings } from 'bun:sqlite';
-import { existsSync, statSync } from 'node:fs';
-
-import { NotFoundError } from './errors.js';
-import type { Topo } from './topo.js';
-import { resource } from './resource.js';
-import { Result } from './result.js';
-import {
-  TOPO_SCHEMA_VERSION,
-  ensureTopoSnapshotSchema,
-  listTopoSnapshots as listStoredTopoSnapshots,
-  pinTopoSnapshot as pinStoredTopoSnapshot,
-  unpinTopoSnapshot as unpinStoredTopoSnapshot,
-} from './internal/topo-snapshots.js';
-import type {
-  CreateTopoSnapshotInput,
-  ListTopoSnapshotsOptions,
-  TopoSnapshot,
-} from './internal/topo-snapshots.js';
-import type {
-  TopoStoreExportRecord,
-  TopoStoreResourceRecord,
-  TopoStoreRef,
-  TopoStoreTrailDetailRecord,
-  TopoStoreTrailRecord,
-} from './internal/topo-store-read.js';
-import {
-  getTopoStoreExport,
-  getTopoStoreResource,
-  getTopoStoreTrail,
-  listTopoStoreResources,
-  listTopoStoreSnapshots,
-  listTopoStoreTrails,
-  queryTopoStore,
-  readTopoStoreSnapshot,
-} from './internal/topo-store-read.js';
-import { createTopoSnapshot as storeTopoSnapshot } from './internal/topo-store.js';
-import {
-  openReadTrailsDb,
-  openWriteTrailsDb,
-  deriveTrailsDbPath,
-} from './internal/trails-db.js';
-import type { TrailsDbLocationOptions } from './internal/trails-db.js';
-
-interface MigratedDbIdentity {
-  readonly mtimeMs: number;
-  readonly size: number;
-}
-
-const migratedTopoDbPaths = new Map<string, MigratedDbIdentity>();
-
-/**
- * Test-only instrumentation counters. Incremented by the read-path migration
- * check to let tests assert that a current-schema store does not escalate to
- * a write-mode open, and that cache invalidation re-runs the check when the
- * underlying file is replaced.
- *
- * @internal
- */
-export const __topoStoreMigrationStats = {
-  peekCalls: 0,
-  writeEscalations: 0,
-};
-
-const peekTopoSchemaVersion = (
-  options: TrailsDbLocationOptions | undefined
-): number | undefined => {
-  let db: ReturnType<typeof openReadTrailsDb> | undefined;
-  try {
-    db = openReadTrailsDb(options);
-    const row = db
-      .query<{ version: number }, [string]>(
-        'SELECT version FROM meta_schema_versions WHERE subsystem = ?'
-      )
-      .get('topo');
-    return row?.version ?? 0;
-  } catch {
-    // Table missing or unexpected shape: caller will escalate to a write-mode
-    // open and run the migration, which rebuilds the schema.
-    return undefined;
-  } finally {
-    db?.close();
-  }
-};
-
-const statIdentity = (dbPath: string): MigratedDbIdentity | undefined => {
-  try {
-    const info = statSync(dbPath);
-    return { mtimeMs: info.mtimeMs, size: info.size };
-  } catch {
-    return undefined;
-  }
-};
-
-const identitiesEqual = (
-  a: MigratedDbIdentity,
-  b: MigratedDbIdentity
-): boolean => a.mtimeMs === b.mtimeMs && a.size === b.size;
-
-const runTopoMigrationEscalation = (
-  options: TrailsDbLocationOptions | undefined,
-  dbPath: string,
-  fallbackIdentity: MigratedDbIdentity
-): void => {
-  __topoStoreMigrationStats.writeEscalations += 1;
-  const db = openWriteTrailsDb(options);
-  try {
-    ensureTopoSnapshotSchema(db);
-  } finally {
-    db.close();
-  }
-  // Re-stat after the migration so the cached identity matches the file we
-  // just touched, avoiding a spurious second escalation on the next read.
-  const postIdentity = statIdentity(dbPath) ?? fallbackIdentity;
-  migratedTopoDbPaths.set(dbPath, postIdentity);
-};
-
-const resolveIdentityIfFresh = (
-  dbPath: string
-): MigratedDbIdentity | undefined => {
-  if (!existsSync(dbPath)) {
-    return undefined;
-  }
-  const identity = statIdentity(dbPath);
-  if (identity === undefined) {
-    return undefined;
-  }
-  const cached = migratedTopoDbPaths.get(dbPath);
-  if (cached !== undefined && identitiesEqual(cached, identity)) {
-    return undefined;
-  }
-  return identity;
-};
-
-/**
- * Ensure the topo snapshot schema is at the current version before any
- * read-only access. Peeks the version through a read-only handle first and
- * only escalates to a write-mode open + migration when the store is stale.
- *
- * Memoized per resolved DB path keyed on file identity (mtime + size) so a
- * long-running process that deletes and recreates `trails.db` re-runs the
- * migration check against the fresh file.
- *
- * If the DB file does not yet exist, this is a no-op — the downstream read
- * path will surface its own NotFoundError.
- */
-const ensureTopoMigratedIfExists = (
-  options?: TrailsDbLocationOptions
-): void => {
-  const dbPath = deriveTrailsDbPath(options);
-  const identity = resolveIdentityIfFresh(dbPath);
-  if (identity === undefined) {
-    return;
-  }
-
-  __topoStoreMigrationStats.peekCalls += 1;
-  const version = peekTopoSchemaVersion(options);
-  if (version !== undefined && version >= TOPO_SCHEMA_VERSION) {
-    // Already current — record identity and skip the write-mode open entirely,
-    // preserving the read-only contract for callers whose filesystem mounts
-    // `trails.db` read-only.
-    migratedTopoDbPaths.set(dbPath, identity);
-    return;
-  }
-
-  runTopoMigrationEscalation(options, dbPath, identity);
-};
-
-export type {
-  TopoStoreExportRecord,
-  TopoStoreResourceRecord,
-  TopoStoreRef,
-  TopoStoreTrailDetailRecord,
-  TopoStoreTrailRecord,
-} from './internal/topo-store-read.js';
-export type {
-  CreateTopoSnapshotInput,
-  ListTopoSnapshotsOptions,
-  TopoSnapshot,
-} from './internal/topo-snapshots.js';
-
-export interface ReadOnlyTopoStore {
-  readonly exports: {
-    get(ref?: TopoStoreRef): TopoStoreExportRecord | undefined;
-  };
-  query<TRow extends Record<string, unknown>>(
-    sql: string,
-    bindings?: readonly SQLQueryBindings[]
-  ): readonly TRow[];
-  readonly resources: {
-    get(
-      id: string,
-      options?: { readonly snapshot?: TopoStoreRef }
-    ): TopoStoreResourceRecord | undefined;
-    list(options?: {
-      readonly snapshot?: TopoStoreRef;
-    }): readonly TopoStoreResourceRecord[];
-  };
-  readonly snapshots: {
-    get(ref?: TopoStoreRef): TopoSnapshot | undefined;
-    latest(): TopoSnapshot | undefined;
-    list(options?: ListTopoSnapshotsOptions): readonly TopoSnapshot[];
-  };
-  readonly trails: {
-    get(
-      id: string,
-      options?: { readonly snapshot?: TopoStoreRef }
-    ): TopoStoreTrailDetailRecord | undefined;
-    list(options?: {
-      readonly intent?: TopoStoreTrailRecord['intent'];
-      readonly snapshot?: TopoStoreRef;
-    }): readonly TopoStoreTrailRecord[];
-  };
-}
-
-export interface MockTopoStoreSeed {
-  readonly exports?: readonly TopoStoreExportRecord[];
-  readonly resources?: readonly TopoStoreResourceRecord[];
-  readonly snapshots?: readonly TopoSnapshot[];
-  readonly trails?: readonly TopoStoreTrailDetailRecord[];
-}
-
-const missingStoreMessage =
-  'No saved topo state found. Populate trails.db first or run a topo-backed surface.';
-
-const resolveStoreRootDir = (options?: TrailsDbLocationOptions): string =>
-  options?.rootDir ?? process.cwd();
-
-const requireReadDb = (
-  options?: TrailsDbLocationOptions
-): ReturnType<typeof openReadTrailsDb> => {
-  const dbPath = deriveTrailsDbPath(options);
-  if (!existsSync(dbPath)) {
-    throw new NotFoundError(missingStoreMessage);
-  }
-  ensureTopoMigratedIfExists(options);
-  return openReadTrailsDb(options);
-};
-
-const requireSavedTopoState = (
-  db: ReturnType<typeof openReadTrailsDb>
-): void => {
-  if (readTopoStoreSnapshot(db) === undefined) {
-    throw new NotFoundError(missingStoreMessage);
-  }
-};
-
-const withStoredTopoState = <T>(
-  options: TrailsDbLocationOptions | undefined,
-  run: (db: ReturnType<typeof openReadTrailsDb>) => T
-): T => {
-  const db = requireReadDb(options);
-  try {
-    requireSavedTopoState(db);
-    return run(db);
-  } finally {
-    db.close();
-  }
-};
-
-const createSeedResolver = (seed?: MockTopoStoreSeed) => {
-  const snapshots = [...(seed?.snapshots ?? [])];
-  const trails = [...(seed?.trails ?? [])];
-  const resources = [...(seed?.resources ?? [])];
-  const exports = [...(seed?.exports ?? [])];
-
-  const resolveSnapshot = (ref?: TopoStoreRef): TopoSnapshot | undefined => {
-    if (ref?.snapshotId !== undefined) {
-      return snapshots.find((snapshot) => snapshot.id === ref.snapshotId);
-    }
-    if (ref?.pin !== undefined) {
-      return snapshots.find((snapshot) => snapshot.pinnedAs === ref.pin);
-    }
-    return snapshots[0];
-  };
-
-  return {
-    exports,
-    resolveSnapshot,
-    resources,
-    snapshots,
-    trails,
-  };
-};
-
-export const createMockTopoStore = (
-  seed?: MockTopoStoreSeed
-): ReadOnlyTopoStore => {
-  const resolved = createSeedResolver(seed);
-
-  return {
-    exports: {
-      get(ref?: TopoStoreRef) {
-        const snapshot = resolved.resolveSnapshot(ref);
-        return snapshot === undefined
-          ? undefined
-          : resolved.exports.find((entry) => entry.snapshot.id === snapshot.id);
-      },
-    },
-    query() {
-      throw new NotFoundError(
-        'Mock topoStore.query() is unsupported. Seed typed accessors instead.'
-      );
-    },
-    resources: {
-      get(id, options) {
-        const snapshot = resolved.resolveSnapshot(options?.snapshot);
-        return resolved.resources.find(
-          (item) =>
-            item.id === id &&
-            (snapshot === undefined || item.snapshotId === snapshot.id)
-        );
-      },
-      list(options) {
-        const snapshot = resolved.resolveSnapshot(options?.snapshot);
-        return snapshot === undefined
-          ? []
-          : resolved.resources.filter(
-              (item) => item.snapshotId === snapshot.id
-            );
-      },
-    },
-    snapshots: {
-      get(ref?: TopoStoreRef) {
-        return resolved.resolveSnapshot(ref);
-      },
-      latest() {
-        return resolved.snapshots[0];
-      },
-      list(options) {
-        let snapshots =
-          options?.pinned === undefined
-            ? resolved.snapshots
-            : resolved.snapshots.filter((snapshot) =>
-                options.pinned
-                  ? snapshot.pinnedAs !== undefined
-                  : snapshot.pinnedAs === undefined
-              );
-        if (options?.before !== undefined) {
-          const target = snapshots.find((s) => s.id === options.before);
-          if (target !== undefined) {
-            snapshots = snapshots.filter(
-              (s) =>
-                s.createdAt < target.createdAt ||
-                (s.createdAt === target.createdAt && s.id < target.id)
-            );
-          }
-        }
-        if (options?.limit !== undefined) {
-          snapshots = snapshots.slice(0, options.limit);
-        }
-        return snapshots;
-      },
-    },
-    trails: {
-      get(id, options) {
-        const snapshot = resolved.resolveSnapshot(options?.snapshot);
-        if (snapshot === undefined) {
-          return;
-        }
-        return resolved.trails.find(
-          (trail) => trail.id === id && trail.snapshotId === snapshot.id
-        );
-      },
-      list(options) {
-        const snapshot = resolved.resolveSnapshot(options?.snapshot);
-        if (snapshot === undefined) {
-          return [];
-        }
-        return resolved.trails.filter(
-          (trail) =>
-            trail.snapshotId === snapshot.id &&
-            (options?.intent === undefined || trail.intent === options.intent)
-        );
-      },
-    },
-  };
-};
-
-export const createTopoStore = (
-  options?: TrailsDbLocationOptions
-): ReadOnlyTopoStore => ({
-  exports: {
-    get(ref?: TopoStoreRef) {
-      return withStoredTopoState(options, (db) => getTopoStoreExport(db, ref));
-    },
-  },
-  query<TRow extends Record<string, unknown>>(
-    sql: string,
-    bindings?: readonly SQLQueryBindings[]
-  ) {
-    return withStoredTopoState(options, (db) =>
-      queryTopoStore<TRow>(db, sql, bindings)
-    );
-  },
-  resources: {
-    get(id, queryOptions) {
-      return withStoredTopoState(options, (db) =>
-        getTopoStoreResource(db, id, queryOptions)
-      );
-    },
-    list(queryOptions) {
-      return withStoredTopoState(options, (db) =>
-        listTopoStoreResources(db, queryOptions)
-      );
-    },
-  },
-  snapshots: {
-    get(ref?: TopoStoreRef) {
-      return withStoredTopoState(options, (db) =>
-        readTopoStoreSnapshot(db, ref)
-      );
-    },
-    latest() {
-      return withStoredTopoState(options, (db) => readTopoStoreSnapshot(db));
-    },
-    list(snapshotOptions) {
-      return withStoredTopoState(options, (db) =>
-        listTopoStoreSnapshots(db, snapshotOptions)
-      );
-    },
-  },
-  trails: {
-    get(id, queryOptions) {
-      return withStoredTopoState(options, (db) =>
-        getTopoStoreTrail(db, id, queryOptions)
-      );
-    },
-    list(queryOptions) {
-      return withStoredTopoState(options, (db) =>
-        listTopoStoreTrails(db, queryOptions)
-      );
-    },
-  },
-});
-
-export const createTopoSnapshot = (
-  topo: Topo,
-  options?: TrailsDbLocationOptions & CreateTopoSnapshotInput
-): Result<TopoSnapshot, Error> => {
-  const db = openWriteTrailsDb(options);
-  try {
-    return storeTopoSnapshot(db, topo, options);
-  } finally {
-    db.close();
-  }
-};
-
-export const listTopoSnapshots = (
-  options?: TrailsDbLocationOptions & ListTopoSnapshotsOptions
-): readonly TopoSnapshot[] => {
-  const dbPath = deriveTrailsDbPath(options);
-  if (!existsSync(dbPath)) {
-    return [];
-  }
-
-  ensureTopoMigratedIfExists(options);
-  const db = openReadTrailsDb(options);
-  try {
-    return listStoredTopoSnapshots(db, options);
-  } finally {
-    db.close();
-  }
-};
-
-export const pinTopoSnapshot = (
-  id: string,
-  name: string,
-  options?: TrailsDbLocationOptions
-): TopoSnapshot | undefined => {
-  const dbPath = deriveTrailsDbPath(options);
-  if (!existsSync(dbPath)) {
-    return undefined;
-  }
-
-  const db = openWriteTrailsDb(options);
-  try {
-    return pinStoredTopoSnapshot(db, { id, name });
-  } finally {
-    db.close();
-  }
-};
-
-export const unpinTopoSnapshot = (
-  nameOrId: string,
-  options?: TrailsDbLocationOptions
-): TopoSnapshot | undefined => {
-  const dbPath = deriveTrailsDbPath(options);
-  if (!existsSync(dbPath)) {
-    return undefined;
-  }
-
-  const db = openWriteTrailsDb(options);
-  try {
-    return unpinStoredTopoSnapshot(db, nameOrId);
-  } finally {
-    db.close();
-  }
-};
-
-export const topoStore = resource('topo.store', {
-  create: (svc) =>
-    Result.ok(
-      createTopoStore({
-        rootDir: svc.workspaceRoot ?? svc.cwd ?? resolveStoreRootDir(),
-      })
-    ),
-  description: 'Read-only query access to saved topo state in trails.db',
-  mock: () => createMockTopoStore(),
-});