@opengeni/db 4.3.2-canary.0 → 4.3.3-canary.0

package/src/mcp-operations.ts

@@ -0,0 +1,189 @@
+import { AttemptToolResult } from "@opengeni/contracts";
+import { sql } from "drizzle-orm";
+import { type Database, withRlsContext } from "./database";
+import {
+  fromPostgresLosslessJson,
+  toPostgresLosslessJson,
+  LOSSLESS_CONTENT_CODEC_VERSION,
+} from "./lossless-json";
+
+/** Worker-authenticated invocation identity, never model/HTTP/request JSON.
+ * Possessing a DB handle or matching GUCs does NOT authenticate a caller.
+ * Bind this tuple only after verifying the worker invocation credential. SQL
+ * then derives the principal and rechecks canonical live disclosure authority. */
+export type McpOperationAttempt = {
+  accountId: string;
+  workspaceId: string;
+  sessionId: string;
+  turnId: string;
+  attemptId: string;
+  executionGeneration: number;
+};
+
+/** Structurally aligned with runtime CapturedMcpOperation, without a runtime dependency. */
+export type CaptureMcpOperationInput = {
+  operationId: string;
+  sourceCallId?: string;
+  serverId: string;
+  originalTool: string;
+  observerTool: string;
+  destinationDigest: string;
+  argumentDigest: string;
+  authorityDigest: string;
+};
+export type McpOperationSelector =
+  | { operationId: string }
+  | { sourceTurnId: string; sourceCallId: string };
+export type McpOperationRecord = Omit<CaptureMcpOperationInput, "sourceCallId"> & {
+  sourceCallId: string | null;
+  accountId: string;
+  workspaceId: string;
+  sessionId: string;
+  sourceTurnId: string;
+  sourceAttemptId: string;
+  sourceExecutionGeneration: number;
+  principalKind: "subject" | "service";
+  principalId: string;
+  /** captured means possibly dispatched, NEVER permission to replay a mutation. */
+  originalOutcome: "captured" | "completed" | "outcome_unknown";
+  originalResult: AttemptToolResult | null;
+  observationResult: AttemptToolResult | null;
+  receiptRevision: string | null;
+  receiptDigest: string | null;
+};
+export type McpOperationLookup =
+  | { status: "found"; operation: McpOperationRecord }
+  | { status: "not_found" | "ambiguous" };
+
+async function command<T>(
+  db: Database,
+  attempt: McpOperationAttempt,
+  action: string,
+  payload: object,
+): Promise<T> {
+  return withRlsContext(
+    db,
+    { accountId: attempt.accountId, workspaceId: attempt.workspaceId },
+    async (tx) => {
+      const result =
+        await tx.execute(sql`select mcp_operation_command(${JSON.stringify(attempt)}::jsonb,
+      ${action}::text, ${JSON.stringify(payload)}::jsonb) as value`);
+      const rows = Array.isArray(result) ? result : result.rows;
+      if (!rows?.[0]) throw new Error("MCP operation command returned no receipt");
+      return rows[0].value as T;
+    },
+    undefined,
+    "none", // SQL owns membership -> tenancy -> control -> session lock order.
+  );
+}
+
+export function captureMcpOperation(
+  db: Database,
+  attempt: McpOperationAttempt,
+  operation: CaptureMcpOperationInput,
+) {
+  return command<"created" | "existing">(db, attempt, "capture", operation);
+}
+export async function settleOriginalMcpOperation(
+  db: Database,
+  attempt: McpOperationAttempt,
+  input:
+    | { operationId: string; outcome: "completed"; result: AttemptToolResult }
+    | { operationId: string; outcome: "outcome_unknown" },
+): Promise<void> {
+  const payload =
+    input.outcome === "completed"
+      ? {
+          ...input,
+          result: toPostgresLosslessJson(AttemptToolResult.parse(input.result)),
+          resultCodecVersion: LOSSLESS_CONTENT_CODEC_VERSION,
+        }
+      : input;
+  const result = await command<{ status: string }>(db, attempt, "settle_original", payload);
+  if (result.status !== "settled") throw new Error("Original MCP operation not found");
+}
+export async function readMcpOperation(
+  db: Database,
+  attempt: McpOperationAttempt,
+  selector: McpOperationSelector,
+): Promise<McpOperationLookup> {
+  const result = await command<McpOperationLookup>(db, attempt, "read", selector);
+  if (result.status !== "found") return result;
+  const { originalResultCodecVersion, observationResultCodecVersion, ...operation } =
+    result.operation as McpOperationRecord & {
+      originalResultCodecVersion: number | null;
+      observationResultCodecVersion: number | null;
+    };
+  return {
+    status: "found",
+    operation: {
+      ...operation,
+      originalResult: fromPostgresLosslessJson(
+        operation.originalResult,
+        originalResultCodecVersion,
+      ),
+      observationResult: fromPostgresLosslessJson(
+        operation.observationResult,
+        observationResultCodecVersion,
+      ),
+    },
+  };
+}
+/** Claims authorize only the read observer; expiry never authorizes a mutation. */
+export function claimMcpOperationObservation(
+  db: Database,
+  attempt: McpOperationAttempt,
+  operationId: string,
+) {
+  return command<
+    { status: "claimed"; claimId: string } | { status: "busy" | "terminal" | "not_found" }
+  >(db, attempt, "claim_read", { operationId });
+}
+export function settleMcpOperationObservation(
+  db: Database,
+  attempt: McpOperationAttempt,
+  input: {
+    operationId: string;
+    claimId: string;
+    receiptRevision: string;
+    result: AttemptToolResult;
+  },
+) {
+  // This atomically stores one receipt, not an autonomous session notification.
+  // Explicit operation_read is a new ordinary tool call: its existing result
+  // lifecycle delivers the evidence. Repeated explicit reads legitimately have
+  // distinct call outputs while the original timeout and receipt stay immutable.
+  return command<
+    | { status: "settled" | "existing" | "conflict"; receiptDigest: string }
+    | { status: "stale_claim" | "not_found" | "original_completed" }
+  >(db, attempt, "settle_observation", {
+    ...input,
+    result: toPostgresLosslessJson(AttemptToolResult.parse(input.result)),
+    resultCodecVersion: LOSSLESS_CONTENT_CODEC_VERSION,
+  });
+}
+
+/** Unknown/pending/error cleanup only; never releases or replaces a receipt. */
+export function releaseMcpOperationObservation(
+  db: Database,
+  attempt: McpOperationAttempt,
+  input: { operationId: string; claimId: string },
+) {
+  return command<{ status: "released" | "stale_claim" | "terminal" | "not_found" }>(
+    db,
+    attempt,
+    "release_read",
+    input,
+  );
+}
+
+/** Bind only inside the trusted worker, after exact invocation authentication.
+ * Provider authorization and immutable binding fences remain the broker's job. */
+export function createMcpOperationPersistence(db: Database, attempt: McpOperationAttempt) {
+  const frozen = { ...attempt };
+  return {
+    capture: (operation: CaptureMcpOperationInput) => captureMcpOperation(db, frozen, operation),
+    settleOriginal: (input: Parameters<typeof settleOriginalMcpOperation>[2]) =>
+      settleOriginalMcpOperation(db, frozen, input),
+  };
+}

package/src/provision-roles.ts

@@ -618,6 +618,10 @@ DECLARE
 BEGIN
   EXECUTE format('REVOKE CREATE ON DATABASE %I FROM %I', current_database(), ${literal(role)});
   IF EXISTS (SELECT 1 FROM pg_namespace WHERE nspname = ${literal(schema)}) THEN
+    IF to_regprocedure(format('%I.mcp_operation_command(jsonb,text,jsonb)', ${literal(schema)})) IS NOT NULL THEN
+      EXECUTE format('REVOKE ALL ON FUNCTION %I.mcp_operation_command(jsonb,text,jsonb) FROM PUBLIC', ${literal(schema)});
+      EXECUTE format('GRANT EXECUTE ON FUNCTION %I.mcp_operation_command(jsonb,text,jsonb) TO %I', ${literal(schema)}, ${literal(role)});
+    END IF;
     EXECUTE format('GRANT USAGE ON SCHEMA %I TO %I', ${literal(schema)}, ${literal(role)});
     EXECUTE format('REVOKE CREATE ON SCHEMA %I FROM %I', ${literal(schema)}, ${literal(role)});
     EXECUTE format('REVOKE ALL PRIVILEGES ON ALL TABLES IN SCHEMA %I FROM %I', ${literal(schema)}, ${literal(role)});
@@ -2120,6 +2124,8 @@ BEGIN
     EXECUTE format('REVOKE CREATE ON SCHEMA opengeni_private FROM %I', ${literal(role)});
     EXECUTE format('GRANT EXECUTE ON ALL FUNCTIONS IN SCHEMA opengeni_private TO %I', ${literal(role)});
     FOREACH routine_signature IN ARRAY ARRAY[
+      'guard_mcp_operation_immutable()',
+      'mcp_operation_command_scoped(jsonb,text,jsonb)',
       'guard_workspace_owned_skill_head_delete()',
       'guard_workspace_owned_skill_history_delete()'
     ] LOOP

package/src/runtime-posture.ts

@@ -51,7 +51,24 @@ const AUTOMATIC_SESSION_TITLE_FANOUT_OUTBOX_TABLE = "automatic_session_title_fan
 const AUTOMATIC_SESSION_TITLE_QUARANTINE_FENCE_ROUTINE =
   "acquire_automatic_session_title_quarantine_fences_v1(integer)";
 
+const MCP_OPERATION_CAPABILITY_ROUTINE = "mcp_operation_command(jsonb, text, jsonb)";
+const MCP_OPERATION_AUTHORITY_TABLES = [
+  "mcp_operations",
+  "sessions",
+  "session_turns",
+  "session_turn_attempts",
+  "workspaces",
+  "workspace_inference_controls",
+  "organization_memberships",
+  "workspace_memberships",
+  "external_identity_links",
+  "external_link_turn_authorities",
+  "host_mcp_turn_authorities",
+  "scheduled_task_runs",
+] as const;
 const OWNER_INTERNAL_PRIVATE_ROUTINES = new Set<string>([
+  "guard_mcp_operation_immutable()",
+  "mcp_operation_command_scoped(jsonb, text, jsonb)",
   "guard_workspace_owned_skill_head_delete()",
   "guard_workspace_owned_skill_history_delete()",
   ...ARTIFACT_OUTBOX_CAPABILITY_ROUTINES,
@@ -557,6 +574,7 @@ const XAI_AUTHORITY_TABLES = [
 ] as const;
 
 export const RUNTIME_TARGET_SCHEMA_CAPABILITY_ROUTINES = [
+  MCP_OPERATION_CAPABILITY_ROUTINE,
   "skill_apply_lifecycle(uuid, uuid, jsonb, jsonb)",
   COMPANY_BRAIN_CONTEXT_INSPECTION_ROUTINE,
   COMPANY_BRAIN_CONTEXT_SELECTION_ROUTINE,
@@ -807,6 +825,7 @@ export const FORCE_RLS_TABLES = [
   "managed_auth_login_transactions",
   "managed_auth_session_set_operations",
   "managed_auth_session_sets",
+  "mcp_operations",
   "memory_slack_publication_configurations",
   "memory_slack_publication_receipts",
   "memory_slack_publications",
@@ -1381,6 +1400,7 @@ export const PROTECTED_NO_DIRECT_DML_TABLES = [
   "managed_auth_login_transactions",
   "managed_auth_session_set_operations",
   "managed_auth_session_sets",
+  "mcp_operations",
   "organization_company_profile_agent_policies",
   "organization_company_profile_agent_policy_events",
   "organization_invitation_binding_events",
@@ -2231,6 +2251,19 @@ export function evaluateRuntimeDatabasePosture(
           );
         }
       }
+    } else if (routine.name === MCP_OPERATION_CAPABILITY_ROUTINE) {
+      const missing = MCP_OPERATION_AUTHORITY_TABLES.filter((name) => !tableByName.has(name));
+      if (missing.length > 0) {
+        violations.push(`MCP operation authority tables are missing: ${missing.join(", ")}`);
+      } else if (
+        MCP_OPERATION_AUTHORITY_TABLES.some(
+          (name) => tableByName.get(name)!.owner !== routine.owner,
+        )
+      ) {
+        violations.push(
+          `MCP operation capability ${routine.name} authority table owners do not match`,
+        );
+      }
     } else if (routine.name === KNOWLEDGE_SOURCE_SYNC_LOCK_AUTHORITY_ROUTINE) {
       const missingAuthorityTables = KNOWLEDGE_SOURCE_SYNC_LOCK_AUTHORITY_TABLES.filter(
         (tableName) => !tableByName.has(tableName),
@@ -3385,6 +3418,23 @@ export function evaluateRuntimeDatabasePosture(
       violations.push(`runtime role owns private routine ${routine.name}`);
     }
     const ownerInternalRoutine = OWNER_INTERNAL_PRIVATE_ROUTINES.has(routine.name);
+    if (
+      [
+        "guard_mcp_operation_immutable()",
+        "mcp_operation_command_scoped(jsonb, text, jsonb)",
+      ].includes(routine.name)
+    ) {
+      if (routine.execute || routine.publicExecute) {
+        violations.push(
+          `runtime or PUBLIC has forbidden EXECUTE on MCP operation internal routine ${routine.name}`,
+        );
+      }
+      if (routine.owner !== tableByName.get("mcp_operations")?.owner) {
+        violations.push(
+          `MCP operation internal routine ${routine.name} owner does not match ledger owner`,
+        );
+      }
+    }
     if (
       [
         "guard_workspace_owned_skill_head_delete()",

package/src/schema.ts

@@ -6928,6 +6928,52 @@ export const sessionRealtimeContextProjections = pgTable(
 // First-class ownership for one accepted execution attempt. A workflow may
 // preallocate id, but this row is inserted only by the activity transaction
 // that actually claims the logical turn and registers its exact dispatch.
+// Protected EXECUTE-only ledger. SQL owns live-attempt/principal derivation,
+// immutable settlement, bounds, RLS and source ownership constraints.
+export const mcpOperations = pgTable(
+  "mcp_operations",
+  {
+    operationId: uuid("operation_id").primaryKey(),
+    accountId: uuid("account_id").notNull(),
+    workspaceId: uuid("workspace_id").notNull(),
+    sessionId: uuid("session_id").notNull(),
+    sourceTurnId: uuid("source_turn_id").notNull(),
+    sourceAttemptId: uuid("source_attempt_id").notNull(),
+    sourceExecutionGeneration: integer("source_execution_generation").notNull(),
+    sourceCallId: text("source_call_id"),
+    principalKind: text("principal_kind").notNull(),
+    principalId: text("principal_id").notNull(),
+    principalMembershipId: uuid("principal_membership_id"),
+    principalMembershipRevision: bigint("principal_membership_revision", { mode: "number" }),
+    serverId: text("server_id").notNull(),
+    originalTool: text("original_tool").notNull(),
+    observerTool: text("observer_tool").notNull(),
+    argumentDigest: text("argument_digest").notNull(),
+    destinationDigest: text("destination_digest").notNull(),
+    authorityDigest: text("authority_digest").notNull(),
+    originalOutcome: text("original_outcome").notNull().default("captured"),
+    originalResult: jsonb("original_result"),
+    originalResultCodecVersion: integer("original_result_codec_version"),
+    observationResult: jsonb("observation_result"),
+    observationResultCodecVersion: integer("observation_result_codec_version"),
+    receiptRevision: text("receipt_revision"),
+    receiptDigest: text("receipt_digest"),
+    observationClaimId: uuid("observation_claim_id"),
+    observationClaimAttemptId: uuid("observation_claim_attempt_id"),
+    observationClaimExpiresAt: timestamp("observation_claim_expires_at", { withTimezone: true }),
+    createdAt: timestamp("created_at", { withTimezone: true }).notNull().defaultNow(),
+    observedAt: timestamp("observed_at", { withTimezone: true }),
+  },
+  (table) => ({
+    source: index("mcp_operations_source_idx").on(
+      table.workspaceId,
+      table.sessionId,
+      table.sourceTurnId,
+      table.sourceCallId,
+    ),
+  }),
+);
+
 export const sessionTurnAttempts = pgTable(
   "session_turn_attempts",
   {