@opengeni/db 4.4.0-canary.0 → 4.4.0-canary.2

package/drizzle/0462_agent_instruction_non_destructive_edits.sql

@@ -0,0 +1,212 @@
+-- deployment-mode: rolling
+-- Old application instances omit editMode and retain their complete-content
+-- replacement behavior. New instances require an explicit append/edit/replace
+-- choice, so the normal append path cannot erase an active instruction.
+
+CREATE OR REPLACE FUNCTION agent_instruction_apply(p_account uuid,p_workspace uuid,p_actor jsonb,p_request jsonb)
+RETURNS jsonb LANGUAGE plpgsql SECURITY DEFINER SET search_path FROM CURRENT AS $$
+<<instruction_change>>
+DECLARE actor jsonb; mode text; operation text:=p_request->>'operation'; fingerprint text; result jsonb;
+  operation_id uuid:=(p_request->>'operationId')::uuid; revision_id uuid; batch uuid; actor_subject text;
+  target jsonb:=p_request->'target'; context jsonb; expected_revision uuid; expected_version bigint;
+  head workspace_instruction_policy_heads%ROWTYPE; revision workspace_instruction_policy_revisions%ROWTYPE;
+  -- Keep this forward CREATE OR REPLACE compilable in historical partial-replay
+  -- fixtures that predate 0461. Supported deployments have the table before
+  -- this function can execute; the untyped record acquires its row descriptor
+  -- from the SELECT below.
+  prior record; content_hash text; outcome text; link record; version bigint;
+  edit_mode text; requested_content text; old_text text; new_text text; current_content text;
+  resolved_content text; first_position integer; second_position integer;
+BEGIN
+  IF p_account IS DISTINCT FROM nullif(current_setting('opengeni.account_id',true),'')::uuid
+    OR p_workspace IS DISTINCT FROM nullif(current_setting('opengeni.workspace_id',true),'')::uuid THEN
+    RAISE EXCEPTION 'Instruction changes require exact tenant scope' USING ERRCODE='42501';
+  END IF;
+  -- Keep the workspace identity stable without excluding unrelated FK readers.
+  -- Publication serializes on the account advisory lock below before the
+  -- instruction head, matching other Knowledge writers without an advisory /
+  -- workspace-row lock inversion.
+  PERFORM 1 FROM workspaces WHERE id=p_workspace AND account_id=p_account FOR KEY SHARE;
+  actor:=knowledge_resolve_actor(p_account,p_workspace,p_actor);
+  IF operation='get' THEN
+    SELECT * INTO head FROM workspace_instruction_policy_heads h WHERE h.account_id=p_account AND h.workspace_id=p_workspace
+      AND h.kind=target->>'kind' AND h.scope=target->>'scope' AND h.role_key IS NOT DISTINCT FROM target->>'roleKey';
+    SELECT * INTO revision FROM workspace_instruction_policy_revisions r WHERE r.account_id=p_account AND r.workspace_id=p_workspace
+      AND r.id=head.revision_id;
+    RETURN jsonb_build_object('target',target,'expectedCurrentRevisionId',head.revision_id,
+      'expectedActivationVersion',coalesce(head.activation_version,(SELECT max(d.activation_version)
+        FROM workspace_instruction_policy_deactivation_events d WHERE d.account_id=p_account AND d.workspace_id=p_workspace
+          AND d.kind=target->>'kind' AND d.scope=target->>'scope' AND d.role_key IS NOT DISTINCT FROM target->>'roleKey'),0),
+      'content',revision.content);
+  END IF;
+  IF operation='save' THEN
+    IF actor->>'kind'<>'agent' OR (actor->>'defaultScope'='personal' AND get_workspace_kind(p_account,p_workspace)<>'personal') THEN
+      RAISE EXCEPTION 'Workspace instructions require a workspace agent context' USING ERRCODE='42501';
+    END IF;
+    mode:=actor#>>'{policy,effective,instructions}';
+    IF mode NOT IN ('automatic','review_first') OR mode IS NULL THEN
+      RAISE EXCEPTION 'Instruction learning is Off' USING ERRCODE='42501';
+    END IF;
+    actor_subject:='service:agent-learning:'||(p_actor->>'attemptId');
+  ELSE
+    IF actor->>'kind'<>'human' OR NOT coalesce((p_actor->'settingsScopes') ? 'workspace',false) THEN
+      RAISE EXCEPTION 'Instruction review requires workspace administration' USING ERRCODE='42501';
+    END IF;
+    actor_subject:=actor->>'subjectId';
+  END IF;
+  IF operation='list' THEN
+    RETURN (SELECT coalesce(jsonb_agg(item ORDER BY identity),'[]'::jsonb) FROM (
+      SELECT r.id AS identity,jsonb_build_object('revisionId',r.id,'target',jsonb_build_object('kind',r.kind,'scope',r.scope,'roleKey',r.role_key),
+        'content',r.content,'createdAt',r.created_at,'reviewBatchId',knowledge_instruction_context(r)->'reviewBatchId',
+        'sessionId',knowledge_instruction_context(r)#>'{actor,sessionId}','reason',knowledge_instruction_context(r)->'reason') AS item
+      FROM workspace_instruction_policy_revisions r WHERE r.account_id=p_account AND r.workspace_id=p_workspace
+        AND knowledge_instruction_context(r) IS NOT NULL
+        AND NOT EXISTS(SELECT 1 FROM workspace_instruction_policy_activation_events ev WHERE ev.account_id=p_account
+          AND ev.workspace_id=p_workspace AND ev.new_revision_id=r.id)
+        AND NOT EXISTS(SELECT 1 FROM agent_instruction_operations op WHERE op.account_id=p_account AND op.revision_id=r.id
+          AND op.receipt->>'outcome' IN ('published','rejected'))
+        AND NOT EXISTS(SELECT 1 FROM workspace_instruction_policy_revisions newer WHERE newer.account_id=p_account
+          AND newer.workspace_id=p_workspace AND newer.kind=r.kind AND newer.scope=r.scope
+          AND newer.role_key IS NOT DISTINCT FROM r.role_key AND newer.revision>r.revision)
+        AND (NOT(p_request ? 'cursor') OR r.id>(p_request->>'cursor')::uuid)
+      ORDER BY r.id LIMIT 51) visible);
+  END IF;
+  IF operation_id IS NULL OR operation NOT IN ('save','approve','reject') OR length(btrim(p_request->>'reason')) NOT BETWEEN 1 AND 4096 THEN
+    RAISE EXCEPTION 'Invalid instruction change' USING ERRCODE='22023';
+  END IF;
+  IF operation='save' THEN
+    -- Calls from pre-0462 application instances carry complete replacement
+    -- content and omit editMode. Preserve that rolling-deployment contract.
+    edit_mode:=CASE WHEN p_request ? 'editMode' THEN p_request->>'editMode' ELSE 'replace' END;
+    IF edit_mode NOT IN ('append','edit','replace') THEN
+      RAISE EXCEPTION 'Invalid instruction edit mode' USING ERRCODE='22023';
+    END IF;
+    IF edit_mode IN ('append','replace') THEN
+      IF jsonb_typeof(p_request->'content') IS DISTINCT FROM 'string'
+        OR length(p_request->>'content') NOT BETWEEN 1 AND 600
+        OR length(btrim(p_request->>'content'))=0
+        OR p_request ? 'oldText' OR p_request ? 'newText' THEN
+        RAISE EXCEPTION 'Append and replace instruction changes require only non-empty content' USING ERRCODE='22023';
+      END IF;
+      requested_content:=p_request->>'content';
+    ELSE
+      IF p_request ? 'content'
+        OR jsonb_typeof(p_request->'oldText') IS DISTINCT FROM 'string'
+        OR jsonb_typeof(p_request->'newText') IS DISTINCT FROM 'string'
+        OR length(p_request->>'oldText') NOT BETWEEN 1 AND 600
+        OR length(p_request->>'newText')>600 THEN
+        RAISE EXCEPTION 'Exact instruction edits require oldText and newText only' USING ERRCODE='22023';
+      END IF;
+      old_text:=p_request->>'oldText';
+      new_text:=p_request->>'newText';
+    END IF;
+    IF jsonb_typeof(p_request->'evidence') IS DISTINCT FROM 'array' OR jsonb_array_length(p_request->'evidence')>32 THEN
+      RAISE EXCEPTION 'Invalid instruction evidence' USING ERRCODE='22023';
+    END IF;
+  END IF;
+  fingerprint:=encode(sha256(convert_to(jsonb_build_array(
+    CASE WHEN p_actor->>'kind'='agent' THEN p_actor-'attemptId'-'executionGeneration' ELSE p_actor END,
+    p_request)::text,'UTF8')),'hex');
+  SELECT * INTO prior FROM agent_instruction_operations op WHERE op.account_id=p_account AND op.operation_id=instruction_change.operation_id;
+  IF FOUND THEN
+    IF prior.request_hash<>fingerprint OR prior.origin_workspace_id<>p_workspace THEN
+      RAISE EXCEPTION 'Instruction operation key reused' USING ERRCODE='23505'; END IF;
+    RETURN prior.receipt||jsonb_build_object('replayed',true);
+  END IF;
+  IF operation<>'save' THEN
+    SELECT * INTO revision FROM workspace_instruction_policy_revisions r WHERE r.account_id=p_account AND r.workspace_id=p_workspace
+      AND r.id=(p_request->>'revisionId')::uuid AND knowledge_instruction_context(r) IS NOT NULL;
+    IF NOT FOUND OR EXISTS(SELECT 1 FROM agent_instruction_operations op WHERE op.account_id=p_account AND op.revision_id=revision.id
+      AND op.receipt->>'outcome' IN ('published','rejected')) OR EXISTS(SELECT 1 FROM workspace_instruction_policy_revisions newer
+      WHERE newer.account_id=p_account AND newer.workspace_id=p_workspace AND newer.kind=revision.kind AND newer.scope=revision.scope
+        AND newer.role_key IS NOT DISTINCT FROM revision.role_key AND newer.revision>revision.revision) THEN
+      RAISE EXCEPTION 'Instruction review is no longer current' USING ERRCODE='40001'; END IF;
+    revision_id:=revision.id; context:=knowledge_instruction_context(revision);
+    target:=jsonb_build_object('kind',revision.kind,'scope',revision.scope,'roleKey',revision.role_key);
+    expected_revision:=(context->>'expectedCurrentRevisionId')::uuid;
+    expected_version:=(context->>'expectedActivationVersion')::bigint;
+    batch:=(context->>'reviewBatchId')::uuid;
+    outcome:=CASE WHEN operation='approve' THEN 'published' ELSE 'rejected' END;
+  ELSE
+    expected_revision:=(p_request->>'expectedCurrentRevisionId')::uuid;
+    expected_version:=(p_request->>'expectedActivationVersion')::bigint;
+    outcome:=CASE WHEN mode='automatic' THEN 'published' ELSE 'pending' END;
+    IF outcome='pending' THEN batch:=knowledge_review_batch_for_actor(p_account,p_workspace,actor); END IF;
+    context:=jsonb_build_object('actor',p_actor,'policy',actor->'policy','evidence',p_request->'evidence','reason',p_request->'reason',
+      'editMode',edit_mode,'expectedCurrentRevisionId',expected_revision,'expectedActivationVersion',expected_version,'reviewBatchId',batch);
+  END IF;
+  IF operation<>'reject' THEN
+    PERFORM pg_advisory_xact_lock(hashtextextended('knowledge-publication:'||p_account,0));
+  END IF;
+  SELECT * INTO head FROM workspace_instruction_policy_heads h WHERE h.account_id=p_account AND h.workspace_id=p_workspace
+    AND h.kind=target->>'kind' AND h.scope=target->>'scope' AND h.role_key IS NOT DISTINCT FROM target->>'roleKey' FOR UPDATE;
+  version:=coalesce(head.activation_version,(SELECT max(d.activation_version) FROM workspace_instruction_policy_deactivation_events d
+    WHERE d.account_id=p_account AND d.workspace_id=p_workspace AND d.kind=target->>'kind' AND d.scope=target->>'scope'
+      AND d.role_key IS NOT DISTINCT FROM target->>'roleKey'),0);
+  IF operation<>'reject' AND (head.revision_id IS DISTINCT FROM expected_revision OR version IS DISTINCT FROM expected_version) THEN
+    RAISE EXCEPTION 'Instruction head changed; read its current baseline' USING ERRCODE='40001'; END IF;
+  IF operation='save' THEN
+    SELECT r.content INTO current_content FROM workspace_instruction_policy_revisions r
+      WHERE r.account_id=p_account AND r.workspace_id=p_workspace AND r.id=head.revision_id;
+    IF edit_mode='append' THEN
+      resolved_content:=CASE
+        WHEN current_content IS NULL THEN requested_content
+        WHEN right(current_content,2)=E'\n\n' THEN current_content||requested_content
+        WHEN right(current_content,1)=E'\n' THEN current_content||E'\n'||requested_content
+        ELSE current_content||E'\n\n'||requested_content
+      END;
+    ELSIF edit_mode='edit' THEN
+      IF current_content IS NULL THEN
+        RAISE EXCEPTION 'Exact instruction edit requires an active instruction' USING ERRCODE='22023';
+      END IF;
+      first_position:=strpos(current_content,old_text);
+      IF first_position=0 THEN
+        RAISE EXCEPTION 'Exact instruction edit anchor was not found' USING ERRCODE='22023';
+      END IF;
+      second_position:=strpos(substring(current_content FROM first_position+1),old_text);
+      IF second_position>0 THEN
+        RAISE EXCEPTION 'Exact instruction edit anchor is ambiguous' USING ERRCODE='22023';
+      END IF;
+      resolved_content:=overlay(current_content PLACING new_text FROM first_position FOR length(old_text));
+    ELSE
+      resolved_content:=requested_content;
+    END IF;
+    IF length(resolved_content) NOT BETWEEN 1 AND 600 OR length(btrim(resolved_content))=0 THEN
+      RAISE EXCEPTION 'Resulting agent-authored instruction must contain 1 to 600 characters' USING ERRCODE='22023';
+    END IF;
+  END IF;
+  IF operation<>'reject' THEN
+    FOR link IN SELECT * FROM jsonb_array_elements(context->'evidence') LOOP
+      IF NOT EXISTS(SELECT 1 FROM knowledge_entries e WHERE e.account_id=p_account AND e.id=(link.value->>'entryId')::uuid
+        AND NOT e.archived AND e.scope IN ('workspace','organization') AND knowledge_scope_visible(e)
+        AND knowledge_revision_visible(p_account,e.id,(link.value->>'revisionId')::uuid,false)) THEN
+        RAISE EXCEPTION 'Instruction evidence is unavailable to workspace readers' USING ERRCODE='42501'; END IF;
+    END LOOP;
+  END IF;
+  IF operation='save' THEN
+    content_hash:=encode(sha256(convert_to(resolved_content,'UTF8')),'hex');
+    INSERT INTO workspace_instruction_policy_revisions(account_id,workspace_id,operation_id,request_fingerprint,kind,scope,role_key,
+      content,content_hash,provenance_source,provenance_source_id,created_by_subject_id,supersedes_revision_id,agent_learning_context)
+      VALUES(p_account,p_workspace,operation_id,fingerprint,target->>'kind',target->>'scope',target->>'roleKey',resolved_content,
+        content_hash,'agent_learning',p_actor->>'attemptId',actor_subject,expected_revision,context) RETURNING * INTO revision;
+    revision_id:=revision.id;
+  END IF;
+  IF outcome='published' THEN
+    INSERT INTO workspace_instruction_policy_activation_events(account_id,workspace_id,operation_id,request_fingerprint,
+      kind,scope,role_key,type,activation_version,old_revision_id,old_revision,old_content_hash,new_revision_id,new_revision,new_content_hash,
+      actor_subject_id,reason)
+      VALUES(p_account,p_workspace,operation_id,fingerprint,revision.kind,revision.scope,revision.role_key,'activate',version+1,
+        head.revision_id,head.revision,head.content_hash,revision.id,revision.revision,revision.content_hash,actor_subject,p_request->>'reason');
+    IF head.id IS NULL THEN
+      INSERT INTO workspace_instruction_policy_heads(account_id,workspace_id,kind,scope,role_key,revision_id,revision,content_hash,activation_version)
+        VALUES(p_account,p_workspace,revision.kind,revision.scope,revision.role_key,revision.id,revision.revision,revision.content_hash,version+1);
+    ELSE
+      UPDATE workspace_instruction_policy_heads h SET revision_id=revision.id,revision=revision.revision,content_hash=revision.content_hash,
+        activation_version=version+1,activated_at=transaction_timestamp() WHERE h.account_id=p_account AND h.id=head.id;
+    END IF;
+  END IF;
+  result:=jsonb_build_object('operationId',operation_id,'revisionId',revision_id,'outcome',outcome,'reviewBatchId',batch,'replayed',false);
+  INSERT INTO agent_instruction_operations(account_id,origin_workspace_id,operation_id,revision_id,request_hash,actor,receipt)
+    VALUES(p_account,p_workspace,operation_id,revision_id,fingerprint,p_actor,result);
+  RETURN result;
+END $$;

package/drizzle/0463_host_mcp_resolver_registration.sql

@@ -0,0 +1,111 @@
+-- deployment-mode: maintenance
+-- Native namespace routing changes the exact runtime role contract. Stop old
+-- API/worker processes, migrate/provision roles, then start matching binaries.
+SET LOCAL lock_timeout = '5s';
+SET LOCAL statement_timeout = '5min';
+DO $drain$
+DECLARE roles jsonb := nullif(current_setting('opengeni.migration_application_roles', true), '')::jsonb;
+BEGIN
+  IF roles IS NULL OR jsonb_typeof(roles) <> 'array' OR jsonb_array_length(roles) NOT BETWEEN 1 AND 16 THEN
+    RAISE EXCEPTION '0463 requires application database roles' USING ERRCODE = '55000';
+  END IF;
+  IF EXISTS (SELECT 1 FROM jsonb_array_elements(roles) item WHERE jsonb_typeof(item) <> 'string'
+    OR btrim(item #>> '{}') = '' OR item #>> '{}' <> btrim(item #>> '{}') OR octet_length(item #>> '{}') > 63)
+  OR EXISTS (SELECT 1 FROM pg_stat_activity a JOIN jsonb_array_elements_text(roles) r ON r = a.usename
+    WHERE a.datname = current_database() AND a.pid <> pg_backend_pid()) THEN
+    RAISE EXCEPTION '0463 requires valid stopped application roles' USING ERRCODE = '55000';
+  END IF;
+END
+$drain$;
+
+CREATE TABLE host_mcp_resolvers (
+  id uuid PRIMARY KEY,
+  account_id uuid NOT NULL REFERENCES managed_accounts(id) ON DELETE CASCADE,
+  external_source text NOT NULL CHECK (length(external_source) BETWEEN 1 AND 200 AND external_source = btrim(external_source)),
+  url text NOT NULL CHECK (length(url) BETWEEN 1 AND 2048),
+  secret_encrypted text NOT NULL,
+  timeout_ms integer NOT NULL CHECK (timeout_ms BETWEEN 100 AND 30000),
+  generation bigint NOT NULL CHECK (generation BETWEEN 1 AND 9007199254740991),
+  status text NOT NULL CHECK (status IN ('active', 'revoked')),
+  created_at timestamptz NOT NULL DEFAULT clock_timestamp(),
+  updated_at timestamptz NOT NULL DEFAULT clock_timestamp(),
+  UNIQUE (account_id, external_source)
+);
+CREATE TABLE host_mcp_resolver_operations (
+  account_id uuid NOT NULL REFERENCES managed_accounts(id) ON DELETE CASCADE,
+  operation_id uuid NOT NULL,
+  actor_subject_id text NOT NULL,
+  request_digest text NOT NULL CHECK (request_digest ~ '^[0-9a-f]{64}$'),
+  result jsonb NOT NULL,
+  created_at timestamptz NOT NULL DEFAULT clock_timestamp(),
+  PRIMARY KEY (account_id, operation_id)
+);
+ALTER TABLE host_mcp_resolvers ENABLE ROW LEVEL SECURITY;
+ALTER TABLE host_mcp_resolvers FORCE ROW LEVEL SECURITY;
+ALTER TABLE host_mcp_resolver_operations ENABLE ROW LEVEL SECURITY;
+ALTER TABLE host_mcp_resolver_operations FORCE ROW LEVEL SECURITY;
+CREATE POLICY host_mcp_resolvers_account ON host_mcp_resolvers
+  USING (account_id = opengeni_private.current_account_id())
+  WITH CHECK (account_id = opengeni_private.current_account_id());
+CREATE POLICY host_mcp_resolver_operations_account ON host_mcp_resolver_operations
+  USING (account_id = opengeni_private.current_account_id())
+  WITH CHECK (account_id = opengeni_private.current_account_id());
+
+CREATE FUNCTION opengeni_private.guard_host_mcp_resolver_write() RETURNS trigger
+LANGUAGE plpgsql SET search_path FROM CURRENT AS $body$
+DECLARE permissions_value jsonb;
+BEGIN
+  SELECT credential.permissions INTO permissions_value FROM api_keys credential
+  WHERE credential.account_id = NEW.account_id
+    AND 'api_key:' || credential.id::text = opengeni_private.current_subject_id()
+    AND credential.workspace_id IS NULL AND credential.credential_kind = 'organization'
+    AND credential.revoked_at IS NULL
+    AND (credential.expires_at IS NULL OR credential.expires_at > clock_timestamp())
+  FOR SHARE;
+  IF NEW.account_id IS DISTINCT FROM opengeni_private.current_account_id()
+    OR NOT coalesce(permissions_value ? 'account:admin', false) THEN
+    RAISE EXCEPTION 'organization service administration required' USING ERRCODE = '42501';
+  END IF;
+  IF TG_TABLE_NAME = 'host_mcp_resolvers' THEN
+    IF TG_OP = 'UPDATE' THEN
+      IF ROW(NEW.id, NEW.account_id, NEW.external_source, NEW.created_at)
+        IS DISTINCT FROM ROW(OLD.id, OLD.account_id, OLD.external_source, OLD.created_at)
+        OR NEW.generation <> OLD.generation + 1 THEN
+        RAISE EXCEPTION 'resolver identity or generation conflict' USING ERRCODE = '40001';
+      END IF;
+    ELSIF NEW.generation <> 1 THEN
+      RAISE EXCEPTION 'initial resolver generation invalid' USING ERRCODE = '22023';
+    END IF;
+  ELSIF NEW.actor_subject_id IS DISTINCT FROM opengeni_private.current_subject_id() THEN
+    RAISE EXCEPTION 'resolver operation actor invalid' USING ERRCODE = '42501';
+  END IF;
+  RETURN NEW;
+END
+$body$;
+CREATE TRIGGER host_mcp_resolver_write BEFORE INSERT OR UPDATE ON host_mcp_resolvers
+  FOR EACH ROW EXECUTE FUNCTION opengeni_private.guard_host_mcp_resolver_write();
+CREATE TRIGGER host_mcp_resolver_operation_write BEFORE INSERT ON host_mcp_resolver_operations
+  FOR EACH ROW EXECUTE FUNCTION opengeni_private.guard_host_mcp_resolver_write();
+REVOKE ALL ON FUNCTION opengeni_private.guard_host_mcp_resolver_write() FROM PUBLIC;
+REVOKE ALL ON TABLE host_mcp_resolvers, host_mcp_resolver_operations FROM PUBLIC;
+DO $acl$
+DECLARE target_role record;
+BEGIN
+  FOR target_role IN SELECT DISTINCT role.rolname FROM pg_class relation
+    CROSS JOIN LATERAL aclexplode(coalesce(relation.relacl, acldefault('r', relation.relowner))) privilege
+    JOIN pg_roles role ON role.oid = privilege.grantee
+    WHERE relation.oid IN ('host_mcp_resolvers'::regclass, 'host_mcp_resolver_operations'::regclass)
+      AND privilege.grantee <> relation.relowner
+  LOOP EXECUTE format('REVOKE ALL ON TABLE host_mcp_resolvers, host_mcp_resolver_operations FROM %I', target_role.rolname); END LOOP;
+  FOR target_role IN SELECT DISTINCT role.rolname FROM pg_proc routine
+    CROSS JOIN LATERAL aclexplode(coalesce(routine.proacl, acldefault('f', routine.proowner))) privilege
+    JOIN pg_roles role ON role.oid = privilege.grantee
+    WHERE routine.oid = 'opengeni_private.guard_host_mcp_resolver_write()'::regprocedure AND privilege.grantee <> routine.proowner
+  LOOP EXECUTE format('REVOKE ALL ON FUNCTION opengeni_private.guard_host_mcp_resolver_write() FROM %I', target_role.rolname); END LOOP;
+  IF EXISTS (SELECT 1 FROM pg_stat_activity a
+    JOIN jsonb_array_elements_text(current_setting('opengeni.migration_application_roles')::jsonb) r ON r = a.usename
+    WHERE a.datname = current_database() AND a.pid <> pg_backend_pid()) THEN
+    RAISE EXCEPTION '0463 requires stopped application sessions' USING ERRCODE = '55000';
+  END IF;
+END
+$acl$;

package/drizzle/0464_external_workspace_membership_operations.sql

@@ -0,0 +1,166 @@
+-- deployment-mode: rolling
+-- Opt-in external service operations reuse the native workspace receipt ledger
+-- and membership-removal protocol. Unkeyed in-flight grants cannot be fenced.
+SET LOCAL lock_timeout = '5s';
+SET LOCAL statement_timeout = '5min';
+
+ALTER TABLE organization_workspace_lifecycle_events
+  ALTER COLUMN actor_membership_id DROP NOT NULL,
+  ADD COLUMN actor_service_subject text,
+  ADD CONSTRAINT organization_workspace_lifecycle_actor_check CHECK (
+    (actor_membership_id IS NOT NULL AND actor_service_subject IS NULL)
+    OR (actor_membership_id IS NULL AND actor_service_subject IS NOT NULL AND actor_service_subject ~ '^api_key:[0-9a-f-]{36}$')
+  );
+CREATE INDEX organization_workspace_cancelled_grant_idx
+  ON organization_workspace_operation_receipts (account_id, (result ->> 'fencedGrantOperationId'))
+  WHERE action = 'revoke' AND result ? 'fencedGrantOperationId';
+
+-- Authentication is performed by the API. This is its live commit-time fence,
+-- not permission to derive an actor from request JSON.
+CREATE FUNCTION opengeni_private.external_workspace_service_permissions(p_account uuid, p_actor text)
+RETURNS jsonb LANGUAGE plpgsql SECURITY DEFINER SET search_path FROM CURRENT AS $body$
+DECLARE permissions_value jsonb;
+BEGIN
+  IF p_account IS DISTINCT FROM opengeni_private.current_account_id()
+    OR p_actor IS NULL OR p_actor IS DISTINCT FROM opengeni_private.current_subject_id()
+  THEN RAISE EXCEPTION 'external workspace service scope invalid' USING ERRCODE = '42501'; END IF;
+  SELECT k.permissions INTO permissions_value FROM api_keys k
+  WHERE k.account_id = p_account AND 'api_key:' || k.id::text = p_actor
+    AND k.credential_kind = 'organization' AND k.workspace_id IS NULL
+    AND k.revoked_at IS NULL AND (k.expires_at IS NULL OR k.expires_at > clock_timestamp())
+  FOR SHARE;
+  IF NOT coalesce(permissions_value ?| ARRAY['members:manage', 'workspace:admin'], false)
+  THEN RAISE EXCEPTION 'external workspace service administration required' USING ERRCODE = '42501'; END IF;
+  RETURN permissions_value;
+END $body$;
+REVOKE ALL ON FUNCTION opengeni_private.external_workspace_service_permissions(uuid,text) FROM PUBLIC;
+
+CREATE FUNCTION lookup_external_identity(p_account uuid, p_actor text, p_source text, p_external_id text)
+RETURNS jsonb LANGUAGE plpgsql SECURITY DEFINER SET search_path FROM CURRENT AS $body$
+DECLARE result jsonb; previous_marker text := current_setting('opengeni.organization_tenancy_lifecycle', true);
+BEGIN
+  PERFORM opengeni_private.external_workspace_service_permissions(p_account, p_actor);
+  PERFORM set_config('opengeni.organization_tenancy_lifecycle', 'external_identity_provisioning', true);
+  SELECT jsonb_build_object('found', true, 'subjectId', i.subject_id,
+    'organizationMembershipId', m.id, 'identityStatus', i.status,
+    'identityAuthorizationRevision', i.authorization_revision,
+    'membershipStatus', m.status, 'membershipAuthorizationRevision', m.authorization_revision)
+  INTO result FROM external_identities i JOIN organization_memberships m
+    ON m.account_id = i.account_id AND m.id = i.organization_membership_id AND m.subject_id = i.subject_id
+  WHERE i.account_id = p_account AND i.source = p_source AND i.external_id = p_external_id;
+  PERFORM set_config('opengeni.organization_tenancy_lifecycle', coalesce(previous_marker,''), true);
+  RETURN coalesce(result, '{"found":false}'::jsonb);
+END $body$;
+REVOKE ALL ON FUNCTION lookup_external_identity(uuid,text,text,text) FROM PUBLIC;
+
+-- Both preparation and recording run in the caller's ONE open transaction.
+-- The same organization prefix serializes unstarted grants with cancellation.
+CREATE FUNCTION prepare_external_workspace_membership_operation(p_command jsonb)
+RETURNS jsonb LANGUAGE plpgsql SECURITY DEFINER SET search_path FROM CURRENT AS $body$
+DECLARE
+  account_value uuid := (p_command ->> 'organizationId')::uuid;
+  workspace_value uuid := (p_command ->> 'workspaceId')::uuid;
+  operation_value uuid := (p_command ->> 'operationId')::uuid;
+  actor_value text := p_command ->> 'actorSubjectId';
+  action_value text := p_command ->> 'action';
+  cancelled_value uuid := (p_command ->> 'cancelGrantOperationId')::uuid;
+  service_permissions jsonb; identity_value jsonb; prior record; cancellation record;
+  hash_value text; previous_marker text := current_setting('opengeni.organization_tenancy_lifecycle', true);
+BEGIN
+  IF account_value IS NULL OR workspace_value IS NULL OR operation_value IS NULL
+    OR action_value IS NULL OR action_value NOT IN ('grant','revoke')
+    OR (action_value = 'revoke' AND (cancelled_value IS NULL OR cancelled_value = operation_value))
+    OR (action_value = 'grant' AND cancelled_value IS NOT NULL)
+  THEN RAISE EXCEPTION 'invalid external workspace operation' USING ERRCODE = '22023'; END IF;
+  PERFORM pg_advisory_xact_lock(hashtextextended('organization-membership:' || account_value::text, 0));
+  service_permissions := opengeni_private.external_workspace_service_permissions(account_value, actor_value);
+  IF action_value = 'grant' AND (jsonb_typeof(p_command -> 'permissions') IS DISTINCT FROM 'array'
+    OR jsonb_array_length(p_command -> 'permissions') = 0
+    OR ((p_command -> 'permissions') ? 'secrets:read' AND NOT service_permissions ? 'secrets:read')
+    OR (NOT service_permissions ? 'workspace:admin' AND NOT (p_command -> 'permissions') <@ service_permissions))
+  THEN RAISE EXCEPTION 'external grant exceeds service authority' USING ERRCODE = '42501'; END IF;
+  PERFORM 1 FROM workspaces w WHERE w.account_id = account_value AND w.id = workspace_value FOR KEY SHARE;
+  IF NOT FOUND THEN RAISE EXCEPTION 'workspace not found' USING ERRCODE = 'P0002'; END IF;
+  PERFORM set_config('opengeni.organization_tenancy_lifecycle', 'organization_membership_lifecycle', true);
+  IF EXISTS (SELECT 1 FROM organization_memberships m WHERE m.account_id = account_value AND m.personal_workspace_id = workspace_value)
+  THEN RAISE EXCEPTION 'personal workspace is not administrable' USING ERRCODE = '42501'; END IF;
+  -- Credential identity is audit attribution, not the operation's semantic
+  -- identity: an authorized replacement organization key may reconcile it.
+  hash_value := encode(sha256(convert_to((p_command - 'actorSubjectId')::text, 'UTF8')), 'hex');
+  SELECT * INTO prior FROM organization_workspace_operation_receipts
+    WHERE account_id = account_value AND operation_id = operation_value;
+  IF FOUND AND (prior.action <> action_value OR prior.input_hash <> hash_value)
+  THEN RAISE EXCEPTION 'operation identity reused' USING ERRCODE = '23505'; END IF;
+  IF action_value = 'grant' THEN
+    SELECT * INTO cancellation FROM organization_workspace_operation_receipts
+      WHERE account_id = account_value AND action = 'revoke'
+        AND result ->> 'fencedGrantOperationId' = operation_value::text LIMIT 1;
+    IF FOUND THEN RAISE EXCEPTION 'external membership grant cancelled' USING ERRCODE = '55000'; END IF;
+  END IF;
+  IF prior.operation_id IS NOT NULL THEN
+    PERFORM set_config('opengeni.organization_tenancy_lifecycle', coalesce(previous_marker,''), true);
+    RETURN jsonb_build_object('replay', true, 'result', prior.result);
+  END IF;
+  PERFORM set_config('opengeni.organization_tenancy_lifecycle', 'external_identity_provisioning', true);
+  IF action_value = 'grant' THEN
+    identity_value := ensure_external_identity(account_value, p_command #>> '{identity,source}', p_command #>> '{identity,externalId}');
+  ELSE
+    SELECT jsonb_build_object('subjectId', i.subject_id, 'organizationMembershipId', i.organization_membership_id)
+      INTO identity_value FROM external_identities i
+      WHERE i.account_id = account_value AND i.organization_membership_id = (p_command ->> 'membershipId')::uuid;
+    IF identity_value IS NULL THEN RAISE EXCEPTION 'external member not found' USING ERRCODE = 'P0002'; END IF;
+    PERFORM set_config('opengeni.organization_tenancy_lifecycle', 'organization_membership_lifecycle', true);
+    SELECT * INTO prior FROM organization_workspace_operation_receipts
+      WHERE account_id = account_value AND operation_id = cancelled_value;
+    IF FOUND AND (prior.action <> 'grant' OR prior.result ->> 'workspaceId' IS DISTINCT FROM workspace_value::text
+      OR prior.result #>> '{identity,organizationMembershipId}' IS DISTINCT FROM identity_value ->> 'organizationMembershipId')
+    THEN RAISE EXCEPTION 'cancelled operation target mismatch' USING ERRCODE = '23505'; END IF;
+  END IF;
+  PERFORM set_config('opengeni.organization_tenancy_lifecycle', coalesce(previous_marker,''), true);
+  RETURN jsonb_build_object('replay', false, 'identity', identity_value);
+END $body$;
+REVOKE ALL ON FUNCTION prepare_external_workspace_membership_operation(jsonb) FROM PUBLIC;
+
+CREATE FUNCTION record_external_workspace_membership_operation(p_command jsonb, p_result jsonb)
+RETURNS void LANGUAGE plpgsql SECURITY DEFINER SET search_path FROM CURRENT AS $body$
+DECLARE prepared jsonb; subject_value text; member_value uuid; hash_value text;
+  account_value uuid := (p_command ->> 'organizationId')::uuid;
+  workspace_value uuid := (p_command ->> 'workspaceId')::uuid;
+  action_value text := p_command ->> 'action';
+  previous_marker text := current_setting('opengeni.organization_tenancy_lifecycle', true);
+BEGIN
+  prepared := prepare_external_workspace_membership_operation(p_command);
+  IF (prepared ->> 'replay')::boolean THEN RAISE EXCEPTION 'operation already recorded' USING ERRCODE = '23505'; END IF;
+  subject_value := prepared #>> '{identity,subjectId}';
+  IF action_value = 'grant' AND p_result -> 'identity' IS DISTINCT FROM prepared -> 'identity'
+  THEN RAISE EXCEPTION 'grant receipt identity mismatch' USING ERRCODE = '55000'; END IF;
+  IF p_result ->> 'workspaceId' IS DISTINCT FROM workspace_value::text
+    OR (action_value = 'revoke' AND p_result ->> 'fencedGrantOperationId' IS DISTINCT FROM p_command ->> 'cancelGrantOperationId')
+  THEN RAISE EXCEPTION 'operation receipt scope mismatch' USING ERRCODE = '55000'; END IF;
+  SELECT id INTO member_value FROM workspace_memberships
+    WHERE account_id = account_value AND workspace_id = workspace_value AND subject_id = subject_value;
+  IF (action_value = 'grant' AND member_value IS NULL) OR (action_value = 'revoke' AND member_value IS NOT NULL)
+  THEN RAISE EXCEPTION 'operation effects not settled' USING ERRCODE = '55000'; END IF;
+  hash_value := encode(sha256(convert_to((p_command - 'actorSubjectId')::text, 'UTF8')), 'hex');
+  PERFORM set_config('opengeni.organization_tenancy_lifecycle', 'organization_membership_lifecycle', true);
+  INSERT INTO organization_workspace_operation_receipts (account_id, operation_id, action, input_hash, result)
+    VALUES (account_value, (p_command ->> 'operationId')::uuid, action_value, hash_value, p_result);
+  INSERT INTO organization_workspace_lifecycle_events (account_id, operation_id, actor_service_subject,
+    workspace_id, target_organization_membership_id, target_workspace_membership_id, kind, role)
+    VALUES (account_value, (p_command ->> 'operationId')::uuid, p_command ->> 'actorSubjectId', workspace_value,
+      (prepared #>> '{identity,organizationMembershipId}')::uuid, member_value, action_value,
+      CASE WHEN action_value = 'grant' THEN 'member' ELSE NULL END);
+  PERFORM set_config('opengeni.organization_tenancy_lifecycle', coalesce(previous_marker,''), true);
+END $body$;
+REVOKE ALL ON FUNCTION record_external_workspace_membership_operation(jsonb,jsonb) FROM PUBLIC;
+
+DO $acl$
+DECLARE target_role record;
+BEGIN
+  FOR target_role IN SELECT DISTINCT grantee FROM information_schema.routine_privileges
+    WHERE routine_schema = current_schema() AND routine_name = 'ensure_external_identity'
+      AND grantee <> 'PUBLIC' AND privilege_type = 'EXECUTE'
+  LOOP
+    EXECUTE format('GRANT EXECUTE ON FUNCTION lookup_external_identity(uuid,text,text,text), prepare_external_workspace_membership_operation(jsonb), record_external_workspace_membership_operation(jsonb,jsonb) TO %I', target_role.grantee);
+  END LOOP;
+END $acl$;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opengeni/db",
-  "version": "4.4.0-canary.0",
+  "version": "4.4.0-canary.2",
   "description": "OpenGeni persistence: Drizzle schema, RLS-scoped query layer, the SQL migration runner, and role provisioning.",
   "license": "Apache-2.0",
   "repository": {
@@ -102,11 +102,11 @@
     "prepublishOnly": "bash ../../scripts/prepublish-guard"
   },
   "dependencies": {
-    "@opengeni/codemode": "^0.5.7-canary.0",
-    "@opengeni/codex": "^0.2.22-canary.12",
-    "@opengeni/config": "^1.2.0-canary.0",
-    "@opengeni/contracts": "^3.1.0-canary.0",
-    "@opengeni/network": "^0.3.1-canary.12",
+    "@opengeni/codemode": "^0.5.7-canary.2",
+    "@opengeni/codex": "^0.2.22-canary.14",
+    "@opengeni/config": "^1.2.0-canary.2",
+    "@opengeni/contracts": "^3.1.0-canary.2",
+    "@opengeni/network": "^0.3.1-canary.14",
     "drizzle-orm": "^0.45.2",
     "postgres": "^3.4.7"
   },