@venturekit-pro/ai 0.0.47 → 0.0.50

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/tracing/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAErD,MAAM,MAAM,gBAAgB,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,MAAM,EAAE,GAAG,MAAM,EAAE,GAAG,OAAO,EAAE,CAAC;AAE3F,MAAM,WAAW,MAAM;IACrB,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,gBAAgB,GAAG,OAAO,CAAC;IAC5D,aAAa,CAAC,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,GAAG,OAAO,CAAC;IACrE,eAAe,CAAC,SAAS,EAAE,KAAK,GAAG,MAAM,GAAG,IAAI,CAAC;IACjD,SAAS,CAAC,MAAM,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC;IAC/D,GAAG,IAAI,IAAI,CAAC;CACb;AAED,MAAM,WAAW,aAAa;IAC5B,sDAAsD;IACtD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAC;CAC/C;AAED,MAAM,WAAW,QAAQ;IACvB,eAAe,CAAC,CAAC,SAAS,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,EACjD,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,aAAa,EACtB,EAAE,EAAE,CAAC,GACJ,UAAU,CAAC,CAAC,CAAC,CAAC;CAClB;AAED;;;;;;;;GAQG;AACH,wBAAgB,UAAU,CAAC,IAAI,SAAkB,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,QAAQ,GAAG,SAAS,CAIzF;AAED,eAAO,MAAM,SAAS;;;CAAsC,CAAC;AAC7D,eAAO,MAAM,WAAW;;;CAA+B,CAAC;AAExD,8DAA8D;AAC9D,wBAAgB,aAAa,CAAC,QAAQ,EAAE,YAAY,GAAG,MAAM,CAE5D;AAED,wFAAwF;AACxF,wBAAgB,UAAU,CACxB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,gBAAgB,GAAG,IAAI,GAAG,SAAS,CAAC,GAC1D,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAKlC;AAED;;;;GAIG;AACH,wBAAsB,MAAM,CAAC,CAAC,EAC5B,MAAM,EAAE,QAAQ,GAAG,SAAS,EAC5B,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,aAAa,EACtB,EAAE,EAAE,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,KAAK,OAAO,CAAC,CAAC,CAAC,GACtC,OAAO,CAAC,CAAC,CAAC,CAgBZ"}

package/dist/tracing/index.js

@@ -0,0 +1,72 @@
+/**
+ * OpenTelemetry GenAI spans without a dependency: pass any tracer with
+ * `startActiveSpan` — an `@opentelemetry/api` `Tracer`
+ * (`trace.getTracer('venturekit-ai')`) fits as is — to the gateway, the
+ * agent loop or the harness.
+ *
+ *   harness.node <graph>/<node>   one per node attempt (run, step, attempt, outcome, cost)
+ *   invoke_agent <name>           one per `runAgent`
+ *   execute_tool <tool>           one per tool call
+ *   chat <model>                  one per gateway call (retries and fallbacks inside)
+ *
+ * Model-call attributes follow the GenAI semantic conventions
+ * (`gen_ai.provider.name`, `gen_ai.request.model`, `gen_ai.usage.*` with
+ * cache reads and writes, `gen_ai.response.finish_reasons`,
+ * `gen_ai.response.time_to_first_chunk`); VentureKit's own (cost, call id,
+ * tenant, feature, fallback) are under `vk.ai.*` / `vk.harness.*`. Spans
+ * nest through the tracer's active context, so the exporter (CloudWatch /
+ * X-Ray, OTLP…) is whatever the app configured.
+ */
+/**
+ * The tracer of the OpenTelemetry SDK registered in this process (the AWS
+ * Lambda Layer for OpenTelemetry registers one before the handler loads —
+ * `lambda.otel` in the VentureKit config), or `undefined` when none is.
+ *
+ * Reads the global registry `@opentelemetry/api` v1 keeps on `globalThis`
+ * rather than importing the package: nothing to install, and it works in
+ * Lambda bundles where the layer's packages can't be `import()`ed.
+ */
+export function otelTracer(name = 'venturekit-ai', version) {
+    const api = globalThis[Symbol.for('opentelemetry.js.api.1')];
+    return api?.trace?.getTracer(name, version);
+}
+export const SPAN_KIND = { INTERNAL: 0, CLIENT: 2 };
+export const SPAN_STATUS = { OK: 1, ERROR: 2 };
+/** GenAI `gen_ai.provider.name` for a VentureKit provider. */
+export function genAiProvider(provider) {
+    return provider === 'google' ? 'gcp.gen_ai' : provider;
+}
+/** Attributes without the undefined / null values (OpenTelemetry drops them anyway). */
+export function attributes(values) {
+    const out = {};
+    for (const [key, value] of Object.entries(values))
+        if (value !== undefined && value !== null)
+            out[key] = value;
+    return out;
+}
+/**
+ * Run `fn` in an active span when a tracer is set (`span` is `null`
+ * otherwise). A thrown error is recorded and marks the span as failed;
+ * the span always ends.
+ */
+export async function inSpan(tracer, name, options, fn) {
+    if (!tracer)
+        return fn(null);
+    return tracer.startActiveSpan(name, options, async (span) => {
+        try {
+            return await fn(span);
+        }
+        catch (err) {
+            span.recordException(err instanceof Error ? err : String(err));
+            span.setStatus({
+                code: SPAN_STATUS.ERROR,
+                message: err instanceof Error ? err.message : String(err),
+            });
+            throw err;
+        }
+        finally {
+            span.end();
+        }
+    });
+}
+//# sourceMappingURL=index.js.map

package/dist/tracing/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/tracing/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AA4BH;;;;;;;;GAQG;AACH,MAAM,UAAU,UAAU,CAAC,IAAI,GAAG,eAAe,EAAE,OAAgB;IACjE,MAAM,GAAG,GAAI,UAAsC,CAAC,MAAM,CAAC,GAAG,CAAC,wBAAwB,CAAC,CACR,CAAC;IACjF,OAAO,GAAG,EAAE,KAAK,EAAE,SAAS,CAAC,IAAI,EAAE,OAAO,CAAyB,CAAC;AACtE,CAAC;AAED,MAAM,CAAC,MAAM,SAAS,GAAG,EAAE,QAAQ,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAW,CAAC;AAC7D,MAAM,CAAC,MAAM,WAAW,GAAG,EAAE,EAAE,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,EAAW,CAAC;AAExD,8DAA8D;AAC9D,MAAM,UAAU,aAAa,CAAC,QAAsB;IAClD,OAAO,QAAQ,KAAK,QAAQ,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,QAAQ,CAAC;AACzD,CAAC;AAED,wFAAwF;AACxF,MAAM,UAAU,UAAU,CACxB,MAA2D;IAE3D,MAAM,GAAG,GAAqC,EAAE,CAAC;IACjD,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC;QAC/C,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,IAAI;YAAE,GAAG,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;IAC9D,OAAO,GAAG,CAAC;AACb,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,MAAM,CAC1B,MAA4B,EAC5B,IAAY,EACZ,OAAsB,EACtB,EAAuC;IAEvC,IAAI,CAAC,MAAM;QAAE,OAAO,EAAE,CAAC,IAAI,CAAC,CAAC;IAC7B,OAAO,MAAM,CAAC,eAAe,CAAC,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,IAAY,EAAE,EAAE;QAClE,IAAI,CAAC;YACH,OAAO,MAAM,EAAE,CAAC,IAAI,CAAC,CAAC;QACxB,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,IAAI,CAAC,eAAe,CAAC,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC;YAC/D,IAAI,CAAC,SAAS,CAAC;gBACb,IAAI,EAAE,WAAW,CAAC,KAAK;gBACvB,OAAO,EAAE,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC;aAC1D,CAAC,CAAC;YACH,MAAM,GAAG,CAAC;QACZ,CAAC;gBAAS,CAAC;YACT,IAAI,CAAC,GAAG,EAAE,CAAC;QACb,CAAC;IACH,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist/tracing/recording.d.ts

@@ -0,0 +1,23 @@
+/**
+ * `createRecordingTracer` — an in-memory `AiTracer` for tests and local
+ * debugging: every span with its attributes, status, exceptions and parent
+ * (spans opened while another one runs nest under it).
+ */
+import type { AiAttributeValue, AiTracer } from './index.js';
+export interface RecordedSpan {
+    name: string;
+    kind: number | undefined;
+    attributes: Record<string, AiAttributeValue>;
+    status: {
+        code: number;
+        message?: string;
+    } | null;
+    exceptions: Array<Error | string>;
+    /** Name of the span this one was opened under. */
+    parent: string | null;
+    ended: boolean;
+}
+export declare function createRecordingTracer(): AiTracer & {
+    spans: RecordedSpan[];
+};
+//# sourceMappingURL=recording.d.ts.map

package/dist/tracing/recording.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"recording.d.ts","sourceRoot":"","sources":["../../src/tracing/recording.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAyB,QAAQ,EAAE,MAAM,YAAY,CAAC;AAEpF,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,GAAG,SAAS,CAAC;IACzB,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAC;IAC7C,MAAM,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;IAClD,UAAU,EAAE,KAAK,CAAC,KAAK,GAAG,MAAM,CAAC,CAAC;IAClC,kDAAkD;IAClD,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,KAAK,EAAE,OAAO,CAAC;CAChB;AAED,wBAAgB,qBAAqB,IAAI,QAAQ,GAAG;IAAE,KAAK,EAAE,YAAY,EAAE,CAAA;CAAE,CA2C5E"}

package/dist/tracing/recording.js

@@ -0,0 +1,49 @@
+/**
+ * `createRecordingTracer` — an in-memory `AiTracer` for tests and local
+ * debugging: every span with its attributes, status, exceptions and parent
+ * (spans opened while another one runs nest under it).
+ */
+export function createRecordingTracer() {
+    const spans = [];
+    const active = [];
+    return {
+        spans,
+        startActiveSpan(name, options, fn) {
+            const span = {
+                name,
+                kind: options.kind,
+                attributes: { ...(options.attributes ?? {}) },
+                status: null,
+                exceptions: [],
+                parent: active[active.length - 1]?.name ?? null,
+                ended: false,
+            };
+            spans.push(span);
+            const api = {
+                setAttribute: (key, value) => void (span.attributes[key] = value),
+                setAttributes: (values) => void Object.assign(span.attributes, values),
+                recordException: (exception) => void span.exceptions.push(exception),
+                setStatus: (status) => void (span.status = status),
+                end: () => void (span.ended = true),
+            };
+            active.push(span);
+            const leave = () => {
+                const i = active.lastIndexOf(span);
+                if (i >= 0)
+                    active.splice(i, 1);
+            };
+            try {
+                const result = fn(api);
+                if (result instanceof Promise)
+                    return result.finally(leave);
+                leave();
+                return result;
+            }
+            catch (err) {
+                leave();
+                throw err;
+            }
+        },
+    };
+}
+//# sourceMappingURL=recording.js.map

package/dist/tracing/recording.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"recording.js","sourceRoot":"","sources":["../../src/tracing/recording.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAeH,MAAM,UAAU,qBAAqB;IACnC,MAAM,KAAK,GAAmB,EAAE,CAAC;IACjC,MAAM,MAAM,GAAmB,EAAE,CAAC;IAClC,OAAO;QACL,KAAK;QACL,eAAe,CACb,IAAY,EACZ,OAAsB,EACtB,EAAK;YAEL,MAAM,IAAI,GAAiB;gBACzB,IAAI;gBACJ,IAAI,EAAE,OAAO,CAAC,IAAI;gBAClB,UAAU,EAAE,EAAE,GAAG,CAAC,OAAO,CAAC,UAAU,IAAI,EAAE,CAAC,EAAE;gBAC7C,MAAM,EAAE,IAAI;gBACZ,UAAU,EAAE,EAAE;gBACd,MAAM,EAAE,MAAM,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC,EAAE,IAAI,IAAI,IAAI;gBAC/C,KAAK,EAAE,KAAK;aACb,CAAC;YACF,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YACjB,MAAM,GAAG,GAAW;gBAClB,YAAY,EAAE,CAAC,GAAG,EAAE,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;gBACjE,aAAa,EAAE,CAAC,MAAM,EAAE,EAAE,CAAC,KAAK,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,UAAU,EAAE,MAAM,CAAC;gBACtE,eAAe,EAAE,CAAC,SAAS,EAAE,EAAE,CAAC,KAAK,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,SAAS,CAAC;gBACpE,SAAS,EAAE,CAAC,MAAM,EAAE,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;gBAClD,GAAG,EAAE,GAAG,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC;aACpC,CAAC;YACF,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YAClB,MAAM,KAAK,GAAG,GAAG,EAAE;gBACjB,MAAM,CAAC,GAAG,MAAM,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC;gBACnC,IAAI,CAAC,IAAI,CAAC;oBAAE,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;YAClC,CAAC,CAAC;YACF,IAAI,CAAC;gBACH,MAAM,MAAM,GAAG,EAAE,CAAC,GAAG,CAAC,CAAC;gBACvB,IAAI,MAAM,YAAY,OAAO;oBAAE,OAAO,MAAM,CAAC,OAAO,CAAC,KAAK,CAAkB,CAAC;gBAC7E,KAAK,EAAE,CAAC;gBACR,OAAO,MAAuB,CAAC;YACjC,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,KAAK,EAAE,CAAC;gBACR,MAAM,GAAG,CAAC;YACZ,CAAC;QACH,CAAC;KACF,CAAC;AACJ,CAAC"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@venturekit-pro/ai",
-  "version": "0.0.47",
-  "description": "AI utilities for VentureKit - embeddings, RAG, agents, chat completion, and image generation",
+  "version": "0.0.50",
+  "description": "AI utilities for VentureKit - LLM gateway, agent loop, durable harness, embeddings, RAG, chat completion, and image generation",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -34,10 +34,13 @@
     "saas",
     "ai",
     "embeddings",
-    "rag"
+    "rag",
+    "llm-gateway",
+    "agents",
+    "harness"
   ],
   "dependencies": {
-    "@venturekit/core": "0.0.47"
+    "@venturekit/core": "0.0.50"
   },
   "peerDependencies": {
     "@aws-sdk/client-bedrock-runtime": "^3.0.0",

package/src/cost-ledger/migrations/vk_ai_cost_0004_llm_gateway.sql

@@ -0,0 +1,69 @@
+-- @venturekit-pro/ai — LLM gateway (SCHEMA ONLY).
+--
+-- 1. Two prices on the catalog the gateway needs (`src/gateway/pricing.ts`):
+--      cost_per_1k_cached_input  USD per 1K input tokens served from the
+--                                provider's prompt cache. NULL = priced at
+--                                the input rate (conservative).
+--      web_search_per_1k         USD per 1,000 native web searches
+--                                (Anthropic web search, OpenAI web_search,
+--                                Gemini grounding). NULL = $0.
+--    Mirrors `ModelDescriptor.costPer1kCachedInputUsd` / `webSearchPer1kUsd`.
+--
+-- 2. `vk_llm_calls` — the gateway's audit trail: one row per call (served,
+--    failed, denied or cancelled) with its context, every candidate tried,
+--    policy decisions, usage, cost and the full request / response content.
+--    File and image inputs are stored as size + SHA-256, never their bytes.
+--    Rows carry `expires_at` (retention at write time) and are deleted by
+--    `purgeExpiredLlmCalls()`.
+--
+-- The cost ledger (`vk_llm_cost_events`) stays the billing record; this
+-- table is the "what exactly was asked and answered" record.
+--
+-- Idempotent: every statement is IF NOT EXISTS.
+
+ALTER TABLE vk_llm_models
+  ADD COLUMN IF NOT EXISTS cost_per_1k_cached_input numeric(12, 8),
+  ADD COLUMN IF NOT EXISTS web_search_per_1k        numeric(12, 6);
+
+CREATE TABLE IF NOT EXISTS vk_llm_calls (
+  id                 uuid          PRIMARY KEY,
+  tenant_id          uuid,
+  feature            text          NOT NULL,
+  actor_type         text,
+  actor_id           text,
+  target_type        text,
+  target_id          text,
+  correlation_id     text,
+  -- succeeded | failed | denied | cancelled
+  status             text          NOT NULL,
+  model_key          text,
+  provider           text,
+  model              text,
+  -- platform | tenant
+  credential_source  text,
+  fell_back          boolean       NOT NULL DEFAULT false,
+  attempts           jsonb         NOT NULL DEFAULT '[]'::jsonb,
+  policy_decisions   jsonb         NOT NULL DEFAULT '[]'::jsonb,
+  usage              jsonb,
+  cost_usd           numeric(12, 8),
+  cost_micro_usd     bigint,
+  latency_ms         integer,
+  labels             jsonb         NOT NULL DEFAULT '{}'::jsonb,
+  request            jsonb         NOT NULL,
+  response           jsonb,
+  error              jsonb,
+  started_at         timestamptz   NOT NULL,
+  finished_at        timestamptz   NOT NULL,
+  created_at         timestamptz   NOT NULL DEFAULT now(),
+  expires_at         timestamptz   NOT NULL
+);
+
+CREATE INDEX IF NOT EXISTS llm_calls_correlation_idx
+  ON vk_llm_calls (correlation_id, started_at DESC)
+  WHERE correlation_id IS NOT NULL;
+
+CREATE INDEX IF NOT EXISTS llm_calls_tenant_started_idx
+  ON vk_llm_calls (tenant_id, started_at DESC);
+
+CREATE INDEX IF NOT EXISTS llm_calls_expires_idx
+  ON vk_llm_calls (expires_at);

package/src/cost-ledger/migrations/vk_ai_cost_0005_harness.sql

@@ -0,0 +1,99 @@
+-- @venturekit-pro/ai — harness (durable graph runs), SCHEMA ONLY.
+--
+-- Store behind `createPostgresHarnessStore` (src/harness/postgres-store.ts):
+--
+--   vk_harness_runs       one row per run: graph key@version pinned at
+--                         start, status, the run context, input, every
+--                         node's output, the node to run, its step and
+--                         attempt, delays, the worker lease, cancel flag,
+--                         error, spend. `version` is the compare-and-set
+--                         token every state change checks; `event_seq`
+--                         numbers the run's events.
+--   vk_harness_node_runs  one row per node attempt (output, error, spend).
+--   vk_harness_map_items  per-item checkpoints of map nodes.
+--   vk_harness_events     append-only event log (timeline, progress,
+--                         tool calls, gates) ordered by (run_id, seq).
+--
+-- Statuses: queued · running · waiting · completed · failed · cancelled.
+-- Idempotent: every statement is IF NOT EXISTS.
+
+CREATE TABLE IF NOT EXISTS vk_harness_runs (
+  id                uuid           PRIMARY KEY,
+  tenant_id         uuid,
+  graph_key         text           NOT NULL,
+  graph_version     integer        NOT NULL,
+  status            text           NOT NULL,
+  context           jsonb          NOT NULL DEFAULT '{}'::jsonb,
+  target_type       text,
+  target_id         text,
+  input             jsonb,
+  outputs           jsonb          NOT NULL DEFAULT '{}'::jsonb,
+  current_node      text,
+  step              integer        NOT NULL DEFAULT 1,
+  attempt           integer        NOT NULL DEFAULT 1,
+  attempt_base      integer        NOT NULL DEFAULT 0,
+  not_before        timestamptz,
+  lease_until       timestamptz,
+  cancel_requested  boolean        NOT NULL DEFAULT false,
+  error             jsonb,
+  cost_usd          numeric(14, 8) NOT NULL DEFAULT 0,
+  event_seq         integer        NOT NULL DEFAULT 0,
+  version           integer        NOT NULL DEFAULT 0,
+  created_at        timestamptz    NOT NULL DEFAULT now(),
+  updated_at        timestamptz    NOT NULL DEFAULT now(),
+  completed_at      timestamptz,
+  CONSTRAINT harness_runs_status_chk CHECK (status IN ('queued', 'running', 'waiting', 'completed', 'failed', 'cancelled'))
+);
+
+CREATE INDEX IF NOT EXISTS harness_runs_tenant_graph_idx
+  ON vk_harness_runs (tenant_id, graph_key, status, created_at DESC);
+
+CREATE INDEX IF NOT EXISTS harness_runs_target_idx
+  ON vk_harness_runs (tenant_id, target_type, target_id)
+  WHERE target_type IS NOT NULL;
+
+-- The sweep: queued runs (lost / due tasks) and running runs (expired leases).
+CREATE INDEX IF NOT EXISTS harness_runs_sweep_idx
+  ON vk_harness_runs (status, updated_at)
+  WHERE status IN ('queued', 'running');
+
+CREATE TABLE IF NOT EXISTS vk_harness_node_runs (
+  run_id       uuid           NOT NULL REFERENCES vk_harness_runs(id) ON DELETE CASCADE,
+  step         integer        NOT NULL,
+  node_id      text           NOT NULL,
+  attempt      integer        NOT NULL,
+  -- succeeded | failed | cancelled
+  status       text           NOT NULL,
+  started_at   timestamptz    NOT NULL,
+  finished_at  timestamptz    NOT NULL,
+  output       jsonb,
+  error        jsonb,
+  cost_usd     numeric(14, 8) NOT NULL DEFAULT 0,
+  PRIMARY KEY (run_id, step, attempt)
+);
+
+CREATE TABLE IF NOT EXISTS vk_harness_map_items (
+  run_id      uuid         NOT NULL REFERENCES vk_harness_runs(id) ON DELETE CASCADE,
+  step        integer      NOT NULL,
+  item_index  integer      NOT NULL,
+  output      jsonb,
+  created_at  timestamptz  NOT NULL DEFAULT now(),
+  PRIMARY KEY (run_id, step, item_index)
+);
+
+CREATE TABLE IF NOT EXISTS vk_harness_events (
+  run_id   uuid         NOT NULL REFERENCES vk_harness_runs(id) ON DELETE CASCADE,
+  seq      integer      NOT NULL,
+  at       timestamptz  NOT NULL DEFAULT now(),
+  type     text         NOT NULL,
+  node_id  text,
+  step     integer,
+  attempt  integer,
+  label    text         NOT NULL,
+  detail   text,
+  data     jsonb,
+  PRIMARY KEY (run_id, seq)
+);
+
+CREATE INDEX IF NOT EXISTS harness_events_type_idx
+  ON vk_harness_events (run_id, type, seq DESC);

package/src/cost-ledger/migrations/vk_ai_cost_0006_cache_write_prices.sql

@@ -0,0 +1,17 @@
+-- @venturekit-pro/ai — prompt-cache write prices (SCHEMA ONLY).
+--
+-- Writing a prompt prefix to the provider's cache costs more than reading
+-- plain input: Anthropic 1.25× input for 5-minute entries and 2× for
+-- 1-hour entries, OpenAI GPT-5.6+ 1.25×. The gateway prices them
+-- (`src/gateway/pricing.ts`) from:
+--      cost_per_1k_cache_write     USD per 1K tokens written to the cache.
+--                                  NULL = priced at the input rate.
+--      cost_per_1k_cache_write_1h  USD per 1K tokens written with a 1-hour
+--                                  lifetime. NULL = the write rate.
+-- Mirrors `ModelDescriptor.costPer1kCacheWriteUsd` / `costPer1kCacheWrite1hUsd`.
+--
+-- Idempotent: ADD COLUMN IF NOT EXISTS.
+
+ALTER TABLE vk_llm_models
+  ADD COLUMN IF NOT EXISTS cost_per_1k_cache_write    numeric(12, 8),
+  ADD COLUMN IF NOT EXISTS cost_per_1k_cache_write_1h numeric(12, 8);

package/src/cost-ledger/migrations/vk_ai_cost_0007_harness_fan_out.sql

@@ -0,0 +1,47 @@
+-- @venturekit-pro/ai — harness fan-out (SCHEMA ONLY).
+--
+-- A map node with `dispatch: 'tasks'` sends one queue message per item
+-- (src/harness/harness.ts). Each item becomes a small task row of its own
+-- in `vk_harness_map_items`:
+--      status       pending (not sent yet) · queued (its message is out)
+--                   · running (leased) · done · failed. Rows of inline maps
+--                   are `done` (the default keeps the existing rows valid).
+--      input        the item, as the node's `items()` returned it.
+--      attempt      attempts so far — never reset, so a worker left over
+--                   from an earlier node attempt can't commit.
+--      attempt_base `attempt` when the current node attempt fanned out
+--                   (its retry budget counts from there).
+--      lease_until  the worker's lease on a running item.
+--      not_before   when a retried item is due.
+--      error        the last failure.
+--      cost_usd     model spend of the item (added to the run at the join).
+-- and `vk_harness_map_joins` is the join counter: the item whose write
+-- brings `done` to `total` commits the node.
+--
+-- Idempotent: ADD COLUMN / CREATE ... IF NOT EXISTS.
+
+ALTER TABLE vk_harness_map_items
+  ADD COLUMN IF NOT EXISTS status      text           NOT NULL DEFAULT 'done',
+  ADD COLUMN IF NOT EXISTS input       jsonb,
+  ADD COLUMN IF NOT EXISTS attempt     integer        NOT NULL DEFAULT 0,
+  ADD COLUMN IF NOT EXISTS attempt_base integer       NOT NULL DEFAULT 0,
+  ADD COLUMN IF NOT EXISTS lease_until timestamptz,
+  ADD COLUMN IF NOT EXISTS not_before  timestamptz,
+  ADD COLUMN IF NOT EXISTS error       jsonb,
+  ADD COLUMN IF NOT EXISTS cost_usd    numeric(14, 8) NOT NULL DEFAULT 0,
+  ADD COLUMN IF NOT EXISTS updated_at  timestamptz    NOT NULL DEFAULT now();
+
+-- The sweep: items whose message was lost, or whose worker died.
+CREATE INDEX IF NOT EXISTS harness_map_items_sweep_idx
+  ON vk_harness_map_items (status, updated_at)
+  WHERE status IN ('queued', 'running');
+
+CREATE TABLE IF NOT EXISTS vk_harness_map_joins (
+  run_id      uuid         NOT NULL REFERENCES vk_harness_runs(id) ON DELETE CASCADE,
+  step        integer      NOT NULL,
+  total       integer      NOT NULL,
+  done        integer      NOT NULL DEFAULT 0,
+  created_at  timestamptz  NOT NULL DEFAULT now(),
+  updated_at  timestamptz  NOT NULL DEFAULT now(),
+  PRIMARY KEY (run_id, step)
+);