spine-framework 0.3.145 → 0.4.0

package/.framework/migrations/052_registration_security.sql

@@ -0,0 +1,421 @@
+-- CIL[BEGIN stable_id="~/.framework/migrations/052_registration_security.sql:registration_security:file" type="file" identity="registration_security" parent="~/.framework/migrations/052_registration_security.sql"]
+-- CIL[DOC-MACRO purpose="Registration and invite hardening: advisory-locked, token-gated stub claiming in handle_new_auth_user and an atomic, service-role-only complete_registration_placement RPC."]
+-- CIL[DOC-RESPONSIBILITY responsibility="Serialize signup processing and invite-stub claims, fail clearly on missing seed dependencies, and move account placement/role assignment out of the request path into a locked SECURITY DEFINER RPC."]
+-- CIL[DOC-CONTEXT module="migrations" layer="database" related_files=".framework/migrations/010_auth_user_trigger.sql,.framework/migrations/042_registration_hierarchy.sql,.framework/functions/invites.ts"]
+-- CIL[DOC-CONTRACT inputs="NEW auth.users row; p_person_id/p_app_slug/p_path/p_account_name" outputs="people rows inserted/updated; jsonb {status,account_slug,role_slug}" errors="RAISE EXCEPTION on missing person type, unclaimed invite stub, missing first-user seeds, invalid app/path/role/account" side_effects="Replaces handle_new_auth_user; creates complete_registration_placement; revokes EXECUTE from PUBLIC/anon/authenticated and grants to service_role"]
+-- CIL[DOC-MICRO logic_summary="handle_new_auth_user takes pg_advisory_xact_lock('spine.registration') before any reads, claims invited/pending stubs only when raw_user_meta_data.invite_token matches the stub's stored token and the invite is unblocked/unexpired, raises when an unbound stub exists but the token is absent/invalid, and raises on missing seed dependencies for the first user. complete_registration_placement locks per person, is idempotent, resolves apps.config->'registration' server-side, and assigns account_id/role_id/status atomically for new_account, existing_account, and join_request paths." notable_decisions="Advisory xact locks serialize first-user detection and stub claims; the RPC is the only placement writer so client-supplied role/target values are never trusted"]
+-- CIL[DOC-CONFIDENCE pass="first" score="0.85" flags="none"]
+-- CIL[DOC-STABILITY stability="stable"]
+
+-- Registration/invitation server-side hardening (Phase D).
+--
+--   * handle_new_auth_user() previously bound ANY unbound invited/pending
+--     stub by email alone — anyone who registered with the invitee's email
+--     claimed the invite without the token. Claims now require the invite
+--     token carried in raw_user_meta_data.invite_token (set by the invite
+--     link signup flow).
+--   * The first-user check (NOT EXISTS people) raced under concurrent
+--     signups; an advisory lock now serializes it.
+--   * complete_registration_placement() is the single atomic writer for
+--     registration placement. The invites endpoint calls it with the
+--     server-resolved person id — role, account strategy, and join target
+--     all come from the app's installed config, never the request body.
+
+-- ============================================
+-- 1. handle_new_auth_user() v3
+-- ============================================
+CREATE OR REPLACE FUNCTION public.handle_new_auth_user()
+RETURNS TRIGGER LANGUAGE plpgsql SECURITY DEFINER SET search_path = public AS $$
+DECLARE
+  v_account_id         uuid;
+  v_type_id            uuid;
+  v_role_id            uuid;
+  v_is_first           boolean;
+  v_design_schema      jsonb;
+  v_validation_schema  jsonb;
+  v_stub_id            uuid;
+  v_stub_status        text;
+  v_token              text;
+BEGIN
+  -- Serialize first-user detection AND invite-stub claims. Without this,
+  -- two concurrent signups could both pass the NOT EXISTS people check or
+  -- race to claim the same stub.
+  PERFORM pg_advisory_xact_lock(hashtext('spine.registration'));
+
+  SELECT id, design_schema, validation_schema
+    INTO v_type_id, v_design_schema, v_validation_schema
+  FROM public.types WHERE kind = 'person' AND slug = 'person' LIMIT 1;
+
+  -- Fail clearly: an auth user with no resolvable person type can never be
+  -- placed — better to error than silently create an unresolvable account.
+  IF v_type_id IS NULL THEN
+    RAISE EXCEPTION 'handle_new_auth_user: person type (kind=person, slug=person) not found — run framework type seeds before registering';
+  END IF;
+
+  -- Invite-stub claims REQUIRE the token. The stub's token lives in
+  -- people.data->>'invite_token' (written by createInvite); the client
+  -- echoes it back via raw_user_meta_data.invite_token at signup.
+  v_token := NEW.raw_user_meta_data->>'invite_token';
+
+  SELECT id, status
+    INTO v_stub_id, v_stub_status
+  FROM public.people
+  WHERE email = NEW.email
+    AND auth_uid IS NULL
+    AND status IN ('invited', 'pending')
+    AND data->>'invite_token' = v_token
+    AND data->>'invite_blocked_at' IS NULL
+    AND (data->>'invite_expires_at' IS NULL
+         OR (data->>'invite_expires_at')::timestamptz > now())
+  ORDER BY created_at
+  LIMIT 1;
+
+  IF v_stub_id IS NOT NULL THEN
+    UPDATE public.people SET
+      auth_uid   = NEW.id,
+      full_name  = COALESCE(NEW.raw_user_meta_data->>'full_name', full_name, split_part(NEW.email, '@', 1)),
+      status     = CASE WHEN v_stub_status = 'invited' THEN 'active' ELSE 'pending' END,
+      data       = (COALESCE(data, '{}'::jsonb) - 'invite_token')
+                   || jsonb_build_object('invite_claimed_at', now()),
+      updated_at = now()
+    WHERE id = v_stub_id;
+
+    RETURN NEW;
+  END IF;
+
+  -- The email matches an unbound invited/pending stub but the token was
+  -- absent, wrong, blocked, or expired. people.email is UNIQUE so no second
+  -- row can be created — fail loudly instead of silently orphaning the auth
+  -- user or letting them bypass the invite gate.
+  IF EXISTS (
+    SELECT 1 FROM public.people
+    WHERE email = NEW.email
+      AND auth_uid IS NULL
+      AND status IN ('invited', 'pending')
+  ) THEN
+    RAISE EXCEPTION 'A pending invitation exists for this email; register via your invite link';
+  END IF;
+
+  -- First-user detection stays inside the advisory lock so concurrent
+  -- signups cannot both claim system_admin.
+  SELECT NOT EXISTS (SELECT 1 FROM public.people LIMIT 1) INTO v_is_first;
+  IF v_is_first THEN
+    SELECT id INTO v_role_id FROM public.roles WHERE slug = 'system_admin' LIMIT 1;
+    SELECT id INTO v_account_id FROM public.accounts WHERE slug = 'spine-system' LIMIT 1;
+
+    -- Missing seeds are unrecoverable here — fail clearly and name the
+    -- dependency instead of creating a rootless first user.
+    IF v_account_id IS NULL AND v_role_id IS NULL THEN
+      RAISE EXCEPTION 'handle_new_auth_user: first-user bootstrap requires the ''spine-system'' account and ''system_admin'' role seeds — run framework seeds before registering';
+    ELSIF v_account_id IS NULL THEN
+      RAISE EXCEPTION 'handle_new_auth_user: first-user bootstrap requires the ''spine-system'' account seed — run framework seeds before registering';
+    ELSIF v_role_id IS NULL THEN
+      RAISE EXCEPTION 'handle_new_auth_user: first-user bootstrap requires the ''system_admin'' role seed — run framework seeds before registering';
+    END IF;
+  END IF;
+
+  -- Non-first, non-invited users get no account and no role here.
+  -- complete_registration_placement assigns both from the app's installed
+  -- config via the invites endpoint.
+  INSERT INTO public.people (
+    id,
+    auth_uid,
+    email,
+    full_name,
+    account_id,
+    type_id,
+    role_id,
+    status,
+    is_active,
+    design_schema,
+    validation_schema
+  ) VALUES (
+    NEW.id,
+    NEW.id,
+    NEW.email,
+    COALESCE(NEW.raw_user_meta_data->>'full_name', split_part(NEW.email, '@', 1)),
+    v_account_id,
+    v_type_id,
+    v_role_id,
+    'active',
+    true,
+    v_design_schema,
+    COALESCE(v_validation_schema, '{}'::jsonb)
+  )
+  ON CONFLICT (id) DO NOTHING;
+
+  RETURN NEW;
+END;
+$$;
+
+DROP TRIGGER IF EXISTS on_auth_user_created ON auth.users;
+CREATE TRIGGER on_auth_user_created
+  AFTER INSERT ON auth.users
+  FOR EACH ROW EXECUTE FUNCTION public.handle_new_auth_user();
+
+-- ============================================
+-- 2. complete_registration_placement()
+--    Atomic, idempotent placement writer. Service-role only — the invites
+--    endpoint calls it as adminDb; PUBLIC/anon/authenticated get nothing.
+-- ============================================
+CREATE OR REPLACE FUNCTION public.complete_registration_placement(
+  p_person_id uuid,
+  p_app_slug text,
+  p_path text,
+  p_account_name text
+)
+RETURNS jsonb
+LANGUAGE plpgsql
+SECURITY DEFINER
+SET search_path = public
+AS $$
+DECLARE
+  v_person           public.people%ROWTYPE;
+  v_app_reg          jsonb;
+  v_role_slug        text;
+  v_role             public.roles%ROWTYPE;
+  v_account_id       uuid;
+  v_account_slug     text;
+  v_account_type_id  uuid;
+  v_parent_id        uuid;
+  v_type_id          uuid;
+  v_design_schema    jsonb;
+  v_validation_schema jsonb;
+  v_base             text;
+  v_domain           text;
+  v_status           text;
+  v_target           record;
+  v_personal_domains text[] := ARRAY[
+    'gmail.com', 'yahoo.com', 'hotmail.com', 'outlook.com', 'icloud.com',
+    'aol.com', 'protonmail.com', 'me.com', 'mac.com', 'live.com',
+    'msn.com', 'ymail.com', 'googlemail.com', 'fastmail.com'
+  ];
+BEGIN
+  IF p_person_id IS NULL OR p_app_slug IS NULL OR p_path IS NULL THEN
+    RAISE EXCEPTION 'person, app, and path are required';
+  END IF;
+
+  -- Per-person lock serializes concurrent/duplicate placement calls.
+  PERFORM pg_advisory_xact_lock(hashtext('spine.placement.' || p_person_id::text));
+
+  SELECT * INTO v_person FROM public.people WHERE id = p_person_id FOR UPDATE;
+  IF NOT FOUND THEN
+    RAISE EXCEPTION 'Person not found';
+  END IF;
+
+  -- Idempotent: a retry after a lost response returns the placement that
+  -- already committed instead of creating a second account or failing.
+  IF v_person.account_id IS NOT NULL AND v_person.role_id IS NOT NULL THEN
+    RETURN (
+      SELECT jsonb_build_object(
+        'status', v_person.status,
+        'account_slug', a.slug,
+        'role_slug', r.slug
+      )
+      FROM public.accounts a, public.roles r
+      WHERE a.id = v_person.account_id AND r.id = v_person.role_id
+    );
+  END IF;
+
+  -- Resolve the installed registration policy server-side.
+  SELECT config->'registration' INTO v_app_reg
+  FROM public.apps
+  WHERE slug = p_app_slug AND is_active = true
+  LIMIT 1;
+
+  IF v_app_reg IS NULL THEN
+    RAISE EXCEPTION 'Unknown or uninstalled app ''%'' or no registration policy configured', p_app_slug;
+  END IF;
+  IF COALESCE((v_app_reg->>'enabled')::boolean, false) = false THEN
+    RAISE EXCEPTION 'Registration is not enabled for app ''%''', p_app_slug;
+  END IF;
+
+  -- Role comes from the app's installed config — NEVER the request.
+  -- join_request defaults to 'member' when the app permits it.
+  v_role_slug := CASE
+    WHEN p_path = 'join_request' AND (v_app_reg->'roles' ? 'member') THEN 'member'
+    ELSE v_app_reg->>'default_role'
+  END;
+
+  IF v_role_slug IS NULL THEN
+    RAISE EXCEPTION 'App ''%'' registration has no default_role configured', p_app_slug;
+  END IF;
+  IF v_app_reg->'roles' IS NOT NULL AND NOT (v_app_reg->'roles' ? v_role_slug) THEN
+    RAISE EXCEPTION 'Role ''%'' is not permitted in this context', v_role_slug;
+  END IF;
+  IF v_role_slug = 'system_admin' THEN
+    RAISE EXCEPTION 'Role ''system_admin'' cannot be assigned through registration';
+  END IF;
+
+  SELECT * INTO v_role FROM public.roles WHERE slug = v_role_slug LIMIT 1;
+  IF NOT FOUND THEN
+    RAISE EXCEPTION 'Role ''%'' not found', v_role_slug;
+  END IF;
+  IF v_role.is_system = true THEN
+    RAISE EXCEPTION 'Role ''%'' is not permitted in this context', v_role_slug;
+  END IF;
+
+  -- Post-lock precondition: another writer already assigned a role. Return
+  -- the existing placement rather than overwrite (lost-response resume).
+  IF v_person.role_id IS NOT NULL THEN
+    RETURN (
+      SELECT jsonb_build_object(
+        'status', v_person.status,
+        'account_slug', a.slug,
+        'role_slug', r.slug
+      )
+      FROM public.roles r
+      LEFT JOIN public.accounts a ON a.id = v_person.account_id
+      WHERE r.id = v_person.role_id
+    );
+  END IF;
+
+  SELECT id, design_schema, validation_schema
+    INTO v_type_id, v_design_schema, v_validation_schema
+  FROM public.types WHERE kind = 'person' AND slug = 'person' LIMIT 1;
+  IF v_type_id IS NULL THEN
+    RAISE EXCEPTION 'Person type (kind=person, slug=person) not found — run framework type seeds';
+  END IF;
+
+  IF p_path = 'new_account' THEN
+    IF p_account_name IS NULL OR btrim(p_account_name) = '' THEN
+      RAISE EXCEPTION 'account_name is required for new_account path';
+    END IF;
+
+    v_parent_id := NULL;
+    IF v_app_reg->>'parent_account' IS NOT NULL THEN
+      SELECT id INTO v_parent_id FROM public.accounts
+      WHERE slug = v_app_reg->>'parent_account' LIMIT 1;
+      IF v_parent_id IS NULL THEN
+        RAISE EXCEPTION 'Parent account ''%'' not found', v_app_reg->>'parent_account';
+      END IF;
+    END IF;
+
+    SELECT id INTO v_account_type_id FROM public.types
+    WHERE kind = 'account' AND slug = 'account' LIMIT 1;
+    IF v_account_type_id IS NULL THEN
+      RAISE EXCEPTION 'Account type (kind=account, slug=account) not found — run framework type seeds';
+    END IF;
+
+    -- Slug pattern matches generateAccountSlug: lower, non-alphanumeric runs
+    -- -> '-', trimmed, 40-char base, '-xxxxxx' random suffix, retried on
+    -- collision until unique.
+    v_base := left(btrim(lower(regexp_replace(p_account_name, '[^a-z0-9]+', '-', 'g')), '-'), 40);
+    IF v_base = '' THEN v_base := 'account'; END IF;
+    LOOP
+      v_account_slug := v_base || '-' || substr(md5(random()::text), 1, 6);
+      EXIT WHEN NOT EXISTS (SELECT 1 FROM public.accounts WHERE slug = v_account_slug);
+    END LOOP;
+
+    INSERT INTO public.accounts (slug, display_name, type_id, parent_id, is_active)
+    VALUES (v_account_slug, btrim(p_account_name), v_account_type_id, v_parent_id, true)
+    RETURNING id INTO v_account_id;
+
+    v_status := 'active';
+
+    UPDATE public.people SET
+      account_id        = v_account_id,
+      role_id           = v_role.id,
+      status            = 'active',
+      type_id           = v_type_id,
+      design_schema     = v_design_schema,
+      validation_schema = COALESCE(v_validation_schema, '{}'::jsonb),
+      updated_at        = now()
+    WHERE id = v_person.id
+      AND role_id IS NULL;
+
+  ELSIF p_path = 'existing_account' THEN
+    IF COALESCE(v_app_reg->>'account_strategy', '') <> 'existing' THEN
+      RAISE EXCEPTION 'App ''%'' does not support joining an existing account', p_app_slug;
+    END IF;
+    IF v_app_reg->>'target_account' IS NULL THEN
+      RAISE EXCEPTION 'No target_account configured for this app registration';
+    END IF;
+
+    SELECT id, slug INTO v_target FROM public.accounts
+    WHERE slug = v_app_reg->>'target_account' LIMIT 1;
+    IF NOT FOUND THEN
+      RAISE EXCEPTION 'Target account ''%'' not found', v_app_reg->>'target_account';
+    END IF;
+    v_account_id   := v_target.id;
+    v_account_slug := v_target.slug;
+    v_status       := 'active';
+
+    UPDATE public.people SET
+      account_id        = v_account_id,
+      role_id           = v_role.id,
+      status            = 'active',
+      type_id           = v_type_id,
+      design_schema     = v_design_schema,
+      validation_schema = COALESCE(v_validation_schema, '{}'::jsonb),
+      data              = '{}'::jsonb,
+      updated_at        = now()
+    WHERE id = v_person.id
+      AND role_id IS NULL;
+
+  ELSIF p_path = 'join_request' THEN
+    -- Opt-in only: apps must declare allow_domain_join. The target account
+    -- is derived server-side from the person's email domain — the client
+    -- never supplies target_account_id.
+    IF COALESCE((v_app_reg->>'allow_domain_join')::boolean, false) = false THEN
+      RAISE EXCEPTION 'App ''%'' does not allow domain-based join requests', p_app_slug;
+    END IF;
+
+    v_domain := lower(split_part(v_person.email, '@', 2));
+    IF v_domain IS NULL OR v_domain = '' OR v_domain = ANY(v_personal_domains) THEN
+      RAISE EXCEPTION 'No account found for this email domain';
+    END IF;
+
+    SELECT p2.account_id INTO v_account_id
+    FROM public.people p2
+    WHERE lower(split_part(p2.email, '@', 2)) = v_domain
+      AND p2.status = 'active'
+      AND p2.account_id IS NOT NULL
+    ORDER BY p2.created_at
+    LIMIT 1;
+
+    IF v_account_id IS NULL THEN
+      RAISE EXCEPTION 'No account found for this email domain';
+    END IF;
+    SELECT slug INTO v_account_slug FROM public.accounts WHERE id = v_account_id;
+
+    v_status := 'pending';
+
+    UPDATE public.people SET
+      account_id        = v_account_id,
+      role_id           = v_role.id,
+      status            = 'pending',
+      type_id           = v_type_id,
+      design_schema     = v_design_schema,
+      validation_schema = COALESCE(v_validation_schema, '{}'::jsonb),
+      data              = COALESCE(data, '{}'::jsonb) || jsonb_build_object(
+                            'invite_kind', 'access_request',
+                            'invite_invited_by', null,
+                            'invite_token', null),
+      updated_at        = now()
+    WHERE id = v_person.id
+      AND role_id IS NULL;
+
+  ELSE
+    RAISE EXCEPTION 'Unknown registration path: %', p_path;
+  END IF;
+
+  RETURN jsonb_build_object(
+    'status', v_status,
+    'account_slug', v_account_slug,
+    'role_slug', v_role.slug
+  );
+END;
+$$;
+
+REVOKE ALL ON FUNCTION public.complete_registration_placement(uuid, text, text, text) FROM PUBLIC;
+REVOKE ALL ON FUNCTION public.complete_registration_placement(uuid, text, text, text) FROM anon;
+REVOKE ALL ON FUNCTION public.complete_registration_placement(uuid, text, text, text) FROM authenticated;
+GRANT EXECUTE ON FUNCTION public.complete_registration_placement(uuid, text, text, text) TO service_role;
+-- CIL[DOC-VECTOR type="context" content="purpose='Registration and invite hardening: advisory-locked, token-gated stub claiming in handle_new_auth_user and an atomic, service-role-only complete_registration_placement RPC.'; No verified external callers; imports: none" status="ready"]
+-- CIL[DOC-VECTOR type="blast_radius" content="All new signups; invites.completeRegistration delegates placement to the RPC; invited stubs can only be claimed with a valid token" status="ready"]
+-- CIL[DOC-VECTOR type="configuration" content="Requires people.data invite_* keys written by createInvite; apps.config->'registration' installed per app (042); optional allow_domain_join flag for join_request" status="ready"]
+-- CIL[DOC-VECTOR type="constraint" content="complete_registration_placement is service-role only; role must be declared in appReg.roles, non-system_admin, and is_system=false" status="ready"]
+-- CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+-- CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
+-- CIL[END stable_id="~/.framework/migrations/052_registration_security.sql:registration_security:file"]

package/.framework/migrations/053_builtin_action_seeds.sql

@@ -0,0 +1,66 @@
+-- CIL[BEGIN stable_id="~/.framework/migrations/053_builtin_action_seeds.sql:builtin_action_seeds:file" type="file" identity="builtin_action_seeds" parent="~/.framework/migrations/053_builtin_action_seeds.sql"]
+-- CIL[DOC-MACRO purpose="Idempotently seed the 11 built-in pipeline action rows that the pipeline-runner stageHandlers map requires."]
+-- CIL[DOC-RESPONSIBILITY responsibility="Insert one public.actions row per built-in stage type (update_item, create_record, http_request, send_notification, run_pipeline, search_knowledge, query_items, agent_inference, generate_embeddings, revoke_embeddings, create_interaction) only when no row with that slug exists."]
+-- CIL[DOC-CONTEXT module="migrations" layer="database" related_files=".framework/migrations/018_runtime_tables.sql,.framework/functions/_shared/pipeline-runner.ts,custom/apps/cortex/seed/actions.json"]
+-- CIL[DOC-CONTRACT inputs="none" outputs="11 global actions rows (account_id NULL, ownership platform, is_system true)" errors="none — INSERT ... SELECT ... WHERE NOT EXISTS is a no-op when a slug is already present" side_effects="Fresh installs gain the action rows runPipeline resolves via .eq('slug', stage_type).eq('is_active', true).single()"]
+-- CIL[DOC-MICRO logic_summary="Each INSERT ... SELECT ... WHERE NOT EXISTS checks the slug alone (actions.slug is deliberately NOT UNIQUE — no constraint added, existing DBs may carry dupes). Names/descriptions mirror custom/apps/cortex/seed/actions.json wording, which no manifest seeds, so this migration is the only writer of built-in action rows." notable_decisions="Per-row NOT EXISTS keeps the file re-runnable and leaves pre-existing rows untouched; global rows carry account_id NULL"]
+-- CIL[DOC-CONFIDENCE pass="first" score="0.9" flags="none"]
+-- CIL[DOC-STABILITY stability="stable"]
+
+-- Built-in pipeline action seeds. runPipeline resolves every stage's action by
+-- slug + is_active via .single(); without these rows a fresh install cannot run
+-- any pipeline stage. cortex/seed/actions.json documents the same shape but no
+-- manifest references it, so the framework migration owns the built-ins.
+-- Each row is guarded by NOT EXISTS on slug — idempotent across re-runs and
+-- additive-only on databases that already carry equivalent rows.
+
+INSERT INTO public.actions (slug, name, description, handler, handler_module, ownership, is_system, is_active)
+SELECT 'update_item', 'Update Item', 'Core pipeline stage: update fields on a runtime record.', 'update_item', 'functions', 'platform', true, true
+WHERE NOT EXISTS (SELECT 1 FROM public.actions WHERE slug = 'update_item');
+
+INSERT INTO public.actions (slug, name, description, handler, handler_module, ownership, is_system, is_active)
+SELECT 'create_record', 'Create Record', 'Core pipeline stage: create a runtime record in a whitelisted entity table.', 'create_record', 'functions', 'platform', true, true
+WHERE NOT EXISTS (SELECT 1 FROM public.actions WHERE slug = 'create_record');
+
+INSERT INTO public.actions (slug, name, description, handler, handler_module, ownership, is_system, is_active)
+SELECT 'http_request', 'HTTP Request', 'Core pipeline stage: perform an outbound HTTP request.', 'http_request', 'functions', 'platform', true, true
+WHERE NOT EXISTS (SELECT 1 FROM public.actions WHERE slug = 'http_request');
+
+INSERT INTO public.actions (slug, name, description, handler, handler_module, ownership, is_system, is_active)
+SELECT 'send_notification', 'Send Notification', 'Core pipeline stage: send a notification to role- or person-scoped recipients.', 'send_notification', 'functions', 'platform', true, true
+WHERE NOT EXISTS (SELECT 1 FROM public.actions WHERE slug = 'send_notification');
+
+INSERT INTO public.actions (slug, name, description, handler, handler_module, ownership, is_system, is_active)
+SELECT 'run_pipeline', 'Run Pipeline', 'Core pipeline stage: invoke another pipeline by id or slug.', 'run_pipeline', 'functions', 'platform', true, true
+WHERE NOT EXISTS (SELECT 1 FROM public.actions WHERE slug = 'run_pipeline');
+
+INSERT INTO public.actions (slug, name, description, handler, handler_module, ownership, is_system, is_active)
+SELECT 'search_knowledge', 'Search Knowledge', 'Core pipeline stage: hybrid retrieval over the knowledge base.', 'search_knowledge', 'functions', 'platform', true, true
+WHERE NOT EXISTS (SELECT 1 FROM public.actions WHERE slug = 'search_knowledge');
+
+INSERT INTO public.actions (slug, name, description, handler, handler_module, ownership, is_system, is_active)
+SELECT 'query_items', 'Query Items', 'Core pipeline stage: query runtime items with filters.', 'query_items', 'functions', 'platform', true, true
+WHERE NOT EXISTS (SELECT 1 FROM public.actions WHERE slug = 'query_items');
+
+INSERT INTO public.actions (slug, name, description, handler, handler_module, ownership, is_system, is_active)
+SELECT 'agent_inference', 'Agent Inference', 'Core pipeline stage: run an agent inference step.', 'agent_inference', 'functions', 'platform', true, true
+WHERE NOT EXISTS (SELECT 1 FROM public.actions WHERE slug = 'agent_inference');
+
+INSERT INTO public.actions (slug, name, description, handler, handler_module, ownership, is_system, is_active)
+SELECT 'generate_embeddings', 'Generate Embeddings', 'Core pipeline stage: generate embeddings for a runtime item via the core embedding engine.', 'generate_embeddings', 'functions', 'platform', true, true
+WHERE NOT EXISTS (SELECT 1 FROM public.actions WHERE slug = 'generate_embeddings');
+
+INSERT INTO public.actions (slug, name, description, handler, handler_module, ownership, is_system, is_active)
+SELECT 'revoke_embeddings', 'Revoke Embeddings', 'Core pipeline stage: revoke embeddings for a runtime item via the core embedding engine.', 'revoke_embeddings', 'functions', 'platform', true, true
+WHERE NOT EXISTS (SELECT 1 FROM public.actions WHERE slug = 'revoke_embeddings');
+
+INSERT INTO public.actions (slug, name, description, handler, handler_module, ownership, is_system, is_active)
+SELECT 'create_interaction', 'Create AI Interaction', 'Core pipeline stage: capture an AI interaction record via ai-interactions.createInteraction.', 'create_interaction', 'functions', 'platform', true, true
+WHERE NOT EXISTS (SELECT 1 FROM public.actions WHERE slug = 'create_interaction');
+-- CIL[DOC-VECTOR type="context" content="purpose='Idempotently seed the 11 built-in pipeline action rows the pipeline-runner stageHandlers map requires.'; No verified external callers; imports: none" status="ready"]
+-- CIL[DOC-VECTOR type="blast_radius" content="Fresh installs can execute every built-in pipeline stage; existing databases keep their action rows untouched" status="ready"]
+-- CIL[DOC-VECTOR type="configuration" content="Runs after 018 (actions table); supersedes the unreferenced custom/apps/cortex/seed/actions.json for built-ins" status="ready"]
+-- CIL[DOC-VECTOR type="constraint" content="NOT EXISTS guard is on slug only; no unique constraint is added because existing DBs may already hold duplicate slugs" status="ready"]
+-- CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+-- CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
+-- CIL[END stable_id="~/.framework/migrations/053_builtin_action_seeds.sql:builtin_action_seeds:file"]

package/.framework/migrations/054_kb_ingest_lease.sql

@@ -0,0 +1,157 @@
+-- CIL[BEGIN stable_id="~/.framework/migrations/054_kb_ingest_lease.sql:kb_ingest_lease:file" type="file" identity="kb_ingest_lease" parent="~/.framework/migrations/054_kb_ingest_lease.sql"]
+-- CIL[DOC-MACRO purpose="Content-hash document lease for kbIngest: document_leases table, atomic service-role-only acquire/release RPCs, and kb_ingest/kb_revoke pipeline action seeds."]
+-- CIL[DOC-RESPONSIBILITY responsibility="Create public.document_leases (one row per embedded document), provide acquire_document_lease/release_document_lease as the single atomic writers, and seed the generic kb_ingest/kb_revoke pipeline action rows."]
+-- CIL[DOC-CONTEXT module="migrations" layer="database" related_files=".framework/functions/_shared/kb.ts,.framework/functions/_shared/pipeline-runner.ts,.framework/migrations/053_builtin_action_seeds.sql,.framework/migrations/049_security_blocklist.sql"]
+-- CIL[DOC-CONTRACT inputs="acquire: p_document_id/p_account_id/p_content_hash/p_ttl_seconds; release: p_document_id/p_lease_id/p_status" outputs="acquire jsonb {outcome: acquired|reused|processing, lease_id?}; release boolean" errors="none — all branches return" side_effects="Upserts/updates document_leases; kbIngest callers use the lease to skip unchanged re-embeds and fence concurrent workers"]
+-- CIL[DOC-MICRO logic_summary="acquire_document_lease INSERTs ON CONFLICT DO NOTHING; on conflict it SELECTs FOR UPDATE and returns 'reused' for a completed same-hash row, 'processing' for a live same-hash in-flight row, and takes over (new lease_id, new hash, fresh TTL) for expired/failed/different-hash rows. release_document_lease updates only on (document_id, lease_id) match so a superseded worker's release is fenced by the token." notable_decisions="Same-hash completed work is reused without extending the lease; a new content_hash supersedes an in-flight worker whose later release then fails the token check; RLS grants service_role FOR ALL and EXECUTE goes to service_role only, matching 049/052's service-only convention"]
+-- CIL[DOC-CONFIDENCE pass="first" score="0.9" flags="none"]
+-- CIL[DOC-STABILITY stability="stable"]
+
+-- ── document_leases ────────────────────────────────────────────────
+-- One row per embedded document (items.id). kbIngest acquires before
+-- embedding: 'reused' skips unchanged content, 'processing' fences a
+-- second worker, 'acquired' grants a lease_id token the holder must
+-- present to release.
+CREATE TABLE IF NOT EXISTS public.document_leases (
+  document_id  uuid        PRIMARY KEY,
+  account_id   uuid        NOT NULL,
+  content_hash text        NOT NULL,
+  lease_id     uuid        NOT NULL,
+  status       text        NOT NULL DEFAULT 'processing',
+  expires_at   timestamptz NOT NULL,
+  created_at   timestamptz DEFAULT now(),
+  updated_at   timestamptz DEFAULT now()
+);
+
+ALTER TABLE public.document_leases ENABLE ROW LEVEL SECURITY;
+
+-- Service-role only: all reads/writes flow through _shared/kb.ts
+-- (adminDb) and the two RPCs below.
+DROP POLICY IF EXISTS document_leases_service_role ON public.document_leases;
+CREATE POLICY document_leases_service_role ON public.document_leases
+  FOR ALL TO service_role USING (true) WITH CHECK (true);
+
+-- ── acquire_document_lease ─────────────────────────────────────────
+-- Atomic claim. Returns {outcome, lease_id?}:
+--   acquired   — caller owns the work; must release with the token
+--   reused     — same-hash completed embeddings exist; skip re-embed
+--   processing — a live worker holds the same hash; do not stamp success
+CREATE OR REPLACE FUNCTION public.acquire_document_lease(
+  p_document_id uuid,
+  p_account_id uuid,
+  p_content_hash text,
+  p_ttl_seconds integer DEFAULT 300
+)
+RETURNS jsonb
+LANGUAGE plpgsql
+SECURITY DEFINER
+SET search_path = public
+AS $$
+DECLARE
+  v_lease        public.document_leases%ROWTYPE;
+  v_new_lease_id uuid := gen_random_uuid();
+BEGIN
+  -- Fast path: claim the empty slot. The document_id PK serializes
+  -- concurrent first-writers — the loser's INSERT is a no-op.
+  INSERT INTO public.document_leases (document_id, account_id, content_hash, lease_id, status, expires_at)
+  VALUES (
+    p_document_id,
+    p_account_id,
+    p_content_hash,
+    v_new_lease_id,
+    'processing',
+    now() + make_interval(secs => p_ttl_seconds)
+  )
+  ON CONFLICT (document_id) DO NOTHING;
+
+  IF FOUND THEN
+    RETURN jsonb_build_object('outcome', 'acquired', 'lease_id', v_new_lease_id);
+  END IF;
+
+  -- Conflict path: lock the row so a concurrent release/takeover cannot
+  -- interleave between our read and our verdict.
+  SELECT * INTO v_lease
+  FROM public.document_leases
+  WHERE document_id = p_document_id
+  FOR UPDATE;
+
+  -- Same-hash completed work is reused — do NOT extend the lease.
+  IF v_lease.status = 'completed' AND v_lease.content_hash = p_content_hash THEN
+    RETURN jsonb_build_object('outcome', 'reused');
+  END IF;
+
+  -- A live worker owns the same hash — the caller must not stamp success.
+  IF v_lease.status = 'processing'
+     AND v_lease.expires_at > now()
+     AND v_lease.content_hash = p_content_hash THEN
+    RETURN jsonb_build_object('outcome', 'processing', 'lease_id', null);
+  END IF;
+
+  -- Expired, failed, or a different content hash: take over. A new hash
+  -- supersedes — the displaced worker's release will fail the token check.
+  UPDATE public.document_leases SET
+    lease_id     = v_new_lease_id,
+    status       = 'processing',
+    content_hash = p_content_hash,
+    account_id   = p_account_id,
+    expires_at   = now() + make_interval(secs => p_ttl_seconds),
+    updated_at   = now()
+  WHERE document_id = p_document_id;
+
+  RETURN jsonb_build_object('outcome', 'acquired', 'lease_id', v_new_lease_id);
+END;
+$$;
+
+REVOKE ALL ON FUNCTION public.acquire_document_lease(uuid, uuid, text, integer) FROM PUBLIC;
+REVOKE ALL ON FUNCTION public.acquire_document_lease(uuid, uuid, text, integer) FROM anon;
+REVOKE ALL ON FUNCTION public.acquire_document_lease(uuid, uuid, text, integer) FROM authenticated;
+GRANT EXECUTE ON FUNCTION public.acquire_document_lease(uuid, uuid, text, integer) TO service_role;
+
+-- ── release_document_lease ─────────────────────────────────────────
+-- Token-gated completion. Returns false when the lease_id no longer
+-- matches (a superseding acquire took over) — the caller must treat
+-- that as "do not stamp success", not as an error.
+CREATE OR REPLACE FUNCTION public.release_document_lease(
+  p_document_id uuid,
+  p_lease_id uuid,
+  p_status text
+)
+RETURNS boolean
+LANGUAGE plpgsql
+SECURITY DEFINER
+SET search_path = public
+AS $$
+BEGIN
+  UPDATE public.document_leases SET
+    status     = p_status,
+    expires_at = now(),
+    updated_at = now()
+  WHERE document_id = p_document_id
+    AND lease_id = p_lease_id;
+
+  RETURN FOUND;
+END;
+$$;
+
+REVOKE ALL ON FUNCTION public.release_document_lease(uuid, uuid, text) FROM PUBLIC;
+REVOKE ALL ON FUNCTION public.release_document_lease(uuid, uuid, text) FROM anon;
+REVOKE ALL ON FUNCTION public.release_document_lease(uuid, uuid, text) FROM authenticated;
+GRANT EXECUTE ON FUNCTION public.release_document_lease(uuid, uuid, text) TO service_role;
+
+-- ── kb_ingest / kb_revoke action seeds ─────────────────────────────
+-- Generic typed-path stages (wrap _shared/kb.ts kbIngest/kbRevoke) —
+-- same WHERE-NOT-EXISTS idempotency as 053's built-in seeds.
+INSERT INTO public.actions (slug, name, description, handler, handler_module, ownership, is_system, is_active)
+SELECT 'kb_ingest', 'KB Ingest', 'Core pipeline stage: ingest a runtime item into the knowledge base via the canonical typed path (content-hash lease + declared vector fields).', 'kb_ingest', 'functions', 'platform', true, true
+WHERE NOT EXISTS (SELECT 1 FROM public.actions WHERE slug = 'kb_ingest');
+
+INSERT INTO public.actions (slug, name, description, handler, handler_module, ownership, is_system, is_active)
+SELECT 'kb_revoke', 'KB Revoke', 'Core pipeline stage: revoke a runtime item from the knowledge base via the canonical typed path (embeddings + document lease).', 'kb_revoke', 'functions', 'platform', true, true
+WHERE NOT EXISTS (SELECT 1 FROM public.actions WHERE slug = 'kb_revoke');
+-- CIL[DOC-VECTOR type="context" content="purpose='Content-hash document lease for kbIngest plus generic kb_ingest/kb_revoke action seeds.'; No verified external callers; imports: none" status="ready"]
+-- CIL[DOC-VECTOR type="blast_radius" content="kbIngest skips unchanged re-embeds and fences concurrent workers; pipelines gain generic kb_ingest/kb_revoke stages on fresh installs" status="ready"]
+-- CIL[DOC-VECTOR type="configuration" content="Runs after 018 (actions) and 020 (embeddings); consumed by _shared/kb.ts via adminDb.rpc" status="ready"]
+-- CIL[DOC-VECTOR type="constraint" content="document_leases and both RPCs are service-role only; release is fenced by lease_id token; same-hash completed rows return reused without TTL extension" status="ready"]
+-- CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+-- CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
+-- CIL[END stable_id="~/.framework/migrations/054_kb_ingest_lease.sql:kb_ingest_lease:file"]