@aigne/afs-did-space 1.12.0-beta.5

package/dist/changelog-write.cjs

@@ -0,0 +1,80 @@
+
+//#region src/changelog-write.ts
+/**
+* changelog-write — shared runtime helpers for Task 2.4a atomic changelog writes.
+*
+* Both `D1TreeIndex` (Cloudflare Worker) and `MetadataDB` (desktop libsql) call
+* into these helpers so the two runtimes stay byte-equivalent in SQL shape and
+* deviceId validation. The DDL itself lives in `changelog-schema.ts` (parity-
+* checked via CI); the INSERT statements live here.
+*
+* Design note: D1 and libsql have different prepared-statement builder APIs, so
+* we cannot share a single "prepared statement" helper. Instead we export:
+*
+*   1. The canonical INSERT SQL string (identical across runtimes)
+*   2. A deviceId validator (runtime-agnostic)
+*   3. A small `buildChangelogBinds()` helper that returns the positional argument
+*      array both runtimes bind against
+*
+* This keeps the shared surface small and forces each call site to be explicit
+* about which runtime it is writing to.
+*/
+/**
+* Canonical INSERT statement for `changelog`. Positional args:
+*   [scope, path, op, cid, old_cid, size, mtime, device_id]
+*
+* `seq` is omitted because the column is `INTEGER PRIMARY KEY AUTOINCREMENT` —
+* SQLite/D1 assigns it automatically.
+*
+* This string is used VERBATIM in both `D1TreeIndex` (via `db.prepare(...)`) and
+* `MetadataDB` (via `client.batch([{ sql, args }], 'write')`). Do not rewrite
+* into multi-line form — the parity test compares byte-for-byte.
+*/
+const CHANGELOG_INSERT_SQL = "INSERT INTO ds_changelog (scope, path, op, cid, old_cid, size, mtime, device_id) VALUES (?, ?, ?, ?, ?, ?, ?, ?)";
+/** Max allowed deviceId length in bytes (arbitrary cap to bound changelog row size). */
+const MAX_DEVICE_ID_BYTES = 128;
+/**
+* Validate `opts.deviceId` at runtime.
+*
+* TypeScript's strict mode already blocks missing `opts` or missing `deviceId`
+* at compile time (see `interface PutOpts`). This helper exists as a defense-
+* in-depth check against:
+*   - empty string  (fabricated at runtime by bypassing the type system)
+*   - oversized string (prevents DoS / unbounded changelog rows)
+*
+* Throws a plain `Error` prefixed with `InvalidDeviceId:` so callers can
+* distinguish device-id failures from generic SQL errors.
+*/
+function validateDeviceId(deviceId) {
+	if (typeof deviceId !== "string" || deviceId.length === 0) throw new Error("InvalidDeviceId: deviceId must be a non-empty string");
+	const bytes = new TextEncoder().encode(deviceId).length;
+	if (bytes > MAX_DEVICE_ID_BYTES) throw new Error(`InvalidDeviceId: deviceId exceeds ${MAX_DEVICE_ID_BYTES} bytes (got ${bytes})`);
+}
+/**
+* Build the positional bind arguments for a `changelog` INSERT row.
+*
+* Columns match `CHANGELOG_INSERT_SQL` exactly. Nulls are explicit so D1 and
+* libsql do not accidentally coerce `undefined` → SQL default.
+*
+* Size semantics:
+*   - put   : file size (bytes)
+*   - delete: null (the file is gone; its prior size lives in the old entries row)
+*/
+function buildChangelogBinds(args) {
+	return [
+		args.scope,
+		args.path,
+		args.op,
+		args.cid,
+		args.oldCid,
+		args.size,
+		args.mtime,
+		args.deviceId
+	];
+}
+
+//#endregion
+exports.CHANGELOG_INSERT_SQL = CHANGELOG_INSERT_SQL;
+exports.MAX_DEVICE_ID_BYTES = MAX_DEVICE_ID_BYTES;
+exports.buildChangelogBinds = buildChangelogBinds;
+exports.validateDeviceId = validateDeviceId;

package/dist/changelog-write.d.cts

@@ -0,0 +1,70 @@
+//#region src/changelog-write.d.ts
+/**
+ * changelog-write — shared runtime helpers for Task 2.4a atomic changelog writes.
+ *
+ * Both `D1TreeIndex` (Cloudflare Worker) and `MetadataDB` (desktop libsql) call
+ * into these helpers so the two runtimes stay byte-equivalent in SQL shape and
+ * deviceId validation. The DDL itself lives in `changelog-schema.ts` (parity-
+ * checked via CI); the INSERT statements live here.
+ *
+ * Design note: D1 and libsql have different prepared-statement builder APIs, so
+ * we cannot share a single "prepared statement" helper. Instead we export:
+ *
+ *   1. The canonical INSERT SQL string (identical across runtimes)
+ *   2. A deviceId validator (runtime-agnostic)
+ *   3. A small `buildChangelogBinds()` helper that returns the positional argument
+ *      array both runtimes bind against
+ *
+ * This keeps the shared surface small and forces each call site to be explicit
+ * about which runtime it is writing to.
+ */
+/**
+ * Canonical INSERT statement for `changelog`. Positional args:
+ *   [scope, path, op, cid, old_cid, size, mtime, device_id]
+ *
+ * `seq` is omitted because the column is `INTEGER PRIMARY KEY AUTOINCREMENT` —
+ * SQLite/D1 assigns it automatically.
+ *
+ * This string is used VERBATIM in both `D1TreeIndex` (via `db.prepare(...)`) and
+ * `MetadataDB` (via `client.batch([{ sql, args }], 'write')`). Do not rewrite
+ * into multi-line form — the parity test compares byte-for-byte.
+ */
+declare const CHANGELOG_INSERT_SQL = "INSERT INTO ds_changelog (scope, path, op, cid, old_cid, size, mtime, device_id) VALUES (?, ?, ?, ?, ?, ?, ?, ?)";
+/** Max allowed deviceId length in bytes (arbitrary cap to bound changelog row size). */
+declare const MAX_DEVICE_ID_BYTES = 128;
+/**
+ * Validate `opts.deviceId` at runtime.
+ *
+ * TypeScript's strict mode already blocks missing `opts` or missing `deviceId`
+ * at compile time (see `interface PutOpts`). This helper exists as a defense-
+ * in-depth check against:
+ *   - empty string  (fabricated at runtime by bypassing the type system)
+ *   - oversized string (prevents DoS / unbounded changelog rows)
+ *
+ * Throws a plain `Error` prefixed with `InvalidDeviceId:` so callers can
+ * distinguish device-id failures from generic SQL errors.
+ */
+declare function validateDeviceId(deviceId: string): void;
+/**
+ * Build the positional bind arguments for a `changelog` INSERT row.
+ *
+ * Columns match `CHANGELOG_INSERT_SQL` exactly. Nulls are explicit so D1 and
+ * libsql do not accidentally coerce `undefined` → SQL default.
+ *
+ * Size semantics:
+ *   - put   : file size (bytes)
+ *   - delete: null (the file is gone; its prior size lives in the old entries row)
+ */
+declare function buildChangelogBinds(args: {
+  scope: string;
+  path: string;
+  op: "put" | "delete";
+  cid: string | null;
+  oldCid: string | null;
+  size: number | null;
+  mtime: number;
+  deviceId: string;
+}): [string, string, string, string | null, string | null, number | null, number, string];
+//#endregion
+export { CHANGELOG_INSERT_SQL, MAX_DEVICE_ID_BYTES, buildChangelogBinds, validateDeviceId };
+//# sourceMappingURL=changelog-write.d.cts.map

package/dist/changelog-write.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"changelog-write.d.cts","names":[],"sources":["../src/changelog-write.ts"],"mappings":";;AA+BA;;;;;AAIA;;;;;AAcA;;;;;AAwBA;;;;;;;;;;;;;;cA1Ca,oBAAA;;cAIA,mBAAA;;;;;;;;;;;;;iBAcG,gBAAA,CAAiB,QAAA;;;;;;;;;;;iBAwBjB,mBAAA,CAAoB,IAAA;EAClC,KAAA;EACA,IAAA;EACA,EAAA;EACA,GAAA;EACA,MAAA;EACA,IAAA;EACA,KAAA;EACA,QAAA;AAAA"}

package/dist/changelog-write.d.mts

@@ -0,0 +1,70 @@
+//#region src/changelog-write.d.ts
+/**
+ * changelog-write — shared runtime helpers for Task 2.4a atomic changelog writes.
+ *
+ * Both `D1TreeIndex` (Cloudflare Worker) and `MetadataDB` (desktop libsql) call
+ * into these helpers so the two runtimes stay byte-equivalent in SQL shape and
+ * deviceId validation. The DDL itself lives in `changelog-schema.ts` (parity-
+ * checked via CI); the INSERT statements live here.
+ *
+ * Design note: D1 and libsql have different prepared-statement builder APIs, so
+ * we cannot share a single "prepared statement" helper. Instead we export:
+ *
+ *   1. The canonical INSERT SQL string (identical across runtimes)
+ *   2. A deviceId validator (runtime-agnostic)
+ *   3. A small `buildChangelogBinds()` helper that returns the positional argument
+ *      array both runtimes bind against
+ *
+ * This keeps the shared surface small and forces each call site to be explicit
+ * about which runtime it is writing to.
+ */
+/**
+ * Canonical INSERT statement for `changelog`. Positional args:
+ *   [scope, path, op, cid, old_cid, size, mtime, device_id]
+ *
+ * `seq` is omitted because the column is `INTEGER PRIMARY KEY AUTOINCREMENT` —
+ * SQLite/D1 assigns it automatically.
+ *
+ * This string is used VERBATIM in both `D1TreeIndex` (via `db.prepare(...)`) and
+ * `MetadataDB` (via `client.batch([{ sql, args }], 'write')`). Do not rewrite
+ * into multi-line form — the parity test compares byte-for-byte.
+ */
+declare const CHANGELOG_INSERT_SQL = "INSERT INTO ds_changelog (scope, path, op, cid, old_cid, size, mtime, device_id) VALUES (?, ?, ?, ?, ?, ?, ?, ?)";
+/** Max allowed deviceId length in bytes (arbitrary cap to bound changelog row size). */
+declare const MAX_DEVICE_ID_BYTES = 128;
+/**
+ * Validate `opts.deviceId` at runtime.
+ *
+ * TypeScript's strict mode already blocks missing `opts` or missing `deviceId`
+ * at compile time (see `interface PutOpts`). This helper exists as a defense-
+ * in-depth check against:
+ *   - empty string  (fabricated at runtime by bypassing the type system)
+ *   - oversized string (prevents DoS / unbounded changelog rows)
+ *
+ * Throws a plain `Error` prefixed with `InvalidDeviceId:` so callers can
+ * distinguish device-id failures from generic SQL errors.
+ */
+declare function validateDeviceId(deviceId: string): void;
+/**
+ * Build the positional bind arguments for a `changelog` INSERT row.
+ *
+ * Columns match `CHANGELOG_INSERT_SQL` exactly. Nulls are explicit so D1 and
+ * libsql do not accidentally coerce `undefined` → SQL default.
+ *
+ * Size semantics:
+ *   - put   : file size (bytes)
+ *   - delete: null (the file is gone; its prior size lives in the old entries row)
+ */
+declare function buildChangelogBinds(args: {
+  scope: string;
+  path: string;
+  op: "put" | "delete";
+  cid: string | null;
+  oldCid: string | null;
+  size: number | null;
+  mtime: number;
+  deviceId: string;
+}): [string, string, string, string | null, string | null, number | null, number, string];
+//#endregion
+export { CHANGELOG_INSERT_SQL, MAX_DEVICE_ID_BYTES, buildChangelogBinds, validateDeviceId };
+//# sourceMappingURL=changelog-write.d.mts.map

package/dist/changelog-write.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"changelog-write.d.mts","names":[],"sources":["../src/changelog-write.ts"],"mappings":";;AA+BA;;;;;AAIA;;;;;AAcA;;;;;AAwBA;;;;;;;;;;;;;;cA1Ca,oBAAA;;cAIA,mBAAA;;;;;;;;;;;;;iBAcG,gBAAA,CAAiB,QAAA;;;;;;;;;;;iBAwBjB,mBAAA,CAAoB,IAAA;EAClC,KAAA;EACA,IAAA;EACA,EAAA;EACA,GAAA;EACA,MAAA;EACA,IAAA;EACA,KAAA;EACA,QAAA;AAAA"}

package/dist/changelog-write.mjs

@@ -0,0 +1,77 @@
+//#region src/changelog-write.ts
+/**
+* changelog-write — shared runtime helpers for Task 2.4a atomic changelog writes.
+*
+* Both `D1TreeIndex` (Cloudflare Worker) and `MetadataDB` (desktop libsql) call
+* into these helpers so the two runtimes stay byte-equivalent in SQL shape and
+* deviceId validation. The DDL itself lives in `changelog-schema.ts` (parity-
+* checked via CI); the INSERT statements live here.
+*
+* Design note: D1 and libsql have different prepared-statement builder APIs, so
+* we cannot share a single "prepared statement" helper. Instead we export:
+*
+*   1. The canonical INSERT SQL string (identical across runtimes)
+*   2. A deviceId validator (runtime-agnostic)
+*   3. A small `buildChangelogBinds()` helper that returns the positional argument
+*      array both runtimes bind against
+*
+* This keeps the shared surface small and forces each call site to be explicit
+* about which runtime it is writing to.
+*/
+/**
+* Canonical INSERT statement for `changelog`. Positional args:
+*   [scope, path, op, cid, old_cid, size, mtime, device_id]
+*
+* `seq` is omitted because the column is `INTEGER PRIMARY KEY AUTOINCREMENT` —
+* SQLite/D1 assigns it automatically.
+*
+* This string is used VERBATIM in both `D1TreeIndex` (via `db.prepare(...)`) and
+* `MetadataDB` (via `client.batch([{ sql, args }], 'write')`). Do not rewrite
+* into multi-line form — the parity test compares byte-for-byte.
+*/
+const CHANGELOG_INSERT_SQL = "INSERT INTO ds_changelog (scope, path, op, cid, old_cid, size, mtime, device_id) VALUES (?, ?, ?, ?, ?, ?, ?, ?)";
+/** Max allowed deviceId length in bytes (arbitrary cap to bound changelog row size). */
+const MAX_DEVICE_ID_BYTES = 128;
+/**
+* Validate `opts.deviceId` at runtime.
+*
+* TypeScript's strict mode already blocks missing `opts` or missing `deviceId`
+* at compile time (see `interface PutOpts`). This helper exists as a defense-
+* in-depth check against:
+*   - empty string  (fabricated at runtime by bypassing the type system)
+*   - oversized string (prevents DoS / unbounded changelog rows)
+*
+* Throws a plain `Error` prefixed with `InvalidDeviceId:` so callers can
+* distinguish device-id failures from generic SQL errors.
+*/
+function validateDeviceId(deviceId) {
+	if (typeof deviceId !== "string" || deviceId.length === 0) throw new Error("InvalidDeviceId: deviceId must be a non-empty string");
+	const bytes = new TextEncoder().encode(deviceId).length;
+	if (bytes > MAX_DEVICE_ID_BYTES) throw new Error(`InvalidDeviceId: deviceId exceeds ${MAX_DEVICE_ID_BYTES} bytes (got ${bytes})`);
+}
+/**
+* Build the positional bind arguments for a `changelog` INSERT row.
+*
+* Columns match `CHANGELOG_INSERT_SQL` exactly. Nulls are explicit so D1 and
+* libsql do not accidentally coerce `undefined` → SQL default.
+*
+* Size semantics:
+*   - put   : file size (bytes)
+*   - delete: null (the file is gone; its prior size lives in the old entries row)
+*/
+function buildChangelogBinds(args) {
+	return [
+		args.scope,
+		args.path,
+		args.op,
+		args.cid,
+		args.oldCid,
+		args.size,
+		args.mtime,
+		args.deviceId
+	];
+}
+
+//#endregion
+export { CHANGELOG_INSERT_SQL, MAX_DEVICE_ID_BYTES, buildChangelogBinds, validateDeviceId };
+//# sourceMappingURL=changelog-write.mjs.map

package/dist/changelog-write.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"changelog-write.mjs","names":[],"sources":["../src/changelog-write.ts"],"sourcesContent":["/**\n * changelog-write — shared runtime helpers for Task 2.4a atomic changelog writes.\n *\n * Both `D1TreeIndex` (Cloudflare Worker) and `MetadataDB` (desktop libsql) call\n * into these helpers so the two runtimes stay byte-equivalent in SQL shape and\n * deviceId validation. The DDL itself lives in `changelog-schema.ts` (parity-\n * checked via CI); the INSERT statements live here.\n *\n * Design note: D1 and libsql have different prepared-statement builder APIs, so\n * we cannot share a single \"prepared statement\" helper. Instead we export:\n *\n *   1. The canonical INSERT SQL string (identical across runtimes)\n *   2. A deviceId validator (runtime-agnostic)\n *   3. A small `buildChangelogBinds()` helper that returns the positional argument\n *      array both runtimes bind against\n *\n * This keeps the shared surface small and forces each call site to be explicit\n * about which runtime it is writing to.\n */\n\n/**\n * Canonical INSERT statement for `changelog`. Positional args:\n *   [scope, path, op, cid, old_cid, size, mtime, device_id]\n *\n * `seq` is omitted because the column is `INTEGER PRIMARY KEY AUTOINCREMENT` —\n * SQLite/D1 assigns it automatically.\n *\n * This string is used VERBATIM in both `D1TreeIndex` (via `db.prepare(...)`) and\n * `MetadataDB` (via `client.batch([{ sql, args }], 'write')`). Do not rewrite\n * into multi-line form — the parity test compares byte-for-byte.\n */\nexport const CHANGELOG_INSERT_SQL =\n  \"INSERT INTO ds_changelog (scope, path, op, cid, old_cid, size, mtime, device_id) VALUES (?, ?, ?, ?, ?, ?, ?, ?)\";\n\n/** Max allowed deviceId length in bytes (arbitrary cap to bound changelog row size). */\nexport const MAX_DEVICE_ID_BYTES = 128;\n\n/**\n * Validate `opts.deviceId` at runtime.\n *\n * TypeScript's strict mode already blocks missing `opts` or missing `deviceId`\n * at compile time (see `interface PutOpts`). This helper exists as a defense-\n * in-depth check against:\n *   - empty string  (fabricated at runtime by bypassing the type system)\n *   - oversized string (prevents DoS / unbounded changelog rows)\n *\n * Throws a plain `Error` prefixed with `InvalidDeviceId:` so callers can\n * distinguish device-id failures from generic SQL errors.\n */\nexport function validateDeviceId(deviceId: string): void {\n  if (typeof deviceId !== \"string\" || deviceId.length === 0) {\n    throw new Error(\"InvalidDeviceId: deviceId must be a non-empty string\");\n  }\n  // Byte length, not char length — a non-ASCII deviceId may overflow the cap\n  // even when its char count looks small.\n  const bytes = new TextEncoder().encode(deviceId).length;\n  if (bytes > MAX_DEVICE_ID_BYTES) {\n    throw new Error(\n      `InvalidDeviceId: deviceId exceeds ${MAX_DEVICE_ID_BYTES} bytes (got ${bytes})`,\n    );\n  }\n}\n\n/**\n * Build the positional bind arguments for a `changelog` INSERT row.\n *\n * Columns match `CHANGELOG_INSERT_SQL` exactly. Nulls are explicit so D1 and\n * libsql do not accidentally coerce `undefined` → SQL default.\n *\n * Size semantics:\n *   - put   : file size (bytes)\n *   - delete: null (the file is gone; its prior size lives in the old entries row)\n */\nexport function buildChangelogBinds(args: {\n  scope: string;\n  path: string;\n  op: \"put\" | \"delete\";\n  cid: string | null;\n  oldCid: string | null;\n  size: number | null;\n  mtime: number;\n  deviceId: string;\n}): [string, string, string, string | null, string | null, number | null, number, string] {\n  return [\n    args.scope,\n    args.path,\n    args.op,\n    args.cid,\n    args.oldCid,\n    args.size,\n    args.mtime,\n    args.deviceId,\n  ];\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA+BA,MAAa,uBACX;;AAGF,MAAa,sBAAsB;;;;;;;;;;;;;AAcnC,SAAgB,iBAAiB,UAAwB;AACvD,KAAI,OAAO,aAAa,YAAY,SAAS,WAAW,EACtD,OAAM,IAAI,MAAM,uDAAuD;CAIzE,MAAM,QAAQ,IAAI,aAAa,CAAC,OAAO,SAAS,CAAC;AACjD,KAAI,QAAQ,oBACV,OAAM,IAAI,MACR,qCAAqC,oBAAoB,cAAc,MAAM,GAC9E;;;;;;;;;;;;AAcL,SAAgB,oBAAoB,MASsD;AACxF,QAAO;EACL,KAAK;EACL,KAAK;EACL,KAAK;EACL,KAAK;EACL,KAAK;EACL,KAAK;EACL,KAAK;EACL,KAAK;EACN"}

package/dist/cid-byte-cache.cjs

@@ -0,0 +1,126 @@
+
+//#region src/cid-byte-cache.ts
+/** Canonical prefix under which content-addressed blobs live: `objects/{cid}`. */
+const OBJECT_KEY_PREFIX = "objects/";
+/** Total bytes the cache may hold before LRU eviction kicks in (per instance). */
+const DEFAULT_MAX_TOTAL_BYTES = 64 * 1024 * 1024;
+/**
+* Largest single object we cache. Bigger blobs (large media / bundles) are left
+* uncached: they'd evict many small hot files, and the ≳8 MiB range is
+* download-plane territory (served R2-direct, never read through the Worker).
+*/
+const DEFAULT_MAX_ENTRY_BYTES = 4 * 1024 * 1024;
+const UTF8_DECODER = new TextDecoder();
+/** Synthetic timestamp for cached objects — object-store metadata is never read
+* from `get()` (the provider takes size/mtime from the tree index), so a fixed
+* epoch is faithful and avoids a per-entry Date allocation. */
+const SYNTHETIC_UPLOADED = /* @__PURE__ */ new Date(0);
+/**
+* Bounded LRU cache of `cid → bytes`. Insertion order in the backing Map is the
+* LRU order; a `get` re-inserts (bumps to most-recently-used).
+*/
+var CidByteCache = class {
+	map = /* @__PURE__ */ new Map();
+	maxTotalBytes;
+	maxEntryBytes;
+	totalBytes = 0;
+	constructor(options) {
+		this.maxTotalBytes = options?.maxTotalBytes ?? DEFAULT_MAX_TOTAL_BYTES;
+		this.maxEntryBytes = options?.maxEntryBytes ?? DEFAULT_MAX_ENTRY_BYTES;
+	}
+	get(cid) {
+		const bytes = this.map.get(cid);
+		if (bytes === void 0) return void 0;
+		this.map.delete(cid);
+		this.map.set(cid, bytes);
+		return bytes;
+	}
+	set(cid, bytes) {
+		if (bytes.byteLength > this.maxEntryBytes) return;
+		const existing = this.map.get(cid);
+		if (existing !== void 0) {
+			this.totalBytes -= existing.byteLength;
+			this.map.delete(cid);
+		}
+		this.map.set(cid, bytes);
+		this.totalBytes += bytes.byteLength;
+		this.evictToBudget();
+	}
+	delete(cid) {
+		const existing = this.map.get(cid);
+		if (existing === void 0) return;
+		this.totalBytes -= existing.byteLength;
+		this.map.delete(cid);
+	}
+	/** Test/introspection helper. */
+	get size() {
+		return this.map.size;
+	}
+	evictToBudget() {
+		while (this.totalBytes > this.maxTotalBytes) {
+			const oldest = this.map.keys().next().value;
+			if (oldest === void 0) break;
+			const evicted = this.map.get(oldest);
+			if (evicted !== void 0) this.totalBytes -= evicted.byteLength;
+			this.map.delete(oldest);
+		}
+	}
+};
+/** Build a minimal ObjectStoreObject that serves cached bytes. */
+function objectFromBytes(key, bytes) {
+	return {
+		key,
+		size: bytes.byteLength,
+		uploaded: SYNTHETIC_UPLOADED,
+		async text() {
+			return UTF8_DECODER.decode(bytes);
+		},
+		async arrayBuffer() {
+			return bytes.slice().buffer;
+		}
+	};
+}
+/**
+* ObjectStore decorator that serves `objects/{cid}` reads from an in-memory
+* {@link CidByteCache}. Non-`objects/` keys and all writes/lists pass straight
+* through. `delete` drops the cid from the cache (belt-and-suspenders against GC
+* — a still-referenced object is never GC'd, so this rarely matters).
+*/
+var CachingObjectStore = class {
+	constructor(inner, cache) {
+		this.inner = inner;
+		this.cache = cache;
+	}
+	cidOf(key) {
+		return key.startsWith(OBJECT_KEY_PREFIX) ? key.slice(8) : void 0;
+	}
+	async get(key) {
+		const cid = this.cidOf(key);
+		if (cid === void 0) return this.inner.get(key);
+		const cached = this.cache.get(cid);
+		if (cached !== void 0) return objectFromBytes(key, cached);
+		const obj = await this.inner.get(key);
+		if (!obj) return null;
+		const bytes = new Uint8Array(await obj.arrayBuffer());
+		this.cache.set(cid, bytes);
+		return objectFromBytes(key, bytes);
+	}
+	put(key, value) {
+		return this.inner.put(key, value);
+	}
+	async delete(key) {
+		const cid = this.cidOf(key);
+		if (cid !== void 0) this.cache.delete(cid);
+		return this.inner.delete(key);
+	}
+	list(options) {
+		return this.inner.list(options);
+	}
+	head(key) {
+		return this.inner.head(key);
+	}
+};
+
+//#endregion
+exports.CachingObjectStore = CachingObjectStore;
+exports.CidByteCache = CidByteCache;

package/dist/cid-byte-cache.d.cts

@@ -0,0 +1,46 @@
+import { ObjectStore, ObjectStoreHeadResult, ObjectStoreListOptions, ObjectStoreListResult, ObjectStoreObject } from "./platform/r2/dist/types.cjs";
+
+//#region src/cid-byte-cache.d.ts
+interface CidByteCacheOptions {
+  /** Total byte budget before LRU eviction. Default 64 MiB. */
+  maxTotalBytes?: number;
+  /** Per-object cap; larger objects are not cached. Default 4 MiB. */
+  maxEntryBytes?: number;
+}
+/**
+ * Bounded LRU cache of `cid → bytes`. Insertion order in the backing Map is the
+ * LRU order; a `get` re-inserts (bumps to most-recently-used).
+ */
+declare class CidByteCache {
+  private readonly map;
+  private readonly maxTotalBytes;
+  private readonly maxEntryBytes;
+  private totalBytes;
+  constructor(options?: CidByteCacheOptions);
+  get(cid: string): Uint8Array | undefined;
+  set(cid: string, bytes: Uint8Array): void;
+  delete(cid: string): void;
+  /** Test/introspection helper. */
+  get size(): number;
+  private evictToBudget;
+}
+/**
+ * ObjectStore decorator that serves `objects/{cid}` reads from an in-memory
+ * {@link CidByteCache}. Non-`objects/` keys and all writes/lists pass straight
+ * through. `delete` drops the cid from the cache (belt-and-suspenders against GC
+ * — a still-referenced object is never GC'd, so this rarely matters).
+ */
+declare class CachingObjectStore implements ObjectStore {
+  private readonly inner;
+  private readonly cache;
+  constructor(inner: ObjectStore, cache: CidByteCache);
+  private cidOf;
+  get(key: string): Promise<ObjectStoreObject | null>;
+  put(key: string, value: string | ArrayBuffer | ReadableStream): Promise<void>;
+  delete(key: string): Promise<void>;
+  list(options?: ObjectStoreListOptions): Promise<ObjectStoreListResult>;
+  head(key: string): Promise<ObjectStoreHeadResult | null>;
+}
+//#endregion
+export { CachingObjectStore, CidByteCache, CidByteCacheOptions };
+//# sourceMappingURL=cid-byte-cache.d.cts.map

package/dist/cid-byte-cache.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cid-byte-cache.d.cts","names":[],"sources":["../src/cid-byte-cache.ts"],"mappings":";;;UAiDiB,mBAAA;EAsBX;EApBJ,aAAA;EA6BA;EA3BA,aAAA;AAAA;;;;;cAOW,YAAA;EAAA,iBACM,GAAA;EAAA,iBACA,aAAA;EAAA,iBACA,aAAA;EAAA,QACT,UAAA;cAEI,OAAA,GAAU,mBAAA;EAKtB,GAAA,CAAI,GAAA,WAAc,UAAA;EASlB,GAAA,CAAI,GAAA,UAAa,KAAA,EAAO,UAAA;EAYxB,MAAA,CAAO,GAAA;EAuDiB;EAAA,IA/CpB,IAAA,CAAA;EAAA,QAII,aAAA;AAAA;;;;;;;cAiCG,kBAAA,YAA8B,WAAA;EAAA,iBAEtB,KAAA;EAAA,iBACA,KAAA;cADA,KAAA,EAAO,WAAA,EACP,KAAA,EAAO,YAAA;EAAA,QAGlB,KAAA;EAIF,GAAA,CAAI,GAAA,WAAc,OAAA,CAAQ,iBAAA;EAchC,GAAA,CAAI,GAAA,UAAa,KAAA,WAAgB,WAAA,GAAc,cAAA,GAAiB,OAAA;EAM1D,MAAA,CAAO,GAAA,WAAc,OAAA;EAM3B,IAAA,CAAK,OAAA,GAAU,sBAAA,GAAyB,OAAA,CAAQ,qBAAA;EAIhD,IAAA,CAAK,GAAA,WAAc,OAAA,CAAQ,qBAAA;AAAA"}

package/dist/cid-byte-cache.d.mts

@@ -0,0 +1,47 @@
+import { ObjectStore, ObjectStoreHeadResult, ObjectStoreListOptions, ObjectStoreListResult, ObjectStoreObject } from "./providers/platform/r2/dist/types.mjs";
+import "./providers/platform/r2/dist/index.mjs";
+
+//#region src/cid-byte-cache.d.ts
+interface CidByteCacheOptions {
+  /** Total byte budget before LRU eviction. Default 64 MiB. */
+  maxTotalBytes?: number;
+  /** Per-object cap; larger objects are not cached. Default 4 MiB. */
+  maxEntryBytes?: number;
+}
+/**
+ * Bounded LRU cache of `cid → bytes`. Insertion order in the backing Map is the
+ * LRU order; a `get` re-inserts (bumps to most-recently-used).
+ */
+declare class CidByteCache {
+  private readonly map;
+  private readonly maxTotalBytes;
+  private readonly maxEntryBytes;
+  private totalBytes;
+  constructor(options?: CidByteCacheOptions);
+  get(cid: string): Uint8Array | undefined;
+  set(cid: string, bytes: Uint8Array): void;
+  delete(cid: string): void;
+  /** Test/introspection helper. */
+  get size(): number;
+  private evictToBudget;
+}
+/**
+ * ObjectStore decorator that serves `objects/{cid}` reads from an in-memory
+ * {@link CidByteCache}. Non-`objects/` keys and all writes/lists pass straight
+ * through. `delete` drops the cid from the cache (belt-and-suspenders against GC
+ * — a still-referenced object is never GC'd, so this rarely matters).
+ */
+declare class CachingObjectStore implements ObjectStore {
+  private readonly inner;
+  private readonly cache;
+  constructor(inner: ObjectStore, cache: CidByteCache);
+  private cidOf;
+  get(key: string): Promise<ObjectStoreObject | null>;
+  put(key: string, value: string | ArrayBuffer | ReadableStream): Promise<void>;
+  delete(key: string): Promise<void>;
+  list(options?: ObjectStoreListOptions): Promise<ObjectStoreListResult>;
+  head(key: string): Promise<ObjectStoreHeadResult | null>;
+}
+//#endregion
+export { CachingObjectStore, CidByteCache, CidByteCacheOptions };
+//# sourceMappingURL=cid-byte-cache.d.mts.map

package/dist/cid-byte-cache.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cid-byte-cache.d.mts","names":[],"sources":["../src/cid-byte-cache.ts"],"mappings":";;;;UAiDiB,mBAAA;EAsBf;EApBA,aAAA;EAoBkB;EAlBlB,aAAA;AAAA;;;;;cAOW,YAAA;EAAA,iBACM,GAAA;EAAA,iBACA,aAAA;EAAA,iBACA,aAAA;EAAA,QACT,UAAA;cAEI,OAAA,GAAU,mBAAA;EAKtB,GAAA,CAAI,GAAA,WAAc,UAAA;EASlB,GAAA,CAAI,GAAA,UAAa,KAAA,EAAO,UAAA;EAYxB,MAAA,CAAO,GAAA;EAuDyB;EAAA,IA/C5B,IAAA,CAAA;EAAA,QAII,aAAA;AAAA;;;;;;;cAiCG,kBAAA,YAA8B,WAAA;EAAA,iBAEtB,KAAA;EAAA,iBACA,KAAA;cADA,KAAA,EAAO,WAAA,EACP,KAAA,EAAO,YAAA;EAAA,QAGlB,KAAA;EAIF,GAAA,CAAI,GAAA,WAAc,OAAA,CAAQ,iBAAA;EAchC,GAAA,CAAI,GAAA,UAAa,KAAA,WAAgB,WAAA,GAAc,cAAA,GAAiB,OAAA;EAM1D,MAAA,CAAO,GAAA,WAAc,OAAA;EAM3B,IAAA,CAAK,OAAA,GAAU,sBAAA,GAAyB,OAAA,CAAQ,qBAAA;EAIhD,IAAA,CAAK,GAAA,WAAc,OAAA,CAAQ,qBAAA;AAAA"}

package/dist/cid-byte-cache.mjs

@@ -0,0 +1,125 @@
+//#region src/cid-byte-cache.ts
+/** Canonical prefix under which content-addressed blobs live: `objects/{cid}`. */
+const OBJECT_KEY_PREFIX = "objects/";
+/** Total bytes the cache may hold before LRU eviction kicks in (per instance). */
+const DEFAULT_MAX_TOTAL_BYTES = 64 * 1024 * 1024;
+/**
+* Largest single object we cache. Bigger blobs (large media / bundles) are left
+* uncached: they'd evict many small hot files, and the ≳8 MiB range is
+* download-plane territory (served R2-direct, never read through the Worker).
+*/
+const DEFAULT_MAX_ENTRY_BYTES = 4 * 1024 * 1024;
+const UTF8_DECODER = new TextDecoder();
+/** Synthetic timestamp for cached objects — object-store metadata is never read
+* from `get()` (the provider takes size/mtime from the tree index), so a fixed
+* epoch is faithful and avoids a per-entry Date allocation. */
+const SYNTHETIC_UPLOADED = /* @__PURE__ */ new Date(0);
+/**
+* Bounded LRU cache of `cid → bytes`. Insertion order in the backing Map is the
+* LRU order; a `get` re-inserts (bumps to most-recently-used).
+*/
+var CidByteCache = class {
+	map = /* @__PURE__ */ new Map();
+	maxTotalBytes;
+	maxEntryBytes;
+	totalBytes = 0;
+	constructor(options) {
+		this.maxTotalBytes = options?.maxTotalBytes ?? DEFAULT_MAX_TOTAL_BYTES;
+		this.maxEntryBytes = options?.maxEntryBytes ?? DEFAULT_MAX_ENTRY_BYTES;
+	}
+	get(cid) {
+		const bytes = this.map.get(cid);
+		if (bytes === void 0) return void 0;
+		this.map.delete(cid);
+		this.map.set(cid, bytes);
+		return bytes;
+	}
+	set(cid, bytes) {
+		if (bytes.byteLength > this.maxEntryBytes) return;
+		const existing = this.map.get(cid);
+		if (existing !== void 0) {
+			this.totalBytes -= existing.byteLength;
+			this.map.delete(cid);
+		}
+		this.map.set(cid, bytes);
+		this.totalBytes += bytes.byteLength;
+		this.evictToBudget();
+	}
+	delete(cid) {
+		const existing = this.map.get(cid);
+		if (existing === void 0) return;
+		this.totalBytes -= existing.byteLength;
+		this.map.delete(cid);
+	}
+	/** Test/introspection helper. */
+	get size() {
+		return this.map.size;
+	}
+	evictToBudget() {
+		while (this.totalBytes > this.maxTotalBytes) {
+			const oldest = this.map.keys().next().value;
+			if (oldest === void 0) break;
+			const evicted = this.map.get(oldest);
+			if (evicted !== void 0) this.totalBytes -= evicted.byteLength;
+			this.map.delete(oldest);
+		}
+	}
+};
+/** Build a minimal ObjectStoreObject that serves cached bytes. */
+function objectFromBytes(key, bytes) {
+	return {
+		key,
+		size: bytes.byteLength,
+		uploaded: SYNTHETIC_UPLOADED,
+		async text() {
+			return UTF8_DECODER.decode(bytes);
+		},
+		async arrayBuffer() {
+			return bytes.slice().buffer;
+		}
+	};
+}
+/**
+* ObjectStore decorator that serves `objects/{cid}` reads from an in-memory
+* {@link CidByteCache}. Non-`objects/` keys and all writes/lists pass straight
+* through. `delete` drops the cid from the cache (belt-and-suspenders against GC
+* — a still-referenced object is never GC'd, so this rarely matters).
+*/
+var CachingObjectStore = class {
+	constructor(inner, cache) {
+		this.inner = inner;
+		this.cache = cache;
+	}
+	cidOf(key) {
+		return key.startsWith(OBJECT_KEY_PREFIX) ? key.slice(8) : void 0;
+	}
+	async get(key) {
+		const cid = this.cidOf(key);
+		if (cid === void 0) return this.inner.get(key);
+		const cached = this.cache.get(cid);
+		if (cached !== void 0) return objectFromBytes(key, cached);
+		const obj = await this.inner.get(key);
+		if (!obj) return null;
+		const bytes = new Uint8Array(await obj.arrayBuffer());
+		this.cache.set(cid, bytes);
+		return objectFromBytes(key, bytes);
+	}
+	put(key, value) {
+		return this.inner.put(key, value);
+	}
+	async delete(key) {
+		const cid = this.cidOf(key);
+		if (cid !== void 0) this.cache.delete(cid);
+		return this.inner.delete(key);
+	}
+	list(options) {
+		return this.inner.list(options);
+	}
+	head(key) {
+		return this.inner.head(key);
+	}
+};
+
+//#endregion
+export { CachingObjectStore, CidByteCache };
+//# sourceMappingURL=cid-byte-cache.mjs.map