@f0rbit/corpus 0.1.5 → 0.1.7

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';

package/dist/observations/schema.d.ts

@@ -0,0 +1,267 @@
+/**
+ * @module ObservationSchema
+ * @description Database schema definitions for observations using Drizzle ORM.
+ */
+/**
+ * Drizzle ORM schema for the corpus_observations table.
+ *
+ * Used by the Cloudflare backend with D1 (SQLite). Defines the table structure
+ * for storing observation metadata linking structured facts to versioned content.
+ *
+ * Columns:
+ * - `id` - Primary key (unique observation identifier)
+ * - `type` - Observation type name (e.g., 'entity_mention')
+ * - `source_store_id` + `source_version` - Points to the snapshot this observation is about
+ * - `source_path` - Optional JSONPath expression to specific element
+ * - `source_span_start` / `source_span_end` - Optional character range within text
+ * - `content` - JSON-encoded observation data
+ * - `confidence` - Optional confidence score (0.0 to 1.0)
+ * - `observed_at` - When the observation was made (ISO 8601)
+ * - `created_at` - When the record was stored (ISO 8601)
+ * - `derived_from` - Optional JSON array of SnapshotPointers for provenance
+ *
+ * @example
+ * ```ts
+ * import { drizzle } from 'drizzle-orm/d1'
+ * import { corpus_observations } from 'corpus/observation-schema'
+ *
+ * const db = drizzle(env.D1)
+ * const rows = await db.select().from(corpus_observations).where(eq(corpus_observations.type, 'entity_mention'))
+ * ```
+ */
+export declare const corpus_observations: import("drizzle-orm/sqlite-core").SQLiteTableWithColumns<{
+    name: "corpus_observations";
+    schema: undefined;
+    columns: {
+        id: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: "id";
+            tableName: "corpus_observations";
+            dataType: "string";
+            columnType: "SQLiteText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: true;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {
+            length: number | undefined;
+        }>;
+        type: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: "type";
+            tableName: "corpus_observations";
+            dataType: "string";
+            columnType: "SQLiteText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {
+            length: number | undefined;
+        }>;
+        source_store_id: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: "source_store_id";
+            tableName: "corpus_observations";
+            dataType: "string";
+            columnType: "SQLiteText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {
+            length: number | undefined;
+        }>;
+        source_version: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: "source_version";
+            tableName: "corpus_observations";
+            dataType: "string";
+            columnType: "SQLiteText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {
+            length: number | undefined;
+        }>;
+        source_path: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: "source_path";
+            tableName: "corpus_observations";
+            dataType: "string";
+            columnType: "SQLiteText";
+            data: string;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {
+            length: number | undefined;
+        }>;
+        source_span_start: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: "source_span_start";
+            tableName: "corpus_observations";
+            dataType: "string";
+            columnType: "SQLiteText";
+            data: string;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {
+            length: number | undefined;
+        }>;
+        source_span_end: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: "source_span_end";
+            tableName: "corpus_observations";
+            dataType: "string";
+            columnType: "SQLiteText";
+            data: string;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {
+            length: number | undefined;
+        }>;
+        content: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: "content";
+            tableName: "corpus_observations";
+            dataType: "string";
+            columnType: "SQLiteText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {
+            length: number | undefined;
+        }>;
+        confidence: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: "confidence";
+            tableName: "corpus_observations";
+            dataType: "number";
+            columnType: "SQLiteReal";
+            data: number;
+            driverParam: number;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        observed_at: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: "observed_at";
+            tableName: "corpus_observations";
+            dataType: "string";
+            columnType: "SQLiteText";
+            data: string;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {
+            length: number | undefined;
+        }>;
+        created_at: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: "created_at";
+            tableName: "corpus_observations";
+            dataType: "string";
+            columnType: "SQLiteText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {
+            length: number | undefined;
+        }>;
+        derived_from: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: "derived_from";
+            tableName: "corpus_observations";
+            dataType: "string";
+            columnType: "SQLiteText";
+            data: string;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {
+            length: number | undefined;
+        }>;
+    };
+    dialect: "sqlite";
+}>;
+export type ObservationRow = typeof corpus_observations.$inferSelect;
+export type ObservationInsert = typeof corpus_observations.$inferInsert;
+//# sourceMappingURL=schema.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../../observations/schema.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAIH;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EA0B7B,CAAA;AAEH,MAAM,MAAM,cAAc,GAAG,OAAO,mBAAmB,CAAC,YAAY,CAAA;AACpE,MAAM,MAAM,iBAAiB,GAAG,OAAO,mBAAmB,CAAC,YAAY,CAAA"}

package/dist/observations/schema.js

@@ -0,0 +1,55 @@
+/**
+ * @module ObservationSchema
+ * @description Database schema definitions for observations using Drizzle ORM.
+ */
+import { sqliteTable, text, real, index } from 'drizzle-orm/sqlite-core';
+/**
+ * Drizzle ORM schema for the corpus_observations table.
+ *
+ * Used by the Cloudflare backend with D1 (SQLite). Defines the table structure
+ * for storing observation metadata linking structured facts to versioned content.
+ *
+ * Columns:
+ * - `id` - Primary key (unique observation identifier)
+ * - `type` - Observation type name (e.g., 'entity_mention')
+ * - `source_store_id` + `source_version` - Points to the snapshot this observation is about
+ * - `source_path` - Optional JSONPath expression to specific element
+ * - `source_span_start` / `source_span_end` - Optional character range within text
+ * - `content` - JSON-encoded observation data
+ * - `confidence` - Optional confidence score (0.0 to 1.0)
+ * - `observed_at` - When the observation was made (ISO 8601)
+ * - `created_at` - When the record was stored (ISO 8601)
+ * - `derived_from` - Optional JSON array of SnapshotPointers for provenance
+ *
+ * @example
+ * ```ts
+ * import { drizzle } from 'drizzle-orm/d1'
+ * import { corpus_observations } from 'corpus/observation-schema'
+ *
+ * const db = drizzle(env.D1)
+ * const rows = await db.select().from(corpus_observations).where(eq(corpus_observations.type, 'entity_mention'))
+ * ```
+ */
+export const corpus_observations = sqliteTable('corpus_observations', {
+    id: text('id').primaryKey(),
+    type: text('type').notNull(),
+    // Source pointer
+    source_store_id: text('source_store_id').notNull(),
+    source_version: text('source_version').notNull(),
+    source_path: text('source_path'),
+    source_span_start: text('source_span_start'),
+    source_span_end: text('source_span_end'),
+    // Content
+    content: text('content').notNull(),
+    confidence: real('confidence'),
+    // Timestamps
+    observed_at: text('observed_at'),
+    created_at: text('created_at').notNull(),
+    // Derivation lineage
+    derived_from: text('derived_from'),
+}, (table) => ({
+    type_idx: index('idx_obs_type').on(table.type),
+    source_idx: index('idx_obs_source').on(table.source_store_id, table.source_version),
+    type_observed_idx: index('idx_obs_type_observed').on(table.type, table.observed_at),
+    type_source_idx: index('idx_obs_type_source').on(table.type, table.source_store_id),
+}));

package/dist/observations/storage.d.ts

@@ -0,0 +1,75 @@
+/**
+ * @module ObservationsStorage
+ * @description Raw storage interface and row conversion utilities for observations.
+ */
+import type { Result, CorpusError } from '../types';
+import type { ObservationRow } from './schema';
+import type { Observation, ObservationMeta, SnapshotPointer } from './types';
+/**
+ * Query options for raw storage operations.
+ * Dates are ISO strings at the storage layer.
+ */
+export type StorageQueryOpts = {
+    type?: string | string[];
+    source_store_id?: string;
+    source_version?: string;
+    source_prefix?: string;
+    created_after?: string;
+    created_before?: string;
+    observed_after?: string;
+    observed_before?: string;
+    limit?: number;
+};
+/**
+ * Raw storage adapter for observation rows.
+ * Backends implement this thin interface; all business logic lives in the client.
+ */
+export type ObservationsStorage = {
+    /** Store a row. Returns the row on success. */
+    put_row: (row: ObservationRow) => Promise<Result<ObservationRow, CorpusError>>;
+    /** Get a row by ID. Returns null if not found. */
+    get_row: (id: string) => Promise<Result<ObservationRow | null, CorpusError>>;
+    /** Query rows with optional filters. */
+    query_rows: (opts?: StorageQueryOpts) => AsyncIterable<ObservationRow>;
+    /** Delete a row by ID. Returns true if deleted, false if not found. */
+    delete_row: (id: string) => Promise<Result<boolean, CorpusError>>;
+    /** Delete rows matching source. Returns count deleted. */
+    delete_by_source: (store_id: string, version: string, path?: string) => Promise<Result<number, CorpusError>>;
+};
+/**
+ * Convert a storage row to an Observation (includes content).
+ */
+export declare function row_to_observation(row: ObservationRow): Observation;
+/**
+ * Convert a storage row to ObservationMeta (excludes content).
+ */
+export declare function row_to_meta(row: ObservationRow): ObservationMeta;
+/**
+ * Create an ObservationRow from put options.
+ */
+export declare function create_observation_row(id: string, type_name: string, source: SnapshotPointer, content: unknown, opts: {
+    confidence?: number;
+    observed_at?: Date;
+    derived_from?: SnapshotPointer[];
+}): ObservationRow;
+/**
+ * Filter and sort observation rows based on query options.
+ * Used by in-memory storage implementations (memory backend, file backend).
+ */
+export declare function filter_observation_rows(rows: ObservationRow[], opts?: StorageQueryOpts): ObservationRow[];
+/**
+ * Simple CRUD interface for observation storage backends.
+ */
+export type ObservationsCRUD = {
+    get_all: () => Promise<ObservationRow[]>;
+    set_all: (rows: ObservationRow[]) => Promise<void>;
+    get_one: (id: string) => Promise<ObservationRow | null>;
+    add_one: (row: ObservationRow) => Promise<void>;
+    remove_one: (id: string) => Promise<boolean>;
+};
+/**
+ * Create an ObservationsStorage from simple CRUD operations.
+ * Used by memory and file backends.
+ */
+export declare function create_observations_storage(crud: ObservationsCRUD): ObservationsStorage;
+//# sourceMappingURL=storage.d.ts.map