@gr8ful/spf 0.14.0 → 0.16.0

package/dist/ui/server/db.d.ts

@@ -1,21 +1,75 @@
+import type { NormalizedObservabilityDb } from "../../core/data_types.ts";
+import type { DataPaths } from "../../core/paths.ts";
 import type { AgentSession, Envelope, EventsPage, GateResult, Phase, Session, SessionDetail, SessionSummary, SessionUsage } from "../shared/types.ts";
 export declare class SfDb {
-    readonly path: string;
+    /** Absolute local sqlite path — `null` for a `kind:"d1"` config. */
+    readonly path: string | null;
+    /** Human label for API/console display: the sqlite path, or `d1:<database_id>`. */
+    readonly label: string;
     /**
      * Where the ADW session dirs live: `{data_dir}/sessions/{adw_id}/{agent}/`.
-     * The db sits in the same data_dir (config's `observability.db` defaults to
-     * `adws/adw_data/spf.db`), so deriving it as a sibling of the db file keeps
-     * working when the whole data_dir is relocated.
+     * Passed in explicitly (from `paths.resolveDataPaths(...).sessions_dir`)
+     * rather than derived from the db path — session JSONL/envelope artifact
+     * files always live on the local filesystem regardless of where the
+     * queryable trace mirror (`db` below) lives; see `paths.ts`'s `DataPaths`.
      */
     readonly sessionsDir: string;
+    /** `"n/a (d1)"` for a remote backend — journal mode is a local-file concept. */
     readonly journalMode: string;
     private readonly db;
-    /** Opened on first archive and kept; null until then. */
+    private readonly dbConfig;
+    /** D1-only; carried from `open()`'s `options.fetchImpl` so a lazily-opened writer (`setArchived`) uses the same injected fetch a test gave the reader. */
+    private readonly fetchImpl;
+    /** Opened on first archive and kept; `null` until then. */
     private writer;
     /** Cache for optionalColumn(), keyed "table.column". Only ever false → true. */
     private readonly columnCache;
-    /** `path` is always absolute — resolved upstream by the ui command via paths.resolveAnchor/resolveDataPaths. */
-    constructor(path: string);
+    private constructor();
+    /**
+     * Open a trace db for reading. `dbConfig` accepts either a bare local
+     * sqlite path (sugar for `{kind:"sqlite",path}` — `--db <path>`/`SF_DB`
+     * CLI overrides, and every test's shorthand) or a normalized
+     * `observability.db` descriptor (`paths.resolveDataPaths(...).db`).
+     *
+     * `sessionsDir` should be `paths.resolveDataPaths(...).sessions_dir`
+     * whenever the caller has a `DataPaths` in hand; omitted, it falls back to
+     * the historical "sibling of the sqlite file" derivation — only valid for
+     * the LOCAL backend (a bare-path caller has no other sessions dir to
+     * offer), so it is required when `dbConfig` names a `kind:"d1"` config.
+     *
+     * `options.fetchImpl` is D1-only and exists purely so tests can drive this
+     * end-to-end against a mocked D1 HTTP response shape — every real caller
+     * omits it and gets the global `fetch`, same as `createTraceDb` itself.
+     */
+    static open(dbConfig: NormalizedObservabilityDb | string, sessionsDir?: string, options?: {
+        fetchImpl?: typeof fetch;
+    }): Promise<SfDb>;
+    /**
+     * Cheap "is there anything to read yet" check — the async equivalent of
+     * the `existsSync(dataPaths.db_path)` fast path every sqlite-only caller
+     * used before D1 existed, extended to cover the d1 case those callers
+     * never accounted for.
+     *
+     * `open()` deliberately THROWS a friendly, actionable error on a
+     * never-written db (see above) — the right behavior for `spf ui`, where
+     * "nothing here yet" is a misconfiguration to surface loudly. Callers that
+     * instead want to treat a never-written db as "empty, skip this check" —
+     * `spf fanout`'s collision preflight and lazy metrics reader, `spf loop`'s
+     * per-iteration readback, `spf estimate`'s cold-start path, `spf watch`'s
+     * salt-collision short-circuit — use this instead, so they behave
+     * identically whether the backend is local sqlite or a fresh D1 database
+     * that has never been written to.
+     *
+     * For a `kind:"sqlite"` db: `existsSync(dataPaths.db_path)`, unchanged.
+     * For a `kind:"d1"` db: the same `sqlite_master` probe `open()`'s
+     * friendly-error path already runs, but returning `false` instead of
+     * throwing when the `sessions` table isn't there yet. Any OTHER failure
+     * (network, auth, a malformed database_id) still throws — only "nothing
+     * written yet" collapses to `false`.
+     */
+    static exists(dataPaths: Pick<DataPaths, "db" | "db_path">, options?: {
+        fetchImpl?: typeof fetch;
+    }): Promise<boolean>;
     /**
      * A SELECT fragment for a column the tracer adds by migration.
      *
@@ -32,7 +86,21 @@ export declare class SfDb {
      */
     private hasColumn;
     private optionalColumn;
-    close(): void;
+    /**
+     * D1 caps bound parameters at 100 per statement; local sqlite allows tens
+     * of thousands. Any query that binds a whole id list into an `IN (...)`
+     * clause must go through this instead of a single unbounded bind, or it
+     * throws past ~100 ids on the D1 backend. Chunking is harmless on the
+     * local backend too (just slightly less efficient), so this is used
+     * unconditionally rather than special-cased per backend.
+     *
+     * Each id belongs to exactly one chunk, so per-id ordering from `fn`'s own
+     * ORDER BY is preserved — only the relative order of rows belonging to
+     * *different* chunks can interleave, which none of this class's callers
+     * depend on (they always regroup by id afterward).
+     */
+    private chunked;
+    close(): Promise<void>;
     /**
      * Archive or restore a session — the only write in this process.
      *
@@ -40,12 +108,12 @@ export declare class SfDb {
      * click should wait its turn rather than fail. Returns false when the id
      * does not exist, so the route can 404 instead of silently succeeding.
      */
-    setArchived(adwId: string, archived: boolean): boolean;
+    setArchived(adwId: string, archived: boolean): Promise<boolean>;
     /** Sessions, most recent first, each with its phase statuses for the progress dots. */
-    sessions(limit?: number): SessionSummary[];
-    session(adwId: string): Session | null;
-    phases(adwId: string): Phase[];
-    agentSessions(adwId: string): AgentSession[];
+    sessions(limit?: number): Promise<SessionSummary[]>;
+    session(adwId: string): Promise<Session | null>;
+    phases(adwId: string): Promise<Phase[]>;
+    agentSessions(adwId: string): Promise<AgentSession[]>;
     /**
      * Agents per session, for a set of ids at once: the agent_sessions rows plus
      * anything that has started but not finished.
@@ -57,7 +125,7 @@ export declare class SfDb {
      */
     private agentsFor;
     /** Session + phases + agents in one shot — L2 needs all three to draw lanes. */
-    sessionDetail(adwId: string): SessionDetail | null;
+    sessionDetail(adwId: string): Promise<SessionDetail | null>;
     /**
      * Raw tokens read and written, beside the billed headline.
      *
@@ -70,15 +138,15 @@ export declare class SfDb {
      * material generated. The gap between them and the headline is cached
      * re-reads, which is usually most of it.
      */
-    usage(adwId: string): SessionUsage;
+    usage(adwId: string): Promise<SessionUsage>;
     /**
      * The polling query. Rowid cursor, insertion order, bounded page — the same
      * mechanism serves the live tail and lazy-paged history.
      */
-    events(adwId: string, after?: number, limit?: number): EventsPage;
-    envelopes(adwId: string): Envelope[];
-    gates(adwId: string): GateResult[];
-    sessionCount(): number;
+    events(adwId: string, after?: number, limit?: number): Promise<EventsPage>;
+    envelopes(adwId: string): Promise<Envelope[]>;
+    gates(adwId: string): Promise<GateResult[]>;
+    sessionCount(): Promise<number>;
     /**
      * `spf estimate`'s one read: every session that ran EXACTLY `chainName`
      * (never a joined one — see below), each with its per-phase token totals,
@@ -100,10 +168,10 @@ export declare class SfDb {
      * first (`spf estimate`'s own sample-selection order), which is a decision
      * `estimate.ts` makes, not this method.
      */
-    chainPhaseHistory(chainName: string): {
+    chainPhaseHistory(chainName: string): Promise<{
         sessions: ChainHistorySession[];
         joinedExcluded: number;
-    };
+    }>;
 }
 /** One EXACT-match session's history, as `chainPhaseHistory` returns it — `spf estimate`'s raw material. */
 export interface ChainHistorySession {