@fayz-ai/db 0.12.0 → 0.13.0

package/migrations/149_the_event_log_gets_a_consumer.sql

@@ -0,0 +1,331 @@
+-- ============================================================================
+-- 149_the_event_log_gets_a_consumer.sql — the log stops being a pile of rows
+-- nobody reads (#277).
+--
+-- The decision (rodada 3, Q2): the domain-event log is the CONTRACT between
+-- plugins for business effect; the in-memory bus stays, demoted to reactions on
+-- a screen. The reason is not taste — the bus only reaches listeners inside the
+-- app process, so an order placed on the storefront at 2am, an import in bulk,
+-- or a plugin running in another cluster all emit into silence. A row in a table
+-- survives all three, and survives the consumer being down.
+--
+-- What was missing was the consumer. 027 built the emitter and the ledger, and
+-- said so plainly in the status vocabulary: `recorded` means "the trigger fired
+-- and nobody acted yet (today's state: the catalog exists, message dispatch does
+-- not)". This file is that missing half.
+--
+-- THREE THINGS IT HAS TO GET RIGHT, and how:
+--
+--   Idempotence — a fact must not act twice. Delivery is a row keyed
+--   (event, plugin, handler): the consumer inserts it BEFORE calling, so a
+--   double run collides instead of double-charging. This is the same shape as
+--   the effect claim in 030.
+--
+--   Concurrency — two consumers must not fight. Claiming is
+--   `FOR UPDATE SKIP LOCKED`, so a second worker takes the next fact instead of
+--   waiting on the first.
+--
+--   Failure — a handler that throws must not stop the queue or lose the fact.
+--   Each delivery runs in its own subtransaction: it fails alone, records why,
+--   and is retried with backoff until `max_attempts`, after which it is
+--   `failed` and visible rather than retried forever.
+--
+-- WHAT THIS FILE DOES NOT DO. It does not schedule anything. Who calls
+-- `consume_event_log()` — pg_cron, an edge function, the app — is deployment,
+-- and a migration that assumed one would be wrong in every pool that uses
+-- another.
+-- ============================================================================
+
+-- ─────────────────────────────────────────────────────────────────────────
+-- §1  Subscriptions — a plugin declares what it reacts to, as a row
+-- ─────────────────────────────────────────────────────────────────────────
+
+CREATE TABLE IF NOT EXISTS public.event_subscriptions (
+  plugin       text NOT NULL,
+  event_key    text NOT NULL,
+  handler      text NOT NULL,
+  description  text,
+  max_attempts integer NOT NULL DEFAULT 5 CHECK (max_attempts BETWEEN 1 AND 50),
+  is_active    boolean NOT NULL DEFAULT true,
+  created_at   timestamptz NOT NULL DEFAULT now(),
+  updated_at   timestamptz NOT NULL DEFAULT now(),
+  PRIMARY KEY (plugin, event_key, handler),
+  CONSTRAINT event_subscriptions_handler_shape CHECK (handler ~ '^[a-z][a-z0-9_]*$')
+);
+
+COMMENT ON TABLE public.event_subscriptions IS
+  'Who reacts to which fact (149). A plugin declares its subscription as a ROW in its own migration — never by DDL on someone else''s table. handler is the name of a public function taking (jsonb) and returning jsonb.';
+COMMENT ON COLUMN public.event_subscriptions.handler IS
+  'A public function name. It receives the whole event row as jsonb and returns jsonb (its result, recorded on the delivery). Raising is how it says it failed.';
+
+ALTER TABLE public.event_subscriptions ENABLE ROW LEVEL SECURITY;
+DROP POLICY IF EXISTS event_subscriptions_read ON public.event_subscriptions;
+CREATE POLICY event_subscriptions_read ON public.event_subscriptions
+  FOR SELECT TO authenticated, service_role USING (true);
+GRANT SELECT ON public.event_subscriptions TO authenticated, service_role;
+GRANT ALL ON public.event_subscriptions TO service_role;
+REVOKE INSERT, UPDATE, DELETE ON public.event_subscriptions FROM anon, authenticated;
+
+DROP TRIGGER IF EXISTS event_subscriptions_updated_at ON public.event_subscriptions;
+CREATE TRIGGER event_subscriptions_updated_at BEFORE UPDATE ON public.event_subscriptions
+  FOR EACH ROW EXECUTE FUNCTION public.handle_updated_at();
+
+CREATE OR REPLACE FUNCTION public.register_event_subscription(
+  p_plugin       text,
+  p_event_key    text,
+  p_handler      text,
+  p_description  text DEFAULT NULL,
+  p_max_attempts integer DEFAULT 5
+) RETURNS void
+LANGUAGE plpgsql SECURITY DEFINER SET search_path = ''
+AS $$
+BEGIN
+  INSERT INTO public.event_subscriptions (plugin, event_key, handler, description, max_attempts)
+  VALUES (p_plugin, p_event_key, p_handler, p_description, p_max_attempts)
+  ON CONFLICT (plugin, event_key, handler) DO UPDATE
+    SET description  = coalesce(EXCLUDED.description, public.event_subscriptions.description),
+        max_attempts = EXCLUDED.max_attempts,
+        is_active    = true;
+END $$;
+
+REVOKE ALL ON FUNCTION public.register_event_subscription(text, text, text, text, integer) FROM public, anon, authenticated;
+GRANT EXECUTE ON FUNCTION public.register_event_subscription(text, text, text, text, integer) TO service_role;
+
+-- ─────────────────────────────────────────────────────────────────────────
+-- §2  Deliveries — one row per (fact, subscriber), which is what makes a
+--     second run harmless
+-- ─────────────────────────────────────────────────────────────────────────
+
+CREATE TABLE IF NOT EXISTS public.event_deliveries (
+  event_id        uuid NOT NULL REFERENCES public.event_log(id) ON DELETE CASCADE,
+  plugin          text NOT NULL,
+  handler         text NOT NULL,
+  status          text NOT NULL DEFAULT 'pending'
+                  CHECK (status IN ('pending', 'delivered', 'failed', 'abandoned')),
+  attempts        integer NOT NULL DEFAULT 0,
+  next_attempt_at timestamptz NOT NULL DEFAULT now(),
+  result          jsonb,
+  error           text,
+  created_at      timestamptz NOT NULL DEFAULT now(),
+  updated_at      timestamptz NOT NULL DEFAULT now(),
+  PRIMARY KEY (event_id, plugin, handler)
+);
+
+COMMENT ON TABLE public.event_deliveries IS
+  'One row per (fact, subscriber) — the idempotence guarantee (149). The consumer inserts the row before calling the handler, so a second run collides instead of acting twice. `abandoned` is a delivery that used up max_attempts: still visible, no longer retried.';
+
+CREATE INDEX IF NOT EXISTS event_deliveries_due
+  ON public.event_deliveries (next_attempt_at)
+  WHERE status = 'pending';
+
+ALTER TABLE public.event_deliveries ENABLE ROW LEVEL SECURITY;
+DROP POLICY IF EXISTS event_deliveries_read ON public.event_deliveries;
+CREATE POLICY event_deliveries_read ON public.event_deliveries
+  FOR SELECT TO authenticated, service_role USING (true);
+GRANT SELECT ON public.event_deliveries TO authenticated, service_role;
+GRANT ALL ON public.event_deliveries TO service_role;
+REVOKE INSERT, UPDATE, DELETE ON public.event_deliveries FROM anon, authenticated;
+
+DROP TRIGGER IF EXISTS event_deliveries_updated_at ON public.event_deliveries;
+CREATE TRIGGER event_deliveries_updated_at BEFORE UPDATE ON public.event_deliveries
+  FOR EACH ROW EXECUTE FUNCTION public.handle_updated_at();
+
+-- ─────────────────────────────────────────────────────────────────────────
+-- §3  The consumer
+--
+-- Claims up to p_limit facts that still have work, delivers each subscription in
+-- its own subtransaction, and moves the fact's status only when every
+-- subscription has finished. Returns a summary so a scheduler can log something
+-- meaningful and back off when there is nothing to do.
+-- ─────────────────────────────────────────────────────────────────────────
+
+CREATE OR REPLACE FUNCTION public.consume_event_log(
+  p_limit integer DEFAULT 100,
+  p_event_key text DEFAULT NULL
+) RETURNS TABLE (
+  events_claimed    integer,
+  deliveries_ok     integer,
+  deliveries_failed integer,
+  deliveries_abandoned integer
+)
+LANGUAGE plpgsql SECURITY DEFINER SET search_path = ''
+AS $$
+DECLARE
+  v_event      record;
+  v_sub        record;
+  v_result     jsonb;
+  v_attempts   integer;
+  v_claimed    integer := 0;
+  v_ok         integer := 0;
+  v_failed     integer := 0;
+  v_abandoned  integer := 0;
+  v_open       integer;
+BEGIN
+  FOR v_event IN
+    SELECT e.*
+      FROM public.event_log e
+     WHERE e.status = 'recorded'
+       AND (p_event_key IS NULL OR e.event_key = p_event_key)
+     ORDER BY e.occurred_at
+     LIMIT greatest(p_limit, 0)
+     FOR UPDATE SKIP LOCKED
+  LOOP
+    v_claimed := v_claimed + 1;
+
+    -- No subscriber is not a failure: the fact is recorded and nobody asked for
+    -- it. `skipped` is 027's own word for that.
+    IF NOT EXISTS (
+      SELECT 1 FROM public.event_subscriptions s
+       WHERE s.event_key = v_event.event_key AND s.is_active
+    ) THEN
+      UPDATE public.event_log SET status = 'skipped' WHERE id = v_event.id;
+      CONTINUE;
+    END IF;
+
+    FOR v_sub IN
+      SELECT s.* FROM public.event_subscriptions s
+       WHERE s.event_key = v_event.event_key AND s.is_active
+       ORDER BY s.plugin, s.handler
+    LOOP
+      -- The claim comes first: this row existing is what a second consumer
+      -- collides with.
+      INSERT INTO public.event_deliveries (event_id, plugin, handler)
+      VALUES (v_event.id, v_sub.plugin, v_sub.handler)
+      ON CONFLICT (event_id, plugin, handler) DO NOTHING;
+
+      SELECT d.attempts INTO v_attempts
+        FROM public.event_deliveries d
+       WHERE d.event_id = v_event.id AND d.plugin = v_sub.plugin AND d.handler = v_sub.handler
+         AND d.status = 'pending' AND d.next_attempt_at <= now()
+       FOR UPDATE SKIP LOCKED;
+
+      IF NOT FOUND THEN
+        CONTINUE;  -- already delivered, abandoned, or not due yet
+      END IF;
+
+      BEGIN
+        EXECUTE format('SELECT public.%I($1)', v_sub.handler)
+          INTO v_result
+          USING to_jsonb(v_event);
+
+        UPDATE public.event_deliveries
+           SET status = 'delivered', attempts = v_attempts + 1, result = v_result, error = NULL
+         WHERE event_id = v_event.id AND plugin = v_sub.plugin AND handler = v_sub.handler;
+        v_ok := v_ok + 1;
+
+      EXCEPTION WHEN OTHERS THEN
+        -- Fails alone. The subtransaction rolls back whatever the handler did,
+        -- so a half-applied effect cannot survive its own error.
+        IF v_attempts + 1 >= v_sub.max_attempts THEN
+          UPDATE public.event_deliveries
+             SET status = 'abandoned', attempts = v_attempts + 1, error = SQLERRM
+           WHERE event_id = v_event.id AND plugin = v_sub.plugin AND handler = v_sub.handler;
+          v_abandoned := v_abandoned + 1;
+        ELSE
+          UPDATE public.event_deliveries
+             SET status = 'pending', attempts = v_attempts + 1, error = SQLERRM,
+                 -- Backoff, capped: 2^n seconds up to an hour.
+                 next_attempt_at = now() + least(interval '1 hour', (power(2, v_attempts + 1) || ' seconds')::interval)
+           WHERE event_id = v_event.id AND plugin = v_sub.plugin AND handler = v_sub.handler;
+          v_failed := v_failed + 1;
+        END IF;
+      END;
+    END LOOP;
+
+    -- The fact moves only when nothing is still owed.
+    SELECT count(*)::int INTO v_open
+      FROM public.event_deliveries d
+     WHERE d.event_id = v_event.id AND d.status = 'pending';
+
+    IF v_open = 0 THEN
+      UPDATE public.event_log
+         SET status = CASE
+               WHEN EXISTS (SELECT 1 FROM public.event_deliveries d WHERE d.event_id = v_event.id AND d.status = 'abandoned')
+                 THEN 'failed' ELSE 'sent' END,
+             result = (SELECT jsonb_object_agg(d.plugin || '.' || d.handler, coalesce(d.result, to_jsonb(d.status)))
+                         FROM public.event_deliveries d WHERE d.event_id = v_event.id),
+             error = (SELECT string_agg(d.plugin || '.' || d.handler || ': ' || d.error, '; ')
+                        FROM public.event_deliveries d WHERE d.event_id = v_event.id AND d.error IS NOT NULL)
+       WHERE id = v_event.id;
+    END IF;
+  END LOOP;
+
+  RETURN QUERY SELECT v_claimed, v_ok, v_failed, v_abandoned;
+END $$;
+
+COMMENT ON FUNCTION public.consume_event_log(integer, text) IS
+  'Delivers recorded facts to their declared subscribers (149). Idempotent by (event, plugin, handler); concurrent-safe by SKIP LOCKED; a failing handler fails alone, is retried with capped backoff and is abandoned — visibly — after max_attempts. Scheduling is deployment, not schema.';
+
+REVOKE ALL ON FUNCTION public.consume_event_log(integer, text) FROM public, anon, authenticated;
+GRANT EXECUTE ON FUNCTION public.consume_event_log(integer, text) TO service_role;
+
+-- ─────────────────────────────────────────────────────────────────────────
+-- §4  What the queue looks like from outside
+-- ─────────────────────────────────────────────────────────────────────────
+
+CREATE OR REPLACE VIEW public.v_event_queue
+WITH (security_invoker = true) AS
+SELECT e.event_key,
+       e.status,
+       count(*)::bigint                                   AS facts,
+       min(e.occurred_at)                                 AS oldest,
+       count(*) FILTER (WHERE d.status = 'pending')::bigint   AS deliveries_pending,
+       count(*) FILTER (WHERE d.status = 'abandoned')::bigint AS deliveries_abandoned
+  FROM public.event_log e
+  LEFT JOIN public.event_deliveries d ON d.event_id = e.id
+ GROUP BY e.event_key, e.status;
+
+COMMENT ON VIEW public.v_event_queue IS
+  'The queue at a glance (149): facts by key and status, with what is still owed and what was abandoned. "Why did the stock not move?" is answered here rather than by asking each plugin.';
+
+GRANT SELECT ON public.v_event_queue TO authenticated, service_role;
+
+-- ─────────────────────────────────────────────────────────────────────────
+-- §5  The first fact worth reacting to: a Venda reaches completed
+--
+-- Emitted AFTER the row is written, so the fact is recorded only if the sale
+-- actually happened, and outside the writer's decision — nothing a subscriber
+-- does can roll the sale back. That asymmetry is the point of the log.
+--
+-- Only the transition INTO a completed state emits: an UPDATE that touches a
+-- note on an already-completed order is not a new fact.
+-- ─────────────────────────────────────────────────────────────────────────
+
+CREATE OR REPLACE FUNCTION public.trg_orders_emit_completed()
+RETURNS trigger
+LANGUAGE plpgsql SECURITY DEFINER SET search_path = ''
+AS $$
+BEGIN
+  IF NEW.status IS DISTINCT FROM 'completed' THEN
+    RETURN NULL;
+  END IF;
+  IF TG_OP = 'UPDATE' AND OLD.status IS NOT DISTINCT FROM 'completed' THEN
+    RETURN NULL;
+  END IF;
+
+  PERFORM public.plg_emit_event(
+    'order.completed',
+    jsonb_build_object(
+      'order_id',  NEW.id,
+      'kind',      NEW.kind,
+      'unit_id',   NEW.unit_id,
+      'party_id',  NEW.party_id,
+      'total',     NEW.total
+    ),
+    'order',
+    NEW.id::text,
+    NEW.tenant_id,
+    NULL
+  );
+  RETURN NULL;
+END $$;
+
+COMMENT ON FUNCTION public.trg_orders_emit_completed() IS
+  'Records the fact that a Venda completed (149). AFTER, so the fact follows the write; only on the transition, so an edit to a completed order is not a second fact.';
+
+REVOKE ALL ON FUNCTION public.trg_orders_emit_completed() FROM public, anon, authenticated;
+
+DROP TRIGGER IF EXISTS orders_emit_completed ON public.orders;
+CREATE TRIGGER orders_emit_completed
+  AFTER INSERT OR UPDATE OF status ON public.orders
+  FOR EACH ROW EXECUTE FUNCTION public.trg_orders_emit_completed();

package/migrations/150_the_app_is_configured_in_the_database.sql

@@ -0,0 +1,285 @@
+-- ============================================================================
+-- 150_the_app_is_configured_in_the_database.sql — what a tenant HAS stops being
+-- a file in a repository (#280, ADR 0023).
+--
+-- The split the decision fixes: the MANIFEST is what a plugin CAN do — routes,
+-- screens, the permissions it declares, the species it registers. The DATABASE
+-- is what THIS tenant HAS — which plugins are on, which parts of them, how the
+-- menu is composed, what the branding is. Those were the same thing, living in
+-- `app.manifest.json` next to the code, which is why eleven applications needed
+-- eleven repositories and why turning a feature on meant a deploy.
+--
+-- WHAT WAS ALREADY HERE, and is not rebuilt: `tenants.settings` with the
+-- registry in `app.tenant_setting_keys` (076) already governs branding, locale
+-- and every other keyed setting, RPCs included. This file adds the two things
+-- that had no home at all:
+--
+--   §1  ACTIVATION — which plugins and which facets this tenant has. The type
+--       `TenantPluginBinding` has existed in @fayz-ai/core since the runtime was
+--       written, and nothing ever persisted it: activation lived in a file.
+--   §2  NAVIGATION — the tenant's own composition over what the plugins offer:
+--       order, hidden entries, renamed labels.
+--
+-- §3 is the one call that returns all of it, which is what makes the shell able
+-- to render from the database instead of from a bundle.
+--
+-- WHAT THIS FILE DOES NOT DECIDE. Whether the plan permits an activation is
+-- #281's question, and the column it will read (`source`) is already here so
+-- that answer does not need a second migration to change shape. Until then any
+-- activation is allowed and `source` records who did it.
+--
+-- Idempotent and replay-safe.
+-- ============================================================================
+
+-- ─────────────────────────────────────────────────────────────────────────
+-- §1  Activation — plugin and facet, per tenant
+--
+-- One table, not two: a facet is a part of a plugin, and (tenant, plugin, '')
+-- is the plugin itself. Two tables would have made "is this on?" a union in
+-- every reader.
+-- ─────────────────────────────────────────────────────────────────────────
+
+CREATE TABLE IF NOT EXISTS app.tenant_plugins (
+  tenant_id    uuid NOT NULL REFERENCES public.tenants(id) ON DELETE CASCADE,
+  plugin_id    text NOT NULL CHECK (plugin_id ~ '^[a-z][a-z0-9-]*$'),
+  facet        text NOT NULL DEFAULT '' CHECK (facet = '' OR facet ~ '^[a-z][a-z0-9_-]*$'),
+  status       text NOT NULL DEFAULT 'active' CHECK (status IN ('active', 'disabled')),
+  config       jsonb NOT NULL DEFAULT '{}'::jsonb,
+  source       text NOT NULL DEFAULT 'manual' CHECK (source IN ('manual', 'plan', 'trial', 'agent', 'default')),
+  expires_at   timestamptz,
+  activated_by uuid,
+  created_at   timestamptz NOT NULL DEFAULT now(),
+  updated_at   timestamptz NOT NULL DEFAULT now(),
+  PRIMARY KEY (tenant_id, plugin_id, facet)
+);
+
+COMMENT ON TABLE app.tenant_plugins IS
+  'What this tenant HAS (150, ADR 0023): which plugins are on, and which facets of them. The manifest says what a plugin CAN do; this says what is on here. facet = '''' is the plugin itself.';
+COMMENT ON COLUMN app.tenant_plugins.source IS
+  'Who turned it on: manual (an operator), plan (an entitlement), trial (with expires_at), agent (onboarding), default (the plugin ships defaultEnabled). #281 reads this to know what a plan change may switch off.';
+COMMENT ON COLUMN app.tenant_plugins.expires_at IS
+  'When a trial or courtesy ends. NULL is forever. Enforced by the reader — a row that has expired is not active, and nothing has to run to make that true.';
+
+CREATE INDEX IF NOT EXISTS tenant_plugins_active
+  ON app.tenant_plugins (tenant_id)
+  WHERE status = 'active';
+
+ALTER TABLE app.tenant_plugins ENABLE ROW LEVEL SECURITY;
+DROP POLICY IF EXISTS tenant_plugins_read ON app.tenant_plugins;
+CREATE POLICY tenant_plugins_read ON app.tenant_plugins
+  FOR SELECT TO authenticated
+  USING (tenant_id IN (SELECT public.user_tenant_ids()));
+GRANT SELECT ON app.tenant_plugins TO authenticated;
+GRANT ALL ON app.tenant_plugins TO service_role;
+
+DROP TRIGGER IF EXISTS tenant_plugins_updated_at ON app.tenant_plugins;
+CREATE TRIGGER tenant_plugins_updated_at BEFORE UPDATE ON app.tenant_plugins
+  FOR EACH ROW EXECUTE FUNCTION public.handle_updated_at();
+
+-- ─────────────────────────────────────────────────────────────────────────
+-- §2  Navigation — the tenant's composition over what the plugins offer
+--
+-- Only the DIFFERENCE is stored. A plugin's nav entry is the default; a row
+-- here hides it, renames it or moves it. Storing the whole menu would mean a
+-- tenant stops receiving new entries the day a plugin ships one.
+-- ─────────────────────────────────────────────────────────────────────────
+
+CREATE TABLE IF NOT EXISTS app.tenant_nav (
+  tenant_id  uuid NOT NULL REFERENCES public.tenants(id) ON DELETE CASCADE,
+  entry_key  text NOT NULL,
+  hidden     boolean NOT NULL DEFAULT false,
+  label      text,
+  section    text CHECK (section IS NULL OR section IN ('main', 'secondary', 'settings')),
+  position   integer,
+  created_at timestamptz NOT NULL DEFAULT now(),
+  updated_at timestamptz NOT NULL DEFAULT now(),
+  PRIMARY KEY (tenant_id, entry_key)
+);
+
+COMMENT ON TABLE app.tenant_nav IS
+  'The tenant''s own menu composition (150): only the difference from what the plugins offer. A plugin that ships a new entry reaches every tenant; a tenant that hid one keeps it hidden.';
+COMMENT ON COLUMN app.tenant_nav.entry_key IS
+  'The nav entry''s stable key — `<plugin>:<route>` as the shell composes it.';
+
+ALTER TABLE app.tenant_nav ENABLE ROW LEVEL SECURITY;
+DROP POLICY IF EXISTS tenant_nav_read ON app.tenant_nav;
+CREATE POLICY tenant_nav_read ON app.tenant_nav
+  FOR SELECT TO authenticated
+  USING (tenant_id IN (SELECT public.user_tenant_ids()));
+GRANT SELECT ON app.tenant_nav TO authenticated;
+GRANT ALL ON app.tenant_nav TO service_role;
+
+DROP TRIGGER IF EXISTS tenant_nav_updated_at ON app.tenant_nav;
+CREATE TRIGGER tenant_nav_updated_at BEFORE UPDATE ON app.tenant_nav
+  FOR EACH ROW EXECUTE FUNCTION public.handle_updated_at();
+
+-- ─────────────────────────────────────────────────────────────────────────
+-- §3  Is it on? — one function, so no reader has to know about expiry
+-- ─────────────────────────────────────────────────────────────────────────
+
+CREATE OR REPLACE FUNCTION public.tenant_plugin_active(p_plugin text, p_facet text DEFAULT '')
+RETURNS boolean
+LANGUAGE sql STABLE SECURITY DEFINER SET search_path = ''
+AS $$
+  SELECT EXISTS (
+    SELECT 1 FROM app.tenant_plugins t
+     WHERE t.tenant_id = app.current_tenant_id()
+       AND t.plugin_id = p_plugin
+       AND t.facet = coalesce(p_facet, '')
+       AND t.status = 'active'
+       AND (t.expires_at IS NULL OR t.expires_at > now())
+  )
+$$;
+
+COMMENT ON FUNCTION public.tenant_plugin_active(text, text) IS
+  'Whether this plugin (or one of its facets) is on for the current tenant, expiry included (150). One place, so a trial that lapsed cannot be on in one reader and off in another.';
+
+GRANT EXECUTE ON FUNCTION public.tenant_plugin_active(text, text) TO authenticated, service_role;
+
+-- ─────────────────────────────────────────────────────────────────────────
+-- §4  The single initial load
+--
+-- One call, one round trip, cacheable: everything the shell needs to render
+-- before it knows anything else. Branding comes from 076's RPC — which never
+-- raises, because branding must not be able to block a login.
+-- ─────────────────────────────────────────────────────────────────────────
+
+CREATE OR REPLACE FUNCTION public.app_config()
+RETURNS jsonb
+LANGUAGE plpgsql STABLE SECURITY DEFINER SET search_path = ''
+AS $$
+DECLARE
+  v_tenant uuid := app.current_tenant_id();
+BEGIN
+  IF v_tenant IS NULL THEN
+    -- Fail closed and legibly: a caller with no resolvable tenant gets an empty
+    -- configuration, not somebody else's.
+    RETURN jsonb_build_object('tenant_id', NULL, 'plugins', '[]'::jsonb, 'nav', '[]'::jsonb);
+  END IF;
+
+  RETURN jsonb_build_object(
+    'tenant_id', v_tenant,
+    'branding',  public.tenant_branding(),
+    'settings',  public.tenant_settings(),
+    'plugins', coalesce((
+      SELECT jsonb_agg(jsonb_build_object(
+               'plugin', t.plugin_id,
+               'facet',  nullif(t.facet, ''),
+               'status', t.status,
+               'source', t.source,
+               'config', t.config,
+               'expires_at', t.expires_at
+             ) ORDER BY t.plugin_id, t.facet)
+        FROM app.tenant_plugins t
+       WHERE t.tenant_id = v_tenant
+         AND t.status = 'active'
+         AND (t.expires_at IS NULL OR t.expires_at > now())
+    ), '[]'::jsonb),
+    'nav', coalesce((
+      SELECT jsonb_agg(jsonb_build_object(
+               'key', n.entry_key, 'hidden', n.hidden, 'label', n.label,
+               'section', n.section, 'position', n.position
+             ) ORDER BY coalesce(n.position, 999), n.entry_key)
+        FROM app.tenant_nav n
+       WHERE n.tenant_id = v_tenant
+    ), '[]'::jsonb),
+    'permissions', coalesce((
+      SELECT jsonb_agg(DISTINCT rp.permission)
+        FROM app.memberships m
+        JOIN app.role_permissions rp ON rp.role_id = m.role_id AND rp.tenant_id = m.tenant_id
+       WHERE m.tenant_id = v_tenant AND m.user_id = auth.uid() AND m.active
+    ), '[]'::jsonb),
+    'generated_at', now()
+  );
+END $$;
+
+COMMENT ON FUNCTION public.app_config() IS
+  'Everything the shell needs to render, in one call (150, ADR 0023): branding, settings, active plugins and facets, the tenant''s nav composition and the caller''s permissions. Cacheable per (tenant, user); invalidated by any write through the RPCs below.';
+
+GRANT EXECUTE ON FUNCTION public.app_config() TO authenticated, service_role;
+
+-- ─────────────────────────────────────────────────────────────────────────
+-- §5  The write surface — scoped, permissioned, and the only door
+--
+-- The agent configures the system through this, never through raw SQL: it is
+-- bounded by the caller's tenant and by `settings.manage`, so an onboarding
+-- assistant cannot reach another tenant even if it tries.
+-- ─────────────────────────────────────────────────────────────────────────
+
+CREATE OR REPLACE FUNCTION public.tenant_plugin_set(
+  p_plugin  text,
+  p_status  text DEFAULT 'active',
+  p_facet   text DEFAULT '',
+  p_config  jsonb DEFAULT NULL,
+  p_source  text DEFAULT 'manual',
+  p_expires timestamptz DEFAULT NULL
+) RETURNS jsonb
+LANGUAGE plpgsql SECURITY DEFINER SET search_path = ''
+AS $$
+DECLARE
+  v_tenant uuid := app.current_tenant_id();
+BEGIN
+  IF v_tenant IS NULL THEN
+    RAISE EXCEPTION 'no tenant in scope' USING ERRCODE = '42501';
+  END IF;
+  IF NOT app.has_permission('settings.manage') THEN
+    RAISE EXCEPTION 'settings.manage is required to change what this account has'
+      USING ERRCODE = '42501';
+  END IF;
+  IF p_status NOT IN ('active', 'disabled') THEN
+    RAISE EXCEPTION 'status must be active or disabled' USING ERRCODE = '22023';
+  END IF;
+
+  INSERT INTO app.tenant_plugins (tenant_id, plugin_id, facet, status, config, source, expires_at, activated_by)
+  VALUES (v_tenant, p_plugin, coalesce(p_facet, ''), p_status, coalesce(p_config, '{}'::jsonb), p_source, p_expires, auth.uid())
+  ON CONFLICT (tenant_id, plugin_id, facet) DO UPDATE
+    SET status       = EXCLUDED.status,
+        config       = coalesce(p_config, app.tenant_plugins.config),
+        source       = EXCLUDED.source,
+        expires_at   = EXCLUDED.expires_at,
+        activated_by = EXCLUDED.activated_by;
+
+  RETURN jsonb_build_object('plugin', p_plugin, 'facet', nullif(coalesce(p_facet, ''), ''), 'status', p_status);
+END $$;
+
+COMMENT ON FUNCTION public.tenant_plugin_set(text, text, text, jsonb, text, timestamptz) IS
+  'Turns a plugin or facet on or off for the CURRENT tenant (150). The only door: bounded by the caller''s tenant and by settings.manage, which is what lets the onboarding agent use it without being able to reach anyone else. Turning off changes what is seen, never what is stored.';
+
+REVOKE ALL ON FUNCTION public.tenant_plugin_set(text, text, text, jsonb, text, timestamptz) FROM public, anon;
+GRANT EXECUTE ON FUNCTION public.tenant_plugin_set(text, text, text, jsonb, text, timestamptz) TO authenticated, service_role;
+
+CREATE OR REPLACE FUNCTION public.tenant_nav_set(
+  p_entry_key text,
+  p_hidden    boolean DEFAULT NULL,
+  p_label     text DEFAULT NULL,
+  p_section   text DEFAULT NULL,
+  p_position  integer DEFAULT NULL
+) RETURNS jsonb
+LANGUAGE plpgsql SECURITY DEFINER SET search_path = ''
+AS $$
+DECLARE
+  v_tenant uuid := app.current_tenant_id();
+BEGIN
+  IF v_tenant IS NULL THEN
+    RAISE EXCEPTION 'no tenant in scope' USING ERRCODE = '42501';
+  END IF;
+  IF NOT app.has_permission('settings.manage') THEN
+    RAISE EXCEPTION 'settings.manage is required to change the menu' USING ERRCODE = '42501';
+  END IF;
+
+  INSERT INTO app.tenant_nav (tenant_id, entry_key, hidden, label, section, position)
+  VALUES (v_tenant, p_entry_key, coalesce(p_hidden, false), p_label, p_section, p_position)
+  ON CONFLICT (tenant_id, entry_key) DO UPDATE
+    SET hidden   = coalesce(p_hidden, app.tenant_nav.hidden),
+        label    = coalesce(p_label, app.tenant_nav.label),
+        section  = coalesce(p_section, app.tenant_nav.section),
+        position = coalesce(p_position, app.tenant_nav.position);
+
+  RETURN jsonb_build_object('entry', p_entry_key);
+END $$;
+
+COMMENT ON FUNCTION public.tenant_nav_set(text, boolean, text, text, integer) IS
+  'Hides, renames or moves one menu entry for the current tenant (150). Only the difference is stored, so a plugin that ships a new entry still reaches everyone.';
+
+REVOKE ALL ON FUNCTION public.tenant_nav_set(text, boolean, text, text, integer) FROM public, anon;
+GRANT EXECUTE ON FUNCTION public.tenant_nav_set(text, boolean, text, text, integer) TO authenticated, service_role;