@ontrails/topography 0.2.0

package/src/forces.ts

@@ -0,0 +1,125 @@
+import type {
+  DiffEntry,
+  TopoGraph,
+  TopoGraphEntry,
+  TopoGraphForceEntry,
+} from './types.js';
+
+export interface TopoGraphForceOptions {
+  readonly acceptedAt?: string | undefined;
+  readonly reason?: string | undefined;
+}
+
+type ForceableDiffEntry = DiffEntry & {
+  readonly kind: TopoGraphForceEntry['kind'];
+};
+
+const isForceableDiffEntry = (diff: DiffEntry): diff is ForceableDiffEntry =>
+  diff.kind !== 'trailhead';
+
+const toForceEntry = (
+  diff: ForceableDiffEntry,
+  detail: string,
+  acceptedAt: string,
+  reason?: string | undefined
+): TopoGraphForceEntry => ({
+  acceptedAt,
+  change: diff.change === 'removed' ? 'removed' : 'modified',
+  detail,
+  id: diff.id,
+  kind: diff.kind,
+  ...(reason === undefined ? {} : { reason }),
+  severity: 'breaking',
+  source: 'trails compile --force',
+});
+
+export const deriveTopoGraphForceEntries = (
+  diff: DiffEntry,
+  options?: TopoGraphForceOptions
+): readonly TopoGraphForceEntry[] => {
+  if (diff.severity !== 'breaking' || !isForceableDiffEntry(diff)) {
+    return [];
+  }
+
+  const acceptedAt = options?.acceptedAt ?? new Date().toISOString();
+  return diff.details.map((detail) =>
+    toForceEntry(diff, detail, acceptedAt, options?.reason)
+  );
+};
+
+export const annotateTopoGraphForces = (
+  graph: TopoGraph,
+  breaking: readonly DiffEntry[],
+  options?: TopoGraphForceOptions
+): TopoGraph => {
+  if (breaking.length === 0) {
+    return graph;
+  }
+
+  const removedForces = breaking
+    .filter((entry) => entry.change === 'removed')
+    .flatMap((entry) => deriveTopoGraphForceEntries(entry, options));
+  const byId = new Map(
+    breaking
+      .filter((entry) => entry.change !== 'removed')
+      .map((entry) => [entry.id, entry])
+  );
+  const entries: TopoGraphEntry[] = graph.entries.map((entry) => {
+    const diff = byId.get(entry.id);
+    if (diff === undefined) {
+      return entry;
+    }
+
+    const forces = deriveTopoGraphForceEntries(diff, options);
+    return forces.length === 0
+      ? entry
+      : { ...entry, forces: [...(entry.forces ?? []), ...forces] };
+  });
+
+  return {
+    ...graph,
+    entries,
+    ...(removedForces.length === 0
+      ? {}
+      : { forces: [...(graph.forces ?? []), ...removedForces] }),
+  };
+};
+
+export const carryForwardTopoGraphForces = (
+  previous: TopoGraph,
+  next: TopoGraph
+): TopoGraph => {
+  const previousEntryForces = new Map(
+    previous.entries
+      .filter((entry) => entry.forces !== undefined && entry.forces.length > 0)
+      .map((entry) => [entry.id, entry.forces ?? []])
+  );
+  const entries = next.entries.map((entry) => {
+    const carriedForces = previousEntryForces.get(entry.id);
+    if (carriedForces === undefined || carriedForces.length === 0) {
+      return entry;
+    }
+    return {
+      ...entry,
+      forces: [...carriedForces, ...(entry.forces ?? [])],
+    };
+  });
+  return {
+    ...next,
+    entries,
+    ...(previous.forces === undefined || previous.forces.length === 0
+      ? {}
+      : { forces: [...previous.forces, ...(next.forces ?? [])] }),
+  };
+};
+
+export const stripTopoGraphForces = (graph: TopoGraph): TopoGraph => {
+  const { forces: _graphForces, ...rest } = graph;
+  return {
+    ...rest,
+    entries: graph.entries.map((entry) => {
+      const { forces: _entryForces, ...entryRest } = entry;
+      return entryRest;
+    }),
+  };
+};

package/src/hash.ts

@@ -0,0 +1,55 @@
+/**
+ * SHA-256 hashing for topo graphs.
+ *
+ * Uses Bun.CryptoHasher for native hashing.
+ */
+
+import type { TopoGraph } from './types.js';
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Recursively sort all object keys for deterministic JSON serialization.
+ * Arrays preserve order; primitives pass through.
+ */
+const canonicalize = (value: unknown): unknown => {
+  if (Array.isArray(value)) {
+    return value.map(canonicalize);
+  }
+  if (value !== null && typeof value === 'object') {
+    const sorted: Record<string, unknown> = {};
+    for (const key of Object.keys(value).toSorted()) {
+      sorted[key] = canonicalize((value as Record<string, unknown>)[key]);
+    }
+    return sorted;
+  }
+  return value;
+};
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Compute a SHA-256 hash of a topo graph.
+ *
+ * The `generatedAt` field is excluded so that identical topos always
+ * produce the same hash regardless of when they were generated.
+ */
+export const deriveStableHash = (value: unknown): string => {
+  const canonical = canonicalize(value);
+  const json = JSON.stringify(canonical);
+
+  const hasher = new Bun.CryptoHasher('sha256');
+  hasher.update(json);
+  return hasher.digest('hex');
+};
+
+export const deriveTopoGraphHash = (topoGraph: TopoGraph): string => {
+  // Strip generatedAt before hashing
+  const { generatedAt: _unused, ...rest } = topoGraph;
+
+  return deriveStableHash(rest);
+};

package/src/index.ts

@@ -0,0 +1,273 @@
+// `@ontrails/topography` owns durable graph artifacts derived from the
+// resolved graph (per ADR-0042). Wayfind reads those artifacts through
+// graph-read trails exported from this package.
+
+// Derivation
+export { deriveTopoGraph } from './derive.js';
+export {
+  deriveActivationGraph,
+  deriveDeclaredTrailActivation,
+  deriveSignalActivationRelations,
+} from './activation-report.js';
+export type {
+  ActivationChainReport,
+  ActivationEdgeReport,
+  ActivationGraphReport,
+  ActivationOverviewReport,
+  ActivationSourceReport,
+  SignalActivationRelations,
+  TrailActivationReport,
+} from './activation-report.js';
+export { deriveTopoGraphHash } from './hash.js';
+export {
+  deriveWorkspaceView,
+  WORKSPACE_VIEW_SCHEMA_VERSION,
+} from './workspace-view.js';
+export type {
+  DeriveWorkspaceViewOptions,
+  UnownedWorkspaceLockObservation,
+  WorkspaceAppLockBinding,
+  WorkspaceAppLockFreshness,
+  WorkspaceAppLockObservation,
+  WorkspaceAppLockStatus,
+  WorkspaceView,
+  WorkspaceViewApp,
+  WorkspaceViewCollectionSkip,
+  WorkspaceViewCollision,
+  WorkspaceViewContent,
+  WorkspaceViewEvidence,
+} from './workspace-view.js';
+export { collectTopoGraphOverlays } from './overlays.js';
+export { deriveSourceFingerprint } from './source-fingerprint.js';
+export { deriveTopoGraphDiff } from './diff.js';
+export {
+  annotateTopoGraphForces,
+  carryForwardTopoGraphForces,
+  deriveTopoGraphForceEntries,
+  stripTopoGraphForces,
+} from './forces.js';
+export type { TopoGraphForceOptions } from './forces.js';
+export {
+  collectTopoGraphVersionMarkers,
+  deriveTopoGraphVersionMarkerRecords,
+  resolveTopoGraphVersionReference,
+} from './versioning.js';
+export type {
+  TopoGraphVersionMarkerRecord,
+  TopoGraphVersionMarkerResolution,
+} from './versioning.js';
+
+// File I/O
+export {
+  writeTopoGraph,
+  readTopoGraph,
+  isTopoArtifactRegenerationError,
+  writeLockManifest,
+  readLockManifest,
+  writeTrailsLock,
+  readTrailsLock,
+  readWorkspaceTopoMetadata,
+  readWorkspaceTrailIndex,
+  readWorkspaceLock,
+} from './io.js';
+export {
+  lockManifestArtifactSchema,
+  lockManifestSchema,
+  lockManifestSummarySchema,
+  LOCK_MANIFEST_SCHEMA_VERSION,
+  TOPO_GRAPH_SCHEMA_VERSION,
+  TRAILS_LOCK_SCHEMA_VERSION,
+  trailsLockSchema,
+  topoGraphTrailheadEntrySchema,
+  topoGraphLibraryDerivedSchema,
+  workspaceTopoMetadataSchema,
+  workspaceTrailCollisionSchema,
+  workspaceTrailEntrySchema,
+  workspaceTrailIndexSchema,
+} from './types.js';
+
+// Types
+export type {
+  TopoGraph,
+  TopoGraphEntry,
+  TopoGraphTrailheadEntry,
+  TopoGraphForceEntry,
+  TopoGraphFieldOverride,
+  TopoGraphFieldOverrideKey,
+  TopoGraphLibraryCollision,
+  TopoGraphLibraryExclusion,
+  TopoGraphLibraryExclusionReason,
+  TopoGraphLibraryExport,
+  TopoGraphLibraryExportSource,
+  TopoGraphLibraryDerived,
+  TopoGraphLayerReference,
+  TopoGraphOverlayRegistration,
+  TopoGraphOverlays,
+  DeriveTopoGraphOptions,
+  TopoGraphVersionDetour,
+  TopoGraphVersionEntry,
+  LockManifest,
+  LockManifestArtifact,
+  LockManifestSummary,
+  TrailsLock,
+  WorkspaceTopoMetadata,
+  WorkspaceTrailCollision,
+  WorkspaceTrailEntry,
+  WorkspaceTrailIndex,
+  DiffEntry,
+  DiffResult,
+  JsonSchema,
+  TopoGraphEntityReference,
+  TopoGraphActivationEdge,
+  TopoGraphActivationEntry,
+  TopoGraphActivationSource,
+  WriteOptions,
+  ReadOptions,
+} from './types.js';
+
+// Topo-store public API. Persistence layer for the resolved topo graph; relies
+// on `@ontrails/core` for primitive types and the generic `trails-db` helpers.
+// See ADR-0042 for the core/topography boundary doctrine.
+export {
+  createTopoSnapshot,
+  createMockTopoStore,
+  createTopoStore,
+  listTopoSnapshots,
+  pinTopoSnapshot,
+  topoStore,
+  TOPO_STORE_SCHEMA_VERSION,
+  unpinTopoSnapshot,
+} from './topo-store.js';
+export type {
+  CreateTopoSnapshotInput,
+  ListTopoSnapshotsOptions,
+  MockTopoStoreSeed,
+  ReadOnlyTopoStore,
+  TopoSnapshot,
+  TopoStoreActivationContextRecord,
+  TopoStoreEntityRecord,
+  TopoStoreEntryKind,
+  TopoStoreExportRecord,
+  TopoStoreResourceRecord,
+  TopoStoreRef,
+  TopoStoreSignalDetailRecord,
+  TopoStoreSignalRecord,
+  TopoStoreSurfaceDerivedRecord,
+  TopoStoreTopoGraphEntryRecord,
+  TopoStoreTopoGraphRecord,
+  TopoStoreTrailDetailRecord,
+  TopoStoreTrailRecord,
+} from './topo-store.js';
+
+// Wayfind graph-read APIs. The product, trail IDs, and public type names remain
+// Wayfinder/wayfind even though the package owner is now Topography.
+export { deriveTrailErrorFacts } from './wayfind/error-facts.js';
+export type {
+  TrailErrorEvidenceInput,
+  TrailErrorFact,
+  TrailErrorFactKind,
+  TrailErrorFactProvenance,
+  TrailErrorFacts,
+  TrailErrorFactsCompleteness,
+  TrailErrorFactsOptions,
+  TrailErrorTaxonomyFacts,
+} from './wayfind/error-facts.js';
+export {
+  createWayfinderEntityPredicate,
+  createWayfinderFilterContext,
+  createWayfinderGraphEntityPredicate,
+  filterWayfinderEntityRefs,
+  listWayfinderEntityRefs,
+  wayfinderEntityFilterSchema,
+  wayfinderEntityKindSchema,
+  wayfinderIntentSchema,
+} from './wayfind/filters.js';
+export type {
+  WayfinderEntityFilterInput,
+  WayfinderEntityFilters,
+  WayfinderEntityKind,
+  WayfinderEntityRef,
+  WayfinderFilterContext,
+  WayfinderIntent,
+} from './wayfind/filters.js';
+export {
+  loadWayfinderArtifacts,
+  wayfinderTopoGraphSource,
+  wayfinderTopoStoreSource,
+} from './wayfind/loader.js';
+export type {
+  WayfinderArtifactLoad,
+  WayfinderArtifactLoaderOptions,
+  WayfinderTopoStoreLoad,
+} from './wayfind/loader.js';
+export {
+  resolveWayfinderPopulation,
+  resolveWayfinderRelations,
+  wayfinderDriftStatusSchema,
+  wayfinderIncludeSchema,
+  wayfinderNavigationPlanSchema,
+  wayfinderRelationModeSchema,
+  wayfinderResolverSchema,
+  wayfinderSourceModeSchema,
+  wayfinderViewSchema,
+} from './wayfind/navigation.js';
+export type {
+  WayfinderDriftStatus,
+  WayfinderInclude,
+  WayfinderNavigationPlan,
+  WayfinderPopulationInput,
+  WayfinderRelationMode,
+  WayfinderRelationResolver,
+  WayfinderResolvedRelationInput,
+  WayfinderResolvedRelations,
+  WayfinderResolver,
+  WayfinderSourceMode,
+  WayfinderView,
+} from './wayfind/navigation.js';
+export {
+  wayfindAdaptersTrail,
+  wayfindContractTrail,
+  wayfindDescribeTrail,
+  wayfindDiffTrail,
+  wayfindEntitiesTrail,
+  wayfindErrorsTrail,
+  wayfindExamplesTrail,
+  wayfindImpactTrail,
+  wayfindNearbyTrail,
+  wayfindOverlayTrail,
+  wayfindOverviewTrail,
+  wayfindResourcesTrail,
+  wayfindSearchTrail,
+  wayfindSignalsTrail,
+  wayfindSurfacesTrail,
+  wayfindTrailheadsTrail,
+  wayfindTrailsTrail,
+  wayfindVersionsTrail,
+  wayfinderTopo,
+} from './wayfind/queries.js';
+export {
+  wayfinderDriftFromArtifactStatus,
+  wayfinderDriftFromFreshness,
+  wayfinderFact,
+} from './wayfind/provenance.js';
+export type {
+  WayfinderArtifactKind,
+  WayfinderArtifactSource,
+  WayfinderArtifactStatus,
+  WayfinderArtifactStatusFresh,
+  WayfinderArtifactStatusMissing,
+  WayfinderArtifactStatusSchemaVersionDrift,
+  WayfinderArtifactStatusStale,
+  WayfinderContractRef,
+  WayfinderFact,
+  WayfinderFactCategory,
+  WayfinderFactDrift,
+  WayfinderFactDriftStatus,
+  WayfinderFactInput,
+  WayfinderFreshness,
+  WayfinderFreshnessFresh,
+  WayfinderFreshnessMissing,
+  WayfinderFreshnessSchemaVersionDrift,
+  WayfinderFreshnessStale,
+  WayfinderStaleReason,
+} from './wayfind/provenance.js';