@fayz-ai/db 0.12.0 → 0.13.0

package/migrations/151_stock_balance_is_an_archetype.sql

@@ -0,0 +1,144 @@
+-- ============================================================================
+-- 151_stock_balance_is_an_archetype.sql — how much there is, in one place
+-- (#276, ADR 0024).
+--
+-- Two books have been kept for the same number. `plg_inventory_stock_positions`
+-- counts by (product, location, batch, expiry) in numeric; `plg_shop_stock_
+-- balances` counts by (variant, location, lot) in integers, with its own
+-- reserved/available. 146 measured the consequence and wrote it down: restaurant
+-- disagreed with itself by 20 units, salon by 29, and the ecommerce pool held
+-- 1,200,449 on one book against 12 on the other. Its answer was a register
+-- saying which book wins per tenant — the right answer for that day, and not an
+-- answer to the question, which is that a number with two writers has no owner.
+--
+-- THE GRAIN, and why it is not the finer one. The archetype counts by
+-- (variant × UNIT), not by (variant × shelf). A unit is a base concept every
+-- plugin already shares — it is where the tenant operates. A shelf, a lot, a
+-- batch and an expiry date are how a particular plugin organises what sits in
+-- that unit, and they stay with that plugin, summing into the archetype. That
+-- is the same shape the whole model uses: the base owns the form every plugin
+-- needs, the plugin owns its own detail.
+--
+-- THE WRITER. One: `public.stock_apply`. RLS denies direct writes to the table
+-- outright, so "who moved the stock" has exactly one answer and the movement
+-- that caused it is recorded on the row. plugin-inventory calls it from the
+-- trigger it already has on its movements; the shop's own decrement keeps
+-- running for now and its cutover is #276's remaining half, gated on the
+-- reconciliation view below reading zero.
+--
+-- WHAT THIS FILE DELIBERATELY DOES NOT DO. It does not revoke the shop's writes
+-- to its own book. Doing that in the same migration that introduces the
+-- archetype would be a cutover with no way back on a pool holding a million
+-- units — and 148 already set the precedent for the honest order: introduce,
+-- reconcile, then retire with the count in hand.
+--
+-- Idempotent and replay-safe.
+-- ============================================================================
+
+-- ─────────────────────────────────────────────────────────────────────────
+-- §1  The balance
+-- ─────────────────────────────────────────────────────────────────────────
+
+CREATE TABLE IF NOT EXISTS public.stock_balances (
+  tenant_id   uuid NOT NULL REFERENCES public.tenants(id) ON DELETE CASCADE,
+  variant_id  uuid NOT NULL REFERENCES public.product_variants(id) ON DELETE CASCADE,
+  unit_id     uuid,
+  on_hand     numeric(14,4) NOT NULL DEFAULT 0,
+  reserved    numeric(14,4) NOT NULL DEFAULT 0 CHECK (reserved >= 0),
+  available   numeric(14,4) GENERATED ALWAYS AS (on_hand - reserved) STORED,
+  updated_at  timestamptz NOT NULL DEFAULT now(),
+  updated_by  text,
+  id          uuid PRIMARY KEY DEFAULT gen_random_uuid()
+);
+
+COMMENT ON TABLE public.stock_balances IS
+  'How much of a variant a unit has (151, ADR 0024). The archetype: one number, one writer (public.stock_apply). Batches, lots, shelves and expiry dates are plugin detail that sums into this — the base owns the form, the plugin owns its own grain.';
+COMMENT ON COLUMN public.stock_balances.unit_id IS
+  'The operating unit holding it. NULL is the tenant-wide balance, for a tenant that does not separate stock by unit.';
+COMMENT ON COLUMN public.stock_balances.updated_by IS
+  'Which book last moved this number. With one writer this is a breadcrumb, not arbitration — 146 needed arbitration because there were two.';
+
+-- A tenant-wide balance is a real thing (a tenant that does not separate stock
+-- by unit), and NULL is how it is spelled — which a composite PRIMARY KEY cannot
+-- hold, because every PK column is NOT NULL. The identity is therefore an
+-- expression index, and `stock_apply` upserts on exactly that expression: one
+-- row per (tenant, variant, unit-or-tenant-wide), NULL included.
+CREATE UNIQUE INDEX IF NOT EXISTS stock_balances_identity
+  ON public.stock_balances (tenant_id, variant_id, coalesce(unit_id, '00000000-0000-0000-0000-000000000000'::uuid));
+
+ALTER TABLE public.stock_balances ENABLE ROW LEVEL SECURITY;
+
+-- 002's generic sweep gives every public table carrying tenant_id the four
+-- `tenant_isolation_*` policies, and on a REPLAY it meets this table and hands
+-- it an INSERT, an UPDATE and a DELETE — which would make "one writer" a
+-- comment rather than a rule. It runs before this file on every pass, so
+-- dropping them here is what holds, and holds again on the next replay.
+DROP POLICY IF EXISTS tenant_isolation_select ON public.stock_balances;
+DROP POLICY IF EXISTS tenant_isolation_insert ON public.stock_balances;
+DROP POLICY IF EXISTS tenant_isolation_update ON public.stock_balances;
+DROP POLICY IF EXISTS tenant_isolation_delete ON public.stock_balances;
+
+-- Read for the tenant; NOBODY writes directly. The absence of an INSERT/UPDATE
+-- policy is the point: `stock_apply` is SECURITY DEFINER and is the only path.
+DROP POLICY IF EXISTS stock_balances_read ON public.stock_balances;
+CREATE POLICY stock_balances_read ON public.stock_balances
+  FOR SELECT TO authenticated
+  USING (tenant_id IN (SELECT public.user_tenant_ids()));
+GRANT SELECT ON public.stock_balances TO authenticated;
+GRANT ALL ON public.stock_balances TO service_role;
+REVOKE INSERT, UPDATE, DELETE ON public.stock_balances FROM anon, authenticated;
+
+-- ─────────────────────────────────────────────────────────────────────────
+-- §2  The only writer
+-- ─────────────────────────────────────────────────────────────────────────
+
+CREATE OR REPLACE FUNCTION public.stock_apply(
+  p_tenant    uuid,
+  p_variant   uuid,
+  p_unit      uuid,
+  p_on_hand   numeric DEFAULT 0,
+  p_reserved  numeric DEFAULT 0,
+  p_source    text DEFAULT 'inventory'
+) RETURNS jsonb
+LANGUAGE plpgsql SECURITY DEFINER SET search_path = ''
+AS $$
+DECLARE
+  v_on_hand  numeric;
+  v_reserved numeric;
+BEGIN
+  IF p_tenant IS NULL OR p_variant IS NULL THEN
+    RAISE EXCEPTION 'stock_apply: tenant and variant are required' USING ERRCODE = '22023';
+  END IF;
+
+  INSERT INTO public.stock_balances (tenant_id, variant_id, unit_id, on_hand, reserved, updated_by)
+  VALUES (p_tenant, p_variant, p_unit, coalesce(p_on_hand, 0), greatest(coalesce(p_reserved, 0), 0), p_source)
+  ON CONFLICT (tenant_id, variant_id, coalesce(unit_id, '00000000-0000-0000-0000-000000000000'::uuid)) DO UPDATE
+    SET on_hand    = public.stock_balances.on_hand + coalesce(p_on_hand, 0),
+        reserved   = greatest(public.stock_balances.reserved + coalesce(p_reserved, 0), 0),
+        updated_at = now(),
+        updated_by = p_source
+  RETURNING on_hand, reserved INTO v_on_hand, v_reserved;
+
+  -- Below zero is a data question, not a rounding one: the caller that asked for
+  -- it is the one that has to answer.
+  IF v_on_hand < 0 THEN
+    RAISE EXCEPTION 'stock_apply: % would take variant % below zero (%)', p_source, p_variant, v_on_hand
+      USING ERRCODE = '23514';
+  END IF;
+
+  RETURN jsonb_build_object('on_hand', v_on_hand, 'reserved', v_reserved, 'available', v_on_hand - v_reserved);
+END $$;
+
+COMMENT ON FUNCTION public.stock_apply(uuid, uuid, uuid, numeric, numeric, text) IS
+  'The only writer of public.stock_balances (151). Applies a DELTA — a movement, not a number — which is what makes two concurrent sales add up instead of overwrite each other. Below zero raises: it is a data question, and the caller is who answers it.';
+
+REVOKE ALL ON FUNCTION public.stock_apply(uuid, uuid, uuid, numeric, numeric, text) FROM public, anon, authenticated;
+GRANT EXECUTE ON FUNCTION public.stock_apply(uuid, uuid, uuid, numeric, numeric, text) TO service_role;
+
+-- ─────────────────────────────────────────────────────────────────────────
+-- §3  Reconciliation lives with the book it compares against
+--
+-- "Where does the archetype disagree with the shop's book?" is half a question
+-- about a plugin's table, so the base cannot ask it: a pool without the shop has
+-- no second book and no reason to carry the view. It is packages/shop 0082.
+-- ─────────────────────────────────────────────────────────────────────────

package/migrations/152_a_file_is_an_archetype.sql

@@ -0,0 +1,222 @@
+-- ============================================================================
+-- 152_a_file_is_an_archetype.sql — the register is the base's, the bytes are
+-- somebody else's (#282, ADR 0020).
+--
+-- An attachment shows up in every domain: the photo on a record, the receipt on
+-- an invoice, the file on a form answer, the picture of a product, the document
+-- of an employee. It had no owner. `public.documents` exists and is very nearly
+-- the right shape — but plugin-forms creates it, which means a base-looking name
+-- belongs to an optional plugin, and a pool without forms has no attachments at
+-- all.
+--
+-- THE SPLIT, which is the decision: the base owns the REGISTER — who the file
+-- belongs to, what species it is, who may see it — and the BYTES live in
+-- external storage (R2, Supabase Storage), with the row pointing at them. A
+-- database is a bad filesystem, and a filesystem is a terrible permission
+-- system; each keeps what it is good at.
+--
+-- WHAT THIS BUYS, and it is the reason the decision names it: "everything you
+-- have about this person" becomes ONE query. With attachments spread across
+-- plugin tables, an LGPD erasure request is a sweep, and a plugin nobody
+-- remembered is a fine. And "who may see this file" becomes ONE rule instead of
+-- N — which is also why it has to be right, because it is now a single point of
+-- failure for every attachment in the system.
+--
+-- Ownership is transferred, not recreated: the table already exists in pools
+-- with real rows, so this file adopts it — declares the base as its owner,
+-- adds what was missing, and leaves the data alone. plugin-forms' own CREATE
+-- stays as the guarded no-op it already is.
+--
+-- Idempotent and replay-safe.
+-- ============================================================================
+
+-- ─────────────────────────────────────────────────────────────────────────
+-- §1  The archetype, adopted
+-- ─────────────────────────────────────────────────────────────────────────
+
+CREATE TABLE IF NOT EXISTS public.documents (
+  id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+  tenant_id uuid NOT NULL REFERENCES public.tenants(id) ON DELETE CASCADE,
+  kind text NOT NULL DEFAULT 'attachment',
+  person_id uuid REFERENCES public.people(id) ON DELETE SET NULL,
+  title text,
+  description text,
+  status text NOT NULL DEFAULT 'draft',
+  file_url text,
+  file_name text,
+  file_size integer,
+  mime_type text,
+  tags text[] DEFAULT '{}',
+  notes text,
+  is_active boolean NOT NULL DEFAULT true,
+  metadata jsonb DEFAULT '{}',
+  created_by uuid,
+  updated_by uuid,
+  created_at timestamptz NOT NULL DEFAULT now(),
+  updated_at timestamptz NOT NULL DEFAULT now()
+);
+
+-- What the bytes are, and where. `file_url` predates this and stays for the
+-- readers that use it; the three columns below are what a storage service needs
+-- to find, sign and delete an object without parsing a URL.
+ALTER TABLE public.documents ADD COLUMN IF NOT EXISTS storage_provider text;
+ALTER TABLE public.documents ADD COLUMN IF NOT EXISTS storage_bucket   text;
+ALTER TABLE public.documents ADD COLUMN IF NOT EXISTS storage_path     text;
+ALTER TABLE public.documents ADD COLUMN IF NOT EXISTS checksum         text;
+ALTER TABLE public.documents ADD COLUMN IF NOT EXISTS unit_id          uuid;
+ALTER TABLE public.documents ADD COLUMN IF NOT EXISTS subject_type     text;
+ALTER TABLE public.documents ADD COLUMN IF NOT EXISTS subject_id       uuid;
+
+COMMENT ON TABLE public.documents IS
+  'The Arquivo archetype (152, ADR 0020): the REGISTER of a file — who it belongs to, what species it is, who may see it. The bytes live in external storage and this row points at them. Owned by the base since 152; plugin-forms'' CREATE is a guarded no-op.';
+COMMENT ON COLUMN public.documents.storage_provider IS
+  'Where the bytes are: r2, supabase, or another service. NULL on a row that predates the split and still answers through file_url.';
+COMMENT ON COLUMN public.documents.storage_path IS
+  'The object key inside the bucket. With provider and bucket, this is everything a storage service needs to sign, fetch or delete it — no URL parsing.';
+COMMENT ON COLUMN public.documents.subject_type IS
+  'What the file is ABOUT when it is not about a person: an invoice, an order, a product. person_id stays a first-class column because the LGPD question is asked about people.';
+
+-- N14: a public base table carrying tenant_id has RLS on and forced, no
+-- exceptions. The scaffold in §3 adds the template policies; it does not turn
+-- RLS on for a table it is meeting for the first time, and a pool without
+-- plugin-forms meets this table here.
+ALTER TABLE public.documents ENABLE ROW LEVEL SECURITY;
+ALTER TABLE public.documents FORCE ROW LEVEL SECURITY;
+
+CREATE INDEX IF NOT EXISTS documents_person ON public.documents (tenant_id, person_id) WHERE person_id IS NOT NULL;
+CREATE INDEX IF NOT EXISTS documents_subject ON public.documents (tenant_id, subject_type, subject_id) WHERE subject_id IS NOT NULL;
+
+-- ─────────────────────────────────────────────────────────────────────────
+-- §2  Its species registry, in the shape 147 gave every archetype
+-- ─────────────────────────────────────────────────────────────────────────
+
+CREATE TABLE IF NOT EXISTS public.document_kinds (
+  kind        text PRIMARY KEY,
+  plugin      text NOT NULL,
+  description text,
+  statuses    text[],
+  transitions jsonb,
+  status      text NOT NULL DEFAULT 'declared',
+  created_at  timestamptz NOT NULL DEFAULT now(),
+  updated_at  timestamptz NOT NULL DEFAULT now(),
+  CONSTRAINT document_kinds_format CHECK (kind ~ '^[a-z][a-z0-9_]*$'),
+  CONSTRAINT document_kinds_status CHECK (status IN ('declared', 'adopted'))
+);
+
+COMMENT ON TABLE public.document_kinds IS
+  'The species registry of the Arquivo archetype (152): invoice attachment, record photo, form file — each declared by the plugin that owns it.';
+
+ALTER TABLE public.document_kinds ENABLE ROW LEVEL SECURITY;
+DROP POLICY IF EXISTS document_kinds_select ON public.document_kinds;
+CREATE POLICY document_kinds_select ON public.document_kinds
+  FOR SELECT TO anon, authenticated, service_role USING (true);
+GRANT SELECT ON public.document_kinds TO anon, authenticated, service_role;
+GRANT ALL ON public.document_kinds TO service_role;
+REVOKE INSERT, UPDATE, DELETE ON public.document_kinds FROM anon, authenticated;
+
+DROP TRIGGER IF EXISTS document_kinds_updated_at ON public.document_kinds;
+CREATE TRIGGER document_kinds_updated_at BEFORE UPDATE ON public.document_kinds
+  FOR EACH ROW EXECUTE FUNCTION public.handle_updated_at();
+
+-- 147's dispatcher learns the archetype that did not exist when it was written.
+CREATE OR REPLACE FUNCTION public.kind_registry_table(p_archetype text)
+RETURNS text
+LANGUAGE sql IMMUTABLE PARALLEL SAFE
+AS $$
+  SELECT CASE p_archetype
+    WHEN 'order'       THEN 'order_kinds'
+    WHEN 'person_role' THEN 'person_role_kinds'
+    WHEN 'person'      THEN 'person_kinds'
+    WHEN 'category'    THEN 'category_kinds'
+    WHEN 'appointment' THEN 'appointment_kinds'
+    WHEN 'schedule'    THEN 'schedule_kinds'
+    WHEN 'document'    THEN 'document_kinds'
+  END
+$$;
+
+-- What the base itself files. A plugin's own species is declared in that
+-- plugin's migration.
+SELECT public.register_kind('document', d.kind, 'base', NULL, NULL, d.note)
+FROM (VALUES
+  ('attachment', 'A file attached to something, with no more specific meaning'),
+  ('image',      'A picture'),
+  ('contract',   'A document with a signature and a consequence')
+) AS d(kind, note);
+
+SELECT public.adopt_existing_kinds('document', 'documents', 'kind');
+
+DO $$
+BEGIN
+  IF NOT EXISTS (SELECT 1 FROM pg_constraint WHERE conname = 'documents_kind_registered') THEN
+    ALTER TABLE public.documents
+      ADD CONSTRAINT documents_kind_registered FOREIGN KEY (kind) REFERENCES public.document_kinds(kind);
+  END IF;
+END $$;
+
+-- The census speaks for seven archetypes now.
+CREATE OR REPLACE VIEW public.v_archetype_kinds
+WITH (security_invoker = true) AS
+  SELECT 'order'::text AS archetype, kind, plugin, description, statuses, transitions, status FROM public.order_kinds
+  UNION ALL SELECT 'person_role', kind, plugin, description, statuses, transitions, status FROM public.person_role_kinds
+  UNION ALL SELECT 'person',      kind, plugin, description, statuses, transitions, status FROM public.person_kinds
+  UNION ALL SELECT 'category',    kind, plugin, description, statuses, transitions, status FROM public.category_kinds
+  UNION ALL SELECT 'appointment', kind, plugin, description, statuses, transitions, status FROM public.appointment_kinds
+  UNION ALL SELECT 'schedule',    kind, plugin, description, statuses, transitions, status FROM public.schedule_kinds
+  UNION ALL SELECT 'document',    kind, plugin, description, statuses, transitions, status FROM public.document_kinds;
+
+GRANT SELECT ON public.v_archetype_kinds TO anon, authenticated, service_role;
+
+-- ─────────────────────────────────────────────────────────────────────────
+-- §3  One rule for who may see a file
+--
+-- The scaffold is the platform's single authorization template — the same one
+-- every business table went through in the Fase 0 sweep. Putting documents
+-- under it is what makes "who may see this file" one rule rather than N, and
+-- what makes that rule the same one that governs everything else.
+-- ─────────────────────────────────────────────────────────────────────────
+
+DO $$
+BEGIN
+  IF to_regproc('app.scaffold_table(text,text,text,boolean,text)') IS NULL THEN
+    RETURN;
+  END IF;
+  IF NOT EXISTS (SELECT 1 FROM app.scaffold_registry WHERE table_schema = 'public' AND table_name = 'documents') THEN
+    PERFORM app.scaffold_table('public.documents', 'core.document', 'core', true, 'shadow');
+  END IF;
+END $$;
+
+-- ─────────────────────────────────────────────────────────────────────────
+-- §4  The LGPD question, answered in one place
+-- ─────────────────────────────────────────────────────────────────────────
+
+CREATE OR REPLACE VIEW public.v_person_files
+WITH (security_invoker = true) AS
+SELECT d.id, d.tenant_id, d.person_id, d.kind, d.title, d.file_name, d.mime_type, d.file_size,
+       d.storage_provider, d.storage_bucket, d.storage_path, d.created_at
+  FROM public.documents d
+ WHERE d.person_id IS NOT NULL
+   AND d.is_active;
+
+COMMENT ON VIEW public.v_person_files IS
+  'Every file the platform holds about a Person (152, ADR 0020). One query answers the LGPD request — which is the reason the register is in the base rather than spread across the plugins that produced the files.';
+
+GRANT SELECT ON public.v_person_files TO authenticated, service_role;
+
+CREATE OR REPLACE FUNCTION public.person_storage_usage(p_person uuid)
+RETURNS jsonb
+LANGUAGE sql STABLE SECURITY DEFINER SET search_path = ''
+AS $$
+  SELECT jsonb_build_object(
+    'person_id', p_person,
+    'files', count(*),
+    'bytes', coalesce(sum(d.file_size), 0)
+  )
+  FROM public.documents d
+  WHERE d.person_id = p_person
+    AND d.tenant_id = app.current_tenant_id()
+$$;
+
+COMMENT ON FUNCTION public.person_storage_usage(uuid) IS
+  'How many files and how many bytes the platform holds about a Person (152). A direct sum, because there is one register.';
+
+GRANT EXECUTE ON FUNCTION public.person_storage_usage(uuid) TO authenticated, service_role;

package/migrations/153_a_plugin_calls_a_service_through_one_door.sql

@@ -0,0 +1,199 @@
+-- ============================================================================
+-- 153_a_plugin_calls_a_service_through_one_door.sql — the credential is the
+-- cluster's, the contract decides, the plugin sees neither (#278, ADR 0018).
+--
+-- The round-3 decision put the valuable half of an open plugin in a SERVICE: the
+-- agenda ships open with the button, and the intelligence that suggests where to
+-- fit an appointment is an API we host. That created a question nobody had
+-- answered — who carries the credential, and who decides whether this tenant may
+-- call at all.
+--
+-- The answer that was chosen: THE CLUSTER SPEAKS FOR THE PLUGIN. The plugin
+-- calls a name; the call leaves from the server with the cluster's credential;
+-- the service reads the tenant's contract and decides. Three things fall out of
+-- that, and they are why it was chosen over the alternatives:
+--
+--   · the plugin never holds a secret, so an open-source plugin can call a
+--     closed service without shipping anything worth stealing
+--   · the customer configures nothing to use what they already bought — the
+--     "paste your API key" flow is for someone else's API, not ours
+--   · it works with no browser present, which the event consumer (#277) needs:
+--     the 2am reaction has no session to borrow
+--
+-- WHAT LIVES HERE and what does not. This file is the REGISTRY and the
+-- ENTITLEMENT CHECK — which services exist, what each one costs in permission
+-- terms, whether this tenant may call it, and the record of every call. The HTTP
+-- leg is not in the database: an edge function reads this to decide and then
+-- makes the request. A migration that opened a socket would be the wrong kind of
+-- clever.
+--
+-- DEGRADING. Every service must have a manual path, or say plainly that it has
+-- none. `manual_fallback` is that declaration, and it is NOT NULL — a service
+-- that cannot answer "what happens when I am down" has not been specified.
+--
+-- Idempotent and replay-safe.
+-- ============================================================================
+
+-- ─────────────────────────────────────────────────────────────────────────
+-- §1  The registry of services
+-- ─────────────────────────────────────────────────────────────────────────
+
+CREATE TABLE IF NOT EXISTS app.services (
+  name             text PRIMARY KEY CHECK (name ~ '^[a-z][a-z0-9_.]*$'),
+  plugin           text NOT NULL,
+  description      text,
+  -- What a caller must hold to reach it. NULL means any member of the tenant.
+  permission       text,
+  -- The entitlement that must be on for this tenant. NULL means "included".
+  entitlement      text,
+  -- What the user can still do when the service is unreachable. Required: a
+  -- service with no answer here has not been thought through.
+  manual_fallback  text NOT NULL,
+  timeout_ms       integer NOT NULL DEFAULT 8000 CHECK (timeout_ms BETWEEN 100 AND 60000),
+  is_active        boolean NOT NULL DEFAULT true,
+  created_at       timestamptz NOT NULL DEFAULT now(),
+  updated_at       timestamptz NOT NULL DEFAULT now()
+);
+
+COMMENT ON TABLE app.services IS
+  'Which services exist and what it takes to call one (153, ADR 0018). The plugin calls a NAME; the cluster carries the credential; this table is what says whether the call is allowed at all.';
+COMMENT ON COLUMN app.services.manual_fallback IS
+  'What the user can still do with the service unreachable. NOT NULL on purpose: "the plugin must work without it" is a rule, and a rule with no answer per service is a slogan.';
+
+ALTER TABLE app.services ENABLE ROW LEVEL SECURITY;
+DROP POLICY IF EXISTS services_read ON app.services;
+CREATE POLICY services_read ON app.services FOR SELECT TO authenticated USING (true);
+GRANT SELECT ON app.services TO authenticated;
+GRANT ALL ON app.services TO service_role;
+
+DROP TRIGGER IF EXISTS services_updated_at ON app.services;
+CREATE TRIGGER services_updated_at BEFORE UPDATE ON app.services
+  FOR EACH ROW EXECUTE FUNCTION public.handle_updated_at();
+
+CREATE OR REPLACE FUNCTION public.register_service(
+  p_name            text,
+  p_plugin          text,
+  p_manual_fallback text,
+  p_permission      text DEFAULT NULL,
+  p_entitlement     text DEFAULT NULL,
+  p_description     text DEFAULT NULL,
+  p_timeout_ms      integer DEFAULT 8000
+) RETURNS void
+LANGUAGE plpgsql SECURITY DEFINER SET search_path = ''
+AS $$
+BEGIN
+  IF coalesce(btrim(p_manual_fallback), '') = '' THEN
+    RAISE EXCEPTION 'register_service: % must declare what works without it', p_name
+      USING ERRCODE = '22023',
+            HINT = 'If there is genuinely no manual path, say so — "none: the feature does not exist offline" is a valid answer and a visible one.';
+  END IF;
+  INSERT INTO app.services (name, plugin, description, permission, entitlement, manual_fallback, timeout_ms)
+  VALUES (p_name, p_plugin, p_description, p_permission, p_entitlement, p_manual_fallback, p_timeout_ms)
+  ON CONFLICT (name) DO UPDATE
+    SET plugin = EXCLUDED.plugin,
+        description = coalesce(EXCLUDED.description, app.services.description),
+        permission = EXCLUDED.permission,
+        entitlement = EXCLUDED.entitlement,
+        manual_fallback = EXCLUDED.manual_fallback,
+        timeout_ms = EXCLUDED.timeout_ms,
+        is_active = true;
+END $$;
+
+REVOKE ALL ON FUNCTION public.register_service(text, text, text, text, text, text, integer) FROM public, anon, authenticated;
+GRANT EXECUTE ON FUNCTION public.register_service(text, text, text, text, text, text, integer) TO service_role;
+
+-- ─────────────────────────────────────────────────────────────────────────
+-- §2  May this call be made?
+--
+-- One answer, given before the request leaves, so a refusal costs nothing and
+-- reads the same everywhere: not the network's job, not each plugin's job.
+-- ─────────────────────────────────────────────────────────────────────────
+
+CREATE OR REPLACE FUNCTION public.service_authorize(p_name text)
+RETURNS jsonb
+LANGUAGE plpgsql STABLE SECURITY DEFINER SET search_path = ''
+AS $$
+DECLARE
+  v_service app.services%ROWTYPE;
+  v_tenant  uuid := app.current_tenant_id();
+BEGIN
+  SELECT * INTO v_service FROM app.services WHERE name = p_name;
+
+  IF NOT FOUND OR NOT v_service.is_active THEN
+    RETURN jsonb_build_object('allowed', false, 'reason', 'unknown_service');
+  END IF;
+  IF v_tenant IS NULL THEN
+    RETURN jsonb_build_object('allowed', false, 'reason', 'no_tenant');
+  END IF;
+  IF v_service.permission IS NOT NULL AND NOT app.has_permission(v_service.permission) THEN
+    RETURN jsonb_build_object('allowed', false, 'reason', 'forbidden',
+                              'permission', v_service.permission,
+                              'manual_fallback', v_service.manual_fallback);
+  END IF;
+  IF v_service.entitlement IS NOT NULL AND NOT public.tenant_plugin_active(v_service.plugin, v_service.entitlement) THEN
+    -- Not an error: an upsell. The caller shows the button and what it costs,
+    -- rather than a failure the user cannot act on.
+    RETURN jsonb_build_object('allowed', false, 'reason', 'not_contracted',
+                              'entitlement', v_service.entitlement,
+                              'plugin', v_service.plugin,
+                              'manual_fallback', v_service.manual_fallback);
+  END IF;
+
+  RETURN jsonb_build_object('allowed', true, 'service', v_service.name, 'tenant_id', v_tenant,
+                            'timeout_ms', v_service.timeout_ms,
+                            'manual_fallback', v_service.manual_fallback);
+END $$;
+
+COMMENT ON FUNCTION public.service_authorize(text) IS
+  'Whether this caller, in this tenant, may call this service (153). Answered before the request leaves, so a refusal costs no network and reads the same everywhere. `not_contracted` carries the entitlement so the caller can offer the upgrade instead of showing a dead button.';
+
+GRANT EXECUTE ON FUNCTION public.service_authorize(text) TO authenticated, service_role;
+
+-- ─────────────────────────────────────────────────────────────────────────
+-- §3  What was called, and what happened
+--
+-- Not an audit trail for its own sake: this is what answers "the button did
+-- nothing" without asking the user to reproduce it, and what a quota is
+-- eventually counted from.
+-- ─────────────────────────────────────────────────────────────────────────
+
+CREATE TABLE IF NOT EXISTS app.service_calls (
+  id          uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+  tenant_id   uuid NOT NULL REFERENCES public.tenants(id) ON DELETE CASCADE,
+  service     text NOT NULL,
+  caller      uuid,
+  status      text NOT NULL CHECK (status IN ('allowed', 'refused', 'ok', 'failed', 'timeout')),
+  reason      text,
+  duration_ms integer,
+  created_at  timestamptz NOT NULL DEFAULT now()
+);
+
+COMMENT ON TABLE app.service_calls IS
+  'Every service call and what became of it (153). "The button did nothing" is answered here rather than by asking the user to do it again.';
+
+CREATE INDEX IF NOT EXISTS service_calls_tenant_time ON app.service_calls (tenant_id, created_at DESC);
+
+ALTER TABLE app.service_calls ENABLE ROW LEVEL SECURITY;
+DROP POLICY IF EXISTS service_calls_read ON app.service_calls;
+CREATE POLICY service_calls_read ON app.service_calls
+  FOR SELECT TO authenticated
+  USING (tenant_id IN (SELECT public.user_tenant_ids()));
+GRANT SELECT ON app.service_calls TO authenticated;
+GRANT ALL ON app.service_calls TO service_role;
+
+CREATE OR REPLACE FUNCTION public.service_call_record(
+  p_service text, p_status text, p_reason text DEFAULT NULL, p_duration_ms integer DEFAULT NULL
+) RETURNS uuid
+LANGUAGE plpgsql SECURITY DEFINER SET search_path = ''
+AS $$
+DECLARE
+  v_id uuid;
+BEGIN
+  INSERT INTO app.service_calls (tenant_id, service, caller, status, reason, duration_ms)
+  VALUES (app.current_tenant_id(), p_service, auth.uid(), p_status, p_reason, p_duration_ms)
+  RETURNING id INTO v_id;
+  RETURN v_id;
+END $$;
+
+REVOKE ALL ON FUNCTION public.service_call_record(text, text, text, integer) FROM public, anon;
+GRANT EXECUTE ON FUNCTION public.service_call_record(text, text, text, integer) TO authenticated, service_role;