@ontrails/topography 1.0.0-beta.41

package/src/internal/topo-store.ts

@@ -0,0 +1,1651 @@
+import type { Database, SQLQueryBindings } from 'bun:sqlite';
+
+import {
+  DETOUR_MAX_ATTEMPTS_CAP,
+  Result,
+  activationSourceKey,
+  deriveCliPath,
+  deriveStructuredSignalExamples,
+  deriveStructuredTrailExamples,
+  deriveTrailCliCommandProjection,
+  getEntityReferences,
+  projectActivationSourceDeclaration,
+  signalDiagnosticDefinitions,
+  validateEstablishedTopo,
+  zodToJsonSchema,
+} from '@ontrails/core';
+import type {
+  ActivationEntry,
+  ActivationSource,
+  AnyEntity,
+  AnyResource,
+  AnySignal,
+  AnyTrail,
+  CliSurfaceBindingAliases,
+  FieldOverride,
+  Layer,
+  Topo,
+} from '@ontrails/core';
+
+import { addPermitRequirement } from '../permit.js';
+import { collectLibraryProjection } from '../library-projection.js';
+import { collectTopoGraphOverlays } from '../overlays.js';
+import {
+  resolveCliAliasInputsFromOverlays,
+  resolveTrailheadEntriesFromOverlays,
+} from '../surface-bindings.js';
+import { deriveStableHash } from '../hash.js';
+import {
+  LOCK_MANIFEST_SCHEMA_VERSION,
+  TOPO_GRAPH_SCHEMA_VERSION,
+} from '../types.js';
+import { projectTrailVersions } from '../versioning.js';
+import type {
+  LockManifest,
+  TopoGraphFieldOverride,
+  TopoGraphFieldOverrideKey,
+  TopoGraphLibraryProjection,
+  TopoGraphOverlays,
+  TopoGraphTrailheadEntry,
+} from '../types.js';
+import type {
+  CreateTopoSnapshotInput,
+  TopoSnapshot,
+} from './topo-snapshots.js';
+import {
+  ensureTopoSnapshotSchema,
+  insertTopoSnapshotRecord,
+} from './topo-snapshots.js';
+
+type TopoGraphEntryRecord = Readonly<Record<string, unknown>> & {
+  readonly id: string;
+  readonly kind: 'entity' | 'resource' | 'signal' | 'trail';
+};
+
+type TopoGraphRecord = Readonly<{
+  readonly activationGraph: ActivationGraphRecord;
+  readonly activationSources: Readonly<
+    Record<string, ActivationSourceCatalogRecord>
+  >;
+  readonly entries: readonly TopoGraphEntryRecord[];
+  readonly generatedAt: string;
+  readonly library: TopoGraphLibraryProjection;
+  readonly overlays?: TopoGraphOverlays | undefined;
+  readonly topoGraphSchemaVersion: typeof TOPO_GRAPH_SCHEMA_VERSION;
+  readonly trailheads?: readonly TopoGraphTrailheadEntry[] | undefined;
+}>;
+
+type JsonRecord = Readonly<Record<string, unknown>>;
+type ZodSchemaInput = Parameters<typeof zodToJsonSchema>[0];
+
+interface TopoTrailRow {
+  readonly description: string | null;
+  readonly exampleCount: number;
+  readonly hasExamples: number;
+  readonly hasOutput: number;
+  readonly id: string;
+  readonly idempotent: number;
+  readonly intent: string;
+  readonly meta: string | null;
+  readonly pattern: string | null;
+  readonly snapshotId: string;
+}
+
+interface TopoComposingRow {
+  readonly snapshotId: string;
+  readonly sourceId: string;
+  readonly targetId: string;
+}
+
+interface TopoFiresRow {
+  readonly snapshotId: string;
+  readonly signalId: string;
+  readonly trailId: string;
+}
+
+interface TopoOnRow {
+  readonly snapshotId: string;
+  readonly signalId: string;
+  readonly trailId: string;
+}
+
+interface TopoActivationSourceRow {
+  readonly snapshotId: string;
+  readonly source: string;
+  readonly sourceId: string;
+  readonly sourceKey: string;
+  readonly sourceKind: string;
+}
+
+interface TopoActivationEdgeRow {
+  readonly edge: string;
+  readonly hasWhere: number;
+  readonly snapshotId: string;
+  readonly sourceId: string;
+  readonly sourceKey: string;
+  readonly sourceKind: string;
+  readonly trailId: string;
+}
+
+interface TopoTrailResourceRow {
+  readonly resourceId: string;
+  readonly snapshotId: string;
+  readonly trailId: string;
+}
+
+interface TopoResourceRow {
+  readonly hasHealth: number;
+  readonly hasMock: number;
+  readonly id: string;
+  readonly snapshotId: string;
+}
+
+interface TopoSignalRow {
+  readonly description: string | null;
+  readonly id: string;
+  readonly snapshotId: string;
+}
+
+interface TopoTrailSignalRow {
+  readonly snapshotId: string;
+  readonly signalId: string;
+  readonly trailId: string;
+}
+
+interface TopoSurfaceRow {
+  readonly derivedName: string;
+  readonly method: string | null;
+  readonly snapshotId: string;
+  readonly trailId: string;
+  readonly surface: string;
+}
+
+interface TopoExampleRow {
+  readonly description: string | null;
+  readonly error: string | null;
+  readonly expected: string | null;
+  readonly expectedMatch: string | null;
+  readonly id: string;
+  readonly input: string;
+  readonly name: string;
+  readonly ordinal: number;
+  readonly signals: string | null;
+  readonly snapshotId: string;
+  readonly trailId: string;
+}
+
+interface TopoSchemaRow {
+  readonly jsonSchema: string;
+  readonly ownerId: string;
+  readonly ownerKind: 'signal' | 'trail';
+  readonly snapshotId: string;
+  readonly schemaKind: 'input' | 'output' | 'payload';
+  readonly zodHash: string;
+}
+
+interface StoredTopoExportRow {
+  readonly snapshotId: string;
+  readonly lockManifest: string;
+  readonly topoGraphHash: string;
+  readonly topoGraph: string;
+}
+
+interface StoredTopoExportDbRow {
+  readonly lock_manifest: string;
+  readonly topo_graph: string;
+  readonly topo_graph_hash: string;
+}
+
+export interface StoredTopoExport {
+  readonly lockManifestJson: string;
+  readonly topoGraphHash: string;
+  readonly topoGraphJson: string;
+}
+
+interface MaterializedSchemas {
+  readonly rows: readonly TopoSchemaRow[];
+  readonly signalPayloads: ReadonlyMap<string, JsonRecord>;
+  readonly trailSchemas: ReadonlyMap<
+    string,
+    Readonly<{
+      readonly input: JsonRecord;
+      readonly output?: JsonRecord;
+    }>
+  >;
+}
+
+interface MaterializedTopoArtifacts {
+  readonly exportRow: StoredTopoExportRow;
+  readonly schemaRows: readonly TopoSchemaRow[];
+}
+
+interface SignalGraphRelations {
+  readonly consumers: readonly string[];
+  readonly producers: readonly string[];
+}
+
+interface ActivationSourceCatalogRecord extends JsonRecord {
+  readonly hasParse?: true;
+  readonly hasPayloadSchema?: true;
+  readonly id: string;
+  readonly kind: string;
+  readonly key: string;
+}
+
+interface ActivationGraphEdgeRecord extends JsonRecord {
+  readonly hasWhere: boolean;
+  readonly sourceId: string;
+  readonly sourceKey: string;
+  readonly sourceKind: string;
+  readonly trailId: string;
+}
+
+interface ActivationGraphRecord extends JsonRecord {
+  readonly edgeCount: number;
+  readonly edges: readonly ActivationGraphEdgeRecord[];
+  readonly sourceCount: number;
+  readonly sourceKeys: readonly string[];
+  readonly trailIds: readonly string[];
+}
+
+const EMPTY_SIGNAL_RELATIONS: SignalGraphRelations = {
+  consumers: [],
+  producers: [],
+};
+
+const SIGNAL_DIAGNOSTIC_CODES = Object.keys(
+  signalDiagnosticDefinitions
+).toSorted();
+
+const SIGNAL_DIAGNOSTIC_HOOKS = {
+  codes: SIGNAL_DIAGNOSTIC_CODES,
+  strictMode: true,
+} as const;
+
+const SIGNAL_GOVERNANCE_HOOKS = {
+  consumers: 'trail.on',
+  payload: 'signal.payload',
+  producers: 'trail.fires',
+} as const;
+
+interface NormalizedTopoProjection {
+  readonly activationEdges: readonly TopoActivationEdgeRow[];
+  readonly activationSources: readonly TopoActivationSourceRow[];
+  readonly composings: readonly TopoComposingRow[];
+  readonly examples: readonly TopoExampleRow[];
+  readonly fires: readonly TopoFiresRow[];
+  readonly on: readonly TopoOnRow[];
+  readonly resources: readonly TopoResourceRow[];
+  readonly signals: readonly TopoSignalRow[];
+  readonly surfaces: readonly TopoSurfaceRow[];
+  readonly trailResources: readonly TopoTrailResourceRow[];
+  readonly trailSignals: readonly TopoTrailSignalRow[];
+  readonly trails: readonly TopoTrailRow[];
+}
+
+const canonicalLeaf = (value: unknown): unknown => {
+  switch (typeof value) {
+    case 'bigint': {
+      return value.toString();
+    }
+    case 'function': {
+      return `[Function:${value.name || 'anonymous'}]`;
+    }
+    case 'symbol': {
+      return `[Symbol:${value.description ?? ''}]`;
+    }
+    case 'undefined': {
+      return '[Undefined]';
+    }
+    default: {
+      return value;
+    }
+  }
+};
+
+const canonicalObject = (
+  value: Record<string, unknown>,
+  visit: (value: unknown) => unknown
+): Record<string, unknown> => {
+  const sorted: Record<string, unknown> = {};
+  for (const key of Object.keys(value).toSorted()) {
+    const next = value[key];
+    sorted[key] = next === undefined ? '[Undefined]' : visit(next);
+  }
+  return sorted;
+};
+
+const canonicalize = (value: unknown): unknown => {
+  if (Array.isArray(value)) {
+    return value.map(canonicalize);
+  }
+  if (value instanceof Date) {
+    return value.toISOString();
+  }
+  if (value instanceof RegExp) {
+    return value.toString();
+  }
+  if (value !== null && typeof value === 'object') {
+    return canonicalObject(value as Record<string, unknown>, canonicalize);
+  }
+  return canonicalLeaf(value);
+};
+
+/**
+ * Canonicalize a value for schema definition hashing.
+ *
+ * Matches the canonicalization logic used in `@ontrails/topography` so that
+ * schema hashes are consistent regardless of which code path computes them.
+ * Unlike the general `canonicalize`, this does not convert `Date`, `RegExp`,
+ * or `undefined` to sentinel strings — Zod `_zod.def` objects are plain
+ * JSON-serializable structures and both paths must agree on the same encoding.
+ */
+const schemaCanonical = (value: unknown): unknown => {
+  if (Array.isArray(value)) {
+    return value.map(schemaCanonical);
+  }
+  if (value !== null && typeof value === 'object') {
+    const sorted: Record<string, unknown> = {};
+    for (const key of Object.keys(value).toSorted()) {
+      sorted[key] = schemaCanonical((value as Record<string, unknown>)[key]);
+    }
+    return sorted;
+  }
+  return value;
+};
+
+const stableJson = (value: unknown): string =>
+  JSON.stringify(canonicalize(value));
+
+const hashText = (text: string): string => {
+  const hasher = new Bun.CryptoHasher('sha256');
+  hasher.update(text);
+  return hasher.digest('hex');
+};
+
+const parseJsonRecord = (value: string): JsonRecord =>
+  JSON.parse(value) as JsonRecord;
+
+const schemaDefinitionHash = (schema: unknown): string => {
+  const def =
+    typeof schema === 'object' &&
+    schema !== null &&
+    '_zod' in schema &&
+    typeof (schema as { readonly _zod: unknown })._zod === 'object' &&
+    (schema as { readonly _zod: Record<string, unknown> })._zod !== null &&
+    'def' in (schema as { readonly _zod: Record<string, unknown> })._zod
+      ? (schema as { readonly _zod: { readonly def: unknown } })._zod.def
+      : schema;
+  return hashText(JSON.stringify(schemaCanonical(def)));
+};
+
+const sortedJsonSchema = (
+  schema: ZodSchemaInput
+): { readonly json: string; readonly value: JsonRecord } => {
+  const json = stableJson(zodToJsonSchema(schema));
+  return {
+    json,
+    value: parseJsonRecord(json),
+  };
+};
+
+const sortKeys = <T extends Record<string, unknown>>(value: T): T => {
+  const sorted: Record<string, unknown> = {};
+  for (const key of Object.keys(value).toSorted()) {
+    sorted[key] = value[key];
+  }
+  return sorted as T;
+};
+
+const normalizeTrailRows = (
+  trails: readonly AnyTrail[],
+  snapshotId: string
+): readonly TopoTrailRow[] =>
+  trails.map((trail) => ({
+    description: trail.description ?? null,
+    exampleCount: trail.examples?.length ?? 0,
+    hasExamples: (trail.examples?.length ?? 0) > 0 ? 1 : 0,
+    hasOutput: trail.output === undefined ? 0 : 1,
+    id: trail.id,
+    idempotent: trail.idempotent === true ? 1 : 0,
+    intent: trail.intent,
+    meta: trail.meta === undefined ? null : stableJson(trail.meta),
+    pattern: trail.pattern ?? null,
+    snapshotId,
+  }));
+
+const normalizeComposingRows = (
+  trails: readonly AnyTrail[],
+  snapshotId: string
+): readonly TopoComposingRow[] =>
+  trails.flatMap((trail) =>
+    [...new Set(trail.composes)].toSorted().map((targetId) => ({
+      snapshotId,
+      sourceId: trail.id,
+      targetId,
+    }))
+  );
+
+export const normalizeFiresRows = (
+  trails: readonly AnyTrail[],
+  snapshotId: string
+): readonly TopoFiresRow[] =>
+  trails.flatMap((trail) =>
+    [...new Set(trail.fires)].toSorted().map((signalId) => ({
+      signalId,
+      snapshotId,
+      trailId: trail.id,
+    }))
+  );
+
+export const normalizeOnRows = (
+  trails: readonly AnyTrail[],
+  snapshotId: string
+): readonly TopoOnRow[] =>
+  trails.flatMap((trail) =>
+    [...new Set(trail.on)].toSorted().map((signalId) => ({
+      signalId,
+      snapshotId,
+      trailId: trail.id,
+    }))
+  );
+
+const projectActivationSource = (
+  source: ActivationSource
+): ActivationSourceCatalogRecord =>
+  projectActivationSourceDeclaration(source) as ActivationSourceCatalogRecord;
+
+const projectActivationEdge = (
+  trailId: string,
+  activation: ActivationEntry
+): ActivationGraphEdgeRecord => {
+  const sourceKey = activationSourceKey(activation.source);
+  const edge: Record<string, unknown> = {
+    hasWhere: activation.where !== undefined,
+    sourceId: activation.source.id,
+    sourceKey,
+    sourceKind: activation.source.kind,
+    trailId,
+  };
+
+  if (activation.meta !== undefined) {
+    edge['meta'] = canonicalize(activation.meta);
+  }
+  if (activation.where !== undefined) {
+    edge['where'] = { predicate: true };
+  }
+
+  return sortKeys(edge) as ActivationGraphEdgeRecord;
+};
+
+const collectActivationSourceCatalog = (
+  trails: readonly AnyTrail[]
+): readonly ActivationSourceCatalogRecord[] => {
+  const sources = new Map<string, ActivationSourceCatalogRecord>();
+  for (const trail of trails) {
+    for (const activation of trail.activationSources) {
+      const projected = projectActivationSource(activation.source);
+      sources.set(projected.key, projected);
+    }
+  }
+  return [...sources.values()].toSorted((a, b) => a.key.localeCompare(b.key));
+};
+
+const collectActivationGraphEdges = (
+  trails: readonly AnyTrail[]
+): readonly ActivationGraphEdgeRecord[] => {
+  const edges = new Map<string, ActivationGraphEdgeRecord>();
+  for (const trail of trails) {
+    for (const activation of trail.activationSources) {
+      const edge = projectActivationEdge(trail.id, activation);
+      const key = `${edge.sourceKey}\0${edge.trailId}`;
+      const previous = edges.get(key);
+      edges.set(
+        key,
+        previous === undefined || (!previous.hasWhere && edge.hasWhere)
+          ? edge
+          : previous
+      );
+    }
+  }
+
+  return [...edges.values()].toSorted(
+    (a, b) =>
+      a.sourceKey.localeCompare(b.sourceKey) ||
+      a.trailId.localeCompare(b.trailId)
+  );
+};
+
+const buildActivationGraphRecord = (
+  edges: readonly ActivationGraphEdgeRecord[],
+  sources: readonly ActivationSourceCatalogRecord[]
+): ActivationGraphRecord =>
+  sortKeys({
+    edgeCount: edges.length,
+    edges,
+    sourceCount: sources.length,
+    sourceKeys: sources.map((source) => source.key),
+    trailIds: [...new Set(edges.map((edge) => edge.trailId))].toSorted(),
+  }) as ActivationGraphRecord;
+
+export const normalizeActivationSourceRows = (
+  trails: readonly AnyTrail[],
+  snapshotId: string
+): readonly TopoActivationSourceRow[] =>
+  collectActivationSourceCatalog(trails).map((source) => ({
+    snapshotId,
+    source: stableJson(source),
+    sourceId: source.id,
+    sourceKey: source.key,
+    sourceKind: source.kind,
+  }));
+
+export const normalizeActivationEdgeRows = (
+  trails: readonly AnyTrail[],
+  snapshotId: string
+): readonly TopoActivationEdgeRow[] =>
+  collectActivationGraphEdges(trails).map((edge) => ({
+    edge: stableJson(edge),
+    hasWhere: edge.hasWhere ? 1 : 0,
+    snapshotId,
+    sourceId: edge.sourceId,
+    sourceKey: edge.sourceKey,
+    sourceKind: edge.sourceKind,
+    trailId: edge.trailId,
+  }));
+
+const normalizeTrailResourceRows = (
+  trails: readonly AnyTrail[],
+  snapshotId: string
+): readonly TopoTrailResourceRow[] =>
+  trails.flatMap((trail) =>
+    [...new Set(trail.resources.map((resource) => resource.id))]
+      .toSorted()
+      .map((resourceId) => ({
+        resourceId,
+        snapshotId,
+        trailId: trail.id,
+      }))
+  );
+
+const normalizeResourceRows = (
+  resources: readonly AnyResource[],
+  snapshotId: string
+): readonly TopoResourceRow[] =>
+  resources.map((resource) => ({
+    hasHealth: resource.health === undefined ? 0 : 1,
+    hasMock: resource.mock === undefined ? 0 : 1,
+    id: resource.id,
+    snapshotId,
+  }));
+
+const normalizeSignalRows = (
+  signals: readonly AnySignal[],
+  snapshotId: string
+): readonly TopoSignalRow[] =>
+  signals.map((signal) => ({
+    description: signal.description ?? null,
+    id: signal.id,
+    snapshotId,
+  }));
+
+const normalizeTrailSignalRows = (
+  signals: readonly AnySignal[],
+  snapshotId: string
+): readonly TopoTrailSignalRow[] =>
+  signals.flatMap((signal) => {
+    if (signal.from === undefined) {
+      return [];
+    }
+
+    return [...new Set(signal.from)].toSorted().map((trailId) => ({
+      signalId: signal.id,
+      snapshotId,
+      trailId,
+    }));
+  });
+
+/**
+ * Project surface rows for stored topo.
+ *
+ * Currently records only CLI-derived rows. MCP, HTTP, and other surface
+ * projections are intentionally deferred until the topo-store schema supports
+ * multi-surface representation. The JSON export (`topo_graph` in
+ * `topo_exports`) is more faithful for now. See ADR-0015 for the target shape.
+ */
+const normalizeSurfaceRows = (
+  trails: readonly AnyTrail[],
+  snapshotId: string
+): readonly TopoSurfaceRow[] =>
+  trails.map((trail) => ({
+    derivedName: deriveCliPath(trail.id).join(' '),
+    method: null,
+    snapshotId,
+    surface: 'cli',
+    trailId: trail.id,
+  }));
+
+const buildExampleId = (
+  snapshotId: string,
+  trailId: string,
+  ordinal: number
+): string => `${snapshotId}:${trailId}:${ordinal.toString().padStart(4, '0')}`;
+
+const normalizeExampleRows = (
+  trails: readonly AnyTrail[],
+  snapshotId: string
+): readonly TopoExampleRow[] =>
+  trails.flatMap((trail) => {
+    const examples = deriveStructuredTrailExamples(trail.examples) ?? [];
+    return examples.map((example, index) => ({
+      description: example.description ?? null,
+      error: example.error ?? null,
+      expected:
+        example.expected === undefined ? null : stableJson(example.expected),
+      expectedMatch:
+        example.expectedMatch === undefined
+          ? null
+          : stableJson(example.expectedMatch),
+      id: buildExampleId(snapshotId, trail.id, index),
+      input: stableJson(example.input),
+      name: example.name,
+      ordinal: index,
+      signals:
+        example.signals === undefined ? null : stableJson(example.signals),
+      snapshotId,
+      trailId: trail.id,
+    }));
+  });
+
+const normalizeTopoProjection = (
+  topo: Topo,
+  snapshotId: string
+): NormalizedTopoProjection => {
+  const trails = topo.list().toSorted((a, b) => a.id.localeCompare(b.id));
+  const resources = topo
+    .listResources()
+    .toSorted((a, b) => a.id.localeCompare(b.id));
+  const signals = topo
+    .listSignals()
+    .toSorted((a, b) => a.id.localeCompare(b.id));
+
+  return {
+    activationEdges: normalizeActivationEdgeRows(trails, snapshotId),
+    activationSources: normalizeActivationSourceRows(trails, snapshotId),
+    composings: normalizeComposingRows(trails, snapshotId),
+    examples: normalizeExampleRows(trails, snapshotId),
+    fires: normalizeFiresRows(trails, snapshotId),
+    on: normalizeOnRows(trails, snapshotId),
+    resources: normalizeResourceRows(resources, snapshotId),
+    signals: normalizeSignalRows(signals, snapshotId),
+    surfaces: normalizeSurfaceRows(trails, snapshotId),
+    trailResources: normalizeTrailResourceRows(trails, snapshotId),
+    trailSignals: normalizeTrailSignalRows(signals, snapshotId),
+    trails: normalizeTrailRows(trails, snapshotId),
+  };
+};
+
+/**
+ * Materialize the JSON Schema row for an owner, always generating fresh
+ * output from the live Zod schema.
+ *
+ * Earlier revisions reused a previously stored `json_schema` when the
+ * `zod_hash` matched, across all snapshots in the store. That hash is
+ * computed from `JSON.stringify` over the Zod definition, which cannot see
+ * `.describe()` metadata or object field order, so schema edits that change
+ * the generated JSON Schema could keep serving pre-edit bytes and make a
+ * freshly compiled lock diverge from a fresh derivation (TRL-1191). The
+ * `zod_hash` column remains as per-snapshot provenance only — it is never
+ * a substitute for generation.
+ */
+const resolveSchemaRow = (
+  _db: Database,
+  ownerId: string,
+  ownerKind: TopoSchemaRow['ownerKind'],
+  snapshotId: string,
+  schemaKind: TopoSchemaRow['schemaKind'],
+  schema: ZodSchemaInput
+): {
+  readonly row: TopoSchemaRow;
+  readonly value: JsonRecord;
+} => {
+  const zodHash = schemaDefinitionHash(schema);
+  const generated = sortedJsonSchema(schema);
+  return {
+    row: {
+      jsonSchema: generated.json,
+      ownerId,
+      ownerKind,
+      schemaKind,
+      snapshotId,
+      zodHash,
+    },
+    value: generated.value,
+  };
+};
+
+const materializeTrailSchema = (
+  db: Database,
+  snapshotId: string,
+  trail: AnyTrail
+): {
+  readonly rows: readonly TopoSchemaRow[];
+  readonly value: Readonly<{
+    readonly input: JsonRecord;
+    readonly output?: JsonRecord;
+  }>;
+} => {
+  const inputSchema = resolveSchemaRow(
+    db,
+    trail.id,
+    'trail',
+    snapshotId,
+    'input',
+    trail.input as ZodSchemaInput
+  );
+
+  if (trail.output === undefined) {
+    return {
+      rows: [inputSchema.row],
+      value: {
+        input: inputSchema.value,
+      },
+    };
+  }
+
+  const outputSchema = resolveSchemaRow(
+    db,
+    trail.id,
+    'trail',
+    snapshotId,
+    'output',
+    trail.output as ZodSchemaInput
+  );
+
+  return {
+    rows: [inputSchema.row, outputSchema.row],
+    value: {
+      input: inputSchema.value,
+      output: outputSchema.value,
+    },
+  };
+};
+
+const materializeTrailSchemas = (
+  db: Database,
+  snapshotId: string,
+  trails: readonly AnyTrail[]
+): Pick<MaterializedSchemas, 'rows' | 'trailSchemas'> => {
+  const rows: TopoSchemaRow[] = [];
+  const trailSchemas = new Map<
+    string,
+    Readonly<{
+      readonly input: JsonRecord;
+      readonly output?: JsonRecord;
+    }>
+  >();
+
+  for (const trail of trails) {
+    const materialized = materializeTrailSchema(db, snapshotId, trail);
+    rows.push(...materialized.rows);
+    trailSchemas.set(trail.id, materialized.value);
+  }
+
+  return {
+    rows,
+    trailSchemas,
+  };
+};
+
+const materializeSignalSchemas = (
+  db: Database,
+  snapshotId: string,
+  signals: readonly AnySignal[]
+): Pick<MaterializedSchemas, 'rows' | 'signalPayloads'> => {
+  const rows: TopoSchemaRow[] = [];
+  const signalPayloads = new Map<string, JsonRecord>();
+
+  for (const signal of signals) {
+    const payloadSchema = resolveSchemaRow(
+      db,
+      signal.id,
+      'signal',
+      snapshotId,
+      'payload',
+      signal.payload as ZodSchemaInput
+    );
+    rows.push(payloadSchema.row);
+    signalPayloads.set(signal.id, payloadSchema.value);
+  }
+
+  return {
+    rows,
+    signalPayloads,
+  };
+};
+
+const materializeSchemas = (
+  db: Database,
+  snapshotId: string,
+  signals: readonly AnySignal[],
+  trails: readonly AnyTrail[]
+): MaterializedSchemas => {
+  const trailMaterial = materializeTrailSchemas(db, snapshotId, trails);
+  const signalMaterial = materializeSignalSchemas(db, snapshotId, signals);
+
+  return {
+    rows: [...trailMaterial.rows, ...signalMaterial.rows],
+    signalPayloads: signalMaterial.signalPayloads,
+    trailSchemas: trailMaterial.trailSchemas,
+  };
+};
+
+const extractSurfaces = (raw: Record<string, unknown>): string[] =>
+  Array.isArray(raw['surfaces'])
+    ? (raw['surfaces'] as string[]).toSorted()
+    : [];
+
+const addSafetyMarkers = (
+  entry: Record<string, unknown>,
+  trail: AnyTrail
+): void => {
+  if (trail.intent !== 'write') {
+    entry['intent'] = trail.intent;
+  }
+
+  if (trail.idempotent === true) {
+    entry['idempotent'] = true;
+  }
+
+  if (trail.dryRun === true) {
+    entry['dryRunCapable'] = true;
+  }
+};
+
+const addExtendedMetadata = (
+  entry: Record<string, unknown>,
+  raw: Record<string, unknown>,
+  trail: AnyTrail
+): void => {
+  if (raw['deprecated'] === true) {
+    entry['deprecated'] = true;
+  }
+
+  if (typeof raw['replacedBy'] === 'string') {
+    entry['replacedBy'] = raw['replacedBy'];
+  }
+
+  if (trail.detours.length > 0) {
+    entry['detours'] = trail.detours.map((d) => ({
+      maxAttempts: Math.max(
+        1,
+        Math.min(d.maxAttempts ?? 1, DETOUR_MAX_ATTEMPTS_CAP)
+      ),
+      on: d.on.name,
+    }));
+  }
+};
+
+const addTrailRelations = (
+  entry: Record<string, unknown>,
+  trail: AnyTrail
+): void => {
+  if (trail.activationSources.length > 0) {
+    entry['activationSources'] = trail.activationSources.map((activation) =>
+      sortKeys({
+        ...(activation.meta === undefined
+          ? {}
+          : { meta: canonicalize(activation.meta) }),
+        source: projectActivationSource(activation.source),
+        ...(activation.where === undefined
+          ? {}
+          : { where: sortKeys({ predicate: true }) }),
+      })
+    );
+  }
+
+  if (trail.composes.length > 0) {
+    entry['composes'] = trail.composes.toSorted();
+  }
+
+  if (trail.fires.length > 0) {
+    entry['fires'] = trail.fires.toSorted();
+  }
+
+  if (trail.on.length > 0) {
+    entry['on'] = trail.on.toSorted();
+  }
+
+  if (trail.entities.length > 0) {
+    entry['entities'] = trail.entities.map((entity) => entity.name).toSorted();
+  }
+
+  if (trail.resources.length > 0) {
+    entry['resources'] = trail.resources
+      .map((resource) => resource.id)
+      .toSorted();
+  }
+};
+
+const layerToReferenceRecord = (
+  scope: 'topo' | 'trail',
+  layer: Layer
+): Record<string, unknown> => {
+  const reference: Record<string, unknown> = {
+    name: layer.name,
+    scope,
+  };
+  if (layer.input !== undefined) {
+    reference['input'] = parseJsonRecord(
+      stableJson(zodToJsonSchema(layer.input as ZodSchemaInput))
+    );
+  }
+  return sortKeys(reference);
+};
+
+const addLayerAttachments = (
+  entry: Record<string, unknown>,
+  topoLayers: readonly Layer[],
+  trail: AnyTrail
+): void => {
+  const layers = [
+    ...topoLayers.map((layer) => layerToReferenceRecord('topo', layer)),
+    ...trail.layers.map((layer) => layerToReferenceRecord('trail', layer)),
+  ].toSorted((left, right) => {
+    const scope = String(left['scope']).localeCompare(String(right['scope']));
+    return scope === 0
+      ? String(left['name']).localeCompare(String(right['name']))
+      : scope;
+  });
+
+  if (layers.length > 0) {
+    entry['layers'] = layers;
+  }
+};
+
+const FIELD_OVERRIDE_KEYS: readonly TopoGraphFieldOverrideKey[] = [
+  'hint',
+  'label',
+  'message',
+  'options',
+];
+
+const collectFieldOverrideKeys = (
+  override: FieldOverride
+): readonly TopoGraphFieldOverrideKey[] =>
+  FIELD_OVERRIDE_KEYS.filter((key) => override[key] !== undefined);
+
+const deriveFieldOverrides = (
+  fields: Readonly<Record<string, FieldOverride>> | undefined
+): readonly TopoGraphFieldOverride[] | undefined => {
+  if (fields === undefined) {
+    return undefined;
+  }
+
+  const overrides = Object.entries(fields)
+    .flatMap(([field, override]) => {
+      const overrideKeys = collectFieldOverrideKeys(override);
+      if (overrideKeys.length === 0) {
+        return [];
+      }
+      return [
+        {
+          field,
+          overrides: overrideKeys,
+          provenance: { source: 'trail.fields' as const },
+        },
+      ];
+    })
+    .toSorted((a, b) => a.field.localeCompare(b.field));
+
+  return overrides.length > 0 ? overrides : undefined;
+};
+
+const addFieldOverrides = (
+  entry: Record<string, unknown>,
+  trail: AnyTrail
+): void => {
+  const fieldOverrides = deriveFieldOverrides(trail.fields);
+  if (fieldOverrides !== undefined) {
+    entry['fieldOverrides'] = fieldOverrides;
+  }
+};
+
+const buildTrailEntryBase = (
+  trail: AnyTrail,
+  trailSchema: Readonly<{
+    readonly input: JsonRecord;
+    readonly output?: JsonRecord;
+  }>,
+  surfaceAliases: CliSurfaceBindingAliases | undefined
+): {
+  readonly entry: Record<string, unknown>;
+  readonly raw: Record<string, unknown>;
+} => {
+  const raw = trail as unknown as Record<string, unknown>;
+  const entry: Record<string, unknown> = {
+    cli: deriveTrailCliCommandProjection(trail, {
+      aliasSource: 'surface',
+      aliases: surfaceAliases?.[trail.id],
+    }),
+    exampleCount: trail.examples?.length ?? 0,
+    id: trail.id,
+    input: trailSchema.input,
+    kind: trail.kind,
+    surfaces: extractSurfaces(raw),
+  };
+
+  if (trailSchema.output !== undefined) {
+    entry['output'] = trailSchema.output;
+  }
+
+  const examples = deriveStructuredTrailExamples(trail.examples);
+  if (examples !== undefined) {
+    entry['examples'] = examples;
+  }
+
+  if (trail.description !== undefined) {
+    entry['description'] = trail.description;
+  }
+
+  if (trail.pattern !== undefined) {
+    entry['pattern'] = trail.pattern;
+  }
+
+  return {
+    entry,
+    raw,
+  };
+};
+
+const addVersioning = (
+  entry: Record<string, unknown>,
+  trail: AnyTrail
+): void => {
+  if (trail.version === undefined) {
+    return;
+  }
+  const projection = projectTrailVersions(
+    trail,
+    (schema) => sortedJsonSchema(schema as ZodSchemaInput).value
+  );
+  if (projection === undefined) {
+    return;
+  }
+
+  entry['marker'] = projection.marker;
+  entry['supports'] = projection.supports;
+  entry['version'] = projection.version;
+  if (projection.versions !== undefined) {
+    entry['versions'] = projection.versions;
+  }
+};
+
+const trailToEntryRecord = (
+  trail: AnyTrail,
+  topoLayers: readonly Layer[],
+  trailSchema: Readonly<{
+    readonly input: JsonRecord;
+    readonly output?: JsonRecord;
+  }>,
+  surfaceAliases: CliSurfaceBindingAliases | undefined
+): TopoGraphEntryRecord => {
+  const { entry, raw } = buildTrailEntryBase(
+    trail,
+    trailSchema,
+    surfaceAliases
+  );
+  addSafetyMarkers(entry, trail);
+  addPermitRequirement(entry, trail);
+  addExtendedMetadata(entry, raw, trail);
+  addTrailRelations(entry, trail);
+  addLayerAttachments(entry, topoLayers, trail);
+  addFieldOverrides(entry, trail);
+  addVersioning(entry, trail);
+  return sortKeys(entry) as TopoGraphEntryRecord;
+};
+
+const signalToEntryRecord = (
+  signal: AnySignal,
+  payloadSchema: JsonRecord,
+  relations: SignalGraphRelations
+): TopoGraphEntryRecord => {
+  const raw = signal as unknown as Record<string, unknown>;
+  const examples = deriveStructuredSignalExamples(signal.examples);
+  const entry: Record<string, unknown> = {
+    consumers: relations.consumers,
+    diagnostics: SIGNAL_DIAGNOSTIC_HOOKS,
+    exampleCount: signal.examples?.length ?? 0,
+    governance: SIGNAL_GOVERNANCE_HOOKS,
+    id: signal.id,
+    input: payloadSchema,
+    kind: 'signal',
+    payload: payloadSchema,
+    producers: relations.producers,
+    surfaces: extractSurfaces(raw),
+  };
+
+  if (signal.description !== undefined) {
+    entry['description'] = signal.description;
+  }
+
+  if (signal.meta !== undefined) {
+    entry['meta'] = signal.meta;
+  }
+
+  if (examples !== undefined && examples.length > 0) {
+    entry['examples'] = examples;
+  }
+
+  if (signal.from !== undefined && signal.from.length > 0) {
+    entry['from'] = signal.from.toSorted();
+  }
+
+  if (raw['deprecated'] === true) {
+    entry['deprecated'] = true;
+  }
+
+  if (typeof raw['replacedBy'] === 'string') {
+    entry['replacedBy'] = raw['replacedBy'];
+  }
+
+  return sortKeys(entry) as TopoGraphEntryRecord;
+};
+
+const resourceToEntryRecord = (resource: AnyResource): TopoGraphEntryRecord => {
+  const entry: Record<string, unknown> = {
+    exampleCount: 0,
+    id: resource.id,
+    kind: 'resource',
+    surfaces: [],
+  };
+
+  if (resource.description !== undefined) {
+    entry['description'] = resource.description;
+  }
+
+  if (resource.health !== undefined) {
+    entry['healthcheck'] = true;
+  }
+
+  return sortKeys(entry) as TopoGraphEntryRecord;
+};
+
+const entityToEntryRecord = (entity: AnyEntity): TopoGraphEntryRecord => {
+  const schema = sortedJsonSchema(entity);
+  const entry: Record<string, unknown> = {
+    exampleCount: entity.examples?.length ?? 0,
+    id: entity.name,
+    identity: entity.identity,
+    kind: 'entity',
+    schema: schema.value,
+    surfaces: [],
+  };
+
+  const references = getEntityReferences(entity);
+  if (references.length > 0) {
+    entry['references'] = references;
+  }
+
+  return sortKeys(entry) as TopoGraphEntryRecord;
+};
+
+const requireTrailSchema = (
+  trailSchemas: MaterializedSchemas['trailSchemas'],
+  trailId: string
+): Readonly<{
+  readonly input: JsonRecord;
+  readonly output?: JsonRecord;
+}> => {
+  const schema = trailSchemas.get(trailId);
+  if (schema === undefined) {
+    throw new Error(`Missing cached trail schema for "${trailId}"`);
+  }
+  return schema;
+};
+
+const requireSignalPayload = (
+  signalPayloads: MaterializedSchemas['signalPayloads'],
+  signalId: string
+): JsonRecord => {
+  const payload = signalPayloads.get(signalId);
+  if (payload === undefined) {
+    throw new Error(`Missing cached signal schema for "${signalId}"`);
+  }
+  return payload;
+};
+
+const collectSignalGraphRelations = (
+  signals: readonly AnySignal[],
+  trails: readonly AnyTrail[]
+): ReadonlyMap<string, SignalGraphRelations> => {
+  const producers = new Map<string, Set<string>>();
+  const consumers = new Map<string, Set<string>>();
+
+  for (const trail of trails) {
+    for (const signalId of trail.fires) {
+      const current = producers.get(signalId) ?? new Set<string>();
+      current.add(trail.id);
+      producers.set(signalId, current);
+    }
+    for (const signalId of trail.on) {
+      const current = consumers.get(signalId) ?? new Set<string>();
+      current.add(trail.id);
+      consumers.set(signalId, current);
+    }
+  }
+
+  return new Map(
+    signals.map((signal) => [
+      signal.id,
+      {
+        consumers: [...(consumers.get(signal.id) ?? [])].toSorted(),
+        producers: [...(producers.get(signal.id) ?? [])].toSorted(),
+      },
+    ])
+  );
+};
+
+const buildTopoGraph = (
+  entities: readonly AnyEntity[],
+  generatedAt: string,
+  resources: readonly AnyResource[],
+  signalPayloads: ReadonlyMap<string, JsonRecord>,
+  signals: readonly AnySignal[],
+  topo: Topo,
+  topoLayers: readonly Layer[],
+  trailSchemas: ReadonlyMap<
+    string,
+    Readonly<{
+      readonly input: JsonRecord;
+      readonly output?: JsonRecord;
+    }>
+  >,
+  trails: readonly AnyTrail[],
+  options?: Pick<CreateTopoSnapshotInput, 'overlays'> | undefined
+): TopoGraphRecord => {
+  const overlays = collectTopoGraphOverlays(topo, options?.overlays);
+  const surfaceAliases = resolveCliAliasInputsFromOverlays(
+    topo,
+    options?.overlays
+  );
+  const trailheads = resolveTrailheadEntriesFromOverlays(
+    topo,
+    options?.overlays
+  );
+  const signalRelations = collectSignalGraphRelations(signals, trails);
+  const activationSources = collectActivationSourceCatalog(trails);
+  const activationEdges = collectActivationGraphEdges(trails);
+  const entries = [
+    ...entities.map((entity) => entityToEntryRecord(entity)),
+    ...trails.map((trail) =>
+      trailToEntryRecord(
+        trail,
+        topoLayers,
+        requireTrailSchema(trailSchemas, trail.id),
+        surfaceAliases
+      )
+    ),
+    ...signals.map((signal) =>
+      signalToEntryRecord(
+        signal,
+        requireSignalPayload(signalPayloads, signal.id),
+        signalRelations.get(signal.id) ?? EMPTY_SIGNAL_RELATIONS
+      )
+    ),
+    ...resources.map((resource) => resourceToEntryRecord(resource)),
+  ].toSorted((a, b) => a.id.localeCompare(b.id));
+
+  return {
+    activationGraph: buildActivationGraphRecord(
+      activationEdges,
+      activationSources
+    ),
+    activationSources: Object.fromEntries(
+      activationSources.map((source) => [source.key, source])
+    ),
+    entries,
+    generatedAt,
+    library: collectLibraryProjection(topo),
+    ...(overlays === undefined ? {} : { overlays }),
+    topoGraphSchemaVersion: TOPO_GRAPH_SCHEMA_VERSION,
+    ...(trailheads === undefined ? {} : { trailheads }),
+  };
+};
+
+const hashTopoGraphRecord = (topoGraph: TopoGraphRecord): string => {
+  // Same canonical hash path as `deriveTopoGraphHash`: strip `generatedAt`,
+  // then key-sorted SHA-256 via the shared `deriveStableHash`.
+  const { generatedAt: _unused, ...rest } = topoGraph;
+  return deriveStableHash(rest);
+};
+
+const countEntriesForKind = (
+  entries: readonly TopoGraphEntryRecord[],
+  kind: TopoGraphEntryRecord['kind']
+): number => entries.filter((entry) => entry.kind === kind).length;
+
+const buildLockManifest = (
+  hash: string,
+  topo: Topo,
+  topoGraph: TopoGraphRecord
+): LockManifest =>
+  sortKeys({
+    artifacts: [{ path: 'topo.lock', role: 'topo', sha256: hash }],
+    scope: { app: topo.name },
+    summary: {
+      entities: countEntriesForKind(topoGraph.entries, 'entity'),
+      resources: countEntriesForKind(topoGraph.entries, 'resource'),
+      signals: countEntriesForKind(topoGraph.entries, 'signal'),
+      trails: countEntriesForKind(topoGraph.entries, 'trail'),
+    },
+    version: LOCK_MANIFEST_SCHEMA_VERSION,
+  }) as LockManifest;
+
+const buildStoredTopoExport = (
+  db: Database,
+  snapshot: TopoSnapshot,
+  topo: Topo,
+  options?: Pick<CreateTopoSnapshotInput, 'overlays'> | undefined
+): MaterializedTopoArtifacts => {
+  const entities = topo
+    .listEntities()
+    .toSorted((a, b) => a.name.localeCompare(b.name));
+  const trails = topo.list().toSorted((a, b) => a.id.localeCompare(b.id));
+  const resources = topo
+    .listResources()
+    .toSorted((a, b) => a.id.localeCompare(b.id));
+  const signals = topo
+    .listSignals()
+    .toSorted((a, b) => a.id.localeCompare(b.id));
+  const schemas = materializeSchemas(db, snapshot.id, signals, trails);
+  const topoGraph = buildTopoGraph(
+    entities,
+    snapshot.createdAt,
+    resources,
+    schemas.signalPayloads,
+    signals,
+    topo,
+    topo.layers,
+    schemas.trailSchemas,
+    trails,
+    options
+  );
+  const topoGraphHash = hashTopoGraphRecord(topoGraph);
+  const lockManifest = `${JSON.stringify(
+    buildLockManifest(topoGraphHash, topo, topoGraph),
+    null,
+    2
+  )}\n`;
+
+  return {
+    exportRow: {
+      lockManifest,
+      snapshotId: snapshot.id,
+      topoGraph: `${JSON.stringify(topoGraph, null, 2)}\n`,
+      topoGraphHash,
+    },
+    schemaRows: schemas.rows,
+  };
+};
+
+const insertRows = <TRow>(
+  db: Database,
+  rows: readonly TRow[],
+  statement: string,
+  toParams: (row: TRow) => SQLQueryBindings[]
+): void => {
+  for (const row of rows) {
+    db.run(statement, toParams(row));
+  }
+};
+
+const insertProjectedRows = (
+  db: Database,
+  projection: NormalizedTopoProjection
+): void => {
+  insertRows(
+    db,
+    projection.trails,
+    `INSERT INTO topo_trails (
+      id, intent, idempotent, has_output, has_examples, example_count, description, pattern, meta, snapshot_id
+    ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+    (row) => [
+      row.id,
+      row.intent,
+      row.idempotent,
+      row.hasOutput,
+      row.hasExamples,
+      row.exampleCount,
+      row.description,
+      row.pattern,
+      row.meta,
+      row.snapshotId,
+    ]
+  );
+  insertRows(
+    db,
+    projection.composings,
+    'INSERT INTO topo_composings (source_id, target_id, snapshot_id) VALUES (?, ?, ?)',
+    (row) => [row.sourceId, row.targetId, row.snapshotId]
+  );
+  insertRows(
+    db,
+    projection.trailResources,
+    `INSERT INTO topo_trail_resources (trail_id, resource_id, snapshot_id)
+     VALUES (?, ?, ?)`,
+    (row) => [row.trailId, row.resourceId, row.snapshotId]
+  );
+  insertRows(
+    db,
+    projection.resources,
+    `INSERT INTO topo_resources (id, has_mock, has_health, snapshot_id)
+     VALUES (?, ?, ?, ?)`,
+    (row) => [row.id, row.hasMock, row.hasHealth, row.snapshotId]
+  );
+  insertRows(
+    db,
+    projection.signals,
+    'INSERT INTO topo_signals (id, description, snapshot_id) VALUES (?, ?, ?)',
+    (row) => [row.id, row.description, row.snapshotId]
+  );
+  insertRows(
+    db,
+    projection.trailSignals,
+    `INSERT INTO topo_trail_signals (trail_id, signal_id, snapshot_id)
+     VALUES (?, ?, ?)`,
+    (row) => [row.trailId, row.signalId, row.snapshotId]
+  );
+  insertRows(
+    db,
+    projection.fires,
+    `INSERT INTO topo_trail_fires (trail_id, signal_id, snapshot_id)
+     VALUES (?, ?, ?)`,
+    (row) => [row.trailId, row.signalId, row.snapshotId]
+  );
+  insertRows(
+    db,
+    projection.on,
+    `INSERT INTO topo_trail_on (trail_id, signal_id, snapshot_id)
+     VALUES (?, ?, ?)`,
+    (row) => [row.trailId, row.signalId, row.snapshotId]
+  );
+  insertRows(
+    db,
+    projection.activationSources,
+    `INSERT INTO topo_activation_sources (
+      source_key, source_id, source_kind, source, snapshot_id
+    ) VALUES (?, ?, ?, ?, ?)`,
+    (row) => [
+      row.sourceKey,
+      row.sourceId,
+      row.sourceKind,
+      row.source,
+      row.snapshotId,
+    ]
+  );
+  insertRows(
+    db,
+    projection.activationEdges,
+    `INSERT INTO topo_activation_edges (
+      source_key, source_id, source_kind, trail_id, has_where, edge, snapshot_id
+    ) VALUES (?, ?, ?, ?, ?, ?, ?)`,
+    (row) => [
+      row.sourceKey,
+      row.sourceId,
+      row.sourceKind,
+      row.trailId,
+      row.hasWhere,
+      row.edge,
+      row.snapshotId,
+    ]
+  );
+  insertRows(
+    db,
+    projection.surfaces,
+    `INSERT INTO topo_surfaces (trail_id, surface, derived_name, method, snapshot_id)
+     VALUES (?, ?, ?, ?, ?)`,
+    (row) => [
+      row.trailId,
+      row.surface,
+      row.derivedName,
+      row.method,
+      row.snapshotId,
+    ]
+  );
+  insertRows(
+    db,
+    projection.examples,
+    `INSERT INTO topo_examples (
+      id, trail_id, ordinal, name, description, input, expected, expected_match, error, signals, snapshot_id
+    ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+    (row) => [
+      row.id,
+      row.trailId,
+      row.ordinal,
+      row.name,
+      row.description,
+      row.input,
+      row.expected,
+      row.expectedMatch,
+      row.error,
+      row.signals,
+      row.snapshotId,
+    ]
+  );
+};
+
+const insertSchemaRows = (
+  db: Database,
+  rows: readonly TopoSchemaRow[]
+): void => {
+  insertRows(
+    db,
+    rows,
+    `INSERT INTO topo_schemas (
+      owner_id, owner_kind, schema_kind, zod_hash, json_schema, snapshot_id
+    ) VALUES (?, ?, ?, ?, ?, ?)`,
+    (row) => [
+      row.ownerId,
+      row.ownerKind,
+      row.schemaKind,
+      row.zodHash,
+      row.jsonSchema,
+      row.snapshotId,
+    ]
+  );
+};
+
+const insertStoredExport = (
+  db: Database,
+  exportRow: StoredTopoExportRow
+): void => {
+  db.run(
+    `INSERT INTO topo_exports (
+      snapshot_id, topo_graph, topo_graph_hash, lock_manifest
+    ) VALUES (?, ?, ?, ?)`,
+    [
+      exportRow.snapshotId,
+      exportRow.topoGraph,
+      exportRow.topoGraphHash,
+      exportRow.lockManifest,
+    ]
+  );
+};
+
+export const getStoredTopoExport = (
+  db: Database,
+  snapshotId: string
+): StoredTopoExport | undefined => {
+  const row = db
+    .query<StoredTopoExportDbRow, [string]>(
+      `SELECT topo_graph, topo_graph_hash, lock_manifest
+       FROM topo_exports
+       WHERE snapshot_id = ?`
+    )
+    .get(snapshotId);
+
+  if (row === undefined || row === null) {
+    return undefined;
+  }
+
+  return {
+    lockManifestJson: row.lock_manifest,
+    topoGraphHash: row.topo_graph_hash,
+    topoGraphJson: row.topo_graph,
+  };
+};
+
+/**
+ * Fail-fast boundary validation for the app-authored `surfaces` overlay's
+ * `cli` bindings, run before the snapshot transaction opens so an invalid
+ * binding surfaces as a Result instead of aborting mid-write.
+ */
+const validateSurfaceCliBindings = (
+  topo: Topo,
+  input?: Pick<CreateTopoSnapshotInput, 'overlays'> | undefined
+): Result<void, Error> => {
+  try {
+    resolveCliAliasInputsFromOverlays(topo, input?.overlays);
+    return Result.ok();
+  } catch (error: unknown) {
+    return Result.err(
+      error instanceof Error ? error : new Error(String(error))
+    );
+  }
+};
+
+export const createTopoSnapshot = (
+  db: Database,
+  topo: Topo,
+  input?: CreateTopoSnapshotInput
+): Result<TopoSnapshot, Error> => {
+  const validated = validateEstablishedTopo(topo);
+  if (validated.isErr()) {
+    return validated;
+  }
+  const cliBindings = validateSurfaceCliBindings(topo, input);
+  if (cliBindings.isErr()) {
+    return cliBindings;
+  }
+
+  ensureTopoSnapshotSchema(db);
+
+  const snapshotInput: CreateTopoSnapshotInput = {
+    ...input,
+    resourceCount: input?.resourceCount ?? topo.resources.size,
+    signalCount: input?.signalCount ?? topo.signals.size,
+    trailCount: input?.trailCount ?? topo.trails.size,
+  };
+
+  const snapshot = db.transaction(() => {
+    const record = insertTopoSnapshotRecord(db, snapshotInput);
+    const artifacts = buildStoredTopoExport(db, record, topo, snapshotInput);
+    insertProjectedRows(db, normalizeTopoProjection(topo, record.id));
+    insertSchemaRows(db, artifacts.schemaRows);
+    insertStoredExport(db, artifacts.exportRow);
+    return record;
+  })();
+
+  return Result.ok(snapshot);
+};