@opengeni/db 0.31.1 → 0.36.0

package/drizzle/0218_organization_tenancy_foundation.sql

@@ -0,0 +1,299 @@
+-- deployment-mode: rolling
+-- Additive organization-tenancy Slice A foundation only. This migration names
+-- durable organization membership, user-resource authority/grant identity,
+-- retention policy, and generic session visibility/fork provenance. It does
+-- not move an existing resource, grant runtime access, or activate sharing.
+
+SET LOCAL lock_timeout = '5s';
+SET LOCAL statement_timeout = '10min';
+
+CREATE TABLE "organization_memberships" (
+  "id" uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+  "account_id" uuid NOT NULL REFERENCES "managed_accounts"("id") ON DELETE CASCADE,
+  "subject_id" text NOT NULL,
+  "status" text NOT NULL DEFAULT 'provisioning',
+  "personal_workspace_id" uuid,
+  "authorization_revision" bigint NOT NULL DEFAULT 1,
+  "revoked_at" timestamptz,
+  "personal_retention_until" timestamptz,
+  "created_at" timestamptz NOT NULL DEFAULT now(),
+  "updated_at" timestamptz NOT NULL DEFAULT now(),
+  CONSTRAINT "organization_memberships_status_check" CHECK (
+    "status" IN ('provisioning', 'active', 'suspended', 'revoked')
+  ),
+  CONSTRAINT "organization_memberships_active_personal_workspace_check" CHECK (
+    "status" <> 'active' OR "personal_workspace_id" IS NOT NULL
+  ),
+  CONSTRAINT "organization_memberships_subject_check" CHECK (
+    length(btrim("subject_id")) BETWEEN 1 AND 1024
+  ),
+  CONSTRAINT "organization_memberships_revision_check" CHECK (
+    "authorization_revision" > 0
+  ),
+  CONSTRAINT "organization_memberships_revocation_check" CHECK (
+    ("status" = 'revoked' AND "revoked_at" IS NOT NULL)
+    OR ("status" <> 'revoked' AND "revoked_at" IS NULL)
+  ),
+  CONSTRAINT "organization_memberships_personal_workspace_account_fk"
+    FOREIGN KEY ("personal_workspace_id", "account_id")
+    REFERENCES "workspaces"("id", "account_id") ON DELETE RESTRICT
+);
+
+CREATE UNIQUE INDEX "organization_memberships_id_account_idx"
+  ON "organization_memberships" ("id", "account_id");
+CREATE UNIQUE INDEX "organization_memberships_account_subject_idx"
+  ON "organization_memberships" ("account_id", "subject_id");
+CREATE UNIQUE INDEX "organization_memberships_personal_workspace_idx"
+  ON "organization_memberships" ("account_id", "personal_workspace_id")
+  WHERE "personal_workspace_id" IS NOT NULL;
+
+CREATE TABLE "organization_user_retention_policies" (
+  "account_id" uuid PRIMARY KEY REFERENCES "managed_accounts"("id") ON DELETE CASCADE,
+  "mode" text NOT NULL DEFAULT 'retain',
+  "retention_days" integer,
+  "version" bigint NOT NULL DEFAULT 1,
+  "updated_by_membership_id" uuid,
+  "updated_at" timestamptz NOT NULL DEFAULT now(),
+  CONSTRAINT "organization_user_retention_policies_updater_fk"
+    FOREIGN KEY ("updated_by_membership_id", "account_id")
+    REFERENCES "organization_memberships"("id", "account_id") ON DELETE RESTRICT,
+  CONSTRAINT "organization_user_retention_policies_mode_check" CHECK (
+    "mode" IN ('retain', 'delete_after')
+  ),
+  CONSTRAINT "organization_user_retention_policies_duration_check" CHECK (
+    ("mode" = 'retain' AND "retention_days" IS NULL)
+    OR (
+      "mode" = 'delete_after'
+      AND "retention_days" IS NOT NULL
+      AND "retention_days" BETWEEN 1 AND 3650
+    )
+  ),
+  CONSTRAINT "organization_user_retention_policies_version_check" CHECK (
+    "version" > 0
+  )
+);
+
+CREATE TABLE "organization_user_resource_authorities" (
+  "id" uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+  "account_id" uuid NOT NULL REFERENCES "managed_accounts"("id") ON DELETE CASCADE,
+  "organization_membership_id" uuid NOT NULL,
+  "resource_kind" text NOT NULL,
+  "resource_id" uuid NOT NULL,
+  "origin_workspace_id" uuid,
+  "generation" bigint NOT NULL DEFAULT 1,
+  "status" text NOT NULL DEFAULT 'active',
+  "revoked_at" timestamptz,
+  "created_at" timestamptz NOT NULL DEFAULT now(),
+  "updated_at" timestamptz NOT NULL DEFAULT now(),
+  CONSTRAINT "organization_user_resource_authorities_membership_fk"
+    FOREIGN KEY ("organization_membership_id", "account_id")
+    REFERENCES "organization_memberships"("id", "account_id") ON DELETE RESTRICT,
+  CONSTRAINT "organization_user_resource_authorities_origin_workspace_fk"
+    FOREIGN KEY ("origin_workspace_id", "account_id")
+    REFERENCES "workspaces"("id", "account_id")
+    ON DELETE SET NULL ("origin_workspace_id"),
+  CONSTRAINT "organization_user_resource_authorities_kind_check" CHECK (
+    "resource_kind" = lower(btrim("resource_kind"))
+    AND length("resource_kind") BETWEEN 1 AND 64
+    AND "resource_kind" ~ '^[a-z0-9](?:[a-z0-9._-]*[a-z0-9])?$'
+  ),
+  CONSTRAINT "organization_user_resource_authorities_generation_check" CHECK (
+    "generation" > 0
+  ),
+  CONSTRAINT "organization_user_resource_authorities_status_check" CHECK (
+    "status" IN ('active', 'retained', 'revoked')
+  ),
+  CONSTRAINT "organization_user_resource_authorities_revocation_check" CHECK (
+    ("status" = 'revoked' AND "revoked_at" IS NOT NULL)
+    OR ("status" <> 'revoked' AND "revoked_at" IS NULL)
+  )
+);
+
+CREATE UNIQUE INDEX "organization_user_resource_authorities_id_account_idx"
+  ON "organization_user_resource_authorities" ("id", "account_id");
+CREATE UNIQUE INDEX "organization_user_resource_authorities_id_account_membership_idx"
+  ON "organization_user_resource_authorities" ("id", "account_id", "organization_membership_id");
+CREATE UNIQUE INDEX "organization_user_resource_authorities_resource_identity_idx"
+  ON "organization_user_resource_authorities" (
+    "account_id",
+    "organization_membership_id",
+    "resource_kind",
+    "resource_id"
+  );
+
+-- Existing sessions remain explicitly workspace-owned/workspace-visible. Null
+-- owner and fork facts are non-authority; epoch 1 is the legacy baseline.
+ALTER TABLE "sessions"
+  ADD COLUMN IF NOT EXISTS "owner_organization_membership_id" uuid,
+  ADD COLUMN IF NOT EXISTS "visibility" text NOT NULL DEFAULT 'workspace_shared',
+  ADD COLUMN IF NOT EXISTS "authority_epoch" integer NOT NULL DEFAULT 1,
+  ADD COLUMN IF NOT EXISTS "forked_from_session_id" uuid,
+  ADD COLUMN IF NOT EXISTS "forked_from_authority_epoch" integer,
+  ADD COLUMN IF NOT EXISTS "forked_from_visibility" text,
+  ADD COLUMN IF NOT EXISTS "forked_at" timestamptz,
+  ADD COLUMN IF NOT EXISTS "forked_by_organization_membership_id" uuid;
+
+CREATE UNIQUE INDEX IF NOT EXISTS "sessions_id_account_idx"
+  ON "sessions" ("id", "account_id");
+
+ALTER TABLE "sessions"
+  ADD CONSTRAINT "sessions_owner_organization_membership_fk"
+    FOREIGN KEY ("owner_organization_membership_id", "account_id")
+    REFERENCES "organization_memberships"("id", "account_id") ON DELETE RESTRICT NOT VALID,
+  ADD CONSTRAINT "sessions_forked_from_session_account_fk"
+    FOREIGN KEY ("forked_from_session_id", "account_id")
+    REFERENCES "sessions"("id", "account_id") ON DELETE RESTRICT NOT VALID,
+  ADD CONSTRAINT "sessions_forked_by_organization_membership_fk"
+    FOREIGN KEY ("forked_by_organization_membership_id", "account_id")
+    REFERENCES "organization_memberships"("id", "account_id") ON DELETE RESTRICT NOT VALID,
+  ADD CONSTRAINT "sessions_visibility_check" CHECK (
+    "visibility" IN ('user_private', 'workspace_shared')
+  ) NOT VALID,
+  ADD CONSTRAINT "sessions_private_owner_check" CHECK (
+    "visibility" <> 'user_private' OR "owner_organization_membership_id" IS NOT NULL
+  ) NOT VALID,
+  ADD CONSTRAINT "sessions_authority_epoch_check" CHECK (
+    "authority_epoch" > 0
+  ) NOT VALID,
+  ADD CONSTRAINT "sessions_fork_provenance_check" CHECK (
+    (
+      "forked_from_session_id" IS NULL
+      AND "forked_from_authority_epoch" IS NULL
+      AND "forked_from_visibility" IS NULL
+      AND "forked_at" IS NULL
+      AND "forked_by_organization_membership_id" IS NULL
+    ) OR (
+      "forked_from_session_id" IS NOT NULL
+      AND "forked_from_authority_epoch" IS NOT NULL
+      AND "forked_from_authority_epoch" > 0
+      AND "forked_from_visibility" IN ('user_private', 'workspace_shared')
+      AND "forked_at" IS NOT NULL
+      AND "forked_by_organization_membership_id" IS NOT NULL
+    )
+  ) NOT VALID;
+
+ALTER TABLE "sessions"
+  VALIDATE CONSTRAINT "sessions_owner_organization_membership_fk",
+  VALIDATE CONSTRAINT "sessions_forked_from_session_account_fk",
+  VALIDATE CONSTRAINT "sessions_forked_by_organization_membership_fk",
+  VALIDATE CONSTRAINT "sessions_visibility_check",
+  VALIDATE CONSTRAINT "sessions_private_owner_check",
+  VALIDATE CONSTRAINT "sessions_authority_epoch_check",
+  VALIDATE CONSTRAINT "sessions_fork_provenance_check";
+
+CREATE TABLE "organization_user_resource_grants" (
+  "id" uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+  "account_id" uuid NOT NULL REFERENCES "managed_accounts"("id") ON DELETE CASCADE,
+  "authority_id" uuid NOT NULL,
+  "owner_organization_membership_id" uuid NOT NULL,
+  "workspace_id" uuid NOT NULL,
+  "session_id" uuid,
+  "action" text NOT NULL,
+  "mode" text NOT NULL,
+  "context" text NOT NULL,
+  "authority_epoch" integer,
+  "generation" bigint NOT NULL DEFAULT 1,
+  "status" text NOT NULL DEFAULT 'active',
+  "expires_at" timestamptz,
+  "revoked_at" timestamptz,
+  "created_at" timestamptz NOT NULL DEFAULT now(),
+  "updated_at" timestamptz NOT NULL DEFAULT now(),
+  CONSTRAINT "organization_user_resource_grants_authority_fk"
+    FOREIGN KEY ("authority_id", "account_id")
+    REFERENCES "organization_user_resource_authorities"("id", "account_id")
+    ON DELETE RESTRICT,
+  CONSTRAINT "organization_user_resource_grants_owner_membership_fk"
+    FOREIGN KEY ("owner_organization_membership_id", "account_id")
+    REFERENCES "organization_memberships"("id", "account_id") ON DELETE RESTRICT,
+  CONSTRAINT "organization_user_resource_grants_authority_owner_fk"
+    FOREIGN KEY ("authority_id", "account_id", "owner_organization_membership_id")
+    REFERENCES "organization_user_resource_authorities"(
+      "id", "account_id", "organization_membership_id"
+    ) ON DELETE RESTRICT,
+  CONSTRAINT "organization_user_resource_grants_workspace_account_fk"
+    FOREIGN KEY ("workspace_id", "account_id")
+    REFERENCES "workspaces"("id", "account_id") ON DELETE CASCADE,
+  CONSTRAINT "organization_user_resource_grants_session_workspace_fk"
+    FOREIGN KEY ("workspace_id", "session_id")
+    REFERENCES "sessions"("workspace_id", "id") ON DELETE RESTRICT,
+  CONSTRAINT "organization_user_resource_grants_action_check" CHECK (
+    "action" = lower(btrim("action"))
+    AND length("action") BETWEEN 1 AND 64
+    AND "action" ~ '^[a-z0-9](?:[a-z0-9._:-]*[a-z0-9])?$'
+  ),
+  CONSTRAINT "organization_user_resource_grants_mode_check" CHECK (
+    "mode" IN ('once', 'session', 'always')
+  ),
+  CONSTRAINT "organization_user_resource_grants_context_check" CHECK (
+    "context" IN ('user_private', 'workspace_shared')
+  ),
+  CONSTRAINT "organization_user_resource_grants_session_fence_check" CHECK (
+    (
+      "mode" = 'always'
+      AND "session_id" IS NULL
+      AND "authority_epoch" IS NULL
+    ) OR (
+      "mode" IN ('once', 'session')
+      AND
+      "session_id" IS NOT NULL
+      AND "authority_epoch" IS NOT NULL
+      AND "authority_epoch" > 0
+    )
+  ),
+  CONSTRAINT "organization_user_resource_grants_generation_check" CHECK (
+    "generation" > 0
+  ),
+  CONSTRAINT "organization_user_resource_grants_status_check" CHECK (
+    "status" IN ('active', 'consumed', 'revoked', 'expired')
+  ),
+  CONSTRAINT "organization_user_resource_grants_revocation_check" CHECK (
+    ("status" = 'revoked' AND "revoked_at" IS NOT NULL)
+    OR ("status" <> 'revoked' AND "revoked_at" IS NULL)
+  )
+);
+
+CREATE UNIQUE INDEX "organization_user_resource_grants_id_account_idx"
+  ON "organization_user_resource_grants" ("id", "account_id");
+CREATE INDEX "organization_user_resource_grants_authority_workspace_idx"
+  ON "organization_user_resource_grants" ("authority_id", "workspace_id", "status");
+
+-- Slice A is intentionally inert. Each table has one explicit system-only
+-- deny-all policy and no direct opengeni_app privileges, so the runtime role
+-- remains denied until a later reviewed dual-write/backfill/validate/activate
+-- slice installs exact behavior.
+ALTER TABLE "organization_memberships" ENABLE ROW LEVEL SECURITY;
+ALTER TABLE "organization_memberships" FORCE ROW LEVEL SECURITY;
+ALTER TABLE "organization_user_retention_policies" ENABLE ROW LEVEL SECURITY;
+ALTER TABLE "organization_user_retention_policies" FORCE ROW LEVEL SECURITY;
+ALTER TABLE "organization_user_resource_authorities" ENABLE ROW LEVEL SECURITY;
+ALTER TABLE "organization_user_resource_authorities" FORCE ROW LEVEL SECURITY;
+ALTER TABLE "organization_user_resource_grants" ENABLE ROW LEVEL SECURITY;
+ALTER TABLE "organization_user_resource_grants" FORCE ROW LEVEL SECURITY;
+
+DROP POLICY IF EXISTS organization_tenancy_system_only ON "organization_memberships";
+CREATE POLICY organization_tenancy_system_only ON "organization_memberships"
+  USING (false) WITH CHECK (false);
+DROP POLICY IF EXISTS organization_tenancy_system_only ON "organization_user_retention_policies";
+CREATE POLICY organization_tenancy_system_only ON "organization_user_retention_policies"
+  USING (false) WITH CHECK (false);
+DROP POLICY IF EXISTS organization_tenancy_system_only ON "organization_user_resource_authorities";
+CREATE POLICY organization_tenancy_system_only ON "organization_user_resource_authorities"
+  USING (false) WITH CHECK (false);
+DROP POLICY IF EXISTS organization_tenancy_system_only ON "organization_user_resource_grants";
+CREATE POLICY organization_tenancy_system_only ON "organization_user_resource_grants"
+  USING (false) WITH CHECK (false);
+
+COMMENT ON TABLE "organization_memberships" IS
+  'Organization membership and personal-workspace lifecycle metadata; not workspace content access.';
+COMMENT ON COLUMN "organization_memberships"."personal_workspace_id" IS
+  'One personal workspace per membership; lifecycle metadata, never user-resource ownership.';
+COMMENT ON TABLE "organization_user_resource_authorities" IS
+  'Stable organization+membership user-resource authority identity; inert in Slice A.';
+COMMENT ON COLUMN "organization_user_resource_authorities"."origin_workspace_id" IS
+  'Non-authoritative provenance only; deletion clears this fact without transferring authority.';
+COMMENT ON TABLE "organization_user_resource_grants" IS
+  'Opaque once/session/always user-resource grant identities; inert in Slice A.';
+COMMENT ON COLUMN "sessions"."visibility" IS
+  'Generic user_private/workspace_shared tenancy visibility; Slice A adds storage only.';
+COMMENT ON COLUMN "sessions"."authority_epoch" IS
+  'Monotonic execution-authority fence for later sharing/fork runtime; Slice A baseline is 1.';

package/drizzle/0219_organization_tenancy_managed_human_provisioning.sql

@@ -0,0 +1,317 @@
+-- deployment-mode: rolling
+-- Activate only the managed-human provisioning seam for organization tenancy.
+-- This migration does not expose organization/member CRUD, resource authority or
+-- grant writes, session sharing, or personal-workspace runtime access.
+
+SET LOCAL lock_timeout = '5s';
+SET LOCAL statement_timeout = '10min';
+
+-- Keep all four Slice A tables FORCE-RLS and replace the inert deny-all policy
+-- with one transaction-local capability marker. The marker is set only inside
+-- the exact SECURITY DEFINER lifecycle routine below; opengeni_app still has
+-- no direct table privileges on any of these tables.
+DROP POLICY IF EXISTS organization_tenancy_system_only ON "organization_memberships";
+CREATE POLICY organization_tenancy_lifecycle ON "organization_memberships"
+  USING (
+    current_setting('opengeni.organization_tenancy_lifecycle', true)
+      = 'managed_human_provisioning'
+  )
+  WITH CHECK (
+    current_setting('opengeni.organization_tenancy_lifecycle', true)
+      = 'managed_human_provisioning'
+  );
+
+DROP POLICY IF EXISTS organization_tenancy_system_only ON "organization_user_retention_policies";
+CREATE POLICY organization_tenancy_lifecycle ON "organization_user_retention_policies"
+  USING (
+    current_setting('opengeni.organization_tenancy_lifecycle', true)
+      = 'managed_human_provisioning'
+  )
+  WITH CHECK (
+    current_setting('opengeni.organization_tenancy_lifecycle', true)
+      = 'managed_human_provisioning'
+  );
+
+DROP POLICY IF EXISTS organization_tenancy_system_only ON "organization_user_resource_authorities";
+CREATE POLICY organization_tenancy_lifecycle ON "organization_user_resource_authorities"
+  USING (
+    current_setting('opengeni.organization_tenancy_lifecycle', true)
+      = 'managed_human_provisioning'
+  )
+  WITH CHECK (
+    current_setting('opengeni.organization_tenancy_lifecycle', true)
+      = 'managed_human_provisioning'
+  );
+
+DROP POLICY IF EXISTS organization_tenancy_system_only ON "organization_user_resource_grants";
+CREATE POLICY organization_tenancy_lifecycle ON "organization_user_resource_grants"
+  USING (
+    current_setting('opengeni.organization_tenancy_lifecycle', true)
+      = 'managed_human_provisioning'
+  )
+  WITH CHECK (
+    current_setting('opengeni.organization_tenancy_lifecycle', true)
+      = 'managed_human_provisioning'
+  );
+
+DO $organization_tenancy_managed_human_provisioning$
+DECLARE
+  data_schema text := current_schema();
+BEGIN
+  EXECUTE format($ddl$
+    CREATE OR REPLACE FUNCTION %1$I.ensure_managed_human_personal_workspace(
+      p_account_id uuid,
+      p_subject_id text,
+      p_personal_workspace_id uuid
+    )
+    RETURNS TABLE (
+      organization_membership_id uuid,
+      personal_workspace_id uuid
+    )
+    LANGUAGE plpgsql
+    SECURITY DEFINER
+    SET search_path = %1$I, pg_catalog
+    AS $body$
+    DECLARE
+      expected_external_id text;
+      membership_row organization_memberships%%ROWTYPE;
+      workspace_row workspaces%%ROWTYPE;
+      previous_workspace_id text := pg_catalog.current_setting(
+        'opengeni.workspace_id',
+        true
+      );
+      previous_lifecycle_marker text := pg_catalog.current_setting(
+        'opengeni.organization_tenancy_lifecycle',
+        true
+      );
+    BEGIN
+      IF p_account_id IS NULL
+        OR p_subject_id IS NULL
+        OR p_personal_workspace_id IS NULL
+      THEN
+        RAISE EXCEPTION 'managed-human provisioning requires complete identity'
+          USING ERRCODE = '42501';
+      END IF;
+
+      IF p_subject_id <> pg_catalog.btrim(p_subject_id)
+        OR pg_catalog.length(p_subject_id) NOT BETWEEN 1 AND 1024
+        OR p_subject_id NOT LIKE 'user:%%'
+      THEN
+        RAISE EXCEPTION 'managed-human provisioning subject is invalid'
+          USING ERRCODE = '42501';
+      END IF;
+
+      expected_external_id := pg_catalog.substr(p_subject_id, 6);
+      IF expected_external_id IS NULL OR pg_catalog.length(expected_external_id) < 1 THEN
+        RAISE EXCEPTION 'managed-human provisioning subject is invalid'
+          USING ERRCODE = '42501';
+      END IF;
+
+      IF p_account_id IS DISTINCT FROM opengeni_private.current_account_id() THEN
+        RAISE EXCEPTION 'managed-human provisioning account authority is invalid'
+          USING ERRCODE = '42501';
+      END IF;
+
+      IF NOT EXISTS (
+        SELECT 1
+        FROM managed_accounts account_row
+        WHERE account_row.id = p_account_id
+          AND account_row.external_source = 'better-auth:user'
+          AND account_row.external_id = expected_external_id
+      ) THEN
+        RAISE EXCEPTION 'managed-human provisioning account identity is invalid'
+          USING ERRCODE = '42501';
+      END IF;
+
+      IF NOT EXISTS (
+        SELECT 1
+        FROM workspace_memberships owner_membership
+        INNER JOIN workspaces owner_workspace
+          ON owner_workspace.id = owner_membership.workspace_id
+         AND owner_workspace.account_id = owner_membership.account_id
+        WHERE owner_membership.account_id = p_account_id
+          AND owner_membership.subject_id = p_subject_id
+          AND owner_membership.role = 'owner'
+      ) THEN
+        RAISE EXCEPTION 'managed-human provisioning owner membership is invalid'
+          USING ERRCODE = '42501';
+      END IF;
+
+      SELECT *
+      INTO workspace_row
+      FROM workspaces candidate_workspace
+      WHERE candidate_workspace.id = p_personal_workspace_id
+      FOR UPDATE;
+      IF NOT FOUND
+        OR workspace_row.account_id IS DISTINCT FROM p_account_id
+        OR workspace_row.external_source IS DISTINCT FROM 'opengeni:organization-membership'
+        OR workspace_row.external_id IS DISTINCT FROM (
+          p_account_id::text || ':' || p_subject_id
+        )
+      THEN
+        RAISE EXCEPTION 'managed-human provisioning personal workspace identity is invalid'
+          USING ERRCODE = '42501';
+      END IF;
+
+      IF EXISTS (
+        SELECT 1
+        FROM workspaces conflicting_workspace
+        WHERE conflicting_workspace.external_source = 'opengeni:organization-membership'
+          AND conflicting_workspace.external_id = (
+            p_account_id::text || ':' || p_subject_id
+          )
+          AND conflicting_workspace.id <> p_personal_workspace_id
+      ) THEN
+        RAISE EXCEPTION 'managed-human provisioning personal workspace identity conflicts'
+          USING ERRCODE = '23505';
+      END IF;
+
+      IF EXISTS (
+        SELECT 1
+        FROM workspace_memberships personal_access
+        WHERE personal_access.workspace_id = p_personal_workspace_id
+      ) THEN
+        RAISE EXCEPTION 'managed-human personal workspace already has runtime access'
+          USING ERRCODE = '42501';
+      END IF;
+
+      -- workspace_inference_controls is FORCE-RLS and needs the exact workspace
+      -- context for this structural validation. Restore the caller context on
+      -- both success and error before returning from this capability.
+      PERFORM pg_catalog.set_config(
+        'opengeni.workspace_id',
+        p_personal_workspace_id::text,
+        true
+      );
+      IF NOT EXISTS (
+        SELECT 1
+        FROM workspace_inference_controls control_row
+        WHERE control_row.workspace_id = p_personal_workspace_id
+          AND control_row.account_id = p_account_id
+      ) THEN
+        RAISE EXCEPTION 'managed-human personal workspace control is missing'
+          USING ERRCODE = '42501';
+      END IF;
+
+      PERFORM pg_catalog.set_config(
+        'opengeni.organization_tenancy_lifecycle',
+        'managed_human_provisioning',
+        true
+      );
+
+      INSERT INTO organization_memberships (
+        account_id,
+        subject_id,
+        status,
+        personal_workspace_id
+      ) VALUES (
+        p_account_id,
+        p_subject_id,
+        'active',
+        p_personal_workspace_id
+      )
+      ON CONFLICT (account_id, subject_id) DO NOTHING;
+
+      SELECT *
+      INTO membership_row
+      FROM organization_memberships candidate_membership
+      WHERE candidate_membership.account_id = p_account_id
+        AND candidate_membership.subject_id = p_subject_id
+      FOR UPDATE;
+      IF NOT FOUND THEN
+        RAISE EXCEPTION 'managed-human organization membership was not created'
+          USING ERRCODE = 'P0002';
+      END IF;
+
+      IF membership_row.status IN ('suspended', 'revoked') THEN
+        RAISE EXCEPTION 'managed-human organization membership is not active'
+          USING ERRCODE = '42501';
+      END IF;
+      IF membership_row.status = 'active'
+        AND membership_row.personal_workspace_id IS DISTINCT FROM p_personal_workspace_id
+      THEN
+        RAISE EXCEPTION 'managed-human organization membership personal workspace conflicts'
+          USING ERRCODE = '23505';
+      END IF;
+      IF membership_row.status = 'provisioning'
+        AND membership_row.personal_workspace_id IS NOT NULL
+        AND membership_row.personal_workspace_id IS DISTINCT FROM p_personal_workspace_id
+      THEN
+        RAISE EXCEPTION 'managed-human organization membership personal workspace conflicts'
+          USING ERRCODE = '23505';
+      END IF;
+
+      IF membership_row.status = 'provisioning' THEN
+        UPDATE organization_memberships
+        SET status = 'active',
+            personal_workspace_id = p_personal_workspace_id,
+            updated_at = pg_catalog.clock_timestamp()
+        WHERE id = membership_row.id;
+        membership_row.status := 'active';
+        membership_row.personal_workspace_id := p_personal_workspace_id;
+      END IF;
+
+      IF membership_row.status <> 'active'
+        OR membership_row.personal_workspace_id IS DISTINCT FROM p_personal_workspace_id
+      THEN
+        RAISE EXCEPTION 'managed-human organization membership did not converge'
+          USING ERRCODE = '42501';
+      END IF;
+
+      PERFORM pg_catalog.set_config(
+        'opengeni.workspace_id',
+        CASE
+          WHEN previous_workspace_id IS NULL THEN ''
+          ELSE previous_workspace_id
+        END,
+        true
+      );
+      PERFORM pg_catalog.set_config(
+        'opengeni.organization_tenancy_lifecycle',
+        CASE
+          WHEN previous_lifecycle_marker IS NULL THEN ''
+          ELSE previous_lifecycle_marker
+        END,
+        true
+      );
+
+      organization_membership_id := membership_row.id;
+      personal_workspace_id := membership_row.personal_workspace_id;
+      RETURN NEXT;
+    EXCEPTION WHEN OTHERS THEN
+      PERFORM pg_catalog.set_config(
+        'opengeni.workspace_id',
+        CASE
+          WHEN previous_workspace_id IS NULL THEN ''
+          ELSE previous_workspace_id
+        END,
+        true
+      );
+      PERFORM pg_catalog.set_config(
+        'opengeni.organization_tenancy_lifecycle',
+        CASE
+          WHEN previous_lifecycle_marker IS NULL THEN ''
+          ELSE previous_lifecycle_marker
+        END,
+        true
+      );
+      RAISE;
+    END;
+    $body$;
+  $ddl$, data_schema);
+
+  EXECUTE format(
+    'REVOKE ALL ON FUNCTION %I.ensure_managed_human_personal_workspace(uuid,text,uuid) FROM PUBLIC',
+    data_schema
+  );
+  IF EXISTS (SELECT 1 FROM pg_roles WHERE rolname = 'opengeni_app') THEN
+    EXECUTE format(
+      'GRANT EXECUTE ON FUNCTION %I.ensure_managed_human_personal_workspace(uuid,text,uuid) TO opengeni_app',
+      data_schema
+    );
+  END IF;
+END
+$organization_tenancy_managed_human_provisioning$;
+
+COMMENT ON FUNCTION ensure_managed_human_personal_workspace(uuid, text, uuid) IS
+  'Lifecycle-only managed-human organization membership and personal-workspace provisioning; no workspace access grant.';