@f0rbit/corpus 0.1.3 → 0.1.5

package/dist/backend/memory.js

@@ -1,4 +1,34 @@
-import { ok, err } from '../types';
+/**
+ * @module Backends
+ * @description In-memory storage backend for testing and development.
+ */
+import { ok, err } from "../types";
+/**
+ * Creates an in-memory storage backend.
+ * @category Backends
+ * @group Storage Backends
+ *
+ * Ideal for testing, development, and ephemeral storage scenarios.
+ * All data is lost when the process ends.
+ *
+ * @param options - Optional configuration with `on_event` handler for observability
+ * @returns A Backend instance using in-memory storage
+ *
+ * @example
+ * ```ts
+ * // Basic usage for testing
+ * const backend = create_memory_backend()
+ * const corpus = create_corpus()
+ *   .with_backend(backend)
+ *   .with_store(define_store('test', text_codec()))
+ *   .build()
+ *
+ * // With event logging
+ * const backend = create_memory_backend({
+ *   on_event: (e) => console.log(`[${e.type}]`, e)
+ * })
+ * ```
+ */
 export function create_memory_backend(options) {
     const meta_store = new Map();
     const data_store = new Map();
@@ -12,20 +42,20 @@ export function create_memory_backend(options) {
     const metadata = {
         async get(store_id, version) {
             const meta = meta_store.get(make_meta_key(store_id, version));
-            emit({ type: 'meta_get', store_id, version, found: !!meta });
+            emit({ type: "meta_get", store_id, version, found: !!meta });
             if (!meta) {
-                return err({ kind: 'not_found', store_id, version });
+                return err({ kind: "not_found", store_id, version });
             }
             return ok(meta);
         },
         async put(meta) {
             meta_store.set(make_meta_key(meta.store_id, meta.version), meta);
-            emit({ type: 'meta_put', store_id: meta.store_id, version: meta.version });
+            emit({ type: "meta_put", store_id: meta.store_id, version: meta.version });
             return ok(undefined);
         },
         async delete(store_id, version) {
             meta_store.delete(make_meta_key(store_id, version));
-            emit({ type: 'meta_delete', store_id, version });
+            emit({ type: "meta_delete", store_id, version });
             return ok(undefined);
         },
         async *list(store_id, opts) {
@@ -38,7 +68,7 @@ export function create_memory_backend(options) {
                     continue;
                 if (opts?.after && meta.created_at <= opts.after)
                     continue;
-                if (opts?.tags?.length && !opts.tags.some(t => meta.tags?.includes(t)))
+                if (opts?.tags?.length && !opts.tags.every(t => meta.tags?.includes(t)))
                     continue;
                 matches.push(meta);
             }
@@ -49,7 +79,7 @@ export function create_memory_backend(options) {
                 yield match;
                 count++;
             }
-            emit({ type: 'meta_list', store_id, count });
+            emit({ type: "meta_list", store_id, count });
         },
         async get_latest(store_id) {
             let latest = null;
@@ -62,7 +92,7 @@ export function create_memory_backend(options) {
                 }
             }
             if (!latest) {
-                return err({ kind: 'not_found', store_id, version: 'latest' });
+                return err({ kind: "not_found", store_id, version: "latest" });
             }
             return ok(latest);
         },
@@ -86,16 +116,16 @@ export function create_memory_backend(options) {
     const data = {
         async get(data_key) {
             const bytes = data_store.get(data_key);
-            emit({ type: 'data_get', store_id: data_key.split('/')[0] ?? data_key, version: data_key, found: !!bytes });
+            emit({ type: "data_get", store_id: data_key.split("/")[0] ?? data_key, version: data_key, found: !!bytes });
             if (!bytes) {
-                return err({ kind: 'not_found', store_id: data_key, version: '' });
+                return err({ kind: "not_found", store_id: data_key, version: "" });
             }
             return ok({
                 stream: () => new ReadableStream({
                     start(controller) {
                         controller.enqueue(bytes);
                         controller.close();
-                    }
+                    },
                 }),
                 bytes: async () => bytes,
             });

package/dist/backends.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Storage backend implementations for different environments.
+ * @module Backends
+ * @packageDocumentation
+ */
+export { create_memory_backend, type MemoryBackendOptions } from './backend/memory';
+export { create_file_backend, type FileBackendConfig } from './backend/file';
+export { create_cloudflare_backend, type CloudflareBackendConfig } from './backend/cloudflare';
+export { create_layered_backend, type LayeredBackendOptions } from './backend/layered';
+export type { Backend, MetadataClient, DataClient, DataHandle, EventHandler, CorpusEvent } from './types';
+//# sourceMappingURL=backends.d.ts.map

package/dist/backends.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"backends.d.ts","sourceRoot":"","sources":["../backends.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,qBAAqB,EAAE,KAAK,oBAAoB,EAAE,MAAM,kBAAkB,CAAA;AACnF,OAAO,EAAE,mBAAmB,EAAE,KAAK,iBAAiB,EAAE,MAAM,gBAAgB,CAAA;AAC5E,OAAO,EAAE,yBAAyB,EAAE,KAAK,uBAAuB,EAAE,MAAM,sBAAsB,CAAA;AAC9F,OAAO,EAAE,sBAAsB,EAAE,KAAK,qBAAqB,EAAE,MAAM,mBAAmB,CAAA;AACtF,YAAY,EAAE,OAAO,EAAE,cAAc,EAAE,UAAU,EAAE,UAAU,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,SAAS,CAAA"}

package/dist/backends.js

@@ -0,0 +1,9 @@
+/**
+ * Storage backend implementations for different environments.
+ * @module Backends
+ * @packageDocumentation
+ */
+export { create_memory_backend } from './backend/memory';
+export { create_file_backend } from './backend/file';
+export { create_cloudflare_backend } from './backend/cloudflare';
+export { create_layered_backend } from './backend/layered';

package/dist/cloudflare.d.ts

@@ -2,14 +2,11 @@
  * Cloudflare Workers compatible exports
  * This entry point excludes the file backend which uses Node.js APIs
  */
-export { create_corpus } from './corpus';
-export { create_store } from './store';
+export { create_corpus, create_store } from './corpus';
 export { create_memory_backend, type MemoryBackendOptions } from './backend/memory';
 export { create_cloudflare_backend, type CloudflareBackendConfig } from './backend/cloudflare';
-export { json_codec, text_codec, binary_codec } from './codec';
+export { json_codec, text_codec, binary_codec, compute_hash, generate_version } from './utils';
 export { corpus_snapshots, type CorpusSnapshotRow, type CorpusSnapshotInsert } from './schema';
-export { compute_hash } from './hash';
-export { generate_version } from './version';
 export type { ContentType, ParentRef, SnapshotMeta, Snapshot, DataHandle, MetadataClient, DataClient, ListOpts, Backend, Codec, Store, StoreDefinition, PutOpts, CorpusBuilder, Corpus, CorpusError, Result, CorpusEvent, EventHandler, } from './types';
 export { ok, err, define_store } from './types';
 //# sourceMappingURL=cloudflare.d.ts.map

package/dist/cloudflare.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cloudflare.d.ts","sourceRoot":"","sources":["../cloudflare.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAA;AACxC,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAA;AAEtC,OAAO,EAAE,qBAAqB,EAAE,KAAK,oBAAoB,EAAE,MAAM,kBAAkB,CAAA;AACnF,OAAO,EAAE,yBAAyB,EAAE,KAAK,uBAAuB,EAAE,MAAM,sBAAsB,CAAA;AAE9F,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,SAAS,CAAA;AAE9D,OAAO,EAAE,gBAAgB,EAAE,KAAK,iBAAiB,EAAE,KAAK,oBAAoB,EAAE,MAAM,UAAU,CAAA;AAE9F,OAAO,EAAE,YAAY,EAAE,MAAM,QAAQ,CAAA;AACrC,OAAO,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAA;AAE5C,YAAY,EACV,WAAW,EACX,SAAS,EACT,YAAY,EACZ,QAAQ,EACR,UAAU,EACV,cAAc,EACd,UAAU,EACV,QAAQ,EACR,OAAO,EACP,KAAK,EACL,KAAK,EACL,eAAe,EACf,OAAO,EACP,aAAa,EACb,MAAM,EACN,WAAW,EACX,MAAM,EACN,WAAW,EACX,YAAY,GACb,MAAM,SAAS,CAAA;AAEhB,OAAO,EAAE,EAAE,EAAE,GAAG,EAAE,YAAY,EAAE,MAAM,SAAS,CAAA"}
+{"version":3,"file":"cloudflare.d.ts","sourceRoot":"","sources":["../cloudflare.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,UAAU,CAAA;AAEtD,OAAO,EAAE,qBAAqB,EAAE,KAAK,oBAAoB,EAAE,MAAM,kBAAkB,CAAA;AACnF,OAAO,EAAE,yBAAyB,EAAE,KAAK,uBAAuB,EAAE,MAAM,sBAAsB,CAAA;AAE9F,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,YAAY,EAAE,YAAY,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAA;AAE9F,OAAO,EAAE,gBAAgB,EAAE,KAAK,iBAAiB,EAAE,KAAK,oBAAoB,EAAE,MAAM,UAAU,CAAA;AAE9F,YAAY,EACV,WAAW,EACX,SAAS,EACT,YAAY,EACZ,QAAQ,EACR,UAAU,EACV,cAAc,EACd,UAAU,EACV,QAAQ,EACR,OAAO,EACP,KAAK,EACL,KAAK,EACL,eAAe,EACf,OAAO,EACP,aAAa,EACb,MAAM,EACN,WAAW,EACX,MAAM,EACN,WAAW,EACX,YAAY,GACb,MAAM,SAAS,CAAA;AAEhB,OAAO,EAAE,EAAE,EAAE,GAAG,EAAE,YAAY,EAAE,MAAM,SAAS,CAAA"}

package/dist/cloudflare.js

@@ -2,12 +2,9 @@
  * Cloudflare Workers compatible exports
  * This entry point excludes the file backend which uses Node.js APIs
  */
-export { create_corpus } from './corpus';
-export { create_store } from './store';
+export { create_corpus, create_store } from './corpus';
 export { create_memory_backend } from './backend/memory';
 export { create_cloudflare_backend } from './backend/cloudflare';
-export { json_codec, text_codec, binary_codec } from './codec';
+export { json_codec, text_codec, binary_codec, compute_hash, generate_version } from './utils';
 export { corpus_snapshots } from './schema';
-export { compute_hash } from './hash';
-export { generate_version } from './version';
 export { ok, err, define_store } from './types';

package/dist/codecs.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Codec implementations for serializing and deserializing data.
+ * @module Codecs
+ * @packageDocumentation
+ */
+export { json_codec, text_codec, binary_codec } from './utils';
+export type { Codec, ContentType } from './types';
+//# sourceMappingURL=codecs.d.ts.map

package/dist/codecs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"codecs.d.ts","sourceRoot":"","sources":["../codecs.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,SAAS,CAAA;AAC9D,YAAY,EAAE,KAAK,EAAE,WAAW,EAAE,MAAM,SAAS,CAAA"}

package/dist/codecs.js

@@ -0,0 +1,6 @@
+/**
+ * Codec implementations for serializing and deserializing data.
+ * @module Codecs
+ * @packageDocumentation
+ */
+export { json_codec, text_codec, binary_codec } from './utils';

package/dist/core.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Core corpus functionality for creating and managing versioned data stores.
+ * @module Core
+ * @packageDocumentation
+ */
+export { create_corpus, create_store } from './corpus';
+export { define_store, ok, err } from './types';
+export type { Corpus, CorpusBuilder, Store, StoreDefinition, Result, CorpusError, PutOpts, } from './types';
+//# sourceMappingURL=core.d.ts.map

package/dist/core.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"core.d.ts","sourceRoot":"","sources":["../core.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,UAAU,CAAA;AACtD,OAAO,EAAE,YAAY,EAAE,EAAE,EAAE,GAAG,EAAE,MAAM,SAAS,CAAA;AAC/C,YAAY,EACV,MAAM,EACN,aAAa,EACb,KAAK,EACL,eAAe,EACf,MAAM,EACN,WAAW,EACX,OAAO,GACR,MAAM,SAAS,CAAA"}

package/dist/core.js

@@ -0,0 +1,7 @@
+/**
+ * Core corpus functionality for creating and managing versioned data stores.
+ * @module Core
+ * @packageDocumentation
+ */
+export { create_corpus, create_store } from './corpus';
+export { define_store, ok, err } from './types';

package/dist/corpus.d.ts

@@ -1,3 +1,70 @@
-import type { CorpusBuilder } from './types';
+/**
+ * @module Core
+ * @description Core corpus and store creation functions.
+ */
+import type { Backend, CorpusBuilder, StoreDefinition, Store } from './types';
+/**
+ * Creates a typed Store instance bound to a Backend.
+ * @category Core
+ * @group Builders
+ *
+ * Each store manages versioned snapshots of data with automatic deduplication:
+ * when the same content is stored twice, only one copy of the data is kept
+ * (identified by content hash), though separate metadata entries are created.
+ *
+ * Stores are typically created via `create_corpus().with_store()` rather than
+ * directly, which provides type-safe access through `corpus.stores.<id>`.
+ *
+ * @param backend - The storage backend for persistence
+ * @param definition - Store configuration including id and codec
+ * @returns A Store instance for the specified type
+ *
+ * @example
+ * ```ts
+ * const backend = create_memory_backend()
+ * const users = define_store('users', json_codec(UserSchema))
+ * const store = create_store(backend, users)
+ *
+ * // Store a snapshot
+ * const result = await store.put({ name: 'Alice', email: 'alice@example.com' })
+ * if (result.ok) {
+ *   console.log('Stored version:', result.value.version)
+ * }
+ *
+ * // Storing identical content reuses the same data_key (deduplication)
+ * const result2 = await store.put({ name: 'Alice', email: 'alice@example.com' })
+ * // result.value.data_key === result2.value.data_key (same content hash)
+ * ```
+ */
+export declare function create_store<T>(backend: Backend, definition: StoreDefinition<string, T>): Store<T>;
+/**
+ * Creates a new Corpus instance using the builder pattern.
+ *
+ * A Corpus is a collection of typed stores backed by a storage backend.
+ * Use the builder chain to configure: `with_backend()` → `with_store()` → `build()`.
+ *
+ * @category Core
+ * @group Builders
+ * @returns A CorpusBuilder to configure and build the Corpus
+ *
+ * @example
+ * ```ts
+ * import { z } from 'zod'
+ *
+ * const UserSchema = z.object({ name: z.string(), email: z.string() })
+ * const users = define_store('users', json_codec(UserSchema))
+ * const notes = define_store('notes', text_codec())
+ *
+ * const corpus = create_corpus()
+ *   .with_backend(create_memory_backend())
+ *   .with_store(users)
+ *   .with_store(notes)
+ *   .build()
+ *
+ * // Type-safe access to stores
+ * await corpus.stores.users.put({ name: 'Alice', email: 'alice@example.com' })
+ * await corpus.stores.notes.put('Hello, world!')
+ * ```
+ */
 export declare function create_corpus(): CorpusBuilder<{}>;
 //# sourceMappingURL=corpus.d.ts.map

package/dist/corpus.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"corpus.d.ts","sourceRoot":"","sources":["../corpus.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAmB,aAAa,EAA0B,MAAM,SAAS,CAAA;AAGrF,wBAAgB,aAAa,IAAI,aAAa,CAAC,EAAE,CAAC,CAoCjD"}
+{"version":3,"file":"corpus.d.ts","sourceRoot":"","sources":["../corpus.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAU,aAAa,EAAE,eAAe,EAAE,KAAK,EAAqD,MAAM,SAAS,CAAA;AAIxI;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,wBAAgB,YAAY,CAAC,CAAC,EAAE,OAAO,EAAE,OAAO,EAAE,UAAU,EAAE,eAAe,CAAC,MAAM,EAAE,CAAC,CAAC,GAAG,KAAK,CAAC,CAAC,CAAC,CAmJlG;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAgB,aAAa,IAAI,aAAa,CAAC,EAAE,CAAC,CAoCjD"}

package/dist/corpus.js

@@ -1,4 +1,197 @@
-import { create_store } from './store';
+/**
+ * @module Core
+ * @description Core corpus and store creation functions.
+ */
+import { ok, err } from './types';
+import { compute_hash, generate_version } from './utils';
+/**
+ * Creates a typed Store instance bound to a Backend.
+ * @category Core
+ * @group Builders
+ *
+ * Each store manages versioned snapshots of data with automatic deduplication:
+ * when the same content is stored twice, only one copy of the data is kept
+ * (identified by content hash), though separate metadata entries are created.
+ *
+ * Stores are typically created via `create_corpus().with_store()` rather than
+ * directly, which provides type-safe access through `corpus.stores.<id>`.
+ *
+ * @param backend - The storage backend for persistence
+ * @param definition - Store configuration including id and codec
+ * @returns A Store instance for the specified type
+ *
+ * @example
+ * ```ts
+ * const backend = create_memory_backend()
+ * const users = define_store('users', json_codec(UserSchema))
+ * const store = create_store(backend, users)
+ *
+ * // Store a snapshot
+ * const result = await store.put({ name: 'Alice', email: 'alice@example.com' })
+ * if (result.ok) {
+ *   console.log('Stored version:', result.value.version)
+ * }
+ *
+ * // Storing identical content reuses the same data_key (deduplication)
+ * const result2 = await store.put({ name: 'Alice', email: 'alice@example.com' })
+ * // result.value.data_key === result2.value.data_key (same content hash)
+ * ```
+ */
+export function create_store(backend, definition) {
+    const { id, codec, data_key_fn } = definition;
+    function emit(event) {
+        backend.on_event?.(event);
+    }
+    function make_data_key(ctx) {
+        if (data_key_fn) {
+            return data_key_fn(ctx);
+        }
+        return `${ctx.store_id}/${ctx.content_hash}`;
+    }
+    return {
+        id,
+        codec,
+        async put(data, opts) {
+            const version = generate_version();
+            let bytes;
+            try {
+                bytes = codec.encode(data);
+            }
+            catch (cause) {
+                const error = { kind: 'encode_error', cause: cause };
+                emit({ type: 'error', error });
+                return err(error);
+            }
+            const content_hash = await compute_hash(bytes);
+            const key_ctx = { store_id: id, version, content_hash, tags: opts?.tags };
+            // deduplication: reuse existing data_key if content already exists
+            const existing = await backend.metadata.find_by_hash(id, content_hash);
+            const deduplicated = existing !== null;
+            const data_key = deduplicated ? existing.data_key : make_data_key(key_ctx);
+            if (!deduplicated) {
+                const data_result = await backend.data.put(data_key, bytes);
+                if (!data_result.ok) {
+                    emit({ type: 'error', error: data_result.error });
+                    return data_result;
+                }
+            }
+            emit({ type: 'data_put', store_id: id, version, size_bytes: bytes.length, deduplicated });
+            const meta = {
+                store_id: id,
+                version,
+                parents: opts?.parents ?? [],
+                created_at: new Date(),
+                invoked_at: opts?.invoked_at,
+                content_hash,
+                content_type: codec.content_type,
+                size_bytes: bytes.length,
+                data_key,
+                tags: opts?.tags,
+            };
+            const meta_result = await backend.metadata.put(meta);
+            if (!meta_result.ok) {
+                emit({ type: 'error', error: meta_result.error });
+                return meta_result;
+            }
+            emit({ type: 'snapshot_put', store_id: id, version, content_hash, deduplicated });
+            return ok(meta);
+        },
+        async get(version) {
+            const meta_result = await backend.metadata.get(id, version);
+            if (!meta_result.ok) {
+                emit({ type: 'snapshot_get', store_id: id, version, found: false });
+                return meta_result;
+            }
+            const meta = meta_result.value;
+            const data_result = await backend.data.get(meta.data_key);
+            if (!data_result.ok) {
+                emit({ type: 'error', error: data_result.error });
+                return data_result;
+            }
+            const bytes = await data_result.value.bytes();
+            let data;
+            try {
+                data = codec.decode(bytes);
+            }
+            catch (cause) {
+                const error = { kind: 'decode_error', cause: cause };
+                emit({ type: 'error', error });
+                return err(error);
+            }
+            emit({ type: 'snapshot_get', store_id: id, version, found: true });
+            return ok({ meta, data });
+        },
+        async get_latest() {
+            const meta_result = await backend.metadata.get_latest(id);
+            if (!meta_result.ok) {
+                return meta_result;
+            }
+            const meta = meta_result.value;
+            const data_result = await backend.data.get(meta.data_key);
+            if (!data_result.ok) {
+                return data_result;
+            }
+            const bytes = await data_result.value.bytes();
+            let data;
+            try {
+                data = codec.decode(bytes);
+            }
+            catch (cause) {
+                const error = { kind: 'decode_error', cause: cause };
+                emit({ type: 'error', error });
+                return err(error);
+            }
+            return ok({ meta, data });
+        },
+        async get_meta(version) {
+            return backend.metadata.get(id, version);
+        },
+        list(opts) {
+            return backend.metadata.list(id, opts);
+        },
+        async delete(version) {
+            const meta_result = await backend.metadata.get(id, version);
+            if (!meta_result.ok) {
+                return meta_result;
+            }
+            const delete_meta_result = await backend.metadata.delete(id, version);
+            if (!delete_meta_result.ok) {
+                return delete_meta_result;
+            }
+            emit({ type: 'meta_delete', store_id: id, version });
+            return ok(undefined);
+        },
+    };
+}
+/**
+ * Creates a new Corpus instance using the builder pattern.
+ *
+ * A Corpus is a collection of typed stores backed by a storage backend.
+ * Use the builder chain to configure: `with_backend()` → `with_store()` → `build()`.
+ *
+ * @category Core
+ * @group Builders
+ * @returns A CorpusBuilder to configure and build the Corpus
+ *
+ * @example
+ * ```ts
+ * import { z } from 'zod'
+ *
+ * const UserSchema = z.object({ name: z.string(), email: z.string() })
+ * const users = define_store('users', json_codec(UserSchema))
+ * const notes = define_store('notes', text_codec())
+ *
+ * const corpus = create_corpus()
+ *   .with_backend(create_memory_backend())
+ *   .with_store(users)
+ *   .with_store(notes)
+ *   .build()
+ *
+ * // Type-safe access to stores
+ * await corpus.stores.users.put({ name: 'Alice', email: 'alice@example.com' })
+ * await corpus.stores.notes.put('Hello, world!')
+ * ```
+ */
 export function create_corpus() {
     let backend = null;
     const definitions = [];

package/dist/index.d.ts

@@ -1,14 +1,11 @@
-export { create_corpus } from './corpus';
-export { create_store } from './store';
+export { create_corpus, create_store } from './corpus';
 export { create_memory_backend, type MemoryBackendOptions } from './backend/memory';
 export { create_file_backend, type FileBackendConfig } from './backend/file';
 export { create_cloudflare_backend, type CloudflareBackendConfig } from './backend/cloudflare';
 export { create_layered_backend, type LayeredBackendOptions } from './backend/layered';
-export { json_codec, text_codec, binary_codec } from './codec';
+export { json_codec, text_codec, binary_codec, compute_hash, generate_version } from './utils';
 export { corpus_snapshots, type CorpusSnapshotRow, type CorpusSnapshotInsert } from './schema';
-export { compute_hash } from './hash';
-export { generate_version } from './version';
-export type { ContentType, ParentRef, SnapshotMeta, Snapshot, DataHandle, MetadataClient, DataClient, ListOpts, Backend, Codec, Store, StoreDefinition, PutOpts, CorpusBuilder, Corpus, CorpusError, Result, CorpusEvent, EventHandler, } from './types';
+export type { ContentType, ParentRef, SnapshotMeta, Snapshot, DataHandle, MetadataClient, DataClient, ListOpts, Backend, Codec, Store, StoreDefinition, DefineStoreOpts, DataKeyContext, PutOpts, CorpusBuilder, Corpus, CorpusError, Result, CorpusEvent, EventHandler, } from './types';
 export { ok, err, define_store } from './types';
 export { createCorpusInfra, CORPUS_MIGRATION_SQL, type CorpusInfra, type CorpusInfraConfig } from './sst';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAA;AACxC,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAA;AAEtC,OAAO,EAAE,qBAAqB,EAAE,KAAK,oBAAoB,EAAE,MAAM,kBAAkB,CAAA;AACnF,OAAO,EAAE,mBAAmB,EAAE,KAAK,iBAAiB,EAAE,MAAM,gBAAgB,CAAA;AAC5E,OAAO,EAAE,yBAAyB,EAAE,KAAK,uBAAuB,EAAE,MAAM,sBAAsB,CAAA;AAC9F,OAAO,EAAE,sBAAsB,EAAE,KAAK,qBAAqB,EAAE,MAAM,mBAAmB,CAAA;AAEtF,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,SAAS,CAAA;AAE9D,OAAO,EAAE,gBAAgB,EAAE,KAAK,iBAAiB,EAAE,KAAK,oBAAoB,EAAE,MAAM,UAAU,CAAA;AAE9F,OAAO,EAAE,YAAY,EAAE,MAAM,QAAQ,CAAA;AACrC,OAAO,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAA;AAE5C,YAAY,EACV,WAAW,EACX,SAAS,EACT,YAAY,EACZ,QAAQ,EACR,UAAU,EACV,cAAc,EACd,UAAU,EACV,QAAQ,EACR,OAAO,EACP,KAAK,EACL,KAAK,EACL,eAAe,EACf,OAAO,EACP,aAAa,EACb,MAAM,EACN,WAAW,EACX,MAAM,EACN,WAAW,EACX,YAAY,GACb,MAAM,SAAS,CAAA;AAEhB,OAAO,EAAE,EAAE,EAAE,GAAG,EAAE,YAAY,EAAE,MAAM,SAAS,CAAA;AAE/C,OAAO,EAAE,iBAAiB,EAAE,oBAAoB,EAAE,KAAK,WAAW,EAAE,KAAK,iBAAiB,EAAE,MAAM,OAAO,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,UAAU,CAAA;AAEtD,OAAO,EAAE,qBAAqB,EAAE,KAAK,oBAAoB,EAAE,MAAM,kBAAkB,CAAA;AACnF,OAAO,EAAE,mBAAmB,EAAE,KAAK,iBAAiB,EAAE,MAAM,gBAAgB,CAAA;AAC5E,OAAO,EAAE,yBAAyB,EAAE,KAAK,uBAAuB,EAAE,MAAM,sBAAsB,CAAA;AAC9F,OAAO,EAAE,sBAAsB,EAAE,KAAK,qBAAqB,EAAE,MAAM,mBAAmB,CAAA;AAEtF,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,YAAY,EAAE,YAAY,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAA;AAE9F,OAAO,EAAE,gBAAgB,EAAE,KAAK,iBAAiB,EAAE,KAAK,oBAAoB,EAAE,MAAM,UAAU,CAAA;AAE9F,YAAY,EACV,WAAW,EACX,SAAS,EACT,YAAY,EACZ,QAAQ,EACR,UAAU,EACV,cAAc,EACd,UAAU,EACV,QAAQ,EACR,OAAO,EACP,KAAK,EACL,KAAK,EACL,eAAe,EACf,eAAe,EACf,cAAc,EACd,OAAO,EACP,aAAa,EACb,MAAM,EACN,WAAW,EACX,MAAM,EACN,WAAW,EACX,YAAY,GACb,MAAM,SAAS,CAAA;AAEhB,OAAO,EAAE,EAAE,EAAE,GAAG,EAAE,YAAY,EAAE,MAAM,SAAS,CAAA;AAE/C,OAAO,EAAE,iBAAiB,EAAE,oBAAoB,EAAE,KAAK,WAAW,EAAE,KAAK,iBAAiB,EAAE,MAAM,OAAO,CAAA"}

package/dist/index.js

@@ -1,12 +1,9 @@
-export { create_corpus } from './corpus';
-export { create_store } from './store';
+export { create_corpus, create_store } from './corpus';
 export { create_memory_backend } from './backend/memory';
 export { create_file_backend } from './backend/file';
 export { create_cloudflare_backend } from './backend/cloudflare';
 export { create_layered_backend } from './backend/layered';
-export { json_codec, text_codec, binary_codec } from './codec';
+export { json_codec, text_codec, binary_codec, compute_hash, generate_version } from './utils';
 export { corpus_snapshots } from './schema';
-export { compute_hash } from './hash';
-export { generate_version } from './version';
 export { ok, err, define_store } from './types';
 export { createCorpusInfra, CORPUS_MIGRATION_SQL } from './sst';

package/dist/schema.d.ts

@@ -1,3 +1,30 @@
+/**
+ * @module Schema
+ * @description Database schema definitions for Drizzle ORM.
+ */
+/**
+ * Drizzle ORM schema for the corpus_snapshots table.
+ *
+ * Used by the Cloudflare backend with D1 (SQLite). Defines the table structure
+ * for storing snapshot metadata.
+ *
+ * Columns:
+ * - `store_id` + `version` - Composite primary key
+ * - `parents` - JSON array of parent references
+ * - `created_at` / `invoked_at` - ISO 8601 timestamps
+ * - `content_hash` - SHA-256 hash for deduplication
+ * - `data_key` - Key to retrieve binary data from R2
+ * - `tags` - Optional JSON array of tags
+ *
+ * @example
+ * ```ts
+ * import { drizzle } from 'drizzle-orm/d1'
+ * import { corpus_snapshots } from 'corpus/schema'
+ *
+ * const db = drizzle(env.D1)
+ * const rows = await db.select().from(corpus_snapshots).limit(10)
+ * ```
+ */
 export declare const corpus_snapshots: import("drizzle-orm/sqlite-core").SQLiteTableWithColumns<{
     name: "corpus_snapshots";
     schema: undefined;

package/dist/schema.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../schema.ts"],"names":[],"mappings":"AAEA,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAgB1B,CAAA;AAEH,MAAM,MAAM,iBAAiB,GAAG,OAAO,gBAAgB,CAAC,YAAY,CAAA;AACpE,MAAM,MAAM,oBAAoB,GAAG,OAAO,gBAAgB,CAAC,YAAY,CAAA"}
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../schema.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAIH;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAgB1B,CAAA;AAEH,MAAM,MAAM,iBAAiB,GAAG,OAAO,gBAAgB,CAAC,YAAY,CAAA;AACpE,MAAM,MAAM,oBAAoB,GAAG,OAAO,gBAAgB,CAAC,YAAY,CAAA"}

package/dist/schema.js

@@ -1,4 +1,31 @@
+/**
+ * @module Schema
+ * @description Database schema definitions for Drizzle ORM.
+ */
 import { sqliteTable, text, integer, primaryKey, index } from 'drizzle-orm/sqlite-core';
+/**
+ * Drizzle ORM schema for the corpus_snapshots table.
+ *
+ * Used by the Cloudflare backend with D1 (SQLite). Defines the table structure
+ * for storing snapshot metadata.
+ *
+ * Columns:
+ * - `store_id` + `version` - Composite primary key
+ * - `parents` - JSON array of parent references
+ * - `created_at` / `invoked_at` - ISO 8601 timestamps
+ * - `content_hash` - SHA-256 hash for deduplication
+ * - `data_key` - Key to retrieve binary data from R2
+ * - `tags` - Optional JSON array of tags
+ *
+ * @example
+ * ```ts
+ * import { drizzle } from 'drizzle-orm/d1'
+ * import { corpus_snapshots } from 'corpus/schema'
+ *
+ * const db = drizzle(env.D1)
+ * const rows = await db.select().from(corpus_snapshots).limit(10)
+ * ```
+ */
 export const corpus_snapshots = sqliteTable('corpus_snapshots', {
     store_id: text('store_id').notNull(),
     version: text('version').notNull(),

package/dist/sst.d.ts

@@ -13,6 +13,44 @@ export type CorpusInfra = {
     database_name: string;
     bucket_name: string;
 };
+/**
+ * SST infrastructure helper for creating Corpus resources.
+ *
+ * Generates resource names for D1 database and R2 bucket based on a prefix.
+ * Returns objects compatible with SST resource definitions.
+ *
+ * @param name - Base name prefix for resources
+ * @param config - Optional overrides for resource names
+ * @returns Resource definitions with database and bucket names
+ *
+ * @example
+ * ```ts
+ * // In sst.config.ts
+ * const corpus = createCorpusInfra('myapp')
+ *
+ * const db = new sst.cloudflare.D1(corpus.database.name)
+ * const bucket = new sst.cloudflare.R2(corpus.bucket.name)
+ *
+ * // Resource names: 'myappDb', 'myappBucket'
+ * ```
+ */
 export declare function createCorpusInfra(name: string, config?: Partial<CorpusInfraConfig>): CorpusInfra;
+/**
+ * SQL migration script to create required D1 tables for the Cloudflare backend.
+ *
+ * Must be executed on the D1 database before using `create_cloudflare_backend()`.
+ * Creates the `corpus_snapshots` table and required indexes.
+ *
+ * Safe to run multiple times (uses IF NOT EXISTS).
+ *
+ * @example
+ * ```ts
+ * // Run migration via wrangler
+ * // wrangler d1 execute <database-name> --command "$(cat migration.sql)"
+ *
+ * // Or programmatically in a Worker
+ * await env.CORPUS_DB.exec(CORPUS_MIGRATION_SQL)
+ * ```
+ */
 export declare const CORPUS_MIGRATION_SQL = "\nCREATE TABLE IF NOT EXISTS corpus_snapshots (\n  store_id TEXT NOT NULL,\n  version TEXT NOT NULL,\n  parents TEXT NOT NULL,\n  created_at TEXT NOT NULL,\n  invoked_at TEXT,\n  content_hash TEXT NOT NULL,\n  content_type TEXT NOT NULL,\n  size_bytes INTEGER NOT NULL,\n  data_key TEXT NOT NULL,\n  tags TEXT,\n  PRIMARY KEY (store_id, version)\n);\n\nCREATE INDEX IF NOT EXISTS idx_store_created ON corpus_snapshots(store_id, created_at);\nCREATE INDEX IF NOT EXISTS idx_content_hash ON corpus_snapshots(store_id, content_hash);\nCREATE INDEX IF NOT EXISTS idx_data_key ON corpus_snapshots(data_key);\n";
 //# sourceMappingURL=sst.d.ts.map