@glossarist/concept-browser 0.7.50 → 0.7.52

package/src/composables/useSphereProjection.ts

@@ -0,0 +1,125 @@
+/**
+ * Sphere projection + force-layout math for RelationSphere.
+ *
+ * All functions are pure — no Vue, no DOM. The component passes positions in,
+ * gets screen coordinates out. This keeps the math testable and the component
+ * focused on rendering.
+ *
+ * Coordinates: unit sphere (‖p‖ = 1). The "front pole" is (0, 0, 1) — the
+ * focal point of the camera. The simulation runs in 3D and is projected to
+ * 2D with perspective at render time.
+ */
+
+export interface Vec3 {
+  x: number;
+  y: number;
+  z: number;
+}
+
+/** Perspective projection constants — tuned for unit sphere. */
+const FOCAL = 600;
+const Z_OFFSET = 800;
+const SPHERE_R = 360;
+
+/** Slow-fast-slow easing — cubic ease-in-out. */
+export function easeInOutCubic(t: number): number {
+  return t < 0.5 ? 4 * t * t * t : 1 - Math.pow(-2 * t + 2, 3) / 2;
+}
+
+/** Great-circle interpolation between two unit-sphere points. */
+export function slerp(a: Vec3, b: Vec3, t: number): Vec3 {
+  const dot = Math.max(-1, Math.min(1, a.x * b.x + a.y * b.y + a.z * b.z));
+  const omega = Math.acos(dot);
+  if (omega < 0.001) {
+    return {
+      x: a.x + (b.x - a.x) * t,
+      y: a.y + (b.y - a.y) * t,
+      z: a.z + (b.z - a.z) * t,
+    };
+  }
+  const sinO = Math.sin(omega);
+  const wa = Math.sin((1 - t) * omega) / sinO;
+  const wb = Math.sin(t * omega) / sinO;
+  return {
+    x: a.x * wa + b.x * wb,
+    y: a.y * wa + b.y * wb,
+    z: a.z * wa + b.z * wb,
+  };
+}
+
+/**
+ * Initial sphere position by depth band. Focus at (0,0,1); 1°/2°/3° neighbors
+ * distributed at increasing angular distance from the focus.
+ *
+ * Depth 1 forms an EVEN ring (best spacing for small N). Deeper levels use
+ * the golden-angle offset so they interleave with the previous ring.
+ */
+export function fibonacciSpherePosition(
+  depth: number,
+  idx: number,
+  total: number,
+  jitterSeed: number,
+): Vec3 {
+  if (depth === 0) return { x: 0, y: 0, z: 1 };
+  /* Angular distance from north pole — each ring further out. */
+  const thetaByDepth: Record<number, number> = { 1: 1.15, 2: 1.55, 3: 1.95 };
+  const theta = thetaByDepth[depth] ?? 1.15;
+  const j = (jitterSeed % 7) * 0.008;
+  const t = theta + j;
+  let phi: number;
+  if (depth === 1) {
+    /* Even ring for depth 1 — gives best spread for small N */
+    phi = (idx / Math.max(total, 1)) * Math.PI * 2;
+  } else {
+    /* Golden-angle spiral for deeper rings, offset by depth so rings interleave */
+    phi = (idx * 2.39996 + depth * 1.7 + (jitterSeed % 11) * 0.4) % (Math.PI * 2);
+  }
+  return {
+    x: Math.sin(t) * Math.cos(phi),
+    y: Math.sin(t) * Math.sin(phi),
+    z: Math.cos(t),
+  };
+}
+
+/** 3D unit-sphere point → 2D screen offset from sphere center. */
+export interface Projected {
+  x: number;
+  y: number;
+  scale: number;
+  z: number;
+}
+
+export function project(p: Vec3): Projected {
+  const persp = FOCAL / (Z_OFFSET - p.z * SPHERE_R);
+  return {
+    x: p.x * SPHERE_R * persp,
+    y: -p.y * SPHERE_R * persp,
+    scale: persp,
+    z: p.z,
+  };
+}
+
+/**
+ * Find the point on a rectangle's edge in the direction of an external point.
+ * Used so SVG edge paths start/end on the rim of the card, not its center.
+ */
+export function cardEdge(
+  from: { x: number; y: number },
+  to: { x: number; y: number },
+  w: number,
+  h: number,
+): { x: number; y: number } {
+  const dx = to.x - from.x;
+  const dy = to.y - from.y;
+  const len = Math.sqrt(dx * dx + dy * dy) || 1;
+  const ux = dx / len;
+  const uy = dy / len;
+  const absUx = Math.abs(ux);
+  const absUy = Math.abs(uy);
+  const halfW = w / 2;
+  const halfH = h / 2;
+  const tX = absUx > 0.001 ? halfW / absUx : Infinity;
+  const tY = absUy > 0.001 ? halfH / absUy : Infinity;
+  const t = Math.min(tX, tY);
+  return { x: from.x + ux * t, y: from.y + uy * t };
+}

package/src/config/group-types.ts

@@ -0,0 +1,92 @@
+/**
+ * Dataset group type registry.
+ *
+ * Maps each `DatasetGroupKind` to its semantic metadata. Adding a new kind
+ * is a single entry here + a new renderer component — no edits to existing
+ * components needed (open/closed principle).
+ *
+ * The registry is intentionally pure data — no Vue imports — so it can be
+ * consumed by both the sidebar (compact rendering) and the home page (rich
+ * rendering) without coupling.
+ */
+import type { DatasetGroupKind } from './types';
+
+export interface GroupTypeMeta {
+  /** Discriminator value matching `DatasetGroup.kind`. */
+  kind: DatasetGroupKind;
+  /** Human label for the kind, e.g. "Edition series". */
+  label: string;
+  /** Short description shown in tooltips / section headers. */
+  description: string;
+  /** Icon glyph — used in section headers and breadcrumbs. */
+  glyph: string;
+  /** Whether members have an inherent temporal ordering. */
+  ordered: boolean;
+  /** Whether members have a supersession chain (newer supersedes older). */
+  supersession: boolean;
+  /** Whether members share the same vocabulary identity across editions. */
+  sameVocabulary: boolean;
+}
+
+export const GROUP_TYPES: Record<DatasetGroupKind, GroupTypeMeta> = {
+  lineage: {
+    kind: 'lineage',
+    label: 'Edition series',
+    description: 'Same vocabulary, different editions over time',
+    glyph: '⏳',
+    ordered: true,
+    supersession: true,
+    sameVocabulary: true,
+  },
+  topic: {
+    kind: 'topic',
+    label: 'Topic bundle',
+    description: 'Different vocabularies covering the same subject',
+    glyph: '◆',
+    ordered: false,
+    supersession: false,
+    sameVocabulary: false,
+  },
+  family: {
+    kind: 'family',
+    label: 'Publication family',
+    description: 'Related vocabularies from the same publisher or program',
+    glyph: '✦',
+    ordered: false,
+    supersession: false,
+    sameVocabulary: false,
+  },
+  collection: {
+    kind: 'collection',
+    label: 'Curated collection',
+    description: 'Hand-picked bundle of datasets for a specific audience',
+    glyph: '❖',
+    ordered: false,
+    supersession: false,
+    sameVocabulary: false,
+  },
+  default: {
+    kind: 'default',
+    label: 'Datasets',
+    description: 'Grouped datasets',
+    glyph: '▸',
+    ordered: false,
+    supersession: false,
+    sameVocabulary: false,
+  },
+};
+
+/**
+ * Normalize a group config (which may use the legacy `series: true` flag or
+ * the new `kind` discriminator) into a canonical `kind`. Pure function.
+ */
+export function resolveGroupKind(group: { kind?: DatasetGroupKind; series?: boolean }): DatasetGroupKind {
+  if (group.kind) return group.kind;
+  if (group.series) return 'lineage';
+  return 'default';
+}
+
+/** Lookup the metadata for any group, using `resolveGroupKind` for compat. */
+export function groupTypeMeta(group: { kind?: DatasetGroupKind; series?: boolean }): GroupTypeMeta {
+  return GROUP_TYPES[resolveGroupKind(group)];
+}

package/src/config/types.ts

@@ -82,6 +82,8 @@ export interface RoutingEntry {
 
 // === Dataset ===
 
+export type DatasetColorSpec = string | { light: string; dark: string };
+
 export interface DatasetConfig {
   id: string;
   uri: string;
@@ -92,7 +94,13 @@ export interface DatasetConfig {
   title: string;
   description?: string;
   owner?: string;
-  color?: string;
+  /**
+   * Dataset accent color. Accepts either a single hex (applied to both
+   * light and dark modes) or an explicit `{ light, dark }` pair.
+   * Per-deployment overrides via `site-config.json` `colors.dataset[id]`
+   * take precedence.
+   */
+  color?: DatasetColorSpec;
   tags?: string[];
   languageOrder?: string[];
   ref?: string;
@@ -142,17 +150,86 @@ export interface PageConfig {
 
 // === Dataset Groups ===
 
+/**
+ * Kind of dataset group. Determines how the group is rendered in the sidebar
+ * and home page, and what semantic relationships between members are assumed.
+ *
+ * - `lineage` — same vocabulary, different editions (e.g. VIML 1968/2000/2013/2022).
+ *   Members have temporal ordering and a supersession chain. Rendered as a
+ *   timeline with year badges and "current" markers.
+ *
+ * - `topic` — different vocabularies on the same subject (e.g. three SDOs
+ *   publishing "intelligent transport systems" terminology). Members may
+ *   overlap in concepts but have no temporal ordering. Rendered as a card
+ *   grid with overlap indicators.
+ *
+ * - `family` — related vocabularies from the same publisher or program
+ *   (e.g. all OIML publications). Hierarchical grouping, no required
+ *   relationships between members. Rendered as a flat list under a labeled
+ *   header.
+ *
+ * - `collection` — curated bundle of datasets (e.g. "Starter pack for new
+ *   metrologists"). Arbitrary selection, often cross-publisher. Rendered as
+ *   a featured card with custom descriptions.
+ *
+ * - `default` (omitted) — backward-compatible flat list. No special
+ *   semantics. Used when no `kind` is specified.
+ *
+ * The registry in `src/config/group-types.ts` maps each kind to its renderer
+ * component, so new kinds can be added without modifying existing code
+ * (open/closed principle).
+ */
+export type DatasetGroupKind = 'lineage' | 'topic' | 'family' | 'collection' | 'default';
+
 export interface DatasetGroup {
   id: string;
   label: string;
   description?: string;
-  color?: string;
+  /**
+   * Group accent color. Same shape as DatasetConfig.color.
+   * Per-deployment overrides via `site-config.json` `colors.group[id]`.
+   */
+  color?: DatasetColorSpec;
   datasets: string[];
   translations?: Record<string, { label?: string; description?: string }>;
+  /**
+   * Discriminator for the group's semantic type and UX. See DatasetGroupKind
+   * for the full list of supported values. Defaults to 'default' (flat list).
+   *
+   * Replaces the older `series?: boolean` flag — use `kind: lineage` instead.
+   */
+  kind?: DatasetGroupKind;
+  /**
+   * For lineage series: the dataset id of the current (newest valid) edition.
+   * If omitted, the newest member by year (or last in `datasets` order) is
+   * used. Setting this explicitly avoids misdetection when only a subset of
+   * editions happen to be loaded.
+   */
+  current?: string;
+  /**
+   * @deprecated Use `kind: 'lineage'` instead. Still respected as a
+   * backward-compat shorthand: `series: true` is treated as `kind: 'lineage'`.
+   */
+  series?: boolean;
 }
 
 // === Site Config ===
 
+export interface SiteColors {
+  /** Per-dataset color overrides. Keyed by dataset id. */
+  dataset?: Record<string, DatasetColorSpec>;
+  /** Per-group color overrides. Keyed by group id. */
+  group?: Record<string, DatasetColorSpec>;
+  /** Per-relation-type color overrides. Keyed by type id (e.g. "supersedes"). */
+  relationshipType?: Record<string, DatasetColorSpec>;
+  /** Per-relation-category color overrides. Keyed by category id (e.g. "lifecycle"). */
+  relationshipCategory?: Record<string, DatasetColorSpec>;
+  /** Per-concept-status color overrides. Keyed by status id. */
+  conceptStatus?: Record<string, DatasetColorSpec>;
+  /** Per-group-kind color overrides. Keyed by DatasetGroupKind. */
+  groupKind?: Record<string, DatasetColorSpec>;
+}
+
 export interface SiteConfig {
   id: string;
   domain: string;
@@ -171,6 +248,8 @@ export interface SiteConfig {
   social?: SocialLinks;
   nav?: NavItem[];
   footerNav?: NavItem[];
+  /** Color overrides. Merged over `data/colors.json` defaults. */
+  colors?: SiteColors;
   defaults: {
     language?: string;
     languageOrder?: string[];

package/src/config/use-site-config.ts

@@ -1,5 +1,5 @@
 import { ref, computed } from 'vue';
-import type { PageConfig } from './types';
+import type { PageConfig, SiteColors } from './types';
 import type { DatasetGroup } from './types';
 import { locale } from '../i18n';
 
@@ -38,6 +38,7 @@ export interface RuntimeSiteConfig {
   pages?: PageConfig[];
   contributors?: { name: string; role?: string; organization?: string; url?: string; email?: string }[];
   copyright?: string;
+  colors?: SiteColors;
 }
 
 const siteConfig = ref<RuntimeSiteConfig | null>(null);

package/src/errors.ts

@@ -0,0 +1,136 @@
+export interface ErrorContext {
+  readonly conceptId?: string;
+  readonly registerId?: string;
+  readonly locale?: string;
+  readonly predicate?: string;
+  readonly sourcePath?: string;
+  readonly cause?: unknown;
+  readonly [key: string]: unknown;
+}
+
+export class GlossaristError extends Error {
+  constructor(
+    message: string,
+    public readonly context: ErrorContext = {},
+  ) {
+    super(message);
+    this.name = this.constructor.name;
+  }
+
+  hint(): string {
+    return '';
+  }
+}
+
+export class ConfigurationError extends GlossaristError {}
+export class DataSourceError extends GlossaristError {}
+export class SerializationError extends GlossaristError {}
+export class ValidationError extends GlossaristError {}
+
+export class UnknownDatasetError extends ConfigurationError {
+  static make(registerId: string): UnknownDatasetError {
+    return new UnknownDatasetError(`Unknown dataset: ${registerId}`, { registerId });
+  }
+
+  hint(): string {
+    return 'Check datasets.yml / datasets.json registration and adapter discovery.';
+  }
+}
+
+export class DatasetRegistryLoadError extends DataSourceError {
+  static make(status: number, url?: string): DatasetRegistryLoadError {
+    return new DatasetRegistryLoadError(
+      `Failed to load dataset registry: HTTP ${status}`,
+      { status, url },
+    );
+  }
+}
+
+export class ManifestLoadError extends DataSourceError {
+  static make(registerId: string, status: number): ManifestLoadError {
+    return new ManifestLoadError(
+      `Failed to load manifest for ${registerId}: HTTP ${status}`,
+      { registerId, status },
+    );
+  }
+}
+
+export class IndexLoadError extends DataSourceError {
+  static make(registerId: string, status: number): IndexLoadError {
+    return new IndexLoadError(
+      `Failed to load index for ${registerId}: HTTP ${status}`,
+      { registerId, status },
+    );
+  }
+}
+
+export class ChunkLoadError extends DataSourceError {
+  static make(registerId: string, chunkIndex: number, status: number): ChunkLoadError {
+    return new ChunkLoadError(
+      `Failed to load chunk ${chunkIndex} for ${registerId}: HTTP ${status}`,
+      { registerId, chunkIndex, status },
+    );
+  }
+}
+
+export class ConceptNotFoundError extends DataSourceError {
+  static make(registerId: string, conceptId: string): ConceptNotFoundError {
+    return new ConceptNotFoundError(
+      `Concept ${conceptId} not found in ${registerId}`,
+      { registerId, conceptId },
+    );
+  }
+}
+
+export class NonVerbalEntityNotFoundError extends DataSourceError {
+  static make(datasetId: string, kind: string, entityId: string, status: number): NonVerbalEntityNotFoundError {
+    return new NonVerbalEntityNotFoundError(
+      `Failed to load ${kind} ${entityId} from ${datasetId}: HTTP ${status}`,
+      { datasetId, kind, entityId, status },
+    );
+  }
+}
+
+export class InvalidConceptIdentityError extends SerializationError {
+  hint(): string {
+    return 'ConceptIdentity requires non-empty localId, registerId, and uriBase.';
+  }
+}
+
+export class InvalidConceptUriError extends SerializationError {
+  static make(uri: string): InvalidConceptUriError {
+    return new InvalidConceptUriError(`Not a concept URI: ${uri}`, { uri });
+  }
+
+  hint(): string {
+    return 'Expected format: <uriBase>/<registerId>/concept/<conceptId>';
+  }
+}
+
+export class InvalidLangTagError extends SerializationError {
+  hint(): string {
+    return 'Use BCP-47 form: primary[-script][-region][-variant]*[-x-private]. ' +
+      'ISO 639-3 codes (eng, fra) are normalized to ISO 639-1 (en, fr).';
+  }
+}
+
+export function isGlossaristError(err: unknown): err is GlossaristError {
+  return err instanceof GlossaristError;
+}
+
+export function formatError(err: GlossaristError): string {
+  const lines = [`${err.name}: ${err.message}`];
+  const fields: Record<string, unknown> = {};
+  for (const [k, v] of Object.entries(err.context)) {
+    if (k === 'cause' || v === undefined || v === null) continue;
+    fields[k] = v;
+  }
+  if (Object.keys(fields).length) {
+    for (const [k, v] of Object.entries(fields)) {
+      lines.push(`  ${k}: ${typeof v === 'object' ? JSON.stringify(v) : v}`);
+    }
+  }
+  const h = err.hint();
+  if (h) lines.push(`  hint: ${h}`);
+  return lines.join('\n');
+}

package/src/i18n/locales/eng.yml

@@ -97,6 +97,12 @@ concept.failedToLoad: Failed to load concept
 concept.notFound: Concept not found
 concept.notFoundMsg: "The concept \"{id}\" does not exist in this dataset."
 concept.backToDataset: Back to dataset
+concept.editionSeries: Edition series
+concept.viewing: viewing
+concept.currentEdition: current edition
+edge.supersedes: supersedes
+edge.superseded_by: superseded by
+concept.noChain: No supersession chain recorded for this concept.
 
 # Sidebar
 sidebar.overview: Overview
@@ -185,3 +191,21 @@ dataset.alphabetical: Alphabetical
 dataset.sectionFilter: Section
 dataset.clearSection: Clear section
 dataset.conceptsInSection: concepts in section
+
+# Relation sphere view
+sphere.viewOptions: View options
+sphere.degree: Degree
+sphere.language: Language
+sphere.datasets: Datasets
+sphere.relationTypes: Relation types
+sphere.expand: Expand
+sphere.tight: tight
+sphere.loose: loose
+sphere.redraw: Redraw
+sphere.focus: FOCUS
+concept.detailView: Detail
+concept.relationSphere: Relation Sphere
+concept.permalink: Permalink
+concept.copied: Copied
+
+# Relation types (displayed in legend + edge labels)

package/src/i18n/locales/fra.yml

@@ -97,6 +97,12 @@ concept.failedToLoad: Échec du chargement du concept
 concept.notFound: Concept non trouvé
 concept.notFoundMsg: "Le concept « {id} » n'existe pas dans ce jeu de données."
 concept.backToDataset: Retour au jeu de données
+concept.editionSeries: Série d'éditions
+concept.viewing: affiché
+concept.currentEdition: édition courante
+edge.supersedes: remplace
+edge.superseded_by: remplacé par
+concept.noChain: Aucune chaîne de succession enregistrée pour ce concept.
 
 # Sidebar
 sidebar.overview: Vue d'ensemble
@@ -185,3 +191,21 @@ dataset.alphabetical: Alphabétique
 dataset.sectionFilter: Section
 dataset.clearSection: Effacer la section
 dataset.conceptsInSection: concepts dans la section
+
+# Relation sphere view
+sphere.viewOptions: Options d'affichage
+sphere.degree: Degré
+sphere.language: Langue
+sphere.datasets: Jeux de données
+sphere.relationTypes: Types de relation
+sphere.expand: Expansion
+sphere.tight: serré
+sphere.loose: étendu
+sphere.redraw: Redessiner
+sphere.focus: FOCUS
+concept.detailView: Détail
+concept.relationSphere: Sphère de relations
+concept.permalink: Permalien
+concept.copied: Copié
+
+# Relation types (affichés dans la légende + étiquettes d'arêtes)

package/src/stores/vocabulary.ts

@@ -8,6 +8,7 @@ import { conceptUri } from '../adapters/model-bridge';
 import { GraphEngine } from '../graph';
 import { UriRouter } from '../adapters/UriRouter';
 import { deduplicateSearchHits } from '../utils/search';
+import { UnknownDatasetError } from '../errors';
 
 export const useVocabularyStore = defineStore('vocabulary', () => {
   // State
@@ -193,7 +194,7 @@ export const useVocabularyStore = defineStore('vocabulary', () => {
 
     try {
       const adapter = datasets.value.get(registerId);
-      if (!adapter) throw new Error(`Dataset ${registerId} not loaded`);
+      if (!adapter) throw UnknownDatasetError.make(registerId);
 
       // Fetch concept and cross-dataset edges in parallel
       const [concept] = await Promise.all([
@@ -332,6 +333,7 @@ export const useVocabularyStore = defineStore('vocabulary', () => {
     datasetList,
     discoverDatasets,
     loadDataset,
+    ensureEdgesForDataset,
     viewConcept,
     navigateToUri,
     searchAcrossDatasets,

package/src/style.css

@@ -482,10 +482,25 @@
 
 /* ── Sidebar group labels (brand colors are too dark in dark mode) ── */
 .dark .sidebar-group-label {
-  filter: brightness(2);
+  filter: brightness(1.6);
 }
 .dark .sidebar-group-label:hover {
-  filter: brightness(1.8);
+  filter: brightness(1.4);
+}
+
+/* ── Gold accent that adapts to theme ── */
+:root {
+  --gold-accent: #B8935A;
+  --gold-accent-deep: #8C6A3A;
+}
+.dark {
+  --gold-accent: #D4AF6E;
+  --gold-accent-deep: #B8935A;
+}
+
+/* Section labels brighter in dark mode */
+.dark .section-label {
+  color: theme('colors.ink.300') !important;
 }
 
 /* Scrollbar hide utility */

package/src/types/agents-version-turtle.d.ts

@@ -0,0 +1,27 @@
+declare module '*/scripts/lib/agents-turtle.mjs' {
+  export function buildAgentsTurtle(
+    contributors: readonly { name: string; role?: string; organization?: string; url?: string; email?: string }[],
+    agentBase?: string,
+  ): string;
+}
+
+declare module '*/scripts/lib/version-turtle.mjs' {
+  export interface VersionInput {
+    readonly registerId: string;
+    readonly version: string;
+    readonly versionIri: string;
+    readonly datasetIri: string;
+    readonly generatedAt: string;
+    readonly previousVersionIri?: string;
+    readonly changeSummary?: string;
+    readonly associatedAgentIri?: string;
+  }
+  export interface VersionHistoryInput {
+    readonly registerId: string;
+    readonly datasetIri: string;
+    readonly versions: readonly { version: string; generatedAt: string; changeSummary?: string }[];
+    readonly associatedAgentIri?: string;
+  }
+  export function buildVersionTurtle(input: VersionInput): string;
+  export function buildVersionHistoryTurtle(input: VersionHistoryInput): string;
+}

package/src/types/bibliography-turtle.d.ts

@@ -0,0 +1,12 @@
+declare module '*/scripts/lib/bibliography-turtle.mjs' {
+  export interface BibliographyEntryJson {
+    readonly reference?: string;
+    readonly title?: string;
+    readonly link?: string;
+  }
+  export function buildBibliographyTurtle(
+    register: string,
+    bibliographyJson: Record<string, BibliographyEntryJson>,
+    baseUri?: string,
+  ): string;
+}

package/src/types/build-activity-turtle.d.ts

@@ -0,0 +1,16 @@
+declare module '*/scripts/lib/build-activity-turtle.mjs' {
+  export interface BuildActivityTurtleInput {
+    readonly runId: string;
+    readonly startedAt: string;
+    readonly endedAt: string;
+    readonly gitSha?: string | null;
+    readonly gitBranch?: string | null;
+    readonly toolId: string;
+    readonly toolVersion: string;
+    readonly datasetRegisters: readonly string[];
+    readonly conceptCount: number;
+    readonly associatedAgentIri?: string | null;
+  }
+
+  export function buildActivityTurtle(input: BuildActivityTurtleInput): string;
+}

package/src/types/build-cache.d.ts

@@ -0,0 +1,20 @@
+declare module '*/scripts/lib/build-cache.mjs' {
+  export interface BuildCacheEntry<T = unknown> {
+    hash: string;
+    value: T;
+    storedAt: string;
+  }
+
+  export class BuildCache {
+    constructor(cacheDir: string);
+    get<T = unknown>(key: string): Promise<BuildCacheEntry<T> | null>;
+    set<T = unknown>(key: string, value: T, hash: string): Promise<void>;
+    readThrough<T>(
+      key: string,
+      hash: string,
+      producer: () => Promise<T>,
+    ): Promise<{ value: T; hit: boolean }>;
+    pathFor(key: string): string;
+    static hash(input: string): string;
+  }
+}