@opengeni/db 1.0.1 → 3.2.0-canary.0

package/src/database.ts

@@ -115,6 +115,18 @@ export type RlsStrategy = "force" | "scoped";
  */
 export type UserLookup = (db: Database, email: string) => Promise<string | null>;
 
+export type ManagedUserProfile = {
+  id: string;
+  name: string | null;
+  email: string;
+};
+
+/** Host identity projection used by organization administration rosters. */
+export type UserProfileLookup = (
+  db: Database,
+  userIds: readonly string[],
+) => Promise<ManagedUserProfile[]>;
+
 export type CreateDbOptions = {
   /**
    * The Postgres `search_path` for this connection (Step I, §7.8 runtime half).
@@ -132,6 +144,8 @@ export type CreateDbOptions = {
   rlsStrategy?: RlsStrategy;
   /** Host-provided user-by-email resolver; unset → today's raw `auth_users` query. */
   userLookup?: UserLookup;
+  /** Host-provided user profile projection; unset → standalone `auth_users`. */
+  userProfileLookup?: UserProfileLookup;
   /** postgres-js pool size; defaults to today's `10`. */
   max?: number;
   /**
@@ -150,7 +164,11 @@ export type CreateDbOptions = {
  * config (e.g. one built outside `createDb`, or in a test) falls back to the
  * standalone defaults: `rlsStrategy: "force"`, raw `auth_users` lookup.
  */
-type DbBinding = { rlsStrategy: RlsStrategy; userLookup?: UserLookup };
+type DbBinding = {
+  rlsStrategy: RlsStrategy;
+  userLookup?: UserLookup;
+  userProfileLookup?: UserProfileLookup;
+};
 
 const dbBindings = new WeakMap<object, DbBinding>();
 
@@ -314,6 +332,7 @@ export function createDb(databaseUrl: string, options: CreateDbOptions = {}): Db
   dbBindings.set(db as unknown as object, {
     rlsStrategy: options.rlsStrategy ?? "force",
     ...(options.userLookup ? { userLookup: options.userLookup } : {}),
+    ...(options.userProfileLookup ? { userProfileLookup: options.userProfileLookup } : {}),
   });
   return {
     db,
@@ -331,11 +350,16 @@ export function createDb(databaseUrl: string, options: CreateDbOptions = {}): Db
  */
 export function registerDbBinding(
   db: Database,
-  binding: { rlsStrategy?: RlsStrategy; userLookup?: UserLookup },
+  binding: {
+    rlsStrategy?: RlsStrategy;
+    userLookup?: UserLookup;
+    userProfileLookup?: UserProfileLookup;
+  },
 ): void {
   dbBindings.set(db as unknown as object, {
     rlsStrategy: binding.rlsStrategy ?? "force",
     ...(binding.userLookup ? { userLookup: binding.userLookup } : {}),
+    ...(binding.userProfileLookup ? { userProfileLookup: binding.userProfileLookup } : {}),
   });
 }
 
@@ -429,12 +453,18 @@ export async function withRlsContext<T>(
   context: RlsContext,
   fn: (db: Database) => Promise<T>,
   transactionConfig?: PgTransactionConfig,
+  sessionTenancyFence: "shared" | "none" = "shared",
 ): Promise<T> {
   const restoreParentScope = isTransactionHandle(db);
   return await db.transaction(async (tx) => {
     const scoped = tx as unknown as Database;
     const parentScope = restoreParentScope ? await readRlsContextSettings(scoped) : null;
     await setRlsContext(scoped, context);
+    if (context.workspaceId && sessionTenancyFence === "shared") {
+      await scoped.execute(
+        sql`select pg_advisory_xact_lock_shared(hashtextextended(${`session-tenancy:${context.workspaceId}`}, 0))`,
+      );
+    }
     // Defense-in-depth: read the LOCAL GUC back on THIS backend BEFORE running
     // the scoped query. The set_config and this read share one db.transaction,
     // which a transaction pooler pins to a single backend — so a mismatch here
@@ -662,6 +692,14 @@ async function finalizeSessionActivityGate(
   await db.execute(
     sql`set constraints sessions_activity_insert_commit_guard, sessions_activity_update_commit_guard immediate`,
   );
+  // A restored activity scope can be followed by another workspace scope, or
+  // by a SECURITY DEFINER lifecycle that opens and finalizes its own gate in
+  // the same outer transaction. Keep the guards deferred after proving this
+  // scope's final state so those later writes reach their own finalizer instead
+  // of firing the commit guard at the first session update.
+  await db.execute(
+    sql`set constraints sessions_activity_insert_commit_guard, sessions_activity_update_commit_guard deferred`,
+  );
 }
 
 /**
@@ -674,6 +712,7 @@ export async function withSessionActivityRlsContext<T>(
   context: RlsContext & { workspaceId: string },
   fn: (db: SessionActivityDatabase) => Promise<T>,
   transactionConfig?: PgTransactionConfig,
+  fenceMode: "shared" | "none" = "shared",
 ): Promise<T> {
   await assertSessionActivityGateEntry(db);
   return await withRlsContext(
@@ -692,6 +731,7 @@ export async function withSessionActivityRlsContext<T>(
       return value;
     },
     transactionConfig,
+    fenceMode,
   );
 }
 
@@ -709,6 +749,47 @@ export async function withWorkspaceSessionActivityRls<T>(
   );
 }
 
+/**
+ * Run one of several ordered workspace activity scopes inside a caller-owned
+ * transaction. Each scope is fully finalized before restoring the caller's
+ * gate GUCs, so the next workspace can reuse the same outer transaction.
+ */
+export async function withRestoredSessionActivityRlsContext<T>(
+  db: Database,
+  context: RlsContext & { workspaceId: string },
+  fn: (db: SessionActivityDatabase) => Promise<T>,
+): Promise<T> {
+  if (!isTransactionHandle(db)) {
+    throw new Error("Sequential workspace activity scopes require a caller-owned transaction");
+  }
+  const [prior] = await rawRows<{ state: string; workspace_id: string }>(
+    db,
+    sql`select
+      coalesce(current_setting('opengeni.session_activity_gate_state', true), '') as state,
+      coalesce(
+        current_setting('opengeni.session_activity_gate_workspace_id', true), ''
+      ) as workspace_id`,
+  );
+  try {
+    return await withRlsContext(db, context, async (scopedDb) => {
+      const gate = await beginSessionActivityGate(scopedDb, context.workspaceId);
+      if (!gate.owner) {
+        throw new Error("Sequential workspace activity scope unexpectedly reused an open gate");
+      }
+      const value = await fn(gate.db);
+      await assertRlsContextApplied(gate.db, context);
+      await finalizeSessionActivityGate(gate.db, context.workspaceId);
+      return value;
+    });
+  } finally {
+    await db.execute(sql`select
+      set_config('opengeni.session_activity_gate_state', ${prior?.state ?? ""}, true),
+      set_config(
+        'opengeni.session_activity_gate_workspace_id', ${prior?.workspace_id ?? ""}, true
+      )`);
+  }
+}
+
 /**
  * Open one nested savepoint without losing the gate brand. Drizzle correctly
  * preserves the backend-local gate GUCs, but its structural transaction type
@@ -765,6 +846,7 @@ export async function withWorkspaceSubjectRls<T>(
   subjectId: string,
   fn: (db: Database) => Promise<T>,
   transactionConfig?: PgTransactionConfig,
+  sessionTenancyFence: "shared" | "none" = "shared",
 ): Promise<T> {
   if (!subjectId.trim()) {
     throw new Error("withWorkspaceSubjectRls: a non-empty subjectId is required");
@@ -778,6 +860,7 @@ export async function withWorkspaceSubjectRls<T>(
       return await fn(scopedDb);
     },
     transactionConfig,
+    sessionTenancyFence,
   );
 }
 
@@ -787,6 +870,7 @@ export async function withWorkspaceSubjectSessionActivityRls<T>(
   subjectId: string,
   fn: (db: SessionActivityDatabase) => Promise<T>,
   transactionConfig?: PgTransactionConfig,
+  fenceMode: "shared" | "none" = "shared",
 ): Promise<T> {
   if (!subjectId.trim()) {
     throw new Error("withWorkspaceSubjectSessionActivityRls: a non-empty subjectId is required");
@@ -800,6 +884,7 @@ export async function withWorkspaceSubjectSessionActivityRls<T>(
       return await fn(scopedDb);
     },
     transactionConfig,
+    fenceMode,
   );
 }
 

package/src/editable-artifacts-schema.ts

@@ -272,7 +272,6 @@ export const editableArtifactTransactions = pgTable(
         and ${table.intentHash} = ${table.requestHash}
         and ${table.intentEnvelopeVersion} = 1
         and ${table.intentProtocolVersion} = 1
-        and ${table.commandProtocolVersion} > 0
         and ${table.intentByteSize} between 8 and 5242880
         and octet_length(${table.intentBytes}) = ${table.intentByteSize}
         and substring(${table.intentBytes} from 1 for 8) = convert_to('OGATX001', 'UTF8')
@@ -288,6 +287,8 @@ export const editableArtifactTransactions = pgTable(
           'sha256:' || encode(sha256(${table.committedTransactionBytes}), 'hex')
         and (
           (${table.modality} = 'spreadsheet'
+            and ${table.modelSchemaVersion} = 2
+            and ${table.commandProtocolVersion} = 2
             and ${table.operationCount} between 1 and 4096
             and ${table.sequenceEnd} = ${table.sequenceStart} + ${table.operationCount} - 1
             and jsonb_typeof(${table.causalBase}) = 'array'
@@ -296,7 +297,7 @@ export const editableArtifactTransactions = pgTable(
             and jsonb_typeof(${table.selectiveUndoTargets}) = 'array'
             and jsonb_typeof(${table.operationIds}) = 'array'
             and jsonb_array_length(${table.operationIds}) = ${table.operationCount}
-            and ${table.operationProtocolVersion} = 1
+            and ${table.operationProtocolVersion} = 2
             and ${table.commitProtocolVersion} is null
             and ${table.priorNativeRevision} is null
             and ${table.nativeRevision} is null
@@ -304,9 +305,11 @@ export const editableArtifactTransactions = pgTable(
             and ${table.nativeReceiptByteSize} is null
             and ${table.nativeReceiptHash} is null
             and ${table.nativeReceiptBytes} is null
-            and substring(${table.committedTransactionBytes} from 1 for 8) = convert_to('OGACO001', 'UTF8'))
+            and substring(${table.committedTransactionBytes} from 1 for 8) = convert_to('OGACO002', 'UTF8'))
           or
           (${table.modality} in ('document', 'presentation')
+            and ${table.modelSchemaVersion} = 1
+            and ${table.commandProtocolVersion} = 1
             and ${table.sequenceEnd} = ${table.sequenceStart}
             and ${table.causalBase} is null
             and ${table.resolvedCausalBase} is null
@@ -635,11 +638,13 @@ export const editableArtifactSnapshots = pgTable(
       sql`${stableIdSql(table.id)} and ${sha256Sql(table.contentHash)} and ${sha256Sql(table.stateHash)}
         and (
           (${table.modality} = 'spreadsheet'
+            and ${table.modelSchemaVersion} = 2
             and jsonb_typeof(${table.coveredCausalFrontier}) = 'array'
-            and ${table.operationProtocolVersion} = 1
-            and ${table.crdtStateVersion} > 0
+            and ${table.operationProtocolVersion} = 2
+            and ${table.crdtStateVersion} = 2
             and ${table.nativeRevision} is null)
           or (${table.modality} in ('document', 'presentation')
+            and ${table.modelSchemaVersion} = 1
             and ${table.coveredCausalFrontier} is null
             and ${table.operationProtocolVersion} is null
             and ${table.crdtStateVersion} is null

package/src/editable-artifacts.ts

@@ -11,9 +11,11 @@ import {
   decodeEditableArtifactSerializedCommit,
 } from "@opengeni/contracts/editable-artifact-serialized-commit";
 import {
+  EDITABLE_ARTIFACT_INTENT_PROTOCOL_VERSION,
   EDITABLE_ARTIFACT_KERNEL_VERSION_MAX_BYTES,
   EDITABLE_ARTIFACT_PRODUCT_MAX_SNAPSHOT_BYTES,
 } from "@opengeni/contracts/editable-artifacts";
+import { EDITABLE_ARTIFACT_LIVE_WIRE_VERSION } from "@opengeni/contracts/editable-artifact-versions";
 import { sql } from "drizzle-orm";
 
 import { rawRows, type Database, withRlsContext } from "./database";
@@ -331,7 +333,7 @@ export type PersistedEditableArtifactLiveHead =
 
 export type PersistedEditableArtifactLiveResume =
   | Readonly<{
-      modality?: "spreadsheet";
+      modality: "spreadsheet";
       localCursor: number | null;
       localStateHash: string | null;
       localCausalFrontier: PersistedEditableArtifactCausalFrontier;
@@ -354,6 +356,7 @@ export type PersistedEditableArtifactLiveSnapshot =
       causalFrontier: PersistedEditableArtifactCausalFrontier;
       digest: string;
       operationProtocolVersion: number;
+      snapshotVersion: number;
       kernelVersion: string;
       modelSchemaVersion: number;
       bytes: Uint8Array;
@@ -1841,11 +1844,9 @@ export class PostgresEditableArtifactLiveReadStore {
     scope: PersistedEditableArtifactScope;
     artifactId: string;
     resume: PersistedEditableArtifactLiveResume;
-    protocolVersion: number;
   }): Promise<PersistedEditableArtifactLiveBootstrap> {
     const scope = validateScope(input.scope);
     const artifactId = validateStableId(input.artifactId, "artifact id");
-    validateInteger(input.protocolVersion, "live protocol version", 1);
     const resume = validateLiveResume(input.resume);
     const authority = await withRlsContext(
       this.db,
@@ -2103,6 +2104,7 @@ export class PostgresEditableArtifactLiveReadStore {
           modality: snapshot.modality,
           causalFrontier: snapshot.coveredCausalFrontier,
           operationProtocolVersion: snapshot.operationProtocolVersion,
+          snapshotVersion: snapshot.crdtStateVersion,
         })
       : Object.freeze({
           ...common,
@@ -2872,7 +2874,7 @@ function validateLiveResume(
   input: PersistedEditableArtifactLiveResume,
 ): NormalizedPersistedEditableArtifactLiveResume {
   if (!isPlainRecord(input)) throw new TypeError("Editable artifact live resume is invalid");
-  const modality = input.modality ?? "spreadsheet";
+  const modality = input.modality;
   if (modality !== "spreadsheet" && modality !== "document" && modality !== "presentation") {
     throw new TypeError("Editable artifact live resume modality is invalid");
   }
@@ -3443,7 +3445,7 @@ function committedTransactionFromRow(
     } catch (error) {
       throw new EditableArtifactPersistenceError(
         "corrupt_history",
-        "Stored canonical committed transaction is not a valid OGACO001 envelope",
+        "Stored canonical committed transaction is not a valid OGACO002 envelope",
         { cause: error },
       );
     }
@@ -4144,7 +4146,7 @@ function validateCommittedTransactionProjection(
     try {
       summary = decodeCommittedTransactionSummary(transaction.committedTransactionBytes);
     } catch (error) {
-      throw new TypeError("Canonical committed transaction is not a valid OGACO001 envelope", {
+      throw new TypeError("Canonical committed transaction is not a valid OGACO002 envelope", {
         cause: error,
       });
     }
@@ -4159,7 +4161,7 @@ function validateCommittedTransactionProjection(
       !sameFrontier(summary.resolvedCausalBase, resolvedCausalBase) ||
       !sameFrontier(summary.resultingCausalFrontier, resultingCausalFrontier)
     ) {
-      throw new TypeError("Canonical OGACO001 bytes disagree with their durable projection");
+      throw new TypeError("Canonical OGACO002 bytes disagree with their durable projection");
     }
     return;
   }
@@ -4681,6 +4683,10 @@ function validateLiveTicketRecord(
     throw new TypeError("Live ticket lifetime must be 1-60 seconds");
   }
   const modality = validateLiveTicketModality(input.modality);
+  const protocolVersion = validateInteger(input.protocolVersion, "live protocol version", 1);
+  if (protocolVersion !== EDITABLE_ARTIFACT_LIVE_WIRE_VERSION) {
+    throw new TypeError("Live ticket protocol version is unsupported");
+  }
   return Object.freeze({
     tokenDigest: validateHash(input.tokenDigest, "live ticket digest"),
     scope: validateScope(input.scope),
@@ -4688,7 +4694,7 @@ function validateLiveTicketRecord(
     modality,
     actor: validateLiveTicketActor(input.actor),
     allowEdit: validateBoolean(input.allowEdit, "live ticket allowEdit"),
-    protocolVersion: validateInteger(input.protocolVersion, "live protocol version", 1),
+    protocolVersion,
     issuedAt,
     expiresAt,
   });
@@ -4984,9 +4990,13 @@ function validateCanonicalIntentBytes(value: unknown, requestHashInput: unknown)
   return bytes;
 }
 
-function validateIntentProtocolVersion(value: unknown): 1 {
-  if (value !== 1) throw new TypeError("Intent protocol version must be 1 for OGATX001");
-  return 1;
+function validateIntentProtocolVersion(
+  value: unknown,
+): typeof EDITABLE_ARTIFACT_INTENT_PROTOCOL_VERSION {
+  if (value !== EDITABLE_ARTIFACT_INTENT_PROTOCOL_VERSION) {
+    throw new TypeError("Intent protocol version is unsupported for current OGATX001");
+  }
+  return EDITABLE_ARTIFACT_INTENT_PROTOCOL_VERSION;
 }
 
 function validateClientTransactionId(value: unknown): string {

package/src/governed-learning-activation-schema.ts

@@ -0,0 +1,121 @@
+import {
+  bigint,
+  check,
+  index,
+  pgTable,
+  text,
+  timestamp,
+  uniqueIndex,
+  uuid,
+} from "drizzle-orm/pg-core";
+import { sql } from "drizzle-orm";
+
+/** Migration 0269 owns exact foreign keys, RLS, immutability and lifecycle checks. */
+export const governedLearningActivationReceipts = pgTable(
+  "governed_learning_activation_receipts",
+  {
+    id: uuid("id").primaryKey().defaultRandom(),
+    accountId: uuid("account_id").notNull(),
+    workspaceId: uuid("workspace_id").notNull(),
+    operationId: uuid("operation_id").notNull(),
+    inputHash: text("input_hash").notNull(),
+    decisionReceiptId: uuid("decision_receipt_id").notNull(),
+    initiatingHumanSubjectId: text("initiating_human_subject_id").notNull(),
+    serviceActorSubjectId: text("service_actor_subject_id").notNull(),
+    policyRevisionId: uuid("policy_revision_id").notNull(),
+    policyHash: text("policy_hash").notNull(),
+    policyActivationVersion: bigint("policy_activation_version", { mode: "number" }).notNull(),
+    sourceKind: text("source_kind").notNull(),
+    sourceId: uuid("source_id").notNull(),
+    sourceAuthorityHash: text("source_authority_hash").notNull(),
+    proposalId: uuid("proposal_id").notNull(),
+    claimId: uuid("claim_id").notNull(),
+    evidenceId: uuid("evidence_id").notNull(),
+    knowledgePreviousReviewId: uuid("knowledge_previous_review_id").notNull(),
+    knowledgePreviousReviewRevision: bigint("knowledge_previous_review_revision", {
+      mode: "number",
+    }).notNull(),
+    knowledgeApprovalReviewId: uuid("knowledge_approval_review_id").notNull(),
+    knowledgeApprovalReviewRevision: bigint("knowledge_approval_review_revision", {
+      mode: "number",
+    }).notNull(),
+    knowledgeApprovalInputHash: text("knowledge_approval_input_hash").notNull(),
+    destination: text("destination").notNull(),
+    destinationProposalId: uuid("destination_proposal_id").notNull(),
+    destinationRevisionId: uuid("destination_revision_id").notNull(),
+    destinationOldRevisionId: uuid("destination_old_revision_id"),
+    destinationOldContentHash: text("destination_old_content_hash"),
+    destinationOldVersion: bigint("destination_old_version", { mode: "number" }).notNull(),
+    destinationNewContentHash: text("destination_new_content_hash").notNull(),
+    destinationNewVersion: bigint("destination_new_version", { mode: "number" }).notNull(),
+    destinationEventId: uuid("destination_event_id").notNull(),
+    // Added by migration 0272 alongside human-confirmed activation; the schema
+    // file had not caught up.
+    authorityKind: text("authority_kind").notNull().default("automatic"),
+    humanInputRequestId: uuid("human_input_request_id"),
+    effectiveAt: timestamp("effective_at", { withTimezone: true }).notNull(),
+    createdAt: timestamp("created_at", { withTimezone: true }).notNull().defaultNow(),
+  },
+  (table) => ({
+    operation: uniqueIndex("governed_learning_activation_receipts_operation_uq").on(
+      table.workspaceId,
+      table.operationId,
+    ),
+    decision: uniqueIndex("governed_learning_activation_receipts_decision_uq").on(
+      table.decisionReceiptId,
+    ),
+    timeline: index("governed_learning_activation_receipts_workspace_time_idx").on(
+      table.workspaceId,
+      table.createdAt,
+      table.id,
+    ),
+    hash: check(
+      "governed_learning_activation_receipts_hash_chk",
+      sql`${table.inputHash} ~ '^[0-9a-f]{64}$'`,
+    ),
+  }),
+);
+
+export const governedLearningActivationUndoReceipts = pgTable(
+  "governed_learning_activation_undo_receipts",
+  {
+    id: uuid("id").primaryKey().defaultRandom(),
+    accountId: uuid("account_id").notNull(),
+    workspaceId: uuid("workspace_id").notNull(),
+    operationId: uuid("operation_id").notNull(),
+    inputHash: text("input_hash").notNull(),
+    activationReceiptId: uuid("activation_receipt_id").notNull(),
+    initiatingHumanSubjectId: text("initiating_human_subject_id").notNull(),
+    serviceActorSubjectId: text("service_actor_subject_id").notNull(),
+    destination: text("destination").notNull(),
+    knowledgeApprovalReviewId: uuid("knowledge_approval_review_id").notNull(),
+    knowledgeRevocationReviewId: uuid("knowledge_revocation_review_id").notNull(),
+    knowledgeRevocationReviewRevision: bigint("knowledge_revocation_review_revision", {
+      mode: "number",
+    }).notNull(),
+    knowledgeRevocationInputHash: text("knowledge_revocation_input_hash").notNull(),
+    destinationActivatedRevisionId: uuid("destination_activated_revision_id").notNull(),
+    destinationRestoredRevisionId: uuid("destination_restored_revision_id"),
+    destinationActivatedContentHash: text("destination_activated_content_hash").notNull(),
+    destinationRestoredContentHash: text("destination_restored_content_hash"),
+    destinationOldVersion: bigint("destination_old_version", { mode: "number" }).notNull(),
+    destinationNewVersion: bigint("destination_new_version", { mode: "number" }).notNull(),
+    destinationEventId: uuid("destination_event_id").notNull(),
+    effectiveAt: timestamp("effective_at", { withTimezone: true }).notNull(),
+    createdAt: timestamp("created_at", { withTimezone: true }).notNull().defaultNow(),
+  },
+  (table) => ({
+    operation: uniqueIndex("governed_learning_activation_undo_receipts_operation_uq").on(
+      table.workspaceId,
+      table.operationId,
+    ),
+    activation: uniqueIndex("governed_learning_activation_undo_receipts_activation_uq").on(
+      table.activationReceiptId,
+    ),
+    timeline: index("governed_learning_activation_undo_receipts_workspace_time_idx").on(
+      table.workspaceId,
+      table.createdAt,
+      table.id,
+    ),
+  }),
+);