@opengeni/db 3.5.2-canary.0 → 3.7.3-canary.0

package/src/work-claims-schema.ts

@@ -0,0 +1,148 @@
+import { sql } from "drizzle-orm";
+import {
+  customType,
+  index,
+  integer,
+  pgTable,
+  primaryKey,
+  text,
+  timestamp,
+  uniqueIndex,
+  uuid,
+} from "drizzle-orm/pg-core";
+
+const xid8 = customType<{ data: string; driverData: string }>({
+  dataType: () => "xid8",
+});
+
+// Exact lifecycle-only mutation, immutable revisions, FORCE RLS, and runtime
+// grants are owned by the work-claim migration. The application role receives
+// SELECT on the compact head plus EXECUTE on exact-attempt mutation routines,
+// never direct DML authority.
+export const sessionWorkClaims = pgTable(
+  "session_work_claims",
+  {
+    id: uuid("id").primaryKey().defaultRandom(),
+    accountId: uuid("account_id").notNull(),
+    workspaceId: uuid("workspace_id").notNull(),
+    sessionId: uuid("session_id").notNull(),
+    rootSessionId: uuid("root_session_id").notNull(),
+    subjectNamespace: text("subject_namespace").notNull(),
+    subjectType: text("subject_type").notNull(),
+    canonicalKey: text("canonical_key").notNull(),
+    subjectDigest: text("subject_digest").notNull(),
+    displayLabel: text("display_label"),
+    role: text("role").notNull(),
+    state: text("state").notNull().default("active"),
+    revision: integer("revision").notNull().default(1),
+    provenance: text("provenance").notNull(),
+    versionKind: text("version_kind"),
+    versionValue: text("version_value"),
+    observedAt: timestamp("observed_at", { withTimezone: true }).notNull(),
+    createdAt: timestamp("created_at", { withTimezone: true }).notNull().defaultNow(),
+    updatedAt: timestamp("updated_at", { withTimezone: true }).notNull().defaultNow(),
+    settledAt: timestamp("settled_at", { withTimezone: true }),
+  },
+  (table) => ({
+    workspaceIdentity: uniqueIndex("session_work_claims_workspace_id_uq").on(
+      table.workspaceId,
+      table.id,
+    ),
+    activeIdentity: uniqueIndex("session_work_claims_active_identity_uq")
+      .on(
+        table.workspaceId,
+        table.sessionId,
+        table.subjectNamespace,
+        table.subjectType,
+        table.subjectDigest,
+        table.role,
+      )
+      .where(sql`${table.state} = 'active'`),
+    sessionState: index("session_work_claims_session_state_idx").on(
+      table.workspaceId,
+      table.sessionId,
+      table.state,
+      table.updatedAt,
+      table.id,
+    ),
+    subjectState: index("session_work_claims_subject_state_idx").on(
+      table.workspaceId,
+      table.subjectNamespace,
+      table.subjectType,
+      table.subjectDigest,
+      table.state,
+      table.updatedAt,
+      table.id,
+    ),
+  }),
+);
+
+export const sessionWorkClaimRevisions = pgTable(
+  "session_work_claim_revisions",
+  {
+    id: uuid("id").primaryKey().defaultRandom(),
+    accountId: uuid("account_id").notNull(),
+    workspaceId: uuid("workspace_id").notNull(),
+    claimId: uuid("claim_id").notNull(),
+    sessionId: uuid("session_id").notNull(),
+    rootSessionId: uuid("root_session_id").notNull(),
+    operationId: uuid("operation_id").notNull(),
+    inputHash: text("input_hash").notNull(),
+    mutationKind: text("mutation_kind").notNull(),
+    priorRevision: integer("prior_revision"),
+    resultingRevision: integer("resulting_revision").notNull(),
+    subjectNamespace: text("subject_namespace").notNull(),
+    subjectType: text("subject_type").notNull(),
+    canonicalKey: text("canonical_key").notNull(),
+    subjectDigest: text("subject_digest").notNull(),
+    displayLabel: text("display_label"),
+    role: text("role").notNull(),
+    state: text("state").notNull(),
+    provenance: text("provenance").notNull(),
+    versionKind: text("version_kind"),
+    versionValue: text("version_value"),
+    observedAt: timestamp("observed_at", { withTimezone: true }).notNull(),
+    claimCreatedAt: timestamp("claim_created_at", { withTimezone: true }).notNull(),
+    claimUpdatedAt: timestamp("claim_updated_at", { withTimezone: true }).notNull(),
+    settledAt: timestamp("settled_at", { withTimezone: true }),
+    actorKind: text("actor_kind").notNull(),
+    actorSubjectId: text("actor_subject_id").notNull(),
+    actorSessionId: uuid("actor_session_id"),
+    actorTurnId: uuid("actor_turn_id"),
+    actorAttemptId: uuid("actor_attempt_id"),
+    actorExecutionGeneration: integer("actor_execution_generation"),
+    reason: text("reason"),
+    createdAt: timestamp("created_at", { withTimezone: true }).notNull().defaultNow(),
+  },
+  (table) => ({
+    operation: uniqueIndex("session_work_claim_revisions_workspace_operation_uq").on(
+      table.workspaceId,
+      table.operationId,
+    ),
+    claimRevision: uniqueIndex("session_work_claim_revisions_claim_revision_uq").on(
+      table.workspaceId,
+      table.claimId,
+      table.resultingRevision,
+    ),
+    sessionTimeline: index("session_work_claim_revisions_session_timeline_idx").on(
+      table.workspaceId,
+      table.sessionId,
+      table.createdAt,
+      table.id,
+    ),
+  }),
+);
+
+export const sessionWorkClaimWriteCapabilities = pgTable(
+  "session_work_claim_write_capabilities",
+  {
+    backendPid: integer("backend_pid").notNull(),
+    transactionId: xid8("transaction_id").notNull(),
+    capabilityId: uuid("capability_id").notNull(),
+  },
+  (table) => ({
+    identity: primaryKey({
+      columns: [table.backendPid, table.transactionId, table.capabilityId],
+    }),
+  }),
+);

package/src/work-claims.ts

@@ -0,0 +1,200 @@
+import {
+  WorkClaim,
+  WorkClaimCanonicalKey,
+  WorkClaimDisplayLabel,
+  WorkClaimMutationKind,
+  WorkClaimMutationResult,
+  WorkClaimNamespace,
+  WorkClaimReleaseReason,
+  WorkClaimRole,
+  WorkClaimSubjectType,
+  WorkClaimVersionKind,
+  WorkClaimVersionValue,
+  normalizeWorkClaimCanonicalKey,
+  normalizeWorkClaimDisplayLabel,
+  normalizeWorkClaimNamespace,
+  type WorkClaimRole as WorkClaimRoleType,
+  type WorkClaimSubjectType as WorkClaimSubjectTypeType,
+  type WorkClaimVersionKind as WorkClaimVersionKindType,
+} from "@opengeni/contracts";
+import { sql } from "drizzle-orm";
+import type { Database } from "./database";
+import { rawRows, withSessionActivityRlsContext } from "./database";
+
+export type WorkClaimAttemptClaims = {
+  accountId: string;
+  workspaceId: string;
+  sessionId: string;
+  turnId: string;
+  attemptId: string;
+  executionGeneration: number;
+};
+
+export type UpsertWorkClaimInput = WorkClaimAttemptClaims & {
+  operationId: string;
+  expectedRevision: number;
+  subjectNamespace: string;
+  subjectType: WorkClaimSubjectTypeType;
+  canonicalKey: string;
+  displayLabel?: string | null;
+  role: WorkClaimRoleType;
+  version?: {
+    kind: WorkClaimVersionKindType;
+    value: string;
+  } | null;
+};
+
+export type ReleaseWorkClaimInput = WorkClaimAttemptClaims & {
+  operationId: string;
+  claimId: string;
+  expectedRevision: number;
+  reason: string;
+};
+
+type WorkClaimMutationRow = {
+  claim_id: string;
+  session_id: string;
+  root_session_id: string;
+  subject_namespace: string;
+  subject_type: string;
+  canonical_key: string;
+  display_label: string | null;
+  role: string;
+  state: string;
+  revision: number;
+  provenance: string;
+  version_kind: string | null;
+  version_value: string | null;
+  observed_at: Date | string;
+  created_at: Date | string;
+  updated_at: Date | string;
+  settled_at: Date | string | null;
+  mutation_kind: string;
+  replayed: boolean;
+};
+
+function iso(value: Date | string): string {
+  return (value instanceof Date ? value : new Date(value)).toISOString();
+}
+
+function assertAttemptClaims(claims: WorkClaimAttemptClaims): void {
+  if (!Number.isSafeInteger(claims.executionGeneration) || claims.executionGeneration < 1) {
+    throw new Error("Work claims require a positive exact execution generation");
+  }
+}
+
+function mutationResultFromRow(row: WorkClaimMutationRow) {
+  const version =
+    row.version_kind === null || row.version_value === null
+      ? null
+      : {
+          kind: WorkClaimVersionKind.parse(row.version_kind),
+          value: WorkClaimVersionValue.parse(row.version_value),
+        };
+  return WorkClaimMutationResult.parse({
+    claim: WorkClaim.parse({
+      id: row.claim_id,
+      sessionId: row.session_id,
+      rootSessionId: row.root_session_id,
+      subject: {
+        namespace: row.subject_namespace,
+        type: row.subject_type,
+        canonicalKey: row.canonical_key,
+        displayLabel: row.display_label,
+      },
+      role: row.role,
+      state: row.state,
+      revision: Number(row.revision),
+      provenance: row.provenance,
+      version,
+      observedAt: iso(row.observed_at),
+      createdAt: iso(row.created_at),
+      updatedAt: iso(row.updated_at),
+      settledAt: row.settled_at === null ? null : iso(row.settled_at),
+    }),
+    mutation: WorkClaimMutationKind.parse(row.mutation_kind),
+    replayed: row.replayed,
+  });
+}
+
+export async function upsertWorkClaim(db: Database, input: UpsertWorkClaimInput) {
+  assertAttemptClaims(input);
+  if (!Number.isSafeInteger(input.expectedRevision) || input.expectedRevision < 0) {
+    throw new Error("Work claim expectedRevision must be a non-negative safe integer");
+  }
+  const subjectNamespace = WorkClaimNamespace.parse(
+    normalizeWorkClaimNamespace(input.subjectNamespace),
+  );
+  const subjectType = WorkClaimSubjectType.parse(input.subjectType);
+  const canonicalKey = WorkClaimCanonicalKey.parse(
+    normalizeWorkClaimCanonicalKey(input.canonicalKey),
+  );
+  const role = WorkClaimRole.parse(input.role);
+  const displayLabel =
+    input.displayLabel === undefined || input.displayLabel === null
+      ? null
+      : WorkClaimDisplayLabel.parse(normalizeWorkClaimDisplayLabel(input.displayLabel));
+  const version = input.version
+    ? {
+        kind: WorkClaimVersionKind.parse(input.version.kind),
+        value: WorkClaimVersionValue.parse(normalizeWorkClaimCanonicalKey(input.version.value)),
+      }
+    : null;
+  const rows = await withSessionActivityRlsContext(
+    db,
+    { accountId: input.accountId, workspaceId: input.workspaceId },
+    async (tx) =>
+      await rawRows<WorkClaimMutationRow>(
+        tx,
+        sql`SELECT * FROM upsert_session_work_claim_for_attempt(
+          ${input.accountId}::uuid,
+          ${input.workspaceId}::uuid,
+          ${input.sessionId}::uuid,
+          ${input.turnId}::uuid,
+          ${input.attemptId}::uuid,
+          ${input.executionGeneration}::integer,
+          ${input.operationId}::uuid,
+          ${input.expectedRevision}::integer,
+          ${subjectNamespace}::text,
+          ${subjectType}::text,
+          ${canonicalKey}::text,
+          ${displayLabel}::text,
+          ${role}::text,
+          ${version?.kind ?? null}::text,
+          ${version?.value ?? null}::text
+        )`,
+      ),
+  );
+  if (rows.length !== 1) throw new Error("Work claim upsert returned no durable receipt");
+  return mutationResultFromRow(rows[0]!);
+}
+
+export async function releaseWorkClaim(db: Database, input: ReleaseWorkClaimInput) {
+  assertAttemptClaims(input);
+  if (!Number.isSafeInteger(input.expectedRevision) || input.expectedRevision < 1) {
+    throw new Error("Work claim release requires a positive expectedRevision");
+  }
+  const reason = WorkClaimReleaseReason.parse(input.reason);
+  const rows = await withSessionActivityRlsContext(
+    db,
+    { accountId: input.accountId, workspaceId: input.workspaceId },
+    async (tx) =>
+      await rawRows<WorkClaimMutationRow>(
+        tx,
+        sql`SELECT * FROM release_session_work_claim_for_attempt(
+          ${input.accountId}::uuid,
+          ${input.workspaceId}::uuid,
+          ${input.sessionId}::uuid,
+          ${input.turnId}::uuid,
+          ${input.attemptId}::uuid,
+          ${input.executionGeneration}::integer,
+          ${input.operationId}::uuid,
+          ${input.claimId}::uuid,
+          ${input.expectedRevision}::integer,
+          ${reason}::text
+        )`,
+      ),
+  );
+  if (rows.length !== 1) throw new Error("Work claim release returned no durable receipt");
+  return mutationResultFromRow(rows[0]!);
+}