@jinn-network/client 0.1.8 → 0.1.9-canary.023faefb

package/dist/store/store.d.ts

@@ -1,5 +1,6 @@
 import Database from 'better-sqlite3';
 import type { EnvelopeProjection, EnvelopeProjectionQuery } from '../corpus/types.js';
+import type { TaskRunReadModel } from '../types/task-run-read-model.js';
 import type { TxSubmissionKey, TxSubmissionLedgerEntry } from '../tx-retry.js';
 export interface ActivityEventInput {
     ts: string | null;
@@ -211,6 +212,12 @@ export declare class Store {
      */
     private hasLegacyDesiredStateId;
     constructor(dbPath: string);
+    /**
+     * Read-only task-run view for the status/build endpoints (#1584). Returns a
+     * `TaskRunReadModel` backed by the engine persistence layer, keeping the
+     * concrete `TaskRunPersistence` construction out of `api/`.
+     */
+    taskRunReadModel(): TaskRunReadModel;
     /** Older request-first DBs keyed artifacts by desired_state_id before Task-native IDs landed. */
     private ensureArtifactsTaskColumns;
     /** Older on-disk DBs predate `peer_catalog_id` on network_artifacts. */
@@ -277,6 +284,13 @@ export declare class Store {
         before?: string;
     }): Array<{
         taskId: string;
+        /**
+         * On-chain decimal taskId (#579), decoded from the `TaskCreated` event.
+         * DISTINCT from `taskId`, which is the off-chain task-document id. The
+         * launcher's on-chain status chip keys its indexer lookup on this. Empty
+         * string when no on-chain id was recorded (pre-migration / lost event).
+         */
+        protocolTaskId: string;
         taskCid: string;
         solverType: string | null;
         requestId: string;
@@ -344,6 +358,39 @@ export declare class Store {
      * Issue #815.
      */
     aiUnitsThisWeek(credentialId: string, now?: Date): number;
+    /**
+     * 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: string, now?: Date): {
+        usdMicros: number;
+        estimated: boolean;
+    };
+    /**
+     * 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: string, now?: Date): {
+        usdMicros: number;
+        estimated: boolean;
+    };
+    /** Shared COALESCE-sum + estimate-flag query for the USD accumulators. */
+    private sumUsdMicros;
     /**
      * True iff an `ai_units_cap_reached` row exists for the given
      * (credentialId, window, blockId). Used by the daemon to hydrate the
@@ -357,12 +404,22 @@ export declare class Store {
     hasAiUnitsCapReachedFor(credentialId: string, window: 'block' | 'week', blockId: string): boolean;
     /**
      * Mark the per-request `claimed` row as `delivered` and record
-     * `actual_cost_usd_micros`. The `ai_units` projection captured at
-     * claim time is intentionally NOT recomputed — the issue spec says
-     * "estimates are the gate input, never recomputed". Idempotent: a
-     * no-op when no `claimed` row exists.
+     * `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: string, actualCostUsdMicros: number): void;
+    finalizeClaimDelivered(requestId: string, actualCostUsdMicros: number, actualCostEstimated: boolean): void;
     /** Newer events first, then ascending id for `jinn logs --follow` (oldest in batch printed first in caller). */
     getActivityEventsAfterId(afterId: number, limit: number): ActivityEventRow[];
     /**
@@ -384,6 +441,7 @@ export declare class Store {
     getLastEventAtForService(serviceIndex: number): string | null;
     getActivityCountsForService(serviceIndex: number): Record<string, number>;
     recordRewardClaim(claim: RewardClaimInput): void;
+    getClaimedRewardsLast24hWei(): string;
     getClaimedRewardsByService(): Record<number, {
         total: string;
         lastAt: string;
@@ -499,6 +557,49 @@ export declare class Store {
     queryEnvelopeProjections(query?: EnvelopeProjectionQuery): EnvelopeProjection[];
     saveErc8004Anchor(input: Erc8004AnchorInput): void;
     listErc8004AnchorsByEnvelopeCids(envelopeCids: readonly string[]): Erc8004AnchorRow[];
+    /**
+     * 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: EvalResultRecord): void;
+    /**
+     * 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: string, slate_version: string): EvalAggregate;
+    /**
+     * 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: string, slate_version: string): string[];
+    /** Per-task eval results for a (checkpoint, slate version), ordered by instance_id. */
+    getEvalResults(checkpoint_cid: string, slate_version: string): EvalResultRow[];
     close(): void;
 }
+export interface EvalResultRecord {
+    checkpoint_cid: string;
+    slate_hash: string;
+    slate_version: string;
+    instance_id: string;
+    /** Pass/fail; ignored (stored NULL) when `unscorable` is true. */
+    passed: boolean | null;
+    unscorable: boolean;
+    code_digest: string;
+    run_at_ms: number;
+    test_log_excerpt?: string | null;
+}
+/** A persisted eval result read back from the store (same shape as the record written). */
+export type EvalResultRow = EvalResultRecord;
+export interface EvalAggregate {
+    passed: number;
+    scorable: number;
+    unscorable: number;
+}
 export {};

package/dist/store/store.js

@@ -1,7 +1,7 @@
 import Database from 'better-sqlite3';
 import { mkdirSync } from 'node:fs';
 import { dirname } from 'node:path';
-import { TASK_RUNS_SCHEMA } from '../harnesses/engine/persistence.js';
+import { TASK_RUNS_SCHEMA, TaskRunPersistence } from '../harnesses/engine/persistence.js';
 import { normalizeEnvelopeRole } from '../types/envelope.js';
 function readClaimPolicyMaxClaims(taskPayload) {
     if (!taskPayload)
@@ -288,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. */
@@ -320,6 +339,14 @@ export class Store {
         this.backfillActivityEvents();
         this.recordLegacyRestorationIntentsIgnored();
     }
+    /**
+     * Read-only task-run view for the status/build endpoints (#1584). Returns a
+     * `TaskRunReadModel` backed by the engine persistence layer, keeping the
+     * concrete `TaskRunPersistence` construction out of `api/`.
+     */
+    taskRunReadModel() {
+        return new TaskRunPersistence(this.db);
+    }
     /** Older request-first DBs keyed artifacts by desired_state_id before Task-native IDs landed. */
     ensureArtifactsTaskColumns() {
         const cols = this.db.prepare(`PRAGMA table_info(artifacts)`).all();
@@ -400,6 +427,12 @@ export class Store {
         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'.
@@ -684,6 +717,7 @@ export class Store {
             });
             return {
                 taskId,
+                protocolTaskId,
                 taskCid,
                 solverType: r.solver_type,
                 requestId: r.request_id,
@@ -913,6 +947,56 @@ export class Store {
          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
@@ -935,16 +1019,31 @@ export class Store {
     }
     /**
      * Mark the per-request `claimed` row as `delivered` and record
-     * `actual_cost_usd_micros`. The `ai_units` projection captured at
-     * claim time is intentionally NOT recomputed — the issue spec says
-     * "estimates are the gate input, never recomputed". Idempotent: a
-     * no-op when no `claimed` row exists.
+     * `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) {
+    finalizeClaimDelivered(requestId, actualCostUsdMicros, actualCostEstimated) {
         this.db.prepare(`UPDATE activity_events
          SET claim_status = 'delivered',
-             actual_cost_usd_micros = @actual
-       WHERE request_id = @req AND claim_status = 'claimed'`).run({ req: requestId, actual: actualCostUsdMicros });
+             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) {
@@ -1095,6 +1194,20 @@ export class Store {
             asset: claim.asset ?? 'reward',
         });
     }
+    getClaimedRewardsLast24hWei() {
+        const cutoff = new Date(Date.now() - 24 * 60 * 60 * 1000).toISOString();
+        const rows = this.db.prepare(`SELECT amount_wei FROM reward_claims WHERE ts >= ?`).all(cutoff);
+        let total = 0n;
+        for (const row of rows) {
+            try {
+                total += BigInt(row.amount_wei);
+            }
+            catch {
+                /* ignore malformed legacy rows */
+            }
+        }
+        return total.toString();
+    }
     getClaimedRewardsByService() {
         const rows = this.db.prepare(`SELECT id, service_index, amount_wei, ts, tx_hash FROM reward_claims ORDER BY id ASC`).all();
         const out = {};
@@ -1819,6 +1932,79 @@ export class Store {
             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();
     }