@fayz-ai/db 0.9.0-next.1 → 0.10.0

package/README.md

@@ -39,4 +39,4 @@ export const notes = pgTable('notes', {
 The data spine beneath every plugin schema; apps compose it in their own `drizzle.config`.
 
 ## Roadmap & contributing
-Built and evolving in the open. See the [Fayz SDK roadmap](../../docs/ROADMAP.md#db) for current gaps, missing features, and good first issues.
+Built and evolving in the open. See the [Fayz SDK roadmap](../../docs/platform/ROADMAP.md#db) for current gaps, missing features, and good first issues.

package/dist/index.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/schema/spine.ts","../src/helpers.ts"],"names":["pgTable","uuid","timestamp"],"mappings":";;;;;AAYO,IAAM,OAAA,GAAUA,eAAQ,SAAA,EAAW;AAAA,EACxC,EAAA,EAAIC,WAAA,CAAK,IAAI,CAAA,CAAE,UAAA;AACjB,CAAC;AAEM,IAAM,MAAA,GAASD,eAAQ,QAAA,EAAU;AAAA,EACtC,EAAA,EAAIC,WAAA,CAAK,IAAI,CAAA,CAAE,UAAA;AACjB,CAAC;AAEM,IAAM,MAAA,GAASD,eAAQ,QAAA,EAAU;AAAA,EACtC,EAAA,EAAIC,WAAA,CAAK,IAAI,CAAA,CAAE,UAAA;AACjB,CAAC;AAEM,IAAM,YAAA,GAAeD,eAAQ,cAAA,EAAgB;AAAA,EAClD,EAAA,EAAIC,WAAA,CAAK,IAAI,CAAA,CAAE,UAAA;AACjB,CAAC;AAEM,IAAM,QAAA,GAAWD,eAAQ,UAAA,EAAY;AAAA,EAC1C,EAAA,EAAIC,WAAA,CAAK,IAAI,CAAA,CAAE,UAAA;AACjB,CAAC;AAEM,IAAM,UAAA,GAAaD,eAAQ,aAAA,EAAe;AAAA,EAC/C,EAAA,EAAIC,WAAA,CAAK,IAAI,CAAA,CAAE,UAAA;AACjB,CAAC;AC1BM,IAAM,QAAA,GAAW,MACtBA,WAAAA,CAAK,WAAW,EACb,OAAA,EAAQ,CACR,UAAA,CAAW,MAAM,OAAA,CAAQ,EAAA,EAAI,EAAE,QAAA,EAAU,WAAW;AAGlD,IAAM,UAAA,GAAa;AAAA,EACxB,SAAA,EAAWC,gBAAA,CAAU,YAAA,EAAc,EAAE,YAAA,EAAc,MAAM,CAAA,CAAE,OAAA,EAAQ,CAAE,UAAA,EAAW;AAAA,EAChF,SAAA,EAAWA,gBAAA,CAAU,YAAA,EAAc,EAAE,YAAA,EAAc,MAAM,CAAA,CAAE,OAAA,EAAQ,CAAE,UAAA;AACvE;AAGO,IAAM,SAAA,GAAY;AAAA,EACvB,SAAA,EAAWA,gBAAA,CAAU,YAAA,EAAc,EAAE,YAAA,EAAc,MAAM,CAAA,CAAE,OAAA,EAAQ,CAAE,UAAA;AACvE","file":"index.cjs","sourcesContent":["import { pgTable, uuid } from 'drizzle-orm/pg-core'\n\n/**\n * Ring 0 — the core spine, declared as Drizzle *references* only.\n *\n * These tables are owned by the platform (@fayz-ai/saas core) and already exist\n * in every provisioned pool, directly in the `public` schema (industry-pool\n * model — no saas_core schema). We declare a minimal shape here purely so plugin\n * tables can express real foreign keys in TypeScript. They land in the Drizzle\n * *baseline* snapshot (never re-created), so only the `id` FK target is needed —\n * the live columns are authoritative.\n */\nexport const tenants = pgTable('tenants', {\n  id: uuid('id').primaryKey(),\n})\n\nexport const people = pgTable('people', {\n  id: uuid('id').primaryKey(),\n})\n\nexport const orders = pgTable('orders', {\n  id: uuid('id').primaryKey(),\n})\n\nexport const appointments = pgTable('appointments', {\n  id: uuid('id').primaryKey(),\n})\n\nexport const products = pgTable('products', {\n  id: uuid('id').primaryKey(),\n})\n\nexport const orderItems = pgTable('order_items', {\n  id: uuid('id').primaryKey(),\n})\n","import { uuid, timestamp } from 'drizzle-orm/pg-core'\nimport { tenants } from './schema/spine'\n\n/**\n * Canonical tenant-scoping column: `tenant_id uuid NOT NULL REFERENCES\n * public.tenants(id) ON DELETE CASCADE`. Every Ring-1 plugin table uses this\n * so tenancy is identical everywhere (and RLS can assume the column exists).\n */\nexport const tenantId = () =>\n  uuid('tenant_id')\n    .notNull()\n    .references(() => tenants.id, { onDelete: 'cascade' })\n\n/** Standard `created_at` / `updated_at` timestamptz pair with `now()` defaults. */\nexport const timestamps = {\n  createdAt: timestamp('created_at', { withTimezone: true }).notNull().defaultNow(),\n  updatedAt: timestamp('updated_at', { withTimezone: true }).notNull().defaultNow(),\n}\n\n/** Just `created_at` (for append-only / event-style tables). */\nexport const createdAt = {\n  createdAt: timestamp('created_at', { withTimezone: true }).notNull().defaultNow(),\n}\n"]}
+{"version":3,"sources":["../src/schema/spine.ts","../src/lib/helpers.ts"],"names":["pgTable","uuid","timestamp"],"mappings":";;;;;AAYO,IAAM,OAAA,GAAUA,eAAQ,SAAA,EAAW;AAAA,EACxC,EAAA,EAAIC,WAAA,CAAK,IAAI,CAAA,CAAE,UAAA;AACjB,CAAC;AAEM,IAAM,MAAA,GAASD,eAAQ,QAAA,EAAU;AAAA,EACtC,EAAA,EAAIC,WAAA,CAAK,IAAI,CAAA,CAAE,UAAA;AACjB,CAAC;AAEM,IAAM,MAAA,GAASD,eAAQ,QAAA,EAAU;AAAA,EACtC,EAAA,EAAIC,WAAA,CAAK,IAAI,CAAA,CAAE,UAAA;AACjB,CAAC;AAEM,IAAM,YAAA,GAAeD,eAAQ,cAAA,EAAgB;AAAA,EAClD,EAAA,EAAIC,WAAA,CAAK,IAAI,CAAA,CAAE,UAAA;AACjB,CAAC;AAEM,IAAM,QAAA,GAAWD,eAAQ,UAAA,EAAY;AAAA,EAC1C,EAAA,EAAIC,WAAA,CAAK,IAAI,CAAA,CAAE,UAAA;AACjB,CAAC;AAEM,IAAM,UAAA,GAAaD,eAAQ,aAAA,EAAe;AAAA,EAC/C,EAAA,EAAIC,WAAA,CAAK,IAAI,CAAA,CAAE,UAAA;AACjB,CAAC;AC1BM,IAAM,QAAA,GAAW,MACtBA,WAAAA,CAAK,WAAW,EACb,OAAA,EAAQ,CACR,UAAA,CAAW,MAAM,OAAA,CAAQ,EAAA,EAAI,EAAE,QAAA,EAAU,WAAW;AAGlD,IAAM,UAAA,GAAa;AAAA,EACxB,SAAA,EAAWC,gBAAA,CAAU,YAAA,EAAc,EAAE,YAAA,EAAc,MAAM,CAAA,CAAE,OAAA,EAAQ,CAAE,UAAA,EAAW;AAAA,EAChF,SAAA,EAAWA,gBAAA,CAAU,YAAA,EAAc,EAAE,YAAA,EAAc,MAAM,CAAA,CAAE,OAAA,EAAQ,CAAE,UAAA;AACvE;AAGO,IAAM,SAAA,GAAY;AAAA,EACvB,SAAA,EAAWA,gBAAA,CAAU,YAAA,EAAc,EAAE,YAAA,EAAc,MAAM,CAAA,CAAE,OAAA,EAAQ,CAAE,UAAA;AACvE","file":"index.cjs","sourcesContent":["import { pgTable, uuid } from 'drizzle-orm/pg-core'\n\n/**\n * Ring 0 — the core spine, declared as Drizzle *references* only.\n *\n * These tables are owned by the platform (@fayz-ai/admin core) and already exist\n * in every provisioned pool, directly in the `public` schema (industry-pool\n * model — no saas_core schema). We declare a minimal shape here purely so plugin\n * tables can express real foreign keys in TypeScript. They land in the Drizzle\n * *baseline* snapshot (never re-created), so only the `id` FK target is needed —\n * the live columns are authoritative.\n */\nexport const tenants = pgTable('tenants', {\n  id: uuid('id').primaryKey(),\n})\n\nexport const people = pgTable('people', {\n  id: uuid('id').primaryKey(),\n})\n\nexport const orders = pgTable('orders', {\n  id: uuid('id').primaryKey(),\n})\n\nexport const appointments = pgTable('appointments', {\n  id: uuid('id').primaryKey(),\n})\n\nexport const products = pgTable('products', {\n  id: uuid('id').primaryKey(),\n})\n\nexport const orderItems = pgTable('order_items', {\n  id: uuid('id').primaryKey(),\n})\n","import { uuid, timestamp } from 'drizzle-orm/pg-core'\nimport { tenants } from '../schema/spine'\n\n/**\n * Canonical tenant-scoping column: `tenant_id uuid NOT NULL REFERENCES\n * public.tenants(id) ON DELETE CASCADE`. Every Ring-1 plugin table uses this\n * so tenancy is identical everywhere (and RLS can assume the column exists).\n */\nexport const tenantId = () =>\n  uuid('tenant_id')\n    .notNull()\n    .references(() => tenants.id, { onDelete: 'cascade' })\n\n/** Standard `created_at` / `updated_at` timestamptz pair with `now()` defaults. */\nexport const timestamps = {\n  createdAt: timestamp('created_at', { withTimezone: true }).notNull().defaultNow(),\n  updatedAt: timestamp('updated_at', { withTimezone: true }).notNull().defaultNow(),\n}\n\n/** Just `created_at` (for append-only / event-style tables). */\nexport const createdAt = {\n  createdAt: timestamp('created_at', { withTimezone: true }).notNull().defaultNow(),\n}\n"]}

package/dist/index.d.ts

@@ -1,4 +1,4 @@
 export * from 'drizzle-orm/pg-core';
 export { tenants, people, orders, appointments, products, orderItems } from './schema/spine';
-export { tenantId, timestamps, createdAt } from './helpers';
+export { tenantId, timestamps, createdAt } from './lib/helpers';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAQA,cAAc,qBAAqB,CAAA;AAEnC,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,YAAY,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAA;AAC5F,OAAO,EAAE,QAAQ,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,WAAW,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAQA,cAAc,qBAAqB,CAAA;AAEnC,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,YAAY,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAA;AAC5F,OAAO,EAAE,QAAQ,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,eAAe,CAAA"}

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/schema/spine.ts","../src/helpers.ts"],"names":["uuid"],"mappings":";;;;AAYO,IAAM,OAAA,GAAU,QAAQ,SAAA,EAAW;AAAA,EACxC,EAAA,EAAI,IAAA,CAAK,IAAI,CAAA,CAAE,UAAA;AACjB,CAAC;AAEM,IAAM,MAAA,GAAS,QAAQ,QAAA,EAAU;AAAA,EACtC,EAAA,EAAI,IAAA,CAAK,IAAI,CAAA,CAAE,UAAA;AACjB,CAAC;AAEM,IAAM,MAAA,GAAS,QAAQ,QAAA,EAAU;AAAA,EACtC,EAAA,EAAI,IAAA,CAAK,IAAI,CAAA,CAAE,UAAA;AACjB,CAAC;AAEM,IAAM,YAAA,GAAe,QAAQ,cAAA,EAAgB;AAAA,EAClD,EAAA,EAAI,IAAA,CAAK,IAAI,CAAA,CAAE,UAAA;AACjB,CAAC;AAEM,IAAM,QAAA,GAAW,QAAQ,UAAA,EAAY;AAAA,EAC1C,EAAA,EAAI,IAAA,CAAK,IAAI,CAAA,CAAE,UAAA;AACjB,CAAC;AAEM,IAAM,UAAA,GAAa,QAAQ,aAAA,EAAe;AAAA,EAC/C,EAAA,EAAI,IAAA,CAAK,IAAI,CAAA,CAAE,UAAA;AACjB,CAAC;AC1BM,IAAM,QAAA,GAAW,MACtBA,IAAAA,CAAK,WAAW,EACb,OAAA,EAAQ,CACR,UAAA,CAAW,MAAM,OAAA,CAAQ,EAAA,EAAI,EAAE,QAAA,EAAU,WAAW;AAGlD,IAAM,UAAA,GAAa;AAAA,EACxB,SAAA,EAAW,SAAA,CAAU,YAAA,EAAc,EAAE,YAAA,EAAc,MAAM,CAAA,CAAE,OAAA,EAAQ,CAAE,UAAA,EAAW;AAAA,EAChF,SAAA,EAAW,SAAA,CAAU,YAAA,EAAc,EAAE,YAAA,EAAc,MAAM,CAAA,CAAE,OAAA,EAAQ,CAAE,UAAA;AACvE;AAGO,IAAM,SAAA,GAAY;AAAA,EACvB,SAAA,EAAW,SAAA,CAAU,YAAA,EAAc,EAAE,YAAA,EAAc,MAAM,CAAA,CAAE,OAAA,EAAQ,CAAE,UAAA;AACvE","file":"index.js","sourcesContent":["import { pgTable, uuid } from 'drizzle-orm/pg-core'\n\n/**\n * Ring 0 — the core spine, declared as Drizzle *references* only.\n *\n * These tables are owned by the platform (@fayz-ai/saas core) and already exist\n * in every provisioned pool, directly in the `public` schema (industry-pool\n * model — no saas_core schema). We declare a minimal shape here purely so plugin\n * tables can express real foreign keys in TypeScript. They land in the Drizzle\n * *baseline* snapshot (never re-created), so only the `id` FK target is needed —\n * the live columns are authoritative.\n */\nexport const tenants = pgTable('tenants', {\n  id: uuid('id').primaryKey(),\n})\n\nexport const people = pgTable('people', {\n  id: uuid('id').primaryKey(),\n})\n\nexport const orders = pgTable('orders', {\n  id: uuid('id').primaryKey(),\n})\n\nexport const appointments = pgTable('appointments', {\n  id: uuid('id').primaryKey(),\n})\n\nexport const products = pgTable('products', {\n  id: uuid('id').primaryKey(),\n})\n\nexport const orderItems = pgTable('order_items', {\n  id: uuid('id').primaryKey(),\n})\n","import { uuid, timestamp } from 'drizzle-orm/pg-core'\nimport { tenants } from './schema/spine'\n\n/**\n * Canonical tenant-scoping column: `tenant_id uuid NOT NULL REFERENCES\n * public.tenants(id) ON DELETE CASCADE`. Every Ring-1 plugin table uses this\n * so tenancy is identical everywhere (and RLS can assume the column exists).\n */\nexport const tenantId = () =>\n  uuid('tenant_id')\n    .notNull()\n    .references(() => tenants.id, { onDelete: 'cascade' })\n\n/** Standard `created_at` / `updated_at` timestamptz pair with `now()` defaults. */\nexport const timestamps = {\n  createdAt: timestamp('created_at', { withTimezone: true }).notNull().defaultNow(),\n  updatedAt: timestamp('updated_at', { withTimezone: true }).notNull().defaultNow(),\n}\n\n/** Just `created_at` (for append-only / event-style tables). */\nexport const createdAt = {\n  createdAt: timestamp('created_at', { withTimezone: true }).notNull().defaultNow(),\n}\n"]}
+{"version":3,"sources":["../src/schema/spine.ts","../src/lib/helpers.ts"],"names":["uuid"],"mappings":";;;;AAYO,IAAM,OAAA,GAAU,QAAQ,SAAA,EAAW;AAAA,EACxC,EAAA,EAAI,IAAA,CAAK,IAAI,CAAA,CAAE,UAAA;AACjB,CAAC;AAEM,IAAM,MAAA,GAAS,QAAQ,QAAA,EAAU;AAAA,EACtC,EAAA,EAAI,IAAA,CAAK,IAAI,CAAA,CAAE,UAAA;AACjB,CAAC;AAEM,IAAM,MAAA,GAAS,QAAQ,QAAA,EAAU;AAAA,EACtC,EAAA,EAAI,IAAA,CAAK,IAAI,CAAA,CAAE,UAAA;AACjB,CAAC;AAEM,IAAM,YAAA,GAAe,QAAQ,cAAA,EAAgB;AAAA,EAClD,EAAA,EAAI,IAAA,CAAK,IAAI,CAAA,CAAE,UAAA;AACjB,CAAC;AAEM,IAAM,QAAA,GAAW,QAAQ,UAAA,EAAY;AAAA,EAC1C,EAAA,EAAI,IAAA,CAAK,IAAI,CAAA,CAAE,UAAA;AACjB,CAAC;AAEM,IAAM,UAAA,GAAa,QAAQ,aAAA,EAAe;AAAA,EAC/C,EAAA,EAAI,IAAA,CAAK,IAAI,CAAA,CAAE,UAAA;AACjB,CAAC;AC1BM,IAAM,QAAA,GAAW,MACtBA,IAAAA,CAAK,WAAW,EACb,OAAA,EAAQ,CACR,UAAA,CAAW,MAAM,OAAA,CAAQ,EAAA,EAAI,EAAE,QAAA,EAAU,WAAW;AAGlD,IAAM,UAAA,GAAa;AAAA,EACxB,SAAA,EAAW,SAAA,CAAU,YAAA,EAAc,EAAE,YAAA,EAAc,MAAM,CAAA,CAAE,OAAA,EAAQ,CAAE,UAAA,EAAW;AAAA,EAChF,SAAA,EAAW,SAAA,CAAU,YAAA,EAAc,EAAE,YAAA,EAAc,MAAM,CAAA,CAAE,OAAA,EAAQ,CAAE,UAAA;AACvE;AAGO,IAAM,SAAA,GAAY;AAAA,EACvB,SAAA,EAAW,SAAA,CAAU,YAAA,EAAc,EAAE,YAAA,EAAc,MAAM,CAAA,CAAE,OAAA,EAAQ,CAAE,UAAA;AACvE","file":"index.js","sourcesContent":["import { pgTable, uuid } from 'drizzle-orm/pg-core'\n\n/**\n * Ring 0 — the core spine, declared as Drizzle *references* only.\n *\n * These tables are owned by the platform (@fayz-ai/admin core) and already exist\n * in every provisioned pool, directly in the `public` schema (industry-pool\n * model — no saas_core schema). We declare a minimal shape here purely so plugin\n * tables can express real foreign keys in TypeScript. They land in the Drizzle\n * *baseline* snapshot (never re-created), so only the `id` FK target is needed —\n * the live columns are authoritative.\n */\nexport const tenants = pgTable('tenants', {\n  id: uuid('id').primaryKey(),\n})\n\nexport const people = pgTable('people', {\n  id: uuid('id').primaryKey(),\n})\n\nexport const orders = pgTable('orders', {\n  id: uuid('id').primaryKey(),\n})\n\nexport const appointments = pgTable('appointments', {\n  id: uuid('id').primaryKey(),\n})\n\nexport const products = pgTable('products', {\n  id: uuid('id').primaryKey(),\n})\n\nexport const orderItems = pgTable('order_items', {\n  id: uuid('id').primaryKey(),\n})\n","import { uuid, timestamp } from 'drizzle-orm/pg-core'\nimport { tenants } from '../schema/spine'\n\n/**\n * Canonical tenant-scoping column: `tenant_id uuid NOT NULL REFERENCES\n * public.tenants(id) ON DELETE CASCADE`. Every Ring-1 plugin table uses this\n * so tenancy is identical everywhere (and RLS can assume the column exists).\n */\nexport const tenantId = () =>\n  uuid('tenant_id')\n    .notNull()\n    .references(() => tenants.id, { onDelete: 'cascade' })\n\n/** Standard `created_at` / `updated_at` timestamptz pair with `now()` defaults. */\nexport const timestamps = {\n  createdAt: timestamp('created_at', { withTimezone: true }).notNull().defaultNow(),\n  updatedAt: timestamp('updated_at', { withTimezone: true }).notNull().defaultNow(),\n}\n\n/** Just `created_at` (for append-only / event-style tables). */\nexport const createdAt = {\n  createdAt: timestamp('created_at', { withTimezone: true }).notNull().defaultNow(),\n}\n"]}

package/dist/lib/helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"helpers.d.ts","sourceRoot":"","sources":["../../src/lib/helpers.ts"],"names":[],"mappings":"AAGA;;;;GAIG;AACH,eAAO,MAAM,QAAQ,sGAGqC,CAAA;AAE1D,mFAAmF;AACnF,eAAO,MAAM,UAAU;;;CAGtB,CAAA;AAED,gEAAgE;AAChE,eAAO,MAAM,SAAS;;CAErB,CAAA"}

package/dist/schema/spine.d.ts

@@ -1,7 +1,7 @@
 /**
  * Ring 0 — the core spine, declared as Drizzle *references* only.
  *
- * These tables are owned by the platform (@fayz-ai/saas core) and already exist
+ * These tables are owned by the platform (@fayz-ai/admin core) and already exist
  * in every provisioned pool, directly in the `public` schema (industry-pool
  * model — no saas_core schema). We declare a minimal shape here purely so plugin
  * tables can express real foreign keys in TypeScript. They land in the Drizzle

package/migrations/024_analytics_engine.sql

@@ -0,0 +1,317 @@
+-- ============================================================================
+-- The analytics engine — one aggregate function for every domain
+-- ----------------------------------------------------------------------------
+-- Until now every number in the product was computed twice and differently: a
+-- dashboard KPI pulled `listOrders({limit: 200})` and summed in JavaScript,
+-- while the report engine ran a flat SELECT over a `rep_*` view. Two engines,
+-- two answers, and the KPI silently wrong the moment a tenant passes 200 rows.
+--
+-- This is the half that belongs to NO domain: an allowlist of queryable read
+-- models, an identifier guard, and analytics_run() — which groups, buckets and
+-- aggregates any registered read model from parameters. "Orders over time" and
+-- "sales by product" are the same call with different dimensions, so adding a
+-- report stops being a database migration.
+--
+-- Each domain ships its own read models and registers them (see
+-- packages/shop/migrations/0039_analytics_read_models.sql). A salon, a school
+-- and a store all reuse this function over completely different views.
+--
+-- Because a KPI and the report behind it are literally the same query with and
+-- without the GROUP BY, they cannot disagree.
+--
+-- SECURITY. This function builds dynamic SQL from caller-supplied strings, so:
+--   * the source must be registered in plg_analytics_read_models — an allowlist,
+--     not a prefix convention a future view could accidentally satisfy;
+--   * every column name is verified to exist on that source via
+--     information_schema before it reaches the statement;
+--   * aggregates and time grains are matched against fixed enums;
+--   * identifiers go through %I and literals through %L, never concatenation;
+--   * the function is SECURITY INVOKER and read models are security_invoker=true,
+--     so the underlying RLS still decides which rows exist. The explicit tenant
+--     filter is defence in depth, not the only lock.
+--
+-- Idempotent.
+-- ============================================================================
+
+-- ----------------------------------------------------------------------------
+-- 1. The allowlist. A read model that is not in here cannot be queried, full
+--    stop. Registering is a migration-time act, never a runtime one.
+-- ----------------------------------------------------------------------------
+CREATE TABLE IF NOT EXISTS public.plg_analytics_read_models (
+  name          text PRIMARY KEY,
+  -- The time spine. Taken from HERE and not from the client: the read model is
+  -- the authority on which of its columns is "when this happened".
+  date_column   text NOT NULL DEFAULT 'created_at',
+  tenant_column text NOT NULL DEFAULT 'tenant_id',
+  description   text
+);
+
+ALTER TABLE public.plg_analytics_read_models ENABLE ROW LEVEL SECURITY;
+
+DROP POLICY IF EXISTS plg_analytics_read_models_read ON public.plg_analytics_read_models;
+CREATE POLICY plg_analytics_read_models_read ON public.plg_analytics_read_models
+  FOR SELECT TO authenticated USING (true);
+
+GRANT SELECT ON public.plg_analytics_read_models TO authenticated;
+GRANT ALL    ON public.plg_analytics_read_models TO service_role;
+
+-- ----------------------------------------------------------------------------
+-- 7. Identifier guard. Every column name from the client passes through here
+--    before it can reach a statement. Raises rather than returning false so a
+--    typo in a card definition fails loudly at the call instead of silently
+--    dropping a dimension and returning a wrong-shaped answer.
+-- ----------------------------------------------------------------------------
+CREATE OR REPLACE FUNCTION public.analytics_assert_column(p_source text, p_column text)
+RETURNS text
+LANGUAGE plpgsql
+STABLE
+AS $$
+BEGIN
+  IF p_column IS NULL OR p_column !~ '^[a-z_][a-z0-9_]*$' THEN
+    RAISE EXCEPTION 'analytics: malformed column name %', p_column USING ERRCODE = '22023';
+  END IF;
+
+  IF NOT EXISTS (
+    SELECT 1 FROM information_schema.columns
+    WHERE table_schema = 'public' AND table_name = p_source AND column_name = p_column
+  ) THEN
+    RAISE EXCEPTION 'analytics: column % does not exist on %', p_column, p_source USING ERRCODE = '42703';
+  END IF;
+
+  RETURN p_column;
+END;
+$$;
+
+-- ----------------------------------------------------------------------------
+-- 8. analytics_run — the whole engine.
+--
+--    p_dimensions  [{"key":"created_at","grain":"day"}, {"key":"product_name"}]
+--    p_measures    [{"key":"net_sales","agg":"sum","column":"net_sales"}]
+--    p_filters     {"financial_status":"paid","category_id":["uuid","uuid"]}
+--
+--    Returns {"rows":[...], "total":n, "summary":{...}} where `summary` is the
+--    same measures rolled up over the WHOLE range with no group-by. The summary
+--    is what a KPI card reads and what a report's total row shows — computed
+--    once, from the same filters, so they cannot disagree.
+--
+--    SECURITY INVOKER (the default, stated for the reader): RLS on the base
+--    tables decides visibility; the tenant predicate below is belt and braces.
+-- ----------------------------------------------------------------------------
+CREATE OR REPLACE FUNCTION public.analytics_run(
+  p_source     text,
+  p_tenant_id  uuid    DEFAULT NULL,
+  p_from       timestamptz DEFAULT NULL,
+  p_to         timestamptz DEFAULT NULL,
+  p_dimensions jsonb   DEFAULT '[]'::jsonb,
+  p_measures   jsonb   DEFAULT '[]'::jsonb,
+  p_filters    jsonb   DEFAULT '{}'::jsonb,
+  p_search     text    DEFAULT NULL,
+  p_search_columns text[] DEFAULT NULL,
+  p_sort       text    DEFAULT NULL,
+  p_dir        text    DEFAULT 'desc',
+  p_limit      int     DEFAULT 500,
+  p_offset     int     DEFAULT 0
+)
+RETURNS jsonb
+LANGUAGE plpgsql
+STABLE
+AS $$
+DECLARE
+  v_model      public.plg_analytics_read_models%ROWTYPE;
+  v_where      text[] := ARRAY[]::text[];
+  v_where_sql  text;
+  v_select     text[] := ARRAY[]::text[];
+  v_group      text[] := ARRAY[]::text[];
+  v_agg_only   text[] := ARRAY[]::text[];
+  v_dim        jsonb;
+  v_meas       jsonb;
+  v_key        text;
+  v_col        text;
+  v_grain      text;
+  v_agg        text;
+  v_expr       text;
+  v_filter_key text;
+  v_filter_val jsonb;
+  v_search_ors text[] := ARRAY[]::text[];
+  v_sort_sql   text := '';
+  v_rows       jsonb;
+  v_summary    jsonb;
+  v_total      bigint;
+  v_limit      int := LEAST(GREATEST(COALESCE(p_limit, 500), 1), 5000);
+  v_offset     int := GREATEST(COALESCE(p_offset, 0), 0);
+BEGIN
+  -- 8.1 The source must be registered. Not "look like a read model" — registered.
+  SELECT * INTO v_model FROM public.plg_analytics_read_models WHERE name = p_source;
+  IF NOT FOUND THEN
+    RAISE EXCEPTION 'analytics: % is not a registered read model', p_source USING ERRCODE = '42P01';
+  END IF;
+
+  -- 8.2 Tenant + date window. The date column comes from the registry, so a
+  --     caller cannot redirect the range onto some other timestamp.
+  IF p_tenant_id IS NOT NULL THEN
+    v_where := v_where || format('%I = %L', v_model.tenant_column, p_tenant_id);
+  END IF;
+  IF p_from IS NOT NULL THEN
+    v_where := v_where || format('%I >= %L', v_model.date_column, p_from);
+  END IF;
+  IF p_to IS NOT NULL THEN
+    v_where := v_where || format('%I <= %L', v_model.date_column, p_to);
+  END IF;
+
+  -- 8.3 Equality / IN filters.
+  FOR v_filter_key, v_filter_val IN SELECT key, value FROM jsonb_each(COALESCE(p_filters, '{}'::jsonb))
+  LOOP
+    CONTINUE WHEN v_filter_val IS NULL OR jsonb_typeof(v_filter_val) = 'null';
+    v_col := public.analytics_assert_column(p_source, v_filter_key);
+
+    IF jsonb_typeof(v_filter_val) = 'array' THEN
+      CONTINUE WHEN jsonb_array_length(v_filter_val) = 0;
+      v_where := v_where || format(
+        '%I::text = ANY (SELECT jsonb_array_elements_text(%L::jsonb))', v_col, v_filter_val);
+    ELSE
+      v_where := v_where || format('%I::text = %L', v_col, v_filter_val #>> '{}');
+    END IF;
+  END LOOP;
+
+  -- 8.4 Free-text search across the caller's declared text columns.
+  IF p_search IS NOT NULL AND length(btrim(p_search)) > 0 AND p_search_columns IS NOT NULL THEN
+    FOREACH v_col IN ARRAY p_search_columns LOOP
+      v_col := public.analytics_assert_column(p_source, v_col);
+      v_search_ors := v_search_ors || format('%I::text ILIKE %L', v_col, '%' || btrim(p_search) || '%');
+    END LOOP;
+    IF array_length(v_search_ors, 1) > 0 THEN
+      v_where := v_where || ('(' || array_to_string(v_search_ors, ' OR ') || ')');
+    END IF;
+  END IF;
+
+  v_where_sql := CASE WHEN array_length(v_where, 1) > 0
+                      THEN ' WHERE ' || array_to_string(v_where, ' AND ')
+                      ELSE '' END;
+
+  -- 8.5 Dimensions. A grain turns a timestamp into a bucket; without one the
+  --     raw column value is the group.
+  FOR v_dim IN SELECT * FROM jsonb_array_elements(COALESCE(p_dimensions, '[]'::jsonb))
+  LOOP
+    v_key   := v_dim ->> 'key';
+    v_col   := public.analytics_assert_column(p_source, v_key);
+    v_grain := v_dim ->> 'grain';
+
+    IF v_grain IS NULL THEN
+      v_expr := format('%I', v_col);
+    ELSIF v_grain IN ('hour','day','week','month','quarter','year') THEN
+      v_expr := format('date_trunc(%L, %I)', v_grain, v_col);
+    ELSE
+      RAISE EXCEPTION 'analytics: unsupported time grain %', v_grain USING ERRCODE = '22023';
+    END IF;
+
+    v_select := v_select || format('%s AS %I', v_expr, v_key);
+    v_group  := v_group  || v_expr;
+  END LOOP;
+
+  -- 8.6 Measures. Fixed aggregate vocabulary — anything else is rejected rather
+  --     than passed through, which is the difference between a parameter and an
+  --     injection point. 'ratio' is deliberately absent: it is derived on the
+  --     client from two real measures so ratio-of-sums never degrades into
+  --     avg-of-ratios.
+  FOR v_meas IN SELECT * FROM jsonb_array_elements(COALESCE(p_measures, '[]'::jsonb))
+  LOOP
+    v_key := v_meas ->> 'key';
+    IF v_key IS NULL OR v_key !~ '^[a-z_][a-z0-9_]*$' THEN
+      RAISE EXCEPTION 'analytics: malformed measure key %', v_key USING ERRCODE = '22023';
+    END IF;
+    v_agg := lower(COALESCE(v_meas ->> 'agg', 'sum'));
+
+    IF v_agg = 'count' THEN
+      v_expr := 'count(*)';
+    ELSE
+      v_col := public.analytics_assert_column(p_source, COALESCE(v_meas ->> 'column', v_key));
+      v_expr := CASE v_agg
+        WHEN 'sum'            THEN format('sum(%I)', v_col)
+        WHEN 'avg'            THEN format('avg(%I)', v_col)
+        WHEN 'min'            THEN format('min(%I)', v_col)
+        WHEN 'max'            THEN format('max(%I)', v_col)
+        WHEN 'count_distinct' THEN format('count(DISTINCT %I)', v_col)
+        ELSE NULL
+      END;
+      IF v_expr IS NULL THEN
+        RAISE EXCEPTION 'analytics: unsupported aggregate %', v_agg USING ERRCODE = '22023';
+      END IF;
+    END IF;
+
+    v_select   := v_select   || format('%s AS %I', v_expr, v_key);
+    v_agg_only := v_agg_only || format('%s AS %I', v_expr, v_key);
+  END LOOP;
+
+  -- 8.7 No measures ⇒ a raw detail listing (the classic tabular report).
+  IF array_length(v_agg_only, 1) IS NULL AND array_length(v_group, 1) IS NULL THEN
+    v_select := ARRAY['*'];
+  END IF;
+
+  -- 8.8 Sort. Must be one of the things actually selected — an alias, not an
+  --     arbitrary expression.
+  IF p_sort IS NOT NULL AND p_sort ~ '^[a-z_][a-z0-9_]*$' THEN
+    IF EXISTS (SELECT 1 FROM jsonb_array_elements(COALESCE(p_measures,'[]'::jsonb)) m WHERE m->>'key' = p_sort)
+       OR EXISTS (SELECT 1 FROM jsonb_array_elements(COALESCE(p_dimensions,'[]'::jsonb)) d WHERE d->>'key' = p_sort)
+       OR (array_length(v_agg_only,1) IS NULL AND array_length(v_group,1) IS NULL)
+    THEN
+      IF array_length(v_agg_only,1) IS NULL AND array_length(v_group,1) IS NULL THEN
+        PERFORM public.analytics_assert_column(p_source, p_sort);
+      END IF;
+      v_sort_sql := format(' ORDER BY %I %s NULLS LAST',
+                           p_sort,
+                           CASE WHEN lower(COALESCE(p_dir,'desc')) = 'asc' THEN 'ASC' ELSE 'DESC' END);
+    END IF;
+  END IF;
+
+  -- 8.9 Page of rows.
+  EXECUTE format(
+    'SELECT COALESCE(jsonb_agg(t), ''[]''::jsonb) FROM (SELECT %s FROM public.%I%s%s%s LIMIT %s OFFSET %s) t',
+    array_to_string(v_select, ', '),
+    p_source,
+    v_where_sql,
+    CASE WHEN array_length(v_group, 1) > 0
+         THEN ' GROUP BY ' || array_to_string(v_group, ', ') ELSE '' END,
+    v_sort_sql,
+    v_limit,
+    v_offset
+  ) INTO v_rows;
+
+  -- 8.10 Row count for pagination. This must count what the MAIN query returns,
+  --      not what it reads: grouping ⇒ number of groups; aggregating with no
+  --      dimensions ⇒ exactly one row, however many rows fed it; otherwise the
+  --      underlying rows. Counting reads here made a 1-row KPI claim two pages.
+  IF array_length(v_group, 1) > 0 THEN
+    EXECUTE format(
+      'SELECT count(*) FROM (SELECT %s FROM public.%I%s GROUP BY %s) c',
+      array_to_string(v_group, ', '), p_source, v_where_sql, array_to_string(v_group, ', ')
+    ) INTO v_total;
+  ELSIF array_length(v_agg_only, 1) > 0 THEN
+    v_total := 1;
+  ELSE
+    EXECUTE format('SELECT count(*) FROM public.%I%s', p_source, v_where_sql) INTO v_total;
+  END IF;
+
+  -- 8.11 The summary: identical filters, identical measures, no group-by. This
+  --      is the KPI headline AND the report's total row — one number, one place.
+  IF array_length(v_agg_only, 1) > 0 THEN
+    EXECUTE format(
+      'SELECT to_jsonb(s) FROM (SELECT %s FROM public.%I%s) s',
+      array_to_string(v_agg_only, ', '),
+      p_source,
+      v_where_sql
+    ) INTO v_summary;
+  END IF;
+
+  RETURN jsonb_build_object(
+    'rows',    COALESCE(v_rows, '[]'::jsonb),
+    'total',   COALESCE(v_total, 0),
+    'summary', COALESCE(v_summary, '{}'::jsonb)
+  );
+END;
+$$;
+
+REVOKE ALL ON FUNCTION public.analytics_run(text, uuid, timestamptz, timestamptz, jsonb, jsonb, jsonb, text, text[], text, text, int, int) FROM public;
+GRANT EXECUTE ON FUNCTION public.analytics_run(text, uuid, timestamptz, timestamptz, jsonb, jsonb, jsonb, text, text[], text, text, int, int) TO authenticated, service_role;
+
+REVOKE ALL ON FUNCTION public.analytics_assert_column(text, text) FROM public;
+GRANT EXECUTE ON FUNCTION public.analytics_assert_column(text, text) TO authenticated, service_role;

package/package.json

@@ -3,7 +3,7 @@
   "fayz": {
     "status": "beta"
   },
-  "version": "0.9.0-next.1",
+  "version": "0.10.0",
   "description": "Fayz SDK database layer — Drizzle schema primitives, spine references, and migration helpers shared across plugins.",
   "type": "module",
   "sideEffects": false,
@@ -12,7 +12,6 @@
   "types": "./dist/index.d.ts",
   "exports": {
     ".": {
-      "source": "./src/index.ts",
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js",
       "require": "./dist/index.cjs"
@@ -20,7 +19,6 @@
   },
   "files": [
     "dist",
-    "src",
     "migrations"
   ],
   "dependencies": {

package/dist/helpers.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"helpers.d.ts","sourceRoot":"","sources":["../src/helpers.ts"],"names":[],"mappings":"AAGA;;;;GAIG;AACH,eAAO,MAAM,QAAQ,sGAGqC,CAAA;AAE1D,mFAAmF;AACnF,eAAO,MAAM,UAAU;;;CAGtB,CAAA;AAED,gEAAgE;AAChE,eAAO,MAAM,SAAS;;CAErB,CAAA"}

package/src/helpers.ts

@@ -1,23 +0,0 @@
-import { uuid, timestamp } from 'drizzle-orm/pg-core'
-import { tenants } from './schema/spine'
-
-/**
- * Canonical tenant-scoping column: `tenant_id uuid NOT NULL REFERENCES
- * public.tenants(id) ON DELETE CASCADE`. Every Ring-1 plugin table uses this
- * so tenancy is identical everywhere (and RLS can assume the column exists).
- */
-export const tenantId = () =>
-  uuid('tenant_id')
-    .notNull()
-    .references(() => tenants.id, { onDelete: 'cascade' })
-
-/** Standard `created_at` / `updated_at` timestamptz pair with `now()` defaults. */
-export const timestamps = {
-  createdAt: timestamp('created_at', { withTimezone: true }).notNull().defaultNow(),
-  updatedAt: timestamp('updated_at', { withTimezone: true }).notNull().defaultNow(),
-}
-
-/** Just `created_at` (for append-only / event-style tables). */
-export const createdAt = {
-  createdAt: timestamp('created_at', { withTimezone: true }).notNull().defaultNow(),
-}

package/src/index.ts

@@ -1,12 +0,0 @@
-// @fayz-ai/db — shared Drizzle schema layer for the Fayz SDK.
-//
-// Re-exports the spine references (Ring 0) and the column helpers that plugin
-// schemas compose with. Plugins import from here; apps compose plugin schemas
-// in their own drizzle.config.
-// Re-export the Drizzle pg-core builders so apps import them from @fayz-ai/db
-// (one drizzle-orm instance everywhere — avoids dual-copy PgColumn type clashes
-// when an app composes its own tables with @fayz-ai/db spine refs + plugin schema).
-export * from 'drizzle-orm/pg-core'
-
-export { tenants, people, orders, appointments, products, orderItems } from './schema/spine'
-export { tenantId, timestamps, createdAt } from './helpers'

package/src/schema/spine.ts

@@ -1,35 +0,0 @@
-import { pgTable, uuid } from 'drizzle-orm/pg-core'
-
-/**
- * Ring 0 — the core spine, declared as Drizzle *references* only.
- *
- * These tables are owned by the platform (@fayz-ai/saas core) and already exist
- * in every provisioned pool, directly in the `public` schema (industry-pool
- * model — no saas_core schema). We declare a minimal shape here purely so plugin
- * tables can express real foreign keys in TypeScript. They land in the Drizzle
- * *baseline* snapshot (never re-created), so only the `id` FK target is needed —
- * the live columns are authoritative.
- */
-export const tenants = pgTable('tenants', {
-  id: uuid('id').primaryKey(),
-})
-
-export const people = pgTable('people', {
-  id: uuid('id').primaryKey(),
-})
-
-export const orders = pgTable('orders', {
-  id: uuid('id').primaryKey(),
-})
-
-export const appointments = pgTable('appointments', {
-  id: uuid('id').primaryKey(),
-})
-
-export const products = pgTable('products', {
-  id: uuid('id').primaryKey(),
-})
-
-export const orderItems = pgTable('order_items', {
-  id: uuid('id').primaryKey(),
-})