@devflow-tools/database 0.17.2 → 0.17.3

package/src/task-runtime.ts

@@ -0,0 +1,169 @@
+import { createHash } from 'node:crypto';
+
+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 function stableTaskRuntimeJson(value: unknown): string {
+  return JSON.stringify(canonicalize(value));
+}
+
+export function stableTaskRuntimeHash(value: unknown): string {
+  return createHash('sha256').update(stableTaskRuntimeJson(value)).digest('hex');
+}
+
+export function mapTaskRuntimeEventRow(row: Record<string, unknown>): TaskRuntimeEventRecord {
+  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'),
+  };
+}
+
+export function mapTaskRuntimeSnapshotRow(row: Record<string, unknown>): TaskRuntimeSnapshotRecord {
+  const snapshot = parseObject(row.snapshot_json, 'snapshot_json') as unknown as TaskRuntimeSnapshotRecord;
+  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: Record<string, unknown>): TaskRuntimeIdentityRecord {
+  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<T extends string>(value: unknown, literal: T): T {
+  if (value !== literal) throw new Error(`TASK_RUNTIME_SCHEMA_UNSUPPORTED:${String(value)}`);
+  return literal;
+}
+
+function requiredString(value: unknown, field: string): string {
+  if (typeof value !== 'string' || !value.trim()) throw new Error(`TASK_RUNTIME_ROW_INVALID:${field}`);
+  return value;
+}
+
+function optionalString(value: unknown): string | undefined {
+  return typeof value === 'string' && value.length > 0 ? value : undefined;
+}
+
+function requiredPositiveInteger(value: unknown, field: string): number {
+  const result = Number(value);
+  if (!Number.isSafeInteger(result) || result < 1) throw new Error(`TASK_RUNTIME_ROW_INVALID:${field}`);
+  return result;
+}
+
+function requiredNonNegativeInteger(value: unknown, field: string): number {
+  const result = Number(value);
+  if (!Number.isSafeInteger(result) || result < 0) throw new Error(`TASK_RUNTIME_ROW_INVALID:${field}`);
+  return result;
+}
+
+function parseObject(value: unknown, field: string): Record<string, unknown> {
+  if (typeof value !== 'string') throw new Error(`TASK_RUNTIME_ROW_INVALID:${field}`);
+  try {
+    const parsed = JSON.parse(value) as unknown;
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) throw new Error('not object');
+    return parsed as Record<string, unknown>;
+  } catch {
+    throw new Error(`TASK_RUNTIME_ROW_INVALID:${field}`);
+  }
+}
+
+function canonicalize(value: unknown): unknown {
+  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 as Record<string, unknown>).sort()
+    .map(key => [key, canonicalize((value as Record<string, unknown>)[key])]));
+}

package/src/work-queue.ts

@@ -4,6 +4,8 @@ export type WorkKind =
   | 'memory.turn_capture'
   | 'memory.turn_distill'
   | 'memory.vector_backfill'
+  | 'knowledge.ingest'
+  | 'knowledge.index_refresh'
   | 'context.prefetch'
   | 'verification.policy'
   | 'learning.analyze_session'
@@ -16,7 +18,7 @@ export type WorkKind =
   | 'session.finalize'
   | 'telemetry.reconcile';
 
-export type WorkState = 'pending' | 'leased' | 'completed' | 'failed' | 'dead_letter';
+export type WorkState = 'pending' | 'leased' | 'completed' | 'failed' | 'dead_letter' | 'cancelled';
 
 export interface WorkError {
   category: string;
@@ -30,6 +32,8 @@ export interface WorkItemRecord {
   projectRoot: string;
   sessionId?: string;
   turnId?: string;
+  sourceHash?: string;
+  taskSpecHash?: string;
   payload: unknown;
   state: WorkState;
   attempts: number;
@@ -42,6 +46,10 @@ export interface WorkItemRecord {
   createdAt: number;
   updatedAt: number;
   completedAt?: number;
+  cancelledAt?: number;
+  cancellationReason?: string;
+  replayOfId?: string;
+  replayCount: number;
 }
 
 export interface EnqueueWorkInput {
@@ -50,11 +58,22 @@ 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;