@opengeni/db 3.1.3-canary.38890816741001 → 3.2.2

package/dist/index.d.ts

@@ -9276,6 +9276,11 @@ export declare function claimWorkspaceArchiveCapture(db: Database, input: {
      * exact box are recorded in deadline_forced_admission_ids, captured
      * around, and settled with the box after termination. */
     deadlineMandatoryCaptureLeadMs?: number;
+    /** Draining only: unsettled setup requests whose provider Start outcome
+     * is unknown, owned by a turn attempt closed at least this long ago with
+     * no active retained process, are captured around exactly like the
+     * mandatory pre-deadline save instead of pinning the box until then. */
+    abandonedSetupCaptureAfterMs?: number;
     /** Warm point-in-time checkpoint of a box no turn holds, kept warm by
      * viewers, browser/computer interactions or active background commands
      * (supervised or not) (e.g. while the session waits for one or for input). Requires

package/dist/index.js

@@ -1534,6 +1534,7 @@ import {
   placeSubscriptionCoreTurnWithFailover,
   planWorkspaceCaptureGc,
   preflightOrganizationUserSetup,
+  preflightProviderVaultLink,
   prepareBotMessage,
   prepareBrowserDownloadSave,
   prepareBrowserRevisionPublication,
@@ -2207,7 +2208,7 @@ import {
   writeCompanyProfileLearning,
   writeSessionContentBlobs,
   writeSiteDataPath
-} from "./chunk-JMX6XSIF.js";
+} from "./chunk-V2X2NK7T.js";
 import {
   BROKERED_CREDENTIAL_SHAPE_HINT,
   ConnectionRefreshHttpError,
@@ -4860,6 +4861,7 @@ export {
   placeSubscriptionCoreTurnWithFailover,
   planWorkspaceCaptureGc,
   preflightOrganizationUserSetup,
+  preflightProviderVaultLink,
   prepareBotMessage,
   prepareBrowserDownloadSave,
   prepareBrowserRevisionPublication,

package/dist/migrate.js

@@ -9,7 +9,7 @@ import {
   planMigrations,
   runMigrateCli,
   runMigrations
-} from "./chunk-JMX6XSIF.js";
+} from "./chunk-V2X2NK7T.js";
 import "./chunk-VCJAYIPH.js";
 import "./chunk-XQHABE23.js";
 import "./chunk-4BAKPTPG.js";

package/dist/vaults.d.ts

@@ -1,4 +1,4 @@
-import { VaultErrorCode, type SecretPrincipal, type VaultFieldKind, type VaultItemType, type VaultMode, type VaultOwnerKind, type VaultPolicy, type VaultSource, type VaultSyncStatus, type VaultVersionCreatedByKind } from "@opengeni/contracts";
+import { VaultErrorCode, type SecretPrincipal, type VaultFieldKind, type VaultItemType, type VaultMode, type VaultOwnerKind, type VaultPolicy, type VaultProviderOperations, type VaultSource, type VaultSyncStatus, type VaultVersionCreatedByKind } from "@opengeni/contracts";
 import { type Database } from "./database.js";
 export type VaultDbContext = {
     kind: "subject";
@@ -19,6 +19,15 @@ export declare class VaultError extends Error {
 export declare function isVaultError(error: unknown): error is VaultError;
 /** Map a database error raised by a vault routine to VaultError; null otherwise. */
 export declare function vaultErrorFromDatabase(error: unknown): VaultError | null;
+/**
+ * What a provider (or its bridge) said about its own upstream freshness at
+ * the last successful check (0789). Opengeni's own check time is
+ * `lastSyncedAt`; it never stands in for `sourceSyncedAt`.
+ */
+export type StoredProviderFreshness = {
+    source: "live" | "cache" | "unknown";
+    sourceSyncedAt: string | null;
+};
 export type VaultRow = {
     id: string;
     workspaceId: string;
@@ -36,6 +45,15 @@ export type VaultRow = {
     rateLimitedUntil: string | null;
     providerConnectionId: string | null;
     providerVaultRef: string | null;
+    /** Effective operations the provider last reported (0789); null before the first check. */
+    providerOperations?: VaultProviderOperations | null;
+    /** The provider's own freshness observation from the last successful check (0789). */
+    providerFreshness?: StoredProviderFreshness | null;
+    /**
+     * Durable value-cache epoch (0789, bigint as text). Every complete mirror
+     * replacement advances it; provider value caches compare it before reuse.
+     */
+    providerCacheEpoch?: string;
     availability: {
         allowedWorkspaceIds: string[] | null;
         allowPersonalWorkspaces: boolean;
@@ -105,6 +123,8 @@ export type VaultFieldCiphertext = {
     source: VaultSource;
     providerConnectionId: string | null;
     providerVaultRef: string | null;
+    /** The vault's value-cache epoch (0789). */
+    providerCacheEpoch?: string;
     providerItemRef: string | null;
     providerFieldRef: string | null;
 };
@@ -137,6 +157,8 @@ export type SecretReferenceCandidate = {
     source: VaultSource;
     providerConnectionId: string | null;
     providerVaultRef: string | null;
+    /** The vault's value-cache epoch (0789). */
+    providerCacheEpoch?: string;
     itemId: string;
     itemName: string;
     itemType: VaultItemType;
@@ -349,24 +371,57 @@ export type ProviderVaultItemMirror = {
         kind: VaultFieldKind;
     }>;
 };
+/**
+ * Replace a connected vault's metadata mirror with one complete inventory
+ * (at most `VAULT_LIMITS.itemsPerVault` items; more is refused with
+ * `provider_inventory_incomplete` and the old mirror kept). Items missing
+ * from `items` are removed, and the vault's cache epoch advances (0789).
+ */
 export declare function upsertProviderVaultItems(db: Database, context: VaultDbContext, input: {
     vaultId: string;
     contentVersion: string | null;
     items: ProviderVaultItemMirror[];
 }): Promise<void>;
+/**
+ * Record a connected vault's sync state. `operations` and `freshness` are
+ * optional (0789): absent keeps the stored value, null clears it. The optional
+ * mirror and status settle atomically, comparing `expectedCacheEpoch` under
+ * the vault lock; a mismatch raises provider_conflict with superseded=true.
+ * Every applied settlement advances the epoch, even unchanged or failed checks.
+ */
 export declare function setVaultSyncStatus(db: Database, context: VaultDbContext, input: {
     vaultId: string;
     status: VaultSyncStatus;
     errorCode?: string | null;
     errorMessage?: string | null;
     rateLimitedUntil?: string | null;
+    /** The provider's effective operations for this vault. */
+    operations?: VaultProviderOperations | null;
+    /** The provider's own upstream freshness observation (never Opengeni's check time). */
+    freshness?: StoredProviderFreshness | null;
+    /** Reject a late refresh when another settlement advanced this epoch. */
+    expectedCacheEpoch?: string;
+    /** Complete inventory committed atomically with this successful status. */
+    mirror?: {
+        contentVersion: string | null;
+        items: ProviderVaultItemMirror[];
+    };
 }): Promise<void>;
-/** Link a 1Password or host vault (W5). The mirror is filled by the first sync. */
+/**
+ * Link a connected vault (W5, 0789). Every source but `host` needs an active
+ * `api_key` connection in the caller's workspace whose provider identity
+ * matches (`1password.com` with the 1Password service-account role, or
+ * `vault:<source>` with the `external_vault_provider` role and
+ * `metadata.vaultProvider.provider = source`, version 1, not pending
+ * verification) and whose ownership matches `ownerKind`: a personal
+ * connection backs only its owner's Only-me vaults. The mirror is filled by
+ * the first sync.
+ */
 export declare function linkProviderVault(db: Database, context: VaultDbContext, input: {
     ownerKind: "user" | "workspace" | "organization";
     name: string;
     description?: string | null;
-    source: "onepassword" | "host";
+    source: Exclude<VaultSource, "opengeni">;
     providerConnectionId?: string | null;
     providerVaultRef: string;
     mode: VaultMode;
@@ -377,6 +432,14 @@ export declare function linkProviderVault(db: Database, context: VaultDbContext,
     /** The caller holds account:admin. */
     allowOrganization?: boolean;
 }): Promise<VaultRow>;
+/**
+ * Exercise the exact link policy before an irreversible provider create. The
+ * temporary link, personal authority and audit rows are all rolled back. This
+ * is a preflight, not a reservation: a race after it must return the confirmed
+ * upstream identity so the caller can link that vault instead of creating again.
+ * No database transaction is held open across provider I/O.
+ */
+export declare function preflightProviderVaultLink(db: Database, context: VaultDbContext, input: Omit<Parameters<typeof linkProviderVault>[2], "providerVaultRef">): Promise<void>;
 export type ProviderVaultSyncTargetRow = {
     vaultId: string;
     workspaceId: string;
@@ -386,6 +449,8 @@ export type ProviderVaultSyncTargetRow = {
     providerVaultRef: string;
     providerContentVersion: string | null;
     rateLimitedUntil: string | null;
+    /** The vault's value-cache epoch (0789). */
+    providerCacheEpoch?: string;
 };
 /** The provider refs and mirror version of one reachable connected vault. */
 export declare function getProviderVaultSyncTarget(db: Database, context: VaultDbContext, vaultId: string): Promise<ProviderVaultSyncTargetRow>;

package/drizzle/0789_external_vault_sources.sql

@@ -0,0 +1,318 @@
+-- deployment-mode: rolling
+-- External vault providers (docs/design/external-vaults-2026-10-15.md, sections
+-- 6, 8, 9 and 10).
+--   * New source identities: `external` (remote bridge), `protonpass`,
+--     `keeper` and `bitwarden`. Each is linked through a connection, like
+--     1Password; `host` keeps its injected, connection-less provider.
+--   * Linking checks provider identity, active connection status and
+--     ownership here as well as in HTTP. A personal connection backs only its
+--     owner's Only-me vaults; a shared connection backs only vaults of its own
+--     ownership, so an organization connection never becomes a workspace one.
+--     A legacy 1Password connection without recorded ownership stays a
+--     workspace connection, as the API has always shown it.
+--   * A linked vault keeps the effective operations its provider last
+--     reported, the provider's own freshness observation (never Opengeni's
+--     check time), and a durable cache epoch. Every complete mirror
+--     replacement advances the epoch, so per-attempt value caches in any API
+--     or worker process notice a refresh made elsewhere.
+--   * A mirror replacement holds at most the native 2,000 items per vault; a
+--     larger inventory is refused whole, never stored as its first 2,000.
+--   * Mirror replacements of one vault run one at a time: each holds the
+--     vault row lock from before it reads the mirror until it commits, so an
+--     older listing cannot re-add an item that a newer one just removed and
+--     leave it under the newer content version.
+--   * Core refresh settlement compares the epoch read before provider I/O,
+--     committing inventory and status together. Every settlement advances it;
+--     late results cannot overwrite a newer completed check, even unchanged.
+-- Existing rows keep their meaning: the new columns are NULL or 0 and the
+-- Only-me availability default of 0780 is unchanged.
+SET LOCAL lock_timeout = '5s';
+
+ALTER TABLE vaults DROP CONSTRAINT vaults_source_check;
+ALTER TABLE vaults DROP CONSTRAINT vaults_provider_shape;
+ALTER TABLE vaults
+  ADD COLUMN provider_operations jsonb,
+  ADD COLUMN provider_freshness jsonb,
+  ADD COLUMN provider_cache_epoch bigint NOT NULL DEFAULT 0;
+ALTER TABLE vaults ADD CONSTRAINT vaults_source_check CHECK (
+  source IN ('opengeni', 'onepassword', 'host', 'external', 'protonpass', 'keeper', 'bitwarden')
+);
+ALTER TABLE vaults ADD CONSTRAINT vaults_provider_shape CHECK (
+  (source = 'opengeni' AND provider_vault_ref IS NULL AND provider_connection_id IS NULL
+    AND mode = 'read_write')
+  OR (source IN ('onepassword', 'external', 'protonpass', 'keeper', 'bitwarden')
+    AND provider_vault_ref IS NOT NULL AND provider_connection_id IS NOT NULL)
+  OR (source = 'host' AND provider_vault_ref IS NOT NULL AND provider_connection_id IS NULL)
+);
+ALTER TABLE vaults ADD CONSTRAINT vaults_provider_metadata_shape CHECK (
+  provider_cache_epoch >= 0
+  AND (provider_operations IS NULL
+    OR (source <> 'opengeni' AND jsonb_typeof(provider_operations) = 'object'))
+  AND (provider_freshness IS NULL
+    OR (source <> 'opengeni' AND jsonb_typeof(provider_freshness) = 'object'))
+);
+
+-- Rewrites one routine in place. Each patch must match exactly once, so a
+-- routine that changed since this was written fails the migration loudly.
+-- The name is migration-specific because earlier migrations leave their own
+-- patcher in the migrator session's pg_temp schema.
+CREATE FUNCTION pg_temp.patch_vault_routine_0786(p_routine regprocedure, p_patches text[])
+RETURNS void
+LANGUAGE plpgsql AS $patch$
+DECLARE
+  definition text := pg_catalog.pg_get_functiondef(p_routine);
+  patch text[];
+BEGIN
+  FOREACH patch SLICE 1 IN ARRAY p_patches LOOP
+    IF (pg_catalog.length(definition) - pg_catalog.length(pg_catalog.replace(definition, patch[1], '')))
+      <> pg_catalog.length(patch[1]) THEN
+      RAISE EXCEPTION '0789 external vault sources: % changed near: %', p_routine, patch[1];
+    END IF;
+    definition := pg_catalog.replace(definition, patch[1], patch[2]);
+  END LOOP;
+  EXECUTE definition;
+END
+$patch$;
+
+-- Summaries carry the provider's operations, freshness observation and cache epoch.
+SELECT pg_temp.patch_vault_routine_0786('opengeni_private.vault_summary_json(vaults,jsonb)'::regprocedure, ARRAY[
+  ARRAY[$old$    'providerVaultRef', p_vault.provider_vault_ref,
+$old$,
+    $new$    'providerVaultRef', p_vault.provider_vault_ref,
+    'providerOperations', p_vault.provider_operations,
+    'providerFreshness', p_vault.provider_freshness,
+    'providerCacheEpoch', p_vault.provider_cache_epoch::text,
+$new$]
+]);
+
+-- Link: every connected source needs an active connection of that provider
+-- whose ownership matches the vault it backs.
+SELECT pg_temp.patch_vault_routine_0786('link_provider_vault(jsonb,jsonb)'::regprocedure, ARRAY[
+  ARRAY[$old$  connection_row record;
+$old$,
+    $new$  connection_row record;
+  connection_ownership text;
+  provider_label text;
+$new$],
+  ARRAY[$old$  IF link_source NOT IN ('onepassword', 'host') OR link_source IS NULL THEN
+    PERFORM opengeni_private.vault_raise('vault_permission_denied', 'only 1Password and host vaults are linked');
+  END IF;
+$old$,
+    $new$  IF link_source NOT IN ('onepassword', 'host', 'external', 'protonpass', 'keeper', 'bitwarden')
+    OR link_source IS NULL THEN
+    PERFORM opengeni_private.vault_raise('vault_permission_denied', 'only connected vault providers are linked');
+  END IF;
+$new$],
+  ARRAY[$old$  IF link_source = 'onepassword' THEN
+    SELECT connection.id, connection.subject_id, connection.status INTO connection_row
+    FROM connections connection
+    WHERE connection.id = connection_ref
+      AND connection.account_id = (context ->> 'accountId')::uuid
+      AND connection.workspace_id = (context ->> 'workspaceId')::uuid
+      AND pg_catalog.lower(connection.provider_domain) = '1password.com';
+    IF connection_row.id IS NULL THEN
+      PERFORM opengeni_private.vault_raise('vault_not_found', '1Password connection not found');
+    END IF;
+    IF connection_row.subject_id IS NOT NULL AND (
+      owner_kind <> 'user' OR connection_row.subject_id IS DISTINCT FROM context ->> 'subjectId'
+    ) THEN
+      PERFORM opengeni_private.vault_raise('vault_permission_denied',
+        'a personal 1Password connection backs only its owner''s Only-me vaults');
+    END IF;
+  ELSE
+$old$,
+    $new$  IF link_source <> 'host' THEN
+    provider_label := CASE link_source
+      WHEN 'onepassword' THEN '1Password'
+      WHEN 'protonpass' THEN 'Proton Pass'
+      WHEN 'keeper' THEN 'Keeper'
+      WHEN 'bitwarden' THEN 'Bitwarden'
+      ELSE 'vault provider' END;
+    SELECT connection.id, connection.subject_id, connection.status, connection.metadata
+    INTO connection_row
+    FROM connections connection
+    WHERE connection.id = connection_ref
+      AND connection.account_id = (context ->> 'accountId')::uuid
+      AND connection.workspace_id = (context ->> 'workspaceId')::uuid
+      AND connection.kind = 'api_key'
+      AND CASE WHEN link_source = 'onepassword' THEN
+          pg_catalog.lower(connection.provider_domain) = '1password.com'
+          AND connection.metadata ->> 'credentialRole' = 'onepassword_service_account'
+        ELSE
+          connection.provider_domain = 'vault:' || link_source
+          AND connection.metadata ->> 'credentialRole' = 'external_vault_provider'
+          AND connection.metadata #>> '{vaultProvider,provider}' = link_source
+          AND connection.metadata #>> '{vaultProvider,version}' = '1'
+        END;
+    IF connection_row.id IS NULL OR connection_row.status = 'revoked' THEN
+      PERFORM opengeni_private.vault_raise('vault_not_found', provider_label || ' connection not found');
+    END IF;
+    IF connection_row.status <> 'active'
+      OR coalesce(connection_row.metadata #>> '{vaultProvider,verificationStatus}', 'ready') <> 'ready' THEN
+      PERFORM opengeni_private.vault_raise('provider_auth_expired',
+        'the ' || provider_label || ' connection must be verified again before its vaults are linked',
+        pg_catalog.jsonb_build_object('connectionId', connection_row.id));
+    END IF;
+    connection_ownership := CASE
+      WHEN link_source <> 'onepassword' THEN connection_row.metadata #>> '{vaultProvider,ownership}'
+      WHEN connection_row.subject_id IS NOT NULL THEN 'user'
+      WHEN connection_row.metadata ->> 'ownership' = 'organization' THEN 'organization'
+      WHEN connection_row.metadata ->> 'ownership' = 'user' THEN NULL
+      ELSE 'workspace' END;
+    IF connection_ownership IS NULL
+      OR connection_ownership NOT IN ('user', 'workspace', 'organization')
+      OR (connection_ownership = 'user') <> (connection_row.subject_id IS NOT NULL) THEN
+      PERFORM opengeni_private.vault_raise('vault_permission_denied',
+        'the ' || provider_label || ' connection has no consistent owner',
+        pg_catalog.jsonb_build_object('connectionId', connection_row.id));
+    END IF;
+    IF connection_ownership = 'user' AND (
+      owner_kind <> 'user' OR connection_row.subject_id IS DISTINCT FROM context ->> 'subjectId'
+    ) THEN
+      PERFORM opengeni_private.vault_raise('vault_permission_denied',
+        'a personal ' || provider_label || ' connection backs only its owner''s Only-me vaults');
+    END IF;
+    IF connection_ownership <> owner_kind THEN
+      PERFORM opengeni_private.vault_raise('vault_permission_denied',
+        'a ' || connection_ownership || ' ' || provider_label || ' connection backs only '
+          || connection_ownership || ' vaults',
+        pg_catalog.jsonb_build_object('connectionId', connection_row.id,
+          'connectionOwnership', connection_ownership, 'ownerKind', owner_kind));
+    END IF;
+  ELSE
+$new$]
+]);
+
+-- Mirror replacement: a complete inventory of at most 2,000 items, applied
+-- under the vault row lock, and every replacement advances the cache epoch.
+-- The lock is FOR NO KEY UPDATE, the strength the routine's own final UPDATE
+-- of the vault takes anyway, so it adds no new conflicts: it is only taken
+-- before the mirror is read rather than after it is rewritten. Every later
+-- statement sees what a replacement that held the lock before committed.
+SELECT pg_temp.patch_vault_routine_0786('upsert_provider_vault_items(uuid,text,jsonb,jsonb)'::regprocedure, ARRAY[
+  ARRAY[$old$  kept_refs := ARRAY(SELECT element ->> 'providerItemRef'
+$old$,
+    $new$  SELECT locked.* INTO vault_row FROM vaults locked
+  WHERE locked.id = vault_row.id
+  FOR NO KEY UPDATE OF locked;
+  IF vault_row.id IS NULL THEN
+    PERFORM opengeni_private.vault_raise('vault_not_found', 'vault not found');
+  ELSIF vault_row.source = 'opengeni' THEN
+    PERFORM opengeni_private.vault_raise('vault_permission_denied', 'only connected vaults have a provider mirror');
+  END IF;
+  IF pg_catalog.jsonb_typeof(coalesce(p_items, '[]'::jsonb)) <> 'array' THEN
+    PERFORM opengeni_private.vault_raise('provider_inventory_incomplete',
+      'the provider inventory is malformed; the previous inventory was kept');
+  ELSIF pg_catalog.jsonb_array_length(p_items) > 2000 THEN
+    PERFORM opengeni_private.vault_raise('provider_inventory_incomplete',
+      'a connected vault mirrors at most 2000 items; the previous inventory was kept',
+      pg_catalog.jsonb_build_object('vaultId', vault_row.id, 'limit', 2000));
+  END IF;
+  kept_refs := ARRAY(SELECT element ->> 'providerItemRef'
+$new$],
+  ARRAY[$old$  UPDATE vaults SET provider_content_version = p_content_version, last_synced_at = pg_catalog.now(),
+$old$,
+    $new$  UPDATE vaults SET provider_content_version = p_content_version, last_synced_at = pg_catalog.now(),
+    provider_cache_epoch = provider_cache_epoch + 1,
+$new$]
+]);
+
+-- Sync status also records the provider's effective operations and its own
+-- freshness observation (both optional; a JSON null clears them).
+SELECT pg_temp.patch_vault_routine_0786('set_vault_sync_status(uuid,jsonb,jsonb)'::regprocedure, ARRAY[
+  ARRAY[$old$  UPDATE vaults SET
+    sync_status = p ->> 'status',
+$old$,
+    $new$  IF p ? 'operations' AND (
+    pg_catalog.jsonb_typeof(p -> 'operations') NOT IN ('object', 'null')
+    OR pg_catalog.octet_length((p -> 'operations')::text) > 4096) THEN
+    PERFORM opengeni_private.vault_raise('vault_permission_denied',
+      'provider operations must be a small JSON object');
+  END IF;
+  IF p ? 'freshness' AND (
+    pg_catalog.jsonb_typeof(p -> 'freshness') NOT IN ('object', 'null')
+    OR pg_catalog.octet_length((p -> 'freshness')::text) > 1024) THEN
+    PERFORM opengeni_private.vault_raise('vault_permission_denied',
+      'provider freshness must be a small JSON object');
+  END IF;
+  UPDATE vaults SET
+    sync_status = p ->> 'status',
+$new$],
+  ARRAY[$old$    last_synced_at = CASE WHEN p ->> 'status' = 'ok' THEN pg_catalog.now() ELSE last_synced_at END,
+$old$,
+    $new$    last_synced_at = CASE WHEN p ->> 'status' = 'ok' THEN pg_catalog.now() ELSE last_synced_at END,
+    provider_operations = CASE WHEN p ? 'operations'
+      THEN nullif(p -> 'operations', 'null'::jsonb) ELSE provider_operations END,
+    provider_freshness = CASE WHEN p ? 'freshness'
+      THEN nullif(p -> 'freshness', 'null'::jsonb) ELSE provider_freshness END,
+$new$]
+]);
+
+-- What a sync, a read and a resolution need to key provider value caches.
+-- Settle a refresh under one compare-and-set fence. Provider versions are
+-- opaque: the cache epoch observed before I/O is the only ordering token.
+-- Every settlement advances it, including unchanged checks and failures.
+-- A late result changes neither the mirror nor the newer status/freshness.
+-- The optional mirror uses the same canonical writer in this transaction;
+-- its capability closes on return, so reopen ours before the status UPDATE.
+SELECT pg_temp.patch_vault_routine_0786('set_vault_sync_status(uuid,jsonb,jsonb)'::regprocedure, ARRAY[
+  ARRAY[$old$  IF p ? 'operations' AND (
+$old$,
+    $new$  SELECT locked.* INTO vault_row FROM vaults locked
+  WHERE locked.id = vault_row.id FOR NO KEY UPDATE OF locked;
+  IF vault_row.id IS NULL THEN
+    PERFORM opengeni_private.vault_raise('vault_not_found', 'vault not found');
+  END IF;
+  IF p ? 'expectedCacheEpoch'
+    AND (p ->> 'expectedCacheEpoch')::bigint IS DISTINCT FROM vault_row.provider_cache_epoch THEN
+    PERFORM opengeni_private.vault_raise('provider_conflict',
+      'another refresh settled first; this late inventory was not applied',
+      pg_catalog.jsonb_build_object('vaultId', vault_row.id, 'superseded', true));
+  END IF;
+  IF p ? 'operations' AND (
+$new$],
+  ARRAY[$old$  UPDATE vaults SET
+    sync_status = p ->> 'status',
+$old$,
+    $new$  IF p ? 'mirror' THEN
+    IF NOT (p ? 'expectedCacheEpoch') THEN
+      PERFORM opengeni_private.vault_raise('provider_conflict',
+        'atomic refresh settlement requires its pre-I/O cache epoch');
+    END IF;
+    IF p ->> 'status' IS DISTINCT FROM 'ok' OR pg_catalog.jsonb_typeof(p -> 'mirror') <> 'object' THEN
+      PERFORM opengeni_private.vault_raise('provider_inventory_incomplete',
+        'only a successful refresh may replace the inventory');
+    END IF;
+    PERFORM upsert_provider_vault_items(p_vault, p #>> '{mirror,contentVersion}',
+      p #> '{mirror,items}', p_principal);
+    PERFORM opengeni_private.vault_capability_open('write');
+  END IF;
+  UPDATE vaults SET
+    provider_cache_epoch = provider_cache_epoch + CASE WHEN p ? 'mirror' THEN 0 ELSE 1 END,
+    sync_status = p ->> 'status',
+$new$]
+]);
+
+SELECT pg_temp.patch_vault_routine_0786('provider_vault_sync_target(uuid,jsonb)'::regprocedure, ARRAY[
+  ARRAY[$old$    'providerContentVersion', vault_row.provider_content_version,
+$old$,
+    $new$    'providerContentVersion', vault_row.provider_content_version,
+    'providerCacheEpoch', vault_row.provider_cache_epoch::text,
+$new$]
+]);
+SELECT pg_temp.patch_vault_routine_0786('read_vault_field_ciphertext(uuid,integer,text,jsonb,jsonb)'::regprocedure, ARRAY[
+  ARRAY[$old$    'providerVaultRef', vault_row.provider_vault_ref,
+$old$,
+    $new$    'providerVaultRef', vault_row.provider_vault_ref,
+    'providerCacheEpoch', vault_row.provider_cache_epoch::text,
+$new$]
+]);
+SELECT pg_temp.patch_vault_routine_0786('resolve_secret_reference_candidates(jsonb,jsonb)'::regprocedure, ARRAY[
+  ARRAY[$old$    'providerVaultRef', vault.provider_vault_ref,
+$old$,
+    $new$    'providerVaultRef', vault.provider_vault_ref,
+    'providerCacheEpoch', vault.provider_cache_epoch::text,
+$new$]
+]);
+
+DROP FUNCTION pg_temp.patch_vault_routine_0786(regprocedure, text[]);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opengeni/db",
-  "version": "3.1.3-canary.38890816741001",
+  "version": "3.2.2",
   "description": "Opengeni persistence: Drizzle schema, RLS-scoped query layer, the SQL migration runner, and role provisioning.",
   "license": "Apache-2.0",
   "repository": {
@@ -117,14 +117,14 @@
     "prepublishOnly": "bash ../../scripts/prepublish-guard"
   },
   "dependencies": {
-    "@opengeni/codemode": "3.1.3-canary.38890816741001",
-    "@opengeni/codex": "3.1.3-canary.38890816741001",
-    "@opengeni/config": "3.1.3-canary.38890816741001",
-    "@opengeni/contracts": "3.1.3-canary.38890816741001",
-    "@opengeni/network": "3.1.3-canary.38890816741001",
-    "@opengeni/observability": "3.1.3-canary.38890816741001",
-    "@opengeni/subscriptions": "3.1.3-canary.38890816741001",
-    "@opengeni/xai-subscription": "3.1.3-canary.38890816741001",
+    "@opengeni/codemode": "3.2.2",
+    "@opengeni/codex": "3.2.2",
+    "@opengeni/config": "3.2.2",
+    "@opengeni/contracts": "3.2.2",
+    "@opengeni/network": "3.2.2",
+    "@opengeni/observability": "3.2.2",
+    "@opengeni/subscriptions": "3.2.2",
+    "@opengeni/xai-subscription": "3.2.2",
     "drizzle-orm": "^0.45.2",
     "postgres": "^3.4.7"
   },

package/src/index.ts

@@ -56039,6 +56039,11 @@ export async function claimWorkspaceArchiveCapture(
      * exact box are recorded in deadline_forced_admission_ids, captured
      * around, and settled with the box after termination. */
     deadlineMandatoryCaptureLeadMs?: number;
+    /** Draining only: unsettled setup requests whose provider Start outcome
+     * is unknown, owned by a turn attempt closed at least this long ago with
+     * no active retained process, are captured around exactly like the
+     * mandatory pre-deadline save instead of pinning the box until then. */
+    abandonedSetupCaptureAfterMs?: number;
     /** Warm point-in-time checkpoint of a box no turn holds, kept warm by
      * viewers, browser/computer interactions or active background commands
      * (supervised or not) (e.g. while the session waits for one or for input). Requires
@@ -56341,27 +56346,86 @@ export async function claimWorkspaceArchiveCapture(
           order by admission.id
       `);
       if (unsettled.length > 0) {
-        // Any requested rotation counts: an earlier operator rotation keeps the
-        // due provider-deadline rotation from being stamped separately.
+        // Close to the provider deadline a drain must save now. Due rotations
+        // are only stamped on warm leases, so a lease that was already
+        // draining (no holder left) never gets one; requiring it let such a
+        // box be killed uncaptured at the deadline. This branch is draining
+        // only, so the deadline alone decides.
         const lead = input.deadlineMandatoryCaptureLeadMs;
         const [deadline] =
           input.liveness === "draining" && lead !== undefined && Number.isSafeInteger(lead)
             ? await scopedDb.execute<{ mandatory: boolean }>(sql`
                 select (
-                  ${row.rotation_requested_at !== null}
-                  and ${row.provider_deadline_at ?? null}::timestamptz is not null
+                  ${row.provider_deadline_at ?? null}::timestamptz is not null
                   and ${row.provider_deadline_at ?? null}::timestamptz
                     <= now() + (${lead}::bigint * interval '1 millisecond')
                 ) as mandatory
               `)
             : [];
-        if (deadline?.mandatory !== true) {
+        // A setup request whose provider Start outcome is unknown can never
+        // settle on a live box: no exit can be observed for it, and its turn
+        // waits (recovering) for the box to be gone. Waiting for the deadline
+        // kept a box with no holder running for a day. Once its owner attempt
+        // has been closed for the abandonment window, with no retained process
+        // of that attempt, capture around exactly these setup requests;
+        // termination then settles them and the turn's ended-epoch recovery
+        // resumes it on the saved workspace. Only a point-in-time (Modal
+        // snapshot) capture may run around a request that might still be
+        // writing; a file-by-file tar read keeps waiting for the deadline.
+        const abandonAfterMs = input.abandonedSetupCaptureAfterMs;
+        const [abandoned] =
+          deadline?.mandatory !== true &&
+          input.liveness === "draining" &&
+          input.pointInTimeCapture === true &&
+          abandonAfterMs !== undefined &&
+          Number.isSafeInteger(abandonAfterMs) &&
+          abandonAfterMs > 0
+            ? await scopedDb.execute<{ abandoned: boolean }>(sql`
+                select coalesce(bool_and(coalesce(
+                  admission.actor_kind = 'turn'
+                  and admission.actor_id = attempt.id
+                  and admission.operation in ('lazyOwnedSandboxSetup', 'eagerOwnedSandboxSetup')
+                  and admission.route_kind = 'home'
+                  and admission.route_target_id is null
+                  and attempt.state = 'closed'
+                  and attempt.closed_at
+                    <= now() - (${abandonAfterMs}::bigint * interval '1 millisecond')
+                  and turn.status = 'recovering'
+                  and turn.active_attempt_id is null
+                  and turn.execution_generation = attempt.execution_generation
+                  and turn.metadata -> 'sandboxSetupOutcomeUnknown' @> jsonb_build_object(
+                    'version', 1, 'turnId', turn.id::text, 'attemptId', attempt.id::text,
+                    'reason', 'sandbox_command_start_outcome_unknown')
+                  and not exists (select 1 from sandbox_retained_processes process
+                    where process.workspace_id = attempt.workspace_id
+                      and process.session_id = attempt.session_id
+                      and process.owner_attempt_id = attempt.id
+                      and process.state = 'active'),
+                  false)), false) as abandoned
+                from sandbox_workspace_mutation_admissions admission
+                left join session_turn_attempts attempt
+                  on attempt.account_id = admission.account_id
+                 and attempt.workspace_id = admission.workspace_id
+                 and attempt.session_id = admission.session_id
+                 and attempt.turn_id = admission.turn_id
+                 and attempt.id = admission.attempt_id
+                 and attempt.execution_generation = admission.execution_generation
+                left join session_turns turn
+                  on turn.workspace_id = attempt.workspace_id
+                 and turn.session_id = attempt.session_id
+                 and turn.id = attempt.turn_id
+                where admission.id = any(${`{${unsettled
+                  .map((admission: { id: string }) => admission.id)
+                  .join(",")}}`}::uuid[])
+              `)
+            : [];
+        if (deadline?.mandatory !== true && abandoned?.abandoned !== true) {
           return { status: "mutation_in_progress" as const };
         }
-        // Mandatory pre-deadline save: no holder is left on the box (checked
-        // above), so these requests cannot finish into a capture in time.
-        // Record exactly them; publication excludes them, and the cold commit
-        // settles them only after the box is terminated.
+        // Mandatory save: no holder is left on the box (checked above), so
+        // these requests cannot finish into a capture in time. Record exactly
+        // them; publication excludes them, and the cold commit settles them
+        // only after the box is terminated.
         await scopedDb.execute(sql`
           update sandbox_leases set deadline_forced_admission_ids = ${`{${[
             ...forcedAdmissionIds,