ai-database 2.1.3 → 2.3.0

package/dist/pipelines-iceberg-emitter.js

@@ -0,0 +1,351 @@
+/**
+ * Pipelines → Iceberg analytical fan-out emitter — Phase 2 final, bead `aip-0ypt`.
+ *
+ * Implements the {@link AnalyticalEmitter} contract surfaced by
+ * {@link CascadeWriteStrategy} so cascade writes can dual-write into
+ * Iceberg via Cloudflare Pipelines without changing the strategy or
+ * orchestrator surface. Per
+ * [ADR-0003](../../../docs/adr/0003-storage-strategy-pg-clickhouse-default.md),
+ * Stack B's storage shape is:
+ *
+ * ```text
+ *   cascade write
+ *      │
+ *      ▼
+ *   DO SQLite (per-cascade, transactional, source of truth for traversal)
+ *      │
+ *      └──► CascadeWriteStrategy.analyticalEmitter ──► Cloudflare Pipelines ──► R2 Iceberg
+ *                                                            (analytical SOR; ClickHouse reads from here)
+ * ```
+ *
+ * The transactional path through DO SQLite is the source of truth for
+ * cascade correctness. The analytical fan-out is **fire-and-forget** on
+ * the hot path: emitter failures MUST NOT fail the cascade write. The
+ * `CascadeWriteStrategy` already swallows thrown errors from the
+ * emitter; this module additionally never throws — even on completely
+ * misconfigured bindings — so callers get the same shape regardless of
+ * runtime.
+ *
+ * ## Schema mapping
+ *
+ * Iceberg tables for `things` and `actions` mirror the SVO surface used
+ * by the PG/CH/DO SQLite adapters. Columns are kept in lowercase
+ * snake_case (Iceberg is case-insensitive but tooling typically
+ * normalises this way):
+ *
+ * **things table**
+ * - `id` STRING (Thing id; content-hashed by the orchestrator)
+ * - `type` STRING (Thing `$type`)
+ * - `data` STRING (jsonb-style — emitted as a stringified JSON blob;
+ *   downstream readers (CH `JSONExtract`, DataFusion `arrow_cast`) parse
+ *   on read. Iceberg has STRUCT columns but cascade Things are
+ *   open-shape so we keep the column STRING)
+ * - `cascade_id` STRING (the cascade this row belongs to; partition key)
+ * - `tenant_id` STRING NULL (when sharded by tenant)
+ * - `shard_key` STRING (the strategy's routing key, e.g. `cascade:abc`)
+ * - `created_at` TIMESTAMP (emit time; stable)
+ * - `updated_at` TIMESTAMP (emit time; bumped on re-emit)
+ *
+ * **actions table** — wire-compatible with `SVOAction`
+ * - `id` STRING (Action id; orchestrator-supplied or adapter-generated)
+ * - `verb` STRING
+ * - `subject` STRING NULL
+ * - `object` STRING NULL
+ * - `roles` STRING (JSON-stringified Frame role map)
+ * - `data` STRING (JSON-stringified payload)
+ * - `status` STRING (`pending` | `completed` | `failed` | `cancelled`)
+ * - `cascade_id` STRING (partition key)
+ * - `tenant_id` STRING NULL
+ * - `shard_key` STRING
+ * - `timestamp` TIMESTAMP (emit time)
+ *
+ * Schema bootstrap (creating the Iceberg tables) is a deployment-time
+ * concern; this emitter only writes records into an existing table
+ * via the Pipelines binding's `send()`.
+ *
+ * ## Bindings
+ *
+ * The emitter accepts a structurally-typed
+ * {@link PipelinesStreamBindingLike} so the module compiles in plain
+ * Node tests without `@cloudflare/workers-types`. Real Pipelines
+ * bindings produced by `wrangler.toml` satisfy this shape at runtime.
+ * For non-Workers callers (Node / dev / batch jobs) an
+ * {@link HttpPipelinesEmitterOptions} HTTP fallback is supported,
+ * issuing `POST` requests against the Pipelines stream endpoint.
+ *
+ * ## Exactly-once / dedup
+ *
+ * Cloudflare Pipelines is at-least-once by default. Cascade entity
+ * ids are content-hashed by the orchestrator (same inputs → same id),
+ * so re-emits of the same cascade re-use the same `id` field — Iceberg
+ * MERGE-on-read jobs (or the Pipelines binding's optional dedup key)
+ * collapse duplicates downstream. Callers wanting strict
+ * exactly-once semantics should configure dedup on the Pipelines
+ * stream itself; this emitter exposes `dedupKey?: 'id' | null` to
+ * indicate which field to use.
+ *
+ * @see {@link ../../../docs/adr/0003-storage-strategy-pg-clickhouse-default.md}
+ * @see {@link ./cascade-write-strategy.ts}
+ * @packageDocumentation
+ */
+// =============================================================================
+// Public API
+// =============================================================================
+/**
+ * Create an {@link AnalyticalEmitter} that fans out cascade writes
+ * into Iceberg via Cloudflare Pipelines.
+ *
+ * The returned emitter satisfies the
+ * {@link CascadeWriteStrategy.analyticalEmitter} contract — pass it
+ * directly to {@link CascadeWriteStrategy} or
+ * {@link generateCascade} via the `analyticalEmitter` option.
+ *
+ * @example Workers binding mode
+ * ```ts
+ * import { createPipelinesIcebergEmitter, generateCascade } from 'ai-database'
+ *
+ * const emitter = createPipelinesIcebergEmitter({
+ *   binding: env.ANALYTICAL_PIPE,
+ *   thingsTable: 'aidb.things',
+ *   actionsTable: 'aidb.actions',
+ *   tenantId: 'acme',
+ * })
+ *
+ * await generateCascade({
+ *   adapter,
+ *   rootNoun: 'Customer',
+ *   analyticalEmitter: emitter,
+ *   // ...
+ * })
+ * ```
+ *
+ * @example Node HTTP fallback (dev / batch)
+ * ```ts
+ * import { createHttpPipelinesIcebergEmitter } from 'ai-database'
+ *
+ * const emitter = createHttpPipelinesIcebergEmitter({
+ *   url: process.env.PIPELINES_URL,
+ *   authToken: process.env.PIPELINES_TOKEN,
+ * })
+ * ```
+ */
+export function createPipelinesIcebergEmitter(options) {
+    const thingsBinding = options.thingsBinding ?? options.binding;
+    const actionsBinding = options.actionsBinding ?? options.binding;
+    if (!thingsBinding && !actionsBinding) {
+        throw new Error('createPipelinesIcebergEmitter: at least one of `binding`, ' +
+            '`thingsBinding`, or `actionsBinding` must be provided. For ' +
+            'non-Workers callers, use createHttpPipelinesIcebergEmitter() ' +
+            'with an HTTPS endpoint URL instead.');
+    }
+    return makeEmitter({
+        options,
+        sendThings: thingsBinding ? (rows) => Promise.resolve(thingsBinding.send(rows)) : null,
+        sendActions: actionsBinding ? (rows) => Promise.resolve(actionsBinding.send(rows)) : null,
+    });
+}
+/**
+ * Create an {@link AnalyticalEmitter} that fans out cascade writes
+ * into Iceberg via the Pipelines HTTPS stream endpoint.
+ *
+ * Used by non-Workers callers (Node / dev / batch jobs). Workers
+ * deployments should prefer {@link createPipelinesIcebergEmitter}
+ * for lower latency.
+ */
+export function createHttpPipelinesIcebergEmitter(options) {
+    const thingsUrl = options.thingsUrl ?? options.url;
+    const actionsUrl = options.actionsUrl ?? options.url;
+    if (!thingsUrl && !actionsUrl) {
+        throw new Error('createHttpPipelinesIcebergEmitter: at least one of `url`, ' +
+            '`thingsUrl`, or `actionsUrl` must be provided.');
+    }
+    const fetchImpl = options.fetch ??
+        ((input, init) => {
+            // Defer to the runtime's global fetch. Pulled inline so tests can
+            // pass a structural fake without monkey-patching globals.
+            const g = globalThis;
+            if (typeof g.fetch !== 'function') {
+                return Promise.reject(new Error('createHttpPipelinesIcebergEmitter: no global `fetch` available. ' +
+                    'Pass `fetch` in options for non-Worker / non-Node-18+ environments.'));
+            }
+            return g.fetch(input, init);
+        });
+    const headers = { 'Content-Type': 'application/json' };
+    if (options.authToken)
+        headers['Authorization'] = `Bearer ${options.authToken}`;
+    const send = async (url, rows) => {
+        const res = await fetchImpl(url, {
+            method: 'POST',
+            headers,
+            body: JSON.stringify(rows),
+        });
+        if (!res.ok) {
+            throw new Error(`Pipelines HTTP send failed: ${res.status} ${res.statusText}`);
+        }
+    };
+    return makeEmitter({
+        options,
+        sendThings: thingsUrl ? (rows) => send(thingsUrl, rows) : null,
+        sendActions: actionsUrl
+            ? (rows) => send(actionsUrl, thingsUrl === actionsUrl ? rows : rows /* same payload shape */)
+            : null,
+    });
+}
+function makeEmitter(args) {
+    const thingsTable = args.options.thingsTable ?? 'things';
+    const actionsTable = args.options.actionsTable ?? 'actions';
+    const dedupKey = args.options.dedupKey === undefined ? 'id' : args.options.dedupKey;
+    const nowFn = args.options.now ?? (() => new Date().toISOString());
+    const logger = args.options.logger;
+    const awaitSend = args.options.awaitSend ?? false;
+    const optionTenantId = args.options.tenantId;
+    return async (input) => {
+        // Resolve cascade-routing columns from the shard ref. The strategy
+        // guarantees `shard.context` carries `cascadeId` / `tenantId` when
+        // the active strategy needed them.
+        const shard = input.shard;
+        const cascadeId = resolveCascadeId(shard);
+        const tenantId = optionTenantId ?? resolveTenantId(shard);
+        const shardKey = shard.key;
+        const timestamp = nowFn();
+        const thingsRows = buildThingsRows(input.batch, {
+            thingsTable,
+            cascadeId,
+            tenantId,
+            shardKey,
+            timestamp,
+            dedupKey,
+        });
+        const actionsRows = buildActionsRows(input.batch, {
+            actionsTable,
+            cascadeId,
+            tenantId,
+            shardKey,
+            timestamp,
+            dedupKey,
+        });
+        const tasks = [];
+        if (thingsRows.length > 0 && args.sendThings) {
+            const task = Promise.resolve()
+                .then(() => args.sendThings(thingsRows))
+                .catch((err) => {
+                logger?.warn?.('pipelines-iceberg-emitter:things:send-failed', {
+                    error: errorMessage(err),
+                    rows: thingsRows.length,
+                    shardKey,
+                });
+            });
+            tasks.push(task);
+        }
+        if (actionsRows.length > 0 && args.sendActions) {
+            const task = Promise.resolve()
+                .then(() => args.sendActions(actionsRows))
+                .catch((err) => {
+                logger?.warn?.('pipelines-iceberg-emitter:actions:send-failed', {
+                    error: errorMessage(err),
+                    rows: actionsRows.length,
+                    shardKey,
+                });
+            });
+            tasks.push(task);
+        }
+        if (awaitSend && tasks.length > 0) {
+            await Promise.all(tasks);
+        }
+    };
+}
+function buildThingsRows(batch, ctx) {
+    const things = batch.things ?? [];
+    if (things.length === 0)
+        return [];
+    const rows = [];
+    for (const t of things) {
+        const row = {
+            id: t.id,
+            type: t.type,
+            data: stableJsonStringify(t.data),
+            cascade_id: ctx.cascadeId,
+            tenant_id: ctx.tenantId,
+            shard_key: ctx.shardKey,
+            created_at: ctx.timestamp,
+            updated_at: ctx.timestamp,
+            _table: ctx.thingsTable,
+        };
+        if (ctx.dedupKey)
+            row['_dedup_key'] = row[ctx.dedupKey];
+        rows.push(row);
+    }
+    return rows;
+}
+function buildActionsRows(batch, ctx) {
+    const actions = batch.actions ?? [];
+    if (actions.length === 0)
+        return [];
+    const rows = [];
+    for (const a of actions) {
+        const row = {
+            id: a.id ?? generateActionId(ctx.cascadeId, ctx.timestamp, rows.length),
+            verb: a.verb,
+            subject: a.subject ?? null,
+            object: a.object ?? null,
+            roles: stableJsonStringify(a.roles ?? {}),
+            data: stableJsonStringify(a.data ?? {}),
+            status: a.status ?? 'completed',
+            cascade_id: ctx.cascadeId,
+            tenant_id: ctx.tenantId,
+            shard_key: ctx.shardKey,
+            timestamp: ctx.timestamp,
+            _table: ctx.actionsTable,
+        };
+        if (ctx.dedupKey)
+            row['_dedup_key'] = row[ctx.dedupKey];
+        rows.push(row);
+    }
+    return rows;
+}
+// =============================================================================
+// Internals — utilities
+// =============================================================================
+function resolveCascadeId(shard) {
+    const ctxId = shard.context.cascadeId;
+    if (typeof ctxId === 'string' && ctxId.length > 0)
+        return ctxId;
+    // Fall back to the shard key — for `partitioned-by-tenant` and
+    // `unsharded` strategies there is no per-cascade id, so the routing
+    // key is the best we can do. Iceberg readers can group on it.
+    return shard.key;
+}
+function resolveTenantId(shard) {
+    const t = shard.context.tenantId;
+    return typeof t === 'string' && t.length > 0 ? t : null;
+}
+/**
+ * Stable JSON stringify — keys sorted recursively. Iceberg dedup at
+ * compaction time depends on identical row bytes for the same logical
+ * row; un-sorted key ordering would defeat that.
+ */
+function stableJsonStringify(value) {
+    return JSON.stringify(value, (_key, val) => {
+        if (val === null || typeof val !== 'object' || Array.isArray(val))
+            return val;
+        const sortedKeys = Object.keys(val).sort();
+        const result = {};
+        for (const k of sortedKeys) {
+            result[k] = val[k];
+        }
+        return result;
+    });
+}
+/**
+ * Generate a deterministic-enough Action id when the orchestrator
+ * didn't supply one. Production callers always supply Action ids via
+ * the orchestrator's content-hash; this is a safety net for ad-hoc
+ * `writeBatch` callers.
+ */
+function generateActionId(cascadeId, timestamp, index) {
+    return `act-${cascadeId.slice(0, 16)}-${timestamp.replace(/[^0-9]/g, '').slice(0, 14)}-${index}`;
+}
+function errorMessage(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+//# sourceMappingURL=pipelines-iceberg-emitter.js.map

package/dist/pipelines-iceberg-emitter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pipelines-iceberg-emitter.js","sourceRoot":"","sources":["../src/pipelines-iceberg-emitter.ts"],"names":[],"mappings":"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"}

package/dist/provider-capabilities.d.ts

@@ -0,0 +1,146 @@
+/**
+ * Provider Capability Detection and Management
+ *
+ * This module provides runtime detection of provider capabilities,
+ * enabling graceful degradation when advanced features are unavailable.
+ *
+ * @packageDocumentation
+ */
+import type { DBProvider } from './schema.js';
+/**
+ * Capability flags indicating which features a provider supports
+ *
+ * @example
+ * ```ts
+ * const capabilities: ProviderCapabilities = {
+ *   hasSemanticSearch: true,
+ *   hasEvents: true,
+ *   hasActions: true,
+ *   hasArtifacts: true,
+ *   hasBatchOperations: true,
+ * }
+ * ```
+ */
+export interface ProviderCapabilities {
+    /** Whether the provider supports semantic/vector search */
+    hasSemanticSearch: boolean;
+    /** Whether the provider supports event emission and subscription */
+    hasEvents: boolean;
+    /** Whether the provider supports durable actions (pending/active/completed) */
+    hasActions: boolean;
+    /** Whether the provider supports artifact storage (embeddings, caches) */
+    hasArtifacts: boolean;
+    /** Whether the provider supports batch operations with concurrency control */
+    hasBatchOperations: boolean;
+}
+/**
+ * Detect which capabilities a provider supports by examining its methods
+ *
+ * Probes the provider for the presence of advanced methods to determine
+ * which features are available. Results are cached per-provider.
+ *
+ * @param provider - The database provider to inspect
+ * @returns Detected capabilities
+ *
+ * @example
+ * ```ts
+ * const provider = createMemoryProvider()
+ * const capabilities = await detectCapabilities(provider)
+ *
+ * if (capabilities.hasSemanticSearch) {
+ *   const results = await provider.semanticSearch('Post', 'machine learning')
+ * } else {
+ *   const results = await provider.search('Post', 'machine learning')
+ * }
+ * ```
+ */
+export declare function detectCapabilities(provider: DBProvider): Promise<ProviderCapabilities>;
+/**
+ * Clear the capability cache for a specific provider
+ *
+ * Useful when a provider's capabilities change dynamically.
+ *
+ * @param provider - The provider to clear from cache
+ */
+export declare function clearCapabilityCache(provider: DBProvider): void;
+/**
+ * Error thrown when attempting to use a feature that the provider doesn't support
+ *
+ * @example
+ * ```ts
+ * try {
+ *   await provider.semanticSearch('Post', 'query')
+ * } catch (e) {
+ *   if (isCapabilityNotSupportedError(e)) {
+ *     console.log(`${e.capability} is not supported, using fallback...`)
+ *   }
+ *   throw e
+ * }
+ * ```
+ */
+export declare class CapabilityNotSupportedError extends Error {
+    /** The capability that was requested but not supported */
+    readonly capability: string;
+    /** Optional suggested alternative */
+    readonly alternative?: string | undefined;
+    readonly code = "CAPABILITY_NOT_SUPPORTED";
+    readonly name = "CapabilityNotSupportedError";
+    constructor(
+    /** The capability that was requested but not supported */
+    capability: string, 
+    /** Optional custom error message */
+    message?: string, 
+    /** Optional suggested alternative */
+    alternative?: string | undefined);
+}
+/**
+ * Type guard to check if an error is a CapabilityNotSupportedError
+ *
+ * @param error - The error to check
+ * @returns True if the error is a CapabilityNotSupportedError
+ */
+export declare function isCapabilityNotSupportedError(error: unknown): error is CapabilityNotSupportedError;
+/**
+ * Require a capability to be available, throwing if not
+ *
+ * Use this before calling methods that require specific capabilities.
+ *
+ * @param capabilities - The detected capabilities
+ * @param capability - The capability key to require
+ * @param message - Optional custom error message
+ * @throws CapabilityNotSupportedError if the capability is not available
+ *
+ * @example
+ * ```ts
+ * const capabilities = await detectCapabilities(provider)
+ * requireCapability(capabilities, 'hasSemanticSearch')
+ * // Safe to call semanticSearch now
+ * ```
+ */
+export declare function requireCapability(capabilities: ProviderCapabilities, capability: keyof ProviderCapabilities, message?: string): void;
+/**
+ * Log a warning if a capability is unavailable (only once per capability)
+ *
+ * @param capabilities - The detected capabilities
+ * @param capability - The capability key to check
+ * @param featureName - Human-readable name for the warning message
+ *
+ * @example
+ * ```ts
+ * warnIfUnavailable(capabilities, 'hasSemanticSearch', 'semanticSearch')
+ * // Logs: "Warning: semanticSearch is not available with this provider"
+ * ```
+ */
+export declare function warnIfUnavailable(capabilities: ProviderCapabilities, capability: keyof ProviderCapabilities, featureName: string): void;
+/**
+ * Clear warning suppression (useful for testing)
+ */
+export declare function clearWarningHistory(): void;
+/**
+ * Standard capability matrix for known providers
+ *
+ * This is a reference for documentation purposes. Actual capabilities
+ * are detected at runtime using detectCapabilities().
+ */
+export declare const PROVIDER_CAPABILITY_MATRIX: Record<string, ProviderCapabilities>;
+//# sourceMappingURL=provider-capabilities.d.ts.map

package/dist/provider-capabilities.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider-capabilities.d.ts","sourceRoot":"","sources":["../src/provider-capabilities.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AAO7C;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,oBAAoB;IACnC,2DAA2D;IAC3D,iBAAiB,EAAE,OAAO,CAAA;IAC1B,oEAAoE;IACpE,SAAS,EAAE,OAAO,CAAA;IAClB,+EAA+E;IAC/E,UAAU,EAAE,OAAO,CAAA;IACnB,0EAA0E;IAC1E,YAAY,EAAE,OAAO,CAAA;IACrB,8EAA8E;IAC9E,kBAAkB,EAAE,OAAO,CAAA;CAC5B;AAWD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAsB,kBAAkB,CAAC,QAAQ,EAAE,UAAU,GAAG,OAAO,CAAC,oBAAoB,CAAC,CAuC5F;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,UAAU,GAAG,IAAI,CAE/D;AAMD;;;;;;;;;;;;;;GAcG;AACH,qBAAa,2BAA4B,SAAQ,KAAK;IAKlD,0DAA0D;aAC1C,UAAU,EAAE,MAAM;IAGlC,qCAAqC;aACrB,WAAW,CAAC,EAAE,MAAM;IATtC,SAAgB,IAAI,8BAA6B;IACjD,SAAyB,IAAI,iCAAgC;;IAG3D,0DAA0D;IAC1C,UAAU,EAAE,MAAM;IAClC,oCAAoC;IACpC,OAAO,CAAC,EAAE,MAAM;IAChB,qCAAqC;IACrB,WAAW,CAAC,EAAE,MAAM,YAAA;CAKvC;AAED;;;;;GAKG;AACH,wBAAgB,6BAA6B,CAC3C,KAAK,EAAE,OAAO,GACb,KAAK,IAAI,2BAA2B,CAQtC;AAMD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,iBAAiB,CAC/B,YAAY,EAAE,oBAAoB,EAClC,UAAU,EAAE,MAAM,oBAAoB,EACtC,OAAO,CAAC,EAAE,MAAM,GACf,IAAI,CAIN;AAWD;;;;;;;;;;;;GAYG;AACH,wBAAgB,iBAAiB,CAC/B,YAAY,EAAE,oBAAoB,EAClC,UAAU,EAAE,MAAM,oBAAoB,EACtC,WAAW,EAAE,MAAM,GAClB,IAAI,CAKN;AAED;;GAEG;AACH,wBAAgB,mBAAmB,IAAI,IAAI,CAE1C;AAMD;;;;;GAKG;AACH,eAAO,MAAM,0BAA0B,EAAE,MAAM,CAAC,MAAM,EAAE,oBAAoB,CAsB3E,CAAA"}