@opengeni/db 0.36.1 → 3.1.0-canary.0

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),
   };
 }

package/src/user-resource-authority.ts

@@ -0,0 +1,377 @@
+import {
+  PersonalResourceAttachmentSummary,
+  type PersonalResourceAttachmentIntent,
+  USER_RESOURCE_ACTION_BY_KIND,
+  type UserResourceDelegation,
+  type UserResourceKind,
+} from "@opengeni/contracts";
+import { sql } from "drizzle-orm";
+import { rawRows, setSubjectRlsContext, withRlsContext, type Database } from "./database";
+import { nestedPostgresSqlState } from "./persistence-errors";
+
+export type UserResourceAuthorityGrant = {
+  grantId: string;
+  targetWorkspaceId: string;
+  targetSessionId: string | null;
+  action: (typeof USER_RESOURCE_ACTION_BY_KIND)[UserResourceKind];
+  mode: "once" | "session" | "always";
+  context: "user_private" | "workspace_shared";
+  authorityEpoch: number | null;
+  generation: number;
+  status: "active" | "consumed" | "revoked" | "expired";
+  expiresAt: string | null;
+  delegation: UserResourceDelegation;
+};
+
+export type UserResourceAuthoritySummary = {
+  authorityId: string;
+  resourceKind: UserResourceKind;
+  resourceId: string;
+  originWorkspaceId: string | null;
+  generation: number;
+  status: "active" | "retained" | "revoked";
+  grants: UserResourceAuthorityGrant[];
+};
+
+export type AcceptedTurnPersonalResourceAttachment = {
+  summary: PersonalResourceAttachmentSummary;
+  replay: boolean;
+};
+
+export class PersonalResourceAttachmentAcceptanceError extends Error {
+  readonly name = "PersonalResourceAttachmentAcceptanceError";
+  constructor(
+    readonly kind: "invalid" | "forbidden" | "conflict",
+    options?: ErrorOptions,
+  ) {
+    super(
+      kind === "invalid"
+        ? "The personal-resource attachment request is invalid"
+        : kind === "forbidden"
+          ? "The personal-resource attachment is not authorized"
+          : "The personal-resource attachment conflicts with accepted work",
+      options,
+    );
+  }
+}
+
+/**
+ * Issue and freeze the locked session's personal Variable Set/Rig/Connected
+ * Machine closure on
+ * one already-inserted logical turn. The caller owns the surrounding accepted-
+ * work transaction; this helper must never be called as a standalone grant
+ * mutation.
+ */
+export async function acceptTurnPersonalResourceAttachmentInTransaction(
+  db: Database,
+  input: {
+    accountId: string;
+    workspaceId: string;
+    sessionId: string;
+    turnId: string;
+    subjectId: string;
+    intent: PersonalResourceAttachmentIntent & { expectedAuthorityEpoch: number };
+  },
+): Promise<AcceptedTurnPersonalResourceAttachment> {
+  await setSubjectRlsContext(db, input.subjectId);
+  let row:
+    | {
+        grantMode: "once" | "session" | "always";
+        grantContext: "user_private" | "workspace_shared";
+        resourceCount: number;
+        resourceKinds: Array<"variable_set" | "rig" | "connected_machine">;
+        sharedOutputWarningVersion: 1;
+        replay: boolean;
+      }
+    | undefined;
+  try {
+    [row] = await rawRows(
+      db,
+      sql`
+        select grant_mode as "grantMode", grant_context as "grantContext",
+          resource_count::int as "resourceCount", resource_kinds as "resourceKinds",
+          shared_output_warning_version::int as "sharedOutputWarningVersion", replay
+        from accept_turn_personal_resource_attachment(
+          ${input.accountId}::uuid, ${input.workspaceId}::uuid,
+          ${input.sessionId}::uuid, ${input.turnId}::uuid, ${input.intent.mode},
+          ${input.intent.expectedAuthorityEpoch},
+          ${input.intent.workspaceSharedAcknowledged},
+          ${input.intent.sharedOutputWarningVersion}
+        )
+      `,
+    );
+  } catch (error) {
+    const sqlState = nestedPostgresSqlState(error);
+    if (sqlState === "22023") {
+      throw new PersonalResourceAttachmentAcceptanceError("invalid", { cause: error });
+    }
+    if (sqlState === "42501") {
+      throw new PersonalResourceAttachmentAcceptanceError("forbidden", { cause: error });
+    }
+    if (sqlState === "23505") {
+      throw new PersonalResourceAttachmentAcceptanceError("conflict", { cause: error });
+    }
+    throw error;
+  }
+  if (!row) throw new Error("atomic personal-resource attachment was not returned");
+  return {
+    summary: PersonalResourceAttachmentSummary.parse({
+      mode: row.grantMode,
+      context: row.grantContext,
+      resourceCount: row.resourceCount,
+      resourceKinds: row.resourceKinds,
+      sharedOutputWarningVersion: row.sharedOutputWarningVersion,
+    }),
+    replay: row.replay,
+  };
+}
+
+type AuthorityRow = Omit<
+  UserResourceAuthorityGrant,
+  "grantId" | "targetWorkspaceId" | "delegation"
+> & {
+  authorityId: string;
+  organizationId: string;
+  resourceKind: UserResourceKind;
+  resourceId: string;
+  originWorkspaceId: string | null;
+  authorityGeneration: number;
+  authorityStatus: UserResourceAuthoritySummary["status"];
+  grantId: string | null;
+  targetWorkspaceId: string | null;
+};
+
+function rfc3339(value: string | null): string | null {
+  if (value === null) return null;
+  const date = new Date(value);
+  if (Number.isNaN(date.getTime())) throw new Error("invalid database timestamptz projection");
+  return date.toISOString();
+}
+
+async function withOwnerContext<T>(
+  db: Database,
+  input: { accountId: string; workspaceId: string; subjectId: string },
+  fn: (db: Database) => Promise<T>,
+): Promise<T> {
+  return await withRlsContext(db, input, async (scopedDb) => {
+    await setSubjectRlsContext(scopedDb, input.subjectId);
+    return await fn(scopedDb);
+  });
+}
+
+export async function listSelfUserResourceAuthorities(
+  db: Database,
+  input: {
+    accountId: string;
+    workspaceId: string;
+    subjectId: string;
+    resourceKind: UserResourceKind;
+    cursor?: string | undefined;
+    limit: number;
+  },
+): Promise<{ authorities: UserResourceAuthoritySummary[]; nextCursor: string | null }> {
+  return await withOwnerContext(db, input, async (scopedDb) => {
+    const rows = await rawRows<AuthorityRow>(
+      scopedDb,
+      sql`
+      select authority_id as "authorityId", organization_id as "organizationId",
+        resource_kind as "resourceKind", resource_id as "resourceId",
+        origin_workspace_id as "originWorkspaceId",
+        authority_generation::int as "authorityGeneration",
+        authority_status as "authorityStatus", grant_id as "grantId",
+        target_workspace_id as "targetWorkspaceId", target_session_id as "targetSessionId",
+        action, grant_mode as mode, grant_context as context,
+        authority_epoch::int as "authorityEpoch",
+        grant_generation::int as generation, grant_status as status,
+        expires_at::text as "expiresAt"
+      from list_self_user_resource_authorities(
+        ${input.accountId}::uuid, ${input.workspaceId}::uuid, ${input.resourceKind},
+        ${input.cursor ?? null}::uuid, ${input.limit + 1}
+      )
+    `,
+    );
+    const grouped = new Map<string, UserResourceAuthoritySummary>();
+    for (const row of rows) {
+      const authority = grouped.get(row.authorityId) ?? {
+        authorityId: row.authorityId,
+        resourceKind: row.resourceKind,
+        resourceId: row.resourceId,
+        originWorkspaceId: row.originWorkspaceId,
+        generation: row.authorityGeneration,
+        status: row.authorityStatus,
+        grants: [],
+      };
+      if (row.grantId && row.targetWorkspaceId) {
+        authority.grants.push({
+          grantId: row.grantId,
+          targetWorkspaceId: row.targetWorkspaceId,
+          targetSessionId: row.targetSessionId,
+          action: row.action,
+          mode: row.mode,
+          context: row.context,
+          authorityEpoch: row.authorityEpoch,
+          generation: row.generation,
+          status: row.status,
+          expiresAt: rfc3339(row.expiresAt),
+          delegation: {
+            authorityId: row.authorityId,
+            grantId: row.grantId,
+            organizationId: row.organizationId,
+            workspaceId: row.targetWorkspaceId,
+            sessionId: row.targetSessionId,
+            action: row.action,
+            mode: row.mode,
+            context: row.context,
+            authorityEpoch: row.authorityEpoch,
+            authorityGeneration: row.authorityGeneration,
+            grantGeneration: row.generation,
+          },
+        });
+      }
+      grouped.set(row.authorityId, authority);
+    }
+    const values = [...grouped.values()];
+    const hasMore = values.length > input.limit;
+    const authorities = hasMore ? values.slice(0, input.limit) : values;
+    return {
+      authorities,
+      nextCursor: hasMore ? (authorities.at(-1)?.authorityId ?? null) : null,
+    };
+  });
+}
+
+export async function issueSelfUserResourceGrant(
+  db: Database,
+  input: {
+    accountId: string;
+    workspaceId: string;
+    subjectId: string;
+    authorityId: string;
+    resourceKind: UserResourceKind;
+    mode: "session" | "always";
+    context: "user_private" | "workspace_shared";
+    sessionId?: string | null;
+    expectedAuthorityEpoch?: number | null;
+    workspaceSharedAcknowledged: boolean;
+  },
+): Promise<UserResourceAuthorityGrant> {
+  return await withOwnerContext(db, input, async (scopedDb) => {
+    const [row] = await rawRows<
+      Omit<UserResourceAuthorityGrant, "delegation"> & {
+        organizationId: string;
+        authorityGeneration: number;
+      }
+    >(
+      scopedDb,
+      sql`
+      select grant_id as "grantId", organization_id as "organizationId",
+        authority_generation::int as "authorityGeneration",
+        target_workspace_id as "targetWorkspaceId",
+        target_session_id as "targetSessionId", action, grant_mode as mode,
+        grant_context as context, authority_epoch::int as "authorityEpoch",
+        grant_generation::int as generation,
+        grant_status as status, expires_at::text as "expiresAt"
+      from issue_self_user_resource_grant(
+        ${input.accountId}::uuid, ${input.authorityId}::uuid, ${input.workspaceId}::uuid,
+        ${input.resourceKind}, ${input.mode}, ${input.context},
+        ${input.sessionId ?? null}::uuid, ${input.expectedAuthorityEpoch ?? null}::integer,
+        ${input.workspaceSharedAcknowledged}
+      )
+    `,
+    );
+    if (!row) throw new Error("user-resource grant was not returned");
+    const { organizationId, authorityGeneration, ...grant } = row;
+    return {
+      ...grant,
+      expiresAt: rfc3339(grant.expiresAt),
+      delegation: {
+        authorityId: input.authorityId,
+        grantId: grant.grantId,
+        organizationId,
+        workspaceId: grant.targetWorkspaceId,
+        sessionId: grant.targetSessionId,
+        action: grant.action,
+        mode: grant.mode,
+        context: grant.context,
+        authorityEpoch: grant.authorityEpoch,
+        authorityGeneration,
+        grantGeneration: grant.generation,
+      },
+    };
+  });
+}
+
+export async function revokeSelfUserResourceGrant(
+  db: Database,
+  input: { accountId: string; workspaceId: string; subjectId: string; grantId: string },
+): Promise<{ grantId: string; generation: number; status: "revoked"; revokedAt: string }> {
+  return await withOwnerContext(db, input, async (scopedDb) => {
+    const [row] = await rawRows<{
+      grantId: string;
+      generation: number;
+      status: "revoked";
+      revokedAt: string;
+    }>(
+      scopedDb,
+      sql`
+      select grant_id as "grantId", grant_generation::int as generation,
+        grant_status as status, revoked_at::text as "revokedAt"
+      from revoke_self_user_resource_grant(
+        ${input.accountId}::uuid, ${input.workspaceId}::uuid, ${input.grantId}::uuid
+      )
+    `,
+    );
+    if (!row) throw new Error("user-resource grant was not returned");
+    return { ...row, revokedAt: rfc3339(row.revokedAt)! };
+  });
+}
+
+export async function resolveSessionAttemptPersonalResources(
+  db: Database,
+  input: { accountId: string; workspaceId: string; subjectId: string | null; attemptId: string },
+): Promise<void> {
+  await withRlsContext(db, input, async (scopedDb) => {
+    if (input.subjectId) await setSubjectRlsContext(scopedDb, input.subjectId);
+    await scopedDb.execute(sql`select authorize_session_attempt_personal_resource_reads(
+      ${input.accountId}::uuid, ${input.workspaceId}::uuid, ${input.attemptId}::uuid
+    )`);
+  });
+}
+
+export type PersonalDocumentAuthority = {
+  authorityId: string;
+  ownerOrganizationMembershipId: string;
+  authorityGeneration: number;
+};
+
+/**
+ * Create the common organization-user authority before inserting a personal
+ * Document. Returns null for a configured/local or rolling-legacy subject that
+ * has no eligible active organization membership, preserving the existing
+ * workspace-anchored personal lane. Call this inside the same database
+ * transaction as the Document insert so a failed write cannot leave an orphan
+ * authority.
+ */
+export async function createPersonalDocumentAuthority(
+  db: Database,
+  input: {
+    accountId: string;
+    workspaceId: string;
+    subjectId: string;
+    documentId: string;
+  },
+): Promise<PersonalDocumentAuthority | null> {
+  await setSubjectRlsContext(db, input.subjectId);
+  const [row] = await rawRows<PersonalDocumentAuthority>(
+    db,
+    sql`
+      select authority_id as "authorityId",
+        owner_organization_membership_id as "ownerOrganizationMembershipId",
+        authority_generation::int as "authorityGeneration"
+      from create_personal_document_authority(
+        ${input.accountId}::uuid, ${input.workspaceId}::uuid, ${input.documentId}::uuid
+      )
+    `,
+  );
+  return row ?? null;
+}