@ontrails/core 1.0.0-beta.30 → 1.0.0-beta.39

package/src/trail.ts

@@ -315,6 +315,84 @@ export type TrailVersions<
   >
 >;
 
+/**
+ * Spec for {@link forkVersion}: a fork entry whose blaze signature is owned
+ * by the entry's own schemas instead of falling back to `unknown`.
+ */
+export interface TrailVersionForkSpec<
+  TInputSchema extends z.ZodType,
+  TOutputSchema extends z.ZodType,
+  TComposeInputSchema extends z.ZodType | undefined = undefined,
+> {
+  /** The historical blaze, typed by this entry's schemas. */
+  readonly blaze: Implementation<
+    BlazeInput<
+      z.output<TInputSchema>,
+      ComposeSchemaOutput<TComposeInputSchema>
+    >,
+    z.output<TOutputSchema>
+  >;
+  readonly composeInput?: TComposeInputSchema | undefined;
+  readonly composes?: readonly (string | AnyTrail)[] | undefined;
+  readonly detours?:
+    | readonly Detour<
+        z.output<TInputSchema>,
+        z.output<TOutputSchema>,
+        TrailsError
+      >[]
+    | undefined;
+  readonly examples?:
+    | readonly TrailExample<z.input<TInputSchema>, z.output<TOutputSchema>>[]
+    | undefined;
+  readonly input: TInputSchema;
+  readonly output: TOutputSchema;
+  readonly resources?: readonly AnyResource[] | undefined;
+  readonly status?: TrailVersionStatus | undefined;
+}
+
+/**
+ * Author a fork version entry with a blaze typed by the entry's own schemas.
+ *
+ * `TrailVersions` fixes every entry's generics to `unknown`, so a fork blaze
+ * written inline receives `unknown` input and authors end up re-parsing the
+ * already-validated value just to narrow it. This helper threads the entry's
+ * `input`/`output` schemas into the blaze signature and erases the generics
+ * on the way out. The erasure is sound because the fork pipeline validates
+ * raw input against this entry's own `input` schema before dispatching to
+ * the entry blaze (see `createForkTrailVersion` in execute.ts).
+ *
+ * @example
+ * ```ts
+ * const gearV1Input = z.object({ name: z.string(), weightOz: z.number() });
+ * const gearV1Output = z.object({ id: z.string(), weightOz: z.number() });
+ *
+ * const gearCreate = trail('gear.create', {
+ *   // ... current v2 contract ...
+ *   version: 2,
+ *   versions: {
+ *     1: forkVersion({
+ *       blaze: (input) =>
+ *         // input is { name: string; weightOz: number } — no re-parse
+ *         Result.ok({ id: input.name, weightOz: input.weightOz }),
+ *       input: gearV1Input,
+ *       output: gearV1Output,
+ *     }),
+ *   },
+ * });
+ * ```
+ */
+export const forkVersion = <
+  TInputSchema extends z.ZodType,
+  TOutputSchema extends z.ZodType,
+  TComposeInputSchema extends z.ZodType | undefined = undefined,
+>(
+  spec: TrailVersionForkSpec<TInputSchema, TOutputSchema, TComposeInputSchema>
+): TrailVersionForkEntry =>
+  // Erasing the per-entry generics narrows function parameters, which TS
+  // cannot express without a conversion. Safe: the fork pipeline re-validates
+  // input against `spec.input` before the blaze runs.
+  spec as unknown as TrailVersionForkEntry;
+
 export const getTrailVersionEntryKind = (
   entry: TrailVersionEntry
 ): TrailVersionEntryKind => {

package/src/trails-db.ts

@@ -1,10 +1,19 @@
-import { Database } from 'bun:sqlite';
-import { createHash } from 'node:crypto';
-import { existsSync, mkdirSync } from 'node:fs';
-import { homedir } from 'node:os';
-import { basename, dirname, join, resolve } from 'node:path';
+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 —
+// topographer, 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';
@@ -46,7 +55,7 @@ interface SchemaVersionRow {
 }
 
 const deriveRootDir = (rootDir?: string): string =>
-  resolve(rootDir ?? process.cwd());
+  nodePath().resolve(rootDir ?? process.cwd());
 
 const sanitizeProjectKeyName = (name: string): string => {
   const normalized = name.replaceAll(/[^a-zA-Z0-9._-]+/g, '-');
@@ -54,33 +63,30 @@ const sanitizeProjectKeyName = (name: string): string => {
 };
 
 const projectHash = (rootDir: string): string =>
-  createHash('sha256')
-    .update(rootDir)
-    .digest('hex')
-    .slice(0, PROJECT_KEY_HASH_LENGTH);
+  sha256Hex(rootDir).slice(0, PROJECT_KEY_HASH_LENGTH);
 
 export const deriveTrailsProjectKey = (
   options?: TrailsDbLocationOptions
 ): string => {
   const rootDir = deriveRootDir(options?.rootDir);
-  return `${sanitizeProjectKeyName(basename(rootDir))}-${projectHash(rootDir)}`;
+  return `${sanitizeProjectKeyName(nodePath().basename(rootDir))}-${projectHash(rootDir)}`;
 };
 
 export const deriveTrailsStateHome = (
   options?: TrailsDbLocationOptions
 ): string => {
   const env = options?.env ?? process.env;
-  return resolve(
+  return nodePath().resolve(
     env['TRAILS_STATE_HOME'] ??
       env['XDG_STATE_HOME'] ??
-      join(homedir(), '.local', 'state')
+      nodePath().join(os().homedir(), '.local', 'state')
   );
 };
 
 export const deriveTrailsStateDir = (
   options?: TrailsDbLocationOptions
 ): string =>
-  join(
+  nodePath().join(
     deriveTrailsStateHome(options),
     TRAILS_STORE_DIR,
     TRAILS_PROJECTS_DIR,
@@ -88,15 +94,15 @@ export const deriveTrailsStateDir = (
   );
 
 export const deriveTrailsDir = (options?: TrailsDbLocationOptions): string =>
-  join(deriveRootDir(options?.rootDir), TRAILS_DIR);
+  nodePath().join(deriveRootDir(options?.rootDir), TRAILS_DIR);
 
 export const deriveTrailsDbPath = (options?: TrailsDbLocationOptions): string =>
   options?.path
-    ? resolve(options.path)
-    : join(deriveTrailsStateDir(options), TRAILS_DB_FILE);
+    ? nodePath().resolve(options.path)
+    : nodePath().join(deriveTrailsStateDir(options), TRAILS_DB_FILE);
 
 const ensureDbParentDir = (dbPath: string): void => {
-  mkdirSync(dirname(dbPath), { recursive: true });
+  fs().mkdirSync(nodePath().dirname(dbPath), { recursive: true });
 };
 
 /**
@@ -108,7 +114,7 @@ const ensureDbParentDir = (dbPath: string): void => {
  */
 export const ensureTrailsWorkspace = (rootDir: string): void => {
   const trailsDir = deriveTrailsDir({ rootDir });
-  mkdirSync(trailsDir, { recursive: true });
+  fs().mkdirSync(trailsDir, { recursive: true });
 };
 
 const initializeWritePragmas = (db: Database): void => {
@@ -168,7 +174,7 @@ export const openWriteTrailsDb = (
 
   ensureDbParentDir(dbPath);
 
-  const db = new Database(dbPath, { create: true });
+  const db = new (sqlite().Database)(dbPath, { create: true });
   initializeWritePragmas(db);
   ensureSchemaVersionTable(db);
   return db;
@@ -178,12 +184,12 @@ export const openReadTrailsDb = (
   options?: TrailsDbLocationOptions
 ): Database => {
   const dbPath = deriveTrailsDbPath(options);
-  if (!existsSync(dbPath)) {
+  if (!fs().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 });
+  const db = new (sqlite().Database)(dbPath, { readonly: true });
   initializeReadPragmas(db);
   return db;
 };

package/src/validate-established-topo.ts

@@ -2,7 +2,7 @@ import { ValidationError } from './errors.js';
 import { Result } from './result.js';
 import type { Topo } from './topo.js';
 import { validateDraftFreeTopo } from './draft.js';
-import type { TopoIssue } from './validate-topo.js';
+import type { TopoDiagnostic } from './validate-topo.js';
 import { validateTopo } from './validate-topo.js';
 
 const PROJECTION_BLOCKING_RULES = new Set([
@@ -27,7 +27,7 @@ const keepProjectionBlockingIssues = (
   }
 
   const issues = (
-    result.error.context as { issues?: readonly TopoIssue[] } | undefined
+    result.error.context as { issues?: readonly TopoDiagnostic[] } | undefined
   )?.issues;
   const remainingIssues = issues?.filter((issue) =>
     PROJECTION_BLOCKING_RULES.has(issue.rule)

package/src/validate-topo.ts

@@ -34,18 +34,80 @@ import { validateWebhookSource } from './webhook.js';
 // Issue shape
 // ---------------------------------------------------------------------------
 
-export interface TopoIssue {
+export type TopoDiagnosticCode = 'topo.missing-reference';
+
+export type TopoReferenceKind =
+  | 'compose'
+  | 'contour-reference'
+  | 'resource'
+  | 'signal-fire'
+  | 'signal-on'
+  | 'signal-origin';
+
+export type TopoReferenceOwnerKind =
+  | 'contour'
+  | 'signal'
+  | 'trail'
+  | 'trail-version';
+
+/**
+ * Stable machine-readable payload for dangling topo references.
+ *
+ * Consumers such as Regrade should branch on `code` and `reference` instead
+ * of parsing `message`, which remains a human-readable diagnostic.
+ */
+export interface TopoMissingReference {
+  readonly fromId: string;
+  readonly fromKind: TopoReferenceOwnerKind;
+  readonly fromTrailId?: string;
+  readonly missingId: string;
+  readonly referenceKind: TopoReferenceKind;
+  readonly version?: number;
+}
+
+export interface TopoDiagnostic {
+  /**
+   * Stable machine-readable code. Human-facing messages may change for
+   * clarity; downstream automation should depend on this code and the typed
+   * payload fields.
+   */
+  readonly code?: TopoDiagnosticCode;
   readonly trailId: string;
   readonly rule: string;
   readonly message: string;
   readonly inputPath?: readonly (string | number)[];
+  readonly reference?: TopoMissingReference;
   readonly schemaIssues?: readonly TopoSchemaIssue[];
   readonly sourceId?: string;
   readonly sourceKind?: string;
 }
 
+/**
+ * @deprecated Use {@link TopoDiagnostic}. Kept as a source-compatible alias
+ * during the v1 vocabulary cutover.
+ */
+export interface TopoIssue extends TopoDiagnostic {
+  readonly trailId: TopoDiagnostic['trailId'];
+}
+
 export type TopoSchemaIssue = ActivationSchemaIssue;
 
+const isTopoDiagnostic = (value: unknown): value is TopoDiagnostic =>
+  typeof value === 'object' &&
+  value !== null &&
+  typeof (value as { message?: unknown }).message === 'string' &&
+  typeof (value as { rule?: unknown }).rule === 'string' &&
+  typeof (value as { trailId?: unknown }).trailId === 'string';
+
+const missingReferenceDiagnostic = (
+  issue: Omit<TopoDiagnostic, 'code' | 'reference'> & {
+    readonly reference: TopoMissingReference;
+  }
+): TopoDiagnostic => ({
+  ...issue,
+  code: 'topo.missing-reference',
+});
+
 // ---------------------------------------------------------------------------
 // Validators
 // ---------------------------------------------------------------------------
@@ -92,8 +154,8 @@ const buildComposeGraph = (
 /** Detect multi-node cycles in the trail composing graph via DFS. */
 const detectComposeCycles = (
   trails: ReadonlyMap<string, AnyTrail>
-): TopoIssue[] => {
-  const issues: TopoIssue[] = [];
+): TopoDiagnostic[] => {
+  const issues: TopoDiagnostic[] = [];
   const { color, graph } = buildComposeGraph(trails);
 
   const dfs = (node: string, path: string[]): void => {
@@ -128,8 +190,8 @@ const detectComposeCycles = (
 const checkComposes = (
   trails: ReadonlyMap<string, AnyTrail>,
   topo: Topo
-): TopoIssue[] => {
-  const issues: TopoIssue[] = [];
+): TopoDiagnostic[] => {
+  const issues: TopoDiagnostic[] = [];
   for (const [id, trail] of trails) {
     for (const composedId of trail.composes) {
       if (composedId === id) {
@@ -139,11 +201,20 @@ const checkComposes = (
           trailId: id,
         });
       } else if (!topo.has(composedId) && !isDraftId(composedId)) {
-        issues.push({
-          message: `Composes "${composedId}" which is not in the topo`,
-          rule: 'compose-exists',
-          trailId: id,
-        });
+        issues.push(
+          missingReferenceDiagnostic({
+            message: `Composes "${composedId}" which is not in the topo`,
+            reference: {
+              fromId: id,
+              fromKind: 'trail',
+              fromTrailId: id,
+              missingId: composedId,
+              referenceKind: 'compose',
+            },
+            rule: 'compose-exists',
+            trailId: id,
+          })
+        );
       }
     }
     for (const [rawVersion, entry] of Object.entries(trail.versions ?? {})) {
@@ -166,11 +237,21 @@ const checkComposes = (
             trailId: id,
           });
         } else if (!topo.has(composedId) && !isDraftId(composedId)) {
-          issues.push({
-            message: `Version ${version} composes "${composedId}" which is not in the topo`,
-            rule: 'compose-exists',
-            trailId: id,
-          });
+          issues.push(
+            missingReferenceDiagnostic({
+              message: `Version ${version} composes "${composedId}" which is not in the topo`,
+              reference: {
+                fromId: id,
+                fromKind: 'trail-version',
+                fromTrailId: id,
+                missingId: composedId,
+                referenceKind: 'compose',
+                version,
+              },
+              rule: 'compose-exists',
+              trailId: id,
+            })
+          );
         }
       }
     }
@@ -182,8 +263,8 @@ const checkComposes = (
 const checkResources = (
   trails: ReadonlyMap<string, AnyTrail>,
   topo: Topo
-): TopoIssue[] => {
-  const issues: TopoIssue[] = [];
+): TopoDiagnostic[] => {
+  const issues: TopoDiagnostic[] = [];
 
   for (const [id, trail] of trails) {
     for (const declaredResource of trail.resources) {
@@ -191,11 +272,20 @@ const checkResources = (
         !topo.hasResource(declaredResource.id) &&
         !isDraftId(declaredResource.id)
       ) {
-        issues.push({
-          message: `Resource "${declaredResource.id}" is not in the topo`,
-          rule: 'resource-exists',
-          trailId: id,
-        });
+        issues.push(
+          missingReferenceDiagnostic({
+            message: `Resource "${declaredResource.id}" is not in the topo`,
+            reference: {
+              fromId: id,
+              fromKind: 'trail',
+              fromTrailId: id,
+              missingId: declaredResource.id,
+              referenceKind: 'resource',
+            },
+            rule: 'resource-exists',
+            trailId: id,
+          })
+        );
       }
     }
     for (const [rawVersion, entry] of Object.entries(trail.versions ?? {})) {
@@ -213,11 +303,21 @@ const checkResources = (
           !topo.hasResource(declaredResource.id) &&
           !isDraftId(declaredResource.id)
         ) {
-          issues.push({
-            message: `Version ${version} resource "${declaredResource.id}" is not in the topo`,
-            rule: 'resource-exists',
-            trailId: id,
-          });
+          issues.push(
+            missingReferenceDiagnostic({
+              message: `Version ${version} resource "${declaredResource.id}" is not in the topo`,
+              reference: {
+                fromId: id,
+                fromKind: 'trail-version',
+                fromTrailId: id,
+                missingId: declaredResource.id,
+                referenceKind: 'resource',
+                version,
+              },
+              rule: 'resource-exists',
+              trailId: id,
+            })
+          );
         }
       }
     }
@@ -237,8 +337,8 @@ const checkOneExample = (
   inputSchema: { safeParse: (data: unknown) => { success: boolean } },
   hasOutput: boolean,
   label = `Example "${example.name}"`
-): TopoIssue[] => {
-  const issues: TopoIssue[] = [];
+): TopoDiagnostic[] => {
+  const issues: TopoDiagnostic[] = [];
   const result = validateInput(inputSchema as AnyTrail['input'], example.input);
   if (result.isErr() && example.error !== 'ValidationError') {
     issues.push({
@@ -257,7 +357,7 @@ const checkOneExample = (
   return issues;
 };
 
-const checkVersionExamples = (id: string, trail: AnyTrail): TopoIssue[] =>
+const checkVersionExamples = (id: string, trail: AnyTrail): TopoDiagnostic[] =>
   Object.entries(trail.versions ?? {}).flatMap(([version, entry]) => {
     if (isArchivedTrailVersionEntry(entry)) {
       return [];
@@ -274,8 +374,10 @@ const checkVersionExamples = (id: string, trail: AnyTrail): TopoIssue[] =>
     );
   });
 
-const checkExamples = (trails: ReadonlyMap<string, AnyTrail>): TopoIssue[] => {
-  const issues: TopoIssue[] = [];
+const checkExamples = (
+  trails: ReadonlyMap<string, AnyTrail>
+): TopoDiagnostic[] => {
+  const issues: TopoDiagnostic[] = [];
   for (const [id, trail] of trails) {
     if (trail.examples) {
       for (const example of trail.examples) {
@@ -292,19 +394,27 @@ const checkExamples = (trails: ReadonlyMap<string, AnyTrail>): TopoIssue[] => {
 const checkSignalOrigins = (
   signals: ReadonlyMap<string, AnySignal>,
   topo: Topo
-): TopoIssue[] => {
-  const issues: TopoIssue[] = [];
+): TopoDiagnostic[] => {
+  const issues: TopoDiagnostic[] = [];
   for (const [id, evt] of signals) {
     if (!evt.from) {
       continue;
     }
     for (const originId of evt.from) {
       if (!topo.has(originId) && !isDraftId(originId)) {
-        issues.push({
-          message: `Signal origin "${originId}" is not in the topo`,
-          rule: 'signal-origin-exists',
-          trailId: id,
-        });
+        issues.push(
+          missingReferenceDiagnostic({
+            message: `Signal origin "${originId}" is not in the topo`,
+            reference: {
+              fromId: id,
+              fromKind: 'signal',
+              missingId: originId,
+              referenceKind: 'signal-origin',
+            },
+            rule: 'signal-origin-exists',
+            trailId: id,
+          })
+        );
       }
     }
   }
@@ -314,27 +424,45 @@ const checkSignalOrigins = (
 const checkSignalReferences = (
   trails: ReadonlyMap<string, AnyTrail>,
   signals: ReadonlyMap<string, AnySignal>
-): TopoIssue[] => {
-  const issues: TopoIssue[] = [];
+): TopoDiagnostic[] => {
+  const issues: TopoDiagnostic[] = [];
 
   for (const [id, trail] of trails) {
     for (const signalId of trail.fires ?? []) {
       if (!signals.has(signalId) && !isDraftId(signalId)) {
-        issues.push({
-          message: `Trail fires signal "${signalId}" which is not in the topo`,
-          rule: 'signal-fire-exists',
-          trailId: id,
-        });
+        issues.push(
+          missingReferenceDiagnostic({
+            message: `Trail fires signal "${signalId}" which is not in the topo`,
+            reference: {
+              fromId: id,
+              fromKind: 'trail',
+              fromTrailId: id,
+              missingId: signalId,
+              referenceKind: 'signal-fire',
+            },
+            rule: 'signal-fire-exists',
+            trailId: id,
+          })
+        );
       }
     }
 
     for (const signalId of trail.on ?? []) {
       if (!signals.has(signalId) && !isDraftId(signalId)) {
-        issues.push({
-          message: `Trail declares on signal "${signalId}" which is not in the topo`,
-          rule: 'signal-on-exists',
-          trailId: id,
-        });
+        issues.push(
+          missingReferenceDiagnostic({
+            message: `Trail declares on signal "${signalId}" which is not in the topo`,
+            reference: {
+              fromId: id,
+              fromKind: 'trail',
+              fromTrailId: id,
+              missingId: signalId,
+              referenceKind: 'signal-on',
+            },
+            rule: 'signal-on-exists',
+            trailId: id,
+          })
+        );
       }
     }
   }
@@ -344,8 +472,8 @@ const checkSignalReferences = (
 
 const checkActivationSources = (
   trails: ReadonlyMap<string, AnyTrail>
-): TopoIssue[] => {
-  const issues: TopoIssue[] = [];
+): TopoDiagnostic[] => {
+  const issues: TopoDiagnostic[] = [];
   const sourceDeclarations = new Map<
     string,
     {
@@ -440,7 +568,7 @@ const createSourceCompatibilityIssue = (
   trailId: string,
   activation: ActivationEntry,
   schemaIssues: readonly TopoSchemaIssue[]
-): TopoIssue => {
+): TopoDiagnostic => {
   const [firstIssue] = schemaIssues;
   const inputPath = firstIssue?.path ?? Object.freeze([]);
   return {
@@ -458,7 +586,7 @@ const checkSourcePayloadCompatibility = (
   trail: AnyTrail,
   activation: ActivationEntry,
   signals: ReadonlyMap<string, AnySignal>
-): TopoIssue | undefined => {
+): TopoDiagnostic | undefined => {
   if (
     !isKnownActivationSourceKind(activation.source.kind) ||
     isDraftId(activation.source.id)
@@ -483,8 +611,8 @@ const checkSourcePayloadCompatibility = (
 const checkActivationSourceInputCompatibility = (
   trails: ReadonlyMap<string, AnyTrail>,
   signals: ReadonlyMap<string, AnySignal>
-): TopoIssue[] => {
-  const issues: TopoIssue[] = [];
+): TopoDiagnostic[] => {
+  const issues: TopoDiagnostic[] = [];
 
   for (const trail of trails.values()) {
     for (const activation of trail.activationSources ?? []) {
@@ -501,17 +629,25 @@ const checkActivationSourceInputCompatibility = (
 const checkContourReferences = (
   contours: ReadonlyMap<string, AnyContour>,
   topo: Topo
-): TopoIssue[] => {
-  const issues: TopoIssue[] = [];
+): TopoDiagnostic[] => {
+  const issues: TopoDiagnostic[] = [];
 
   for (const [name, contourDef] of contours) {
     for (const ref of getContourReferences(contourDef)) {
       if (!topo.hasContour(ref.contour) && !isDraftId(ref.contour)) {
-        issues.push({
-          message: `Contour "${name}" references "${ref.contour}" which is not in the topo`,
-          rule: 'contour-reference-exists',
-          trailId: name,
-        });
+        issues.push(
+          missingReferenceDiagnostic({
+            message: `Contour "${name}" references "${ref.contour}" which is not in the topo`,
+            reference: {
+              fromId: name,
+              fromKind: 'contour',
+              missingId: ref.contour,
+              referenceKind: 'contour-reference',
+            },
+            rule: 'contour-reference-exists',
+            trailId: name,
+          })
+        );
       }
     }
   }
@@ -523,6 +659,21 @@ const checkContourReferences = (
 // Public API
 // ---------------------------------------------------------------------------
 
+/**
+ * Extract structured topo diagnostics from a validation error.
+ *
+ * `validateTopo` keeps source compatibility by returning `Result<void,
+ * ValidationError>`. Consumers that need machine-readable diagnostics should
+ * use this helper instead of parsing the human `message` text.
+ */
+export const getTopoDiagnostics = (
+  error: ValidationError
+): readonly TopoDiagnostic[] => {
+  const context = error.context as { issues?: unknown } | undefined;
+  const issues = context?.issues;
+  return Array.isArray(issues) ? issues.filter(isTopoDiagnostic) : [];
+};
+
 /**
  * Validate the structural integrity of a Topo graph.
  *