@pgpm/metaschema-modules 0.21.1 → 0.22.0

package/README.md

@@ -1,4 +1,4 @@
-# @pgpm/metaschema-modules
+# @pgpm/db-meta-modules
 
 <p align="center" width="100%">
   <img height="250" src="https://raw.githubusercontent.com/constructive-io/constructive/refs/heads/main/assets/outline-logo.svg" />
@@ -9,14 +9,14 @@
     <img height="20" src="https://github.com/constructive-io/pgpm-modules/actions/workflows/ci.yml/badge.svg" />
   </a>
    <a href="https://github.com/constructive-io/pgpm-modules/blob/main/LICENSE"><img height="20" src="https://img.shields.io/badge/license-MIT-blue.svg"/></a>
-   <a href="https://www.npmjs.com/package/@pgpm/metaschema-modules"><img height="20" src="https://img.shields.io/github/package-json/v/constructive-io/pgpm-modules?filename=packages%2Fmetaschema-modules%2Fpackage.json"/></a>
+   <a href="https://www.npmjs.com/package/@pgpm/db-meta-modules"><img height="20" src="https://img.shields.io/github/package-json/v/constructive-io/pgpm-modules?filename=packages%2Fdb-meta-modules%2Fpackage.json"/></a>
 </p>
 
 Module metadata handling and dependency tracking.
 
 ## Overview
 
-`@pgpm/metaschema-modules` extends the `@pgpm/metaschema-schema` package with module-specific metadata tables. This package provides tables for tracking various pgpm modules including authentication, permissions, memberships, encrypted secrets, and more. It enables configuration and metadata storage for modular application features.
+`@pgpm/db-meta-modules` extends the `@pgpm/db-meta-schema` package with module-specific metadata tables. This package provides tables for tracking various pgpm modules including authentication, permissions, memberships, encrypted secrets, and more. It enables configuration and metadata storage for modular application features.
 
 ## Features
 
@@ -33,7 +33,7 @@ Module metadata handling and dependency tracking.
 If you have `pgpm` installed:
 
 ```bash
-pgpm install @pgpm/metaschema-modules
+pgpm install @pgpm/db-meta-modules
 pgpm deploy
 ```
 
@@ -56,7 +56,7 @@ eval "$(pgpm env)"
 
 ```bash
 # 1. Install the package
-pgpm install @pgpm/metaschema-modules
+pgpm install @pgpm/db-meta-modules
 
 # 2. Deploy locally
 pgpm deploy 
@@ -74,7 +74,7 @@ pgpm init
 
 # 3. Install a package
 cd packages/my-module
-pgpm install @pgpm/metaschema-modules
+pgpm install @pgpm/db-meta-modules
 
 # 4. Deploy everything
 pgpm deploy --createdb --database mydb1
@@ -108,7 +108,6 @@ The package provides metadata tables for the following modules:
 - **invites_module**: Invitation system configuration
 
 ### Other Modules
-- **field_module**: Custom field configurations
 - **default_ids_module**: Default ID generation settings
 - **limits_module**: Rate limiting and quota configurations
 - **rls_module**: Row-level security configurations
@@ -213,7 +212,7 @@ Use module tables as feature flags:
 
 ## Dependencies
 
-- `@pgpm/metaschema-schema`: Core metadata management
+- `@pgpm/db-meta-schema`: Core metadata management
 - `@pgpm/verify`: Verification utilities
 
 ## Testing

package/deploy/schemas/metaschema_modules_public/tables/billing_module/table.sql

@@ -0,0 +1,47 @@
+-- Deploy schemas/metaschema_modules_public/tables/billing_module/table to pg
+
+-- requires: schemas/metaschema_modules_public/schema
+
+BEGIN;
+
+CREATE TABLE metaschema_modules_public.billing_module (
+  id uuid PRIMARY KEY DEFAULT uuidv7(),
+  database_id uuid NOT NULL,
+
+  schema_id uuid NOT NULL DEFAULT uuid_nil(),
+  private_schema_id uuid NOT NULL DEFAULT uuid_nil(),
+
+  -- Meters table: defines what you track (quota, boolean, credit_pool)
+  meters_table_id uuid NOT NULL DEFAULT uuid_nil(),
+  meters_table_name text NOT NULL DEFAULT '',
+
+  -- Plan subscriptions table: assigns plans to entities with lifecycle
+  plan_subscriptions_table_id uuid NOT NULL DEFAULT uuid_nil(),
+  plan_subscriptions_table_name text NOT NULL DEFAULT '',
+
+  -- Ledger table: append-only event log
+  ledger_table_id uuid NOT NULL DEFAULT uuid_nil(),
+  ledger_table_name text NOT NULL DEFAULT '',
+
+  -- Balances SPRT: denormalized current state (RLS-exempt fast lookups)
+  balances_table_id uuid NOT NULL DEFAULT uuid_nil(),
+  balances_table_name text NOT NULL DEFAULT '',
+
+  -- Generated functions
+  record_usage_function text NOT NULL DEFAULT '',
+
+  prefix text NULL,
+
+  CONSTRAINT db_fkey FOREIGN KEY (database_id) REFERENCES metaschema_public.database (id) ON DELETE CASCADE,
+  CONSTRAINT schema_fkey FOREIGN KEY (schema_id) REFERENCES metaschema_public.schema (id) ON DELETE CASCADE,
+  CONSTRAINT private_schema_fkey FOREIGN KEY (private_schema_id) REFERENCES metaschema_public.schema (id) ON DELETE CASCADE,
+  CONSTRAINT meters_table_fkey FOREIGN KEY (meters_table_id) REFERENCES metaschema_public.table (id) ON DELETE CASCADE,
+  CONSTRAINT plan_subscriptions_table_fkey FOREIGN KEY (plan_subscriptions_table_id) REFERENCES metaschema_public.table (id) ON DELETE CASCADE,
+  CONSTRAINT ledger_table_fkey FOREIGN KEY (ledger_table_id) REFERENCES metaschema_public.table (id) ON DELETE CASCADE,
+  CONSTRAINT balances_table_fkey FOREIGN KEY (balances_table_id) REFERENCES metaschema_public.table (id) ON DELETE CASCADE,
+  CONSTRAINT billing_module_database_id_unique UNIQUE (database_id)
+);
+
+CREATE INDEX billing_module_database_id_idx ON metaschema_modules_public.billing_module ( database_id );
+
+COMMIT;

package/deploy/schemas/metaschema_modules_public/tables/billing_provider_module/table.sql

@@ -0,0 +1,61 @@
+-- Deploy schemas/metaschema_modules_public/tables/billing_provider_module/table to pg
+
+-- requires: schemas/metaschema_modules_public/schema
+
+BEGIN;
+
+CREATE TABLE metaschema_modules_public.billing_provider_module (
+  id uuid PRIMARY KEY DEFAULT uuidv7(),
+  database_id uuid NOT NULL,
+
+  schema_id uuid NOT NULL DEFAULT uuid_nil(),
+  private_schema_id uuid NOT NULL DEFAULT uuid_nil(),
+
+  -- Provider: which billing provider (stripe, paddle, lemon_squeezy, etc.)
+  provider text NOT NULL DEFAULT 'stripe',
+
+  -- Parameterized FK targets: pass in your own tables
+  -- For SaaS: plans, plan_pricing, plan_subscriptions
+  -- For e-commerce: products, product_variants, orders
+  products_table_id uuid NULL,
+  prices_table_id uuid NULL,
+  subscriptions_table_id uuid NULL,
+
+  -- Created mapping tables
+  billing_customers_table_id uuid NOT NULL DEFAULT uuid_nil(),
+  billing_customers_table_name text NOT NULL DEFAULT '',
+
+  billing_products_table_id uuid NOT NULL DEFAULT uuid_nil(),
+  billing_products_table_name text NOT NULL DEFAULT '',
+
+  billing_prices_table_id uuid NOT NULL DEFAULT uuid_nil(),
+  billing_prices_table_name text NOT NULL DEFAULT '',
+
+  billing_subscriptions_table_id uuid NOT NULL DEFAULT uuid_nil(),
+  billing_subscriptions_table_name text NOT NULL DEFAULT '',
+
+  billing_webhook_events_table_id uuid NOT NULL DEFAULT uuid_nil(),
+  billing_webhook_events_table_name text NOT NULL DEFAULT '',
+
+  -- Generated functions
+  process_billing_event_function text NOT NULL DEFAULT '',
+
+  prefix text NULL,
+
+  CONSTRAINT db_fkey FOREIGN KEY (database_id) REFERENCES metaschema_public.database (id) ON DELETE CASCADE,
+  CONSTRAINT schema_fkey FOREIGN KEY (schema_id) REFERENCES metaschema_public.schema (id) ON DELETE CASCADE,
+  CONSTRAINT private_schema_fkey FOREIGN KEY (private_schema_id) REFERENCES metaschema_public.schema (id) ON DELETE CASCADE,
+  CONSTRAINT billing_customers_table_fkey FOREIGN KEY (billing_customers_table_id) REFERENCES metaschema_public.table (id) ON DELETE CASCADE,
+  CONSTRAINT billing_products_table_fkey FOREIGN KEY (billing_products_table_id) REFERENCES metaschema_public.table (id) ON DELETE CASCADE,
+  CONSTRAINT billing_prices_table_fkey FOREIGN KEY (billing_prices_table_id) REFERENCES metaschema_public.table (id) ON DELETE CASCADE,
+  CONSTRAINT billing_subscriptions_table_fkey FOREIGN KEY (billing_subscriptions_table_id) REFERENCES metaschema_public.table (id) ON DELETE CASCADE,
+  CONSTRAINT billing_webhook_events_table_fkey FOREIGN KEY (billing_webhook_events_table_id) REFERENCES metaschema_public.table (id) ON DELETE CASCADE,
+  CONSTRAINT products_table_fkey FOREIGN KEY (products_table_id) REFERENCES metaschema_public.table (id) ON DELETE SET NULL,
+  CONSTRAINT prices_table_fkey FOREIGN KEY (prices_table_id) REFERENCES metaschema_public.table (id) ON DELETE SET NULL,
+  CONSTRAINT subscriptions_table_fkey FOREIGN KEY (subscriptions_table_id) REFERENCES metaschema_public.table (id) ON DELETE SET NULL,
+  CONSTRAINT billing_provider_module_database_id_unique UNIQUE (database_id)
+);
+
+CREATE INDEX billing_provider_module_database_id_idx ON metaschema_modules_public.billing_provider_module ( database_id );
+
+COMMIT;

package/deploy/schemas/metaschema_modules_public/tables/devices_module/table.sql

@@ -0,0 +1,36 @@
+-- Deploy schemas/metaschema_modules_public/tables/devices_module/table to pg
+
+-- requires: schemas/metaschema_modules_public/schema
+
+BEGIN;
+
+CREATE TABLE metaschema_modules_public.devices_module (
+    id uuid PRIMARY KEY DEFAULT uuidv7(),
+    database_id uuid NOT NULL,
+
+    --
+    schema_id uuid NOT NULL DEFAULT uuid_nil(),
+    user_devices_table_id uuid NOT NULL DEFAULT uuid_nil(),
+    device_settings_table_id uuid NOT NULL DEFAULT uuid_nil(),
+
+    user_devices_table text NOT NULL DEFAULT 'auth_user_devices',
+    device_settings_table text NOT NULL DEFAULT 'app_settings_device',
+    --
+
+    CONSTRAINT db_fkey FOREIGN KEY (database_id) REFERENCES metaschema_public.database (id) ON DELETE CASCADE,
+    CONSTRAINT schema_fkey FOREIGN KEY (schema_id) REFERENCES metaschema_public.schema (id) ON DELETE CASCADE,
+    CONSTRAINT user_devices_table_fkey FOREIGN KEY (user_devices_table_id) REFERENCES metaschema_public.table (id) ON DELETE CASCADE,
+    CONSTRAINT device_settings_table_fkey FOREIGN KEY (device_settings_table_id) REFERENCES metaschema_public.table (id) ON DELETE CASCADE,
+
+    --
+    CONSTRAINT devices_module_database_id_uniq UNIQUE(database_id)
+);
+
+CREATE INDEX devices_module_database_id_idx ON metaschema_modules_public.devices_module ( database_id );
+
+COMMENT ON CONSTRAINT user_devices_table_fkey
+     ON metaschema_modules_public.devices_module IS E'@fieldName userDevicesTableByUserDevicesTableId';
+COMMENT ON CONSTRAINT device_settings_table_fkey
+     ON metaschema_modules_public.devices_module IS E'@fieldName deviceSettingsTableByDeviceSettingsTableId';
+
+COMMIT;

package/deploy/schemas/metaschema_modules_public/tables/entity_type_provision/table.sql

@@ -0,0 +1,332 @@
+-- Deploy schemas/metaschema_modules_public/tables/entity_type_provision/table to pg
+
+-- requires: schemas/metaschema_modules_public/schema
+
+BEGIN;
+
+CREATE TABLE metaschema_modules_public.entity_type_provision (
+    id uuid PRIMARY KEY DEFAULT uuidv7(),
+
+    database_id uuid NOT NULL,
+
+    -- =========================================================================
+    -- Identity: what this membership type is called
+    -- =========================================================================
+
+    name text NOT NULL,
+
+    prefix text NOT NULL,
+
+    description text NOT NULL DEFAULT '',
+
+    -- =========================================================================
+    -- Parentage: which entity type is the parent (resolved by trigger)
+    -- =========================================================================
+
+    parent_entity text NOT NULL DEFAULT 'org',
+
+    -- =========================================================================
+    -- Entity table name override
+    -- =========================================================================
+
+    table_name text DEFAULT NULL,
+
+    -- =========================================================================
+    -- Visibility: can parent members see child entities?
+    -- =========================================================================
+
+    is_visible boolean NOT NULL DEFAULT true,
+
+    -- =========================================================================
+    -- Optional modules
+    -- =========================================================================
+
+    has_limits boolean NOT NULL DEFAULT false,
+
+    has_profiles boolean NOT NULL DEFAULT false,
+
+    has_levels boolean NOT NULL DEFAULT false,
+
+    has_storage boolean NOT NULL DEFAULT false,
+
+    has_invites boolean NOT NULL DEFAULT false,
+
+    -- =========================================================================
+    -- Storage configuration: module-level overrides + initial bucket defs.
+    -- Only used when has_storage = true. NULL = use defaults.
+    -- =========================================================================
+
+    storage_config jsonb DEFAULT NULL,
+
+    -- =========================================================================
+    -- Escape hatch: skip default entity table RLS policies
+    -- =========================================================================
+
+    skip_entity_policies boolean NOT NULL DEFAULT false,
+
+    -- =========================================================================
+    -- Table provisioning override: single jsonb object describing the full
+    -- security setup to apply to the entity table, using the same vocabulary
+    -- as metaschema_modules_public.provision_table() and blueprint tables[]
+    -- entries (policies[], nodes[], fields[], grants[], use_rls).
+    --
+    -- Semantics:
+    --   - NULL (default)        -> apply the 5 default entity-table policies
+    --                              (gated by is_visible / skip_entity_policies)
+    --   - non-NULL object       -> fan table_provision.policies[] into N
+    --                              secure_table_provision rows; the 5 defaults
+    --                              are implicitly skipped, and is_visible is
+    --                              a no-op on this path.
+    -- =========================================================================
+
+    table_provision jsonb DEFAULT NULL,
+
+    -- =========================================================================
+    -- Output columns (populated by the trigger, not set by callers)
+    -- =========================================================================
+
+    out_membership_type int DEFAULT NULL,
+
+    out_entity_table_id uuid DEFAULT NULL,
+
+    out_entity_table_name text DEFAULT NULL,
+
+    out_installed_modules text[] DEFAULT NULL,
+
+    out_storage_module_id uuid DEFAULT NULL,
+
+    out_buckets_table_id uuid DEFAULT NULL,
+
+    out_files_table_id uuid DEFAULT NULL,
+
+    out_path_shares_table_id uuid DEFAULT NULL,
+
+    out_invites_module_id uuid DEFAULT NULL,
+
+    -- =========================================================================
+    -- Constraints
+    -- =========================================================================
+
+    CONSTRAINT entity_type_provision_unique_prefix UNIQUE (database_id, prefix),
+    CONSTRAINT entity_type_provision_db_fkey FOREIGN KEY (database_id)
+        REFERENCES metaschema_public.database (id) ON DELETE CASCADE
+);
+
+-- =============================================================================
+-- Table-level comment
+-- =============================================================================
+
+COMMENT ON TABLE metaschema_modules_public.entity_type_provision IS
+    'Provisions a new membership entity type. Each INSERT creates an entity table, registers a membership type,
+     and installs the required modules (permissions, memberships, limits) plus optional modules (profiles, levels, invites).
+     Uses provision_membership_table() internally. Graceful: duplicate (database_id, prefix) pairs are silently skipped
+     via the unique constraint (use INSERT ... ON CONFLICT DO NOTHING).
+     Policy behavior: by default the five entity-table RLS policies are applied (gated by is_visible).
+     Set table_provision to a single jsonb object (using the same shape as provision_table() /
+     blueprint tables[] entries) to replace the defaults with your own; set skip_entity_policies=true
+     as an escape hatch to apply zero policies.';
+
+-- =============================================================================
+-- Identity columns
+-- =============================================================================
+
+COMMENT ON COLUMN metaschema_modules_public.entity_type_provision.id IS
+    'Unique identifier for this provision row.';
+
+COMMENT ON COLUMN metaschema_modules_public.entity_type_provision.database_id IS
+    'The database to provision this entity type in. Required.';
+
+COMMENT ON COLUMN metaschema_modules_public.entity_type_provision.name IS
+    'Human-readable name for this entity type, e.g. ''Data Room'', ''Team Channel''. Required.
+     Stored in the entity_types registry table.';
+
+COMMENT ON COLUMN metaschema_modules_public.entity_type_provision.prefix IS
+    'SQL prefix used for table and module naming, e.g. ''data_room'', ''team_channel''. Required.
+     Drives entity table name (prefix || ''s'' by default), module labels (permissions_module:prefix),
+     and membership table names (prefix_memberships, prefix_members, etc.).
+     Must be unique per database — the (database_id, prefix) constraint ensures graceful ON CONFLICT DO NOTHING.';
+
+COMMENT ON COLUMN metaschema_modules_public.entity_type_provision.description IS
+    'Description of this entity type. Stored in the entity_types registry table. Defaults to empty string.';
+
+-- =============================================================================
+-- Parentage
+-- =============================================================================
+
+COMMENT ON COLUMN metaschema_modules_public.entity_type_provision.parent_entity IS
+    'Prefix of the parent entity type. The trigger resolves this to a membership_type integer
+     by looking up memberships_module WHERE prefix = parent_entity.
+     Defaults to ''org'' (the organization-level type). For nested types, set to the parent''s prefix
+     (e.g. ''data_room'' for a team_channel nested under data_room).
+     The parent type must already be provisioned before this INSERT.';
+
+-- =============================================================================
+-- Entity table name override
+-- =============================================================================
+
+COMMENT ON COLUMN metaschema_modules_public.entity_type_provision.table_name IS
+    'Override the entity table name. When NULL (default), the table name is derived as prefix || ''s''
+     (e.g. prefix ''data_room'' produces table ''data_rooms'').
+     Set this when the pluralization rule doesn''t apply (e.g. prefix ''staff'' should produce ''staff'' not ''staffs'').';
+
+-- =============================================================================
+-- Visibility
+-- =============================================================================
+
+COMMENT ON COLUMN metaschema_modules_public.entity_type_provision.is_visible IS
+    'Whether members of the parent entity can see child entities. Defaults to true.
+     When true: a SELECT policy allows parent members to list child entities (e.g. org members can see all data rooms).
+     When false: only direct members of the entity itself can see it (private entity mode).
+     Controls whether the parent_member SELECT policy is created on the entity table.
+     Only meaningful on the defaults path — ignored (no-op) when table_provision is non-NULL or
+     skip_entity_policies=true, since no default policies are being applied in those cases.';
+
+-- =============================================================================
+-- Optional modules
+-- =============================================================================
+
+COMMENT ON COLUMN metaschema_modules_public.entity_type_provision.has_limits IS
+    'Whether to apply limits_module security for this type. Defaults to false.
+     The limits_module table structure is always created (memberships_module requires it),
+     but when false, no RLS policies are applied to the limits tables.
+     Set to true if this entity type needs configurable resource limits per membership.';
+
+COMMENT ON COLUMN metaschema_modules_public.entity_type_provision.has_profiles IS
+    'Whether to provision profiles_module for this type. Defaults to false.
+     Profiles provide named permission roles (e.g. ''Editor'', ''Viewer'') with pre-configured permission bitmasks.
+     When true, creates profile tables and applies profiles security.';
+
+COMMENT ON COLUMN metaschema_modules_public.entity_type_provision.has_levels IS
+    'Whether to provision levels_module for this type. Defaults to false.
+     Levels provide gamification/achievement tracking for members.
+     When true, creates level steps, achievements, and level tables with security.';
+
+COMMENT ON COLUMN metaschema_modules_public.entity_type_provision.has_storage IS
+    'Whether to provision storage_module for this type. Defaults to false.
+     When true, creates {prefix}_buckets and {prefix}_files tables
+     with entity-scoped RLS (AuthzEntityMembership) using the entity''s membership_type.
+     Storage tables get owner_id FK to the entity table, so files are owned by the entity.';
+
+COMMENT ON COLUMN metaschema_modules_public.entity_type_provision.has_invites IS
+    'Whether to provision invites_module for this type. Defaults to false.
+     When true, the trigger inserts a row into invites_module which in turn
+     (via insert_invites_module BEFORE INSERT) creates {prefix}_invites and
+     {prefix}_claimed_invites tables plus the submit_{prefix}_invite_code() function.
+     Symmetric counterpart of has_storage. Re-provisioning is idempotent: the
+     UNIQUE (database_id, membership_type) constraint on invites_module combined with
+     ON CONFLICT DO NOTHING in the fan-out makes repeated INSERTs safe.';
+
+-- =============================================================================
+-- Escape hatch
+-- =============================================================================
+
+COMMENT ON COLUMN metaschema_modules_public.entity_type_provision.skip_entity_policies IS
+    'Escape hatch: when true, apply zero RLS policies to the entity table. Defaults to false.
+     Use this only when you want the entity table provisioned with zero policies (e.g. because you
+     plan to insert secure_table_provision rows yourself later). In most cases, prefer leaving this
+     false and either accepting the five defaults (table_provision=NULL) or overriding them via
+     table_provision.
+     Defaults (applied when table_provision IS NULL and skip_entity_policies=false):
+       - SELECT (parent_member): parent entity members can see child entities (only when is_visible=true)
+       - SELECT (self_member):   direct members of the entity can see it
+       - INSERT:                 create_entity permission on the parent entity
+       - UPDATE:                 admin_entity permission on the entity itself
+       - DELETE:                 owner of the entity can delete it';
+
+COMMENT ON COLUMN metaschema_modules_public.entity_type_provision.table_provision IS
+    'Single jsonb object describing the full security setup to apply to the entity table.
+     Uses the same vocabulary as metaschema_modules_public.provision_table() and blueprint tables[]
+     entries, so an entity table is configured the same way an ordinary blueprint table is.
+     Defaults to NULL; when non-NULL, the five default policies are implicitly replaced by
+     table_provision.policies[] (is_visible becomes a no-op on this path).
+     Recognized keys (all optional):
+       - use_rls          (boolean, default true)
+       - nodes            (jsonb array of {"$type","data"} Data* module entries)
+       - fields           (jsonb array of field objects: name,type,is_required,default,min,max,regexp,index)
+       - grants           (jsonb array of grant objects; each with roles[] and privileges[])
+       - policies         (jsonb array of policy objects; each with $type, privileges, data, name, role, permissive)
+     The trigger forwards all setup (nodes/fields/grants/policies) as a single secure_table_provision row
+     against the newly created entity table.
+     Example — override with two SELECT policies:
+       table_provision := jsonb_build_object(
+         ''policies'', jsonb_build_array(
+           jsonb_build_object(
+             ''$type'', ''AuthzEntityMembership'',
+             ''privileges'', jsonb_build_array(''select''),
+             ''data'', jsonb_build_object(''entity_field'', ''id'', ''membership_type'', 3),
+             ''name'', ''self_member''
+           ),
+           jsonb_build_object(
+             ''$type'', ''AuthzDirectOwner'',
+             ''privileges'', jsonb_build_array(''select'', ''update''),
+             ''data'', jsonb_build_object(''owner_field'', ''owner_id'')
+           )
+         )
+       )';
+
+-- =============================================================================
+-- Output columns
+-- =============================================================================
+
+COMMENT ON COLUMN metaschema_modules_public.entity_type_provision.out_membership_type IS
+    'Output: the auto-assigned integer membership type ID. Populated by the trigger after successful provisioning.
+     This is the ID used in entity_types, memberships_module, and all module tables.';
+
+COMMENT ON COLUMN metaschema_modules_public.entity_type_provision.out_entity_table_id IS
+    'Output: the UUID of the created entity table. Populated by the trigger.
+     Use this to reference the entity table in subsequent relation_provision or secure_table_provision rows.';
+
+COMMENT ON COLUMN metaschema_modules_public.entity_type_provision.out_entity_table_name IS
+    'Output: the name of the created entity table (e.g. ''data_rooms''). Populated by the trigger.';
+
+COMMENT ON COLUMN metaschema_modules_public.entity_type_provision.out_installed_modules IS
+    'Output: array of installed module labels (e.g. ARRAY[''permissions_module:data_room'', ''memberships_module:data_room'', ''invites_module:data_room'']).
+     Populated by the trigger. Useful for verifying which modules were provisioned.';
+
+COMMENT ON COLUMN metaschema_modules_public.entity_type_provision.storage_config IS
+    'Optional jsonb object for storage module configuration and initial bucket seeding.
+     Only used when has_storage = true; ignored otherwise. NULL = use defaults.
+     Recognized keys (all optional):
+       - upload_url_expiry_seconds    (integer) presigned PUT URL expiry override
+       - download_url_expiry_seconds  (integer) presigned GET URL expiry override
+       - default_max_file_size        (bigint)  global max file size in bytes for this scope
+       - allowed_origins              (text[])  default CORS origins for all buckets in this scope
+       - buckets                      (jsonb[]) array of initial bucket definitions to seed
+     Each bucket in the buckets array recognizes:
+       - name               (text, required) bucket name e.g. ''documents''
+       - description         (text)           human-readable description
+       - is_public           (boolean)        whether files are publicly readable (default false)
+       - allowed_mime_types  (text[])         whitelist of MIME types (null = any)
+       - max_file_size       (bigint)         max file size in bytes (null = use scope default)
+       - allowed_origins     (text[])         per-bucket CORS override
+       - provisions (jsonb object) optional: customize storage tables
+                                  with additional nodes, fields, grants, and policies.
+                                  Keyed by table role: "files", "buckets".
+                                  Each value uses the same shape as table_provision:
+                                  { nodes, fields, grants, use_rls, policies }. Fanned out
+                                  to secure_table_provision targeting the corresponding table.
+                                  When a key includes policies[], those REPLACE the default
+                                  storage policies for that table; tables without a key still
+                                  get defaults. Missing "data" on policy entries is auto-populated
+                                  with storage-specific defaults (same as table_provision).
+                                  Example: add SearchBm25 for full-text search on files:
+                                  {"provisions": {"files": {"nodes": [{"$type":
+                                  "SearchBm25", "data": {"source_fields": ["description"]}}]}}}
+     Example:
+       storage_config := ''{"buckets": [{"name": "documents", "is_public": false, "allowed_mime_types": ["application/pdf"]}], "provisions": {"files": {"nodes": [{"$type": "SearchBm25", "data": {"source_fields": ["description"]}}]}}}''::jsonb';
+
+COMMENT ON COLUMN metaschema_modules_public.entity_type_provision.out_storage_module_id IS
+    'Output: the UUID of the storage_module row created for this entity type. Populated by the trigger when has_storage=true.';
+
+COMMENT ON COLUMN metaschema_modules_public.entity_type_provision.out_buckets_table_id IS
+    'Output: the UUID of the generated buckets table (e.g. data_room_buckets). Populated by the trigger when has_storage=true.';
+
+COMMENT ON COLUMN metaschema_modules_public.entity_type_provision.out_files_table_id IS
+    'Output: the UUID of the generated files table (e.g. data_room_files). Populated by the trigger when has_storage=true.';
+
+COMMENT ON COLUMN metaschema_modules_public.entity_type_provision.out_invites_module_id IS
+    'Output: the UUID of the invites_module row created for this entity type. Populated by the trigger when has_invites=true.
+     NULL when has_invites=false, or when re-provisioning hits ON CONFLICT DO NOTHING
+     (i.e. the invites_module row was created in a previous run).';
+
+COMMIT;

package/deploy/schemas/metaschema_modules_public/tables/identity_providers_module/table.sql

@@ -0,0 +1,33 @@
+-- Deploy schemas/metaschema_modules_public/tables/identity_providers_module/table to pg
+
+-- requires: schemas/metaschema_modules_public/schema
+
+BEGIN;
+
+CREATE TABLE metaschema_modules_public.identity_providers_module (
+    id uuid PRIMARY KEY DEFAULT uuidv7(),
+    database_id uuid NOT NULL,
+
+    schema_id uuid NOT NULL DEFAULT uuid_nil(),
+    private_schema_id uuid NOT NULL DEFAULT uuid_nil(),
+
+    table_id uuid NOT NULL DEFAULT uuid_nil(),
+
+    table_name text NOT NULL DEFAULT 'identity_providers',
+
+    --
+    CONSTRAINT db_fkey FOREIGN KEY (database_id) REFERENCES metaschema_public.database (id) ON DELETE CASCADE,
+    CONSTRAINT table_fkey FOREIGN KEY (table_id) REFERENCES metaschema_public.table (id) ON DELETE CASCADE,
+    CONSTRAINT schema_fkey FOREIGN KEY (schema_id) REFERENCES metaschema_public.schema (id) ON DELETE CASCADE,
+    CONSTRAINT private_schema_fkey FOREIGN KEY (private_schema_id) REFERENCES metaschema_public.schema (id) ON DELETE CASCADE
+);
+
+CREATE INDEX identity_providers_module_database_id_idx ON metaschema_modules_public.identity_providers_module ( database_id );
+CREATE INDEX identity_providers_module_schema_id_idx ON metaschema_modules_public.identity_providers_module ( schema_id );
+CREATE INDEX identity_providers_module_private_schema_id_idx ON metaschema_modules_public.identity_providers_module ( private_schema_id );
+CREATE INDEX identity_providers_module_table_id_idx ON metaschema_modules_public.identity_providers_module ( table_id );
+
+COMMENT ON TABLE metaschema_modules_public.identity_providers_module IS 'Config row for the identity_providers_module, which provisions a per-database identity_providers config table holding OAuth2 / OIDC (and future SAML) provider definitions: protocol kind, endpoint URLs, encrypted client secret, scopes, audience validation, PKCE, and email-handling flags. Built-in providers (google, github, apple, ...) are seeded as is_built_in=true rows; custom providers use slugs of the form custom:<slug>.';
+COMMENT ON COLUMN metaschema_modules_public.identity_providers_module.private_schema_id IS 'Private schema that hosts SECURITY DEFINER admin helpers which write to identity_providers (create / update / enable / disable / rotate-secret / delete) and the per-app quota check.';
+
+COMMIT;

package/deploy/schemas/metaschema_modules_public/tables/invites_module/table.sql

@@ -41,4 +41,12 @@ CREATE TABLE metaschema_modules_public.invites_module (
 
 CREATE INDEX invites_module_database_id_idx ON metaschema_modules_public.invites_module ( database_id );
 
+-- Unique constraint on (database_id, membership_type) so the
+-- entity_type_provision fan-out can use ON CONFLICT DO NOTHING for idempotent
+-- re-provisioning. invites_module is always entity-scoped (membership_type
+-- is NOT NULL on this table), so no COALESCE-NULL trick is needed here,
+-- unlike storage_module which supports an app-level singleton row.
+CREATE UNIQUE INDEX invites_module_unique_scope
+    ON metaschema_modules_public.invites_module (database_id, membership_type);
+
 COMMIT;

package/deploy/schemas/metaschema_modules_public/tables/limits_module/table.sql

@@ -24,7 +24,35 @@ CREATE TABLE metaschema_modules_public.limits_module (
     limit_decrement_trigger text NOT NULL DEFAULT '',
     limit_update_trigger text NOT NULL DEFAULT '',
     limit_check_function text NOT NULL DEFAULT '',
-    
+
+    -- Credit grants ledger table
+    limit_credits_table_id uuid NULL,
+
+    -- Events audit trail table
+    events_table_id uuid NULL,
+
+    -- Credit codes table (app-level only, database-wide)
+    credit_codes_table_id uuid NULL,
+
+    -- Credit code items table (app-level only, database-wide)
+    credit_code_items_table_id uuid NULL,
+
+    -- Credit redemptions table (app-level only, database-wide)
+    credit_redemptions_table_id uuid NULL,
+
+    -- Aggregate entity limits (org-level caps, no actor_id)
+    aggregate_table_id uuid NULL,
+
+    -- Cap tables (static config limits, no metering)
+    limit_caps_table_id uuid NULL,
+    limit_caps_defaults_table_id uuid NULL,
+
+    -- Cap check trigger function (gates inserts behind cap/feature flag values)
+    cap_check_trigger text NOT NULL DEFAULT '',
+
+    -- Resolve cap function (COALESCE lookup: per-entity → default → 0)
+    resolve_cap_function text NOT NULL DEFAULT '',
+
     prefix text NULL,
 
     membership_type int NOT NULL,
@@ -41,7 +69,15 @@ CREATE TABLE metaschema_modules_public.limits_module (
     CONSTRAINT table_fkey FOREIGN KEY (table_id) REFERENCES metaschema_public.table (id) ON DELETE CASCADE,
     CONSTRAINT default_table_fkey FOREIGN KEY (default_table_id) REFERENCES metaschema_public.table (id) ON DELETE CASCADE,
     CONSTRAINT entity_table_fkey FOREIGN KEY (entity_table_id) REFERENCES metaschema_public.table (id) ON DELETE CASCADE,
-    CONSTRAINT actor_table_fkey FOREIGN KEY (actor_table_id) REFERENCES metaschema_public.table (id) ON DELETE CASCADE
+    CONSTRAINT actor_table_fkey FOREIGN KEY (actor_table_id) REFERENCES metaschema_public.table (id) ON DELETE CASCADE,
+    CONSTRAINT aggregate_table_fkey FOREIGN KEY (aggregate_table_id) REFERENCES metaschema_public.table (id) ON DELETE CASCADE,
+    CONSTRAINT limit_credits_table_fkey FOREIGN KEY (limit_credits_table_id) REFERENCES metaschema_public.table (id) ON DELETE CASCADE,
+    CONSTRAINT events_table_fkey FOREIGN KEY (events_table_id) REFERENCES metaschema_public.table (id) ON DELETE CASCADE,
+    CONSTRAINT credit_codes_table_fkey FOREIGN KEY (credit_codes_table_id) REFERENCES metaschema_public.table (id) ON DELETE CASCADE,
+    CONSTRAINT credit_code_items_table_fkey FOREIGN KEY (credit_code_items_table_id) REFERENCES metaschema_public.table (id) ON DELETE CASCADE,
+    CONSTRAINT credit_redemptions_table_fkey FOREIGN KEY (credit_redemptions_table_id) REFERENCES metaschema_public.table (id) ON DELETE CASCADE,
+    CONSTRAINT limit_caps_table_fkey FOREIGN KEY (limit_caps_table_id) REFERENCES metaschema_public.table (id) ON DELETE CASCADE,
+    CONSTRAINT limit_caps_defaults_table_fkey FOREIGN KEY (limit_caps_defaults_table_id) REFERENCES metaschema_public.table (id) ON DELETE CASCADE
 
 );