@ontrails/topography 0.2.0

package/src/io.ts

@@ -0,0 +1,280 @@
+/**
+ * File I/O for topo graphs and lock files.
+ */
+
+import { mkdir } from 'node:fs/promises';
+import { join } from 'node:path';
+
+import type {
+  LockManifest,
+  ReadOptions,
+  TopoGraph,
+  TrailsLock,
+  WorkspaceTopoMetadata,
+  WorkspaceTrailIndex,
+  WriteOptions,
+} from './types.js';
+import {
+  LOCK_MANIFEST_SCHEMA_VERSION,
+  lockManifestSchema,
+  trailsLockSchema,
+  topoGraphSchema,
+} from './types.js';
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+const DEFAULT_DIR = '.trails';
+const LOCK_MANIFEST_FILE = 'trails.lock';
+const TOPO_GRAPH_FILE = 'topo.lock';
+const REGENERATE_LOCK_MESSAGE =
+  'Unsupported trails.lock format; regenerate with `trails compile`.';
+const REGENERATE_TOPO_GRAPH_MESSAGE =
+  'Unsupported topo.lock format; regenerate with `trails compile`.';
+
+export const isTopoArtifactRegenerationError = (
+  error: unknown
+): error is Error =>
+  error instanceof Error &&
+  (error.message.includes(REGENERATE_LOCK_MESSAGE) ||
+    error.message.includes(REGENERATE_TOPO_GRAPH_MESSAGE));
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+const isNotFound = (err: unknown): boolean =>
+  typeof err === 'object' &&
+  err !== null &&
+  (err as NodeJS.ErrnoException).code === 'ENOENT';
+
+const resolveDir = (options?: ReadOptions | WriteOptions): string =>
+  options?.dir ?? DEFAULT_DIR;
+
+const ensureDir = async (dir: string): Promise<void> => {
+  await mkdir(dir, { recursive: true });
+};
+
+const readTextIfExists = async (filePath: string): Promise<string | null> => {
+  try {
+    return await Bun.file(filePath).text();
+  } catch (error: unknown) {
+    if (!isNotFound(error)) {
+      throw error;
+    }
+    return null;
+  }
+};
+
+const parseJson = (
+  content: string,
+  fileName: string,
+  regenerateMessage: string
+): unknown => {
+  try {
+    return JSON.parse(content) as unknown;
+  } catch {
+    throw new Error(`Invalid JSON in ${fileName}. ${regenerateMessage}`);
+  }
+};
+
+const parseLockManifest = (content: string): LockManifest => {
+  const parsed = parseJson(
+    content,
+    LOCK_MANIFEST_FILE,
+    REGENERATE_LOCK_MESSAGE
+  );
+  const result = lockManifestSchema.safeParse(parsed);
+  if (result.success) {
+    return result.data;
+  }
+  throw new Error(REGENERATE_LOCK_MESSAGE);
+};
+
+const parseTrailsLock = (content: string): TrailsLock => {
+  const parsed = parseJson(
+    content,
+    LOCK_MANIFEST_FILE,
+    REGENERATE_LOCK_MESSAGE
+  );
+  const result = trailsLockSchema.safeParse(parsed);
+  if (result.success) {
+    return result.data as TrailsLock;
+  }
+  throw new Error(REGENERATE_LOCK_MESSAGE);
+};
+
+const parseTopoGraph = (content: string): TopoGraph => {
+  const parsed = parseJson(
+    content,
+    TOPO_GRAPH_FILE,
+    REGENERATE_TOPO_GRAPH_MESSAGE
+  );
+  const result = topoGraphSchema.safeParse(parsed);
+  if (result.success) {
+    return result.data as TopoGraph;
+  }
+  throw new Error(REGENERATE_TOPO_GRAPH_MESSAGE);
+};
+
+const lockManifestFromTrailsLock = (lock: TrailsLock): LockManifest => ({
+  artifacts: [
+    {
+      path: TOPO_GRAPH_FILE,
+      role: 'topo',
+      sha256: lock.topoGraphHash,
+    },
+  ],
+  scope: lock.scope,
+  summary: lock.summary,
+  version: LOCK_MANIFEST_SCHEMA_VERSION,
+});
+
+// ---------------------------------------------------------------------------
+// TopoGraph
+// ---------------------------------------------------------------------------
+
+/**
+ * Write a topo graph to `<dir>/topo.lock`.
+ *
+ * Creates the directory if it doesn't exist. Returns the file path.
+ */
+export const writeTopoGraph = async (
+  topoGraph: TopoGraph,
+  options?: WriteOptions
+): Promise<string> => {
+  const dir = resolveDir(options);
+  await ensureDir(dir);
+  const filePath = join(dir, TOPO_GRAPH_FILE);
+  const json = `${JSON.stringify(topoGraph, null, 2)}\n`;
+  await Bun.write(filePath, json);
+  return filePath;
+};
+
+/**
+ * Read a topo graph from `<dir>/trails.lock` or legacy `<dir>/topo.lock`.
+ */
+export const readTopoGraph = async (
+  options?: ReadOptions
+): Promise<TopoGraph | null> => {
+  const dir = resolveDir(options);
+  const lockContent = await readTextIfExists(join(dir, LOCK_MANIFEST_FILE));
+  if (lockContent !== null) {
+    try {
+      return parseTrailsLock(lockContent).topoGraph as TopoGraph;
+    } catch (error) {
+      try {
+        parseLockManifest(lockContent);
+      } catch {
+        throw error;
+      }
+      const legacyTopoContent = await readTextIfExists(
+        join(dir, TOPO_GRAPH_FILE)
+      );
+      if (legacyTopoContent === null) {
+        throw error;
+      }
+      return parseTopoGraph(legacyTopoContent);
+    }
+  }
+
+  const content = await readTextIfExists(join(dir, TOPO_GRAPH_FILE));
+  return content === null ? null : parseTopoGraph(content);
+};
+
+// ---------------------------------------------------------------------------
+// Lock Manifest
+// ---------------------------------------------------------------------------
+
+/**
+ * Write a lock v4 manifest to `<dir>/trails.lock`.
+ *
+ * Creates the directory if it doesn't exist. Returns the file path.
+ */
+export const writeLockManifest = async (
+  lockManifest: LockManifest,
+  options?: WriteOptions
+): Promise<string> => {
+  const dir = resolveDir(options);
+  await ensureDir(dir);
+  const filePath = join(dir, LOCK_MANIFEST_FILE);
+  const parsed = lockManifestSchema.parse(lockManifest);
+  await Bun.write(filePath, `${JSON.stringify(parsed, null, 2)}\n`);
+  return filePath;
+};
+
+/**
+ * Write a v4 Trails lock envelope to `<dir>/trails.lock`.
+ */
+export const writeTrailsLock = async (
+  trailsLock: TrailsLock,
+  options?: WriteOptions
+): Promise<string> => {
+  const dir = resolveDir(options);
+  await ensureDir(dir);
+  const filePath = join(dir, LOCK_MANIFEST_FILE);
+  const parsed = trailsLockSchema.parse(trailsLock);
+  await Bun.write(filePath, `${JSON.stringify(parsed, null, 2)}\n`);
+  return filePath;
+};
+
+/**
+ * Read a lock v4 manifest from `<dir>/trails.lock`.
+ *
+ * v5 root locks are derived back to the v4 manifest shape for compatibility.
+ */
+export const readLockManifest = async (
+  options?: ReadOptions
+): Promise<LockManifest | null> => {
+  const dir = resolveDir(options);
+  const content = await readTextIfExists(join(dir, LOCK_MANIFEST_FILE));
+  if (content === null) {
+    return null;
+  }
+
+  try {
+    return lockManifestFromTrailsLock(parseTrailsLock(content));
+  } catch {
+    return parseLockManifest(content);
+  }
+};
+
+/**
+ * Read a v4 Trails lock envelope from `<dir>/trails.lock`.
+ */
+export const readTrailsLock = async (
+  options?: ReadOptions
+): Promise<TrailsLock | null> => {
+  const dir = resolveDir(options);
+  const content = await readTextIfExists(join(dir, LOCK_MANIFEST_FILE));
+  return content === null ? null : parseTrailsLock(content);
+};
+
+/**
+ * Read workspace metadata from the current topo graph artifact.
+ */
+export const readWorkspaceTopoMetadata = async (
+  options?: ReadOptions
+): Promise<WorkspaceTopoMetadata | null> => {
+  const topoGraph = await readTopoGraph(options);
+  if (topoGraph === null) {
+    return null;
+  }
+  return topoGraph.workspace ?? null;
+};
+
+/**
+ * Read the workspace trail-id index from the current topo graph artifact.
+ */
+export const readWorkspaceTrailIndex = async (
+  options?: ReadOptions
+): Promise<WorkspaceTrailIndex | null> => {
+  const workspace = await readWorkspaceTopoMetadata(options);
+  return workspace?.trails ?? null;
+};
+
+/** @deprecated Use {@link readWorkspaceTrailIndex}. */
+export const readWorkspaceLock = async (
+  options?: ReadOptions
+): Promise<WorkspaceTrailIndex | null> => readWorkspaceTrailIndex(options);

package/src/library-derivation.ts

@@ -0,0 +1,131 @@
+import {
+  filterSurfaceTrails,
+  isDraftId,
+  zodToJsonSchema,
+} from '@ontrails/core';
+import type { Topo, Trail } from '@ontrails/core';
+
+import type {
+  JsonSchema,
+  TopoGraphLibraryCollision,
+  TopoGraphLibraryExclusion,
+  TopoGraphLibraryExport,
+  TopoGraphLibraryDerived,
+} from './types.js';
+
+const sortKeys = <T extends Record<string, unknown>>(obj: T): T => {
+  const sorted: Record<string, unknown> = {};
+  for (const key of Object.keys(obj).toSorted()) {
+    sorted[key] = obj[key];
+  }
+  return sorted as T;
+};
+
+const deepSortKeys = (value: unknown): unknown => {
+  if (Array.isArray(value)) {
+    return value.map(deepSortKeys);
+  }
+  if (value !== null && typeof value === 'object') {
+    const sorted: Record<string, unknown> = {};
+    for (const key of Object.keys(value).toSorted()) {
+      sorted[key] = deepSortKeys((value as Record<string, unknown>)[key]);
+    }
+    return sorted;
+  }
+  return value;
+};
+
+const toSortedJsonSchema = (schema: unknown): JsonSchema => {
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  const raw = zodToJsonSchema(schema as any);
+  return deepSortKeys(raw) as JsonSchema;
+};
+
+const deriveLibraryExportName = (trailId: string): string => {
+  const words = trailId.split(/[.-]/u).filter((word) => word.length > 0);
+  return words
+    .map((word, index) =>
+      index === 0 ? word : word.charAt(0).toUpperCase() + word.slice(1)
+    )
+    .join('');
+};
+
+const isInternalTrail = (trail: Trail<unknown, unknown, unknown>): boolean =>
+  trail.visibility === 'internal' || trail.meta?.['internal'] === true;
+
+const collectLibraryExclusions = (
+  topo: Topo,
+  selectedIds: ReadonlySet<string>
+): readonly TopoGraphLibraryExclusion[] => {
+  const excluded: TopoGraphLibraryExclusion[] = [];
+
+  for (const trail of topo.trails.values()) {
+    if (selectedIds.has(trail.id)) {
+      continue;
+    }
+    if (isDraftId(trail.id)) {
+      excluded.push({ reason: 'draft', trailId: trail.id });
+    } else if (trail.activationSources.length > 0) {
+      excluded.push({ reason: 'activation', trailId: trail.id });
+    } else if (isInternalTrail(trail as Trail<unknown, unknown, unknown>)) {
+      excluded.push({ reason: 'internal', trailId: trail.id });
+    }
+  }
+
+  return excluded.toSorted((a, b) => a.trailId.localeCompare(b.trailId));
+};
+
+export const deriveTopoGraphLibrary = (topo: Topo): TopoGraphLibraryDerived => {
+  const selected = filterSurfaceTrails([...topo.trails.values()]).filter(
+    (trail) => !isDraftId(trail.id)
+  );
+  const selectedIds = new Set(selected.map((trail) => trail.id));
+  const namesToTrailIds = new Map<string, string[]>();
+  const collisionNames = new Set<string>();
+  const exports: TopoGraphLibraryExport[] = [];
+
+  for (const trail of selected.toSorted((a, b) => a.id.localeCompare(b.id))) {
+    const exportName = deriveLibraryExportName(trail.id);
+    const existing = namesToTrailIds.get(exportName);
+    if (existing !== undefined) {
+      existing.push(trail.id);
+      collisionNames.add(exportName);
+      continue;
+    }
+
+    namesToTrailIds.set(exportName, [trail.id]);
+    exports.push(
+      sortKeys({
+        ...(trail.description === undefined
+          ? {}
+          : { description: trail.description }),
+        exportName,
+        ...(trail.input === undefined
+          ? {}
+          : { input: toSortedJsonSchema(trail.input) }),
+        intent: trail.intent,
+        nameSource: 'derived' as const,
+        ...(trail.output === undefined
+          ? {}
+          : { output: toSortedJsonSchema(trail.output) }),
+        resources: trail.resources.map((resource) => resource.id).toSorted(),
+        trailId: trail.id,
+        ...(trail.version === undefined ? {} : { version: trail.version }),
+      })
+    );
+  }
+
+  const collisions: TopoGraphLibraryCollision[] = [...collisionNames]
+    .map((name) => ({
+      exportName: name,
+      trailIds: namesToTrailIds.get(name) ?? [],
+    }))
+    .toSorted((a, b) => a.exportName.localeCompare(b.exportName));
+
+  return sortKeys({
+    app: topo.name,
+    collisions,
+    excluded: collectLibraryExclusions(topo, selectedIds),
+    exports,
+  }) as unknown as TopoGraphLibraryDerived;
+};

package/src/overlays.ts

@@ -0,0 +1,155 @@
+/**
+ * Namespaced overlay collection for topo graphs.
+ *
+ * Both derivation pipelines — `deriveTopoGraph` and the store-side
+ * `buildTopoGraph` — consume overlay registrations through this single
+ * collection path so compiled locks and fresh derivations cannot diverge.
+ */
+
+import { SURFACES_OVERLAY_NAMESPACE, ValidationError } from '@ontrails/core';
+import type { Topo } from '@ontrails/core';
+
+import type {
+  TopoGraphOverlayRegistration,
+  TopoGraphOverlays,
+} from './types.js';
+
+const OVERLAY_NAMESPACE_PATTERN = /^[a-z][a-z0-9-]*(\.[a-z0-9-]+)*$/u;
+
+const DERIVE_REMEDIATION =
+  "Fix the contribution's derive output and rerun `trails compile`.";
+
+/** Sort object keys recursively for deterministic overlay serialization. */
+const deepSortKeys = (value: unknown): unknown => {
+  if (Array.isArray(value)) {
+    return value.map(deepSortKeys);
+  }
+  if (value !== null && typeof value === 'object') {
+    const sorted: Record<string, unknown> = {};
+    for (const key of Object.keys(value).toSorted()) {
+      sorted[key] = deepSortKeys((value as Record<string, unknown>)[key]);
+    }
+    return sorted;
+  }
+  return value;
+};
+
+const summarizeIssuePath = (path: readonly PropertyKey[]): string =>
+  path.length === 0 ? '(root)' : path.map(String).join('.');
+
+/**
+ * Canonicalize schema-parsed facts into JSON-plain, deterministically ordered
+ * data: a JSON round-trip strips non-JSON residue, then a deep key-sort makes
+ * serialization order stable.
+ */
+const canonicalizeOverlayFacts = (
+  namespace: string,
+  parsed: unknown
+): unknown => {
+  let serialized: string | undefined;
+  try {
+    serialized = JSON.stringify(parsed);
+  } catch {
+    serialized = undefined;
+  }
+  if (serialized === undefined) {
+    throw new ValidationError(
+      `Overlay namespace "${namespace}" derived facts are not JSON-serializable. ${DERIVE_REMEDIATION}`
+    );
+  }
+  return deepSortKeys(JSON.parse(serialized));
+};
+
+const assertValidNamespace = (namespace: string): void => {
+  if (!OVERLAY_NAMESPACE_PATTERN.test(namespace)) {
+    throw new ValidationError(
+      `Overlay namespace "${namespace}" must be dotted kebab-case (matching ${OVERLAY_NAMESPACE_PATTERN.source}). Fix the contribution's namespace and rerun \`trails compile\`.`
+    );
+  }
+};
+
+/**
+ * Enforce the reserved `surfaces` namespace: surfaces obey app-authored
+ * overlays only, so an adapter-derived registration (absent provenance is
+ * adapter-derived) can never own it.
+ */
+const assertSurfacesProvenance = (
+  registration: TopoGraphOverlayRegistration
+): void => {
+  if (
+    registration.namespace === SURFACES_OVERLAY_NAMESPACE &&
+    registration.provenance !== 'app-authored'
+  ) {
+    throw new ValidationError(
+      `Adapter-derived overlays cannot own the "${SURFACES_OVERLAY_NAMESPACE}" namespace. Author bindings with \`surfaceOverlay()\` in the app module and rerun \`trails compile\`.`
+    );
+  }
+};
+
+const deriveOverlayFacts = (
+  topo: Topo,
+  registration: TopoGraphOverlayRegistration
+): unknown => {
+  const derived = registration.derive(topo);
+  const parsed = registration.schema.safeParse(derived);
+  if (!parsed.success) {
+    const issues = parsed.error.issues
+      .map((issue) => `${summarizeIssuePath(issue.path)}: ${issue.message}`)
+      .join('; ');
+    throw new ValidationError(
+      `Overlay namespace "${registration.namespace}" derived facts failed schema validation (${issues}). ${DERIVE_REMEDIATION}`
+    );
+  }
+  return canonicalizeOverlayFacts(registration.namespace, parsed.data);
+};
+
+/**
+ * Collect namespaced fact overlays from overlay registrations.
+ *
+ * Each registration owns one dotted-kebab namespace; its derived facts are
+ * validated against the registration's schema, canonicalized into JSON-plain
+ * deep-key-sorted data, and assembled with namespaces sorted
+ * lexicographically. Returns `undefined` when no registrations are supplied
+ * so graphs without overlays stay byte-identical to pre-overlays locks.
+ *
+ * @example
+ * ```ts
+ * const overlays = collectTopoGraphOverlays(app, [
+ *   {
+ *     derive: (topo) => ({ trailCount: topo.trails.size }),
+ *     namespace: 'cloudflare',
+ *     schema: z.object({ trailCount: z.number() }),
+ *   },
+ * ]);
+ * // => { cloudflare: { trailCount: 3 } }
+ * ```
+ */
+export const collectTopoGraphOverlays = (
+  topo: Topo,
+  registrations: readonly TopoGraphOverlayRegistration[] | undefined
+): TopoGraphOverlays | undefined => {
+  if (registrations === undefined || registrations.length === 0) {
+    return undefined;
+  }
+
+  const collected = new Map<string, unknown>();
+  for (const registration of registrations) {
+    assertValidNamespace(registration.namespace);
+    assertSurfacesProvenance(registration);
+    if (collected.has(registration.namespace)) {
+      throw new ValidationError(
+        `Duplicate overlay namespace "${registration.namespace}". Each contribution owns one namespace; remove the duplicate registration and rerun \`trails compile\`.`
+      );
+    }
+    collected.set(
+      registration.namespace,
+      deriveOverlayFacts(topo, registration)
+    );
+  }
+
+  const overlays: Record<string, unknown> = {};
+  for (const namespace of [...collected.keys()].toSorted()) {
+    overlays[namespace] = collected.get(namespace);
+  }
+  return overlays;
+};

package/src/permit.ts

@@ -0,0 +1,19 @@
+import type { AnyTrail, PermitRequirement } from '@ontrails/core';
+
+export type DerivedPermitRequirement =
+  | 'public'
+  | { readonly scopes: readonly string[] };
+
+export const derivePermitRequirement = (
+  permit: PermitRequirement
+): DerivedPermitRequirement =>
+  permit === 'public' ? 'public' : { scopes: [...permit.scopes].toSorted() };
+
+export const addPermitRequirement = (
+  entry: Record<string, unknown>,
+  trail: AnyTrail
+): void => {
+  if (trail.permit !== undefined) {
+    entry['permit'] = derivePermitRequirement(trail.permit);
+  }
+};

package/src/source-fingerprint.ts

@@ -0,0 +1,103 @@
+/**
+ * Content fingerprint over an app's source file set.
+ *
+ * The per-user topo store records this fingerprint on every snapshot so
+ * consumers that serve stored exports can detect that the app sources
+ * changed since the snapshot was taken and self-invalidate instead of
+ * silently serving pre-edit facts (TRL-1196).
+ */
+
+import { readdirSync, readFileSync, statSync } from 'node:fs';
+import { join, relative } from 'node:path';
+
+/** Directories that never contribute to the app source set. */
+const EXCLUDED_DIRECTORIES = new Set([
+  '.git',
+  '.trails',
+  '.trails-tmp',
+  '.turbo',
+  'dist',
+  'node_modules',
+]);
+
+/** Files that are derived outputs rather than sources. */
+const EXCLUDED_FILES = new Set(['trails.lock', 'topo.lock', 'bun.lock']);
+
+const SOURCE_EXTENSIONS = new Set([
+  '.cjs',
+  '.cts',
+  '.js',
+  '.json',
+  '.jsx',
+  '.mjs',
+  '.mts',
+  '.ts',
+  '.tsx',
+]);
+
+const hasSourceExtension = (fileName: string): boolean => {
+  const dot = fileName.lastIndexOf('.');
+  return dot !== -1 && SOURCE_EXTENSIONS.has(fileName.slice(dot));
+};
+
+const collectSourceFiles = (dir: string, out: string[]) => {
+  let entries: string[];
+  try {
+    entries = readdirSync(dir);
+  } catch {
+    return;
+  }
+  for (const entry of entries.toSorted()) {
+    const entryPath = join(dir, entry);
+    let stats: ReturnType<typeof statSync>;
+    try {
+      stats = statSync(entryPath);
+    } catch {
+      continue;
+    }
+    if (stats.isDirectory()) {
+      if (!EXCLUDED_DIRECTORIES.has(entry)) {
+        collectSourceFiles(entryPath, out);
+      }
+      continue;
+    }
+    if (
+      stats.isFile() &&
+      hasSourceExtension(entry) &&
+      !EXCLUDED_FILES.has(entry)
+    ) {
+      out.push(entryPath);
+    }
+  }
+};
+
+/**
+ * Derive a SHA-256 fingerprint of the source files under `rootDir`.
+ *
+ * The fingerprint covers relative paths and file contents, so edits,
+ * additions, removals, and renames all change it. Excluded directories
+ * (`node_modules`, `dist`, `.git`, `.trails`, `.trails-tmp`, `.turbo`)
+ * and derived artifacts (`trails.lock`, `topo.lock`, `bun.lock`) never
+ * participate, so recompiling does not invalidate its own fingerprint.
+ *
+ * @example
+ * ```ts
+ * const fingerprint = deriveSourceFingerprint('/path/to/app');
+ * // "3f8a…" — stable until a source file changes
+ * ```
+ */
+export const deriveSourceFingerprint = (rootDir: string): string => {
+  const files: string[] = [];
+  collectSourceFiles(rootDir, files);
+
+  const hasher = new Bun.CryptoHasher('sha256');
+  for (const filePath of files) {
+    const fileHasher = new Bun.CryptoHasher('sha256');
+    fileHasher.update(readFileSync(filePath));
+    hasher.update(relative(rootDir, filePath));
+    hasher.update('\0');
+    hasher.update(fileHasher.digest('hex'));
+    hasher.update('\n');
+  }
+  return hasher.digest('hex');
+};