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

package/src/internal/trails-db.ts

@@ -0,0 +1,189 @@
+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 resolveRootDir = (rootDir?: string): string =>
+  resolve(rootDir ?? process.cwd());
+
+export const resolveTrailsDir = (options?: TrailsDbLocationOptions): string =>
+  join(resolveRootDir(options?.rootDir), TRAILS_DIR);
+
+export const resolveTrailsDbPath = (
+  options?: TrailsDbLocationOptions
+): string =>
+  options?.path
+    ? resolve(options.path)
+    : join(resolveTrailsDir(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 = resolveTrailsDir({ 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 = resolveRootDir(options?.rootDir);
+  const dbPath = resolveTrailsDbPath(
+    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 = resolveTrailsDbPath(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/topo-store.ts

@@ -0,0 +1,301 @@
+import type { SQLQueryBindings } from 'bun:sqlite';
+import { existsSync } from 'node:fs';
+
+import { NotFoundError } from './errors.js';
+import { provision } from './provision.js';
+import { Result } from './result.js';
+import type { TopoPinRecord, TopoSaveRecord } from './internal/topo-saves.js';
+import { getTopoPin } from './internal/topo-saves.js';
+import type {
+  TopoStoreExportRecord,
+  TopoStoreProvisionRecord,
+  TopoStoreRef,
+  TopoStoreTrailDetailRecord,
+  TopoStoreTrailRecord,
+} from './internal/topo-store-read.js';
+import {
+  getTopoStoreExport,
+  getTopoStoreProvision,
+  getTopoStoreTrail,
+  listTopoStorePins,
+  listTopoStoreProvisions,
+  listTopoStoreSaves,
+  listTopoStoreTrails,
+  queryTopoStore,
+  resolveTopoStoreSave,
+} from './internal/topo-store-read.js';
+import { openReadTrailsDb, resolveTrailsDbPath } from './internal/trails-db.js';
+import type { TrailsDbLocationOptions } from './internal/trails-db.js';
+
+export type {
+  TopoStoreExportRecord,
+  TopoStoreProvisionRecord,
+  TopoStoreRef,
+  TopoStoreTrailDetailRecord,
+  TopoStoreTrailRecord,
+} from './internal/topo-store-read.js';
+
+export interface ReadOnlyTopoStore {
+  readonly exports: {
+    get(ref?: TopoStoreRef): TopoStoreExportRecord | undefined;
+  };
+  readonly pins: {
+    get(name: string): TopoPinRecord | undefined;
+    list(): readonly TopoPinRecord[];
+  };
+  query<TRow extends Record<string, unknown>>(
+    sql: string,
+    bindings?: readonly SQLQueryBindings[]
+  ): readonly TRow[];
+  readonly provisions: {
+    get(
+      id: string,
+      options?: { readonly save?: TopoStoreRef }
+    ): TopoStoreProvisionRecord | undefined;
+    list(options?: {
+      readonly save?: TopoStoreRef;
+    }): readonly TopoStoreProvisionRecord[];
+  };
+  readonly saves: {
+    get(ref?: TopoStoreRef): TopoSaveRecord | undefined;
+    latest(): TopoSaveRecord | undefined;
+    list(): readonly TopoSaveRecord[];
+  };
+  readonly trails: {
+    get(
+      id: string,
+      options?: { readonly save?: TopoStoreRef }
+    ): TopoStoreTrailDetailRecord | undefined;
+    list(options?: {
+      readonly intent?: TopoStoreTrailRecord['intent'];
+      readonly save?: TopoStoreRef;
+    }): readonly TopoStoreTrailRecord[];
+  };
+}
+
+export interface MockTopoStoreSeed {
+  readonly exports?: readonly TopoStoreExportRecord[];
+  readonly pins?: readonly TopoPinRecord[];
+  readonly provisions?: readonly TopoStoreProvisionRecord[];
+  readonly saves?: readonly TopoSaveRecord[];
+  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 = resolveTrailsDbPath(options);
+  if (!existsSync(dbPath)) {
+    throw new NotFoundError(missingStoreMessage);
+  }
+  return openReadTrailsDb(options);
+};
+
+const requireSavedTopoState = (
+  db: ReturnType<typeof openReadTrailsDb>
+): void => {
+  if (resolveTopoStoreSave(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 saves = [...(seed?.saves ?? [])];
+  const pins = [...(seed?.pins ?? [])];
+  const trails = [...(seed?.trails ?? [])];
+  const provisions = [...(seed?.provisions ?? [])];
+  const exports = [...(seed?.exports ?? [])];
+
+  const resolveSave = (ref?: TopoStoreRef): TopoSaveRecord | undefined => {
+    if (ref?.saveId !== undefined) {
+      return saves.find((save) => save.id === ref.saveId);
+    }
+    if (ref?.pin !== undefined) {
+      const pin = pins.find((candidate) => candidate.name === ref.pin);
+      return pin === undefined
+        ? undefined
+        : saves.find((save) => save.id === pin.saveId);
+    }
+    return saves[0];
+  };
+
+  return {
+    exports,
+    pins,
+    provisions,
+    resolveSave,
+    saves,
+    trails,
+  };
+};
+
+export const createMockTopoStore = (
+  seed?: MockTopoStoreSeed
+): ReadOnlyTopoStore => {
+  const resolved = createSeedResolver(seed);
+
+  return {
+    exports: {
+      get(ref?: TopoStoreRef) {
+        const save = resolved.resolveSave(ref);
+        return save === undefined
+          ? undefined
+          : resolved.exports.find((entry) => entry.save.id === save.id);
+      },
+    },
+    pins: {
+      get(name: string) {
+        return resolved.pins.find((pin) => pin.name === name);
+      },
+      list() {
+        return resolved.pins;
+      },
+    },
+    provisions: {
+      get(id, options) {
+        const save = resolved.resolveSave(options?.save);
+        return resolved.provisions.find(
+          (item) =>
+            item.id === id && (save === undefined || item.saveId === save.id)
+        );
+      },
+      list(options) {
+        const save = resolved.resolveSave(options?.save);
+        return save === undefined
+          ? []
+          : resolved.provisions.filter((item) => item.saveId === save.id);
+      },
+    },
+    query() {
+      throw new NotFoundError(
+        'Mock topoStore.query() is unsupported. Seed typed accessors instead.'
+      );
+    },
+    saves: {
+      get(ref?: TopoStoreRef) {
+        return resolved.resolveSave(ref);
+      },
+      latest() {
+        return resolved.saves[0];
+      },
+      list() {
+        return resolved.saves;
+      },
+    },
+    trails: {
+      get(id, options) {
+        const save = resolved.resolveSave(options?.save);
+        if (save === undefined) {
+          return;
+        }
+        return resolved.trails.find(
+          (trail) => trail.id === id && trail.saveId === save.id
+        );
+      },
+      list(options) {
+        const save = resolved.resolveSave(options?.save);
+        if (save === undefined) {
+          return [];
+        }
+        return resolved.trails.filter(
+          (trail) =>
+            trail.saveId === save.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));
+    },
+  },
+  pins: {
+    get(name: string) {
+      return withStoredTopoState(options, (db) => getTopoPin(db, name));
+    },
+    list() {
+      return withStoredTopoState(options, (db) => listTopoStorePins(db));
+    },
+  },
+  provisions: {
+    get(id, queryOptions) {
+      return withStoredTopoState(options, (db) =>
+        getTopoStoreProvision(db, id, queryOptions)
+      );
+    },
+    list(queryOptions) {
+      return withStoredTopoState(options, (db) =>
+        listTopoStoreProvisions(db, queryOptions)
+      );
+    },
+  },
+  query<TRow extends Record<string, unknown>>(
+    sql: string,
+    bindings?: readonly SQLQueryBindings[]
+  ) {
+    return withStoredTopoState(options, (db) =>
+      queryTopoStore<TRow>(db, sql, bindings)
+    );
+  },
+  saves: {
+    get(ref?: TopoStoreRef) {
+      return withStoredTopoState(options, (db) =>
+        resolveTopoStoreSave(db, ref)
+      );
+    },
+    latest() {
+      return withStoredTopoState(options, (db) => resolveTopoStoreSave(db));
+    },
+    list() {
+      return withStoredTopoState(options, (db) => listTopoStoreSaves(db));
+    },
+  },
+  trails: {
+    get(id, queryOptions) {
+      return withStoredTopoState(options, (db) =>
+        getTopoStoreTrail(db, id, queryOptions)
+      );
+    },
+    list(queryOptions) {
+      return withStoredTopoState(options, (db) =>
+        listTopoStoreTrails(db, queryOptions)
+      );
+    },
+  },
+});
+
+export const topoStore = provision('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(),
+});

package/src/validate-established-topo.ts

@@ -0,0 +1,63 @@
+import { ValidationError } from './errors.js';
+import { Result } from './result.js';
+import type { Topo } from './topo.js';
+import { validateEstablishedTopo as validateDraftFreeTopo } from './draft.js';
+import type { TopoIssue } from './validate-topo.js';
+import { validateTopo } from './validate-topo.js';
+
+const PROJECTION_BLOCKING_RULES = new Set([
+  'cross-cycle',
+  'cross-exists',
+  'no-self-cross',
+  'provision-exists',
+  'signal-origin-exists',
+]);
+
+const keepProjectionBlockingIssues = (
+  result: ReturnType<typeof validateTopo>
+) => {
+  if (result.isOk()) {
+    return result;
+  }
+
+  const issues = (
+    result.error.context as { issues?: readonly TopoIssue[] } | undefined
+  )?.issues;
+  const remainingIssues = issues?.filter((issue) =>
+    PROJECTION_BLOCKING_RULES.has(issue.rule)
+  );
+
+  if (remainingIssues === undefined || remainingIssues.length === 0) {
+    return Result.ok();
+  }
+
+  return Result.err(
+    new ValidationError(
+      `Topo validation failed with ${remainingIssues.length} issue(s)`,
+      {
+        cause: result.error,
+        context: { issues: remainingIssues },
+      }
+    )
+  );
+};
+
+/**
+ * Validate that a topo is ready for established outputs.
+ *
+ * Established surfaces still require the authored graph to be structurally
+ * valid, and they must also reject any remaining draft state.
+ */
+export const validateEstablishedTopo = (topo: Topo) => {
+  const structural = keepProjectionBlockingIssues(validateTopo(topo));
+  if (structural.isErr()) {
+    return structural;
+  }
+
+  const established = validateDraftFreeTopo(topo);
+  if (established.isErr()) {
+    return established;
+  }
+
+  return Result.ok();
+};

package/src/validate-topo.ts

@@ -7,6 +7,7 @@
  */
 
 import { ValidationError } from './errors.js';
+import { isDraftId } from './draft.js';
 import type { AnySignal } from './event.js';
 import { Result } from './result.js';
 import type { Topo } from './topo.js';
@@ -100,7 +101,7 @@ const checkCrosses = (
           rule: 'no-self-cross',
           trailId: id,
         });
-      } else if (!topo.has(crossedId)) {
+      } else if (!topo.has(crossedId) && !isDraftId(crossedId)) {
         issues.push({
           message: `Crosses "${crossedId}" which is not in the topo`,
           rule: 'cross-exists',
@@ -121,7 +122,10 @@ const checkProvisions = (
 
   for (const [id, trail] of trails) {
     for (const declaredProvision of trail.provisions) {
-      if (!topo.hasProvision(declaredProvision.id)) {
+      if (
+        !topo.hasProvision(declaredProvision.id) &&
+        !isDraftId(declaredProvision.id)
+      ) {
         issues.push({
           message: `Provision "${declaredProvision.id}" is not in the topo`,
           rule: 'provision-exists',
@@ -187,7 +191,7 @@ const checkSignalOrigins = (
       continue;
     }
     for (const originId of evt.from) {
-      if (!topo.has(originId)) {
+      if (!topo.has(originId) && !isDraftId(originId)) {
         issues.push({
           message: `Signal origin "${originId}" is not in the topo`,
           rule: 'signal-origin-exists',

package/tsconfig.tsbuildinfo

@@ -1 +1 @@
-{"root":["./src/blob-ref.ts","./src/branded.ts","./src/collections.ts","./src/context.ts","./src/derive.ts","./src/errors.ts","./src/event.ts","./src/execute.ts","./src/fetch.ts","./src/gate.ts","./src/guards.ts","./src/index.ts","./src/path-security.ts","./src/provision-config.ts","./src/provision.ts","./src/resilience.ts","./src/result.ts","./src/run.ts","./src/serialization.ts","./src/signal.ts","./src/topo.ts","./src/trail.ts","./src/type-utils.ts","./src/types.ts","./src/validate-topo.ts","./src/validation.ts","./src/workspace.ts","./src/patterns/bulk.ts","./src/patterns/change.ts","./src/patterns/date-range.ts","./src/patterns/index.ts","./src/patterns/pagination.ts","./src/patterns/progress.ts","./src/patterns/sorting.ts","./src/patterns/status.ts","./src/patterns/timestamps.ts","./src/redaction/index.ts","./src/redaction/patterns.ts","./src/redaction/redactor.ts"],"version":"5.9.3"}
+{"root":["./src/blob-ref.ts","./src/branded.ts","./src/collections.ts","./src/context.ts","./src/derive.ts","./src/draft.ts","./src/errors.ts","./src/event.ts","./src/execute.ts","./src/fetch.ts","./src/gate.ts","./src/guards.ts","./src/index.ts","./src/path-security.ts","./src/provision-config.ts","./src/provision.ts","./src/resilience.ts","./src/result.ts","./src/run.ts","./src/serialization.ts","./src/signal.ts","./src/topo-store.ts","./src/topo.ts","./src/trail.ts","./src/type-utils.ts","./src/types.ts","./src/validate-established-topo.ts","./src/validate-topo.ts","./src/validation.ts","./src/workspace.ts","./src/internal/topo-saves.ts","./src/internal/topo-store-read.ts","./src/internal/topo-store.ts","./src/internal/trails-db.ts","./src/patterns/bulk.ts","./src/patterns/change.ts","./src/patterns/date-range.ts","./src/patterns/index.ts","./src/patterns/pagination.ts","./src/patterns/progress.ts","./src/patterns/sorting.ts","./src/patterns/status.ts","./src/patterns/timestamps.ts","./src/redaction/index.ts","./src/redaction/patterns.ts","./src/redaction/redactor.ts"],"version":"5.9.3"}