@opengeni/db 3.5.2-canary.0 → 3.6.0

package/src/provision-roles.ts

@@ -6,6 +6,7 @@ import {
   RUNTIME_READ_INSERT_UPDATE_TABLES,
   RUNTIME_READ_ONLY_TABLES,
   RUNTIME_READ_UPDATE_TABLES,
+  WORK_CLAIM_CAPABILITY_ROUTINES,
 } from "./runtime-posture";
 import {
   classifyRoleRelationships,
@@ -482,6 +483,7 @@ async function grantAppRoleIfSchemaExists(
   const runtimeReadUpdateTables = `ARRAY[${RUNTIME_READ_UPDATE_TABLES.map(literal).join(", ")}]`;
   const runtimeReadInsertTables = `ARRAY[${RUNTIME_READ_INSERT_TABLES.map(literal).join(", ")}]`;
   const runtimeReadInsertUpdateTables = `ARRAY[${RUNTIME_READ_INSERT_UPDATE_TABLES.map(literal).join(", ")}]`;
+  const workClaimCapabilityRoutines = `ARRAY[${WORK_CLAIM_CAPABILITY_ROUTINES.map(literal).join(", ")}]`;
   const organizationMembershipLifecycleRoutines = `ARRAY[${[
     "list_self_organization_memberships(text)",
     "list_self_organization_invitations(text)",
@@ -997,6 +999,22 @@ BEGIN
         ${literal(role)}
       );
     END IF;
+    -- Migration 0365 creates the advisory work-claim mutation capabilities
+    -- before a custom runtime role may exist. Re-converge their exact grants
+    -- for migrate-then-provision installs without exposing claim history or
+    -- the write-capability ledger to direct runtime DML.
+    FOREACH routine_signature IN ARRAY ${workClaimCapabilityRoutines} LOOP
+      IF to_regprocedure(format('%I.%s', ${literal(schema)}, routine_signature)) IS NOT NULL THEN
+        EXECUTE format(
+          'REVOKE ALL ON FUNCTION %I.%s FROM PUBLIC',
+          ${literal(schema)}, routine_signature
+        );
+        EXECUTE format(
+          'GRANT EXECUTE ON FUNCTION %I.%s TO %I',
+          ${literal(schema)}, routine_signature, ${literal(role)}
+        );
+      END IF;
+    END LOOP;
     IF to_regprocedure(
       format(
         '%I.workspace_instruction_policy_get_or_create_snapshot(uuid,uuid,uuid,uuid,uuid,integer)',

package/src/runtime-posture.ts

@@ -377,6 +377,10 @@ const TASK_NOTE_CAPABILITY_ROUTINES = [
   "replace_task_note_for_attempt(uuid, uuid, uuid, uuid, uuid, integer, uuid, uuid, uuid, uuid, integer, text, text, integer, text)",
   "resolve_task_note_knowledge_promotion_source(uuid, uuid, uuid, uuid, uuid, integer, uuid, integer, text, text, text)",
 ] as const;
+export const WORK_CLAIM_CAPABILITY_ROUTINES = [
+  "upsert_session_work_claim_for_attempt(uuid, uuid, uuid, uuid, uuid, integer, uuid, integer, text, text, text, text, text, text, text)",
+  "release_session_work_claim_for_attempt(uuid, uuid, uuid, uuid, uuid, integer, uuid, uuid, integer, text)",
+] as const;
 const COMPANY_BRAIN_CONTEXT_SELECTION_ROUTINE =
   "company_brain_context_get_or_create_selection(uuid, uuid, uuid, uuid, uuid, integer)";
 const COMPANY_BRAIN_CONTEXT_INSPECTION_ROUTINE =
@@ -500,6 +504,7 @@ const SESSION_AUTHORITY_ROUTINES = new Set<string>([
   ...PRIVATE_SESSION_CREATE_CAPABILITY_ROUTINES,
   TRANSITION_SESSION_VISIBILITY_ROUTINE,
   ...TASK_NOTE_CAPABILITY_ROUTINES,
+  ...WORK_CLAIM_CAPABILITY_ROUTINES,
   COMPANY_BRAIN_CONTEXT_SELECTION_ROUTINE,
   COMPANY_BRAIN_CONTEXT_INSPECTION_ROUTINE,
 ]);
@@ -557,6 +562,7 @@ export const RUNTIME_TARGET_SCHEMA_CAPABILITY_ROUTINES = [
   ...MANAGED_AUTH_SESSION_SET_ROUTINES,
   ...ORGANIZATION_RECOVERY_ROUTINES,
   ...TASK_NOTE_CAPABILITY_ROUTINES,
+  ...WORK_CLAIM_CAPABILITY_ROUTINES,
   SESSION_PRIVATE_ACTOR_VISIBLE_ROUTINE,
   SESSION_REFERENCE_VISIBLE_ROUTINE,
   SESSION_VISIBILITY_LIFECYCLE_CAPABILITY_ROUTINE,
@@ -868,6 +874,9 @@ export const FORCE_RLS_TABLES = [
   "session_turns",
   "session_variable_set_attachments",
   "session_visibility_write_capabilities",
+  "session_work_claim_revisions",
+  "session_work_claim_write_capabilities",
+  "session_work_claims",
   "session_workflow_wake_outbox",
   "sessions",
   "site_auth_connections",
@@ -1136,6 +1145,7 @@ export const RUNTIME_READ_ONLY_TABLES = [
   "preference_registry_events",
   "preference_registry_snapshots",
   "session_tenancy_activations",
+  "session_work_claims",
   "slack_installation_bindings",
   "slack_task_policy_activation_events",
   "slack_task_policy_heads",
@@ -1330,6 +1340,8 @@ export const PROTECTED_NO_DIRECT_DML_TABLES = [
   "session_tenancy_greenfield_activation_evidence",
   "session_variable_set_attachments",
   "session_visibility_write_capabilities",
+  "session_work_claim_revisions",
+  "session_work_claim_write_capabilities",
   "task_note_events",
   "task_note_knowledge_promotion_capabilities",
   "task_note_replacement_receipts",

package/src/schema.ts

@@ -12483,6 +12483,7 @@ export * from "./preference-registry-schema";
 export * from "./memory-governance-schema";
 export * from "./scoped-knowledge-schema";
 export * from "./task-notes-schema";
+export * from "./work-claims-schema";
 export * from "./company-brain-context-selection-schema";
 export * from "./governed-learning-evaluator-schema";
 export * from "./governed-learning-activation-schema";

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]!);
+}