@ontrails/topography 0.2.0

package/README.md

@@ -0,0 +1,228 @@
+# @ontrails/topography
+
+Topography is the durable graph substrate for Trails: deterministic TopoGraphs, lockfile helpers, semantic diffing, topo-store persistence, and Wayfind graph-read APIs.
+
+Most applications reach this package through top-level `trails compile`, `trails validate`, and `trails diff`. Those CLI trails layer workspace and topo-store behavior on top of the building blocks in `@ontrails/topography`. The package itself ships library entry points, not a separate CLI binary, and retired `trails topo compile`, `trails topo verify`, and `trails topo check` forms are not aliases.
+
+## Why this package earns a README
+
+[ADR-0042](../../docs/adr/0042-core-topography-boundary-doctrine.md) draws the boundary by lifecycle: core owns the in-process graph, while Topography owns durable graph artifacts that cross process boundaries or compare state across time. That boundary is easy to blur because the same authored topo feeds both runtime execution and saved evidence, so this README keeps the package's job explicit.
+
+The four-role story is:
+
+- author with core;
+- resolve to the topography;
+- render with surfaces;
+- govern with Warden.
+
+This is not a private helper package. The Trails operator app consumes Topography for compile, validate, run, survey, topo history, and Wayfind support. `@ontrails/warden` consumes it for drift detection and topo-aware governance rules. `apps/trails-demo` consumes it as the example app's governance proof. Regrade's contract suite also derives TopoGraph evidence through it. Those independent consumers make the package boundary worth documenting directly.
+
+## What it owns
+
+- deterministic TopoGraph generation from an established topo
+- deterministic app-partitioned workspace views from Config-owned app identity
+  and app-local locks, with completeness, binding, freshness, collection-edge,
+  and unowned-lock evidence kept outside the canonical hash
+- structured example and field-override provenance derivation for TopoGraph entries
+- stable hashing for CI drift detection
+- semantic diffing between two TopoGraphs
+- file I/O helpers for app-root `trails.lock` plus legacy artifact-family readers
+- the topo-store: queryable persistence of the resolved topo graph in the shared
+  `trails.db` in the per-user Trails state store, including snapshots, pinning,
+  history, and read-only query accessors (relocated from `@ontrails/core` per
+  ADR-0042)
+- Wayfind graph-read trails and helpers over saved Topography artifacts,
+  including artifact loading, provenance envelopes, typed entity filters,
+  relation traversal, error facts, adapter facts, and explicit graph diffs
+
+`@ontrails/topography` is the durable graph substrate for Trails. Generic `trails-db` plumbing (read/write SQLite handles, subsystem schema management, derived paths) stays in `@ontrails/core` so other subsystems (tracing, signals) can share it without depending on Topography.
+
+## Usage
+
+```typescript
+import {
+  deriveTopoGraph,
+  deriveTopoGraphDiff,
+  deriveTopoGraphHash,
+  writeTrailsLock,
+} from '@ontrails/topography';
+
+const topoGraph = deriveTopoGraph(graph);
+const hash = deriveTopoGraphHash(topoGraph);
+
+await writeTrailsLock({
+  scope: { app: 'demo' },
+  summary: { entities: 0, resources: 0, signals: 0, trails: 1 },
+  topoGraph,
+  topoGraphHash: hash,
+  version: 5,
+});
+
+// Later, after changes:
+const nextTopoGraph = deriveTopoGraph(graph);
+const diff = deriveTopoGraphDiff(topoGraph, nextTopoGraph);
+
+if (diff.hasBreaking) {
+  console.error('Breaking changes:', diff.breaking);
+}
+```
+
+Configured workspaces name apps through `@ontrails/config`. Topography consumes that static identity and reads exactly those app-root locks; its bounded lock census supplies coaching evidence but never discovers additional app identity:
+
+```typescript
+import { readTrailsProjectIdentity } from '@ontrails/config';
+import { deriveWorkspaceView } from '@ontrails/topography';
+
+const projectRoot = process.cwd();
+const identity = await readTrailsProjectIdentity({
+  boundaryDir: projectRoot,
+  startDir: projectRoot,
+});
+const view = await deriveWorkspaceView({ identity });
+
+if (view.evidence.configuredCompleteness === 'partial') {
+  console.error(view.evidence.apps);
+}
+for (const unowned of view.evidence.unownedLocks) {
+  console.warn(unowned.path, unowned.coaching);
+}
+```
+
+`workspaceViewHash` exists only for a complete, correctly bound configured app set. It hashes the schema version, sorted app IDs and project-relative roots, app graph hashes, and collision facts. Selected scope, absolute checkout location, lock paths, freshness, collection skips, and unowned-lock evidence do not affect it. Passing `currentAppGraphHashes` proves `fresh` or `stale` state; without live evidence, saved graphs report freshness as `unknown`.
+
+`deriveTopoGraph()` rejects draft-contaminated topos. Only established state can be serialized into the committed artifacts.
+
+## File outputs
+
+The normal exported artifact is:
+
+- `trails.lock` — committed resolved truth at the root of one lock-owning app.
+  It embeds the serialized TopoGraph plus the hash and summary needed for drift
+  detection. A configured workspace has one such file per configured app and no
+  workspace-root aggregate lock, unless the root itself is a configured app.
+
+`trails compile` writes it from the current topo. `trails validate` and `@ontrails/warden` use the lockfile helpers here to detect drift.
+
+Compatibility helpers still read the previous `.trails/trails.lock` plus `.trails/topo.lock` artifact family during the migration window. New writes should use `writeTrailsLock()`.
+
+## API
+
+| Export | What it does |
+| --- | --- |
+| `deriveTopoGraph(topo)` | Deterministic TopoGraph of every established trail, signal, resource, and entity |
+| `deriveActivationGraph(topoGraph)` | Static activation overview for trails, signals, and activation sources in a TopoGraph |
+| `deriveDeclaredTrailActivation(entry)` | Trail-local activation report from a resolved TopoGraph entry |
+| `deriveSignalActivationRelations(topoGraph)` | Signal-local activation relations for source and consumer navigation |
+| `deriveTopoGraphHash(topoGraph)` | Stable SHA-256 hash of the TopoGraph |
+| `deriveWorkspaceView(options)` | Config-fed app-partitioned saved graph view with separate observation evidence |
+| `deriveTopoGraphDiff(prev, curr)` | Semantic diff with `breaking`, `warning`, and `info` classifications |
+| `writeTrailsLock(lock, options?)` | Write an app-root `trails.lock` envelope |
+| `readTrailsLock(options?)` | Read an app-root `trails.lock` envelope |
+| `readTopoGraph(options?)` | Read a TopoGraph from v4 `trails.lock` or legacy `topo.lock` |
+| `writeTopoGraph(topoGraph, options?)` | Write legacy `topo.lock` for explicit migration/testing paths |
+| `writeLockManifest(manifest, options?)` | Write legacy `trails.lock` as a v3 manifest |
+| `readLockManifest(options?)` | Read v3 manifests, deriving v4 locks back to v3 for compatibility |
+| `createTopoStore(options?)` | Read-only query interface over the persisted topo state in the Trails state-store `trails.db` |
+| `createMockTopoStore(seed?)` | Seeded in-memory mock for tests that need a `ReadOnlyTopoStore` |
+| `topoStore` | Read-only `resource()` wrapper around `createTopoStore`, suitable for `resources: [...]` |
+| `createTopoSnapshot(topo, options?)` | Persist a new topo snapshot row plus its denormalized derived facts |
+| `listTopoSnapshots(options?)` | List historical topo snapshots (filterable by pinned status) |
+| `pinTopoSnapshot(id, name, options?)` / `unpinTopoSnapshot(nameOrId, options?)` | Manage human-named pins |
+
+## Wayfind graph reads
+
+Wayfind remains the product, trail-id, CLI, and MCP brand for graph navigation. The package boundary is Topography: there is no `@ontrails/wayfinder` compatibility package. Programmatic consumers should import the Wayfind APIs from `@ontrails/topography`:
+
+```typescript
+import {
+  loadWayfinderArtifacts,
+  wayfindContractTrail,
+  wayfindOverviewTrail,
+  wayfinderTopo,
+} from '@ontrails/topography';
+```
+
+The Wayfind catalog is cold and deterministic. Graph queries read the selected app root's `trails.lock` and topo-store records; adapter queries read `@ontrails/adapter-kit` package and conformance evidence. They do not boot apps, resolve resources, reach the network, or mutate local state.
+
+| Export | What it does |
+| --- | --- |
+| `wayfinderTopo` | Internal topo containing the reusable `wayfind.*` graph-read trails |
+| `wayfindOverviewTrail` / `wayfindSearchTrail` | Summarize and search saved graph facts |
+| `wayfindTrailsTrail` / `wayfindEntitiesTrail` / `wayfindResourcesTrail` / `wayfindSignalsTrail` | List typed graph populations with filters |
+| `wayfindSurfacesTrail` / `wayfindTrailheadsTrail` | Inspect saved surface and trailhead membership facts |
+| `wayfindVersionsTrail` / `wayfindExamplesTrail` | Inspect saved version and example facts without executing trails |
+| `wayfindErrorsTrail` / `wayfindAdaptersTrail` / `wayfindOverlayTrail` | Inspect error facts, adapter evidence, and namespaced overlays |
+| `wayfindDescribeTrail` / `wayfindContractTrail` | Inspect one saved entity or trail contract |
+| `wayfindNearbyTrail` / `wayfindImpactTrail` | Traverse typed relation edges around saved graph entities |
+| `wayfindDiffTrail` | Compare two explicit saved TopoGraph baselines as a low-level artifact query |
+| `loadWayfinderArtifacts` | Load lock, TopoGraph, and topo-store evidence with drift status |
+| `createWayfinderGraphEntityPredicate` / `filterWayfinderEntityRefs` | Reuse the typed Wayfind entity filter kit |
+
+Wayfind trails are internal by default. Surface hosts expose selected query trails deliberately, usually by exact trail ID for operator tooling. The Trails operator CLI preserves the existing `trails wayfind` grammar and adds Config-owned project/app selection around saved navigation and semantic diff. Topography continues to own artifact loading, app-partitioned workspace derivation, and graph comparison; it does not interpret `--app`. The operator MCP surface preserves the selected direct `wayfind.*` tools through that same project-aware command boundary.
+
+### Operator File Outline
+
+File outline is an operator capability, not a public Topography query trail. Use `trails wayfind file <file> --outline` for a compact map of authored trail and app declarations, surface membership, saved graph matches, and diagnostics. Add `--source` when the inspection also needs import, export, and declaration rows. The operator parses the explicit file through `@ontrails/source` and reconciles trail IDs with saved Topography artifacts. Missing artifacts are diagnostics, not hard failures, so outline remains useful in a fresh checkout or during repair work.
+
+### Backend Support Subpath
+
+Direct shared database helper APIs are public, but they are backend-support APIs rather than root graph contracts. Import them from `@ontrails/topography/backend-support`:
+
+```typescript
+import {
+  countPinnedSnapshots,
+  countPrunableSnapshots,
+  countTopoSnapshots,
+  createStoredTopoSnapshot,
+  getStoredTopoExport,
+  pruneUnpinnedSnapshots,
+} from '@ontrails/topography/backend-support';
+```
+
+This subpath owns lower-level snapshot counters, pruning helpers, and direct DB-handle variants for callers that already hold an open `trails.db` handle.
+
+## Breaking change detection
+
+The diff classifies every change by severity:
+
+| Change | Severity |
+| --- | --- |
+| Trail removed | breaking |
+| Required input field added | breaking |
+| Input or output field removed | breaking |
+| Output field type changed | breaking |
+| CLI path changed | breaking |
+| Safety property changed | warning |
+| Trail deprecated | warning |
+| Compositions changed | warning |
+| Declared resources changed | warning |
+| Resource removed | breaking |
+| Trail added | info |
+| Resource added | info |
+| Optional input field added | info |
+| Output field added | info |
+
+Because CLI paths are now full hierarchical command paths, command-tree changes are reflected directly in the semantic diff.
+
+## Drift detection with warden
+
+```typescript
+import { deriveTopoGraph, deriveTopoGraphHash, readTrailsLock } from '@ontrails/topography';
+
+const current = deriveTopoGraphHash(deriveTopoGraph(graph));
+const committed = await readTrailsLock();
+
+if (committed?.topoGraphHash !== current) {
+  // lock file is stale -- topo has changed
+}
+```
+
+The `@ontrails/warden` package wraps this into `checkDrift()` with CI-friendly reporting.
+
+## Installation
+
+These commands target stable `0.2.0`. Run them after that version is published to npm.
+
+```bash
+bun add --exact -d @ontrails/topography@0.2.0
+```

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@ontrails/topography",
+  "version": "0.2.0",
+  "description": "Durable graph substrate for Trails: deterministic TopoGraphs, lockfile helpers, and semantic diffing.",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/outfitter-dev/trails.git",
+    "directory": "packages/topography"
+  },
+  "files": [
+    "src/**/*.ts",
+    "!src/**/__tests__/**",
+    "!src/**/*.test.ts",
+    "!src/**/*.test-d.ts",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts",
+    "./backend-support": "./src/backend-support.ts",
+    "./package.json": "./package.json"
+  },
+  "scripts": {
+    "build": "tsc -b",
+    "test": "bun test",
+    "typecheck": "tsc --noEmit",
+    "lint": "oxlint ./src",
+    "clean": "rm -rf dist *.tsbuildinfo"
+  },
+  "dependencies": {
+    "@ontrails/adapter-kit": "^0.2.0",
+    "@ontrails/config": "^0.2.0",
+    "@ontrails/source": "^0.2.0"
+  },
+  "peerDependencies": {
+    "@ontrails/core": "^0.2.0",
+    "zod": "^4.3.5"
+  }
+}

package/src/activation-report.ts

@@ -0,0 +1,385 @@
+import type {
+  ActivationEntry,
+  ActivationSource,
+  ActivationSourceFacts,
+  AnyTrail,
+  Topo,
+} from '@ontrails/core';
+import {
+  activationSourceKey,
+  deriveActivationSourceFacts,
+} from '@ontrails/core';
+
+export interface ActivationChainReport {
+  readonly consumer: string;
+  readonly producer: string;
+  readonly signal: string;
+}
+
+type JsonSchemaReport = Readonly<Record<string, unknown>>;
+
+export interface ActivationSourceReport extends ActivationSourceFacts {
+  readonly cron?: string | undefined;
+  readonly hasParse?: true | undefined;
+  readonly hasPayloadSchema?: true | undefined;
+  readonly hasVerify?: true | undefined;
+  readonly id: string;
+  readonly input?: unknown;
+  readonly inputSchema?: JsonSchemaReport | undefined;
+  readonly kind: string;
+  readonly key: string;
+  readonly meta?: Readonly<Record<string, unknown>> | undefined;
+  readonly method?: string | undefined;
+  readonly parseOutputSchema?: JsonSchemaReport | undefined;
+  readonly path?: string | undefined;
+  readonly payloadSchema?: JsonSchemaReport | undefined;
+  readonly timezone?: string | undefined;
+}
+
+export interface ActivationEdgeReport extends Readonly<
+  Record<string, unknown>
+> {
+  readonly hasWhere: boolean;
+  readonly sourceId: string;
+  readonly sourceKey: string;
+  readonly sourceKind: string;
+  readonly trailId: string;
+  readonly where?: { readonly predicate: true } | undefined;
+}
+
+export interface SignalActivationRelations {
+  readonly consumers: readonly string[];
+  readonly producers: readonly string[];
+}
+
+export interface TrailActivationReport {
+  readonly activatedBy: readonly string[];
+  readonly activates: readonly string[];
+  readonly chains: readonly ActivationChainReport[];
+  readonly edges: readonly ActivationEdgeReport[];
+  readonly fires: readonly string[];
+  readonly on: readonly string[];
+  readonly sources: readonly ActivationSourceReport[];
+}
+
+export interface ActivationOverviewReport {
+  readonly chainCount: number;
+  readonly chains: readonly ActivationChainReport[];
+  readonly edgeCount: number;
+  readonly edges: readonly ActivationEdgeReport[];
+  readonly signalIds: readonly string[];
+  readonly sourceCount: number;
+  readonly sourceKeys: readonly string[];
+  readonly trailIds: readonly string[];
+}
+
+export interface ActivationGraphReport {
+  readonly overview: ActivationOverviewReport;
+  readonly signals: ReadonlyMap<string, SignalActivationRelations>;
+  readonly sources: ReadonlyMap<string, ActivationSourceReport>;
+  readonly trails: ReadonlyMap<string, TrailActivationReport>;
+}
+
+interface MutableSignalRelations {
+  readonly consumers: Set<string>;
+  readonly producers: Set<string>;
+}
+
+interface MutableTrailActivation {
+  readonly activatedBy: Set<string>;
+  readonly activates: Set<string>;
+  readonly chains: ActivationChainReport[];
+  readonly fires: readonly string[];
+  readonly on: readonly string[];
+}
+
+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 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') {
+    const sorted: Record<string, unknown> = {};
+    for (const key of Object.keys(value).toSorted()) {
+      const next = (value as Record<string, unknown>)[key];
+      sorted[key] = next === undefined ? '[Undefined]' : canonicalize(next);
+    }
+    return sorted;
+  }
+  return canonicalLeaf(value);
+};
+
+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 compareChains = (
+  a: ActivationChainReport,
+  b: ActivationChainReport
+): number =>
+  a.producer.localeCompare(b.producer) ||
+  a.signal.localeCompare(b.signal) ||
+  a.consumer.localeCompare(b.consumer);
+
+const sortedUnique = (values: Iterable<string>): readonly string[] =>
+  [...new Set(values)].toSorted();
+
+const deriveActivationSource = (
+  source: ActivationSource
+): ActivationSourceReport =>
+  deriveActivationSourceFacts(source) as ActivationSourceReport;
+
+const deriveActivationEdge = (
+  trailId: string,
+  activation: ActivationEntry
+): ActivationEdgeReport => {
+  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 ActivationEdgeReport;
+};
+
+const collectActivationSourceCatalog = (
+  trails: readonly AnyTrail[]
+): readonly ActivationSourceReport[] => {
+  const sources = new Map<string, ActivationSourceReport>();
+  for (const trail of trails) {
+    for (const activation of trail.activationSources) {
+      const derived = deriveActivationSource(activation.source);
+      sources.set(derived.key, derived);
+    }
+  }
+  return [...sources.values()].toSorted((a, b) => a.key.localeCompare(b.key));
+};
+
+const collectActivationEdges = (
+  trails: readonly AnyTrail[]
+): readonly ActivationEdgeReport[] => {
+  const edges = new Map<string, ActivationEdgeReport>();
+  for (const trail of trails) {
+    for (const activation of trail.activationSources) {
+      const edge = deriveActivationEdge(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 getSignalRelations = (
+  relations: Map<string, MutableSignalRelations>,
+  signalId: string
+): MutableSignalRelations => {
+  const existing = relations.get(signalId);
+  if (existing !== undefined) {
+    return existing;
+  }
+
+  const created = {
+    consumers: new Set<string>(),
+    producers: new Set<string>(),
+  };
+  relations.set(signalId, created);
+  return created;
+};
+
+const getTrailActivation = (
+  trails: Map<string, MutableTrailActivation>,
+  trail: AnyTrail
+): MutableTrailActivation => {
+  const existing = trails.get(trail.id);
+  if (existing !== undefined) {
+    return existing;
+  }
+
+  const created = {
+    activatedBy: new Set<string>(),
+    activates: new Set<string>(),
+    chains: [],
+    fires: sortedUnique(trail.fires),
+    on: sortedUnique(trail.on),
+  };
+  trails.set(trail.id, created);
+  return created;
+};
+
+export const deriveDeclaredTrailActivation = (
+  trail: AnyTrail
+): TrailActivationReport => {
+  const sources = collectActivationSourceCatalog([trail]);
+  return {
+    activatedBy: [],
+    activates: [],
+    chains: [],
+    edges: collectActivationEdges([trail]),
+    fires: sortedUnique(trail.fires),
+    on: sortedUnique(trail.on),
+    sources,
+  };
+};
+
+export const deriveSignalActivationRelations = (
+  app: Topo,
+  signalId: string
+): SignalActivationRelations => {
+  const consumers: string[] = [];
+  const producers: string[] = [];
+
+  for (const trail of app.list()) {
+    if (trail.fires.includes(signalId)) {
+      producers.push(trail.id);
+    }
+    if (trail.on.includes(signalId)) {
+      consumers.push(trail.id);
+    }
+  }
+
+  return {
+    consumers: sortedUnique(consumers),
+    producers: sortedUnique(producers),
+  };
+};
+
+export const deriveActivationGraph = (app: Topo): ActivationGraphReport => {
+  const signalRelations = new Map<string, MutableSignalRelations>();
+  const trailActivations = new Map<string, MutableTrailActivation>();
+  const trails = app.list();
+  const sources = collectActivationSourceCatalog(trails);
+  const edges = collectActivationEdges(trails);
+
+  for (const signal of app.listSignals()) {
+    getSignalRelations(signalRelations, signal.id);
+  }
+
+  for (const trail of trails) {
+    const trailActivation = getTrailActivation(trailActivations, trail);
+    for (const signalId of trailActivation.fires) {
+      getSignalRelations(signalRelations, signalId).producers.add(trail.id);
+    }
+    for (const signalId of trailActivation.on) {
+      getSignalRelations(signalRelations, signalId).consumers.add(trail.id);
+    }
+  }
+
+  const chains: ActivationChainReport[] = [];
+  for (const [signal, related] of signalRelations) {
+    for (const producer of related.producers) {
+      const producerActivation = trailActivations.get(producer);
+      for (const consumer of related.consumers) {
+        const chain = { consumer, producer, signal };
+        chains.push(chain);
+        producerActivation?.activates.add(consumer);
+        producerActivation?.chains.push(chain);
+        const consumerActivation = trailActivations.get(consumer);
+        consumerActivation?.activatedBy.add(producer);
+        if (consumerActivation !== producerActivation) {
+          consumerActivation?.chains.push(chain);
+        }
+      }
+    }
+  }
+
+  chains.sort(compareChains);
+  const activeTrailIds = sortedUnique([
+    ...[...trailActivations.entries()].flatMap(([trailId, trail]) =>
+      trail.fires.length > 0 || trail.on.length > 0
+        ? [trailId, ...trail.activatedBy, ...trail.activates]
+        : []
+    ),
+    ...edges.map((edge) => edge.trailId),
+  ]);
+
+  return {
+    overview: {
+      chainCount: chains.length,
+      chains,
+      edgeCount: edges.length,
+      edges,
+      signalIds: [...signalRelations.keys()].toSorted(),
+      sourceCount: sources.length,
+      sourceKeys: sources.map((source) => source.key),
+      trailIds: activeTrailIds,
+    },
+    signals: new Map(
+      [...signalRelations.entries()].map(([id, relations]) => [
+        id,
+        {
+          consumers: sortedUnique(relations.consumers),
+          producers: sortedUnique(relations.producers),
+        },
+      ])
+    ),
+    sources: new Map(sources.map((source) => [source.key, source])),
+    trails: new Map(
+      [...trailActivations.entries()].map(([id, activation]) => [
+        id,
+        {
+          activatedBy: sortedUnique(activation.activatedBy),
+          activates: sortedUnique(activation.activates),
+          chains: activation.chains.toSorted(compareChains),
+          edges: edges.filter((edge) => edge.trailId === id),
+          fires: activation.fires,
+          on: activation.on,
+          sources: sources.filter((source) =>
+            edges.some(
+              (edge) => edge.trailId === id && edge.sourceKey === source.key
+            )
+          ),
+        },
+      ])
+    ),
+  };
+};

package/src/backend-support.ts

@@ -0,0 +1,11 @@
+export {
+  countPinnedSnapshots,
+  countPrunableSnapshots,
+  countTopoSnapshots,
+  pruneUnpinnedSnapshots,
+} from './internal/topo-snapshots.js';
+export {
+  createTopoSnapshot as createStoredTopoSnapshot,
+  getStoredTopoExport,
+} from './internal/topo-store.js';
+export type { StoredTopoExport } from './internal/topo-store.js';