@volter/sdk 0.0.0-stage → 0.5.204

package/src/kit/state-report-deferral.ts

@@ -0,0 +1,73 @@
+/**
+ * Keeping the editor's status snapshot off the interaction critical path.
+ *
+ * `collectState` (command-listener.ts) is not a read — it RE-DERIVES the whole
+ * status surface. Two families dominate, and both scale with the size of the
+ * project rather than with the size of the change:
+ *
+ *   - the hierarchy walk behind `entities`/`entityCount`, and
+ *   - the capability GRADING facets (`rootCoverage`, `systemCoverage`,
+ *     `projectCoverage`, `authoringCoverage`, `ontologyInvariants`), each
+ *     documented as re-derived on read; `rootCoverage`'s conformance probe
+ *     walks the hierarchy AGAIN, once per mounted root, allocating a receipt
+ *     object and a formatted sentence per node.
+ *
+ * Measured 2026-08-19 through the session journal on `examples/first-person`
+ * in play mode, 251 hierarchy nodes:
+ *
+ *     collectState total 76ms  =  rootCoverage 30ms
+ *                              +  2 x hierarchy walk 23ms
+ *     JSON.stringify of the 41KB result: 0.0ms.  Sending it: 0.1ms.
+ *
+ * So none of the cost is serialization or transport; all of it is derivation,
+ * and it is superlinear in node count (56 nodes: 1.5ms per walk; 251 nodes:
+ * 23ms). On a game-heavy project the same function measured 1.2-1.3s of
+ * main-thread block.
+ *
+ * That would be survivable if it ran rarely. It does not: `reportLatestState`
+ * is wired to the store's own change notification, to restart-required, to the
+ * ingest capture wait, to the adapter load, to every command completion, and
+ * to focus/blur/visibilitychange. So the whole derivation ran on every
+ * selection click and several times over during a mount — which is why the
+ * defect reads as "the editor is slow to touch" while an idle tab is fine.
+ *
+ * The fix is not to derive less truth, it is to derive it OFF the critical
+ * path: an interaction reports immediately with the cheap fields fresh and the
+ * derived families reused from the last full snapshot, and schedules ONE
+ * deferred full collect that makes them current again. the editor's `status` command readers
+ * are never handed a snapshot older than that deferral, and the snapshot
+ * already carries its own age.
+ */
+
+/**
+ * How long the deferred full collect may wait for an idle moment before the
+ * browser runs it anyway. Short enough that "current shortly after the change"
+ * stays true for a the editor's `status` command reader; long enough that the interaction that
+ * triggered it paints first, which is the entire point.
+ */
+export const DEFERRED_FULL_REPORT_TIMEOUT_MS = 500;
+
+interface IdleCallbackHost {
+  requestIdleCallback?: (callback: () => void, options?: { timeout?: number }) => number;
+  cancelIdleCallback?: (handle: number) => void;
+}
+
+/**
+ * Run `report` off the critical path — at the next idle moment, or when
+ * {@link DEFERRED_FULL_REPORT_TIMEOUT_MS} expires, whichever comes first.
+ * Returns the canceller the caller's teardown must run.
+ *
+ * Falls back to a task (`setTimeout`) where `requestIdleCallback` is missing
+ * (Safari before 17, and jsdom): still off the triggering handler's own frame,
+ * which is what makes the interaction cheap.
+ */
+export function scheduleDeferredFullReport(report: () => void): () => void {
+  const host = globalThis as IdleCallbackHost;
+  const idle = host.requestIdleCallback;
+  if (typeof idle === 'function') {
+    const handle = idle.call(globalThis, report, { timeout: DEFERRED_FULL_REPORT_TIMEOUT_MS });
+    return () => host.cancelIdleCallback?.call(globalThis, handle);
+  }
+  const handle = setTimeout(report, 0);
+  return () => clearTimeout(handle);
+}

package/src/kit/storage/host-files-storage.ts

@@ -0,0 +1,97 @@
+/**
+ * `StorageBackend`, answered by the WORKBENCH'S OWN FILE SERVICE (U5).
+ *
+ * ARCHITECTURE-CORE §The core is Code-OSS: *"the storage backends → file
+ * system providers, the dev server as one provider"*. What that turned out to
+ * mean, measured: both product shapes already have a real file service over
+ * the project folder (desktop's disk provider, the REH's `vscode-remote://`),
+ * so there is nothing to PROVIDE — the door CALLS what exists
+ * (`files/project-files.ts` states the decision and the reason).
+ *
+ * This class is how the existing `StorageBackend` callers — forty-odd of
+ * them, from the asset browser to the provenance ledger — reach that file
+ * service without one of them changing. It is a DECORATOR, not a fourth
+ * backend: it overrides exactly the three operations where "is this the
+ * workbench's own write?" is a question that has an answer (`read`,
+ * `readBytes`, `write`) and delegates everything else to the tier's real
+ * backend. `remove`, `mkdir`, `stat`, `list` and `watch` are the session's
+ * still, because the file door deliberately carries no remove/mkdir — a
+ * member nobody reads is cut, and nothing in the frame needs them yet.
+ *
+ * THE ROOT DIFFERENCE IS THE WHOLE JOB. `StorageBackend`'s paths on the server
+ * tier are rooted at `<project>/public/` (`http-storage.ts`'s header) while
+ * the file door's are PROJECT-RELATIVE, because that is the spelling the frame
+ * can resolve against its workspace folder. This class is the `public/` view:
+ * one prefix, in one place, instead of forty callers learning a second
+ * spelling.
+ */
+
+import { projectFiles } from '../files/project-files';
+import type { DirEntry, Stat, StorageBackend, WatchCallback } from '@volter/sdk/kit/storage-types';
+
+export class HostFilesStorage implements StorageBackend {
+  readonly id: string;
+
+  /**
+   * @param inner the tier's own backend, which still owns every operation the
+   *   file door does not carry — and which is also the FALLBACK while the
+   *   frame has taken ownership but not yet installed its provider (the mount
+   *   window `files/file-provider.ts` describes).
+   * @param root the project-relative prefix these paths live under. Always
+   *   `public` today; named rather than hardcoded so the prefix is visible at
+   *   the call site that chose it.
+   */
+  constructor(
+    private readonly inner: StorageBackend,
+    private readonly root = 'public',
+  ) {
+    this.id = `frame:${inner.id}`;
+  }
+
+  private resolve(path: string): string {
+    const key = path.replace(/\\/g, '/').replace(/^\/+/, '');
+    return key ? `${this.root}/${key}` : this.root;
+  }
+
+  read(path: string): Promise<string> {
+    return projectFiles.read(this.resolve(path));
+  }
+
+  readBytes(path: string): Promise<Uint8Array> {
+    return projectFiles.readBytes(this.resolve(path));
+  }
+
+  write(path: string, data: string | Uint8Array): Promise<void> {
+    return projectFiles.write(this.resolve(path), data);
+  }
+
+  async writeIfAbsent(path: string, data: string | Uint8Array): Promise<boolean> {
+    if (await this.exists(path)) return false;
+    await this.write(path, data);
+    return true;
+  }
+
+  list(dir: string): Promise<DirEntry[]> {
+    return this.inner.list(dir);
+  }
+
+  stat(path: string): Promise<Stat | null> {
+    return this.inner.stat(path);
+  }
+
+  exists(path: string): Promise<boolean> {
+    return projectFiles.exists(this.resolve(path));
+  }
+
+  mkdir(path: string): Promise<void> {
+    return this.inner.mkdir(path);
+  }
+
+  remove(path: string): Promise<void> {
+    return this.inner.remove(path);
+  }
+
+  watch(callback: WatchCallback): () => void {
+    return this.inner.watch(callback);
+  }
+}

package/src/kit/storage/http-storage.ts

@@ -0,0 +1,174 @@
+/**
+ * Server-backed `StorageBackend` for the local (Node) editor.
+ *
+ * A thin adapter over the editor server's existing routes — it changes nothing
+ * about how the local editor talks to disk, it just presents that surface behind
+ * the shared interface. The backend is rooted at the project's `public/` folder,
+ * matching the server's `/__editor/assets` (list) and `/__editor/save-file`
+ * (write) routes; reads come from Vite's `/@fs/` static serving.
+ *
+ * Route mapping (paths are relative to `public/`):
+ *   list     → GET  /__editor/assets?dir            → { entries: [{name,type,size,mtime}] }
+ *   write    → POST /__editor/save-file             ({path, content, encoding?})
+ *   read     → GET  /@fs/{projectRoot}/public/{path}
+ *   watch    → EventSource /__editor/events         (chokidar-backed)
+ *
+ * The CLI control channel, native dialogs, `export`, online asset library, and
+ * project/editor-state persistence are NOT file operations and live outside this
+ * interface (see types.ts and editor-api.ts).
+ */
+
+import { bytesToBase64 } from '@volter/sdk/kit/bytes-codec';
+import { assertEditorServerAnswered, editorServerJson } from '@volter/sdk/kit/editor-server-response';
+import { sourceMutationAttribution } from '@volter/sdk/kit/editor-session-attribution';
+import { handleProjectMutationFailure } from '@volter/sdk/kit/source-conflict';
+import { dirAndBase, normalize } from './paths';
+import type { DirEntry, Stat, StorageBackend, WatchCallback, WatchEvent } from '@volter/sdk/kit/storage-types';
+
+const BASE = '/__editor';
+
+interface ServerAssetEntry {
+  name: string;
+  type: 'file' | 'directory';
+  size: number;
+  mtime: number;
+}
+
+export class HttpStorage implements StorageBackend {
+  readonly id = 'http';
+
+  /** Absolute project root on the server (used for /@fs reads). */
+  constructor(private readonly projectRoot: string) {}
+
+  async read(path: string): Promise<string> {
+    const res = await fetch(`/@fs/${this.projectRoot}/public/${normalize(path)}`);
+    if (!res.ok) throw new Error(`HttpStorage.read '${normalize(path)}': HTTP ${res.status}`);
+    return res.text();
+  }
+
+  async readBytes(path: string): Promise<Uint8Array> {
+    const res = await fetch(`/@fs/${this.projectRoot}/public/${normalize(path)}`);
+    if (!res.ok) throw new Error(`HttpStorage.readBytes '${normalize(path)}': HTTP ${res.status}`);
+    return new Uint8Array(await res.arrayBuffer());
+  }
+
+  async write(path: string, data: string | Uint8Array): Promise<void> {
+    const body =
+      typeof data === 'string'
+        ? { path: normalize(path), content: data, ...sourceMutationAttribution() }
+        : {
+            path: normalize(path),
+            content: bytesToBase64(data),
+            encoding: 'base64' as const,
+            ...sourceMutationAttribution(),
+          };
+    const res = await fetch(`${BASE}/save-file`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(body),
+    });
+    // This is the AUTOSAVE path. `!res.ok` alone let a page fallback report
+    // every save as written, so the editor kept showing saved work that no
+    // server had ever received.
+    assertEditorServerAnswered(res, `Write ${normalize(path)} failed`);
+    if (!res.ok) {
+      await handleProjectMutationFailure(res, {
+        label: `Write ${normalize(path)}`,
+        attempted: {
+          [`public/${normalize(path)}`]:
+            typeof data === 'string' ? data : `[${data.byteLength} binary bytes]`,
+        },
+        reapply: () => this.write(path, data),
+      });
+    }
+  }
+
+  async writeIfAbsent(path: string, data: string | Uint8Array): Promise<boolean> {
+    // Browser adaptation never uses HttpStorage: the Node endpoint owns its
+    // true `wx` write. Keep the interface honest for generic callers.
+    if (await this.exists(path)) return false;
+    await this.write(path, data);
+    return true;
+  }
+
+  async list(dir: string): Promise<DirEntry[]> {
+    const res = await fetch(`${BASE}/assets?${new URLSearchParams({ dir: normalize(dir) })}`);
+    const { entries } = await editorServerJson<{ entries: ServerAssetEntry[] }>(
+      res,
+      `HttpStorage.list '${normalize(dir)}' failed`,
+    );
+    return entries.map((e) => {
+      const out: DirEntry = {
+        name: e.name,
+        path: normalize(dir ? `${dir}/${e.name}` : e.name),
+        type: e.type === 'directory' ? 'dir' : 'file',
+        mtime: e.mtime,
+      };
+      if (e.type === 'file') out.size = e.size;
+      out.mtime = e.mtime;
+      return out;
+    });
+  }
+
+  async stat(path: string): Promise<Stat | null> {
+    // The server exposes listings, not a per-path stat. Derive from the parent
+    // listing — sufficient for the editor's needs (existence + type + size).
+    const [dir, base] = dirAndBase(path);
+    if (!base) return { path: '', type: 'dir', size: 0, mtime: 0 };
+    let entries: DirEntry[];
+    try {
+      entries = await this.list(dir);
+    } catch {
+      return null;
+    }
+    const hit = entries.find((e) => e.name === base);
+    return hit
+      ? { path: hit.path, type: hit.type, size: hit.size ?? 0, mtime: hit.mtime ?? 0 }
+      : null;
+  }
+
+  async exists(path: string): Promise<boolean> {
+    return (await this.stat(path)) !== null;
+  }
+
+  async mkdir(path: string): Promise<void> {
+    // The server has no empty-dir route; directories materialize when their
+    // first file is written (save-file creates parents). No-op here.
+    void path;
+  }
+
+  async remove(path: string): Promise<void> {
+    const res = await fetch(`${BASE}/save-file`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ path: normalize(path), delete: true, ...sourceMutationAttribution() }),
+    });
+    assertEditorServerAnswered(res, `Delete ${normalize(path)} failed`);
+    if (!res.ok) {
+      await handleProjectMutationFailure(res, {
+        label: `Delete ${normalize(path)}`,
+        attempted: { [`public/${normalize(path)}`]: null },
+        reapply: () => this.remove(path),
+      });
+    }
+  }
+
+  watch(callback: WatchCallback): () => void {
+    const source = new EventSource(`${BASE}/events`);
+    const handler = (ev: MessageEvent) => {
+      try {
+        const data = JSON.parse(ev.data) as { type?: string; file?: string; path?: string };
+        const path = data.path ?? data.file;
+        if (!path) return;
+        callback({ type: (data.type as WatchEvent['type']) ?? 'update', path: normalize(path) });
+      } catch {
+        // Ignore non-JSON keepalive frames.
+      }
+    };
+    source.addEventListener('message', handler);
+    return () => {
+      source.removeEventListener('message', handler);
+      source.close();
+    };
+  }
+}

package/src/kit/storage/index.ts

@@ -0,0 +1,75 @@
+/**
+ * Storage backend selection — the `public/`-rooted file interface the editor's
+ * asset surfaces read and write through.
+ *
+ * ONE TIER, two implementations, and the second is a decorator:
+ *   - `HttpStorage`      — the session's own `/__editor/*` routes.
+ *   - `HostFilesStorage` — the same view, written through `EditorHost.files`
+ *                          so a write is the WORKBENCH's own (U5).
+ * `MemStorage` is the design system's fixture backend and nothing else.
+ *
+ * Upstream code depends only on `StorageBackend` from `./types` and obtains
+ * an instance via `getStorageBackend()`.
+ */
+
+import { getProjectDefinePath } from '../editor-mode';
+import { filesProviderInstalled } from '../files/file-provider';
+import { HostFilesStorage } from './host-files-storage';
+import { HttpStorage } from './http-storage';
+import type { StorageBackend } from '@volter/sdk/kit/storage-types';
+
+export { HttpStorage } from './http-storage';
+export { MemStorage } from './mem-storage';
+export type { DirEntry, HostCapabilities, Stat, StorageBackend, WatchEvent } from '@volter/sdk/kit/storage-types';
+
+let _backend: StorageBackend | null = null;
+/** The tier's own backend, kept beside the active one so the frame decorator
+ *  never becomes its own delegate — see {@link tierStorageBackend}. */
+let _tier: StorageBackend | null = null;
+
+/**
+ * THE TIER'S OWN backend — never the frame decorator, and the only thing the
+ * file door's host fill is allowed to stand on.
+ *
+ * Without this the fill would recurse: `projectFiles.read` falls back to
+ * `getStorageBackend()`, which under the frame is `HostFilesStorage`, whose
+ * `read` is `projectFiles.read`. One function, so the cycle cannot be written
+ * by accident.
+ */
+export function tierStorageBackend(): StorageBackend {
+  if (_backend && !(_backend instanceof HostFilesStorage)) return _backend;
+  if (!_tier) _tier = new HttpStorage(getProjectDefinePath());
+  return _tier;
+}
+
+/**
+ * The active storage backend: the session's own, wrapped by the frame's file
+ * door once its provider has landed.
+ *
+ * UNDER THE CODE-OSS FRAME the file system is the WORKBENCH'S, not the
+ * session's (U5; ARCHITECTURE-CORE §The core is Code-OSS, "the storage
+ * backends → file system providers"). `HostFilesStorage` is the `public/`
+ * view onto `EditorHost.files`, so an asset write is the workbench's own write
+ * on the URI it already holds — the same property that closed U4's redo open
+ * for source files. Everything the file door does not carry (remove, mkdir,
+ * stat, list, watch) stays this tier's, which is why the decorator keeps it
+ * rather than replacing it.
+ *
+ * Read at FIRST USE rather than at module load: the bridge takes ownership
+ * before the editor mounts, but the provider arrives with the contribution's
+ * own services, after — see `files/file-provider.ts`.
+ */
+export function getStorageBackend(): StorageBackend {
+  if (_backend) return _backend;
+  const tier = tierStorageBackend();
+  _backend = filesProviderInstalled() ? new HostFilesStorage(tier) : tier;
+  return _backend;
+}
+
+/** Override the active backend (the design system's fixture). */
+export function setStorageBackend(backend: StorageBackend): void {
+  _backend = backend;
+  // An explicitly installed backend REPLACES the tier, so the file door's host
+  // fill stands on it too rather than on a stale one it would otherwise hold.
+  if (!(backend instanceof HostFilesStorage)) _tier = backend;
+}

package/src/kit/storage/mem-storage.ts

@@ -0,0 +1,158 @@
+/**
+ * Pure in-memory `StorageBackend` — a virtual filesystem backed by a `Map`.
+ *
+ * Nothing touches disk; files live as bytes in JS and vanish on reload. The
+ * most "virtual" of the backends, and the simplest — the design system's
+ * fixture (`design-system-stories/fixtures/editor-runtime.tsx`) is what uses
+ * it: a story needs a project-shaped backend and must write nothing.
+ *
+ * Implements the same interface as every other backend, so it is a drop-in via
+ * `setStorageBackend(new MemStorage())`.
+ */
+
+import { dirAndBase, normalize } from './paths';
+import type { DirEntry, Stat, StorageBackend, WatchCallback, WatchEvent } from '@volter/sdk/kit/storage-types';
+
+type Node = { type: 'file'; data: Uint8Array; mtime: number } | { type: 'dir'; mtime: number };
+
+export class MemStorage implements StorageBackend {
+  readonly id = 'mem';
+
+  /** Normalized path → node. The root (`''`) is implicit. */
+  private readonly nodes = new Map<string, Node>();
+  private readonly watchers = new Set<WatchCallback>();
+
+  /** Optionally seed the VFS from a `{ path: contents }` map. */
+  constructor(seed?: Record<string, string | Uint8Array>) {
+    if (seed) for (const [path, data] of Object.entries(seed)) this.writeSync(path, data);
+  }
+
+  private emit(event: WatchEvent): void {
+    for (const cb of this.watchers) cb(event);
+  }
+
+  /** Ensure every ancestor directory of `path` exists. */
+  private ensureParents(path: string): void {
+    const parts = normalize(path).split('/');
+    parts.pop();
+    let cur = '';
+    for (const part of parts) {
+      cur = cur ? `${cur}/${part}` : part;
+      if (this.nodes.get(cur)?.type !== 'dir') this.nodes.set(cur, { type: 'dir', mtime: now() });
+    }
+  }
+
+  private writeSync(path: string, data: string | Uint8Array): boolean {
+    const norm = normalize(path);
+    this.ensureParents(norm);
+    const existed = this.nodes.get(norm)?.type === 'file';
+    const bytes = typeof data === 'string' ? new TextEncoder().encode(data) : new Uint8Array(data);
+    this.nodes.set(norm, { type: 'file', data: bytes, mtime: now() });
+    return existed;
+  }
+
+  /**
+   * Put bytes in place WITHOUT announcing a change: a backend that fills itself lazily from
+   * somewhere else (the limited view's seed, `editor-core/view/page/project-store.ts`) is not
+   * editing the file when its first read arrives, so no watcher may hear it as one.
+   */
+  seed(path: string, data: string | Uint8Array): void {
+    this.writeSync(path, data);
+  }
+
+  async read(path: string): Promise<string> {
+    return new TextDecoder().decode(await this.readBytes(path));
+  }
+
+  async readBytes(path: string): Promise<Uint8Array> {
+    const node = this.nodes.get(normalize(path));
+    if (node?.type !== 'file')
+      throw new Error(`MemStorage.read: no such file '${normalize(path)}'`);
+    // Reads own their bytes, just like File/HTTP backends. Asset serving
+    // transfers this buffer to a worker; sharing the stored buffer would
+    // detach the file itself and break every subsequent read.
+    return node.data.slice();
+  }
+
+  async write(path: string, data: string | Uint8Array): Promise<void> {
+    const existed = this.writeSync(path, data);
+    this.emit({ type: existed ? 'update' : 'create', path: normalize(path) });
+  }
+
+  async writeIfAbsent(path: string, data: string | Uint8Array): Promise<boolean> {
+    if (await this.exists(path)) return false;
+    this.writeSync(path, data);
+    this.emit({ type: 'create', path: normalize(path) });
+    return true;
+  }
+
+  async list(dir: string): Promise<DirEntry[]> {
+    const dn = normalize(dir);
+    if (dn !== '' && this.nodes.get(dn)?.type !== 'dir') {
+      throw new Error(`MemStorage.list: no such directory '${dn}'`);
+    }
+    const entries: DirEntry[] = [];
+    for (const [path, node] of this.nodes) {
+      const [parent, base] = dirAndBase(path);
+      if (parent !== dn || !base) continue;
+      const entry: DirEntry = {
+        name: base,
+        path,
+        type: node.type === 'dir' ? 'dir' : 'file',
+        mtime: node.mtime,
+      };
+      if (node.type === 'file') entry.size = node.data.length;
+      entry.mtime = node.mtime;
+      entries.push(entry);
+    }
+    entries.sort((a, b) => {
+      if (a.type !== b.type) return a.type === 'dir' ? -1 : 1;
+      return a.name.localeCompare(b.name);
+    });
+    return entries;
+  }
+
+  async stat(path: string): Promise<Stat | null> {
+    const norm = normalize(path);
+    if (norm === '') return { path: '', type: 'dir', size: 0, mtime: 0 };
+    const node = this.nodes.get(norm);
+    if (!node) return null;
+    return node.type === 'file'
+      ? { path: norm, type: 'file', size: node.data.length, mtime: node.mtime }
+      : { path: norm, type: 'dir', size: 0, mtime: node.mtime };
+  }
+
+  async exists(path: string): Promise<boolean> {
+    return (await this.stat(path)) !== null;
+  }
+
+  async mkdir(path: string): Promise<void> {
+    const norm = normalize(path);
+    if (!norm || this.nodes.get(norm)?.type === 'dir') return;
+    this.ensureParents(norm);
+    this.nodes.set(norm, { type: 'dir', mtime: now() });
+    this.emit({ type: 'create', path: norm });
+  }
+
+  async remove(path: string): Promise<void> {
+    const norm = normalize(path);
+    if (!norm) return;
+    let removed = false;
+    for (const key of [...this.nodes.keys()]) {
+      if (key === norm || key.startsWith(`${norm}/`)) {
+        this.nodes.delete(key);
+        removed = true;
+      }
+    }
+    if (removed) this.emit({ type: 'remove', path: norm });
+  }
+
+  watch(callback: WatchCallback): () => void {
+    this.watchers.add(callback);
+    return () => this.watchers.delete(callback);
+  }
+}
+
+function now(): number {
+  return Date.now();
+}

package/src/kit/storage/path-lock.ts

@@ -0,0 +1,44 @@
+/**
+ * The one cross-realm mutual exclusion a browser storage backend has:
+ * `navigator.locks`, keyed by backend id + path.
+ *
+ * Two callers matter and they MUST agree on the name, which is why this is a
+ * shared function rather than a string built at each site — and why the name is
+ * derived from the NORMALIZED path here rather than from whatever each caller
+ * happens to hold. Sharing the function is not enough on its own: one caller
+ * passes an already-normalized path and the other passes a module constant, so
+ * agreement used to rest on that constant being spelled in normalized form.
+ * Respell it as `/.volter/assets.json` and the two names diverge, both locks are
+ * "held", and mutual exclusion is silently gone with nothing failing. Deriving
+ * the name from `normalize()` makes the agreement structural.
+ *
+ * Callers:
+ *   - the asset ledger's `.lock` compare-and-delete
+ *     (`../asset-workflow/asset-ledger-backend.ts`) — several steps that must
+ *     not interleave with each other OR with the create above.
+ *
+ * Scope, stated exactly: Web Locks span every same-origin realm — the two
+ * tabs on one project that motivate the ledger lock in the first place — and
+ * nothing else. A writer that is not same-origin JS (a Node process
+ * reaching the same files, i.e. `HttpStorage` racing the CLI) is not serialized
+ * by this, and cannot be from the browser side.
+ *
+ * Absent in a non-secure context and in Node (tests): callers then get the bare
+ * operation, which is the same exclusivity the platform itself offers.
+ */
+import { normalize } from '@volter/sdk/kit/storage/paths';
+
+export function withPathLock<T>(
+  backendId: string,
+  path: string,
+  operation: () => Promise<T>,
+): Promise<T> {
+  const locks = globalThis.navigator?.locks;
+  if (!locks) return operation();
+  // `LockManager.request`'s DOM typing infers its result from the callback's
+  // literal return type (`(lock) => T`), so an async callback types as
+  // `Promise<Promise<T>>`. The platform awaits the returned promise before
+  // releasing the lock — that flattening is the documented behavior, not an
+  // assumption — so the settled value really is `T`.
+  return locks.request(`volter:${backendId}:${normalize(path)}`, operation) as Promise<T>;
+}

package/src/kit/storage/paths.ts

@@ -0,0 +1,26 @@
+/**
+ * Path helpers for storage backends. Paths are POSIX-style, root-relative,
+ * '/'-separated, with no leading/trailing slashes.
+ */
+
+/** Split a path into non-empty segments, collapsing `.` and redundant slashes. */
+export function segments(path: string): string[] {
+  return path.split('/').filter((s) => s.length > 0 && s !== '.');
+}
+
+/** Normalize to a canonical root-relative path (`''` for the root). */
+export function normalize(path: string): string {
+  return segments(path).join('/');
+}
+
+/** Split into `[parentDir, baseName]`. Root entries have `parent === ''`. */
+export function dirAndBase(path: string): [string, string] {
+  const segs = segments(path);
+  const base = segs.pop() ?? '';
+  return [segs.join('/'), base];
+}
+
+/** Join path parts into a normalized path. */
+export function join(...parts: string[]): string {
+  return normalize(parts.join('/'));
+}