@jinn-network/client 0.1.7 → 0.1.8-canary.09a3b2f6

package/dist/store/store.js

@@ -228,6 +228,23 @@ CREATE TABLE IF NOT EXISTS envelope_projection_metadata (
 CREATE INDEX IF NOT EXISTS idx_envelope_projection_metadata_key_value
   ON envelope_projection_metadata (key, value_text);
 
+CREATE TABLE IF NOT EXISTS erc8004_anchors (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  envelope_id TEXT NOT NULL,
+  envelope_cid TEXT NOT NULL,
+  content_kind TEXT NOT NULL,
+  metadata_key TEXT NOT NULL,
+  agent_id TEXT NOT NULL,
+  chain_id INTEGER NOT NULL,
+  identity_registry_address TEXT NOT NULL,
+  tx_hash TEXT NOT NULL,
+  block_number INTEGER,
+  payload_hex TEXT NOT NULL,
+  anchored_at INTEGER NOT NULL
+);
+CREATE INDEX IF NOT EXISTS idx_erc8004_anchors_envelope_cid ON erc8004_anchors(envelope_cid);
+CREATE INDEX IF NOT EXISTS idx_erc8004_anchors_envelope_id ON erc8004_anchors(envelope_id);
+
 CREATE TABLE IF NOT EXISTS task_post_locks (
   creator_safe_address TEXT NOT NULL,
   source_key TEXT NOT NULL,
@@ -271,6 +288,25 @@ CREATE TABLE IF NOT EXISTS capture_spans (
 );
 CREATE INDEX IF NOT EXISTS capture_spans_session ON capture_spans (session_id);
 
+-- Held-out checkpoint eval results (issue #818). One row per
+-- (checkpoint, slate version, instance). Scores are only comparable WITHIN a
+-- slate version; slate_hash is stored so a version-bump / hash-drift is
+-- detectable. passed is nullable: an unscorable row (Docker down, disk
+-- floor) carries passed = NULL and is EXCLUDED from the denominator -- never
+-- coerced to a fail.
+CREATE TABLE IF NOT EXISTS eval_results (
+  checkpoint_cid TEXT NOT NULL,
+  slate_hash TEXT NOT NULL,
+  slate_version TEXT NOT NULL,
+  instance_id TEXT NOT NULL,
+  passed INTEGER,
+  unscorable INTEGER NOT NULL DEFAULT 0,
+  code_digest TEXT NOT NULL,
+  run_at_ms INTEGER NOT NULL,
+  test_log_excerpt TEXT,
+  PRIMARY KEY (checkpoint_cid, slate_version, instance_id)
+);
+
 `;
 export class Store {
     /** Exposed for engine persistence layer — treat as package-internal. */
@@ -299,6 +335,7 @@ export class Store {
         this.ensureNetworkArtifactsPeerCatalogId();
         this.ensureTaskPostsTaskCoordinatorColumns();
         this.ensureEnvelopeProjectionColumns();
+        this.ensureActivityEventCostColumns();
         this.backfillActivityEvents();
         this.recordLegacyRestorationIntentsIgnored();
     }
@@ -363,6 +400,36 @@ export class Store {
         this.db.exec(`CREATE INDEX IF NOT EXISTS idx_envelope_projections_solution_ref ON envelope_projections (solution_envelope_ref)`);
         this.db.exec(`CREATE INDEX IF NOT EXISTS idx_envelope_projections_generated ON envelope_projections (generated_at DESC)`);
     }
+    /** Older local DBs predate the per-credential spend-ledger columns on activity_events. */
+    ensureActivityEventCostColumns() {
+        const activityCols = new Set(this.db.prepare(`PRAGMA table_info(activity_events)`).all()
+            .map(c => c.name));
+        const addActivityColumn = (name, ddl) => {
+            if (!activityCols.has(name))
+                this.db.exec(`ALTER TABLE activity_events ADD COLUMN ${ddl}`);
+        };
+        addActivityColumn('credential_id', 'credential_id TEXT');
+        addActivityColumn('cost_usd_micros', 'cost_usd_micros INTEGER');
+        addActivityColumn('model', 'model TEXT');
+        // Issue #815 — AI-units ceiling. ai_units is the gate-input projection
+        // captured at claim time; claim_status tracks the per-request lifecycle
+        // (claimed / claim_failed / delivered); the cost pair splits the
+        // estimated-at-claim-time vs actual-at-completion telemetry.
+        addActivityColumn('ai_units', 'ai_units REAL');
+        addActivityColumn('claim_status', 'claim_status TEXT');
+        addActivityColumn('estimated_cost_usd_micros', 'estimated_cost_usd_micros INTEGER');
+        addActivityColumn('actual_cost_usd_micros', 'actual_cost_usd_micros INTEGER');
+        // Issue #1004 (AC4): whether actual_cost_usd_micros is estimate-backed
+        // (1) or harvested telemetry (0/null). A telemetry-less harness such as
+        // Hermes still writes a NON-null actual cost via finalizeClaimDelivered,
+        // so the column distinguishes a heuristic figure from a metered one. The
+        // gate's estimated flag reads this so a heuristic is not shown as metered.
+        addActivityColumn('actual_cost_estimated', 'actual_cost_estimated INTEGER');
+        this.db.exec(`CREATE INDEX IF NOT EXISTS idx_activity_events_credential ON activity_events (credential_id, ts)`);
+        // Per-request lookup for the completion-time update path that fills
+        // actualCostUsdMicros / sets claim_status='delivered'.
+        this.db.exec(`CREATE INDEX IF NOT EXISTS idx_activity_events_req_claim ON activity_events (request_id, claim_status)`);
+    }
     /**
      * Task-native startup ignores the retired request-first `restoration_intents`
      * table. Keep a one-time local marker when old in-flight rows are present so
@@ -417,6 +484,16 @@ export class Store {
         const ts = new Date().toISOString();
         this.recordActivityEvent({ ts, kind: role, requestId });
     }
+    /**
+     * Membership-only variant of `recordOwnActivity`: writes the
+     * `own_activity` row but does NOT emit a generic `activity_events`
+     * row. Used by paths that emit their own enriched activity event
+     * (e.g. issue #815's claim path attaches credentialId / aiUnits /
+     * estimatedCostUsdMicros / claimStatus to the row).
+     */
+    markOwnActivity(requestId, role) {
+        this.db.prepare(`INSERT OR REPLACE INTO own_activity (request_id, role) VALUES (?, ?)`).run(requestId, role);
+    }
     isOwnActivity(requestId) {
         const row = this.db.prepare('SELECT 1 FROM own_activity WHERE request_id = ?').get(requestId);
         return row !== undefined;
@@ -746,8 +823,14 @@ export class Store {
         return legacyRows.map(r => ({ requestId: r.request_id, role: r.role }));
     }
     recordActivityEvent(event) {
-        this.db.prepare(`INSERT INTO activity_events (ts, kind, request_id, service_index, tx_hash, solver_type, outcome, detail)
-       VALUES (@ts, @kind, @requestId, @serviceIndex, @txHash, @solverType, @outcome, @detail)`).run({
+        this.db.prepare(`INSERT INTO activity_events
+         (ts, kind, request_id, service_index, tx_hash, solver_type, outcome, detail,
+          credential_id, cost_usd_micros, model,
+          ai_units, claim_status, estimated_cost_usd_micros, actual_cost_usd_micros)
+       VALUES
+         (@ts, @kind, @requestId, @serviceIndex, @txHash, @solverType, @outcome, @detail,
+          @credentialId, @costUsdMicros, @model,
+          @aiUnits, @claimStatus, @estimatedCostUsdMicros, @actualCostUsdMicros)`).run({
             ts: event.ts ?? null,
             kind: event.kind,
             requestId: event.requestId ?? null,
@@ -756,6 +839,13 @@ export class Store {
             solverType: event.solverType ?? null,
             outcome: event.outcome ?? null,
             detail: event.detail ?? null,
+            credentialId: event.credentialId ?? null,
+            costUsdMicros: event.costUsdMicros ?? null,
+            model: event.model ?? null,
+            aiUnits: event.aiUnits ?? null,
+            claimStatus: event.claimStatus ?? null,
+            estimatedCostUsdMicros: event.estimatedCostUsdMicros ?? null,
+            actualCostUsdMicros: event.actualCostUsdMicros ?? null,
         });
     }
     getRecentActivityEvents(limit, opts = {}) {
@@ -771,7 +861,9 @@ export class Store {
             params['cursor'] = opts.cursor;
         }
         const where = clauses.length > 0 ? `WHERE ${clauses.join(' AND ')}` : '';
-        const rows = this.db.prepare(`SELECT id, ts, kind, request_id, service_index, tx_hash, solver_type, outcome, detail
+        const rows = this.db.prepare(`SELECT id, ts, kind, request_id, service_index, tx_hash, solver_type, outcome, detail,
+              credential_id, cost_usd_micros, model,
+              ai_units, claim_status, estimated_cost_usd_micros, actual_cost_usd_micros
        FROM activity_events
        ${where}
        ORDER BY id DESC
@@ -786,13 +878,171 @@ export class Store {
             solverType: r.solver_type,
             outcome: r.outcome,
             detail: r.detail,
+            credentialId: r.credential_id,
+            costUsdMicros: r.cost_usd_micros,
+            model: r.model,
+            aiUnits: r.ai_units,
+            claimStatus: r.claim_status,
+            estimatedCostUsdMicros: r.estimated_cost_usd_micros,
+            actualCostUsdMicros: r.actual_cost_usd_micros,
         }));
     }
+    /**
+     * Total cost in micro-dollars recorded against a credential since the most
+     * recent UTC midnight. Backs the daily spend cap.
+     */
+    spentTodayMicros(credentialId, now = new Date()) {
+        const midnight = new Date(Date.UTC(now.getUTCFullYear(), now.getUTCMonth(), now.getUTCDate())).toISOString();
+        const row = this.db.prepare(`SELECT COALESCE(SUM(cost_usd_micros), 0) AS total
+       FROM activity_events
+       WHERE credential_id = @cid AND ts IS NOT NULL AND ts >= @midnight`).get({ cid: credentialId, midnight });
+        return row.total;
+    }
+    /**
+     * Sum of `ai_units` for a credential within the current 6h UTC-aligned
+     * block (00:00 / 06:00 / 12:00 / 18:00 boundaries). Reads only rows whose
+     * `claim_status = 'claimed'` or `'delivered'` so failed-claim rows
+     * (`ai_units = 0`, `claim_status = 'claim_failed'`) don't muddy the sum
+     * even though their contribution is already zero.
+     *
+     * Issue #815. Backs the per-block AI-units ceiling gate.
+     */
+    aiUnitsThisBlock(credentialId, now = new Date()) {
+        const startOfDay = Date.UTC(now.getUTCFullYear(), now.getUTCMonth(), now.getUTCDate());
+        const sinceDayStart = now.getTime() - startOfDay;
+        const sixHoursMs = 6 * 60 * 60 * 1_000;
+        // Cap at 3 — there are 4 blocks per day (indices 0..3). Edge cases
+        // where sinceDayStart ≈ 24h (millisecond rounding) would otherwise
+        // overshoot into a non-existent 5th block in the *next* day.
+        const blocksIn = Math.min(Math.floor(sinceDayStart / sixHoursMs), 3);
+        const blockStart = new Date(startOfDay + blocksIn * sixHoursMs).toISOString();
+        const blockEnd = new Date(startOfDay + (blocksIn + 1) * sixHoursMs).toISOString();
+        const row = this.db.prepare(`SELECT COALESCE(SUM(ai_units), 0) AS total
+       FROM activity_events
+       WHERE credential_id = @cid
+         AND ts IS NOT NULL AND ts >= @blockStart AND ts < @blockEnd
+         AND claim_status IN ('claimed', 'delivered')`).get({ cid: credentialId, blockStart, blockEnd });
+        return row.total ?? 0;
+    }
+    /**
+     * Sum of `ai_units` for a credential within the trailing 7-day rolling
+     * window from `now`. Backs the per-week AI-units safety-net ceiling.
+     * Issue #815.
+     */
+    aiUnitsThisWeek(credentialId, now = new Date()) {
+        const weekStart = new Date(now.getTime() - 7 * 24 * 60 * 60 * 1_000).toISOString();
+        const row = this.db.prepare(`SELECT COALESCE(SUM(ai_units), 0) AS total
+       FROM activity_events
+       WHERE credential_id = @cid
+         AND ts IS NOT NULL AND ts >= @weekStart
+         AND claim_status IN ('claimed', 'delivered')`).get({ cid: credentialId, weekStart });
+        return row.total ?? 0;
+    }
+    /**
+     * Actual-spend accumulator for the current 6h UTC block (issue #1004).
+     *
+     * Sums `COALESCE(actual_cost_usd_micros, estimated_cost_usd_micros, 0)`
+     * over rows whose `claim_status` is `'claimed'` or `'delivered'`:
+     *   - delivered rows contribute the real harvested cost (`actual_*`),
+     *   - in-flight claimed rows contribute their estimate so a burst of
+     *     concurrent claims cannot slip the cap before any of them deliver,
+     *   - failed claims (status `'claim_failed'`) are excluded.
+     *
+     * `estimated` is true iff the summed figure includes any estimate-backed
+     * cost: an in-flight `claimed` row with no `actual_cost_usd_micros` yet,
+     * OR a `delivered` row whose actual cost is itself a heuristic
+     * (`actual_cost_estimated = 1` — a telemetry-less harness such as Hermes).
+     * It is false only when every contributing row is harvested actual
+     * telemetry. The gate surfaces this so an estimate-backed figure is not
+     * presented as metered. Block boundaries mirror `aiUnitsThisBlock`.
+     */
+    usdMicrosThisBlock(credentialId, now = new Date()) {
+        const startOfDay = Date.UTC(now.getUTCFullYear(), now.getUTCMonth(), now.getUTCDate());
+        const sinceDayStart = now.getTime() - startOfDay;
+        const sixHoursMs = 6 * 60 * 60 * 1_000;
+        const blocksIn = Math.min(Math.floor(sinceDayStart / sixHoursMs), 3);
+        const blockStart = new Date(startOfDay + blocksIn * sixHoursMs).toISOString();
+        const blockEnd = new Date(startOfDay + (blocksIn + 1) * sixHoursMs).toISOString();
+        return this.sumUsdMicros(credentialId, blockStart, blockEnd);
+    }
+    /**
+     * Actual-spend accumulator for the trailing 7-day rolling window from
+     * `now` (issue #1004). Same COALESCE + claim_status filter + `estimated`
+     * semantics as {@link usdMicrosThisBlock}.
+     */
+    usdMicrosThisWeek(credentialId, now = new Date()) {
+        const weekStart = new Date(now.getTime() - 7 * 24 * 60 * 60 * 1_000).toISOString();
+        return this.sumUsdMicros(credentialId, weekStart, undefined);
+    }
+    /** Shared COALESCE-sum + estimate-flag query for the USD accumulators. */
+    sumUsdMicros(credentialId, fromIso, toIso) {
+        const upper = toIso ? 'AND ts < @to' : '';
+        const row = this.db
+            .prepare(`SELECT
+           COALESCE(SUM(COALESCE(actual_cost_usd_micros, estimated_cost_usd_micros, 0)), 0) AS total,
+           COALESCE(SUM(CASE WHEN actual_cost_usd_micros IS NULL OR actual_cost_estimated = 1 THEN 1 ELSE 0 END), 0) AS estimatedRows
+         FROM activity_events
+         WHERE credential_id = @cid
+           AND ts IS NOT NULL AND ts >= @from ${upper}
+           AND claim_status IN ('claimed', 'delivered')`)
+            .get({ cid: credentialId, from: fromIso, to: toIso });
+        return { usdMicros: row.total ?? 0, estimated: (row.estimatedRows ?? 0) > 0 };
+    }
+    /**
+     * True iff an `ai_units_cap_reached` row exists for the given
+     * (credentialId, window, blockId). Used by the daemon to hydrate the
+     * AI-units gate's in-memory pause memo across restarts so the
+     * "exactly one event per (credential, window, block-id)" guarantee
+     * holds across process boundaries (issue #815, finding 1).
+     *
+     * Lookup is by `credential_id` + `kind` + the `[block=...][window=...]`
+     * markers that `daemon.ts` embeds in the row's `detail` string.
+     */
+    hasAiUnitsCapReachedFor(credentialId, window, blockId) {
+        const marker = `[block=${blockId}][window=${window}]`;
+        const row = this.db.prepare(`SELECT 1 AS hit
+       FROM activity_events
+       WHERE kind = 'ai_units_cap_reached'
+         AND credential_id = @cid
+         AND detail LIKE @marker
+       LIMIT 1`).get({ cid: credentialId, marker: `${marker}%` });
+        return row !== undefined;
+    }
+    /**
+     * Mark the per-request `claimed` row as `delivered` and record
+     * `actual_cost_usd_micros` (issue #1004 — the gate's accumulator now
+     * reads this column via COALESCE, so a delivered row's real harvested
+     * cost replaces its claim-time estimate in the running total). The
+     * `ai_units` projection captured at claim time is intentionally NOT
+     * recomputed — it remains the per-task estimate for the legacy unit
+     * surfaces. For subscription credentials the resulting USD figure is a
+     * *proxy* budget, not an exact bound on the provider's plan quota.
+     *
+     * `actualCostEstimated` (issue #1004, AC4) records whether the actual
+     * cost is itself a heuristic — true for a telemetry-less harness such as
+     * Hermes whose `harvestHarnessUsage` falls back to an a-priori estimate,
+     * false when the figure is harvested telemetry. The gate reads it so a
+     * delivered-but-heuristic row reports `estimated: true` rather than being
+     * presented as metered. Idempotent: a no-op when no `claimed` row exists.
+     */
+    finalizeClaimDelivered(requestId, actualCostUsdMicros, actualCostEstimated) {
+        this.db.prepare(`UPDATE activity_events
+         SET claim_status = 'delivered',
+             actual_cost_usd_micros = @actual,
+             actual_cost_estimated = @estimated
+       WHERE request_id = @req AND claim_status = 'claimed'`).run({
+            req: requestId,
+            actual: actualCostUsdMicros,
+            estimated: actualCostEstimated ? 1 : 0,
+        });
+    }
     /** Newer events first, then ascending id for `jinn logs --follow` (oldest in batch printed first in caller). */
     getActivityEventsAfterId(afterId, limit) {
         const effectiveLimit = Math.max(0, Math.min(limit, 1000));
         const rows = this.db
-            .prepare(`SELECT id, ts, kind, request_id, service_index, tx_hash, solver_type, outcome, detail
+            .prepare(`SELECT id, ts, kind, request_id, service_index, tx_hash, solver_type, outcome, detail,
+                credential_id, cost_usd_micros, model,
+                ai_units, claim_status, estimated_cost_usd_micros, actual_cost_usd_micros
          FROM activity_events
          WHERE id > @afterId
          ORDER BY id ASC
@@ -808,8 +1058,99 @@ export class Store {
             solverType: r.solver_type,
             outcome: r.outcome,
             detail: r.detail,
+            credentialId: r.credential_id,
+            costUsdMicros: r.cost_usd_micros,
+            model: r.model,
+            aiUnits: r.ai_units,
+            claimStatus: r.claim_status,
+            estimatedCostUsdMicros: r.estimated_cost_usd_micros,
+            actualCostUsdMicros: r.actual_cost_usd_micros,
         }));
     }
+    /**
+     * Filtered, id-cursored page of activity events for the dedicated Events
+     * page. Newest-first.
+     *
+     * Cursors on `id` rather than `ts` so startup/shutdown rows with null
+     * timestamps remain reachable.
+     */
+    getActivityEventsPage(opts = {}) {
+        const effectiveLimit = Math.max(1, Math.min(opts.limit ?? 50, 200));
+        const clauses = [];
+        const params = { limit: effectiveLimit };
+        if (opts.kinds && opts.kinds.length > 0) {
+            const placeholders = opts.kinds.map((_, i) => `@kind${i}`);
+            clauses.push(`kind IN (${placeholders.join(', ')})`);
+            opts.kinds.forEach((k, i) => {
+                params[`kind${i}`] = k;
+            });
+        }
+        if (opts.outcome) {
+            clauses.push('outcome = @outcome');
+            params['outcome'] = opts.outcome;
+        }
+        if (opts.requestId) {
+            clauses.push('request_id = @requestId');
+            params['requestId'] = opts.requestId;
+        }
+        if (opts.beforeId !== undefined) {
+            clauses.push('id < @beforeId');
+            params['beforeId'] = opts.beforeId;
+        }
+        const where = clauses.length > 0 ? `WHERE ${clauses.join(' AND ')}` : '';
+        const rows = this.db.prepare(`SELECT id, ts, kind, request_id, service_index, tx_hash, solver_type, outcome, detail,
+              credential_id, cost_usd_micros, model,
+              ai_units, claim_status, estimated_cost_usd_micros, actual_cost_usd_micros
+       FROM activity_events
+       ${where}
+       ORDER BY id DESC
+       LIMIT @limit`).all(params);
+        return rows.map((r) => ({
+            id: r.id,
+            ts: r.ts,
+            kind: r.kind,
+            requestId: r.request_id,
+            serviceIndex: r.service_index,
+            txHash: r.tx_hash,
+            solverType: r.solver_type,
+            outcome: r.outcome,
+            detail: r.detail,
+            credentialId: r.credential_id,
+            costUsdMicros: r.cost_usd_micros,
+            model: r.model,
+            aiUnits: r.ai_units,
+            claimStatus: r.claim_status,
+            estimatedCostUsdMicros: r.estimated_cost_usd_micros,
+            actualCostUsdMicros: r.actual_cost_usd_micros,
+        }));
+    }
+    getActivityEventById(id) {
+        const r = this.db.prepare(`SELECT id, ts, kind, request_id, service_index, tx_hash, solver_type, outcome, detail,
+              credential_id, cost_usd_micros, model,
+              ai_units, claim_status, estimated_cost_usd_micros, actual_cost_usd_micros
+       FROM activity_events
+       WHERE id = ?`).get(id);
+        if (!r)
+            return null;
+        return {
+            id: r.id,
+            ts: r.ts,
+            kind: r.kind,
+            requestId: r.request_id,
+            serviceIndex: r.service_index,
+            txHash: r.tx_hash,
+            solverType: r.solver_type,
+            outcome: r.outcome,
+            detail: r.detail,
+            credentialId: r.credential_id,
+            costUsdMicros: r.cost_usd_micros,
+            model: r.model,
+            aiUnits: r.ai_units,
+            claimStatus: r.claim_status,
+            estimatedCostUsdMicros: r.estimated_cost_usd_micros,
+            actualCostUsdMicros: r.actual_cost_usd_micros,
+        };
+    }
     getActivityCountsByKind() {
         const rows = this.db.prepare(`SELECT kind, COUNT(*) as c FROM activity_events GROUP BY kind`).all();
         const out = {};
@@ -1519,6 +1860,128 @@ export class Store {
        LIMIT @limit`).all(params);
         return rows.map(rowToEnvelopeProjection);
     }
+    saveErc8004Anchor(input) {
+        this.db.prepare(`INSERT INTO erc8004_anchors
+         (envelope_id, envelope_cid, content_kind, metadata_key, agent_id,
+          chain_id, identity_registry_address, tx_hash, block_number,
+          payload_hex, anchored_at)
+       VALUES
+         (@envelopeId, @envelopeCid, @contentKind, @metadataKey, @agentId,
+          @chainId, @identityRegistryAddress, @txHash, @blockNumber,
+          @payloadHex, @anchoredAt)`).run({
+            envelopeId: input.envelopeId,
+            envelopeCid: input.envelopeCid,
+            contentKind: input.contentKind,
+            metadataKey: input.metadataKey,
+            agentId: input.agentId,
+            chainId: input.chainId,
+            identityRegistryAddress: input.identityRegistryAddress,
+            txHash: input.txHash,
+            blockNumber: input.blockNumber,
+            payloadHex: input.payloadHex,
+            anchoredAt: input.anchoredAt,
+        });
+    }
+    listErc8004AnchorsByEnvelopeCids(envelopeCids) {
+        if (envelopeCids.length === 0)
+            return [];
+        const placeholders = envelopeCids.map((_, i) => `@cid${i}`).join(', ');
+        const params = {};
+        envelopeCids.forEach((cid, i) => { params[`cid${i}`] = cid; });
+        const rows = this.db.prepare(`SELECT id, envelope_id, envelope_cid, content_kind, metadata_key, agent_id,
+              chain_id, identity_registry_address, tx_hash, block_number,
+              payload_hex, anchored_at
+         FROM erc8004_anchors
+         WHERE envelope_cid IN (${placeholders})
+         ORDER BY anchored_at ASC, id ASC`).all(params);
+        return rows.map((r) => ({
+            id: r.id,
+            envelopeId: r.envelope_id,
+            envelopeCid: r.envelope_cid,
+            contentKind: r.content_kind,
+            metadataKey: r.metadata_key,
+            agentId: r.agent_id,
+            chainId: r.chain_id,
+            identityRegistryAddress: r.identity_registry_address,
+            txHash: r.tx_hash,
+            blockNumber: r.block_number,
+            payloadHex: r.payload_hex,
+            anchoredAt: r.anchored_at,
+        }));
+    }
+    /**
+     * Upsert one held-out eval result (issue #818). PK is
+     * `(checkpoint_cid, slate_version, instance_id)` so a re-run overwrites.
+     * `passed` is null for `unscorable` rows.
+     */
+    recordEvalResult(args) {
+        this.db
+            .prepare(`INSERT INTO eval_results
+           (checkpoint_cid, slate_hash, slate_version, instance_id, passed, unscorable, code_digest, run_at_ms, test_log_excerpt)
+         VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
+         ON CONFLICT(checkpoint_cid, slate_version, instance_id) DO UPDATE SET
+           slate_hash = excluded.slate_hash,
+           passed = excluded.passed,
+           unscorable = excluded.unscorable,
+           code_digest = excluded.code_digest,
+           run_at_ms = excluded.run_at_ms,
+           test_log_excerpt = excluded.test_log_excerpt`)
+            .run(args.checkpoint_cid, args.slate_hash, args.slate_version, args.instance_id, args.unscorable ? null : args.passed ? 1 : 0, args.unscorable ? 1 : 0, args.code_digest, args.run_at_ms, args.test_log_excerpt ?? null);
+    }
+    /**
+     * Aggregate the eval results for a (checkpoint, slate version):
+     * `scorable` = rows with `unscorable = 0`; `passed` = scorable rows with
+     * `passed = 1`. Unscorable rows are counted separately and never enter the
+     * denominator. A checkpoint with no rows yields all-zero (the orchestrator
+     * reads this to detect a not-yet-evaluated parent).
+     */
+    getEvalAggregate(checkpoint_cid, slate_version) {
+        const row = this.db
+            .prepare(`SELECT
+           COALESCE(SUM(CASE WHEN unscorable = 0 AND passed = 1 THEN 1 ELSE 0 END), 0) AS passed,
+           COALESCE(SUM(CASE WHEN unscorable = 0 THEN 1 ELSE 0 END), 0) AS scorable,
+           COALESCE(SUM(CASE WHEN unscorable = 1 THEN 1 ELSE 0 END), 0) AS unscorable
+         FROM eval_results
+         WHERE checkpoint_cid = ? AND slate_version = ?`)
+            .get(checkpoint_cid, slate_version);
+        return { passed: row.passed, scorable: row.scorable, unscorable: row.unscorable };
+    }
+    /**
+     * Distinct `slate_hash` values recorded for a (checkpoint, slate version).
+     * The eval orchestrator reads this to detect slate-content drift under a
+     * stable version label — the held-out exam is only an honest before/after
+     * when the parent and child were scored on the SAME slate content (defeating
+     * confounder #1, task-selection). Empty when the checkpoint has no rows.
+     */
+    getEvalSlateHashes(checkpoint_cid, slate_version) {
+        const rows = this.db
+            .prepare(`SELECT DISTINCT slate_hash
+         FROM eval_results
+         WHERE checkpoint_cid = ? AND slate_version = ?
+         ORDER BY slate_hash`)
+            .all(checkpoint_cid, slate_version);
+        return rows.map((r) => r.slate_hash);
+    }
+    /** Per-task eval results for a (checkpoint, slate version), ordered by instance_id. */
+    getEvalResults(checkpoint_cid, slate_version) {
+        const rows = this.db
+            .prepare(`SELECT checkpoint_cid, slate_hash, slate_version, instance_id, passed, unscorable, code_digest, run_at_ms, test_log_excerpt
+         FROM eval_results
+         WHERE checkpoint_cid = ? AND slate_version = ?
+         ORDER BY instance_id`)
+            .all(checkpoint_cid, slate_version);
+        return rows.map((r) => ({
+            checkpoint_cid: r.checkpoint_cid,
+            slate_hash: r.slate_hash,
+            slate_version: r.slate_version,
+            instance_id: r.instance_id,
+            passed: r.passed === null ? null : r.passed === 1,
+            unscorable: r.unscorable === 1,
+            code_digest: r.code_digest,
+            run_at_ms: r.run_at_ms,
+            test_log_excerpt: r.test_log_excerpt,
+        }));
+    }
     close() {
         this.db.close();
     }