@pgpm/metaschema-modules 0.23.0 → 0.26.1

package/Makefile

@@ -1,5 +1,5 @@
 EXTENSION = metaschema-modules
-DATA = sql/metaschema-modules--0.15.5.sql
+DATA = sql/metaschema-modules--0.26.0.sql
 
 PG_CONFIG = pg_config
 PGXS := $(shell $(PG_CONFIG) --pgxs)

package/README.md

@@ -95,7 +95,7 @@ The package provides metadata tables for the following modules:
 - **permissions_module**: Permission system configuration
 - **memberships_module**: Membership management settings
 - **membership_types_module**: Membership type definitions
-- **levels_module**: User level configurations
+- **events_module**: User level configurations
 
 ### Security
 - **encrypted_secrets_module**: Encrypted secrets configuration

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

@@ -0,0 +1,77 @@
+-- Deploy schemas/metaschema_modules_public/tables/agent_module/table to pg
+
+-- requires: schemas/metaschema_modules_public/schema
+
+BEGIN;
+
+CREATE TABLE metaschema_modules_public.agent_module (
+  id uuid PRIMARY KEY DEFAULT uuidv7(),
+  database_id uuid NOT NULL,
+
+  -- Schema references (if uuid_nil, resolved from schema name or default)
+  schema_id uuid NOT NULL DEFAULT uuid_nil(),
+  private_schema_id uuid NOT NULL DEFAULT uuid_nil(),
+
+  -- Generated table IDs (populated by the generator)
+  thread_table_id uuid NOT NULL DEFAULT uuid_nil(),
+  message_table_id uuid NOT NULL DEFAULT uuid_nil(),
+  task_table_id uuid NOT NULL DEFAULT uuid_nil(),
+  prompts_table_id uuid NOT NULL DEFAULT uuid_nil(),
+  knowledge_table_id uuid DEFAULT NULL,
+
+  -- Table names (input to the generator)
+  thread_table_name text NOT NULL DEFAULT 'agent_thread',
+  message_table_name text NOT NULL DEFAULT 'agent_message',
+  task_table_name text NOT NULL DEFAULT 'agent_task',
+  prompts_table_name text NOT NULL DEFAULT 'agent_prompt',
+  knowledge_table_name text NOT NULL DEFAULT 'agent_knowledge',
+
+  -- Feature flags
+  has_knowledge boolean NOT NULL DEFAULT false,
+
+  -- API routing (get-or-create: if set, schema is added to this API; if NULL, no API is added)
+  api_name text DEFAULT 'agent',
+
+  -- Multi-tenant scope
+  membership_type int DEFAULT NULL,
+
+  -- Entity table for RLS (NULL for app-level, entity table for entity-scoped)
+  entity_table_id uuid NULL,
+
+  -- Configurable security policies (NULL = use defaults based on membership_type)
+  policies jsonb NULL,
+
+  -- Knowledge RAG config (dimensions, chunk_size, chunk_strategy, search_indexes, etc.)
+  -- NULL = use sensible defaults (768d, 1000 chars, paragraph, bm25)
+  knowledge_config jsonb NULL,
+
+  -- Custom RLS policies for knowledge table (provisions.knowledge.policies)
+  -- NULL = use defaults (AuthzEntityMembership or AuthzAppMembership)
+  knowledge_policies jsonb NULL,
+
+  -- Per-table provisions overrides from blueprint config.
+  -- Keys are table keys (thread, message, task, prompt, knowledge).
+  -- When a key is present, the module trigger skips default security for that table;
+  -- secure_table_provision applies the custom grants/policies instead.
+  provisions jsonb NULL,
+
+  -- Constraints
+  CONSTRAINT agent_module_db_fkey FOREIGN KEY (database_id) REFERENCES metaschema_public.database (id) ON DELETE CASCADE,
+  CONSTRAINT agent_module_schema_fkey FOREIGN KEY (schema_id) REFERENCES metaschema_public.schema (id) ON DELETE CASCADE,
+  CONSTRAINT agent_module_private_schema_fkey FOREIGN KEY (private_schema_id) REFERENCES metaschema_public.schema (id) ON DELETE CASCADE,
+  CONSTRAINT agent_module_thread_table_fkey FOREIGN KEY (thread_table_id) REFERENCES metaschema_public.table (id) ON DELETE CASCADE,
+  CONSTRAINT agent_module_message_table_fkey FOREIGN KEY (message_table_id) REFERENCES metaschema_public.table (id) ON DELETE CASCADE,
+  CONSTRAINT agent_module_task_table_fkey FOREIGN KEY (task_table_id) REFERENCES metaschema_public.table (id) ON DELETE CASCADE,
+  CONSTRAINT agent_module_prompts_table_fkey FOREIGN KEY (prompts_table_id) REFERENCES metaschema_public.table (id) ON DELETE CASCADE,
+  CONSTRAINT agent_module_knowledge_table_fkey FOREIGN KEY (knowledge_table_id) REFERENCES metaschema_public.table (id) ON DELETE CASCADE,
+  CONSTRAINT agent_module_entity_table_fkey FOREIGN KEY (entity_table_id) REFERENCES metaschema_public.table (id) ON DELETE CASCADE
+);
+
+CREATE INDEX agent_module_database_id_idx ON metaschema_modules_public.agent_module ( database_id );
+
+-- Unique constraint on (database_id, membership_type) using COALESCE to handle NULLs.
+-- NULL membership_type = app-level, non-NULL = entity-scoped.
+-- Only one agent module per scope.
+CREATE UNIQUE INDEX agent_module_unique_scope ON metaschema_modules_public.agent_module ( database_id, COALESCE(membership_type, -1) );
+
+COMMIT;

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

@@ -27,6 +27,14 @@ CREATE TABLE metaschema_modules_public.billing_module (
   balances_table_id uuid NOT NULL DEFAULT uuid_nil(),
   balances_table_name text NOT NULL DEFAULT '',
 
+  -- Meter credits table: append-only credit grants for billing meters
+  meter_credits_table_id uuid NOT NULL DEFAULT uuid_nil(),
+  meter_credits_table_name text NOT NULL DEFAULT '',
+
+  -- Meter sources table: maps billing meters to typed daily summary table columns
+  meter_sources_table_id uuid NOT NULL DEFAULT uuid_nil(),
+  meter_sources_table_name text NOT NULL DEFAULT '',
+
   -- Generated functions
   record_usage_function text NOT NULL DEFAULT '',
 
@@ -39,6 +47,8 @@ CREATE TABLE metaschema_modules_public.billing_module (
   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 meter_credits_table_fkey FOREIGN KEY (meter_credits_table_id) REFERENCES metaschema_public.table (id) ON DELETE CASCADE,
+  CONSTRAINT meter_sources_table_fkey FOREIGN KEY (meter_sources_table_id) REFERENCES metaschema_public.table (id) ON DELETE CASCADE,
   CONSTRAINT billing_module_database_id_unique UNIQUE (database_id)
 );
 

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

@@ -0,0 +1,44 @@
+-- Deploy schemas/metaschema_modules_public/tables/compute_log_module/table to pg
+
+-- requires: schemas/metaschema_modules_public/schema
+
+BEGIN;
+
+CREATE TABLE metaschema_modules_public.compute_log_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(),
+
+  -- Compute log table (partitioned by completed_at)
+  compute_log_table_id uuid NOT NULL DEFAULT uuid_nil(),
+  compute_log_table_name text NOT NULL DEFAULT '',
+
+  -- Pre-aggregated daily rollup table
+  usage_daily_table_id uuid NOT NULL DEFAULT uuid_nil(),
+  usage_daily_table_name text NOT NULL DEFAULT '',
+
+  -- Partition lifecycle configuration
+  "interval" text NOT NULL DEFAULT '1 month',
+  retention text NOT NULL DEFAULT '12 months',
+  premake int NOT NULL DEFAULT 2,
+
+  -- Scope configuration: 'app' = per-app usage (actor_id RLS), 'platform' = tenant metering (database_id RLS)
+  scope text NOT NULL DEFAULT 'app',
+  actor_fk_table_id uuid NULL,
+  entity_fk_table_id uuid NULL,
+
+  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 compute_log_table_fkey FOREIGN KEY (compute_log_table_id) REFERENCES metaschema_public.table (id) ON DELETE CASCADE,
+  CONSTRAINT usage_daily_table_fkey FOREIGN KEY (usage_daily_table_id) REFERENCES metaschema_public.table (id) ON DELETE CASCADE,
+  CONSTRAINT compute_log_module_database_id_prefix_unique UNIQUE NULLS NOT DISTINCT (database_id, prefix)
+);
+
+CREATE INDEX compute_log_module_database_id_idx ON metaschema_modules_public.compute_log_module ( database_id );
+
+COMMIT;

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

@@ -0,0 +1,28 @@
+-- Deploy schemas/metaschema_modules_public/tables/config_secrets_org_module/table to pg
+
+-- requires: schemas/metaschema_modules_public/schema
+
+BEGIN;
+
+CREATE TABLE metaschema_modules_public.config_secrets_org_module (
+    id uuid PRIMARY KEY DEFAULT uuidv7(),
+    database_id uuid NOT NULL,
+
+    --
+    schema_id uuid NOT NULL DEFAULT uuid_nil(),
+    table_id uuid NOT NULL DEFAULT uuid_nil(),
+    table_name text NOT NULL DEFAULT 'org_secrets',
+    --
+
+    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 table_fkey FOREIGN KEY (table_id) REFERENCES metaschema_public.table (id) ON DELETE CASCADE
+);
+
+CREATE INDEX config_secrets_org_module_database_id_idx ON metaschema_modules_public.config_secrets_org_module ( database_id );
+CREATE INDEX config_secrets_org_module_schema_id_idx ON metaschema_modules_public.config_secrets_org_module ( schema_id );
+CREATE INDEX config_secrets_org_module_table_id_idx ON metaschema_modules_public.config_secrets_org_module ( table_id );
+
+COMMENT ON TABLE metaschema_modules_public.config_secrets_org_module IS 'Config row for the config_secrets_org_module, which provisions an organization-scoped encrypted key-value secrets store with manage_secrets permission and entity-membership RLS.';
+
+COMMIT;

package/deploy/schemas/metaschema_modules_public/tables/{encrypted_secrets_module → config_secrets_user_module}/table.sql

@@ -1,17 +1,17 @@
--- Deploy schemas/metaschema_modules_public/tables/encrypted_secrets_module/table to pg
+-- Deploy schemas/metaschema_modules_public/tables/config_secrets_user_module/table to pg
 
 -- requires: schemas/metaschema_modules_public/schema
 
 BEGIN;
 
-CREATE TABLE metaschema_modules_public.encrypted_secrets_module (
+CREATE TABLE metaschema_modules_public.config_secrets_user_module (
     id uuid PRIMARY KEY DEFAULT uuidv7(),
     database_id uuid NOT NULL,
 
     --
     schema_id uuid NOT NULL DEFAULT uuid_nil(),
     table_id uuid NOT NULL DEFAULT uuid_nil(),
-    table_name text NOT NULL DEFAULT 'encrypted_secrets',
+    table_name text NOT NULL DEFAULT 'user_secrets',
     -- 
     
     CONSTRAINT db_fkey FOREIGN KEY (database_id) REFERENCES metaschema_public.database (id) ON DELETE CASCADE,
@@ -19,6 +19,6 @@ CREATE TABLE metaschema_modules_public.encrypted_secrets_module (
     CONSTRAINT table_fkey FOREIGN KEY (table_id) REFERENCES metaschema_public.table (id) ON DELETE CASCADE
 );
 
-CREATE INDEX encrypted_secrets_module_database_id_idx ON metaschema_modules_public.encrypted_secrets_module ( database_id );
+CREATE INDEX config_secrets_user_module_database_id_idx ON metaschema_modules_public.config_secrets_user_module ( database_id );
 
 COMMIT;

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

@@ -0,0 +1,52 @@
+-- Deploy schemas/metaschema_modules_public/tables/db_usage_module/table to pg
+
+-- requires: schemas/metaschema_modules_public/schema
+
+BEGIN;
+
+CREATE TABLE metaschema_modules_public.db_usage_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(),
+
+  -- DB table stats log (partitioned — per-table reads/writes/size from pg_stat_user_tables)
+  table_stats_log_table_id uuid NOT NULL DEFAULT uuid_nil(),
+  table_stats_log_table_name text NOT NULL DEFAULT '',
+
+  -- DB table stats daily rollup
+  table_stats_daily_table_id uuid NOT NULL DEFAULT uuid_nil(),
+  table_stats_daily_table_name text NOT NULL DEFAULT '',
+
+  -- DB query stats log (partitioned — query execution time from pg_stat_statements)
+  query_stats_log_table_id uuid NOT NULL DEFAULT uuid_nil(),
+  query_stats_log_table_name text NOT NULL DEFAULT '',
+
+  -- DB query stats daily rollup
+  query_stats_daily_table_id uuid NOT NULL DEFAULT uuid_nil(),
+  query_stats_daily_table_name text NOT NULL DEFAULT '',
+
+  -- Partition lifecycle configuration
+  "interval" text NOT NULL DEFAULT '1 month',
+  retention text NOT NULL DEFAULT '12 months',
+  premake int NOT NULL DEFAULT 2,
+
+  -- Scope configuration: 'app' = per-app usage, 'platform' = tenant metering (database_id RLS)
+  scope text NOT NULL DEFAULT 'app',
+
+  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 table_stats_log_table_fkey FOREIGN KEY (table_stats_log_table_id) REFERENCES metaschema_public.table (id) ON DELETE CASCADE,
+  CONSTRAINT table_stats_daily_table_fkey FOREIGN KEY (table_stats_daily_table_id) REFERENCES metaschema_public.table (id) ON DELETE CASCADE,
+  CONSTRAINT query_stats_log_table_fkey FOREIGN KEY (query_stats_log_table_id) REFERENCES metaschema_public.table (id) ON DELETE CASCADE,
+  CONSTRAINT query_stats_daily_table_fkey FOREIGN KEY (query_stats_daily_table_id) REFERENCES metaschema_public.table (id) ON DELETE CASCADE,
+  CONSTRAINT db_usage_module_database_id_prefix_unique UNIQUE NULLS NOT DISTINCT (database_id, prefix)
+);
+
+CREATE INDEX db_usage_module_database_id_idx ON metaschema_modules_public.db_usage_module ( database_id );
+
+COMMIT;

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

@@ -47,16 +47,34 @@ CREATE TABLE metaschema_modules_public.entity_type_provision (
 
     has_levels boolean NOT NULL DEFAULT false,
 
-    has_storage boolean NOT NULL DEFAULT false,
-
     has_invites boolean NOT NULL DEFAULT false,
 
+    has_invite_achievements boolean NOT NULL DEFAULT false,
+
     -- =========================================================================
-    -- Storage configuration: module-level overrides + initial bucket defs.
-    -- Only used when has_storage = true. NULL = use defaults.
+    -- Storage configuration: JSON array of storage module definitions.
+    -- Each element provisions a separate storage module with its own tables,
+    -- RLS policies, and feature flags. Presence triggers provisioning
+    -- (same inference model as namespaces, functions, agents).
+    -- NULL = do not provision. '[{}]' = provision one default storage module.
     -- =========================================================================
 
-    storage_config jsonb DEFAULT NULL,
+    storage jsonb DEFAULT NULL,
+
+    -- =========================================================================
+    -- Module configuration arrays: presence triggers provisioning.
+    -- Each is a JSON array of module definitions (like storage).
+    -- NULL = do not provision. '[{}]' = provision one default instance.
+    -- Each element may include "key" (discriminator) and "policies" (override).
+    -- =========================================================================
+
+    namespaces jsonb DEFAULT NULL,
+
+    functions jsonb DEFAULT NULL,
+
+    graphs jsonb DEFAULT NULL,
+
+    agents jsonb DEFAULT NULL,
 
     -- =========================================================================
     -- Escape hatch: skip default entity table RLS policies
@@ -103,6 +121,26 @@ CREATE TABLE metaschema_modules_public.entity_type_provision (
 
     out_invites_module_id uuid DEFAULT NULL,
 
+    out_namespace_module_id uuid DEFAULT NULL,
+
+    out_namespaces_table_id uuid DEFAULT NULL,
+
+    out_namespace_events_table_id uuid DEFAULT NULL,
+
+    out_function_module_id uuid DEFAULT NULL,
+
+    out_definitions_table_id uuid DEFAULT NULL,
+
+    out_invocations_table_id uuid DEFAULT NULL,
+
+    out_execution_logs_table_id uuid DEFAULT NULL,
+
+    out_graph_module_id uuid DEFAULT NULL,
+
+    out_graphs_table_id uuid DEFAULT NULL,
+
+    out_agent_module_id uuid DEFAULT NULL,
+
     -- =========================================================================
     -- Constraints
     -- =========================================================================
@@ -197,24 +235,27 @@ COMMENT ON COLUMN metaschema_modules_public.entity_type_provision.has_profiles I
      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.
+    'Whether to provision events_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.';
+     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.';
+
+COMMENT ON COLUMN metaschema_modules_public.entity_type_provision.has_invite_achievements IS
+    'Whether to auto-attach an EventTracker to the claimed_invites table for invite-based
+     achievements. Defaults to false. Requires has_invites=true AND has_levels=true.
+     When true, the trigger calls event_tracker() on the claimed_invites table with
+     event_name=''invite_claimed'', actor_field=''sender_id'', events=[''INSERT''],
+     crediting the SENDER (inviter) when someone claims their invite code.
+     Developers can then define achievements in the blueprint achievements[] section
+     that reference the ''invite_claimed'' event (e.g., "Invite 5 friends" = count: 5).';
 
 -- =============================================================================
 -- Escape hatch
@@ -283,50 +324,95 @@ COMMENT ON COLUMN metaschema_modules_public.entity_type_provision.out_installed_
     '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.storage IS
+    'Optional JSON array of storage module definitions. Presence triggers provisioning
+     (same inference model as namespaces, functions, agents).
+     Each element provisions a separate storage module with its own tables
+     ({prefix}_{storage_key}_buckets/files), RLS policies, and feature flags.
+     NULL = do not provision storage. ''[{}]'' = provision one default storage module.
+     Each array element recognizes (all optional):
+       - storage_key                   (text) module discriminator, max 16 chars, lowercase snake_case.
+                                              Defaults to ''default'' (omitted from table names).
+                                              Non-default keys become infixes: {prefix}_{key}_buckets.
+       - 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 module
+       - allowed_origins               (text[])  default CORS origins for all buckets in this module
+       - restrict_reads                (boolean) require read_files permission for SELECT on files
+       - has_path_shares               (boolean) enable virtual filesystem + path share policies
+       - has_versioning                (boolean) enable file version chains
+       - has_content_hash              (boolean) enable content hash for dedup
+       - has_custom_keys               (boolean) allow client-provided S3 keys
+       - has_audit_log                 (boolean) enable file events audit table
+       - has_confirm_upload            (boolean) enable HeadObject confirmation flow
+       - confirm_upload_delay          (interval) delay before first confirmation attempt
+       - buckets                       (jsonb[]) array of initial bucket definitions to seed.
+         Each bucket: { name (required), description, is_public, allowed_mime_types, max_file_size, allowed_origins }
+       - provisions                    (jsonb object) per-table customization keyed by "files" or "buckets".
+                                              Each value: { nodes, fields, grants, use_rls, policies }.
+     Example (single module, backward compat):
+       storage := ''[{"buckets": [{"name": "documents"}]}]''::jsonb
+     Example (multi-module):
+       storage := ''[{"has_path_shares": true, "buckets": [{"name": "documents"}]}, {"storage_key": "fn", "has_custom_keys": true, "buckets": [{"name": "functions"}]}]''::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.';
+    'Output: the UUID of the storage_module row created for this entity type. Populated by the trigger when storage is non-NULL and non-empty.';
 
 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.';
+    'Output: the UUID of the generated buckets table (e.g. data_room_buckets). Populated by the trigger when storage is non-NULL and non-empty.';
 
 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.';
+    'Output: the UUID of the generated files table (e.g. data_room_files). Populated by the trigger when storage is non-NULL and non-empty.';
 
 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).';
 
+COMMENT ON COLUMN metaschema_modules_public.entity_type_provision.namespaces IS
+    'Optional JSON array of namespace module definitions. Presence triggers provisioning.
+     NULL = do not provision namespaces. ''[{}]'' = provision one default namespace module.
+     Each element recognizes (all optional):
+       - key       (text) module discriminator. Defaults to ''default''.
+       - policies  (jsonb array) RLS policy overrides. NULL = apply defaults from apply_namespace_security().
+     Creates {prefix}_namespaces (or {prefix}_{key}_namespaces for non-default keys)
+     with entity-scoped RLS (AuthzEntityMembership) and a rename proxy trigger.
+     Registers manage_namespaces permission bit on first provision.
+     Example: namespaces := ''[{}]''::jsonb';
+
+COMMENT ON COLUMN metaschema_modules_public.entity_type_provision.functions IS
+    'Optional JSON array of function module definitions. Presence triggers provisioning.
+     NULL = do not provision functions. ''[{}]'' = provision one default function module.
+     Each element recognizes (all optional):
+       - key       (text) module discriminator. Defaults to ''default''.
+       - policies  (jsonb array) RLS policy overrides. NULL = apply defaults from apply_function_security().
+     Creates {prefix}_function_definitions (or {prefix}_{key}_function_definitions for non-default keys)
+     with entity-scoped RLS and a job trigger dispatching function:provision tasks.
+     Registers manage_functions + invoke_functions permission bits on first provision.
+     Example: functions := ''[{}]''::jsonb';
+
+COMMENT ON COLUMN metaschema_modules_public.entity_type_provision.graphs IS
+    'Optional JSON array of graph module definitions. Presence triggers provisioning.
+     NULL = do not provision graphs. ''[{}]'' = provision one default graph module.
+     Each element recognizes (all optional):
+       - key       (text) module discriminator. Defaults to ''default''.
+       - policies  (jsonb array) RLS policy overrides. NULL = apply defaults from apply_graph_security().
+     Registers manage_graphs + execute_graphs permission bits on first provision.
+     Graph module requires a merkle_store_module_id dependency, so entity_type_provision
+     only registers permissions here. The graph module itself must be provisioned
+     separately with the merkle store dependency resolved.
+     Example: graphs := ''[{}]''::jsonb';
+
+COMMENT ON COLUMN metaschema_modules_public.entity_type_provision.out_namespace_module_id IS
+    'Output: the UUID of the namespace_module row created (or found) for this entity type.
+     Populated by the trigger when namespaces is non-NULL. NULL otherwise.';
+
+COMMENT ON COLUMN metaschema_modules_public.entity_type_provision.out_namespaces_table_id IS
+    'Output: the UUID of the generated namespaces table (e.g. data_room_namespaces).
+     Populated by the trigger when namespaces is non-NULL. NULL otherwise.';
+
+COMMENT ON COLUMN metaschema_modules_public.entity_type_provision.out_namespace_events_table_id IS
+    'Output: the UUID of the generated namespace_events partitioned table (e.g. data_room_namespace_events).
+     Monthly partitioned, 12-month retention. Populated by the trigger when namespaces is non-NULL. NULL otherwise.';
+
 COMMIT;

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

@@ -0,0 +1,85 @@
+-- Deploy schemas/metaschema_modules_public/tables/events_module/table to pg
+
+-- requires: schemas/metaschema_modules_public/schema
+
+BEGIN;
+
+CREATE TABLE metaschema_modules_public.events_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(),
+  --
+  
+  events_table_id uuid NOT NULL DEFAULT uuid_nil(),
+  events_table_name text NOT NULL DEFAULT '',
+
+  event_aggregates_table_id uuid NOT NULL DEFAULT uuid_nil(),
+  event_aggregates_table_name text NOT NULL DEFAULT '',
+
+  event_types_table_id uuid NOT NULL DEFAULT uuid_nil(),
+  event_types_table_name text NOT NULL DEFAULT '',
+
+  levels_table_id uuid NOT NULL DEFAULT uuid_nil(),
+  levels_table_name text NOT NULL DEFAULT '',
+
+  level_requirements_table_id uuid NOT NULL DEFAULT uuid_nil(),
+  level_requirements_table_name text NOT NULL DEFAULT '',
+
+  level_grants_table_id uuid NOT NULL DEFAULT uuid_nil(),
+  level_grants_table_name text NOT NULL DEFAULT '',
+
+  achievement_rewards_table_id uuid NOT NULL DEFAULT uuid_nil(),
+  achievement_rewards_table_name text NOT NULL DEFAULT '',
+
+  record_event text NOT NULL DEFAULT '',
+  remove_event text NOT NULL DEFAULT '',
+  tg_event text NOT NULL DEFAULT '',
+  tg_event_toggle text NOT NULL DEFAULT '',
+  tg_event_toggle_bool text NOT NULL DEFAULT '',
+  tg_event_bool text NOT NULL DEFAULT '',
+  upsert_aggregate text NOT NULL DEFAULT '',
+  tg_update_aggregates text NOT NULL DEFAULT '',
+  prune_events text NOT NULL DEFAULT '',
+  steps_required text NOT NULL DEFAULT '',
+  level_achieved text NOT NULL DEFAULT '',
+  tg_check_achievements text NOT NULL DEFAULT '',
+  grant_achievement text NOT NULL DEFAULT '',
+  tg_achievement_reward text NOT NULL DEFAULT '',
+
+  -- Partition lifecycle configuration for events table
+  "interval" text NOT NULL DEFAULT '1 month',
+  retention text DEFAULT '12 months',
+  premake int NOT NULL DEFAULT 2,
+
+  prefix text NULL,
+
+  membership_type int NOT NULL,
+  -- if this is NOT NULL, then we add entity_id 
+  -- e.g. limits to the app itself are considered global owned by app and no explicit owner
+  entity_table_id uuid NULL,
+
+  -- required tables    
+  actor_table_id uuid NOT NULL DEFAULT uuid_nil(),
+
+
+  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 events_table_fkey FOREIGN KEY (events_table_id) REFERENCES metaschema_public.table (id) ON DELETE CASCADE,
+  CONSTRAINT event_aggregates_table_fkey FOREIGN KEY (event_aggregates_table_id) REFERENCES metaschema_public.table (id) ON DELETE CASCADE,
+  CONSTRAINT event_types_table_fkey FOREIGN KEY (event_types_table_id) REFERENCES metaschema_public.table (id) ON DELETE CASCADE,
+  CONSTRAINT levels_table_fkey FOREIGN KEY (levels_table_id) REFERENCES metaschema_public.table (id) ON DELETE CASCADE,
+  CONSTRAINT level_requirements_table_fkey FOREIGN KEY (level_requirements_table_id) REFERENCES metaschema_public.table (id) ON DELETE CASCADE,
+  CONSTRAINT level_grants_table_fkey FOREIGN KEY (level_grants_table_id) REFERENCES metaschema_public.table (id) ON DELETE CASCADE,
+  CONSTRAINT achievement_rewards_table_fkey FOREIGN KEY (achievement_rewards_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
+);
+
+CREATE INDEX events_module_database_id_idx ON metaschema_modules_public.events_module ( database_id );
+
+COMMIT;