@statewalker/webrun-storage 0.0.0-stage → 0.2.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024-present StateWalker Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,108 @@
-# Temporary Holding Version
+# @statewalker/webrun-storage
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+## What it is
+
+A small byte-persistence layer with two primitives: an immutable `BlobStore` keyed by a
+caller-supplied id, and a mutable `KvStore` with atomic compare-and-set. A `RefStore` facade
+stores string ids on top of a `KvStore`. Adapters are included for memory and for any
+`FilesApi` from `@statewalker/webrun-files`.
+
+## Why it exists
+
+Higher layers (a chunked content store, a git object store, ref tables) all need the same two
+things from a backend: write an immutable blob under a known id, and update a pointer atomically.
+This package defines exactly that contract and nothing more. A new backend (SQL, KV, cloud
+object storage) implements two interfaces, and every layer above works on it unchanged.
+
+## How to use
+
+```bash
+pnpm add @statewalker/webrun-storage
+```
+
+| Import | Contents |
+| --- | --- |
+| `@statewalker/webrun-storage` | `memBlobStore`, `memKvStore`, `filesBlobStore`, `refStore`, and the types `BlobStore`, `KvStore`, `RefStore`, `ObjectStore`, `ByteStream`, `FilesBlobStoreOptions`. ESM, runs in browsers, Node and workers. |
+
+`BlobStore`:
+
+- `put(id, bytes, opts?)`: stores a byte stream. Re-putting the same id is idempotent.
+  `opts.verify(bytes)` re-derives the id; on mismatch `put` rejects and stores nothing.
+- `get(id, range?)`: byte stream; `range` is `{ start?, end? }` with `end` exclusive. An absent id
+  yields an empty stream.
+- `has(id)`, `remove(id)` (resolves `false` if absent), `size(id)` (`-1` if absent),
+  `list(prefix?)`.
+
+`KvStore`: `get`, `put`, `remove`, `list(prefix?)`, and `cas(key, expected, next)`, which writes
+and returns `true` only when the current value equals `expected` byte for byte. `expected ===
+undefined` means "must not exist"; `next === undefined` deletes.
+
+`RefStore`: `read(name)`, `compareAndSet(name, expected, next)`, `list(prefix?)`, all with string
+ids. `ObjectStore` is an alias of `BlobStore`.
+
+## Examples
+
+Blobs in memory and over a `FilesApi`:
+
+```typescript
+import { MemFilesApi } from "@statewalker/webrun-files-mem";
+import { filesBlobStore, memBlobStore } from "@statewalker/webrun-storage";
+
+async function* streamOf(...parts: string[]) {
+  for (const p of parts) yield new TextEncoder().encode(p);
+}
+
+const blobs = memBlobStore();
+await blobs.put("a1b2c3", streamOf("hello ", "world")); // the caller owns the id
+await blobs.size("a1b2c3"); // 11
+const tail = blobs.get("a1b2c3", { start: 6 }); // "world"
+
+const onDisk = filesBlobStore(new MemFilesApi(), { root: "/objects" });
+await onDisk.put("a1b2c3", streamOf("hello")); // stored at /objects/a1/b2c3
+```
+
+Atomic pointer updates:
+
+```typescript
+import { memKvStore, refStore } from "@statewalker/webrun-storage";
+
+const refs = refStore(memKvStore());
+await refs.compareAndSet("refs/heads/main", undefined, "commit-1"); // true: created
+await refs.compareAndSet("refs/heads/main", "commit-0", "commit-2"); // false: lost the race
+await refs.read("refs/heads/main"); // "commit-1"
+```
+
+## Internals
+
+### Ids belong to the caller
+
+`put` never hashes. A git store passes git object ids, a chunk store passes its own chunk hashes.
+The package therefore depends on no hash library and works with any id scheme. Integrity checking
+is opt-in through `verify`; a mismatch fails with
+`blob id mismatch: supplied "<id>", verify computed "<computed>"`.
+
+### Compare-and-set is part of the contract
+
+`cas` is a required method, not an optional capability, so `RefStore` can always offer atomic
+updates without checking what the backend supports. The in-memory adapter is atomic because
+JavaScript runs it in one turn.
+
+### One backend object per blob
+
+`filesBlobStore` writes each blob to its own file, sharded like git's loose objects:
+`<root>/<first two chars>/<rest>`. Ids shorter than three characters produce odd paths; use
+hash-like ids. Packing and chunk grouping are left to the layers above.
+
+### Ranged reads
+
+`get(id, { start, end })` matches the usual "inclusive start, exclusive end" slice convention, so
+random access into pack files and large blobs needs no full read.
+
+### Dependencies
+
+Only `@statewalker/webrun-files`, for the `FilesApi` type used by `filesBlobStore`. No runtime
+dependencies.
+
+## License
+
+MIT

package/dist/blob-store.d.ts

@@ -0,0 +1,10 @@
+import type { ByteStream } from "./types.js";
+/** Wrap already-collected chunks as a re-readable byte stream. */
+export declare function toStream(chunks: Uint8Array[]): ByteStream;
+/**
+ * Run the optional integrity check for a blob `put`. Rejects when the caller's
+ * `verify` re-derives an id that differs from the supplied one. Shared by every
+ * {@link import("./types.js").BlobStore} adapter so the flag behaves identically.
+ */
+export declare function assertVerified(id: string, chunks: Uint8Array[], verify?: (bytes: ByteStream) => Promise<string>): Promise<void>;
+//# sourceMappingURL=blob-store.d.ts.map

package/dist/blob-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"blob-store.d.ts","sourceRoot":"","sources":["../src/blob-store.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAE7C,kEAAkE;AAClE,wBAAuB,QAAQ,CAAC,MAAM,EAAE,UAAU,EAAE,GAAG,UAAU,CAEhE;AAED;;;;GAIG;AACH,wBAAsB,cAAc,CAClC,EAAE,EAAE,MAAM,EACV,MAAM,EAAE,UAAU,EAAE,EACpB,MAAM,CAAC,EAAE,CAAC,KAAK,EAAE,UAAU,KAAK,OAAO,CAAC,MAAM,CAAC,GAC9C,OAAO,CAAC,IAAI,CAAC,CAMf"}

package/dist/facades.d.ts

@@ -0,0 +1,8 @@
+import type { KvStore, RefStore } from "./types.js";
+/**
+ * Build a {@link RefStore} over a {@link KvStore}: string ids are stored as
+ * UTF-8 bytes and `compareAndSet` maps directly onto {@link KvStore.cas}, so the
+ * facade reuses the primitive's atomicity rather than re-implementing storage.
+ */
+export declare function refStore(kv: KvStore): RefStore;
+//# sourceMappingURL=facades.d.ts.map

package/dist/facades.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"facades.d.ts","sourceRoot":"","sources":["../src/facades.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAEpD;;;;GAIG;AACH,wBAAgB,QAAQ,CAAC,EAAE,EAAE,OAAO,GAAG,QAAQ,CAoB9C"}

package/dist/files-blob-store.d.ts

@@ -0,0 +1,12 @@
+import type { FilesApi } from "@statewalker/webrun-files";
+import type { BlobStore } from "./types.js";
+export interface FilesBlobStoreOptions {
+    /** Directory the sharded blob tree lives under. Defaults to `/`. */
+    root?: string;
+}
+/**
+ * {@link BlobStore} backed by a {@link FilesApi}. Ids map to git-style sharded
+ * paths (`ab/cdef…`) so a large id space never lands in one flat directory.
+ */
+export declare function filesBlobStore(files: FilesApi, opts?: FilesBlobStoreOptions): BlobStore;
+//# sourceMappingURL=files-blob-store.d.ts.map

package/dist/files-blob-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"files-blob-store.d.ts","sourceRoot":"","sources":["../src/files-blob-store.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,2BAA2B,CAAC;AAE1D,OAAO,KAAK,EAAE,SAAS,EAAc,MAAM,YAAY,CAAC;AAExD,MAAM,WAAW,qBAAqB;IACpC,oEAAoE;IACpE,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,QAAQ,EAAE,IAAI,CAAC,EAAE,qBAAqB,GAAG,SAAS,CAkDvF"}

package/dist/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * @statewalker/webrun-storage
+ *
+ * Domain-neutral byte-persistence seam: an immutable content-addressed
+ * {@link BlobStore} and a mutable {@link KvStore} with atomic compare-and-set,
+ * plus a thin {@link RefStore} facade — all over the webrun-files FilesApi.
+ * The seam stores bytes; it knows nothing of git objects, chunks, or hashing.
+ */
+export { refStore } from "./facades.js";
+export { type FilesBlobStoreOptions, filesBlobStore } from "./files-blob-store.js";
+export { memBlobStore, memKvStore } from "./mem.js";
+export type { BlobStore, ByteStream, KvStore, ObjectStore, RefStore } from "./types.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAC;AACxC,OAAO,EAAE,KAAK,qBAAqB,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACnF,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AACpD,YAAY,EAAE,SAAS,EAAE,UAAU,EAAE,OAAO,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -0,0 +1,181 @@
+//#region src/facades.ts
+/**
+* Build a {@link RefStore} over a {@link KvStore}: string ids are stored as
+* UTF-8 bytes and `compareAndSet` maps directly onto {@link KvStore.cas}, so the
+* facade reuses the primitive's atomicity rather than re-implementing storage.
+*/
+function refStore(kv) {
+	const encoder = new TextEncoder();
+	const decoder = new TextDecoder();
+	const encode = (s) => s === void 0 ? void 0 : encoder.encode(s);
+	return {
+		async read(name) {
+			const value = await kv.get(name);
+			return value === void 0 ? void 0 : decoder.decode(value);
+		},
+		compareAndSet(name, expected, next) {
+			return kv.cas(name, encode(expected), encode(next));
+		},
+		async *list(prefix) {
+			for await (const { key, value } of kv.list(prefix)) yield {
+				name: key,
+				id: decoder.decode(value)
+			};
+		}
+	};
+}
+//#endregion
+//#region src/blob-store.ts
+/** Wrap already-collected chunks as a re-readable byte stream. */
+async function* toStream(chunks) {
+	yield* chunks;
+}
+/**
+* Run the optional integrity check for a blob `put`. Rejects when the caller's
+* `verify` re-derives an id that differs from the supplied one. Shared by every
+* {@link import("./types.js").BlobStore} adapter so the flag behaves identically.
+*/
+async function assertVerified(id, chunks, verify) {
+	if (!verify) return;
+	const computed = await verify(toStream(chunks));
+	if (computed !== id) throw new Error(`blob id mismatch: supplied "${id}", verify computed "${computed}"`);
+}
+//#endregion
+//#region src/files-blob-store.ts
+/**
+* {@link BlobStore} backed by a {@link FilesApi}. Ids map to git-style sharded
+* paths (`ab/cdef…`) so a large id space never lands in one flat directory.
+*/
+function filesBlobStore(files, opts) {
+	const base = (opts?.root ?? "/").replace(/\/+$/, "");
+	const pathFor = (id) => `${base}/${id.slice(0, 2)}/${id.slice(2)}`;
+	const idFrom = (relative) => relative.replace("/", "");
+	return {
+		async put(id, bytes, opts) {
+			const path = pathFor(id);
+			if (opts?.verify) {
+				const chunks = [];
+				for await (const chunk of bytes) chunks.push(chunk);
+				await assertVerified(id, chunks, opts.verify);
+				await files.write(path, chunks);
+			} else await files.write(path, bytes);
+		},
+		get(id, range) {
+			if (!range) return files.read(pathFor(id));
+			const start = range.start ?? 0;
+			const length = range.end !== void 0 ? range.end - start : void 0;
+			return files.read(pathFor(id), {
+				start,
+				length
+			});
+		},
+		async has(id) {
+			return files.exists(pathFor(id));
+		},
+		async size(id) {
+			const stats = await files.stats(pathFor(id));
+			return stats?.kind === "file" ? stats.size : -1;
+		},
+		async remove(id) {
+			return files.remove(pathFor(id));
+		},
+		async *list(prefix) {
+			const rootPath = base === "" ? "/" : base;
+			const cut = rootPath === "/" ? 1 : rootPath.length + 1;
+			for await (const info of files.list(rootPath, { recursive: true })) {
+				if (info.kind !== "file") continue;
+				const id = idFrom(info.path.slice(cut));
+				if (prefix === void 0 || id.startsWith(prefix)) yield id;
+			}
+		}
+	};
+}
+//#endregion
+//#region src/mem.ts
+/** In-memory {@link BlobStore}. Chunks are kept as a list (never one big concat). */
+function memBlobStore() {
+	const store = /* @__PURE__ */ new Map();
+	return {
+		async put(id, bytes, opts) {
+			const chunks = [];
+			for await (const chunk of bytes) chunks.push(chunk);
+			await assertVerified(id, chunks, opts?.verify);
+			store.set(id, chunks);
+		},
+		get(id, range) {
+			const chunks = store.get(id) ?? [];
+			return toStream(range ? sliceChunks(chunks, range) : chunks);
+		},
+		async has(id) {
+			return store.has(id);
+		},
+		async size(id) {
+			const chunks = store.get(id);
+			if (chunks === void 0) return -1;
+			return chunks.reduce((n, c) => n + c.length, 0);
+		},
+		async remove(id) {
+			return store.delete(id);
+		},
+		async *list(prefix) {
+			for (const id of store.keys()) if (prefix === void 0 || id.startsWith(prefix)) yield id;
+		}
+	};
+}
+/**
+* Return the `[start, end)` slice of a chunk list (end exclusive, start default
+* 0, end default total length) as a new chunk list — mirrors RawStorage.load.
+*/
+function sliceChunks(chunks, range) {
+	const start = range.start ?? 0;
+	const total = chunks.reduce((n, c) => n + c.length, 0);
+	const end = range.end ?? total;
+	const out = [];
+	let pos = 0;
+	for (const chunk of chunks) {
+		const chunkStart = pos;
+		const chunkEnd = pos + chunk.length;
+		pos = chunkEnd;
+		if (chunkEnd <= start || chunkStart >= end) continue;
+		const from = Math.max(start, chunkStart) - chunkStart;
+		const to = Math.min(end, chunkEnd) - chunkStart;
+		out.push(chunk.subarray(from, to));
+	}
+	return out;
+}
+function bytesEqual(a, b) {
+	if (a === void 0 || b === void 0) return a === b;
+	if (a.length !== b.length) return false;
+	for (let i = 0; i < a.length; i++) if (a[i] !== b[i]) return false;
+	return true;
+}
+/** In-memory {@link KvStore} with a natively-atomic compare-and-set. */
+function memKvStore() {
+	const store = /* @__PURE__ */ new Map();
+	return {
+		async get(key) {
+			const v = store.get(key);
+			return v === void 0 ? void 0 : v.slice();
+		},
+		async put(key, value) {
+			store.set(key, value.slice());
+		},
+		async cas(key, expected, next) {
+			if (!bytesEqual(store.get(key), expected)) return false;
+			if (next === void 0) store.delete(key);
+			else store.set(key, next.slice());
+			return true;
+		},
+		async remove(key) {
+			return store.delete(key);
+		},
+		async *list(prefix) {
+			for (const [key, value] of store) if (prefix === void 0 || key.startsWith(prefix)) yield {
+				key,
+				value: value.slice()
+			};
+		}
+	};
+}
+//#endregion
+export { filesBlobStore, memBlobStore, memKvStore, refStore };

package/dist/mem.d.ts

@@ -0,0 +1,6 @@
+import type { BlobStore, KvStore } from "./types.js";
+/** In-memory {@link BlobStore}. Chunks are kept as a list (never one big concat). */
+export declare function memBlobStore(): BlobStore;
+/** In-memory {@link KvStore} with a natively-atomic compare-and-set. */
+export declare function memKvStore(): KvStore;
+//# sourceMappingURL=mem.d.ts.map

package/dist/mem.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mem.d.ts","sourceRoot":"","sources":["../src/mem.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAc,OAAO,EAAE,MAAM,YAAY,CAAC;AAEjE,qFAAqF;AACrF,wBAAgB,YAAY,IAAI,SAAS,CA8BxC;AAiCD,wEAAwE;AACxE,wBAAgB,UAAU,IAAI,OAAO,CA8BpC"}

package/dist/types.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Public contract for the domain-neutral byte-persistence seam.
+ *
+ * Two low-level primitives — an immutable content-addressed {@link BlobStore}
+ * and a mutable {@link KvStore} with atomic compare-and-set — plus thin typed
+ * facades built over them. The seam stores bytes: it knows nothing of git
+ * objects, chunks, or hashing. The caller owns every id (storage is
+ * hash-agnostic).
+ */
+/** A stream of bytes, as produced by {@link import("@statewalker/webrun-files").FilesApi.read}. */
+export type ByteStream = AsyncIterable<Uint8Array>;
+/**
+ * Immutable, content-addressed byte store keyed by a caller-supplied id.
+ *
+ * `put` is idempotent for a given id: because the id names the content, a
+ * re-put of the same id overwrites with identical bytes and never errors.
+ */
+export interface BlobStore {
+    /**
+     * Store `bytes` under `id`. Streaming and bounded-memory — the payload is
+     * never buffered into one contiguous allocation. When `opts.verify` is given,
+     * the re-derived id must equal `id`, otherwise `put` rejects and stores nothing.
+     */
+    put(id: string, bytes: ByteStream, opts?: {
+        verify?: (bytes: ByteStream) => Promise<string>;
+    }): Promise<void>;
+    /**
+     * Read the blob's bytes. Yields an empty stream if the id is absent (FilesApi
+     * convention).
+     *
+     * The optional `range` reads a partial slice, matching `RawStorage.load`'s
+     * semantics exactly so an adapter is a straight pass-through: `start` is the
+     * inclusive byte offset (default 0) and `end` is the **exclusive** upper bound
+     * (default end of content). `{ start }` reads from `start` to the end;
+     * `{ end }` reads `[0, end)`. Existing callers pass nothing and are unaffected.
+     */
+    get(id: string, range?: {
+        start?: number;
+        end?: number;
+    }): ByteStream;
+    has(id: string): Promise<boolean>;
+    /** Remove the blob; resolves `true` if something was removed, `false` if absent. */
+    remove(id: string): Promise<boolean>;
+    /**
+     * Byte length of the stored blob, or `-1` if the id is absent — matching
+     * `RawStorage.size`.
+     */
+    size(id: string): Promise<number>;
+    /** Ids currently stored, optionally filtered by prefix. */
+    list(prefix?: string): AsyncIterable<string>;
+}
+/**
+ * `BlobStore` keyed by a git object id. The seam adds no git semantics, so this
+ * is a plain alias; `content-store` callers use {@link BlobStore} directly.
+ */
+export type ObjectStore = BlobStore;
+/** Mutable keyed byte store with an atomic compare-and-set. */
+export interface KvStore {
+    get(key: string): Promise<Uint8Array | undefined>;
+    put(key: string, value: Uint8Array): Promise<void>;
+    /**
+     * Atomic compare-and-set. Writes `next` and returns `true` iff the current
+     * value deep-equals `expected` (both-undefined counts as a match, i.e. create).
+     * On mismatch returns `false` and writes nothing. `next === undefined` deletes.
+     */
+    cas(key: string, expected: Uint8Array | undefined, next: Uint8Array | undefined): Promise<boolean>;
+    remove(key: string): Promise<boolean>;
+    list(prefix?: string): AsyncIterable<{
+        key: string;
+        value: Uint8Array;
+    }>;
+}
+/** Thin facade over a {@link KvStore} that stores string ids as UTF-8 bytes. */
+export interface RefStore {
+    read(name: string): Promise<string | undefined>;
+    compareAndSet(name: string, expected: string | undefined, next: string | undefined): Promise<boolean>;
+    list(prefix?: string): AsyncIterable<{
+        name: string;
+        id: string;
+    }>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,mGAAmG;AACnG,MAAM,MAAM,UAAU,GAAG,aAAa,CAAC,UAAU,CAAC,CAAC;AAEnD;;;;;GAKG;AACH,MAAM,WAAW,SAAS;IACxB;;;;OAIG;IACH,GAAG,CACD,EAAE,EAAE,MAAM,EACV,KAAK,EAAE,UAAU,EACjB,IAAI,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,CAAC,KAAK,EAAE,UAAU,KAAK,OAAO,CAAC,MAAM,CAAC,CAAA;KAAE,GACzD,OAAO,CAAC,IAAI,CAAC,CAAC;IACjB;;;;;;;;;OASG;IACH,GAAG,CAAC,EAAE,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,GAAG,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,UAAU,CAAC;IACtE,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAClC,oFAAoF;IACpF,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACrC;;;OAGG;IACH,IAAI,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAClC,2DAA2D;IAC3D,IAAI,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,aAAa,CAAC,MAAM,CAAC,CAAC;CAC9C;AAED;;;GAGG;AACH,MAAM,MAAM,WAAW,GAAG,SAAS,CAAC;AAEpC,+DAA+D;AAC/D,MAAM,WAAW,OAAO;IACtB,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,GAAG,SAAS,CAAC,CAAC;IAClD,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACnD;;;;OAIG;IACH,GAAG,CACD,GAAG,EAAE,MAAM,EACX,QAAQ,EAAE,UAAU,GAAG,SAAS,EAChC,IAAI,EAAE,UAAU,GAAG,SAAS,GAC3B,OAAO,CAAC,OAAO,CAAC,CAAC;IACpB,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACtC,IAAI,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,aAAa,CAAC;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,UAAU,CAAA;KAAE,CAAC,CAAC;CAC1E;AAED,gFAAgF;AAChF,MAAM,WAAW,QAAQ;IACvB,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC;IAChD,aAAa,CACX,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,MAAM,GAAG,SAAS,EAC5B,IAAI,EAAE,MAAM,GAAG,SAAS,GACvB,OAAO,CAAC,OAAO,CAAC,CAAC;IACpB,IAAI,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,aAAa,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,EAAE,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CACpE"}

package/package.json

@@ -1,6 +1,54 @@
 {
   "name": "@statewalker/webrun-storage",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.2.2",
+  "description": "Domain-neutral byte-persistence seam (BlobStore + KvStore with CAS) over the webrun-files FilesApi",
+  "bugs": {
+    "url": "https://github.com/statewalker/webrun-sync/issues"
+  },
+  "homepage": "https://github.com/statewalker/webrun-sync/tree/main/packages/webrun-storage#readme",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/statewalker/webrun-sync.git",
+    "directory": "packages/webrun-storage"
+  },
+  "private": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "source": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "dependencies": {
+    "@statewalker/webrun-files": "^0.10.0"
+  },
+  "devDependencies": {
+    "@statewalker/webrun-files-mem": "^0.10.0",
+    "rolldown": "^1.2.12",
+    "vitest": "^5.0.3",
+    "typescript": "^7.0.2",
+    "@types/node": "^26.6.4"
+  },
+  "scripts": {
+    "build": "rm -rf dist && rolldown -c && tsc --emitDeclarationOnly --declaration",
+    "test": "vitest run",
+    "lint": "biome check --write .",
+    "lint:check": "biome check .",
+    "lint:fix": "biome check --write --unsafe .",
+    "format": "biome format --write .",
+    "format:check": "biome format .",
+    "format:fix": "biome check --write --unsafe .",
+    "typecheck": "tsc --noEmit"
+  }
 }

package/src/blob-store.ts

@@ -0,0 +1,23 @@
+import type { ByteStream } from "./types.js";
+
+/** Wrap already-collected chunks as a re-readable byte stream. */
+export async function* toStream(chunks: Uint8Array[]): ByteStream {
+  yield* chunks;
+}
+
+/**
+ * Run the optional integrity check for a blob `put`. Rejects when the caller's
+ * `verify` re-derives an id that differs from the supplied one. Shared by every
+ * {@link import("./types.js").BlobStore} adapter so the flag behaves identically.
+ */
+export async function assertVerified(
+  id: string,
+  chunks: Uint8Array[],
+  verify?: (bytes: ByteStream) => Promise<string>,
+): Promise<void> {
+  if (!verify) return;
+  const computed = await verify(toStream(chunks));
+  if (computed !== id) {
+    throw new Error(`blob id mismatch: supplied "${id}", verify computed "${computed}"`);
+  }
+}

package/src/facades.ts

@@ -0,0 +1,28 @@
+import type { KvStore, RefStore } from "./types.js";
+
+/**
+ * Build a {@link RefStore} over a {@link KvStore}: string ids are stored as
+ * UTF-8 bytes and `compareAndSet` maps directly onto {@link KvStore.cas}, so the
+ * facade reuses the primitive's atomicity rather than re-implementing storage.
+ */
+export function refStore(kv: KvStore): RefStore {
+  const encoder = new TextEncoder();
+  const decoder = new TextDecoder();
+  const encode = (s: string | undefined): Uint8Array | undefined =>
+    s === undefined ? undefined : encoder.encode(s);
+
+  return {
+    async read(name) {
+      const value = await kv.get(name);
+      return value === undefined ? undefined : decoder.decode(value);
+    },
+    compareAndSet(name, expected, next) {
+      return kv.cas(name, encode(expected), encode(next));
+    },
+    async *list(prefix) {
+      for await (const { key, value } of kv.list(prefix)) {
+        yield { name: key, id: decoder.decode(value) };
+      }
+    },
+  };
+}

package/src/files-blob-store.ts

@@ -0,0 +1,64 @@
+import type { FilesApi } from "@statewalker/webrun-files";
+import { assertVerified } from "./blob-store.js";
+import type { BlobStore, ByteStream } from "./types.js";
+
+export interface FilesBlobStoreOptions {
+  /** Directory the sharded blob tree lives under. Defaults to `/`. */
+  root?: string;
+}
+
+/**
+ * {@link BlobStore} backed by a {@link FilesApi}. Ids map to git-style sharded
+ * paths (`ab/cdef…`) so a large id space never lands in one flat directory.
+ */
+export function filesBlobStore(files: FilesApi, opts?: FilesBlobStoreOptions): BlobStore {
+  const base = (opts?.root ?? "/").replace(/\/+$/, "");
+
+  const pathFor = (id: string): string => `${base}/${id.slice(0, 2)}/${id.slice(2)}`;
+  const idFrom = (relative: string): string => relative.replace("/", "");
+
+  return {
+    async put(id, bytes, opts) {
+      const path = pathFor(id);
+      if (opts?.verify) {
+        // Verify needs the bytes replayed to the caller's hash, so buffer the
+        // chunk list (not one contiguous concat), check, then write.
+        const chunks: Uint8Array[] = [];
+        for await (const chunk of bytes) chunks.push(chunk);
+        await assertVerified(id, chunks, opts.verify);
+        await files.write(path, chunks);
+      } else {
+        // No verify: pass the stream straight through — the backend drives
+        // iteration, so nothing is buffered up front.
+        await files.write(path, bytes);
+      }
+    },
+    get(id, range): ByteStream {
+      if (!range) return files.read(pathFor(id));
+      // FilesApi.read takes {start,length}; our range is {start,end} with end
+      // exclusive — translate length = end - start (undefined ⇒ read to end).
+      const start = range.start ?? 0;
+      const length = range.end !== undefined ? range.end - start : undefined;
+      return files.read(pathFor(id), { start, length });
+    },
+    async has(id) {
+      return files.exists(pathFor(id));
+    },
+    async size(id) {
+      const stats = await files.stats(pathFor(id));
+      return stats?.kind === "file" ? stats.size : -1;
+    },
+    async remove(id) {
+      return files.remove(pathFor(id));
+    },
+    async *list(prefix) {
+      const rootPath = base === "" ? "/" : base;
+      const cut = rootPath === "/" ? 1 : rootPath.length + 1;
+      for await (const info of files.list(rootPath, { recursive: true })) {
+        if (info.kind !== "file") continue;
+        const id = idFrom(info.path.slice(cut));
+        if (prefix === undefined || id.startsWith(prefix)) yield id;
+      }
+    },
+  };
+}

package/src/index.ts

@@ -0,0 +1,13 @@
+/**
+ * @statewalker/webrun-storage
+ *
+ * Domain-neutral byte-persistence seam: an immutable content-addressed
+ * {@link BlobStore} and a mutable {@link KvStore} with atomic compare-and-set,
+ * plus a thin {@link RefStore} facade — all over the webrun-files FilesApi.
+ * The seam stores bytes; it knows nothing of git objects, chunks, or hashing.
+ */
+
+export { refStore } from "./facades.js";
+export { type FilesBlobStoreOptions, filesBlobStore } from "./files-blob-store.js";
+export { memBlobStore, memKvStore } from "./mem.js";
+export type { BlobStore, ByteStream, KvStore, ObjectStore, RefStore } from "./types.js";

package/src/mem.ts

@@ -0,0 +1,99 @@
+import { assertVerified, toStream } from "./blob-store.js";
+import type { BlobStore, ByteStream, KvStore } from "./types.js";
+
+/** In-memory {@link BlobStore}. Chunks are kept as a list (never one big concat). */
+export function memBlobStore(): BlobStore {
+  const store = new Map<string, Uint8Array[]>();
+  return {
+    async put(id, bytes, opts) {
+      const chunks: Uint8Array[] = [];
+      for await (const chunk of bytes) chunks.push(chunk);
+      await assertVerified(id, chunks, opts?.verify);
+      store.set(id, chunks);
+    },
+    get(id, range): ByteStream {
+      const chunks = store.get(id) ?? [];
+      return toStream(range ? sliceChunks(chunks, range) : chunks);
+    },
+    async has(id) {
+      return store.has(id);
+    },
+    async size(id) {
+      const chunks = store.get(id);
+      if (chunks === undefined) return -1;
+      return chunks.reduce((n, c) => n + c.length, 0);
+    },
+    async remove(id) {
+      return store.delete(id);
+    },
+    async *list(prefix) {
+      for (const id of store.keys()) {
+        if (prefix === undefined || id.startsWith(prefix)) yield id;
+      }
+    },
+  };
+}
+
+/**
+ * Return the `[start, end)` slice of a chunk list (end exclusive, start default
+ * 0, end default total length) as a new chunk list — mirrors RawStorage.load.
+ */
+function sliceChunks(chunks: Uint8Array[], range: { start?: number; end?: number }): Uint8Array[] {
+  const start = range.start ?? 0;
+  const total = chunks.reduce((n, c) => n + c.length, 0);
+  const end = range.end ?? total;
+  const out: Uint8Array[] = [];
+  let pos = 0;
+  for (const chunk of chunks) {
+    const chunkStart = pos;
+    const chunkEnd = pos + chunk.length;
+    pos = chunkEnd;
+    if (chunkEnd <= start || chunkStart >= end) continue;
+    const from = Math.max(start, chunkStart) - chunkStart;
+    const to = Math.min(end, chunkEnd) - chunkStart;
+    out.push(chunk.subarray(from, to));
+  }
+  return out;
+}
+
+function bytesEqual(a: Uint8Array | undefined, b: Uint8Array | undefined): boolean {
+  if (a === undefined || b === undefined) return a === b;
+  if (a.length !== b.length) return false;
+  for (let i = 0; i < a.length; i++) {
+    if (a[i] !== b[i]) return false;
+  }
+  return true;
+}
+
+/** In-memory {@link KvStore} with a natively-atomic compare-and-set. */
+export function memKvStore(): KvStore {
+  const store = new Map<string, Uint8Array>();
+  return {
+    async get(key) {
+      const v = store.get(key);
+      return v === undefined ? undefined : v.slice();
+    },
+    async put(key, value) {
+      store.set(key, value.slice());
+    },
+    async cas(key, expected, next) {
+      // Single-threaded JS: compare-then-set with no intervening await is
+      // atomic, so two concurrent cas with the same `expected` run sequentially
+      // on the event loop and exactly one wins. Backends without native
+      // conditional writes (sql/kv) will need a lease/lock shim — deferred to
+      // that adapter slice; it is unnecessary for this natively-atomic store.
+      if (!bytesEqual(store.get(key), expected)) return false;
+      if (next === undefined) store.delete(key);
+      else store.set(key, next.slice());
+      return true;
+    },
+    async remove(key) {
+      return store.delete(key);
+    },
+    async *list(prefix) {
+      for (const [key, value] of store) {
+        if (prefix === undefined || key.startsWith(prefix)) yield { key, value: value.slice() };
+      }
+    },
+  };
+}

package/src/types.ts

@@ -0,0 +1,87 @@
+/**
+ * Public contract for the domain-neutral byte-persistence seam.
+ *
+ * Two low-level primitives — an immutable content-addressed {@link BlobStore}
+ * and a mutable {@link KvStore} with atomic compare-and-set — plus thin typed
+ * facades built over them. The seam stores bytes: it knows nothing of git
+ * objects, chunks, or hashing. The caller owns every id (storage is
+ * hash-agnostic).
+ */
+
+/** A stream of bytes, as produced by {@link import("@statewalker/webrun-files").FilesApi.read}. */
+export type ByteStream = AsyncIterable<Uint8Array>;
+
+/**
+ * Immutable, content-addressed byte store keyed by a caller-supplied id.
+ *
+ * `put` is idempotent for a given id: because the id names the content, a
+ * re-put of the same id overwrites with identical bytes and never errors.
+ */
+export interface BlobStore {
+  /**
+   * Store `bytes` under `id`. Streaming and bounded-memory — the payload is
+   * never buffered into one contiguous allocation. When `opts.verify` is given,
+   * the re-derived id must equal `id`, otherwise `put` rejects and stores nothing.
+   */
+  put(
+    id: string,
+    bytes: ByteStream,
+    opts?: { verify?: (bytes: ByteStream) => Promise<string> },
+  ): Promise<void>;
+  /**
+   * Read the blob's bytes. Yields an empty stream if the id is absent (FilesApi
+   * convention).
+   *
+   * The optional `range` reads a partial slice, matching `RawStorage.load`'s
+   * semantics exactly so an adapter is a straight pass-through: `start` is the
+   * inclusive byte offset (default 0) and `end` is the **exclusive** upper bound
+   * (default end of content). `{ start }` reads from `start` to the end;
+   * `{ end }` reads `[0, end)`. Existing callers pass nothing and are unaffected.
+   */
+  get(id: string, range?: { start?: number; end?: number }): ByteStream;
+  has(id: string): Promise<boolean>;
+  /** Remove the blob; resolves `true` if something was removed, `false` if absent. */
+  remove(id: string): Promise<boolean>;
+  /**
+   * Byte length of the stored blob, or `-1` if the id is absent — matching
+   * `RawStorage.size`.
+   */
+  size(id: string): Promise<number>;
+  /** Ids currently stored, optionally filtered by prefix. */
+  list(prefix?: string): AsyncIterable<string>;
+}
+
+/**
+ * `BlobStore` keyed by a git object id. The seam adds no git semantics, so this
+ * is a plain alias; `content-store` callers use {@link BlobStore} directly.
+ */
+export type ObjectStore = BlobStore;
+
+/** Mutable keyed byte store with an atomic compare-and-set. */
+export interface KvStore {
+  get(key: string): Promise<Uint8Array | undefined>;
+  put(key: string, value: Uint8Array): Promise<void>;
+  /**
+   * Atomic compare-and-set. Writes `next` and returns `true` iff the current
+   * value deep-equals `expected` (both-undefined counts as a match, i.e. create).
+   * On mismatch returns `false` and writes nothing. `next === undefined` deletes.
+   */
+  cas(
+    key: string,
+    expected: Uint8Array | undefined,
+    next: Uint8Array | undefined,
+  ): Promise<boolean>;
+  remove(key: string): Promise<boolean>;
+  list(prefix?: string): AsyncIterable<{ key: string; value: Uint8Array }>;
+}
+
+/** Thin facade over a {@link KvStore} that stores string ids as UTF-8 bytes. */
+export interface RefStore {
+  read(name: string): Promise<string | undefined>;
+  compareAndSet(
+    name: string,
+    expected: string | undefined,
+    next: string | undefined,
+  ): Promise<boolean>;
+  list(prefix?: string): AsyncIterable<{ name: string; id: string }>;
+}