@devflow-tools/database 0.16.18 → 0.16.20

package/dist/host-actions.js

@@ -0,0 +1,152 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isHostActionState = isHostActionState;
+exports.mapHostActionRow = mapHostActionRow;
+exports.serializeHostActionReport = serializeHostActionReport;
+exports.hostActionReportsEqual = hostActionReportsEqual;
+const HOST_ACTION_STATES = new Set([
+    'waiting',
+    'running',
+    'reported',
+    'verified',
+    'failed',
+    'cancelled',
+    'degraded',
+]);
+function isHostActionState(value) {
+    return typeof value === 'string' && HOST_ACTION_STATES.has(value);
+}
+function mapHostActionRow(row) {
+    if (!isHostActionState(row.state)) {
+        throw new Error(`Invalid persisted host action state: ${String(row.state)}`);
+    }
+    return {
+        actionId: asRequiredString(row.action_id, 'action_id'),
+        runId: asRequiredString(row.run_id, 'run_id'),
+        engineRunId: asRequiredString(row.engine_run_id, 'engine_run_id'),
+        stepId: asRequiredString(row.step_id, 'step_id'),
+        projectRoot: asRequiredString(row.project_root, 'project_root'),
+        sessionId: asOptionalString(row.session_id),
+        executionId: asOptionalString(row.execution_id),
+        contextReceipt: asOptionalString(row.context_receipt),
+        state: row.state,
+        report: parseReport(row.report_json),
+        evidenceHash: asOptionalString(row.evidence_hash),
+        createdAt: asFiniteNumber(row.created_at, 'created_at'),
+        updatedAt: asFiniteNumber(row.updated_at, 'updated_at'),
+        finishedAt: asOptionalFiniteNumber(row.finished_at),
+    };
+}
+function serializeHostActionReport(report) {
+    if (!isPlainObject(report))
+        throw new Error('Host action report must be a plain object');
+    return JSON.stringify(canonicalizeJson(report, '$', new WeakSet()));
+}
+function hostActionReportsEqual(left, right) {
+    return serializeHostActionReport(left) === serializeHostActionReport(right);
+}
+function parseReport(value) {
+    if (typeof value !== 'string') {
+        throw new Error('Invalid persisted host action report_json: expected JSON text');
+    }
+    try {
+        const parsed = JSON.parse(value);
+        if (!isPlainObject(parsed)) {
+            throw new Error('expected a JSON object');
+        }
+        serializeHostActionReport(parsed);
+        return parsed;
+    }
+    catch (error) {
+        const detail = error instanceof Error ? error.message : String(error);
+        throw new Error(`Invalid persisted host action report_json: ${detail}`);
+    }
+}
+function canonicalizeJson(value, path, ancestors) {
+    if (value === null || typeof value === 'string' || typeof value === 'boolean')
+        return value;
+    if (typeof value === 'number') {
+        if (!Number.isFinite(value) || Object.is(value, -0)) {
+            throw nonJsonValueError(path);
+        }
+        return value;
+    }
+    if (typeof value !== 'object')
+        throw nonJsonValueError(path);
+    if (ancestors.has(value))
+        throw new Error(`Host action report contains a cycle at ${path}`);
+    ancestors.add(value);
+    try {
+        if (Array.isArray(value))
+            return canonicalizeArray(value, path, ancestors);
+        if (!isPlainObject(value))
+            throw nonJsonValueError(path);
+        const result = Object.create(null);
+        const keys = Reflect.ownKeys(value);
+        for (const key of keys) {
+            if (typeof key !== 'string')
+                throw nonJsonValueError(`${path}[symbol]`);
+            const descriptor = Object.getOwnPropertyDescriptor(value, key);
+            if (!descriptor?.enumerable || !('value' in descriptor)) {
+                throw nonJsonValueError(`${path}.${key}`);
+            }
+        }
+        for (const key of keys.slice().sort(comparePropertyKeys)) {
+            const descriptor = Object.getOwnPropertyDescriptor(value, key);
+            result[key] = canonicalizeJson(descriptor.value, `${path}.${key}`, ancestors);
+        }
+        return result;
+    }
+    finally {
+        ancestors.delete(value);
+    }
+}
+function canonicalizeArray(value, path, ancestors) {
+    if (Object.getPrototypeOf(value) !== Array.prototype)
+        throw nonJsonValueError(path);
+    const keys = Reflect.ownKeys(value);
+    const expectedKeys = new Set(['length', ...Array.from({ length: value.length }, (_, index) => String(index))]);
+    if (keys.some(key => typeof key !== 'string' || !expectedKeys.has(key))) {
+        throw nonJsonValueError(path);
+    }
+    return Array.from({ length: value.length }, (_, index) => {
+        const descriptor = Object.getOwnPropertyDescriptor(value, String(index));
+        if (!descriptor?.enumerable || !('value' in descriptor)) {
+            throw nonJsonValueError(`${path}[${index}]`);
+        }
+        return canonicalizeJson(descriptor.value, `${path}[${index}]`, ancestors);
+    });
+}
+function comparePropertyKeys(left, right) {
+    return left < right ? -1 : left > right ? 1 : 0;
+}
+function nonJsonValueError(path) {
+    return new Error(`Host action report contains a non-JSON value at ${path}`);
+}
+function isPlainObject(value) {
+    if (value === null || typeof value !== 'object' || Array.isArray(value))
+        return false;
+    const prototype = Object.getPrototypeOf(value);
+    return prototype === Object.prototype || prototype === null;
+}
+function asRequiredString(value, column) {
+    if (typeof value !== 'string' || value.length === 0) {
+        throw new Error(`Invalid persisted host action ${column}`);
+    }
+    return value;
+}
+function asOptionalString(value) {
+    return typeof value === 'string' ? value : undefined;
+}
+function asFiniteNumber(value, column) {
+    const number = Number(value);
+    if (!Number.isFinite(number))
+        throw new Error(`Invalid persisted host action ${column}`);
+    return number;
+}
+function asOptionalFiniteNumber(value) {
+    if (value === null || value === undefined)
+        return undefined;
+    const number = Number(value);
+    return Number.isFinite(number) ? number : undefined;
+}

package/dist/index.d.ts

@@ -1,5 +1,9 @@
 export { DevFlowDatabase, getGlobalDevFlowDbPath, openGlobalDevFlowDatabase, } from './database';
 export type { BenchmarkReportMetaRecord, BenchmarkReportRecord, FeedbackRecord, GovernanceAuditRecord, GovernanceRuleRecord, HookFallbackRecord, HookReceiptRecord, ContextReceiptRecord, ContextSelectionEventRecord, MemoryDistillCheckpointRecord, MemoryTurnRecord, MemoryTurnStatus, TelemetryFailureRecord, } from './database';
 export type { EnqueueWorkInput, LeaseWorkInput, RequestSessionClosureInput, SessionClosureRecord, SessionClosureState, WorkError, WorkItemRecord, WorkKind, WorkQueueHealth, WorkState, } from './work-queue';
+export { hostActionReportsEqual, isHostActionState, mapHostActionRow, serializeHostActionReport, } from './host-actions';
+export { RETRIEVAL_MAX_CYCLES, isRetrievalSessionState } from './retrieval-sessions';
+export type { AppendRetrievalCycleInput, CreateRetrievalSessionInput, RetrievalCycleRecord, RetrievalGapKind, RetrievalGapRecord, RetrievalSessionRecord, RetrievalSessionState, } from './retrieval-sessions';
+export type { FailHostActionInput, HostActionRecord, HostActionState, ReportHostActionInput, RequestHostActionInput, StartHostActionInput, VerifyHostActionInput, } from './host-actions';
 export { mapSessionObligationRow, normalizeTurnId, } from './obligation-ledger';
 export type { SessionObligationKind, SessionObligationRecord, SessionObligationState, } from './obligation-ledger';

package/dist/index.js

@@ -1,10 +1,18 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.normalizeTurnId = exports.mapSessionObligationRow = exports.openGlobalDevFlowDatabase = exports.getGlobalDevFlowDbPath = exports.DevFlowDatabase = void 0;
+exports.normalizeTurnId = exports.mapSessionObligationRow = exports.isRetrievalSessionState = exports.RETRIEVAL_MAX_CYCLES = exports.serializeHostActionReport = exports.mapHostActionRow = exports.isHostActionState = exports.hostActionReportsEqual = exports.openGlobalDevFlowDatabase = exports.getGlobalDevFlowDbPath = exports.DevFlowDatabase = void 0;
 var database_1 = require("./database");
 Object.defineProperty(exports, "DevFlowDatabase", { enumerable: true, get: function () { return database_1.DevFlowDatabase; } });
 Object.defineProperty(exports, "getGlobalDevFlowDbPath", { enumerable: true, get: function () { return database_1.getGlobalDevFlowDbPath; } });
 Object.defineProperty(exports, "openGlobalDevFlowDatabase", { enumerable: true, get: function () { return database_1.openGlobalDevFlowDatabase; } });
+var host_actions_1 = require("./host-actions");
+Object.defineProperty(exports, "hostActionReportsEqual", { enumerable: true, get: function () { return host_actions_1.hostActionReportsEqual; } });
+Object.defineProperty(exports, "isHostActionState", { enumerable: true, get: function () { return host_actions_1.isHostActionState; } });
+Object.defineProperty(exports, "mapHostActionRow", { enumerable: true, get: function () { return host_actions_1.mapHostActionRow; } });
+Object.defineProperty(exports, "serializeHostActionReport", { enumerable: true, get: function () { return host_actions_1.serializeHostActionReport; } });
+var retrieval_sessions_1 = require("./retrieval-sessions");
+Object.defineProperty(exports, "RETRIEVAL_MAX_CYCLES", { enumerable: true, get: function () { return retrieval_sessions_1.RETRIEVAL_MAX_CYCLES; } });
+Object.defineProperty(exports, "isRetrievalSessionState", { enumerable: true, get: function () { return retrieval_sessions_1.isRetrievalSessionState; } });
 var obligation_ledger_1 = require("./obligation-ledger");
 Object.defineProperty(exports, "mapSessionObligationRow", { enumerable: true, get: function () { return obligation_ledger_1.mapSessionObligationRow; } });
 Object.defineProperty(exports, "normalizeTurnId", { enumerable: true, get: function () { return obligation_ledger_1.normalizeTurnId; } });

package/dist/retrieval-sessions.d.ts

@@ -0,0 +1,74 @@
+export declare const RETRIEVAL_MAX_CYCLES: 3;
+export type RetrievalSessionState = 'open' | 'satisfied' | 'exhausted' | 'expired';
+export type RetrievalGapKind = 'target' | 'caller' | 'route' | 'resource' | 'test' | 'configuration' | 'symbol_ambiguity' | 'memory_applicability' | 'knowledge_version' | 'runtime_evidence' | 'unavailable_channel';
+export interface RetrievalGapRecord {
+    kind: RetrievalGapKind;
+    target?: string;
+    reason: string;
+    evidence: string[];
+    resolver: 'codegraph' | 'memory' | 'knowledge' | 'analyzer' | 'none';
+    priority: number;
+}
+export interface RetrievalCycleRecord {
+    retrievalSessionId: string;
+    cycle: number;
+    gaps: RetrievalGapRecord[];
+    selectedIds: string[];
+    rejectedIds: string[];
+    tokenCost: number;
+    remainingTokenBudget: number;
+    quality: Record<string, unknown>;
+    receipt: string;
+    evidenceHash: string;
+    createdAt: number;
+}
+export interface RetrievalSessionRecord {
+    id: string;
+    requestId: string;
+    projectRoot: string;
+    sessionId: string;
+    executionId?: string;
+    query: string;
+    intent: string;
+    state: RetrievalSessionState;
+    cycle: number;
+    maxCycles: typeof RETRIEVAL_MAX_CYCLES;
+    initialTokenBudget: number;
+    remainingTokenBudget: number;
+    baselineReceipt: string;
+    finalReceipt?: string;
+    createdAt: number;
+    updatedAt: number;
+    expiresAt: number;
+}
+export interface CreateRetrievalSessionInput {
+    id?: string;
+    requestId: string;
+    projectRoot: string;
+    sessionId: string;
+    executionId?: string;
+    query: string;
+    intent: string;
+    tokenBudget: number;
+    baselineReceipt: string;
+    expiresAt: number;
+}
+export interface AppendRetrievalCycleInput {
+    retrievalSessionId: string;
+    projectRoot: string;
+    sessionId: string;
+    baselineReceipt: string;
+    cycle: number;
+    gaps: RetrievalGapRecord[];
+    selectedIds: string[];
+    rejectedIds: string[];
+    tokenCost: number;
+    remainingTokenBudget: number;
+    quality: Record<string, unknown>;
+    receipt: string;
+    evidenceHash: string;
+}
+export declare function mapRetrievalSessionRow(row: Record<string, unknown>): RetrievalSessionRecord;
+export declare function mapRetrievalCycleRow(row: Record<string, unknown>): RetrievalCycleRecord;
+export declare function serializeRetrievalJson(value: unknown): string;
+export declare function isRetrievalSessionState(value: unknown): value is RetrievalSessionState;

package/dist/retrieval-sessions.js

@@ -0,0 +1,117 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RETRIEVAL_MAX_CYCLES = void 0;
+exports.mapRetrievalSessionRow = mapRetrievalSessionRow;
+exports.mapRetrievalCycleRow = mapRetrievalCycleRow;
+exports.serializeRetrievalJson = serializeRetrievalJson;
+exports.isRetrievalSessionState = isRetrievalSessionState;
+exports.RETRIEVAL_MAX_CYCLES = 3;
+function mapRetrievalSessionRow(row) {
+    const state = requiredString(row.state, 'state');
+    if (!isRetrievalSessionState(state)) {
+        throw new Error(`Invalid persisted retrieval session state: ${state}`);
+    }
+    const maxCycles = finiteInteger(row.max_cycles, 'max_cycles');
+    if (maxCycles !== exports.RETRIEVAL_MAX_CYCLES) {
+        throw new Error(`Invalid persisted retrieval max_cycles: ${maxCycles}`);
+    }
+    return {
+        id: requiredString(row.id, 'id'),
+        requestId: requiredString(row.request_id, 'request_id'),
+        projectRoot: requiredString(row.project_root, 'project_root'),
+        sessionId: requiredString(row.session_id, 'session_id'),
+        executionId: optionalString(row.execution_id),
+        query: requiredString(row.query, 'query'),
+        intent: requiredString(row.intent, 'intent'),
+        state,
+        cycle: finiteInteger(row.cycle, 'cycle'),
+        maxCycles: exports.RETRIEVAL_MAX_CYCLES,
+        initialTokenBudget: finiteInteger(row.initial_token_budget, 'initial_token_budget'),
+        remainingTokenBudget: finiteInteger(row.remaining_token_budget, 'remaining_token_budget'),
+        baselineReceipt: requiredString(row.baseline_receipt, 'baseline_receipt'),
+        finalReceipt: optionalString(row.final_receipt),
+        createdAt: finiteInteger(row.created_at, 'created_at'),
+        updatedAt: finiteInteger(row.updated_at, 'updated_at'),
+        expiresAt: finiteInteger(row.expires_at, 'expires_at'),
+    };
+}
+function mapRetrievalCycleRow(row) {
+    return {
+        retrievalSessionId: requiredString(row.retrieval_session_id, 'retrieval_session_id'),
+        cycle: finiteInteger(row.cycle, 'cycle'),
+        gaps: parseJsonArray(row.gaps_json, 'gaps_json'),
+        selectedIds: parseStringArray(row.selected_ids, 'selected_ids'),
+        rejectedIds: parseStringArray(row.rejected_ids, 'rejected_ids'),
+        tokenCost: finiteInteger(row.token_cost, 'token_cost'),
+        remainingTokenBudget: finiteInteger(row.remaining_token_budget, 'remaining_token_budget'),
+        quality: parseJsonObject(row.quality_json, 'quality_json'),
+        receipt: requiredString(row.receipt, 'receipt'),
+        evidenceHash: requiredString(row.evidence_hash, 'evidence_hash'),
+        createdAt: finiteInteger(row.created_at, 'created_at'),
+    };
+}
+function serializeRetrievalJson(value) {
+    return JSON.stringify(canonicalize(value));
+}
+function isRetrievalSessionState(value) {
+    return value === 'open' || value === 'satisfied' || value === 'exhausted' || value === 'expired';
+}
+function canonicalize(value) {
+    if (value === null || typeof value === 'string' || typeof value === 'boolean')
+        return value;
+    if (typeof value === 'number') {
+        if (!Number.isFinite(value) || Object.is(value, -0))
+            throw new Error('Retrieval evidence must be lossless JSON');
+        return value;
+    }
+    if (Array.isArray(value))
+        return value.map(canonicalize);
+    if (!value || typeof value !== 'object' || Object.getPrototypeOf(value) !== Object.prototype) {
+        throw new Error('Retrieval evidence must be plain JSON');
+    }
+    const record = value;
+    return Object.fromEntries(Object.keys(record).sort().map(key => [key, canonicalize(record[key])]));
+}
+function parseJson(value, field) {
+    if (typeof value !== 'string')
+        throw new Error(`Invalid persisted ${field}: expected JSON text`);
+    try {
+        return JSON.parse(value);
+    }
+    catch {
+        throw new Error(`Invalid persisted ${field}: malformed JSON`);
+    }
+}
+function parseJsonArray(value, field) {
+    const parsed = parseJson(value, field);
+    if (!Array.isArray(parsed))
+        throw new Error(`Invalid persisted ${field}: expected array`);
+    return parsed;
+}
+function parseStringArray(value, field) {
+    const parsed = parseJsonArray(value, field);
+    if (parsed.some(item => typeof item !== 'string'))
+        throw new Error(`Invalid persisted ${field}: expected strings`);
+    return parsed;
+}
+function parseJsonObject(value, field) {
+    const parsed = parseJson(value, field);
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        throw new Error(`Invalid persisted ${field}: expected object`);
+    }
+    return parsed;
+}
+function requiredString(value, field) {
+    if (typeof value !== 'string' || value.length === 0)
+        throw new Error(`Invalid persisted ${field}`);
+    return value;
+}
+function optionalString(value) {
+    return typeof value === 'string' && value.length > 0 ? value : undefined;
+}
+function finiteInteger(value, field) {
+    const result = Number(value);
+    if (!Number.isSafeInteger(result) || result < 0)
+        throw new Error(`Invalid persisted ${field}`);
+    return result;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@devflow-tools/database",
-  "version": "0.16.18",
+  "version": "0.16.20",
   "description": "DevFlow SQLite database package",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",