@opengeni/db 0.28.9 → 0.36.0

package/src/task-notes-schema.ts

@@ -0,0 +1,135 @@
+import {
+  customType,
+  index,
+  integer,
+  pgTable,
+  text,
+  timestamp,
+  uniqueIndex,
+  uuid,
+} from "drizzle-orm/pg-core";
+import { sql } from "drizzle-orm";
+
+const xid8 = customType<{ data: string; driverData: string }>({
+  dataType: () => "xid8",
+});
+
+// Cross-row validation, lifecycle-only mutation, exact-attempt authority,
+// restrictive session-visibility RLS, and grants are owned by migration 0239.
+export const taskNotes = pgTable(
+  "task_notes",
+  {
+    id: uuid("id").primaryKey().defaultRandom(),
+    accountId: uuid("account_id").notNull(),
+    workspaceId: uuid("workspace_id").notNull(),
+    rootSessionId: uuid("root_session_id").notNull(),
+    kind: text("kind").notNull(),
+    text: text("text").notNull(),
+    textHash: text("text_hash").notNull(),
+    status: text("status").notNull().default("active"),
+    version: integer("version").notNull().default(1),
+    expiresAt: timestamp("expires_at", { withTimezone: true }).notNull(),
+    createOperationId: uuid("create_operation_id").notNull(),
+    createInputHash: text("create_input_hash").notNull(),
+    createdByActorKind: text("created_by_actor_kind").notNull(),
+    createdByActorSubjectId: text("created_by_actor_subject_id").notNull(),
+    createdByInitiatingHumanSubjectId: text("created_by_initiating_human_subject_id"),
+    createdBySessionId: uuid("created_by_session_id").notNull(),
+    createdByTurnId: uuid("created_by_turn_id").notNull(),
+    createdByAttemptId: uuid("created_by_attempt_id").notNull(),
+    createdByExecutionGeneration: integer("created_by_execution_generation").notNull(),
+    archiveOperationId: uuid("archive_operation_id"),
+    archiveInputHash: text("archive_input_hash"),
+    archivedByActorKind: text("archived_by_actor_kind"),
+    archivedByActorSubjectId: text("archived_by_actor_subject_id"),
+    archivedByInitiatingHumanSubjectId: text("archived_by_initiating_human_subject_id"),
+    archivedBySessionId: uuid("archived_by_session_id"),
+    archivedByTurnId: uuid("archived_by_turn_id"),
+    archivedByAttemptId: uuid("archived_by_attempt_id"),
+    archivedByExecutionGeneration: integer("archived_by_execution_generation"),
+    archivedAt: timestamp("archived_at", { withTimezone: true }),
+    createdAt: timestamp("created_at", { withTimezone: true }).notNull().defaultNow(),
+    updatedAt: timestamp("updated_at", { withTimezone: true }).notNull().defaultNow(),
+  },
+  (table) => ({
+    workspaceIdentity: uniqueIndex("task_notes_workspace_id_uq").on(table.workspaceId, table.id),
+    workspaceRootIdentity: uniqueIndex("task_notes_workspace_root_id_uq").on(
+      table.workspaceId,
+      table.rootSessionId,
+      table.id,
+    ),
+    createOperation: uniqueIndex("task_notes_workspace_create_operation_uq").on(
+      table.workspaceId,
+      table.createOperationId,
+    ),
+    archiveOperation: uniqueIndex("task_notes_workspace_archive_operation_uq")
+      .on(table.workspaceId, table.archiveOperationId)
+      .where(sql`${table.archiveOperationId} is not null`),
+    rootActive: index("task_notes_root_active_idx").on(
+      table.workspaceId,
+      table.rootSessionId,
+      table.status,
+      table.expiresAt,
+      table.updatedAt,
+      table.id,
+    ),
+  }),
+);
+
+export const taskNoteEvents = pgTable(
+  "task_note_events",
+  {
+    id: uuid("id").primaryKey().defaultRandom(),
+    accountId: uuid("account_id").notNull(),
+    workspaceId: uuid("workspace_id").notNull(),
+    rootSessionId: uuid("root_session_id").notNull(),
+    noteId: uuid("note_id").notNull(),
+    eventType: text("event_type").notNull(),
+    noteVersion: integer("note_version").notNull(),
+    operationId: uuid("operation_id").notNull(),
+    inputHash: text("input_hash").notNull(),
+    textHash: text("text_hash").notNull(),
+    reason: text("reason"),
+    actorKind: text("actor_kind").notNull(),
+    actorSubjectId: text("actor_subject_id").notNull(),
+    initiatingHumanSubjectId: text("initiating_human_subject_id"),
+    actorSessionId: uuid("actor_session_id").notNull(),
+    actorTurnId: uuid("actor_turn_id").notNull(),
+    actorAttemptId: uuid("actor_attempt_id").notNull(),
+    actorExecutionGeneration: integer("actor_execution_generation").notNull(),
+    createdAt: timestamp("created_at", { withTimezone: true }).notNull().defaultNow(),
+  },
+  (table) => ({
+    operation: uniqueIndex("task_note_events_workspace_operation_uq").on(
+      table.workspaceId,
+      table.operationId,
+    ),
+    noteVersion: uniqueIndex("task_note_events_note_version_uq").on(
+      table.workspaceId,
+      table.noteId,
+      table.noteVersion,
+    ),
+    rootTimeline: index("task_note_events_root_timeline_idx").on(
+      table.workspaceId,
+      table.rootSessionId,
+      table.createdAt,
+      table.id,
+    ),
+  }),
+);
+
+export const taskNoteWriteCapabilities = pgTable(
+  "task_note_write_capabilities",
+  {
+    backendPid: integer("backend_pid").notNull(),
+    transactionId: xid8("transaction_id").notNull(),
+    capabilityId: uuid("capability_id").notNull(),
+  },
+  (table) => ({
+    identity: uniqueIndex("task_note_write_capabilities_identity_uq").on(
+      table.backendPid,
+      table.transactionId,
+      table.capabilityId,
+    ),
+  }),
+);

package/src/task-notes.ts

@@ -0,0 +1,178 @@
+import {
+  TASK_NOTE_LIST_DEFAULT_LIMIT,
+  TASK_NOTE_LIST_MAX_LIMIT,
+  TaskNote,
+  TaskNoteKind,
+  TaskNoteListResponse,
+  TaskNoteMutationResult,
+  TaskNoteReason,
+  TaskNoteText,
+  type TaskNoteKind as TaskNoteKindType,
+} from "@opengeni/contracts";
+import { sql } from "drizzle-orm";
+import type { Database } from "./database";
+import { rawRows, withRlsContext } from "./database";
+
+export type TaskNoteAttemptClaims = {
+  accountId: string;
+  workspaceId: string;
+  sessionId: string;
+  turnId: string;
+  attemptId: string;
+  executionGeneration: number;
+};
+
+export type CreateTaskNoteInput = TaskNoteAttemptClaims & {
+  operationId: string;
+  kind: TaskNoteKindType;
+  text: string;
+  expiresInDays: number;
+};
+
+export type ArchiveTaskNoteInput = TaskNoteAttemptClaims & {
+  operationId: string;
+  noteId: string;
+  expectedVersion: number;
+  reason: string;
+};
+
+export type ListTaskNotesInput = TaskNoteAttemptClaims & {
+  includeArchived?: boolean;
+  limit?: number;
+};
+
+type TaskNoteRow = {
+  note_id: string;
+  root_session_id: string;
+  kind: string;
+  note_text: string;
+  status: string;
+  version: number;
+  expires_at: Date | string;
+  created_at: Date | string;
+  updated_at: Date | string;
+  archived_at: Date | string | null;
+  actor_kind: string;
+  source_session_id: string;
+  source_turn_id: string;
+  replayed?: boolean;
+};
+
+function iso(value: Date | string): string {
+  return (value instanceof Date ? value : new Date(value)).toISOString();
+}
+
+function noteFromRow(row: TaskNoteRow) {
+  return TaskNote.parse({
+    id: row.note_id,
+    rootSessionId: row.root_session_id,
+    kind: row.kind,
+    text: row.note_text,
+    status: row.status,
+    version: row.version,
+    expiresAt: iso(row.expires_at),
+    createdAt: iso(row.created_at),
+    updatedAt: iso(row.updated_at),
+    archivedAt: row.archived_at === null ? null : iso(row.archived_at),
+    provenance: {
+      actorKind: row.actor_kind,
+      sourceSessionId: row.source_session_id,
+      sourceTurnId: row.source_turn_id,
+    },
+  });
+}
+
+function assertAttemptClaims(claims: TaskNoteAttemptClaims): void {
+  if (!Number.isSafeInteger(claims.executionGeneration) || claims.executionGeneration < 1) {
+    throw new Error("Task notes require a positive exact execution generation");
+  }
+}
+
+export async function createTaskNote(db: Database, input: CreateTaskNoteInput) {
+  assertAttemptClaims(input);
+  TaskNoteKind.parse(input.kind);
+  TaskNoteText.parse(input.text);
+  if (
+    !Number.isSafeInteger(input.expiresInDays) ||
+    input.expiresInDays < 1 ||
+    input.expiresInDays > 30
+  ) {
+    throw new Error("Task note expiry must be 1-30 whole days");
+  }
+  const rows = await withRlsContext(
+    db,
+    { accountId: input.accountId, workspaceId: input.workspaceId },
+    async (tx) =>
+      await rawRows<TaskNoteRow>(
+        tx,
+        sql`SELECT * FROM create_task_note_for_attempt(
+          ${input.accountId}::uuid,
+          ${input.workspaceId}::uuid,
+          ${input.sessionId}::uuid,
+          ${input.turnId}::uuid,
+          ${input.attemptId}::uuid,
+          ${input.executionGeneration}::integer,
+          ${input.operationId}::uuid,
+          ${input.kind}::text,
+          ${input.text}::text,
+          ${input.expiresInDays}::integer
+        )`,
+      ),
+  );
+  if (rows.length !== 1) throw new Error("Task note create returned no durable receipt");
+  return TaskNoteMutationResult.parse({ note: noteFromRow(rows[0]!), replayed: rows[0]!.replayed });
+}
+
+export async function archiveTaskNote(db: Database, input: ArchiveTaskNoteInput) {
+  assertAttemptClaims(input);
+  TaskNoteReason.parse(input.reason);
+  const rows = await withRlsContext(
+    db,
+    { accountId: input.accountId, workspaceId: input.workspaceId },
+    async (tx) =>
+      await rawRows<TaskNoteRow>(
+        tx,
+        sql`SELECT * FROM archive_task_note_for_attempt(
+          ${input.accountId}::uuid,
+          ${input.workspaceId}::uuid,
+          ${input.sessionId}::uuid,
+          ${input.turnId}::uuid,
+          ${input.attemptId}::uuid,
+          ${input.executionGeneration}::integer,
+          ${input.operationId}::uuid,
+          ${input.noteId}::uuid,
+          ${input.expectedVersion}::integer,
+          ${input.reason}::text
+        )`,
+      ),
+  );
+  if (rows.length !== 1) throw new Error("Task note archive returned no durable receipt");
+  return TaskNoteMutationResult.parse({ note: noteFromRow(rows[0]!), replayed: rows[0]!.replayed });
+}
+
+export async function listTaskNotes(db: Database, input: ListTaskNotesInput) {
+  assertAttemptClaims(input);
+  const limit = input.limit ?? TASK_NOTE_LIST_DEFAULT_LIMIT;
+  if (!Number.isSafeInteger(limit) || limit < 1 || limit > TASK_NOTE_LIST_MAX_LIMIT) {
+    throw new Error(`Task note list limit must be 1-${TASK_NOTE_LIST_MAX_LIMIT}`);
+  }
+  const rows = await withRlsContext(
+    db,
+    { accountId: input.accountId, workspaceId: input.workspaceId },
+    async (tx) =>
+      await rawRows<TaskNoteRow>(
+        tx,
+        sql`SELECT * FROM list_task_notes_for_attempt(
+          ${input.accountId}::uuid,
+          ${input.workspaceId}::uuid,
+          ${input.sessionId}::uuid,
+          ${input.turnId}::uuid,
+          ${input.attemptId}::uuid,
+          ${input.executionGeneration}::integer,
+          ${input.includeArchived ?? false}::boolean,
+          ${limit}::integer
+        )`,
+      ),
+  );
+  return TaskNoteListResponse.parse({ notes: rows.map(noteFromRow) });
+}