@substrate-ai/core 0.19.54

package/dist/persistence/queries/amendments.d.ts

@@ -0,0 +1,91 @@
+/**
+ * Amendment query functions for the persistence layer.
+ *
+ * Provides operations specific to the amendment workflow:
+ * - Creating amendment runs (validated against parent run status)
+ * - Loading parent run decisions (active decisions only)
+ * - Superseding decisions (with 3 error conditions)
+ * - Querying active decisions with optional filtering
+ * - Traversing the amendment run chain
+ * - Finding the latest completed run
+ *
+ * All functions are async and accept a DatabaseAdapter, making them
+ * compatible with both the SqliteDatabaseAdapter and DoltDatabaseAdapter.
+ */
+import type { DatabaseAdapter } from '../types.js';
+import type { Decision, PipelineRun } from '../schemas/decisions.js';
+export interface CreateAmendmentRunInput {
+    id: string;
+    parentRunId: string;
+    methodology: string;
+    configJson?: string;
+}
+export interface ActiveDecisionsFilter {
+    pipeline_run_id?: string;
+    phase?: string;
+    category?: string;
+    key?: string;
+}
+export interface SupersessionEvent {
+    originalDecisionId: string;
+    supersedingDecisionId: string;
+    supersededAt: string;
+}
+export interface AmendmentChainEntry {
+    runId: string;
+    parentRunId: string | null;
+    status: string;
+    createdAt: string;
+    depth: number;
+}
+/**
+ * Create a new amendment run that references a completed parent run.
+ *
+ * Validates that the parent run exists and has status = 'completed'.
+ * Throws if the parent run is not found or not completed.
+ * Returns the new run's ID on success.
+ */
+export declare function createAmendmentRun(adapter: DatabaseAdapter, input: CreateAmendmentRunInput): Promise<string>;
+/**
+ * Load active (non-superseded) decisions for a given parent run.
+ *
+ * Returns decisions WHERE superseded_by IS NULL for the specified run,
+ * ordered by created_at ASC.
+ */
+export declare function loadParentRunDecisions(adapter: DatabaseAdapter, parentRunId: string): Promise<Decision[]>;
+/**
+ * Mark a decision as superseded by another decision.
+ *
+ * Error conditions:
+ * 1. originalDecisionId does not exist → throws "Decision not found: <id>"
+ * 2. supersedingDecisionId does not exist → throws "Superseding decision not found: <id>"
+ * 3. originalDecisionId.superseded_by IS NOT NULL → throws "Decision <id> is already superseded"
+ *
+ * On success, updates the original decision's superseded_by field.
+ */
+export declare function supersedeDecision(adapter: DatabaseAdapter, originalDecisionId: string, supersedingDecisionId: string): Promise<void>;
+/**
+ * Get all active (non-superseded) decisions, with optional filtering.
+ *
+ * Supports filtering by pipeline_run_id, phase, category, and/or key.
+ * If no filter is provided, returns all active decisions across all runs.
+ * Results are ordered by created_at ASC.
+ */
+export declare function getActiveDecisions(adapter: DatabaseAdapter, filter?: ActiveDecisionsFilter): Promise<Decision[]>;
+/**
+ * Traverse the parent_run_id chain starting from runId and return the chain
+ * from root (oldest ancestor) to the given run.
+ *
+ * Throws if the chain depth exceeds maxDepth (default: 10) to guard against
+ * circular references.
+ *
+ * Returns an array of AmendmentChainEntry objects ordered root → current,
+ * with depth 0 at the root.
+ */
+export declare function getAmendmentRunChain(adapter: DatabaseAdapter, runId: string, maxDepth?: number): Promise<AmendmentChainEntry[]>;
+/**
+ * Get the most recently created pipeline run with status = 'completed'.
+ * Returns undefined if no completed run exists.
+ */
+export declare function getLatestCompletedRun(adapter: DatabaseAdapter): Promise<PipelineRun | undefined>;
+//# sourceMappingURL=amendments.d.ts.map

package/dist/persistence/queries/amendments.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"amendments.d.ts","sourceRoot":"","sources":["../../../src/persistence/queries/amendments.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,aAAa,CAAA;AAClD,OAAO,KAAK,EAAE,QAAQ,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAA;AAMpE,MAAM,WAAW,uBAAuB;IACtC,EAAE,EAAE,MAAM,CAAA;IACV,WAAW,EAAE,MAAM,CAAA;IACnB,WAAW,EAAE,MAAM,CAAA;IACnB,UAAU,CAAC,EAAE,MAAM,CAAA;CACpB;AAED,MAAM,WAAW,qBAAqB;IACpC,eAAe,CAAC,EAAE,MAAM,CAAA;IACxB,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,GAAG,CAAC,EAAE,MAAM,CAAA;CACb;AAED,MAAM,WAAW,iBAAiB;IAChC,kBAAkB,EAAE,MAAM,CAAA;IAC1B,qBAAqB,EAAE,MAAM,CAAA;IAC7B,YAAY,EAAE,MAAM,CAAA;CACrB;AAED,MAAM,WAAW,mBAAmB;IAClC,KAAK,EAAE,MAAM,CAAA;IACb,WAAW,EAAE,MAAM,GAAG,IAAI,CAAA;IAC1B,MAAM,EAAE,MAAM,CAAA;IACd,SAAS,EAAE,MAAM,CAAA;IACjB,KAAK,EAAE,MAAM,CAAA;CACd;AAMD;;;;;;GAMG;AACH,wBAAsB,kBAAkB,CAAC,OAAO,EAAE,eAAe,EAAE,KAAK,EAAE,uBAAuB,GAAG,OAAO,CAAC,MAAM,CAAC,CAiClH;AAMD;;;;;GAKG;AACH,wBAAsB,sBAAsB,CAAC,OAAO,EAAE,eAAe,EAAE,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,EAAE,CAAC,CAO/G;AAMD;;;;;;;;;GASG;AACH,wBAAsB,iBAAiB,CACrC,OAAO,EAAE,eAAe,EACxB,kBAAkB,EAAE,MAAM,EAC1B,qBAAqB,EAAE,MAAM,GAC5B,OAAO,CAAC,IAAI,CAAC,CAiCf;AAMD;;;;;;GAMG;AACH,wBAAsB,kBAAkB,CAAC,OAAO,EAAE,eAAe,EAAE,MAAM,CAAC,EAAE,qBAAqB,GAAG,OAAO,CAAC,QAAQ,EAAE,CAAC,CA0BtH;AAMD;;;;;;;;;GASG;AACH,wBAAsB,oBAAoB,CACxC,OAAO,EAAE,eAAe,EACxB,KAAK,EAAE,MAAM,EACb,QAAQ,GAAE,MAAW,GACpB,OAAO,CAAC,mBAAmB,EAAE,CAAC,CA+ChC;AAMD;;;GAGG;AACH,wBAAsB,qBAAqB,CAAC,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC,WAAW,GAAG,SAAS,CAAC,CAQtG"}

package/dist/persistence/queries/amendments.js

@@ -0,0 +1,185 @@
+/**
+ * Amendment query functions for the persistence layer.
+ *
+ * Provides operations specific to the amendment workflow:
+ * - Creating amendment runs (validated against parent run status)
+ * - Loading parent run decisions (active decisions only)
+ * - Superseding decisions (with 3 error conditions)
+ * - Querying active decisions with optional filtering
+ * - Traversing the amendment run chain
+ * - Finding the latest completed run
+ *
+ * All functions are async and accept a DatabaseAdapter, making them
+ * compatible with both the SqliteDatabaseAdapter and DoltDatabaseAdapter.
+ */
+// ---------------------------------------------------------------------------
+// createAmendmentRun
+// ---------------------------------------------------------------------------
+/**
+ * Create a new amendment run that references a completed parent run.
+ *
+ * Validates that the parent run exists and has status = 'completed'.
+ * Throws if the parent run is not found or not completed.
+ * Returns the new run's ID on success.
+ */
+export async function createAmendmentRun(adapter, input) {
+    // Validate parent run exists and is completed
+    const rows = await adapter.query('SELECT id, status FROM pipeline_runs WHERE id = ?', [input.parentRunId]);
+    const parentRun = rows[0];
+    if (!parentRun) {
+        throw new Error(`Parent run not found: ${input.parentRunId}`);
+    }
+    if (parentRun.status !== 'completed') {
+        throw new Error(`Parent run is not completed (status: ${parentRun.status}). Only completed runs can be amended.`);
+    }
+    // Insert new amendment run with parent_run_id set
+    await adapter.query(`INSERT INTO pipeline_runs (id, methodology, current_phase, status, config_json, parent_run_id, created_at, updated_at)
+     VALUES (?, ?, NULL, 'running', ?, ?, ?, ?)`, [
+        input.id,
+        input.methodology,
+        input.configJson ?? null,
+        input.parentRunId,
+        new Date().toISOString(),
+        new Date().toISOString(),
+    ]);
+    return input.id;
+}
+// ---------------------------------------------------------------------------
+// loadParentRunDecisions
+// ---------------------------------------------------------------------------
+/**
+ * Load active (non-superseded) decisions for a given parent run.
+ *
+ * Returns decisions WHERE superseded_by IS NULL for the specified run,
+ * ordered by created_at ASC.
+ */
+export async function loadParentRunDecisions(adapter, parentRunId) {
+    return adapter.query(`SELECT * FROM decisions
+     WHERE pipeline_run_id = ? AND superseded_by IS NULL
+     ORDER BY created_at ASC`, [parentRunId]);
+}
+// ---------------------------------------------------------------------------
+// supersedeDecision
+// ---------------------------------------------------------------------------
+/**
+ * Mark a decision as superseded by another decision.
+ *
+ * Error conditions:
+ * 1. originalDecisionId does not exist → throws "Decision not found: <id>"
+ * 2. supersedingDecisionId does not exist → throws "Superseding decision not found: <id>"
+ * 3. originalDecisionId.superseded_by IS NOT NULL → throws "Decision <id> is already superseded"
+ *
+ * On success, updates the original decision's superseded_by field.
+ */
+export async function supersedeDecision(adapter, originalDecisionId, supersedingDecisionId) {
+    // Check original decision exists
+    const origRows = await adapter.query('SELECT id, superseded_by FROM decisions WHERE id = ?', [originalDecisionId]);
+    const original = origRows[0];
+    if (!original) {
+        throw new Error(`Decision not found: ${originalDecisionId}`);
+    }
+    // Check superseding decision exists
+    const superRows = await adapter.query('SELECT id FROM decisions WHERE id = ?', [supersedingDecisionId]);
+    const superseding = superRows[0];
+    if (!superseding) {
+        throw new Error(`Superseding decision not found: ${supersedingDecisionId}`);
+    }
+    // Check original is not already superseded
+    if (original.superseded_by !== null) {
+        throw new Error(`Decision ${originalDecisionId} is already superseded`);
+    }
+    // Perform the update
+    await adapter.query('UPDATE decisions SET superseded_by = ?, updated_at = ? WHERE id = ?', [supersedingDecisionId, new Date().toISOString(), originalDecisionId]);
+}
+// ---------------------------------------------------------------------------
+// getActiveDecisions
+// ---------------------------------------------------------------------------
+/**
+ * Get all active (non-superseded) decisions, with optional filtering.
+ *
+ * Supports filtering by pipeline_run_id, phase, category, and/or key.
+ * If no filter is provided, returns all active decisions across all runs.
+ * Results are ordered by created_at ASC.
+ */
+export async function getActiveDecisions(adapter, filter) {
+    const conditions = ['superseded_by IS NULL'];
+    const values = [];
+    if (filter?.pipeline_run_id !== undefined) {
+        conditions.push('pipeline_run_id = ?');
+        values.push(filter.pipeline_run_id);
+    }
+    if (filter?.phase !== undefined) {
+        conditions.push('phase = ?');
+        values.push(filter.phase);
+    }
+    if (filter?.category !== undefined) {
+        conditions.push('category = ?');
+        values.push(filter.category);
+    }
+    if (filter?.key !== undefined) {
+        conditions.push('`key` = ?');
+        values.push(filter.key);
+    }
+    const where = `WHERE ${conditions.join(' AND ')}`;
+    return adapter.query(`SELECT * FROM decisions ${where} ORDER BY created_at ASC`, values);
+}
+// ---------------------------------------------------------------------------
+// getAmendmentRunChain
+// ---------------------------------------------------------------------------
+/**
+ * Traverse the parent_run_id chain starting from runId and return the chain
+ * from root (oldest ancestor) to the given run.
+ *
+ * Throws if the chain depth exceeds maxDepth (default: 10) to guard against
+ * circular references.
+ *
+ * Returns an array of AmendmentChainEntry objects ordered root → current,
+ * with depth 0 at the root.
+ */
+export async function getAmendmentRunChain(adapter, runId, maxDepth = 10) {
+    const chain = [];
+    let currentId = runId;
+    let depth = 0;
+    while (currentId !== null) {
+        if (depth > maxDepth) {
+            throw new Error(`Amendment chain depth exceeded maxDepth (${maxDepth}). Possible circular reference.`);
+        }
+        const rows = await adapter.query('SELECT id, parent_run_id, status, created_at FROM pipeline_runs WHERE id = ?', [currentId]);
+        const row = rows[0];
+        if (!row)
+            break;
+        chain.unshift({
+            runId: row.id,
+            parentRunId: row.parent_run_id,
+            status: row.status,
+            createdAt: row.created_at,
+            depth,
+        });
+        currentId = row.parent_run_id;
+        depth++;
+    }
+    // Re-assign depth values so root = 0, working down to the original runId
+    // The chain is already in root-first order (unshift builds it that way).
+    // But depth was assigned as the traversal depth from the given run,
+    // so the last element has depth 0 (the start runId) and the first has
+    // the highest depth. We need to reassign so root (index 0) = depth 0.
+    for (const [i, item] of chain.entries()) {
+        item.depth = i;
+    }
+    return chain;
+}
+// ---------------------------------------------------------------------------
+// getLatestCompletedRun
+// ---------------------------------------------------------------------------
+/**
+ * Get the most recently created pipeline run with status = 'completed'.
+ * Returns undefined if no completed run exists.
+ */
+export async function getLatestCompletedRun(adapter) {
+    const rows = await adapter.query(`SELECT * FROM pipeline_runs
+     WHERE status = 'completed'
+     ORDER BY created_at DESC, id DESC
+     LIMIT 1`);
+    return rows[0];
+}
+//# sourceMappingURL=amendments.js.map

package/dist/persistence/queries/amendments.js.map

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

package/dist/persistence/queries/cost.d.ts

@@ -0,0 +1,130 @@
+/**
+ * Cost query functions for the persistence layer.
+ *
+ * Provides read and write access to the cost_entries table.
+ * All queries use indexed columns to meet NFR2 (<100ms response time).
+ *
+ * Indexes available (from migrations 001 + 002):
+ *  - idx_cost_session              : (session_id)
+ *  - idx_cost_task                 : (task_id)
+ *  - idx_cost_category             : (category)
+ *  - idx_cost_entries_session_task  : (session_id, task_id)
+ *  - idx_cost_entries_provider      : (provider)
+ *  - idx_cost_session_agent         : (session_id, agent)  — getAgentCostBreakdown
+ *  - idx_cost_agent                 : (agent)
+ *
+ * All functions are async and accept a DatabaseAdapter, making them
+ * compatible with both the SqliteDatabaseAdapter and DoltDatabaseAdapter.
+ * Prepared statement caching has been removed — adapter handles statement
+ * lifecycle internally.
+ */
+import type { DatabaseAdapter } from '../types.js';
+import type { CostEntry, SessionCostSummary, TaskCostSummary, AgentCostBreakdown } from '../cost-types.js';
+export type CreateCostEntryInput = Omit<CostEntry, 'id' | 'created_at'>;
+/**
+ * Insert a new cost entry record.
+ *
+ * Maps from the CostEntry interface to the cost_entries table schema.
+ * Returns the DB-assigned autoincrement id.
+ *
+ * Uses SELECT MAX(id) instead of last_insert_rowid() / LAST_INSERT_ID()
+ * for portability across both SQLite and MySQL/Dolt backends.
+ */
+export declare function recordCostEntry(adapter: DatabaseAdapter, entry: CreateCostEntryInput): Promise<number>;
+/**
+ * Retrieve a single cost entry by its DB-assigned id.
+ *
+ * Returns null if no row is found for the given id.
+ */
+export declare function getCostEntryById(adapter: DatabaseAdapter, id: number): Promise<CostEntry | null>;
+/**
+ * Atomically increment a task's cumulative cost_usd field.
+ *
+ * Uses a single UPDATE with arithmetic to avoid race conditions.
+ */
+export declare function incrementTaskCost(adapter: DatabaseAdapter, taskId: string, costDelta: number): Promise<void>;
+/**
+ * Return aggregated cost totals for a session (AC2).
+ *
+ * Returns a SessionCostSummary with subscription/API breakdown and savings.
+ * Uses idx_cost_entries_session_task index.
+ */
+export declare function getSessionCostSummary(adapter: DatabaseAdapter, sessionId: string): Promise<SessionCostSummary>;
+/**
+ * Return aggregated cost totals for a session, optionally excluding planning entries.
+ *
+ * When includePlanning=false (the default for `substrate cost`), entries with
+ * category='planning' are excluded from the summary.
+ *
+ * This is the variant used by the Cost Report CLI command (story 4.4) to support
+ * the --include-planning flag.
+ *
+ * Uses idx_cost_entries_session_task index.
+ */
+export declare function getSessionCostSummaryFiltered(adapter: DatabaseAdapter, sessionId: string, includePlanning: boolean): Promise<SessionCostSummary>;
+/**
+ * Return aggregated cost data for a single task (AC1).
+ *
+ * Uses idx_cost_task index.
+ */
+export declare function getTaskCostSummary(adapter: DatabaseAdapter, taskId: string): Promise<TaskCostSummary>;
+/**
+ * Return cost breakdown for a specific agent within a session.
+ *
+ * Uses idx_cost_session index (session_id filter) + agent filter.
+ */
+export declare function getAgentCostBreakdown(adapter: DatabaseAdapter, sessionId: string, agent: string): Promise<AgentCostBreakdown>;
+/**
+ * Return all cost entries for a session, ordered by timestamp descending.
+ *
+ * Supports optional pagination via limit.
+ * Uses idx_cost_entries_session_task index.
+ */
+export declare function getAllCostEntries(adapter: DatabaseAdapter, sessionId: string, limit?: number): Promise<CostEntry[]>;
+/**
+ * Return all cost entries for a session, optionally excluding planning entries.
+ *
+ * When `includePlanning` is false, entries with `category = 'planning'` are
+ * excluded from the result set. This supports the `--include-planning` flag
+ * in the Cost Report CLI command (story 4.4).
+ *
+ * Uses idx_cost_entries_session_task index.
+ */
+export declare function getAllCostEntriesFiltered(adapter: DatabaseAdapter, sessionId: string, includePlanning: boolean): Promise<CostEntry[]>;
+/**
+ * Return the total cost of planning entries for a session.
+ *
+ * Used by the Cost Report CLI command to show excluded planning costs
+ * without requiring a second full summary query.
+ *
+ * Uses idx_cost_category index.
+ */
+export declare function getPlanningCostTotal(adapter: DatabaseAdapter, sessionId: string): Promise<number>;
+/** @deprecated Use recordCostEntry instead */
+export type LegacyCostEntryInput = {
+    session_id: string;
+    task_id?: string | null;
+    agent: string;
+    billing_mode: string;
+    category?: string;
+    input_tokens?: number;
+    output_tokens?: number;
+    estimated_cost?: number;
+    actual_cost?: number | null;
+    model?: string | null;
+};
+/** @deprecated Use getSessionCostSummary instead */
+export declare function getSessionCost(adapter: DatabaseAdapter, sessionId: string): Promise<{
+    total_cost: number;
+    total_input_tokens: number;
+    total_output_tokens: number;
+    entry_count: number;
+}>;
+/** @deprecated Use getTaskCostSummary instead */
+export declare function getTaskCost(adapter: DatabaseAdapter, taskId: string): Promise<{
+    total_cost: number;
+    total_input_tokens: number;
+    total_output_tokens: number;
+    entry_count: number;
+}>;
+//# sourceMappingURL=cost.d.ts.map

package/dist/persistence/queries/cost.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cost.d.ts","sourceRoot":"","sources":["../../../src/persistence/queries/cost.ts"],"names":[],"mappings":"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"}