@devflow-tools/database 0.17.2 → 0.17.4

package/dist/semantic-resolution.d.ts

@@ -0,0 +1,30 @@
+export type PersistedSemanticResolutionState = 'provisional' | 'resolved' | 'abstained' | 'unavailable';
+export type PersistedSemanticGeneratedBy = 'deterministic' | 'embedding_router' | 'host_semantic' | 'hybrid';
+export interface SemanticResolutionRecord {
+    frameHash: string;
+    projectRoot: string;
+    projectId: string;
+    hostId: string;
+    sessionId: string;
+    turnId: string;
+    requestId: string;
+    sourceHash: string;
+    artifactHash: string;
+    artifactRevision: number;
+    supersedesFrameHash?: string;
+    state: PersistedSemanticResolutionState;
+    generatedBy: PersistedSemanticGeneratedBy;
+    modelId?: string;
+    modelRevision?: string;
+    routeCatalogVersion: string;
+    thresholdVersion: string;
+    route: Record<string, unknown>;
+    sampling: Record<string, unknown>;
+    conflicts: Array<Record<string, unknown>>;
+    frame: Record<string, unknown>;
+    durationMs: number;
+    createdAt: number;
+}
+export declare function assertSemanticResolutionRecord(record: SemanticResolutionRecord): void;
+export declare function stableSemanticResolutionJson(value: unknown): string;
+export declare function mapSemanticResolutionRow(row: Record<string, unknown>): SemanticResolutionRecord;

package/dist/semantic-resolution.js

@@ -0,0 +1,156 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.assertSemanticResolutionRecord = assertSemanticResolutionRecord;
+exports.stableSemanticResolutionJson = stableSemanticResolutionJson;
+exports.mapSemanticResolutionRow = mapSemanticResolutionRow;
+const STATES = new Set([
+    'provisional', 'resolved', 'abstained', 'unavailable',
+]);
+const GENERATORS = new Set([
+    'deterministic', 'embedding_router', 'host_semantic', 'hybrid',
+]);
+function assertSemanticResolutionRecord(record) {
+    for (const [field, value] of Object.entries({
+        frameHash: record.frameHash,
+        projectRoot: record.projectRoot,
+        projectId: record.projectId,
+        hostId: record.hostId,
+        sessionId: record.sessionId,
+        turnId: record.turnId,
+        requestId: record.requestId,
+        sourceHash: record.sourceHash,
+        artifactHash: record.artifactHash,
+        routeCatalogVersion: record.routeCatalogVersion,
+        thresholdVersion: record.thresholdVersion,
+    })) {
+        if (typeof value !== 'string' || value.length === 0) {
+            throw new Error(`SEMANTIC_RESOLUTION_INVALID:${field}`);
+        }
+    }
+    if (!Number.isSafeInteger(record.artifactRevision) || record.artifactRevision < 1) {
+        throw new Error('SEMANTIC_RESOLUTION_INVALID:artifactRevision');
+    }
+    if (!Number.isSafeInteger(record.durationMs) || record.durationMs < 0
+        || !Number.isSafeInteger(record.createdAt) || record.createdAt < 0) {
+        throw new Error('SEMANTIC_RESOLUTION_INVALID:timing');
+    }
+    if (!STATES.has(record.state) || !GENERATORS.has(record.generatedBy)) {
+        throw new Error('SEMANTIC_RESOLUTION_INVALID:enum');
+    }
+    if (record.frame.frameHash !== record.frameHash) {
+        throw new Error('SEMANTIC_RESOLUTION_FRAME_HASH_MISMATCH');
+    }
+    stableSemanticResolutionJson(record.route);
+    stableSemanticResolutionJson(record.sampling);
+    stableSemanticResolutionJson(record.conflicts);
+    stableSemanticResolutionJson(record.frame);
+}
+function stableSemanticResolutionJson(value) {
+    return JSON.stringify(canonicalize(value));
+}
+function mapSemanticResolutionRow(row) {
+    const state = requiredString(row.state, 'state');
+    const generatedBy = requiredString(row.generated_by, 'generated_by');
+    if (!STATES.has(state) || !GENERATORS.has(generatedBy)) {
+        throw new Error('SEMANTIC_RESOLUTION_ROW_INVALID:enum');
+    }
+    const result = {
+        frameHash: requiredString(row.frame_hash, 'frame_hash'),
+        projectRoot: requiredString(row.project_root, 'project_root'),
+        projectId: requiredString(row.project_id, 'project_id'),
+        hostId: requiredString(row.host_id, 'host_id'),
+        sessionId: requiredString(row.session_id, 'session_id'),
+        turnId: requiredString(row.turn_id, 'turn_id'),
+        requestId: requiredString(row.request_id, 'request_id'),
+        sourceHash: requiredString(row.source_hash, 'source_hash'),
+        artifactHash: requiredString(row.artifact_hash, 'artifact_hash'),
+        artifactRevision: requiredPositiveInteger(row.artifact_revision, 'artifact_revision'),
+        ...(optionalString(row.supersedes_frame_hash)
+            ? { supersedesFrameHash: optionalString(row.supersedes_frame_hash) }
+            : {}),
+        state,
+        generatedBy,
+        ...(optionalString(row.model_id) ? { modelId: optionalString(row.model_id) } : {}),
+        ...(optionalString(row.model_revision) ? { modelRevision: optionalString(row.model_revision) } : {}),
+        routeCatalogVersion: requiredString(row.route_catalog_version, 'route_catalog_version'),
+        thresholdVersion: requiredString(row.threshold_version, 'threshold_version'),
+        route: parseObject(row.route_json, 'route_json'),
+        sampling: parseObject(row.sampling_json, 'sampling_json'),
+        conflicts: parseObjectArray(row.conflicts_json, 'conflicts_json'),
+        frame: parseObject(row.frame_json, 'frame_json'),
+        durationMs: requiredNonNegativeInteger(row.duration_ms, 'duration_ms'),
+        createdAt: requiredNonNegativeInteger(row.created_at, 'created_at'),
+    };
+    assertSemanticResolutionRecord(result);
+    return result;
+}
+function canonicalize(value) {
+    if (value === undefined)
+        return undefined;
+    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('SEMANTIC_RESOLUTION_JSON_INVALID');
+        return value;
+    }
+    if (Array.isArray(value))
+        return value.map(item => {
+            if (item === undefined)
+                throw new Error('SEMANTIC_RESOLUTION_JSON_INVALID');
+            return canonicalize(item);
+        });
+    if (!value || typeof value !== 'object' || Object.getPrototypeOf(value) !== Object.prototype) {
+        throw new Error('SEMANTIC_RESOLUTION_JSON_INVALID');
+    }
+    const record = value;
+    return Object.fromEntries(Object.keys(record).sort()
+        .filter(key => record[key] !== undefined)
+        .map(key => [key, canonicalize(record[key])]));
+}
+function parseObject(value, field) {
+    const parsed = parseJson(value, field);
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        throw new Error(`SEMANTIC_RESOLUTION_ROW_INVALID:${field}`);
+    }
+    return parsed;
+}
+function parseObjectArray(value, field) {
+    const parsed = parseJson(value, field);
+    if (!Array.isArray(parsed) || parsed.some(item => !item || typeof item !== 'object' || Array.isArray(item))) {
+        throw new Error(`SEMANTIC_RESOLUTION_ROW_INVALID:${field}`);
+    }
+    return parsed;
+}
+function parseJson(value, field) {
+    if (typeof value !== 'string')
+        throw new Error(`SEMANTIC_RESOLUTION_ROW_INVALID:${field}`);
+    try {
+        return JSON.parse(value);
+    }
+    catch {
+        throw new Error(`SEMANTIC_RESOLUTION_ROW_INVALID:${field}`);
+    }
+}
+function requiredString(value, field) {
+    if (typeof value !== 'string' || value.length === 0) {
+        throw new Error(`SEMANTIC_RESOLUTION_ROW_INVALID:${field}`);
+    }
+    return value;
+}
+function optionalString(value) {
+    return typeof value === 'string' && value.length > 0 ? value : undefined;
+}
+function requiredPositiveInteger(value, field) {
+    const result = requiredNonNegativeInteger(value, field);
+    if (result < 1)
+        throw new Error(`SEMANTIC_RESOLUTION_ROW_INVALID:${field}`);
+    return result;
+}
+function requiredNonNegativeInteger(value, field) {
+    const result = Number(value);
+    if (!Number.isSafeInteger(result) || result < 0) {
+        throw new Error(`SEMANTIC_RESOLUTION_ROW_INVALID:${field}`);
+    }
+    return result;
+}

package/dist/task-runtime.d.ts

@@ -0,0 +1,64 @@
+export interface TaskRuntimeIdentityRecord {
+    projectRoot: string;
+    projectId: string;
+    hostId: string;
+    sessionId: string;
+    turnId: string;
+    requestId: string;
+    executionId?: string;
+}
+export interface TaskRuntimeEventRecord {
+    schemaVersion: 'task-runtime-event.v1';
+    producer: string;
+    producerVersion: string;
+    eventId: string;
+    sequence: number;
+    identity: TaskRuntimeIdentityRecord;
+    taskSpecHash: string;
+    kind: string;
+    payload: Record<string, unknown>;
+    createdAt: number;
+}
+export type TaskRuntimeChannelRequirement = 'required' | 'optional' | 'not_required';
+export type TaskRuntimeChannelStatus = 'satisfied' | 'intentional_abstention' | 'empty_valid' | 'degraded' | 'failed';
+export type TaskRuntimeObligationState = 'pending' | 'satisfied' | 'degraded' | 'failed';
+export interface TaskRuntimeChannelRecord {
+    requirement: TaskRuntimeChannelRequirement;
+    status: TaskRuntimeChannelStatus;
+    reasonCode: string;
+    evidenceIds: string[];
+    material: boolean;
+}
+export interface TaskRuntimeObligationRecord {
+    requirement: TaskRuntimeChannelRequirement;
+    state: TaskRuntimeObligationState;
+    receiptId?: string;
+    reasonCode?: string;
+}
+export interface TaskRuntimeSnapshotRecord {
+    schemaVersion: 'task-runtime-snapshot.v1';
+    producer: string;
+    producerVersion: string;
+    identity: TaskRuntimeIdentityRecord;
+    taskSpecHash: string;
+    lastEventSequence: number;
+    artifacts: {
+        requiredIdentityIds: string[];
+        resolvedIdentityIds: string[];
+        ambiguousIdentityIds: string[];
+    };
+    channels: Partial<Record<'code' | 'memory' | 'knowledge', TaskRuntimeChannelRecord>>;
+    contextReceiptId?: string;
+    action: TaskRuntimeObligationRecord;
+    verification: TaskRuntimeObligationRecord;
+    memory: TaskRuntimeObligationRecord;
+    durableWorkIds: string[];
+    terminal: 'running' | 'retry_pending' | 'completed' | 'completed_with_degradation' | 'failed';
+    runtimeHealth: 'healthy' | 'degraded' | 'unavailable';
+    snapshotHash: string;
+    updatedAt: number;
+}
+export declare function stableTaskRuntimeJson(value: unknown): string;
+export declare function stableTaskRuntimeHash(value: unknown): string;
+export declare function mapTaskRuntimeEventRow(row: Record<string, unknown>): TaskRuntimeEventRecord;
+export declare function mapTaskRuntimeSnapshotRow(row: Record<string, unknown>): TaskRuntimeSnapshotRecord;

package/dist/task-runtime.js

@@ -0,0 +1,106 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.stableTaskRuntimeJson = stableTaskRuntimeJson;
+exports.stableTaskRuntimeHash = stableTaskRuntimeHash;
+exports.mapTaskRuntimeEventRow = mapTaskRuntimeEventRow;
+exports.mapTaskRuntimeSnapshotRow = mapTaskRuntimeSnapshotRow;
+const node_crypto_1 = require("node:crypto");
+function stableTaskRuntimeJson(value) {
+    return JSON.stringify(canonicalize(value));
+}
+function stableTaskRuntimeHash(value) {
+    return (0, node_crypto_1.createHash)('sha256').update(stableTaskRuntimeJson(value)).digest('hex');
+}
+function mapTaskRuntimeEventRow(row) {
+    return {
+        schemaVersion: requiredLiteral(row.schema_version, 'task-runtime-event.v1'),
+        producer: requiredString(row.producer, 'producer'),
+        producerVersion: requiredString(row.producer_version, 'producer_version'),
+        eventId: requiredString(row.event_id, 'event_id'),
+        sequence: requiredPositiveInteger(row.sequence, 'sequence'),
+        identity: mapIdentity(row),
+        taskSpecHash: requiredString(row.task_spec_hash, 'task_spec_hash'),
+        kind: requiredString(row.kind, 'kind'),
+        payload: parseObject(row.payload_json, 'payload_json'),
+        createdAt: requiredNonNegativeInteger(row.created_at, 'created_at'),
+    };
+}
+function mapTaskRuntimeSnapshotRow(row) {
+    const snapshot = parseObject(row.snapshot_json, 'snapshot_json');
+    if (snapshot.schemaVersion !== 'task-runtime-snapshot.v1') {
+        throw new Error(`TASK_RUNTIME_SCHEMA_UNSUPPORTED:${String(snapshot.schemaVersion)}`);
+    }
+    if (snapshot.snapshotHash !== requiredString(row.snapshot_hash, 'snapshot_hash')) {
+        throw new Error('TASK_RUNTIME_SNAPSHOT_HASH_MISMATCH');
+    }
+    const { snapshotHash: _snapshotHash, ...body } = snapshot;
+    if (stableTaskRuntimeHash(body) !== snapshot.snapshotHash) {
+        throw new Error('TASK_RUNTIME_SNAPSHOT_HASH_MISMATCH');
+    }
+    return snapshot;
+}
+function mapIdentity(row) {
+    return {
+        projectRoot: requiredString(row.project_root, 'project_root'),
+        projectId: requiredString(row.project_id, 'project_id'),
+        hostId: requiredString(row.host_id, 'host_id'),
+        sessionId: requiredString(row.session_id, 'session_id'),
+        turnId: requiredString(row.turn_id, 'turn_id'),
+        requestId: requiredString(row.request_id, 'request_id'),
+        ...(optionalString(row.execution_id) ? { executionId: optionalString(row.execution_id) } : {}),
+    };
+}
+function requiredLiteral(value, literal) {
+    if (value !== literal)
+        throw new Error(`TASK_RUNTIME_SCHEMA_UNSUPPORTED:${String(value)}`);
+    return literal;
+}
+function requiredString(value, field) {
+    if (typeof value !== 'string' || !value.trim())
+        throw new Error(`TASK_RUNTIME_ROW_INVALID:${field}`);
+    return value;
+}
+function optionalString(value) {
+    return typeof value === 'string' && value.length > 0 ? value : undefined;
+}
+function requiredPositiveInteger(value, field) {
+    const result = Number(value);
+    if (!Number.isSafeInteger(result) || result < 1)
+        throw new Error(`TASK_RUNTIME_ROW_INVALID:${field}`);
+    return result;
+}
+function requiredNonNegativeInteger(value, field) {
+    const result = Number(value);
+    if (!Number.isSafeInteger(result) || result < 0)
+        throw new Error(`TASK_RUNTIME_ROW_INVALID:${field}`);
+    return result;
+}
+function parseObject(value, field) {
+    if (typeof value !== 'string')
+        throw new Error(`TASK_RUNTIME_ROW_INVALID:${field}`);
+    try {
+        const parsed = JSON.parse(value);
+        if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed))
+            throw new Error('not object');
+        return parsed;
+    }
+    catch {
+        throw new Error(`TASK_RUNTIME_ROW_INVALID:${field}`);
+    }
+}
+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('TASK_RUNTIME_JSON_INVALID');
+        return value;
+    }
+    if (Array.isArray(value))
+        return value.map(canonicalize);
+    if (!value || typeof value !== 'object' || Object.getPrototypeOf(value) !== Object.prototype) {
+        throw new Error('TASK_RUNTIME_JSON_INVALID');
+    }
+    return Object.fromEntries(Object.keys(value).sort()
+        .map(key => [key, canonicalize(value[key])]));
+}

package/dist/work-queue.d.ts

@@ -1,5 +1,5 @@
-export type WorkKind = 'memory.explicit_commit' | 'memory.explicit_enrichment' | 'memory.turn_capture' | 'memory.turn_distill' | 'memory.vector_backfill' | 'context.prefetch' | 'verification.policy' | 'learning.analyze_session' | 'workflow.worker_start' | 'workflow.worker_monitor' | 'workflow.worker_verify' | 'workflow.worker_merge' | 'workflow.worker_cleanup' | 'session.bootstrap' | 'session.finalize' | 'telemetry.reconcile';
-export type WorkState = 'pending' | 'leased' | 'completed' | 'failed' | 'dead_letter';
+export type WorkKind = 'memory.explicit_commit' | 'memory.explicit_enrichment' | 'memory.turn_capture' | 'memory.turn_distill' | 'memory.vector_backfill' | 'knowledge.ingest' | 'knowledge.index_refresh' | 'context.prefetch' | 'verification.policy' | 'learning.analyze_session' | 'workflow.worker_start' | 'workflow.worker_monitor' | 'workflow.worker_verify' | 'workflow.worker_merge' | 'workflow.worker_cleanup' | 'session.bootstrap' | 'session.finalize' | 'telemetry.reconcile';
+export type WorkState = 'pending' | 'leased' | 'completed' | 'failed' | 'dead_letter' | 'cancelled';
 export interface WorkError {
     category: string;
     message: string;
@@ -11,6 +11,8 @@ export interface WorkItemRecord {
     projectRoot: string;
     sessionId?: string;
     turnId?: string;
+    sourceHash?: string;
+    taskSpecHash?: string;
     payload: unknown;
     state: WorkState;
     attempts: number;
@@ -23,6 +25,10 @@ export interface WorkItemRecord {
     createdAt: number;
     updatedAt: number;
     completedAt?: number;
+    cancelledAt?: number;
+    cancellationReason?: string;
+    replayOfId?: string;
+    replayCount: number;
 }
 export interface EnqueueWorkInput {
     idempotencyKey: string;
@@ -30,10 +36,20 @@ export interface EnqueueWorkInput {
     projectRoot: string;
     sessionId?: string;
     turnId?: string;
+    sourceHash?: string;
+    taskSpecHash?: string;
     payload: unknown;
     maxAttempts?: number;
     nextAttemptAt?: number;
 }
+export interface ProjectMutationLeaseRecord {
+    projectRoot: string;
+    mutationKind: string;
+    owner: string;
+    leaseExpiresAt: number;
+    sourceHash?: string;
+    updatedAt: number;
+}
 export interface LeaseWorkInput {
     projectRoot: string;
     owner: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@devflow-tools/database",
-  "version": "0.17.2",
+  "version": "0.17.4",
   "description": "DevFlow SQLite database package",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -13,5 +13,5 @@
     "typescript": "^5.5.0",
     "vitest": "^2.0.0"
   },
-  "gitHead": "964af33767bf232606e63d973b3a29d7d53c8119"
+  "gitHead": "b880054f9cef4ed62b4d02544257c9f5cbd811bc"
 }