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

package/src/provision.ts

@@ -0,0 +1,148 @@
+import { NotFoundError } from './errors.js';
+import type { Result } from './result.js';
+import type { ProvisionLookup, TrailContext } from './types.js';
+import type { z } from 'zod';
+
+/**
+ * Stable process-scoped fields available when constructing a provision.
+ *
+ * Provisions are app-level singletons, so they intentionally do not receive
+ * the full per-request TrailContext. When a provision declares a `config` schema,
+ * the validated config is passed as `svc.config`.
+ */
+export type ProvisionContext<C = unknown> = Pick<
+  TrailContext,
+  'cwd' | 'env' | 'workspaceRoot'
+> & {
+  readonly config: C;
+};
+
+/**
+ * Everything needed to describe a provision before a factory is introduced.
+ *
+ * When `config` is a Zod schema, the `create` callback receives
+ * `ProvisionContext<C>` with the validated config value.
+ */
+export interface ProvisionSpec<T, C = unknown> {
+  /** Create the provision instance from stable process-scoped context. */
+  readonly create: (
+    svc: ProvisionContext<C>
+  ) => Result<T, Error> | Promise<Result<T, Error>>;
+  /** Config schema — when present, config is validated and passed to `create`. */
+  readonly config?: z.ZodType<C> | undefined;
+  /** Optional cleanup performed when the hosting trailhead shuts down. */
+  readonly dispose?: ((provision: T) => void | Promise<void>) | undefined;
+  /** Optional operational readiness probe for introspection tooling. */
+  readonly health?:
+    | ((
+        provision: T
+      ) => Result<unknown, Error> | Promise<Result<unknown, Error>>)
+    | undefined;
+  /** Optional test factory used by higher-level helpers. */
+  readonly mock?: (() => T | Promise<T>) | undefined;
+  /** Human-readable description. */
+  readonly description?: string | undefined;
+  /** Arbitrary meta for tooling and filtering. */
+  readonly meta?: Readonly<Record<string, unknown>> | undefined;
+}
+
+/** A typed provision definition. */
+export interface Provision<T> extends ProvisionSpec<T> {
+  readonly kind: 'provision';
+  readonly id: string;
+  /** Read the resolved provision instance from a trail context. */
+  from(ctx: TrailContext): T;
+}
+
+/**
+ * Existential type for heterogeneous provision collections.
+ *
+ * `Provision<T>` includes function parameters in `dispose`/`health`, so
+ * `unknown` is too narrow for mixed provision arrays. `any` is the correct
+ * existential here.
+ */
+// oxlint-disable-next-line no-explicit-any -- existential type for heterogeneous provision collections
+export type AnyProvision = Provision<any>;
+
+/** Explicit runtime overrides keyed by provision ID. */
+export type ProvisionOverrideMap = Readonly<Record<string, unknown>>;
+
+const getProvisionId = <T>(
+  provisionOrId: string | Pick<Provision<T>, 'id'>
+): string =>
+  typeof provisionOrId === 'string' ? provisionOrId : provisionOrId.id;
+
+const getProvisionInstance = <T>(
+  ctx: Pick<TrailContext, 'extensions'>,
+  provisionOrId: string | Pick<Provision<T>, 'id'>
+): T => {
+  const id = getProvisionId(provisionOrId);
+  return ctx.extensions?.[id] as T;
+};
+
+const hasProvisionInstance = (
+  ctx: Pick<TrailContext, 'extensions'>,
+  provisionOrId: string | Pick<AnyProvision, 'id'>
+): boolean =>
+  Object.hasOwn(ctx.extensions ?? {}, getProvisionId(provisionOrId));
+
+/** Create a `ctx.provision(...)` accessor bound to a concrete context snapshot. */
+export const createProvisionLookup = (
+  getContext: () => Pick<TrailContext, 'extensions'>
+): ProvisionLookup =>
+  ((provisionOrId: string | Pick<AnyProvision, 'id'>) => {
+    const id = getProvisionId(provisionOrId);
+    const ctx = getContext();
+    if (!hasProvisionInstance(ctx, id)) {
+      throw new NotFoundError(`Provision "${id}" not found in trail context`);
+    }
+    return getProvisionInstance(ctx, id);
+  }) as ProvisionLookup;
+
+/**
+ * Create a typed provision definition.
+ *
+ * The provision object is inert until a later execution branch resolves concrete
+ * instances into TrailContext extensions.
+ */
+export const provision = <T>(
+  id: string,
+  spec: ProvisionSpec<T>
+): Provision<T> =>
+  Object.freeze({
+    ...spec,
+    from(ctx: TrailContext): T {
+      const lookup = ctx.provision ?? createProvisionLookup(() => ctx);
+      return lookup(this);
+    },
+    id,
+    kind: 'provision' as const,
+  });
+
+/** Narrow unknown values to provision definitions during topo discovery. */
+export const isProvision = (value: unknown): value is AnyProvision => {
+  if (typeof value !== 'object' || value === null) {
+    return false;
+  }
+  const v = value as { kind?: unknown; id?: unknown };
+  return v.kind === 'provision' && typeof v.id === 'string';
+};
+
+/**
+ * Return the first duplicate provision ID in a collection, if any.
+ *
+ * This supports later topo registration without each caller duplicating the
+ * same scan logic.
+ */
+export const findDuplicateProvisionId = (
+  provisions: readonly Pick<AnyProvision, 'id'>[]
+): string | undefined => {
+  const seen = new Set<string>();
+  for (const candidate of provisions) {
+    if (seen.has(candidate.id)) {
+      return candidate.id;
+    }
+    seen.add(candidate.id);
+  }
+  return undefined;
+};

package/src/{dispatch.ts → run.ts}

@@ -1,5 +1,5 @@
 /**
- * Headless trail execution — the "no-surface" surface.
+ * Headless trail execution without mounting a trailhead.
  *
  * Looks up a trail by ID in a topo, then delegates to `executeTrail`.
  * Returns a `Result` and never throws.
@@ -15,15 +15,15 @@ import { Result } from './result.js';
 // Options
 // ---------------------------------------------------------------------------
 
-/** Options forwarded to `executeTrail` from `dispatch`. */
-export type DispatchOptions = ExecuteTrailOptions;
+/** Options forwarded to `executeTrail` from `run`. */
+export type RunOptions = ExecuteTrailOptions;
 
 // ---------------------------------------------------------------------------
-// dispatch()
+// run()
 // ---------------------------------------------------------------------------
 
 /**
- * Execute a trail by ID from a topo without mounting a surface.
+ * Execute a trail by ID from a topo without mounting a trailhead.
  *
  * Resolves the trail from the topo, then runs it through the standard
  * `executeTrail` pipeline. Returns `Result.err(NotFoundError)` if the
@@ -32,15 +32,15 @@ export type DispatchOptions = ExecuteTrailOptions;
  *
  * @example
  * ```typescript
- * const result = await dispatch(myTopo, 'greet', { name: 'Alice' });
+ * const result = await run(myTopo, 'greet', { name: 'Alice' });
  * if (result.isOk()) console.log(result.value);
  * ```
  */
-export const dispatch = (
+export const run = (
   topo: Topo,
   id: string,
   input: unknown,
-  options?: DispatchOptions
+  options?: RunOptions
 ): Promise<Result<unknown, Error>> => {
   const trail = topo.get(id);
   if (trail === undefined) {

package/src/signal.ts

@@ -0,0 +1,65 @@
+/**
+ * Signal — a named payload schema with optional provenance meta.
+ */
+
+import type { z } from 'zod';
+
+// ---------------------------------------------------------------------------
+// Spec (input to the factory)
+// ---------------------------------------------------------------------------
+
+export interface SignalSpec<T> {
+  readonly payload: z.ZodType<T>;
+  readonly description?: string | undefined;
+  readonly meta?: Readonly<Record<string, unknown>> | undefined;
+  /** Trail IDs that produce this signal (e.g. the trails it originates from). */
+  readonly from?: readonly string[] | undefined;
+}
+
+// ---------------------------------------------------------------------------
+// Shape (output of the factory)
+// ---------------------------------------------------------------------------
+
+export interface Signal<T> {
+  readonly id: string;
+  readonly kind: 'signal';
+  readonly payload: z.ZodType<T>;
+  readonly description?: string | undefined;
+  readonly meta?: Readonly<Record<string, unknown>> | undefined;
+  /** Trail IDs that produce this signal (e.g. the trails it originates from). */
+  readonly from?: readonly string[] | undefined;
+}
+
+// ---------------------------------------------------------------------------
+// Factory
+// ---------------------------------------------------------------------------
+
+/**
+ * Create a signal definition.
+ *
+ * A signal is a named payload schema describing something that happened.
+ * Returns a frozen object with `kind: "signal"` and all spec fields.
+ */
+export function signal<T>(id: string, spec: SignalSpec<T>): Signal<T>;
+export function signal<T>(
+  spec: SignalSpec<T> & { readonly id: string }
+): Signal<T>;
+export function signal<T>(
+  idOrSpec: string | (SignalSpec<T> & { readonly id: string }),
+  maybeSpec?: SignalSpec<T>
+): Signal<T> {
+  const resolvedId = typeof idOrSpec === 'string' ? idOrSpec : idOrSpec.id;
+  // oxlint-disable-next-line no-non-null-assertion -- overload guarantees maybeSpec when idOrSpec is string
+  const resolvedSpec = typeof idOrSpec === 'string' ? maybeSpec! : idOrSpec;
+  return Object.freeze({
+    description: resolvedSpec.description,
+    from: resolvedSpec.from ? Object.freeze([...resolvedSpec.from]) : undefined,
+    id: resolvedId,
+    kind: 'signal' as const,
+    meta: resolvedSpec.meta,
+    payload: resolvedSpec.payload,
+  });
+}
+
+/** Existential type for heterogeneous signal collections */
+export type AnySignal = Signal<unknown>;

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(),
+});