@opengeni/db 1.0.1 → 3.2.0-canary.0

package/src/slack-task-policy-schema.ts

@@ -114,6 +114,11 @@ export const slackSharedTaskOrigins = pgTable(
     sourceThreadTs: text("source_thread_ts").notNull(),
     initiatingSlackUserId: text("initiating_slack_user_id").notNull(),
     policyRevisionId: uuid("policy_revision_id").notNull(),
+    // The Slack task policy is a home fact and the interaction is a routed one,
+    // so the frozen revision carries its own tenancy pair. Null on rows written
+    // before Slack workspace routing, where the two were always equal.
+    policyAccountId: uuid("policy_account_id"),
+    policyWorkspaceId: uuid("policy_workspace_id"),
     policyHash: text("policy_hash").notNull(),
     policyActivationVersion: bigint("policy_activation_version", { mode: "number" }).notNull(),
     publicationMode: text("publication_mode")

package/src/slack-task-policy.ts

@@ -30,6 +30,14 @@ export type SlackSharedTaskOrigin = {
   sourceThreadTs: string;
   initiatingSlackUserId: string;
   policyRevisionId: string;
+  /**
+   * Home tenancy of the frozen policy revision. The row's own
+   * `accountId`/`workspaceId` are the routed task's, which is a different
+   * workspace once Slack workspace routing is on. Null on rows written before
+   * routing existed, where the two were always equal.
+   */
+  policyAccountId: string | null;
+  policyWorkspaceId: string | null;
   policyHash: string;
   policyActivationVersion: number;
   publicationMode: "never" | "approval_required" | "allow";
@@ -310,6 +318,16 @@ export async function saveSlackSharedTaskOrigin(
       .limit(1);
     if (!existing) throw new Error("Slack shared-task origin conflict could not be resolved");
     for (const [key, value] of Object.entries(input)) {
+      // A row written before Slack workspace routing carries no policy tenancy
+      // and implied its own, because the two could not differ then. A replay
+      // from a new image supplies it, which is not a change of evidence and
+      // must not be reported as one.
+      if (
+        (key === "policyAccountId" || key === "policyWorkspaceId") &&
+        existing[key as keyof OriginRow] === null
+      ) {
+        continue;
+      }
       if (existing[key as keyof OriginRow] !== value) {
         throw new SlackTaskPolicyInvalidOperationError(
           "Slack shared-task origin identity conflicted with immutable evidence",

package/src/slack-user-link-access.ts

@@ -6,11 +6,13 @@ import {
   type SlackUserLinkAccessRequest,
   type SlackUserLinkAccessRequestStatus,
 } from "@opengeni/contracts";
-import { and, asc, eq, gt, inArray, ne } from "drizzle-orm";
+import { and, asc, eq, gt, inArray, ne, sql } from "drizzle-orm";
 
 import { type Database, withWorkspaceRls } from "./database";
+import { namedSubjectPersonalWorkspaceId } from "./slack-routing-personal-workspace";
 import { withLosslessContentWriteVersion } from "./lossless-json";
 import * as schema from "./schema";
+import { normalizeWorkspaceMembershipPermissions } from "./workspace-membership-permissions";
 
 type RequestRow = typeof schema.slackUserLinkAccessRequests.$inferSelect;
 type OperationKind = "request" | "cancel" | "approve" | "deny";
@@ -51,9 +53,45 @@ export type SlackUserLinkAccessMutationInput = {
   idempotencyKey: string;
 };
 
+/**
+ * The Slack team one access request was raised from.
+ *
+ * The public request shape deliberately omits it, but an approver has to
+ * resolve the installation binding to know where the identity link belongs, and
+ * for a routed request that is not the workspace being granted.
+ */
+export async function slackUserLinkAccessRequestTeam(
+  db: Database,
+  input: { workspaceId: string; requestId: string },
+): Promise<{ slackTeamId: string; connectionId: string } | null> {
+  return await withWorkspaceRls(db, input.workspaceId, async (scopedDb) => {
+    const [row] = await scopedDb
+      .select({
+        slackTeamId: schema.slackUserLinkAccessRequests.slackTeamId,
+        connectionId: schema.slackUserLinkAccessRequests.connectionId,
+      })
+      .from(schema.slackUserLinkAccessRequests)
+      .where(
+        and(
+          eq(schema.slackUserLinkAccessRequests.workspaceId, input.workspaceId),
+          eq(schema.slackUserLinkAccessRequests.id, input.requestId),
+        ),
+      )
+      .limit(1);
+    return row ?? null;
+  });
+}
+
+/**
+ * The tenancy an identity link belongs to. See `withSlackIdentityHomeScope`.
+ */
+export type SlackIdentityHome = { accountId: string; workspaceId: string };
+
 export type ApproveSlackUserLinkAccessInput = SlackUserLinkAccessMutationInput & {
   role?: string;
   permissions: Permission[];
+  /** The installation's tenancy, when it differs from the routed request's. */
+  identityHome?: SlackIdentityHome;
 };
 
 const activeStatuses: SlackUserLinkAccessRequestStatus[] = ["prepared", "pending"];
@@ -154,7 +192,13 @@ export async function prepareSlackUserLinkAccessRequest(
 
 export async function getSlackUserLinkAccessRequestForSubject(
   db: Database,
-  input: { workspaceId: string; requestId: string; subjectId: string },
+  input: {
+    workspaceId: string;
+    requestId: string;
+    subjectId: string;
+    /** The installation's tenancy, when it differs from the routed request's. */
+    identityHome?: SlackIdentityHome;
+  },
   now = new Date(),
 ): Promise<SlackUserLinkAccessRequest | null> {
   return await withWorkspaceRls(db, input.workspaceId, async (scopedDb) => {
@@ -318,7 +362,10 @@ export async function approveSlackUserLinkAccessRequest(
         });
       const membership = await membershipAllowsSlackLink(database, row);
       if (!membership) throw new Error("Slack access approval did not create the required grant");
-      await upsertSlackIdentityLink(database, row, input.actorSubjectId, now);
+      await withSlackIdentityHomeScope(database, row, input.identityHome, async () => {
+        await assertSlackIdentityAvailable(database, row);
+        await upsertSlackIdentityLink(database, row, input.actorSubjectId, now, input.identityHome);
+      });
       const [updated] = await database
         .update(schema.slackUserLinkAccessRequests)
         .set({
@@ -362,7 +409,13 @@ export async function approveSlackUserLinkAccessRequest(
  */
 export async function completeSlackUserLinkAccessIfGranted(
   db: Database,
-  input: { workspaceId: string; requestId: string; subjectId: string },
+  input: {
+    workspaceId: string;
+    requestId: string;
+    subjectId: string;
+    /** The installation's tenancy, when it differs from the routed request's. */
+    identityHome?: SlackIdentityHome;
+  },
   now = new Date(),
 ): Promise<SlackUserLinkAccessRequest | null> {
   return await withWorkspaceRls(db, input.workspaceId, async (scopedDb) => {
@@ -388,8 +441,10 @@ export async function completeSlackUserLinkAccessIfGranted(
       if (!(await membershipAllowsSlackLink(database, row))) {
         return mapRequest(row);
       }
-      await assertSlackIdentityAvailable(database, row);
-      await upsertSlackIdentityLink(database, row, input.subjectId, now);
+      await withSlackIdentityHomeScope(database, row, input.identityHome, async () => {
+        await assertSlackIdentityAvailable(database, row);
+        await upsertSlackIdentityLink(database, row, input.subjectId, now, input.identityHome);
+      });
       const [updated] = await tx
         .update(schema.slackUserLinkAccessRequests)
         .set({
@@ -563,7 +618,21 @@ async function membershipAllowsSlackLink(database: Database, row: RequestRow) {
       ),
     )
     .limit(1);
-  const permissions = membership?.permissions ?? [];
+  if (workspaceMembershipPermissionsAllowSlackLink(membership?.permissions)) return true;
+  // A managed human's own personal workspace deliberately has no
+  // `workspace_memberships` row, so a bare membership join denies its owner.
+  // Once a Slack direct message can land there, that would tell people to
+  // request access to their own workspace. The pointer is DERIVED from an
+  // active organization membership; it is never accepted from the request row.
+  const personalWorkspaceId = await namedSubjectPersonalWorkspaceId(database, {
+    accountId: row.accountId,
+    subjectId: row.subjectId,
+  });
+  return personalWorkspaceId === row.workspaceId;
+}
+
+export function workspaceMembershipPermissionsAllowSlackLink(value: unknown): boolean {
+  const permissions = normalizeWorkspaceMembershipPermissions(value);
   return permissions.includes("sessions:create") || permissions.includes("workspace:admin");
 }
 
@@ -584,17 +653,75 @@ async function assertSlackIdentityAvailable(database: Database, row: RequestRow)
   }
 }
 
+/**
+ * The tenancy an identity link belongs to.
+ *
+ * `slack_bot_user_links` is unique on `(connection_id, slack_user_id)` globally
+ * but RLS-visible only under ONE workspace, and the Slack pump reads it under
+ * the installation's. A request for a ROUTED workspace runs under that routed
+ * scope, so writing the link there would file it where the pump cannot see it,
+ * and reading it there is blind to the row that already exists at home. Both the
+ * availability check and the write therefore take the installation's tenancy
+ * explicitly, and fall back to the request row's when a caller has none, which
+ * is exactly the pre-routing behaviour.
+ */
+function identityHomeFor(row: RequestRow, home: SlackIdentityHome | undefined): SlackIdentityHome {
+  return home ?? { accountId: row.accountId, workspaceId: row.workspaceId };
+}
+
+/**
+ * Run the identity-link statements under the installation's own tenancy.
+ *
+ * The surrounding transaction is scoped to the request's workspace, which for a
+ * routed request is NOT where the link lives, and it must stay one transaction:
+ * an approval that granted membership without linking the identity, or the
+ * reverse, would be worse than either. So the tenant GUCs are swapped for
+ * exactly these statements and restored, rather than opening a second
+ * transaction. Restoring is not optional: everything after this call still
+ * belongs to the request's workspace.
+ */
+async function withSlackIdentityHomeScope<T>(
+  database: Database,
+  row: RequestRow,
+  home: SlackIdentityHome | undefined,
+  fn: () => Promise<T>,
+): Promise<T> {
+  const identity = identityHomeFor(row, home);
+  if (identity.accountId === row.accountId && identity.workspaceId === row.workspaceId) {
+    return await fn();
+  }
+  await database.execute(
+    sql`select set_config('opengeni.account_id', ${identity.accountId}, true),
+               set_config('opengeni.workspace_id', ${identity.workspaceId}, true)`,
+  );
+  try {
+    return await fn();
+  } finally {
+    // A failed statement can leave the transaction aborted and unwinding to
+    // rollback, so preserve the original diagnostic rather than replacing it
+    // with the restore's own error.
+    await database
+      .execute(
+        sql`select set_config('opengeni.account_id', ${row.accountId}, true),
+                   set_config('opengeni.workspace_id', ${row.workspaceId}, true)`,
+      )
+      .catch(() => undefined);
+  }
+}
+
 async function upsertSlackIdentityLink(
   database: Database,
   row: RequestRow,
   actorSubjectId: string,
   now: Date,
+  home?: SlackIdentityHome,
 ) {
+  const identity = identityHomeFor(row, home);
   const [created] = await database
     .insert(schema.slackBotUserLinks)
     .values({
-      accountId: row.accountId,
-      workspaceId: row.workspaceId,
+      accountId: identity.accountId,
+      workspaceId: identity.workspaceId,
       connectionId: row.connectionId,
       slackTeamId: row.slackTeamId,
       slackUserId: row.slackUserId,
@@ -624,8 +751,8 @@ async function upsertSlackIdentityLink(
   await database
     .update(schema.slackBotUserLinks)
     .set({
-      accountId: row.accountId,
-      workspaceId: row.workspaceId,
+      accountId: identity.accountId,
+      workspaceId: identity.workspaceId,
       slackTeamId: row.slackTeamId,
       linkedBySubjectId: actorSubjectId,
       updatedAt: now,

package/src/task-notes-schema.ts

@@ -133,3 +133,77 @@ export const taskNoteWriteCapabilities = pgTable(
     ),
   }),
 );
+
+// Transaction-local, owner-only admission for the single Task-note evidence
+// insert materialized by a governed promotion. Migration 0260 owns its RLS,
+// one-shot trigger consumption, and runtime-role revocation.
+export const taskNoteKnowledgePromotionCapabilities = pgTable(
+  "task_note_knowledge_promotion_capabilities",
+  {
+    backendPid: integer("backend_pid").notNull(),
+    transactionId: xid8("transaction_id").notNull(),
+    capabilityId: uuid("capability_id").notNull(),
+    accountId: uuid("account_id").notNull(),
+    workspaceId: uuid("workspace_id").notNull(),
+    noteId: uuid("note_id").notNull(),
+    rootSessionId: uuid("root_session_id").notNull(),
+    noteVersion: integer("note_version").notNull(),
+    noteTextHash: text("note_text_hash").notNull(),
+    evidenceOperationId: text("evidence_operation_id").notNull(),
+    claimOperationId: text("claim_operation_id").notNull(),
+    actorSubjectId: text("actor_subject_id").notNull(),
+    initiatingHumanSubjectId: text("initiating_human_subject_id").notNull(),
+    learningPolicySnapshotId: uuid("learning_policy_snapshot_id").notNull(),
+  },
+  (table) => ({
+    identity: uniqueIndex("task_note_knowledge_promotion_capabilities_identity_uq").on(
+      table.backendPid,
+      table.transactionId,
+      table.capabilityId,
+    ),
+  }),
+);
+
+// Immutable, content-free lineage for one atomic archive + replacement create.
+// Migration 0260 owns exact constraints, FORCE RLS, and lifecycle-only writes.
+export const taskNoteReplacementReceipts = pgTable(
+  "task_note_replacement_receipts",
+  {
+    id: uuid("id").primaryKey().defaultRandom(),
+    accountId: uuid("account_id").notNull(),
+    workspaceId: uuid("workspace_id").notNull(),
+    rootSessionId: uuid("root_session_id").notNull(),
+    operationId: uuid("operation_id").notNull(),
+    inputHash: text("input_hash").notNull(),
+    replacedNoteId: uuid("replaced_note_id").notNull(),
+    replacedNoteVersion: integer("replaced_note_version").notNull(),
+    replacementNoteId: uuid("replacement_note_id").notNull(),
+    replacementNoteVersion: integer("replacement_note_version").notNull(),
+    archiveOperationId: uuid("archive_operation_id").notNull(),
+    createOperationId: uuid("create_operation_id").notNull(),
+    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) => ({
+    workspaceOperation: uniqueIndex("task_note_replacement_receipts_workspace_operation_uq").on(
+      table.workspaceId,
+      table.operationId,
+    ),
+    workspaceReplacement: uniqueIndex("task_note_replacement_receipts_workspace_replacement_uq").on(
+      table.workspaceId,
+      table.replacementNoteId,
+    ),
+    rootTimeline: index("task_note_replacement_receipts_root_timeline_idx").on(
+      table.workspaceId,
+      table.rootSessionId,
+      table.createdAt,
+      table.id,
+    ),
+  }),
+);

package/src/task-notes.ts

@@ -1,14 +1,17 @@
 import {
   TASK_NOTE_LIST_DEFAULT_LIMIT,
   TASK_NOTE_LIST_MAX_LIMIT,
+  TASK_NOTE_MAX_LIFETIME_DAYS,
   TaskNote,
   TaskNoteKind,
   TaskNoteListResponse,
   TaskNoteMutationResult,
   TaskNoteReason,
+  TaskNoteReplacementResult,
   TaskNoteText,
   type TaskNoteKind as TaskNoteKindType,
 } from "@opengeni/contracts";
+import { createHash } from "node:crypto";
 import { sql } from "drizzle-orm";
 import type { Database } from "./database";
 import { rawRows, withRlsContext } from "./database";
@@ -36,6 +39,16 @@ export type ArchiveTaskNoteInput = TaskNoteAttemptClaims & {
   reason: string;
 };
 
+export type ReplaceTaskNoteInput = TaskNoteAttemptClaims & {
+  operationId: string;
+  replacedNoteId: string;
+  expectedReplacedVersion: number;
+  replacementKind: TaskNoteKindType;
+  replacementText: string;
+  replacementExpiresInDays: number;
+  reason: string;
+};
+
 export type ListTaskNotesInput = TaskNoteAttemptClaims & {
   includeArchived?: boolean;
   limit?: number;
@@ -58,6 +71,27 @@ type TaskNoteRow = {
   replayed?: boolean;
 };
 
+type TaskNoteReplacementRow = {
+  operation_id: string;
+  input_hash: string;
+  replaced_note_id: string;
+  replaced_note_version: number;
+  replacement_note_id: string;
+  root_session_id: string;
+  replacement_kind: string;
+  replacement_text: string;
+  replacement_status: string;
+  replacement_version: number;
+  replacement_expires_at: Date | string;
+  replacement_created_at: Date | string;
+  replacement_updated_at: Date | string;
+  replacement_archived_at: Date | string | null;
+  replacement_actor_kind: string;
+  replacement_source_session_id: string;
+  replacement_source_turn_id: string;
+  replayed: boolean;
+};
+
 function iso(value: Date | string): string {
   return (value instanceof Date ? value : new Date(value)).toISOString();
 }
@@ -88,6 +122,20 @@ function assertAttemptClaims(claims: TaskNoteAttemptClaims): void {
   }
 }
 
+function derivedTaskNoteOperationId(operationId: string, label: "archive" | "create"): string {
+  const bytes = Buffer.from(
+    createHash("sha256")
+      .update(`task-note-replacement:v1:${operationId}:${label}`, "utf8")
+      .digest("hex")
+      .slice(0, 32),
+    "hex",
+  );
+  bytes[6] = (bytes[6]! & 0x0f) | 0x50;
+  bytes[8] = (bytes[8]! & 0x3f) | 0x80;
+  const hex = bytes.toString("hex");
+  return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
+}
+
 export async function createTaskNote(db: Database, input: CreateTaskNoteInput) {
   assertAttemptClaims(input);
   TaskNoteKind.parse(input.kind);
@@ -95,9 +143,9 @@ export async function createTaskNote(db: Database, input: CreateTaskNoteInput) {
   if (
     !Number.isSafeInteger(input.expiresInDays) ||
     input.expiresInDays < 1 ||
-    input.expiresInDays > 30
+    input.expiresInDays > TASK_NOTE_MAX_LIFETIME_DAYS
   ) {
-    throw new Error("Task note expiry must be 1-30 whole days");
+    throw new Error(`Task note expiry must be 1-${TASK_NOTE_MAX_LIFETIME_DAYS} whole days`);
   }
   const rows = await withRlsContext(
     db,
@@ -150,6 +198,80 @@ export async function archiveTaskNote(db: Database, input: ArchiveTaskNoteInput)
   return TaskNoteMutationResult.parse({ note: noteFromRow(rows[0]!), replayed: rows[0]!.replayed });
 }
 
+/**
+ * Atomically archive one exact active note and create its immutable replacement.
+ * Exact retries return the original linked receipt; changed input or authority fails.
+ */
+export async function replaceTaskNote(db: Database, input: ReplaceTaskNoteInput) {
+  assertAttemptClaims(input);
+  TaskNoteKind.parse(input.replacementKind);
+  TaskNoteText.parse(input.replacementText);
+  TaskNoteReason.parse(input.reason);
+  if (
+    input.expectedReplacedVersion !== 1 ||
+    !Number.isSafeInteger(input.replacementExpiresInDays) ||
+    input.replacementExpiresInDays < 1 ||
+    input.replacementExpiresInDays > TASK_NOTE_MAX_LIFETIME_DAYS
+  ) {
+    throw new Error(
+      `Task-note replacement requires version 1 and a 1-${TASK_NOTE_MAX_LIFETIME_DAYS} day expiry`,
+    );
+  }
+  const archiveOperationId = derivedTaskNoteOperationId(input.operationId, "archive");
+  const createOperationId = derivedTaskNoteOperationId(input.operationId, "create");
+  const rows = await withRlsContext(
+    db,
+    { accountId: input.accountId, workspaceId: input.workspaceId },
+    async (tx) =>
+      await rawRows<TaskNoteReplacementRow>(
+        tx,
+        sql`SELECT * FROM replace_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,
+          ${archiveOperationId}::uuid,
+          ${createOperationId}::uuid,
+          ${input.replacedNoteId}::uuid,
+          ${input.expectedReplacedVersion}::integer,
+          ${input.replacementKind}::text,
+          ${input.replacementText}::text,
+          ${input.replacementExpiresInDays}::integer,
+          ${input.reason}::text
+        )`,
+      ),
+  );
+  const row = rows[0];
+  if (!row || rows.length !== 1) throw new Error("Task-note replacement returned no receipt");
+  return TaskNoteReplacementResult.parse({
+    operationId: row.operation_id,
+    inputHash: row.input_hash,
+    replaces: {
+      noteId: row.replaced_note_id,
+      archivedVersion: row.replaced_note_version,
+    },
+    replacement: noteFromRow({
+      note_id: row.replacement_note_id,
+      root_session_id: row.root_session_id,
+      kind: row.replacement_kind,
+      note_text: row.replacement_text,
+      status: row.replacement_status,
+      version: row.replacement_version,
+      expires_at: row.replacement_expires_at,
+      created_at: row.replacement_created_at,
+      updated_at: row.replacement_updated_at,
+      archived_at: row.replacement_archived_at,
+      actor_kind: row.replacement_actor_kind,
+      source_session_id: row.replacement_source_session_id,
+      source_turn_id: row.replacement_source_turn_id,
+    }),
+    replayed: row.replayed,
+  });
+}
+
 export async function listTaskNotes(db: Database, input: ListTaskNotesInput) {
   assertAttemptClaims(input);
   const limit = input.limit ?? TASK_NOTE_LIST_DEFAULT_LIMIT;

package/src/turn-initiator.ts

@@ -16,6 +16,8 @@ export const UNATTRIBUTED_LEGACY_INITIATOR: TurnInitiator = {
 export type FrozenTurnInitiator = {
   initiator: TurnInitiator;
   context: TurnInitiatorContext;
+  /** Exact causal human frozen only after the caller/attempt authority is validated. */
+  initiatingHumanSubjectId?: string | null;
 };
 
 const MAX_AGENT_PROVENANCE_HOPS = 32;
@@ -100,6 +102,7 @@ export async function frozenInitiatorForCommandActor(
         ...(actor.subjectLabel ? { label: actor.subjectLabel } : {}),
       },
       context: { ...(actor.context ?? {}) },
+      initiatingHumanSubjectId: null,
     };
   }
   if (actor.type !== "agent_attempt") {
@@ -110,6 +113,7 @@ export async function frozenInitiatorForCommandActor(
         ...(subjectLabel ? { label: subjectLabel } : {}),
       },
       context: {},
+      initiatingHumanSubjectId: actor.subjectId,
     };
   }
 
@@ -118,6 +122,7 @@ export async function frozenInitiatorForCommandActor(
       initiatorKind: schema.sessionTurns.initiatorKind,
       initiatorSubjectId: schema.sessionTurns.initiatorSubjectId,
       initiatorContext: schema.sessionTurns.initiatorContext,
+      initiatingHumanSubjectId: schema.sessionTurns.initiatingHumanSubjectId,
     })
     .from(schema.sessionTurns)
     .where(
@@ -151,5 +156,8 @@ export async function frozenInitiatorForCommandActor(
       via: clipped,
       ...(hops.length > clipped.length ? { viaTruncated: true } : {}),
     },
+    initiatingHumanSubjectId:
+      turn.initiatingHumanSubjectId ??
+      (turn.initiatorKind === "subject" ? turn.initiatorSubjectId : null),
   };
 }