@opengeni/db 5.0.1 → 6.0.0

package/src/session-event-slices.ts

@@ -27,6 +27,40 @@ export type SessionEventSlicePage = SessionEventPage & {
 const WINDOW = 8192;
 const STRUCTURED_BYTES = 1024 * 1024;
 
+type SliceIdentity = Pick<
+  SessionEvent,
+  "id" | "sequence" | "type" | "turnId" | "turnAssociation" | "duplicateOfEventId"
+>;
+
+/** Internal search projection, NOT authorization. The scanner has selected this
+ * exact identity under its subject RLS/list filters and still holds that same
+ * transaction and tenancy/membership fences. Reuse them rather than creating
+ * two nested scopes and rediscovering the identity for every scalar window.
+ * The scalar query still checks the exact workspace/session/event and RLS.
+ * Keep the codec/window implementation shared with the conversation reader.
+ */
+export async function readSessionMessageSliceInScope(
+  db: Database,
+  workspaceId: string,
+  sessionId: string,
+  identity: SliceIdentity,
+  offset: number,
+  windows = 1,
+): Promise<SessionEventSlice | undefined> {
+  if (!Number.isInteger(windows) || windows < 1 || windows > 4)
+    throw new Error("Invalid search scalar window budget");
+  const page = await listSessionEventSlicesInternal(
+    db,
+    workspaceId,
+    sessionId,
+    { sourceSequence: identity.sequence, sourceOffset: offset, view: "conversation" },
+    undefined,
+    identity,
+    WINDOW * windows,
+  );
+  return page.slices?.[identity.sequence];
+}
+
 /** Bounded transfer over retained scalar truth. JSONB extraction/detoasting still
  * costs PostgreSQL work proportional to the individual source value, not history.
  * This is a read projection, not authorization: the MCP caller must authorize the
@@ -38,6 +72,18 @@ export async function listSessionEventSlices(
   sessionId: string,
   options: SessionEventSliceOptions,
   legacyRead?: (options: ListSessionEventPageOptions) => Promise<SessionEventPage>,
+): Promise<SessionEventSlicePage> {
+  return listSessionEventSlicesInternal(db, workspaceId, sessionId, options, legacyRead);
+}
+
+async function listSessionEventSlicesInternal(
+  db: Database,
+  workspaceId: string,
+  sessionId: string,
+  options: SessionEventSliceOptions,
+  legacyRead?: (options: ListSessionEventPageOptions) => Promise<SessionEventPage>,
+  selectedIdentity?: SliceIdentity,
+  scalarWindow = WINDOW,
 ): Promise<SessionEventSlicePage> {
   // Finish an already-issued UTF-16 cursor using its original bounded reader.
   // New messages use source slices; no cursor offset is silently reinterpreted.
@@ -79,27 +125,29 @@ export async function listSessionEventSlices(
     predicates.push(notInArray(schema.sessionEvents.type, filters.excludeTypes));
   // Unlike audit `none` mode, this identity query does not compute a payload
   // projection merely to report its size. Only the selected scalar is extracted.
-  const identities = await withWorkspaceRls(db, workspaceId, (tx) =>
-    tx
-      .select({
-        id: schema.sessionEvents.id,
-        sequence: schema.sessionEvents.sequence,
-        type: sql<string>`case when octet_length(${schema.sessionEvents.type}) <= 256 then ${schema.sessionEvents.type} else 'session.event.envelope_omitted' end`,
-        turnId: schema.sessionEvents.turnId,
-        turnAssociation: sql<
-          string | null
-        >`case when ${schema.sessionEvents.turnAssociation} is null then null when ${schema.sessionEvents.turnAssociation} = 'current' then 'current' else 'late_rejected' end`,
-        duplicateOfEventId: schema.sessionEvents.duplicateOfEventId,
-      })
-      .from(schema.sessionEvents)
-      .where(and(...predicates))
-      .orderBy(
-        direction === "before"
-          ? desc(schema.sessionEvents.sequence)
-          : asc(schema.sessionEvents.sequence),
-      )
-      .limit(limit + 1),
-  );
+  const identities = selectedIdentity
+    ? [selectedIdentity]
+    : await withWorkspaceRls(db, workspaceId, (tx) =>
+        tx
+          .select({
+            id: schema.sessionEvents.id,
+            sequence: schema.sessionEvents.sequence,
+            type: sql<string>`case when octet_length(${schema.sessionEvents.type}) <= 256 then ${schema.sessionEvents.type} else 'session.event.envelope_omitted' end`,
+            turnId: schema.sessionEvents.turnId,
+            turnAssociation: sql<
+              string | null
+            >`case when ${schema.sessionEvents.turnAssociation} is null then null when ${schema.sessionEvents.turnAssociation} = 'current' then 'current' else 'late_rejected' end`,
+            duplicateOfEventId: schema.sessionEvents.duplicateOfEventId,
+          })
+          .from(schema.sessionEvents)
+          .where(and(...predicates))
+          .orderBy(
+            direction === "before"
+              ? desc(schema.sessionEvents.sequence)
+              : asc(schema.sessionEvents.sequence),
+          )
+          .limit(limit + 1),
+      );
   const ordered = identities.slice(0, limit).map(
     (identity) =>
       ({
@@ -124,7 +172,7 @@ export async function listSessionEventSlices(
   const slices: Record<number, SessionEventSlice> = {};
   const events: SessionEvent[] = [];
   let consumed = 0;
-  await withWorkspaceRls(db, workspaceId, async (tx) => {
+  const readScalars = async (tx: Database) => {
     for (const event of ordered) {
       consumed++;
       if (
@@ -217,8 +265,8 @@ export async function listSessionEventSlices(
           case when tagged then (length(encoded) / 4 * 3 - case when right(encoded, 2) = '==' then 2 when right(encoded, 1) = '=' then 1 else 0 end) / 2
           else length(raw) end else 0 end as total,
         case when kind = 'string' then
-          case when tagged then substring(encoded from ${Math.min(group * 8 + 1, 2_147_483_647)}::integer for ${Math.ceil((WINDOW + 6) / 3) * 8}::integer)
-          else substring(raw from ${Math.min(start + 1, 2_147_483_647)}::integer for ${WINDOW}::integer) end else null end as window,
+          case when tagged then substring(encoded from ${Math.min(group * 8 + 1, 2_147_483_647)}::integer for ${Math.ceil((scalarWindow + 6) / 3) * 8}::integer)
+          else substring(raw from ${Math.min(start + 1, 2_147_483_647)}::integer for ${scalarWindow}::integer) end else null end as window,
         case when kind <> 'string' and structured_bytes <= ${STRUCTURED_BYTES} then value else null end as structured,
         coalesce(kind <> 'string' and structured_bytes > ${STRUCTURED_BYTES}, false) as omitted
       from validated`,
@@ -254,7 +302,7 @@ export async function listSessionEventSlices(
           /[\uDC00-\uDFFF]/.test(text[local] ?? "")
         )
           throw new Error("Invalid message continuation offset: splits a surrogate pair");
-        text = text.slice(local, local + WINDOW);
+        text = text.slice(local, local + scalarWindow);
         if (start + text.length < row.total && /[\uD800-\uDBFF]/.test(text.at(-1)!))
           text = text.slice(0, -1);
       }
@@ -291,7 +339,9 @@ export async function listSessionEventSlices(
       )
         break;
     }
-  });
+  };
+  if (selectedIdentity) await readScalars(db);
+  else await withWorkspaceRls(db, workspaceId, readScalars);
   // Preserve scan advancement even when every identity was excluded above.
   return {
     ...page,

package/src/session-file-attachments.ts

@@ -0,0 +1,66 @@
+import type { FileAsset, ResourceRef, SessionAuthorizationActor } from "@opengeni/contracts";
+import { sql } from "drizzle-orm";
+import { rawRows, withRlsContext, type Database } from "./database";
+
+/** Only call during verified human initial/Send/Steer acceptance, in its transaction. */
+export async function acceptSessionFileAttachments(
+  db: Database,
+  input: {
+    accountId: string;
+    workspaceId: string;
+    sessionId: string;
+    turnId: string;
+    subjectId: string;
+    resources: ResourceRef[];
+  },
+): Promise<void> {
+  const ids = [...new Set(input.resources.flatMap((r) => (r.kind === "file" ? [r.fileId] : [])))];
+  if (!ids.length) return;
+  await withRlsContext(db, input, async (tx) => {
+    await tx.execute(sql`select opengeni_private.accept_session_file_attachments(
+      ${input.accountId}::uuid,${input.workspaceId}::uuid,${input.sessionId}::uuid,${input.turnId}::uuid,
+      ${input.subjectId},ARRAY(select jsonb_array_elements_text(${JSON.stringify(ids)}::jsonb))::uuid[])`);
+  });
+}
+
+export type SessionAttachmentReadAccess = {
+  sessionId: string;
+  authorityEpoch: number;
+  actor: Pick<SessionAuthorizationActor, "kind" | "subjectId"> &
+    Partial<{
+      callerSessionId: string;
+      turnId: string;
+      attemptId: string;
+      executionGeneration: number;
+    }>;
+};
+/** Core must prove session authorization; workers supply their live own-session attempt. */
+export async function readSessionFileAttachments(
+  db: Database,
+  input: {
+    accountId: string;
+    workspaceId: string;
+    fileIds: readonly string[];
+    access: SessionAttachmentReadAccess;
+  },
+): Promise<FileAsset[]> {
+  if (!input.fileIds.length) return [];
+  return withRlsContext(db, input, async (tx) => {
+    const rows = await rawRows<FileAsset>(
+      tx,
+      sql`
+    select id,case when private_owner_subject_ids is null then 'workspace' else 'personal' end as scope,workspace_id as "workspaceId",status,filename,
+      safe_filename as "safeFilename",content_type as "contentType",size_bytes::double precision as "sizeBytes",
+      sha256,bucket,object_key as "objectKey",created_at::text as "createdAt",updated_at::text as "updatedAt"
+    from opengeni_private.read_session_file_attachments(
+      ${input.accountId}::uuid,${input.workspaceId}::uuid,${input.access.sessionId}::uuid,
+      ${input.access.authorityEpoch},ARRAY(select jsonb_array_elements_text(${JSON.stringify([...new Set(input.fileIds)])}::jsonb))::uuid[],
+      ${JSON.stringify(input.access.actor)}::jsonb)`,
+    );
+    return rows.map((row) => ({
+      ...row,
+      createdAt: new Date(row.createdAt).toISOString(),
+      updatedAt: new Date(row.updatedAt).toISOString(),
+    }));
+  });
+}

package/src/session-goal-reports.ts

@@ -0,0 +1,255 @@
+import {
+  SessionGoalReportDeliveries,
+  SessionGoalReportRequirements,
+  type SessionGoalReportRequirement,
+} from "@opengeni/contracts";
+import { and, eq, sql } from "drizzle-orm";
+import {
+  rawRows,
+  withSessionActivityRlsContext,
+  withSessionActivitySavepoint,
+  type Database,
+} from "./database";
+import {
+  transactionallyAuthorizeEditableArtifactActor,
+  type PersistedEditableArtifactActor,
+} from "./editable-artifacts";
+import {
+  assertAgentCommandAuthorityInTransaction,
+  canonicalSessionCommandHash,
+  lockSessionEventWriteRows,
+  reserveSessionCommandReceipt,
+} from "./session-control";
+import * as schema from "./schema";
+
+/** Versioned, server-owned metadata. Malformed persisted data fails closed. */
+export const GOAL_REPORT_REQUIREMENTS_KEY = "reportRequirementsV1";
+
+export function goalReportRequirements(
+  metadata: Record<string, unknown>,
+): SessionGoalReportRequirement[] {
+  return SessionGoalReportRequirements.parse(
+    Object.hasOwn(metadata, GOAL_REPORT_REQUIREMENTS_KEY)
+      ? metadata[GOAL_REPORT_REQUIREMENTS_KEY]
+      : [],
+  );
+}
+
+export function appendGoalReportRequirements(
+  metadata: Record<string, unknown>,
+  declarations: readonly SessionGoalReportRequirement[] = [],
+): Record<string, unknown> {
+  const existing = goalReportRequirements(metadata);
+  const incoming = SessionGoalReportRequirements.parse(declarations);
+  for (const requirement of incoming) {
+    const previous = existing.find((item) => item.id === requirement.id);
+    if (previous && previous.title !== requirement.title) {
+      throw new Error(`Report requirement ${requirement.id} is immutable`);
+    }
+    if (!previous) existing.push(requirement);
+  }
+  return {
+    ...metadata,
+    [GOAL_REPORT_REQUIREMENTS_KEY]: SessionGoalReportRequirements.parse(existing),
+  };
+}
+
+export type ReportArtifactActor = Extract<PersistedEditableArtifactActor, { kind: "agent" }>;
+
+/** Called under the canonical session lock. NOWAIT avoids the existing artifact
+ * writer's artifact -> actor-session authorization lock inversion. The caller
+ * rolls back and retries/re-inspects after a concurrent edit; never waits here. */
+async function lockReadableDocument(
+  tx: Database,
+  scope: { accountId: string; workspaceId: string },
+  actor: ReportArtifactActor,
+  artifactId: string,
+) {
+  const [artifact] = await rawRows<{
+    head_sequence: string | number;
+    state_hash: string;
+    modality: string;
+    lifecycle_state: string;
+    authorization_revision: string | number;
+  }>(
+    tx,
+    sql`
+    select head_sequence, state_hash, modality, lifecycle_state, authorization_revision from editable_artifacts
+    where account_id = ${scope.accountId}::uuid and workspace_id = ${scope.workspaceId}::uuid
+      and id = ${artifactId} for share nowait
+  `,
+  );
+  if (!artifact || artifact.modality !== "document" || artifact.lifecycle_state !== "active") {
+    throw new Error("Report delivery requires an accessible active native document");
+  }
+  const authorization = await transactionallyAuthorizeEditableArtifactActor(tx, {
+    scope,
+    actor,
+    artifactId,
+    permission: "read",
+  });
+  if (!authorization.allowed) throw new Error("Report document access denied");
+  return artifact;
+}
+
+/** Trusted application-only recorder, called after native query/decode. There is
+ * no public route/tool accepting this proof body. The runtime SQL role remains
+ * trusted: it can insert receipt-shaped rows, so stored proof is not a native
+ * execution attestation against arbitrary application-role SQL. UPDATE and
+ * direct DELETE are fenced; legitimate session-retention cascades remove proof.
+ */
+export async function recordNativeDocumentInspection(
+  db: Database,
+  input: {
+    scope: { accountId: string; workspaceId: string };
+    actor: ReportArtifactActor;
+    sessionId: string;
+    artifact: { id: string; modality: string; headSequence: number; stateHash: string };
+    queryHash: string;
+    queryKind: string;
+  },
+): Promise<string> {
+  if (input.actor.sessionId !== input.sessionId)
+    throw new Error("Inspection session authority mismatch");
+  return withSessionActivityRlsContext(db, input.scope, (scopedDb) =>
+    withSessionActivitySavepoint(scopedDb, async (tx) => {
+      const locks = await lockSessionEventWriteRows(tx, {
+        workspaceId: input.scope.workspaceId,
+        controlLock: "share",
+        sessionIds: [input.sessionId],
+      });
+      if (!locks.control || !locks.workspace || !locks.sessions[0])
+        throw new Error("Inspection session not found");
+      const actor = {
+        type: "agent_attempt" as const,
+        sessionId: input.actor.sessionId,
+        turnId: input.actor.turnId,
+        attemptId: input.actor.attemptId,
+        executionGeneration: input.actor.generation,
+      };
+      await assertAgentCommandAuthorityInTransaction(tx, {
+        workspaceId: input.scope.workspaceId,
+        actor,
+        targetSessionId: input.sessionId,
+        action: "goal",
+      });
+      const artifact = await lockReadableDocument(tx, input.scope, input.actor, input.artifact.id);
+      if (
+        Number(artifact.head_sequence) !== input.artifact.headSequence ||
+        artifact.state_hash !== input.artifact.stateHash
+      ) {
+        throw new Error("Document changed during inspection; inspect its current head again");
+      }
+      const result = {
+        version: "native-document-inspection.v1",
+        artifactId: input.artifact.id,
+        headSequence: input.artifact.headSequence,
+        stateHash: input.artifact.stateHash,
+        subjectId: input.actor.subjectId,
+        queryHash: input.queryHash,
+        queryKind: input.queryKind,
+        authorizationRevision: Number(artifact.authorization_revision),
+      };
+      const reserved = await reserveSessionCommandReceipt(tx, {
+        ...input.scope,
+        actor,
+        action: "artifact.document.inspect",
+        targetSessionId: input.sessionId,
+        targetTurnId: input.actor.turnId,
+        operationKey: `document-inspection:${canonicalSessionCommandHash(result)}`,
+        canonicalRequestHash: canonicalSessionCommandHash(result),
+        initialResult: result,
+      });
+      return reserved.receipt.id;
+    }),
+  );
+}
+
+/** No provider calls here: receipt, access, locked current head and completion
+ * share one transaction. Receipts from previous attempts may prove inspection,
+ * but the completing attempt must still have live read authority. */
+export async function verifyGoalReportDeliveries(
+  tx: Database,
+  input: {
+    accountId: string;
+    workspaceId: string;
+    sessionId: string;
+    metadata: Record<string, unknown>;
+    deliveries: unknown;
+    actor?: ReportArtifactActor;
+  },
+): Promise<void> {
+  const requirements = goalReportRequirements(input.metadata);
+  const deliveries = SessionGoalReportDeliveries.parse(input.deliveries ?? []);
+  if (
+    deliveries.length !== requirements.length ||
+    requirements.some((item) => !deliveries.some((delivery) => delivery.requirementId === item.id))
+  ) {
+    throw new Error(
+      "Every persisted report requirement needs exactly one verified document delivery",
+    );
+  }
+  if (!requirements.length) return;
+  if (!input.actor || input.actor.sessionId !== input.sessionId)
+    throw new Error("Report completion requires exact agent artifact authority");
+  const [turn] = await tx
+    .select({
+      initiatingHumanSubjectId: schema.sessionTurns.initiatingHumanSubjectId,
+      initiatorKind: schema.sessionTurns.initiatorKind,
+      initiatorSubjectId: schema.sessionTurns.initiatorSubjectId,
+    })
+    .from(schema.sessionTurns)
+    .where(
+      and(
+        eq(schema.sessionTurns.workspaceId, input.workspaceId),
+        eq(schema.sessionTurns.sessionId, input.sessionId),
+        eq(schema.sessionTurns.id, input.actor.turnId),
+      ),
+    )
+    .limit(1);
+  const recipient =
+    turn?.initiatingHumanSubjectId ??
+    (turn?.initiatorKind === "subject" ? turn.initiatorSubjectId : null);
+  if (!recipient)
+    throw new Error("Report completion requires a verified initiating human recipient");
+  for (const delivery of [...deliveries].sort((a, b) => a.artifactId.localeCompare(b.artifactId))) {
+    const artifact = await lockReadableDocument(tx, input, input.actor, delivery.artifactId);
+    const recipientAccess = await transactionallyAuthorizeEditableArtifactActor(tx, {
+      scope: input,
+      artifactId: delivery.artifactId,
+      actor: { kind: "human", subjectId: recipient, replicaId: input.actor.replicaId },
+      permission: "read",
+    });
+    if (!recipientAccess.allowed)
+      throw new Error("Report recipient cannot access the native document");
+    const [receipt] = await tx
+      .select()
+      .from(schema.sessionCommandReceipts)
+      .where(
+        and(
+          eq(schema.sessionCommandReceipts.id, delivery.inspectionReceiptId),
+          eq(schema.sessionCommandReceipts.accountId, input.accountId),
+          eq(schema.sessionCommandReceipts.workspaceId, input.workspaceId),
+          eq(schema.sessionCommandReceipts.targetSessionId, input.sessionId),
+          eq(schema.sessionCommandReceipts.action, "artifact.document.inspect"),
+          eq(schema.sessionCommandReceipts.actorType, "agent_attempt"),
+        ),
+      )
+      .limit(1);
+    const proof = receipt?.result;
+    if (
+      !proof ||
+      proof.version !== "native-document-inspection.v1" ||
+      proof.queryKind !== "body" ||
+      proof.artifactId !== delivery.artifactId ||
+      proof.subjectId !== input.actor.subjectId ||
+      proof.headSequence !== Number(artifact.head_sequence) ||
+      proof.stateHash !== artifact.state_hash ||
+      proof.authorizationRevision !== Number(artifact.authorization_revision)
+    ) {
+      throw new Error(
+        "Missing, untrusted, inaccessible or stale native document inspection receipt",
+      );
+    }
+  }
+}

package/src/session-mcp-approval.ts

@@ -0,0 +1,30 @@
+import { and, eq, inArray } from "drizzle-orm";
+import type { SessionMcpApprovalPolicy } from "@opengeni/contracts";
+import { withWorkspaceRls, type Database } from "./database";
+import * as schema from "./schema";
+
+/** Read only the immutable active-attempt policy, never a mutable session fallback. */
+export async function getSessionAttemptMcpApprovalPolicies(
+  db: Database,
+  workspaceId: string,
+  sessionId: string,
+  attemptId: string,
+): Promise<Record<string, SessionMcpApprovalPolicy>> {
+  return await withWorkspaceRls(db, workspaceId, async (tx) => {
+    const [attempt] = await tx
+      .select({ policies: schema.sessionTurnAttempts.mcpApprovalPolicies })
+      .from(schema.sessionTurnAttempts)
+      .where(
+        and(
+          eq(schema.sessionTurnAttempts.workspaceId, workspaceId),
+          eq(schema.sessionTurnAttempts.sessionId, sessionId),
+          eq(schema.sessionTurnAttempts.id, attemptId),
+          inArray(schema.sessionTurnAttempts.state, ["claimed", "running"]),
+        ),
+      )
+      .limit(1);
+    if (!attempt)
+      throw new Error(`session MCP policy snapshot is unavailable for attempt ${attemptId}`);
+    return attempt.policies;
+  });
+}