@f0rbit/corpus 0.1.7 → 0.1.8

package/dist/observations/client.d.ts

@@ -2,8 +2,8 @@
  * @module ObservationsClient
  * @description Centralized business logic for observations, built on storage adapters.
  */
-import type { MetadataClient, ObservationsClient } from '../types';
-import type { ObservationsStorage } from './storage';
+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.

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

@@ -1 +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"}
+{"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,CAAC;AAExF,OAAO,KAAK,EAAE,mBAAmB,EAAoB,MAAM,WAAW,CAAC;AAuBvE;;;GAGG;AACH,wBAAgB,0BAA0B,CAAC,OAAO,EAAE,mBAAmB,EAAE,QAAQ,EAAE,cAAc,GAAG,kBAAkB,CAmHrH"}

package/dist/observations/client.js

@@ -2,9 +2,9 @@
  * @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';
+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.
@@ -19,7 +19,7 @@ function to_storage_opts(opts) {
         created_before: opts.created_before?.toISOString(),
         observed_after: opts.after?.toISOString(),
         observed_before: opts.before?.toISOString(),
-        limit: opts.limit
+        limit: opts.limit,
     };
 }
 /**
@@ -31,21 +31,29 @@ export function create_observations_client(storage, metadata) {
         const result = await metadata.get_latest(store_id);
         return result.ok ? result.value.version : null;
     }
+    async function resolve_version(store_id, resolver) {
+        if (resolver) {
+            const resolved = await resolver(store_id);
+            if (resolved !== null)
+                return resolved;
+        }
+        return get_latest_version(store_id);
+    }
     return {
         async put(type, opts) {
             const validation = type.schema.safeParse(opts.content);
             if (!validation.success) {
                 return err({
-                    kind: 'validation_error',
+                    kind: "validation_error",
                     cause: validation.error,
-                    message: validation.error.message
+                    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
+                derived_from: opts.derived_from,
             });
             const result = await storage.put_row(row);
             if (!result.ok)
@@ -58,7 +66,7 @@ export function create_observations_client(storage, metadata) {
                 ...(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 })
+                ...(opts.derived_from && { derived_from: opts.derived_from }),
             };
             return ok(observation);
         },
@@ -67,16 +75,21 @@ export function create_observations_client(storage, metadata) {
             if (!result.ok)
                 return result;
             if (!result.value) {
-                return err({ kind: 'observation_not_found', id });
+                return err({ kind: "observation_not_found", id });
             }
             return ok(row_to_observation(result.value));
         },
         async *query(opts = {}) {
             const storageOpts = to_storage_opts(opts);
+            const version_cache = new Map();
             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)
+                    let canonical_version = version_cache.get(row.source_store_id);
+                    if (canonical_version === undefined) {
+                        canonical_version = await resolve_version(row.source_store_id, opts.version_resolver);
+                        version_cache.set(row.source_store_id, canonical_version);
+                    }
+                    if (canonical_version && row.source_version !== canonical_version)
                         continue;
                 }
                 yield row_to_observation(row);
@@ -84,10 +97,15 @@ export function create_observations_client(storage, metadata) {
         },
         async *query_meta(opts = {}) {
             const storageOpts = to_storage_opts(opts);
+            const version_cache = new Map();
             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)
+                    let canonical_version = version_cache.get(row.source_store_id);
+                    if (canonical_version === undefined) {
+                        canonical_version = await resolve_version(row.source_store_id, opts.version_resolver);
+                        version_cache.set(row.source_store_id, canonical_version);
+                    }
+                    if (canonical_version && row.source_version !== canonical_version)
                         continue;
                 }
                 yield row_to_meta(row);
@@ -98,7 +116,7 @@ export function create_observations_client(storage, metadata) {
             if (!result.ok)
                 return result;
             if (!result.value) {
-                return err({ kind: 'observation_not_found', id });
+                return err({ kind: "observation_not_found", id });
             }
             return ok(undefined);
         },
@@ -110,6 +128,6 @@ export function create_observations_client(storage, metadata) {
             if (!latest)
                 return false;
             return pointer.version !== latest;
-        }
+        },
     };
 }

package/dist/observations/types.d.ts

@@ -2,7 +2,7 @@
  * @module ObservationTypes
  * @description Type definitions for the observations feature.
  */
-import type { ZodType } from 'zod';
+import type { ZodType } from "zod";
 /**
  * Universal address to versioned content within a corpus store.
  *
@@ -105,7 +105,38 @@ export type Observation<T = unknown> = {
  * @category Types
  * @group Observation Types
  */
-export type ObservationMeta = Omit<Observation<never>, 'content'>;
+export type ObservationMeta = Omit<Observation<never>, "content">;
+/**
+ * Options for creating a new observation.
+ *
+ * @category Types
+ * @group Observation Types
+ */
+export type ObservationPutOpts<T> = {
+    source: SnapshotPointer;
+    content: T;
+    confidence?: number;
+    observed_at?: Date;
+    derived_from?: SnapshotPointer[];
+};
+/**
+ * Function that resolves which version is "canonical" for a given store.
+ * Return null to fall back to default behavior (most recent by created_at).
+ *
+ * @category Types
+ * @group Observation Types
+ *
+ * @example
+ * ```ts
+ * const resolver: VersionResolver = async (store_id) => {
+ *   const published = await db.query.published_reports.findFirst({
+ *     where: eq(published_reports.store_id, store_id)
+ *   });
+ *   return published?.version ?? null;
+ * };
+ * ```
+ */
+export type VersionResolver = (store_id: string) => Promise<string | null>;
 /**
  * Query options for filtering observations.
  *
@@ -142,31 +173,30 @@ export type ObservationQueryOpts = {
     include_stale?: boolean;
     limit?: number;
     cursor?: string;
+    /**
+     * Custom function to resolve which version is "current" for a given store.
+     * When provided and include_stale is false, this takes precedence over
+     * the default "most recent by created_at" staleness logic.
+     *
+     * If the resolver returns null for a store_id, falls back to default behavior.
+     */
+    version_resolver?: VersionResolver;
 };
 /**
- * Options for creating a new observation.
+ * Utility type to extract the content type from an ObservationTypeDef.
  *
  * @category Types
  * @group Observation Types
  *
  * @example
  * ```ts
- * const opts: ObservationPutOpts<EntityMention> = {
- *   source: { store_id: 'hansard', version: 'AZJx4vM', path: '$.speeches[0]' },
- *   content: { entity: 'Climate Change', entity_type: 'topic' },
- *   confidence: 0.95,
- *   observed_at: new Date(),
- *   derived_from: [{ store_id: 'raw_text', version: 'xyz789' }]
- * }
+ * const entity_mention = define_observation_type('entity_mention', EntityMentionSchema)
+ *
+ * type EntityMention = InferObservationContent<typeof entity_mention>
+ * // => { entity: string; entity_type: 'person' | 'organization' | ... }
  * ```
  */
-export type ObservationPutOpts<T> = {
-    source: SnapshotPointer;
-    content: T;
-    confidence?: number;
-    observed_at?: Date;
-    derived_from?: SnapshotPointer[];
-};
+export type InferObservationContent<T> = T extends ObservationTypeDef<infer C> ? C : never;
 /**
  * Defines a typed observation schema.
  *
@@ -201,19 +231,4 @@ export type ObservationPutOpts<T> = {
  * ```
  */
 export declare function define_observation_type<T>(name: string, schema: ZodType<T>): ObservationTypeDef<T>;
-/**
- * Utility type to extract the content type from an ObservationTypeDef.
- *
- * @category Types
- * @group Observation Types
- *
- * @example
- * ```ts
- * const entity_mention = define_observation_type('entity_mention', EntityMentionSchema)
- *
- * type EntityMention = InferObservationContent<typeof entity_mention>
- * // => { entity: string; entity_type: 'person' | 'organization' | ... }
- * ```
- */
-export type InferObservationContent<T> = T extends ObservationTypeDef<infer C> ? C : never;
 //# sourceMappingURL=types.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../observations/types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,KAAK,CAAA;AAElC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,MAAM,MAAM,eAAe,GAAG;IAC5B,QAAQ,EAAE,MAAM,CAAA;IAChB,OAAO,EAAE,MAAM,CAAA;IACf,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,IAAI,CAAC,EAAE;QACL,KAAK,EAAE,MAAM,CAAA;QACb,GAAG,EAAE,MAAM,CAAA;KACZ,CAAA;CACF,CAAA;AAED;;;;;;;;GAQG;AACH,MAAM,MAAM,kBAAkB,CAAC,CAAC,IAAI;IAClC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC,CAAA;CAC5B,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,MAAM,MAAM,WAAW,CAAC,CAAC,GAAG,OAAO,IAAI;IACrC,EAAE,EAAE,MAAM,CAAA;IACV,IAAI,EAAE,MAAM,CAAA;IACZ,MAAM,EAAE,eAAe,CAAA;IACvB,OAAO,EAAE,CAAC,CAAA;IACV,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,WAAW,CAAC,EAAE,IAAI,CAAA;IAClB,UAAU,EAAE,IAAI,CAAA;IAChB,YAAY,CAAC,EAAE,eAAe,EAAE,CAAA;CACjC,CAAA;AAED;;;;;;;GAOG;AACH,MAAM,MAAM,eAAe,GAAG,IAAI,CAAC,WAAW,CAAC,KAAK,CAAC,EAAE,SAAS,CAAC,CAAA;AAEjE;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,MAAM,oBAAoB,GAAG;IACjC,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAA;IACxB,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB,KAAK,CAAC,EAAE,IAAI,CAAA;IACZ,MAAM,CAAC,EAAE,IAAI,CAAA;IACb,aAAa,CAAC,EAAE,IAAI,CAAA;IACpB,cAAc,CAAC,EAAE,IAAI,CAAA;IACrB,aAAa,CAAC,EAAE,OAAO,CAAA;IACvB,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,MAAM,CAAC,EAAE,MAAM,CAAA;CAChB,CAAA;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,MAAM,kBAAkB,CAAC,CAAC,IAAI;IAClC,MAAM,EAAE,eAAe,CAAA;IACvB,OAAO,EAAE,CAAC,CAAA;IACV,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,WAAW,CAAC,EAAE,IAAI,CAAA;IAClB,YAAY,CAAC,EAAE,eAAe,EAAE,CAAA;CACjC,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,wBAAgB,uBAAuB,CAAC,CAAC,EACvC,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC,GACjB,kBAAkB,CAAC,CAAC,CAAC,CAEvB;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,MAAM,uBAAuB,CAAC,CAAC,IAAI,CAAC,SAAS,kBAAkB,CAAC,MAAM,CAAC,CAAC,GAAG,CAAC,GAAG,KAAK,CAAA"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../observations/types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,KAAK,CAAC;AAEnC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,MAAM,MAAM,eAAe,GAAG;IAC7B,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE;QACN,KAAK,EAAE,MAAM,CAAC;QACd,GAAG,EAAE,MAAM,CAAC;KACZ,CAAC;CACF,CAAC;AAEF;;;;;;;;GAQG;AACH,MAAM,MAAM,kBAAkB,CAAC,CAAC,IAAI;IACnC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC;CAC5B,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,MAAM,MAAM,WAAW,CAAC,CAAC,GAAG,OAAO,IAAI;IACtC,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,eAAe,CAAC;IACxB,OAAO,EAAE,CAAC,CAAC;IACX,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,WAAW,CAAC,EAAE,IAAI,CAAC;IACnB,UAAU,EAAE,IAAI,CAAC;IACjB,YAAY,CAAC,EAAE,eAAe,EAAE,CAAC;CACjC,CAAC;AAEF;;;;;;;GAOG;AACH,MAAM,MAAM,eAAe,GAAG,IAAI,CAAC,WAAW,CAAC,KAAK,CAAC,EAAE,SAAS,CAAC,CAAC;AAElE;;;;;GAKG;AACH,MAAM,MAAM,kBAAkB,CAAC,CAAC,IAAI;IACnC,MAAM,EAAE,eAAe,CAAC;IACxB,OAAO,EAAE,CAAC,CAAC;IACX,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,WAAW,CAAC,EAAE,IAAI,CAAC;IACnB,YAAY,CAAC,EAAE,eAAe,EAAE,CAAC;CACjC,CAAC;AAEF;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,MAAM,eAAe,GAAG,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;AAE3E;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,MAAM,oBAAoB,GAAG;IAClC,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IACzB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,KAAK,CAAC,EAAE,IAAI,CAAC;IACb,MAAM,CAAC,EAAE,IAAI,CAAC;IACd,aAAa,CAAC,EAAE,IAAI,CAAC;IACrB,cAAc,CAAC,EAAE,IAAI,CAAC;IACtB,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;;;OAMG;IACH,gBAAgB,CAAC,EAAE,eAAe,CAAC;CACnC,CAAC;AAEF;;;;;;;;;;;;;GAaG;AACH,MAAM,MAAM,uBAAuB,CAAC,CAAC,IAAI,CAAC,SAAS,kBAAkB,CAAC,MAAM,CAAC,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;AAE3F;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,wBAAgB,uBAAuB,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC,GAAG,kBAAkB,CAAC,CAAC,CAAC,CAElG"}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@f0rbit/corpus",
-	"version": "0.1.7",
+	"version": "0.1.8",
 	"description": "A functional snapshotting library for TypeScript with versioned data storage, lineage tracking, and multiple backend support",
 	"module": "dist/index.js",
 	"main": "dist/index.js",