@f0rbit/corpus 0.1.4 → 0.1.6

package/dist/backend/layered.js

@@ -3,6 +3,7 @@
  * @description Layered backend for caching and replication strategies.
  */
 import { ok, err } from '../types';
+import { to_bytes } from '../utils';
 /**
  * Creates a layered backend that combines multiple backends with read/write separation.
  * @category Backends
@@ -169,25 +170,72 @@ export function create_layered_backend(options) {
             return false;
         },
     };
-    return { metadata, data };
+    const observations = createLayeredObservationsClient(read, write);
+    return {
+        metadata,
+        data,
+        ...(observations ? { observations } : {}),
+    };
 }
-async function to_bytes(data) {
-    if (data instanceof Uint8Array)
-        return data;
-    const chunks = [];
-    const reader = data.getReader();
-    while (true) {
-        const { done, value } = await reader.read();
-        if (done)
-            break;
-        chunks.push(value);
-    }
-    const total = chunks.reduce((sum, c) => sum + c.length, 0);
-    const result = new Uint8Array(total);
-    let offset = 0;
-    for (const chunk of chunks) {
-        result.set(chunk, offset);
-        offset += chunk.length;
+function createLayeredObservationsClient(readLayers, writeLayers) {
+    const readLayer = readLayers.find(l => l.observations);
+    const writeLayersWithObs = writeLayers.filter(l => l.observations);
+    if (!readLayer?.observations && writeLayersWithObs.length === 0) {
+        return undefined;
     }
-    return result;
+    const primary = readLayer?.observations;
+    return {
+        async put(type, opts) {
+            if (writeLayersWithObs.length === 0) {
+                return err({ kind: 'invalid_config', message: 'No write layers support observations' });
+            }
+            let result;
+            for (const layer of writeLayersWithObs) {
+                result = await layer.observations.put(type, opts);
+                if (!result.ok)
+                    return result;
+            }
+            return result;
+        },
+        async get(id) {
+            if (!primary) {
+                return err({ kind: 'observation_not_found', id });
+            }
+            return primary.get(id);
+        },
+        async *query(opts) {
+            if (!primary)
+                return;
+            yield* primary.query(opts);
+        },
+        async *query_meta(opts) {
+            if (!primary)
+                return;
+            yield* primary.query_meta(opts);
+        },
+        async delete(id) {
+            if (writeLayersWithObs.length === 0) {
+                return err({ kind: 'observation_not_found', id });
+            }
+            let result;
+            for (const layer of writeLayersWithObs) {
+                result = await layer.observations.delete(id);
+            }
+            return result;
+        },
+        async delete_by_source(source) {
+            let total = 0;
+            for (const layer of writeLayersWithObs) {
+                const result = await layer.observations.delete_by_source(source);
+                if (result.ok)
+                    total += result.value;
+            }
+            return ok(total);
+        },
+        async is_stale(pointer) {
+            if (!primary)
+                return false;
+            return primary.is_stale(pointer);
+        },
+    };
 }

package/dist/backend/memory.d.ts

@@ -2,7 +2,8 @@
  * @module Backends
  * @description In-memory storage backend for testing and development.
  */
-import type { Backend, EventHandler } from '../types';
+import type { Backend } from "../types";
+import type { EventHandler } from "../types";
 export type MemoryBackendOptions = {
     on_event?: EventHandler;
 };

package/dist/backend/memory.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"memory.d.ts","sourceRoot":"","sources":["../../backend/memory.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAwF,YAAY,EAAE,MAAM,UAAU,CAAA;AAG3I,MAAM,MAAM,oBAAoB,GAAG;IACjC,QAAQ,CAAC,EAAE,YAAY,CAAA;CACxB,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,CAAC,EAAE,oBAAoB,GAAG,OAAO,CAiJ7E"}
+{"version":3,"file":"memory.d.ts","sourceRoot":"","sources":["../../backend/memory.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAiE,MAAM,UAAU,CAAC;AAKvG,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AAE7C,MAAM,MAAM,oBAAoB,GAAG;IAClC,QAAQ,CAAC,EAAE,YAAY,CAAC;CACxB,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,CAAC,EAAE,oBAAoB,GAAG,OAAO,CA4I7E"}

package/dist/backend/memory.js

@@ -2,7 +2,9 @@
  * @module Backends
  * @description In-memory storage backend for testing and development.
  */
-import { ok, err } from '../types';
+import { create_observations_client, create_observations_storage } from "../observations";
+import { ok, err } from "../types";
+import { to_bytes, create_emitter, filter_snapshots } from "../utils";
 /**
  * Creates an in-memory storage backend.
  * @category Backends
@@ -32,54 +34,46 @@ import { ok, err } from '../types';
 export function create_memory_backend(options) {
     const meta_store = new Map();
     const data_store = new Map();
+    const observation_store = new Map();
     const on_event = options?.on_event;
-    function emit(event) {
-        on_event?.(event);
-    }
+    const emit = create_emitter(on_event);
     function make_meta_key(store_id, version) {
         return `${store_id}:${version}`;
     }
     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) {
             const prefix = `${store_id}:`;
-            const matches = [];
+            const store_metas = [];
             for (const [key, meta] of meta_store) {
-                if (!key.startsWith(prefix))
-                    continue;
-                if (opts?.before && meta.created_at >= opts.before)
-                    continue;
-                if (opts?.after && meta.created_at <= opts.after)
-                    continue;
-                if (opts?.tags?.length && !opts.tags.some(t => meta.tags?.includes(t)))
-                    continue;
-                matches.push(meta);
+                if (key.startsWith(prefix)) {
+                    store_metas.push(meta);
+                }
             }
-            matches.sort((a, b) => b.created_at.getTime() - a.created_at.getTime());
-            const limit = opts?.limit ?? Infinity;
+            const filtered = filter_snapshots(store_metas, opts);
             let count = 0;
-            for (const match of matches.slice(0, limit)) {
-                yield match;
+            for (const meta of filtered) {
+                yield meta;
                 count++;
             }
-            emit({ type: 'meta_list', store_id, count });
+            emit({ type: "meta_list", store_id, count });
         },
         async get_latest(store_id) {
             let latest = null;
@@ -92,7 +86,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);
         },
@@ -116,36 +110,22 @@ 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,
             });
         },
         async put(data_key, input) {
-            let bytes;
-            if (input instanceof Uint8Array) {
-                bytes = input;
-            }
-            else {
-                const chunks = [];
-                const reader = input.getReader();
-                while (true) {
-                    const { done, value } = await reader.read();
-                    if (done)
-                        break;
-                    chunks.push(value);
-                }
-                bytes = concat_bytes(chunks);
-            }
+            const bytes = await to_bytes(input);
             data_store.set(data_key, bytes);
             return ok(undefined);
         },
@@ -157,15 +137,21 @@ export function create_memory_backend(options) {
             return data_store.has(data_key);
         },
     };
-    return { metadata, data, on_event };
-}
-function concat_bytes(chunks) {
-    const total = chunks.reduce((sum, c) => sum + c.length, 0);
-    const result = new Uint8Array(total);
-    let offset = 0;
-    for (const chunk of chunks) {
-        result.set(chunk, offset);
-        offset += chunk.length;
-    }
-    return result;
+    const storage = create_observations_storage({
+        get_all: async () => Array.from(observation_store.values()),
+        set_all: async (rows) => {
+            observation_store.clear();
+            for (const row of rows)
+                observation_store.set(row.id, row);
+        },
+        get_one: async (id) => observation_store.get(id) ?? null,
+        add_one: async (row) => { observation_store.set(row.id, row); },
+        remove_one: async (id) => {
+            const had = observation_store.has(id);
+            observation_store.delete(id);
+            return had;
+        }
+    });
+    const observations = create_observations_client(storage, metadata);
+    return { metadata, data, observations, on_event };
 }

package/dist/corpus.d.ts

@@ -64,6 +64,17 @@ export declare function create_store<T>(backend: Backend, definition: StoreDefin
  * // Type-safe access to stores
  * await corpus.stores.users.put({ name: 'Alice', email: 'alice@example.com' })
  * await corpus.stores.notes.put('Hello, world!')
+ *
+ * // With observations
+ * const corpus_with_obs = create_corpus()
+ *   .with_backend(create_memory_backend())
+ *   .with_store(users)
+ *   .with_observations([EntityType, SentimentType])
+ *   .build()
+ *
+ * // Pointer utilities
+ * const pointer = corpus_with_obs.create_pointer('users', 'v123', '$.name')
+ * const value = await corpus_with_obs.resolve_pointer(pointer)
  * ```
  */
 export declare function create_corpus(): CorpusBuilder<{}>;

package/dist/corpus.d.ts.map

@@ -1 +1 @@
-{"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"}
+{"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,EAAyE,MAAM,SAAS,CAAA;AAM5J;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH,wBAAgB,aAAa,IAAI,aAAa,CAAC,EAAE,CAAC,CAiFjD"}

package/dist/corpus.js

@@ -4,6 +4,7 @@
  */
 import { ok, err } from './types';
 import { compute_hash, generate_version } from './utils';
+import { create_pointer, resolve_path, apply_span } from './observations/utils';
 /**
  * Creates a typed Store instance bound to a Backend.
  * @category Core
@@ -190,11 +191,23 @@ export function create_store(backend, definition) {
  * // Type-safe access to stores
  * await corpus.stores.users.put({ name: 'Alice', email: 'alice@example.com' })
  * await corpus.stores.notes.put('Hello, world!')
+ *
+ * // With observations
+ * const corpus_with_obs = create_corpus()
+ *   .with_backend(create_memory_backend())
+ *   .with_store(users)
+ *   .with_observations([EntityType, SentimentType])
+ *   .build()
+ *
+ * // Pointer utilities
+ * const pointer = corpus_with_obs.create_pointer('users', 'v123', '$.name')
+ * const value = await corpus_with_obs.resolve_pointer(pointer)
  * ```
  */
 export function create_corpus() {
     let backend = null;
     const definitions = [];
+    let observation_types = [];
     const builder = {
         with_backend(b) {
             backend = b;
@@ -204,6 +217,10 @@ export function create_corpus() {
             definitions.push(definition);
             return builder;
         },
+        with_observations(types) {
+            observation_types = types;
+            return builder;
+        },
         build() {
             if (!backend) {
                 throw new Error('Backend is required. Call with_backend() first.');
@@ -213,10 +230,45 @@ export function create_corpus() {
             for (const def of definitions) {
                 stores[def.id] = create_store(b, def);
             }
+            const observations_client = observation_types.length > 0 && 'observations' in b
+                ? b.observations
+                : undefined;
+            async function resolve_pointer_impl(pointer) {
+                const store = stores[pointer.store_id];
+                if (!store) {
+                    return err({ kind: 'not_found', store_id: pointer.store_id, version: pointer.version });
+                }
+                const snapshot_result = await store.get(pointer.version);
+                if (!snapshot_result.ok)
+                    return snapshot_result;
+                let value = snapshot_result.value.data;
+                if (pointer.path) {
+                    const path_result = resolve_path(value, pointer.path);
+                    if (!path_result.ok)
+                        return path_result;
+                    value = path_result.value;
+                }
+                if (pointer.span && typeof value === 'string') {
+                    const span_result = apply_span(value, pointer.span);
+                    if (!span_result.ok)
+                        return span_result;
+                    value = span_result.value;
+                }
+                return ok(value);
+            }
+            async function is_superseded_impl(pointer) {
+                if (!observations_client?.is_stale)
+                    return false;
+                return observations_client.is_stale(pointer);
+            }
             return {
                 stores,
                 metadata: b.metadata,
                 data: b.data,
+                observations: observations_client,
+                create_pointer,
+                resolve_pointer: resolve_pointer_impl,
+                is_superseded: is_superseded_impl,
             };
         },
     };

package/dist/index.d.ts

@@ -5,7 +5,8 @@ export { create_cloudflare_backend, type CloudflareBackendConfig } from './backe
 export { create_layered_backend, type LayeredBackendOptions } from './backend/layered';
 export { json_codec, text_codec, binary_codec, compute_hash, generate_version } from './utils';
 export { corpus_snapshots, type CorpusSnapshotRow, type CorpusSnapshotInsert } from './schema';
-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 type { ContentType, ParentRef, SnapshotMeta, Snapshot, DataHandle, MetadataClient, DataClient, ListOpts, Backend, Codec, Store, StoreDefinition, DefineStoreOpts, DataKeyContext, PutOpts, CorpusBuilder, Corpus, CorpusError, Result, CorpusEvent, EventHandler, ObservationsClient, } from './types';
 export { ok, err, define_store } from './types';
+export * from './observations';
 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,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"}
+{"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,EACZ,kBAAkB,GACnB,MAAM,SAAS,CAAA;AAEhB,OAAO,EAAE,EAAE,EAAE,GAAG,EAAE,YAAY,EAAE,MAAM,SAAS,CAAA;AAE/C,cAAc,gBAAgB,CAAA;AAE9B,OAAO,EAAE,iBAAiB,EAAE,oBAAoB,EAAE,KAAK,WAAW,EAAE,KAAK,iBAAiB,EAAE,MAAM,OAAO,CAAA"}

package/dist/index.js

@@ -6,4 +6,5 @@ export { create_layered_backend } from './backend/layered';
 export { json_codec, text_codec, binary_codec, compute_hash, generate_version } from './utils';
 export { corpus_snapshots } from './schema';
 export { ok, err, define_store } from './types';
+export * from './observations';
 export { createCorpusInfra, CORPUS_MIGRATION_SQL } from './sst';

package/dist/observations/client.d.ts

@@ -0,0 +1,12 @@
+/**
+ * @module ObservationsClient
+ * @description Centralized business logic for observations, built on storage adapters.
+ */
+import type { MetadataClient, ObservationsClient } from '../types';
+import type { ObservationsStorage } from './storage';
+/**
+ * Creates an ObservationsClient from a storage adapter.
+ * All business logic (validation, staleness, etc.) is centralized here.
+ */
+export declare function create_observations_client(storage: ObservationsStorage, metadata: MetadataClient): ObservationsClient;
+//# sourceMappingURL=client.d.ts.map

package/dist/observations/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../observations/client.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAuB,cAAc,EAAE,kBAAkB,EAAE,MAAM,UAAU,CAAA;AAEvF,OAAO,KAAK,EAAE,mBAAmB,EAAoB,MAAM,WAAW,CAAA;AAuBtE;;;GAGG;AACH,wBAAgB,0BAA0B,CACxC,OAAO,EAAE,mBAAmB,EAC5B,QAAQ,EAAE,cAAc,GACvB,kBAAkB,CAqGpB"}

package/dist/observations/client.js

@@ -0,0 +1,115 @@
+/**
+ * @module ObservationsClient
+ * @description Centralized business logic for observations, built on storage adapters.
+ */
+import { row_to_observation, row_to_meta, create_observation_row } from './storage';
+import { generate_observation_id } from './utils';
+import { ok, err } from '../types';
+/**
+ * Convert client query opts to storage query opts.
+ * Handles Date -> ISO string conversion.
+ */
+function to_storage_opts(opts) {
+    return {
+        type: opts.type,
+        source_store_id: opts.source_store,
+        source_version: opts.source_version,
+        source_prefix: opts.source_prefix,
+        created_after: opts.created_after?.toISOString(),
+        created_before: opts.created_before?.toISOString(),
+        observed_after: opts.after?.toISOString(),
+        observed_before: opts.before?.toISOString(),
+        limit: opts.limit
+    };
+}
+/**
+ * Creates an ObservationsClient from a storage adapter.
+ * All business logic (validation, staleness, etc.) is centralized here.
+ */
+export function create_observations_client(storage, metadata) {
+    async function get_latest_version(store_id) {
+        const result = await metadata.get_latest(store_id);
+        return result.ok ? result.value.version : null;
+    }
+    return {
+        async put(type, opts) {
+            const validation = type.schema.safeParse(opts.content);
+            if (!validation.success) {
+                return err({
+                    kind: 'validation_error',
+                    cause: validation.error,
+                    message: validation.error.message
+                });
+            }
+            const id = generate_observation_id();
+            const row = create_observation_row(id, type.name, opts.source, validation.data, {
+                confidence: opts.confidence,
+                observed_at: opts.observed_at,
+                derived_from: opts.derived_from
+            });
+            const result = await storage.put_row(row);
+            if (!result.ok)
+                return result;
+            const observation = {
+                id,
+                type: type.name,
+                source: opts.source,
+                content: validation.data,
+                ...(opts.confidence !== undefined && { confidence: opts.confidence }),
+                ...(opts.observed_at && { observed_at: opts.observed_at }),
+                created_at: new Date(row.created_at),
+                ...(opts.derived_from && { derived_from: opts.derived_from })
+            };
+            return ok(observation);
+        },
+        async get(id) {
+            const result = await storage.get_row(id);
+            if (!result.ok)
+                return result;
+            if (!result.value) {
+                return err({ kind: 'observation_not_found', id });
+            }
+            return ok(row_to_observation(result.value));
+        },
+        async *query(opts = {}) {
+            const storageOpts = to_storage_opts(opts);
+            for await (const row of storage.query_rows(storageOpts)) {
+                if (!opts.include_stale) {
+                    const latest = await get_latest_version(row.source_store_id);
+                    if (latest && row.source_version !== latest)
+                        continue;
+                }
+                yield row_to_observation(row);
+            }
+        },
+        async *query_meta(opts = {}) {
+            const storageOpts = to_storage_opts(opts);
+            for await (const row of storage.query_rows(storageOpts)) {
+                if (!opts.include_stale) {
+                    const latest = await get_latest_version(row.source_store_id);
+                    if (latest && row.source_version !== latest)
+                        continue;
+                }
+                yield row_to_meta(row);
+            }
+        },
+        async delete(id) {
+            const result = await storage.delete_row(id);
+            if (!result.ok)
+                return result;
+            if (!result.value) {
+                return err({ kind: 'observation_not_found', id });
+            }
+            return ok(undefined);
+        },
+        async delete_by_source(source) {
+            return storage.delete_by_source(source.store_id, source.version, source.path);
+        },
+        async is_stale(pointer) {
+            const latest = await get_latest_version(pointer.store_id);
+            if (!latest)
+                return false;
+            return pointer.version !== latest;
+        }
+    };
+}

package/dist/observations/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * @module Observations
+ * @description Re-exports for the observations feature.
+ */
+export * from './types';
+export type { ObservationRow, ObservationInsert } from './schema';
+export { corpus_observations } from './schema';
+export type { ObservationsStorage, StorageQueryOpts, ObservationsCRUD } from './storage';
+export { row_to_observation, row_to_meta, create_observation_row, filter_observation_rows, create_observations_storage } from './storage';
+export { create_observations_client } from './client';
+export * from './utils';
+//# sourceMappingURL=index.d.ts.map

package/dist/observations/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../observations/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,cAAc,SAAS,CAAA;AACvB,YAAY,EAAE,cAAc,EAAE,iBAAiB,EAAE,MAAM,UAAU,CAAA;AACjE,OAAO,EAAE,mBAAmB,EAAE,MAAM,UAAU,CAAA;AAC9C,YAAY,EAAE,mBAAmB,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAA;AAGxF,OAAO,EAAE,kBAAkB,EAAE,WAAW,EAAE,sBAAsB,EAAE,uBAAuB,EAAE,2BAA2B,EAAE,MAAM,WAAW,CAAA;AACzI,OAAO,EAAE,0BAA0B,EAAE,MAAM,UAAU,CAAA;AACrD,cAAc,SAAS,CAAA"}

package/dist/observations/index.js

@@ -0,0 +1,11 @@
+/**
+ * @module Observations
+ * @description Re-exports for the observations feature.
+ */
+// Types
+export * from './types';
+export { corpus_observations } from './schema';
+// Functions
+export { row_to_observation, row_to_meta, create_observation_row, filter_observation_rows, create_observations_storage } from './storage';
+export { create_observations_client } from './client';
+export * from './utils';