@volter/sdk 0.0.0-stage → 0.5.204

package/src/kit/asset-selection.ts

@@ -0,0 +1,146 @@
+/**
+ * Asset SELECTION state (W2) — the "single click selects" half of the selection-vs-open
+ * contract:
+ *
+ *   - single click in the Project/Assets browser SELECTS the asset and shows
+ *     compact preview/metadata in the Inspector (the registered
+ *     `components/asset-selection-section.tsx` section reads this store);
+ *   - double click / Enter OPENS the full viewer as a center document
+ *     (`components/asset-documents.tsx`);
+ *   - drag remains a placement gesture and never touches this store.
+ *
+ * A tiny module-scope store in the house `useSyncExternalStore` shape
+ * (mirrors `inspector-section-registry.ts`): version counter + subscribe +
+ * `__resetForTest`. It deliberately does NOT touch the EditorShellStore's entity
+ * selection — clicking an asset must never deselect/reselect scene entities
+ * (§6.1 "selection never unexpectedly..."); instead the Inspector gives the
+ * asset domain precedence while retaining that entity selection, and the asset is auto-cleared
+ * when the ENTITY selection changes (the user moved on — see
+ * `installAssetSelectionAutoClear`).
+ */
+
+import type { AssetCapabilities } from '@volter/sdk/kit/asset-capabilities';
+
+export type AssetKind = 'model' | 'image' | 'video' | 'audio' | 'json' | 'source';
+
+export interface OnlineAssetInfo {
+  source: 'polyhaven' | 'ambientcg' | 'local';
+  id: string;
+  name: string;
+  thumbnailUrl: string;
+  type: string;
+  tags: string[];
+  license?: string;
+  author?: string;
+  sourceUrl?: string;
+}
+
+/** The §5.1 compact-selection payload — enough for the Inspector section to
+ *  render preview + metadata without re-deriving browser state. */
+export interface SelectedAsset {
+  /** Project serving path, or a stable `online:<source>:<id>` document key. */
+  readonly path: string;
+  /** Source-owned file name as authored (§8 — `crate.png`). */
+  readonly name: string;
+  readonly kind: AssetKind | 'component' | 'folder' | 'unknown';
+  /** Portable-CSF preview identity for a source-owned prefab/component. */
+  readonly componentPreview?: {
+    readonly surface: 'three' | 'canvas' | 'dom' | 'unknown';
+    readonly sourcePath: string;
+  };
+  /** File size in bytes when the browser knows it. */
+  readonly sizeBytes?: number;
+  readonly capabilities?: AssetCapabilities;
+  readonly health?: 'healthy' | 'source-only' | 'unsupported';
+  readonly sourcePath?: string;
+  readonly selectionCount?: number;
+  readonly selectionTotalBytes?: number;
+  readonly selectionFormats?: readonly string[];
+  readonly dependencies?: readonly string[];
+  readonly references?: readonly { ownerPath: string; jsonPath: string }[];
+  readonly healthCodes?: readonly string[];
+  /** Selection came from the external acquisition Library rather than the
+   * project's owned file tree. `online` carries the provider identity and is
+   * intentionally absent from project assets. */
+  readonly origin?: 'project' | 'library';
+  readonly online?: OnlineAssetInfo;
+}
+
+let _selected: SelectedAsset | null = null;
+let _version = 0;
+const _listeners = new Set<() => void>();
+
+function notifyChanged(): void {
+  _version++;
+  for (const fn of _listeners) fn();
+}
+
+/** Subscribe to selection changes. Returns an unsubscribe function. */
+export function subscribeAssetSelection(fn: () => void): () => void {
+  _listeners.add(fn);
+  return () => {
+    _listeners.delete(fn);
+  };
+}
+
+/** Monotonic change counter — the `getSnapshot` for `useSyncExternalStore`. */
+export function assetSelectionVersion(): number {
+  return _version;
+}
+
+/** The currently selected asset, or `null`. */
+export function getSelectedAsset(): SelectedAsset | null {
+  return _selected;
+}
+
+/** Select an asset (single-click). Idempotent on the same path. */
+export function setSelectedAsset(asset: SelectedAsset): void {
+  if (_selected && JSON.stringify(_selected) === JSON.stringify(asset)) return;
+  _selected = asset;
+  notifyChanged();
+}
+
+/** Clear the asset selection (no-op when already clear). */
+export function clearSelectedAsset(): void {
+  if (_selected === null) return;
+  _selected = null;
+  notifyChanged();
+}
+
+/** The narrow store surface the auto-clear needs (testable with a fake). */
+export interface AssetSelectionAutoClearStore {
+  subscribe(listener: () => void): () => void;
+  readonly selectedEntityIds: ReadonlySet<string>;
+}
+
+function entitySelectionKey(store: AssetSelectionAutoClearStore): string {
+  return [...store.selectedEntityIds].sort().join('\n');
+}
+
+/**
+ * Auto-clear wiring (installed once per editor session by the layout): when
+ * the ENTITY selection changes while an asset is selected, the user has moved
+ * on — drop the asset selection so the Inspector goes back to being purely
+ * entity-contextual. The entity-selection snapshot is captured on every asset
+ * selection SET (not at install time), so only a change that happens AFTER
+ * the asset click clears it.
+ */
+export function installAssetSelectionAutoClear(store: AssetSelectionAutoClearStore): () => void {
+  let snapshot = entitySelectionKey(store);
+  const unsubscribeSelf = subscribeAssetSelection(() => {
+    if (_selected) snapshot = entitySelectionKey(store);
+  });
+  const unsubscribeStore = store.subscribe(() => {
+    if (_selected && entitySelectionKey(store) !== snapshot) clearSelectedAsset();
+  });
+  return () => {
+    unsubscribeSelf();
+    unsubscribeStore();
+  };
+}
+
+/** Test-only reset (mirrors `__resetInspectorSectionRegistryForTest`). */
+export function __resetAssetSelectionForTest(): void {
+  _selected = null;
+  notifyChanged();
+}

package/src/kit/asset-thumbnails.ts

@@ -0,0 +1,25 @@
+/**
+ * ASSET THUMBNAILS BY THE MEDIUM THAT CAN DRAW THEM — a model file's picture is
+ * rendered offscreen by the integration that loads that format. The kit's asset
+ * browser asks here whether a file has a rendered thumbnail and queues the
+ * render; a file no renderer accepts keeps its icon.
+ */
+export interface AssetThumbnailRenderer {
+  accepts(url: string): boolean;
+  /** A data URL of the file's picture. */
+  render(url: string): Promise<string>;
+}
+
+let renderers: readonly AssetThumbnailRenderer[] = [];
+
+export function registerAssetThumbnailRenderer(renderer: AssetThumbnailRenderer): () => void {
+  renderers = [...renderers, renderer];
+  return () => {
+    renderers = renderers.filter((existing) => existing !== renderer);
+  };
+}
+
+/** The first registered renderer that draws `url`, or null. */
+export function assetThumbnailRenderer(url: string): AssetThumbnailRenderer | null {
+  return renderers.find((renderer) => renderer.accepts(url)) ?? null;
+}

package/src/kit/asset-viewers.ts

@@ -0,0 +1,115 @@
+/**
+ * ASSET VIEWERS BY ROUTE — the Asset Lab's native views for the formats a media
+ * integration renders (a model, an environment map, a LUT, a shader, a live
+ * modeling module, an entity's model). The kit's asset documents render the
+ * registered viewer for a route and their own fallback when none is: a
+ * composition with no three.js integration still opens the file, as text or as
+ * a file with no renderer. One registration per route; `useAssetViewer` re-renders
+ * when one arrives, so a document restored before its integration loaded
+ * upgrades in place.
+ */
+import { type ComponentType, createElement, type ReactNode, useSyncExternalStore } from 'react';
+
+export type AssetViewerRoute =
+  | 'model'
+  | 'environment'
+  | 'lut'
+  | 'shader'
+  | 'module'
+  | 'entity-model'
+  /** A compact live preview of a model file (an online asset's detail). */
+  | 'model-preview';
+
+export interface AssetViewerProps {
+  readonly documentId: string;
+  /** The asset's project path; empty for an `entity-model`. */
+  readonly assetPath: string;
+  readonly displayName: string;
+  readonly active: boolean;
+  /** `entity-model`: the live entity whose model this is. */
+  readonly entityId?: string;
+  /** `module`: the project root the module is served from. */
+  readonly projectRoot?: string;
+  /** `model-preview`: a material file applied to the model. */
+  readonly materialPath?: string;
+  /** What to show when the viewer finds nothing it renders (a `module` that
+   *  builds no Object3D). */
+  readonly fallback?: ReactNode;
+}
+
+const viewers = new Map<AssetViewerRoute, ComponentType<AssetViewerProps>>();
+const listeners = new Set<() => void>();
+let version = 0;
+
+function changed(): void {
+  version += 1;
+  for (const listener of listeners) listener();
+}
+
+/** Register the viewer for one route. Returns the removal. */
+export function registerAssetViewer(
+  route: AssetViewerRoute,
+  viewer: ComponentType<AssetViewerProps>,
+): () => void {
+  const existing = viewers.get(route);
+  if (existing && existing !== viewer) throw new Error(`An asset viewer for "${route}" is already registered.`);
+  viewers.set(route, viewer);
+  changed();
+  return () => {
+    if (viewers.get(route) !== viewer) return;
+    viewers.delete(route);
+    changed();
+  };
+}
+
+function subscribe(listener: () => void): () => void {
+  listeners.add(listener);
+  return () => listeners.delete(listener);
+}
+
+/** The registered viewer for `route`, or null; re-renders when one arrives. */
+export function useAssetViewer(route: AssetViewerRoute): ComponentType<AssetViewerProps> | null {
+  useSyncExternalStore(subscribe, () => version, () => version);
+  return viewers.get(route) ?? null;
+}
+
+/** The registered viewer for `route` with `props`, or `whenUnregistered` when this
+ *  composition registered none. `props.fallback` still reaches the viewer. */
+export function AssetViewerSlot({
+  route,
+  whenUnregistered,
+  ...props
+}: AssetViewerProps & { readonly route: AssetViewerRoute; readonly whenUnregistered: ReactNode }): ReactNode {
+  const Viewer = useAssetViewer(route);
+  return Viewer ? createElement(Viewer, props) : whenUnregistered;
+}
+
+/**
+ * A JSON FORMAT A MEDIUM RECOGNIZES BY ITS CONTENT — three.quarks writes plain
+ * Object3D JSON with no extension of its own, so only the file's structure can
+ * say it is a particle system. The kit's JSON document asks each registered
+ * recognizer in turn and shows the generic JSON viewer when none claims it.
+ */
+export interface JsonContentViewer {
+  /** The parsed content this viewer renders, or null when it is not its format. */
+  recognize(assetPath: string, signal: AbortSignal): Promise<unknown | null>;
+  readonly Viewer: ComponentType<AssetViewerProps & { readonly content: unknown }>;
+}
+
+let jsonViewers: readonly JsonContentViewer[] = [];
+
+export function registerJsonContentViewer(viewer: JsonContentViewer): () => void {
+  jsonViewers = [...jsonViewers, viewer];
+  changed();
+  return () => {
+    if (!jsonViewers.includes(viewer)) return;
+    jsonViewers = jsonViewers.filter((existing) => existing !== viewer);
+    changed();
+  };
+}
+
+/** The registered JSON recognizers, in registration order — a new array only
+ *  when the set changes, so an effect keyed on it re-runs exactly then. */
+export function useJsonContentViewers(): readonly JsonContentViewer[] {
+  return useSyncExternalStore(subscribe, () => jsonViewers, () => jsonViewers);
+}

package/src/kit/asset-workflow/asset-import-jobs.ts

@@ -0,0 +1,106 @@
+import { connectEvents } from '@volter/sdk/kit/editor-api';
+import type { AssetImportStage } from './import-contract';
+
+export interface AssetImportJob {
+  id: string;
+  label: string;
+  stage: AssetImportStage;
+  loaded: number;
+  total: number;
+  status: 'running' | 'imported' | 'skipped' | 'failed' | 'cancelled';
+  message?: string;
+  controller: AbortController;
+  retry?: () => void;
+}
+
+const jobs = new Map<string, AssetImportJob>();
+const listeners = new Set<() => void>();
+let version = 0;
+function notify(): void {
+  version++;
+  for (const listener of listeners) listener();
+}
+export function assetImportJobsVersion(): number {
+  return version;
+}
+export function subscribeAssetImportJobs(listener: () => void): () => void {
+  listeners.add(listener);
+  return () => {
+    listeners.delete(listener);
+  };
+}
+export function assetImportJobs(): readonly AssetImportJob[] {
+  return [...jobs.values()];
+}
+
+export function beginAssetImportJob(id: string, label: string): AssetImportJob {
+  const existing = jobs.get(id);
+  if (existing?.status === 'running') return existing;
+  const job: AssetImportJob = {
+    id,
+    label,
+    stage: 'fetch',
+    loaded: 0,
+    total: 0,
+    status: 'running',
+    controller: new AbortController(),
+  };
+  jobs.set(id, job);
+  notify();
+  return job;
+}
+export function updateAssetImportJob(
+  id: string,
+  patch: Partial<Omit<AssetImportJob, 'id' | 'controller'>>,
+): void {
+  const job = jobs.get(id);
+  if (!job) return;
+  Object.assign(job, patch);
+  notify();
+}
+export function cancelAssetImportJob(id: string): void {
+  const job = jobs.get(id);
+  if (!job || job.status !== 'running') return;
+  job.controller.abort(new DOMException('Import cancelled', 'AbortError'));
+  job.status = 'cancelled';
+  job.message = 'Cancelled before project commit.';
+  notify();
+}
+export function clearFinishedAssetImportJobs(): void {
+  for (const [id, job] of jobs) if (job.status !== 'running') jobs.delete(id);
+  notify();
+}
+export function resetAssetImportJobs(): void {
+  jobs.clear();
+  notify();
+}
+
+/** Keep jobs progressing independently of whether the Library document is mounted. */
+export function connectAssetImportProgressEvents(): () => void {
+  const source = connectEvents();
+  const listener = (event: MessageEvent) => {
+    try {
+      const update = JSON.parse(event.data as string) as {
+        jobId?: string;
+        stage?: AssetImportStage;
+        loaded?: number;
+        total?: number;
+        message?: string;
+      };
+      if (!update.jobId || !update.stage) return;
+      updateAssetImportJob(update.jobId, {
+        stage: update.stage,
+        loaded: Math.max(0, update.loaded ?? 0),
+        total: Math.max(0, update.total ?? 0),
+        ...(update.message ? { message: update.message } : {}),
+      });
+    } catch {
+      // Optional progress cannot break a running import.
+    }
+  };
+  source.addEventListener('asset-import-progress', listener);
+  return () => {
+    source.removeEventListener('asset-import-progress', listener);
+    source.close();
+  };
+}

package/src/kit/asset-workflow/asset-ledger-backend.ts

@@ -0,0 +1,126 @@
+/**
+ * `StorageBackend` side of the asset provenance ledger (D-AP3) — the
+ * browser/isomorphic sibling of `packages/editor-core/server/asset-ledger-store.ts`,
+ * which reads/writes `.volter/assets.json` via `node:fs` for the local
+ * (HttpStorage-backed) Node editor. Every environment materializes through the
+ * SAME record shape (`../asset-workflow/asset-ledger.ts`'s pure schema) — only
+ * the I/O side differs, exactly like `storage/seed.ts`'s `readProjectManifest`
+ * reading `volter.project.json` through a `StorageBackend` instead of `node:fs`.
+ *
+ * Used by `hosted-asset-materialization.ts` (D-AP4 — a project's declared
+ * packs).
+ *
+ * Concurrency: the same two-half protection the Node side takes, over this
+ * side's I/O (see `./ledger-write-lock.ts`). The in-realm chain covers one tab
+ * — several declared entries materializing in one pass, the Library panel and a
+ * reopen retry overlapping — and the `.lock` file covers the case only another
+ * realm can see: two tabs open on the same project, both retrying their
+ * declared packs. `writeIfAbsent` is honest about not being O_EXCL on
+ * handle APIs (it "serializes same-origin writers and rechecks at handle
+ * acquisition"), which is exactly the guarantee that matters here — the racing
+ * writers ARE same-origin — so it is the strongest primitive available and not
+ * a claim of more.
+ */
+
+import { withPathLock } from '../storage/path-lock';
+import type { StorageBackend } from '@volter/sdk/kit/storage-types';
+import {
+  ASSET_LEDGER_PATH,
+  type AssetLedger,
+  type AssetLedgerEntry,
+  normalizeLedgerPath,
+  parseAssetLedgerJson,
+  serializeAssetLedger,
+  sourceHashFromSha256,
+  upsertAssetLedgerEntry,
+} from './asset-ledger';
+import { createSerializer, withExclusiveLock } from './ledger-write-lock';
+
+/** Read the ledger via `backend`. Absent → `{}`. Corrupt → throws (same
+ *  contract as the Node `asset-ledger-store.ts` — a provenance record that
+ *  silently drops entries is worse than no record). */
+export async function readAssetLedgerFromBackend(backend: StorageBackend): Promise<AssetLedger> {
+  if (!(await backend.exists(ASSET_LEDGER_PATH))) return {};
+  return parseAssetLedgerJson(await backend.read(ASSET_LEDGER_PATH));
+}
+
+export async function writeAssetLedgerToBackend(
+  backend: StorageBackend,
+  ledger: AssetLedger,
+): Promise<void> {
+  await backend.write(ASSET_LEDGER_PATH, serializeAssetLedger(ledger));
+}
+
+export interface BackendMaterializationRecord {
+  /** Project-relative destination, e.g. `public/asset-library/local/x/y.glb`. */
+  readonly destPath: string;
+  /** `source:id` — the library's identity for this asset. */
+  readonly key: string;
+  /** License string as the library reported it, if it reported one. */
+  readonly license?: string | undefined;
+  /** The LIBRARY's sha256 of the source bytes. Omit when the library has
+   *  none — never substitute a hash of the bytes just written (anti-shim). */
+  readonly sourceSha256?: string | undefined;
+  readonly materializedAt?: string;
+}
+
+const LEDGER_LOCK_PATH = `${ASSET_LEDGER_PATH}.lock`;
+const serializeLedgerWrite = createSerializer();
+/** Stable per-backend key for the in-realm chain (`backend.id` is shared by
+ *  every instance of a backend TYPE, so it cannot key this on its own). */
+const backendKeys = new WeakMap<StorageBackend, string>();
+let nextBackendKey = 0;
+
+function ledgerWriteKey(backend: StorageBackend): string {
+  const existing = backendKeys.get(backend);
+  if (existing !== undefined) return existing;
+  nextBackendKey += 1;
+  const key = `${backend.id}#${nextBackendKey}`;
+  backendKeys.set(backend, key);
+  return key;
+}
+
+/** Record one materialization in the project's ledger, via `backend`. */
+export async function recordAssetMaterializationInBackend(
+  backend: StorageBackend,
+  record: BackendMaterializationRecord,
+): Promise<void> {
+  const entry: AssetLedgerEntry = {
+    key: record.key,
+    ...(record.license ? { license: record.license } : {}),
+    ...(record.sourceSha256 ? { sourceHash: sourceHashFromSha256(record.sourceSha256) } : {}),
+    materializedAt: record.materializedAt ?? new Date().toISOString(),
+  };
+  await serializeLedgerWrite(ledgerWriteKey(backend), () =>
+    withExclusiveLock(
+      {
+        createIfAbsent: (content) => backend.writeIfAbsent(LEDGER_LOCK_PATH, content),
+        read: async () =>
+          (await backend.exists(LEDGER_LOCK_PATH)) ? backend.read(LEDGER_LOCK_PATH) : null,
+        // Compare-and-delete (see `./ledger-write-lock.ts`'s `ExclusiveLockIO`),
+        // and its three steps must not interleave with another realm's — so
+        // they run under the SAME path lock `HandleStorage.writeIfAbsent` takes
+        // (`../storage/path-lock.ts`). That makes this side genuinely atomic
+        // against every same-origin tab, so it needs no `rename` takeover
+        // like the `node:fs` side.
+        // NOT covered: `HttpStorage`, whose peer writer is the Node server/CLI
+        // rather than another tab — Web Locks cannot reach a separate process,
+        // and neither can anything else available in the page.
+        removeIfHeldBy: (expected) =>
+          withPathLock(backend.id, LEDGER_LOCK_PATH, async () => {
+            if (!(await backend.exists(LEDGER_LOCK_PATH))) return;
+            if ((await backend.read(LEDGER_LOCK_PATH)) !== expected) return;
+            await backend.remove(LEDGER_LOCK_PATH);
+          }),
+      },
+      async () => {
+        const ledger = await readAssetLedgerFromBackend(backend);
+        await writeAssetLedgerToBackend(
+          backend,
+          upsertAssetLedgerEntry(ledger, normalizeLedgerPath(record.destPath), entry),
+        );
+      },
+      { owner: backend.id },
+    ),
+  );
+}

package/src/kit/asset-workflow/asset-ledger.ts

@@ -0,0 +1,156 @@
+/**
+ * The project-owned asset provenance ledger — `.volter/assets.json` (D-AP3).
+ *
+ * Assets follow the capability model: the asset library is the SOURCE, a
+ * project owns its COPIES. Every materialization — the editor's Library-panel
+ * download, the template/example `asset-packs:sync` script, the hosted seed —
+ * records the copy here, keyed by PROJECT-RELATIVE destination path.
+ *
+ * One ledger, not per-file sidecars: sidecars pollute asset directories and
+ * break tooling that globs them.
+ *
+ * The ledger is the license/attribution record and the drift input. Comparing a
+ * file's current hash to `sourceHash` distinguishes "the user edited their copy"
+ * (legitimate; git reports it) from "the library moved" (reported, never
+ * auto-applied — there is deliberately no `volter asset update`).
+ *
+ * ANTI-SHIM: `license` and `sourceHash` are OPTIONAL and are recorded only when
+ * the library actually supplied them. We never hash the bytes we just wrote and
+ * call the result a `sourceHash` — that would make every copy look pristine
+ * forever and destroy the drift signal the field exists for. A materialization
+ * path with no library-supplied hash records the key and the timestamp and
+ * nothing else. Today that is the polyhaven/ambientcg remote proxy, whose
+ * upstream APIs publish no per-file digest; the local/cloud catalog paths
+ * (34,412 assets) carry `sha256` and populate the field.
+ */
+
+import { isContainedRelativePath } from '@volter/sdk/session/relative-path-guard';
+import { z } from 'zod';
+
+/** Project-relative location of the ledger. */
+export const ASSET_LEDGER_PATH = '.volter/assets.json';
+
+/** The library's asset identity: `source:id` (see `onlineAssetKey`). */
+export function assetKey(source: string, id: string): string {
+  return `${source}:${id}`;
+}
+
+export const AssetLedgerEntrySchema = z
+  .object({
+    /** `source:id` — the library's own identity for the asset. */
+    key: z.string().min(1),
+    /** SPDX-ish license string as the library reported it, when it reported one. */
+    license: z.string().min(1).optional(),
+    /** The LIBRARY's digest of the source bytes — never a re-hash of our copy. */
+    sourceHash: z
+      .string()
+      .regex(/^sha256-[a-f0-9]{64}$/, 'sourceHash must be "sha256-<64 hex>"')
+      .optional(),
+    /** ISO-8601 instant the copy was written into this project. */
+    materializedAt: z.string().datetime(),
+  })
+  .strict();
+
+export const AssetLedgerSchema = z.record(z.string().min(1), AssetLedgerEntrySchema);
+
+export type AssetLedgerEntry = z.infer<typeof AssetLedgerEntrySchema>;
+export type AssetLedger = Record<string, AssetLedgerEntry>;
+
+/** Format a raw hex digest as the ledger's `sourceHash`. Rejects non-digests
+ *  loudly rather than storing something that only looks like a hash. */
+export function sourceHashFromSha256(sha256: string): string {
+  if (!/^[a-f0-9]{64}$/.test(sha256)) {
+    throw new Error(`Not a sha256 digest, refusing to record it as a sourceHash: ${sha256}`);
+  }
+  return `sha256-${sha256}`;
+}
+
+/** The raw hex digest inside a `sha256-…` sourceHash, or null for other forms. */
+export function sha256FromSourceHash(sourceHash: string): string | null {
+  const match = /^sha256-([a-f0-9]{64})$/.exec(sourceHash);
+  return match?.[1] ?? null;
+}
+
+/** Normalize a ledger key: project-relative, forward slashes, no leading `./`. */
+export function normalizeLedgerPath(path: string): string {
+  const normalized = path.replaceAll('\\', '/').replace(/^\.\//, '').replace(/^\/+/, '');
+  if (!normalized) throw new Error('An asset ledger path cannot be empty.');
+  if (!isContainedRelativePath(normalized)) {
+    throw new Error(`An asset ledger path cannot escape the project: ${path}`);
+  }
+  return normalized;
+}
+
+/** Parse a ledger document. Throws (loudly) on anything malformed — a
+ *  provenance record that silently drops entries is worse than no record. */
+export function parseAssetLedger(input: unknown): AssetLedger {
+  return AssetLedgerSchema.parse(input);
+}
+
+/** Parse ledger JSON text; an absent ledger is `{}`, a CORRUPT one throws. */
+export function parseAssetLedgerJson(text: string | null | undefined): AssetLedger {
+  if (text == null || text.trim() === '') return {};
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(text);
+  } catch (cause) {
+    throw new Error(`${ASSET_LEDGER_PATH} is not valid JSON: ${String(cause)}`);
+  }
+  return parseAssetLedger(parsed);
+}
+
+/** Record one materialization. Pure: returns a new, key-sorted ledger. */
+export function upsertAssetLedgerEntry(
+  ledger: AssetLedger,
+  destPath: string,
+  entry: AssetLedgerEntry,
+): AssetLedger {
+  const key = normalizeLedgerPath(destPath);
+  const validated = AssetLedgerEntrySchema.parse(entry);
+  const merged: AssetLedger = { ...ledger, [key]: validated };
+  const sorted: AssetLedger = {};
+  for (const path of Object.keys(merged).sort()) sorted[path] = merged[path]!;
+  return sorted;
+}
+
+/** Serialize for disk — stable key order, trailing newline. */
+export function serializeAssetLedger(ledger: AssetLedger): string {
+  const sorted: AssetLedger = {};
+  for (const path of Object.keys(ledger).sort()) sorted[path] = ledger[path]!;
+  return `${JSON.stringify(sorted, null, 2)}\n`;
+}
+
+export type AssetLedgerDrift =
+  | { readonly status: 'untracked' }
+  | { readonly status: 'unknown-source-hash' }
+  | { readonly status: 'pristine' }
+  | {
+      readonly status: 'edited-locally';
+      readonly sourceHash: string;
+      readonly currentHash: string;
+    };
+
+/**
+ * Classify one copy against its ledger entry. `currentHash` is the sha256 of
+ * the bytes on disk RIGHT NOW.
+ *
+ * This deliberately cannot tell "user edited" from "library moved" on its own —
+ * both show as a hash difference. The ledger supplies one half (what we copied);
+ * re-reading the library supplies the other. Callers that have not consulted the
+ * library must report `edited-locally` as "differs from what was materialized",
+ * never as "the library moved".
+ */
+export function classifyAssetLedgerDrift(
+  ledger: AssetLedger,
+  destPath: string,
+  currentSha256: string,
+): AssetLedgerDrift {
+  const entry = ledger[normalizeLedgerPath(destPath)];
+  if (!entry) return { status: 'untracked' };
+  if (!entry.sourceHash) return { status: 'unknown-source-hash' };
+  const expected = sha256FromSourceHash(entry.sourceHash);
+  if (expected === null) return { status: 'unknown-source-hash' };
+  return expected === currentSha256
+    ? { status: 'pristine' }
+    : { status: 'edited-locally', sourceHash: expected, currentHash: currentSha256 };
+}