@nextsparkjs/ai-workflow 0.1.0-beta.166 → 0.1.0-beta.168

package/claude/skills/entity-system/scripts/generate-migration.py

@@ -56,10 +56,11 @@ FIELD_TYPE_MAP = {
     'select': 'VARCHAR(100)',
     'multiselect': 'TEXT[]',
     'tags': 'TEXT[]',
-    'relation': 'UUID',
-    'relation-multi': 'UUID[]',
-    'reference': 'UUID',
-    'user': 'UUID',
+    # FKs are TEXT: NextSpark ids are TEXT (Better Auth + gen_random_uuid()::text), not UUID
+    'relation': 'TEXT',
+    'relation-multi': 'TEXT[]',
+    'reference': 'TEXT',
+    'user': 'TEXT',
     'phone': 'VARCHAR(50)',
     'rating': 'INTEGER',
     'range': 'DECIMAL',
@@ -124,16 +125,19 @@ def parse_fields_file(fields_path: Path) -> List[Dict]:
 
 def generate_column_sql(field: Dict) -> str:
     """Generate SQL column definition from field."""
-    name = to_snake_case(field['name'])
+    # NextSpark column names are camelCase (e.g. "firstName"), even though table
+    # names are snake_case (e.g. "team_members"). Field names from config may be
+    # camelCase already (no-op) or kebab-case (converted).
+    name = to_camel_case(field['name'])
     field_type = field['type']
     required = field['required']
 
     sql_type = FIELD_TYPE_MAP.get(field_type, 'TEXT')
 
-    # Handle select fields with CHECK constraint
+    # Handle select fields with CHECK constraint (quote the camelCase column)
     if field_type == 'select' and 'options' in field:
         options = ', '.join(f"'{v}'" for v in field['options'])
-        sql_type = f"VARCHAR(100) CHECK ({name} IN ({options}))"
+        sql_type = f'VARCHAR(100) CHECK ("{name}" IN ({options}))'
 
     nullable = '' if required else ''
     not_null = ' NOT NULL' if required else ''
@@ -146,10 +150,10 @@ def generate_table_migration(entity_slug: str, fields: List[Dict], options: Dict
     table_name = to_snake_case(entity_slug)
     timestamp = datetime.now().isoformat()
 
-    # Build column definitions
+    # Build column definitions (NextSpark: TEXT ids, camelCase columns, "users" table)
     columns = [
-        '  "id" UUID PRIMARY KEY DEFAULT gen_random_uuid()',
-        '  "user_id" UUID NOT NULL REFERENCES "user"(id) ON DELETE CASCADE',
+        '  "id" TEXT PRIMARY KEY DEFAULT gen_random_uuid()::text',
+        '  "userId" TEXT NOT NULL REFERENCES "users"(id) ON DELETE CASCADE',
     ]
 
     for field in fields:
@@ -157,15 +161,15 @@ def generate_table_migration(entity_slug: str, fields: List[Dict], options: Dict
 
     # Timestamps
     columns.extend([
-        '  "created_at" TIMESTAMPTZ NOT NULL DEFAULT CURRENT_TIMESTAMP',
-        '  "updated_at" TIMESTAMPTZ NOT NULL DEFAULT CURRENT_TIMESTAMP',
+        '  "createdAt" TIMESTAMPTZ NOT NULL DEFAULT now()',
+        '  "updatedAt" TIMESTAMPTZ NOT NULL DEFAULT now()',
     ])
 
     # Soft delete
     if options.get('soft_delete'):
         columns.extend([
-            '  "deleted_at" TIMESTAMPTZ',
-            '  "deleted_by" UUID REFERENCES "user"(id)',
+            '  "deletedAt" TIMESTAMPTZ',
+            '  "deletedBy" TEXT REFERENCES "users"(id)',
         ])
 
     # Build SQL
@@ -186,19 +190,19 @@ CREATE TABLE "{table_name}" (
     if options.get('with_indexes', True):
         sql += f'''
 -- Indexes
-CREATE INDEX "idx_{table_name}_user_id" ON "{table_name}" ("user_id");
-CREATE INDEX "idx_{table_name}_created_at" ON "{table_name}" ("created_at" DESC);
+CREATE INDEX "idx_{table_name}_userId" ON "{table_name}" ("userId");
+CREATE INDEX "idx_{table_name}_createdAt" ON "{table_name}" ("createdAt" DESC);
 '''
-        # Add indexes for searchable/sortable fields
+        # Add indexes for searchable/sortable fields (camelCase column names)
         for field in fields:
-            name = to_snake_case(field['name'])
+            name = to_camel_case(field['name'])
             if field['type'] in ['text', 'textarea']:
-                sql += f'CREATE INDEX "idx_{table_name}_{name}_search" ON "{table_name}" USING gin(to_tsvector(\'english\', {name}));\n'
+                sql += f'CREATE INDEX "idx_{table_name}_{name}_search" ON "{table_name}" USING gin(to_tsvector(\'english\', "{name}"));\n'
             elif field['type'] == 'select':
                 sql += f'CREATE INDEX "idx_{table_name}_{name}" ON "{table_name}" ("{name}");\n'
 
         if options.get('soft_delete'):
-            sql += f'CREATE INDEX "idx_{table_name}_deleted_at" ON "{table_name}" ("deleted_at");\n'
+            sql += f'CREATE INDEX "idx_{table_name}_deletedAt" ON "{table_name}" ("deletedAt");\n'
 
     # RLS
     if options.get('with_rls', True):
@@ -206,22 +210,21 @@ CREATE INDEX "idx_{table_name}_created_at" ON "{table_name}" ("created_at" DESC)
 -- Enable Row Level Security
 ALTER TABLE "{table_name}" ENABLE ROW LEVEL SECURITY;
 
--- RLS Policies
+-- RLS Policies (NextSpark model: app.user_id GUC via public.get_auth_user_id();
+-- bypass tier via public.can_bypass_rls(). System ops run on the SERVICE connection
+-- which bypasses RLS by credential — no `TO service_role` policy is needed.)
 CREATE POLICY "{table_name}_owner_access" ON "{table_name}"
-  FOR ALL
-  USING (auth.uid() = user_id);
-
-CREATE POLICY "{table_name}_service_role_access" ON "{table_name}"
-  FOR ALL TO service_role
-  USING (TRUE);
+  FOR ALL TO authenticated
+  USING (public.can_bypass_rls() OR "userId" = public.get_auth_user_id())
+  WITH CHECK (public.can_bypass_rls() OR "userId" = public.get_auth_user_id());
 '''
 
     sql += f'''
--- Trigger for updated_at
-CREATE TRIGGER update_{table_name}_updated_at
+-- Trigger for updatedAt (uses the core helper public.set_updated_at from migration 001)
+CREATE TRIGGER {table_name}_set_updated_at
   BEFORE UPDATE ON "{table_name}"
   FOR EACH ROW
-  EXECUTE FUNCTION update_updated_at_column();
+  EXECUTE FUNCTION public.set_updated_at();
 
 COMMIT;
 
@@ -246,45 +249,52 @@ def generate_metas_migration(entity_slug: str) -> str:
 -- Up Migration
 BEGIN;
 
--- Create {table_name}_metas table
+-- Create {table_name}_metas table (NextSpark meta convention: TEXT ids, camelCase,
+-- entityId / metaKey / metaValue / isPublic)
 CREATE TABLE "{table_name}_metas" (
-  "id" UUID PRIMARY KEY DEFAULT gen_random_uuid(),
-  "entity_id" UUID NOT NULL REFERENCES "{table_name}"(id) ON DELETE CASCADE,
-  "key" VARCHAR(255) NOT NULL,
-  "value" JSONB,
-  "created_at" TIMESTAMPTZ NOT NULL DEFAULT CURRENT_TIMESTAMP,
-  "updated_at" TIMESTAMPTZ NOT NULL DEFAULT CURRENT_TIMESTAMP,
-  UNIQUE("entity_id", "key")
+  "id" TEXT PRIMARY KEY DEFAULT gen_random_uuid()::text,
+  "entityId" TEXT NOT NULL REFERENCES "{table_name}"(id) ON DELETE CASCADE,
+  "metaKey" VARCHAR(255) NOT NULL,
+  "metaValue" JSONB,
+  "isPublic" BOOLEAN NOT NULL DEFAULT false,
+  "createdAt" TIMESTAMPTZ NOT NULL DEFAULT now(),
+  "updatedAt" TIMESTAMPTZ NOT NULL DEFAULT now(),
+  UNIQUE("entityId", "metaKey")
 );
 
 -- Indexes
-CREATE INDEX "idx_{table_name}_metas_entity_id" ON "{table_name}_metas" ("entity_id");
-CREATE INDEX "idx_{table_name}_metas_key" ON "{table_name}_metas" ("key");
-CREATE INDEX "idx_{table_name}_metas_value" ON "{table_name}_metas" USING gin("value");
+CREATE INDEX "idx_{table_name}_metas_entityId" ON "{table_name}_metas" ("entityId");
+CREATE INDEX "idx_{table_name}_metas_metaKey" ON "{table_name}_metas" ("metaKey");
+CREATE INDEX "idx_{table_name}_metas_metaValue" ON "{table_name}_metas" USING gin("metaValue");
 
 -- Enable Row Level Security
 ALTER TABLE "{table_name}_metas" ENABLE ROW LEVEL SECURITY;
 
--- RLS Policies
+-- RLS Policies (access inherited from the parent row's ownership; public metas readable)
 CREATE POLICY "{table_name}_metas_owner_access" ON "{table_name}_metas"
-  FOR ALL
+  FOR ALL TO authenticated
   USING (
-    EXISTS (
-      SELECT 1 FROM "{table_name}"
-      WHERE "{table_name}".id = entity_id
-      AND "{table_name}".user_id = auth.uid()
+    public.can_bypass_rls()
+    OR EXISTS (
+      SELECT 1 FROM "{table_name}" p
+      WHERE p.id = "{table_name}_metas"."entityId"
+        AND p."userId" = public.get_auth_user_id()
+    )
+  )
+  WITH CHECK (
+    public.can_bypass_rls()
+    OR EXISTS (
+      SELECT 1 FROM "{table_name}" p
+      WHERE p.id = "{table_name}_metas"."entityId"
+        AND p."userId" = public.get_auth_user_id()
     )
   );
 
-CREATE POLICY "{table_name}_metas_service_role_access" ON "{table_name}_metas"
-  FOR ALL TO service_role
-  USING (TRUE);
-
--- Trigger for updated_at
-CREATE TRIGGER update_{table_name}_metas_updated_at
+-- Trigger for updatedAt (uses the core helper public.set_updated_at from migration 001)
+CREATE TRIGGER {table_name}_metas_set_updated_at
   BEFORE UPDATE ON "{table_name}_metas"
   FOR EACH ROW
-  EXECUTE FUNCTION update_updated_at_column();
+  EXECUTE FUNCTION public.set_updated_at();
 
 COMMIT;
 

package/claude/skills/nextjs-api-development/SKILL.md

@@ -5,7 +5,7 @@ description: |
   Dual authentication (API Key + Session), dynamic entities, metadata system.
   Use this skill to create endpoints, validate APIs, or understand API patterns.
 allowed-tools: Read, Glob, Grep, Bash(python:*)
-version: 1.1.0
+version: 1.2.0
 ---
 
 # Next.js API Development Skill
@@ -311,6 +311,11 @@ describe('Products API - CRUD Operations', {
 
 ### SQL Injection Prevention
 
+> **RLS routing (beta.167):** `queryWithRLS(..., userId)` runs on the app pool (RLS evaluated).
+> The bare `query()`/`queryOne()` family routes to the **service pool (bypass)** — never use it
+> for a user-scoped read. See the **rls-enforcement** skill for the service-pool model and the
+> LIST/READ fail-closed enforcement now applied in the generic handler.
+
 ```typescript
 // ✅ CORRECT - Parameterized queries with queryWithRLS
 const result = await queryWithRLS(

package/claude/skills/permissions-system/SKILL.md

@@ -2,10 +2,12 @@
 name: permissions-system
 description: |
   Three-layer permission system (Team Roles + Plans + Quotas) for this Next.js application.
-  Covers user roles, team roles, theme extensions, permission checking, and RLS integration.
+  Covers user roles, team roles (stored as TEXT), theme role extensions, permission checking,
+  and LIST/READ fail-closed enforcement at the entity handler.
   Use this skill when implementing or modifying access control features.
+  For the runtime RLS model (service pool, nextspark_app cutover) see rls-enforcement.
 allowed-tools: Read, Glob, Grep
-version: 1.0.0
+version: 1.1.0
 ---
 
 # Permissions System Skill
@@ -553,6 +555,13 @@ const customers = await queryWithRLS(
 )
 ```
 
+**Enforcement at the entity handler (beta.167):** the generic handler now checks the session
+permission on **LIST and READ** too (previously only create/update/delete) — a member without
+`entity.list`/`entity.read` gets **403**. A permission check that **throws** returns
+`500 PERMISSION_CHECK_FAILED` (**fail-closed**, never "allow"). Themes must declare `list`/`read`
+per entity (`default`/`starter` already do). Note `team_role` is stored as **TEXT** (themes add
+roles via config, not `ALTER TYPE`). For the runtime RLS model see the **rls-enforcement** skill.
+
 ## Build-Time Registry
 
 ```typescript

package/claude/skills/rls-enforcement/SKILL.md

@@ -0,0 +1,192 @@
+---
+name: rls-enforcement
+description: |
+  Operating Row-Level Security at RUNTIME: the two-pool service-context model
+  (DATABASE_SERVICE_URL bypass vs the app pool), the non-owner runtime role (nextspark_app)
+  and cutover, MIGRATE_DATABASE_URL, fail-closed LIST/READ enforcement, and ownershipFilter.
+  Use this WHENEVER a DB call mysteriously returns 0 rows (or too many) for some users, a
+  query/insert started failing after switching DATABASE_URL, a webhook / scheduled-action /
+  login path hits a Postgres permission error, you're choosing between the app pool and the
+  service (bypass) pool, or composing a transaction that mixes user-scoped and system writes —
+  even if the words "RLS" or "cutover" never appear. Also for forcing the service pool
+  (team/subscription bootstrap), doing/debugging the cutover, and extending core RLS policies
+  from a theme. For policy SQL see database-migrations; for queryWithRLS usage see
+  service-layer; for can_bypass_rls/superadmin see api-bypass-layers.
+allowed-tools: Read, Glob, Grep
+version: 1.1.0
+---
+
+# RLS Enforcement Layer Skill
+
+**Canonical reference (read for SQL + cutover runbook):**
+`packages/core/docs/10-backend/03-rls-policies.md` → "Enforcement Layer (beta.167+)".
+This skill is the agent-facing companion: the operational rules and gotchas, not a
+re-paste of the SQL.
+
+## When to use this skill
+
+- Adding/auditing a DB call and deciding **app pool (RLS) vs service pool (bypass)**.
+- Anything that writes the **first** team membership/subscription (bootstrap).
+- Doing or debugging the **RLS cutover** (`nextspark_app`, `DATABASE_SERVICE_URL`, `MIGRATE_DATABASE_URL`).
+- A theme that needs to **override a core RLS policy** (e.g. widen a tier on `users`/`subscriptions`).
+- Touching `generic-handler.ts` permission checks or `ownershipFilter`.
+
+## 1. Two pools, routed by presence of `userId` (`src/lib/db.ts`)
+
+| Helper | With `userId` | Without `userId` |
+|---|---|---|
+| `queryWithRLS` / `queryOneWithRLS` / `mutateWithRLS` / `getTransactionClient` | **app pool** (`SET LOCAL app.user_id`, RLS evaluated) | **service pool** (bypass) |
+
+- **`query` / `queryOne` / `queryRows` ALWAYS go to the service pool (bypass).** They are
+  system operations by definition. **Never** use them for a user-scoped read that must be
+  RLS-filtered — use `queryWithRLS(sql, params, userId)`.
+- **Force service even with a `userId`:** `mutateWithRLS(sql, params, userId, { service: true })`
+  or `getServiceTransactionClient()`.
+- `DATABASE_SERVICE_URL` falls back to `DATABASE_URL` when unset → pre-cutover behavior is
+  unchanged (the app still connects as owner; nothing breaks).
+- **A transaction is bound to ONE pool + ONE GUC at acquisition.** `getTransactionClient(userId)`
+  / `getServiceTransactionClient()` acquire a single client up front; every `tx.query/.mutate`
+  runs on that pool. You **cannot** do a user-scoped RLS read and a service-pool bootstrap write
+  in the *same* `tx`. If a flow needs both, run the bootstrap as a service transaction and do
+  the RLS reads/writes as separate `queryWithRLS(..., userId)` calls (or sequence them: commit
+  the membership first, then the user-scoped write can satisfy RLS).
+- **Atomicity:** `mutateWithRLS` wraps **each call** in its own BEGIN/COMMIT — N calls = N
+  transactions. For "insert order + 3 items atomically", use `getTransactionClient(userId)`
+  (one GUC, one commit/rollback), not N `mutateWithRLS` calls.
+
+## 2. When you MUST force the service pool
+
+Bootstrap writes that create the **first** membership/subscription of a team can't pass the
+membership-based RLS insert policies under the new member's own GUC (they aren't a member
+yet). These run on the **service pool**, authorized at the API/action layer (not RLS):
+
+- `TeamService.create`, `teams/actions.ts:createTeam`, `addUserToGlobalTeam`,
+  `TeamMemberService.add` (via `{ service: true }`).
+
+If you add a new "first-membership" writer, route it the same way or it will break under RLS.
+
+**Other legitimate service-pool actors** (no request user → service pool by routing, since they
+call with no `userId`): Better Auth login/verification, the **scheduled-actions processor**,
+**payment-provider webhooks**, the superadmin/developer bypass check. Inside such a system path,
+any *user-scoped* sub-operation must re-introduce the resolved userId via
+`queryWithRLS(..., userId)` so RLS applies for that slice.
+
+> ⚠️ **The inverse is a security hole.** Force the service pool **only** for work that
+> *structurally* cannot satisfy RLS (first-membership/subscription, pre-login auth, webhooks/
+> scheduler with no user). **Never** add `{ service: true }` to a normal user-scoped read/write
+> to "fix" a 0-rows or permission-denied bug — that silently disables tenant isolation and leaks
+> cross-tenant data. A 0-rows bug means a missing policy / missing `userId` / missing
+> `entity.list` permission — fix *that*, don't bypass RLS.
+
+## 3. Runtime role + cutover gotcha
+
+- Migration `022_rls_runtime_roles.sql` creates `nextspark_app` (non-owner, member of
+  `authenticated`, **no** `BYPASSRLS`) + grants + `anon` lockdown.
+- **Migrations run as the OWNER** via `MIGRATE_DATABASE_URL` (falls back to `DATABASE_URL`);
+  the runtime runs as `nextspark_app`.
+- **GOTCHA:** post-cutover `DATABASE_URL` is a **non-owner** role — any op that assumed owner
+  (raw DDL, seeds, `query()` expecting full access) behaves differently. Keep owner work on
+  the migrate/service connection.
+- Cutover is **opt-in**: leave `DATABASE_SERVICE_URL` unset and nothing changes.
+
+## 4. Fail-closed permission enforcement (`generic-handler.ts`)
+
+- LIST and READ now check the session entity permission (was create/update/delete only).
+  A member without `entity.list`/`entity.read` → **403**. Admin-bypass and api-key (scope)
+  paths are skipped.
+- A **thrown error** in the permission check returns **`500 PERMISSION_CHECK_FAILED`**
+  (fail-closed) — never "allow". Themes must declare `list`/`read` per entity
+  (`default`/`starter` already do).
+- **api-key vs session — two different layers, two different behaviors:**
+  - The **entity-permission** check is session-only (api-key uses scopes), so it's *skipped* for api-key.
+  - But **DB RLS still applies to api-key** requests — api-key auth carries a `userId`, so reads
+    route to the app pool and policies evaluate (team isolation holds).
+  - **`ownershipFilter` (role-based row scoping) is OFF for api-key and admin-bypass**
+    (`resolveOwnershipFilter` returns `{applies:false}` for those). So an api-key caller is *not*
+    narrowed to "their own" rows by `ownershipFilter`; they see everything their team-RLS policy
+    allows. To restrict api-key callers, scope the key narrowly or enforce it in a DB RLS policy
+    (which fires for any app-pool request), not via `ownershipFilter`.
+
+## 5. `ownershipFilter` (entity `access` config, `entities/types.ts`)
+
+- `linkedBy` is **optional** → omit for **direct-field** ownership (entity row carries the
+  owner id; filtered against the current user).
+- `linkedBy.softDelete` makes the `deletedAt IS NULL` clause conditional — set `false` for
+  tables without a `deletedAt` column (avoids a 42703 undefined-column error).
+
+## Debugging & validating
+
+**"Returned 0 rows after the cutover" (worked before, member gets `[]`, superadmin still sees all).**
+RLS is now live. Triage in order:
+1. **403 vs `[]`?** A `403` = fail-closed permission (member lacks `entity.list`/`read`, or theme
+   didn't declare it). An empty `[]` (200) = permission passed but RLS filtered all rows. They
+   are different bugs.
+2. **Is a `userId` actually passed?** A missing `userId` routes to the service pool → would
+   *over*-return, not under-return. So `[]` means a `userId` *is* present and RLS is filtering.
+3. **Is `DATABASE_SERVICE_URL` set to a real bypass/owner role?** If unset, the "service" pool is
+   *also* `nextspark_app` (no bypass) → even system reads get filtered. Most common cutover
+   mistake. Set it.
+4. **Does a policy exist?** RLS-enabled **with no policy** blocks ALL rows. Confirm a policy
+   `TO authenticated` exists and `nextspark_app` is a member of `authenticated` (it is, per 022).
+5. **Reproduce as the runtime role** (below). If empty there too, it's the policy / membership /
+   `ownershipFilter`, not the app wiring.
+
+**Validate/test RLS as the real runtime role (not the owner — owner bypasses RLS, proving nothing).**
+`nextspark_app` is NOLOGIN, but `022` runs `GRANT nextspark_app TO current_user`, so the
+test/migrate user can assume it:
+```sql
+BEGIN;
+SET LOCAL ROLE nextspark_app;
+SET LOCAL app.user_id = '<teamA_member_id>';
+SELECT count(*) FROM "invoices" WHERE "teamId" = '<teamB_id>';  -- expect 0 (cross-tenant denied)
+COMMIT;
+```
+Always include a positive control (same query as a team-B member → > 0), or a `0` is meaningless.
+Seed fixtures via the service pool / owner (first-membership inserts can't satisfy RLS).
+
+## Non-obvious rules (do not relearn the hard way)
+
+- **RLS primitives live in migration `001`** (`can_bypass_rls`, `auth_user_can_see_user`,
+  `is_superadmin`) — because the hardened policies in `002` use them, and `002` runs before
+  the tables/functions a later migration would define. A policy with a forward dependency on
+  a later table fails at `CREATE POLICY` time; wrap such logic in a `SECURITY DEFINER` helper
+  defined in `001` (table refs resolve at call time). Cite `001`, not the stale `002:102`
+  comment that still says "010".
+- **`team_role` is `TEXT`** (not an ENUM). Themes add roles via config
+  (`availableTeamRoles` + `permissions.config.ts`) — **never** `ALTER TYPE team_role`.
+- **Theme override of a core RLS policy** runs in **phase 2** (after core). It must `DROP`
+  the core policy by name and recreate its own — dropping **both** the legacy AND the current
+  core policy names, or the policies **coexist** (RLS combines them with OR, loosening the
+  restriction). See campus `9035/9036` for the pattern.
+- **Don't break the metadata self-read policy** (`003_user_metas`): login reads the user's own
+  flags under RLS via `MetaService.getEntityMetas(..., userId)`.
+- **`anon` is not the app's public-read path.** Public reads enter with `userId=null` →
+  service pool (bypass), filtered in SQL by the handler. `TO anon` policies + the `022`
+  `anon` revoke are defense for the **Supabase Data API / PostgREST**, not app traffic.
+
+## Anti-patterns
+
+- ❌ Using bare `query()`/`queryOne()` for a user-scoped read that must be RLS-filtered (it
+  bypasses RLS via the service pool).
+- ❌ Adding a hardened policy that references `team_members`/`can_bypass_rls` to an **early**
+  migration (e.g. 002) without a helper in 001 → forward-dependency failure.
+- ❌ `ALTER TYPE team_role ADD VALUE ...` in a theme → the type no longer exists.
+- ❌ A theme override that drops only the legacy core policy names → coexisting policies.
+- ❌ Returning "allow" when a permission check throws → must be fail-closed.
+
+## Checklist (the cross-cutting ones the body's rules don't already make obvious)
+
+- [ ] DB call routing chosen deliberately: user-scoped → `queryWithRLS(..., userId)`; system → `query*`/no-userId; bootstrap-only → `{ service: true }`. **Not** `{ service: true }` to silence a 0-rows bug.
+- [ ] No transaction tries to mix a user-scoped (app-pool) op and a service-pool (bootstrap) op on the same `tx`.
+- [ ] Multi-row atomic write uses `getTransactionClient(userId)`, not N `mutateWithRLS` calls.
+- [ ] New core-table policy: primitive deps already defined in `001` before the migration that uses them.
+- [ ] New entity exposes `list`/`read` permissions (else 403 under enforcement); api-key callers restricted by scope or a DB policy (not `ownershipFilter`).
+- [ ] Theme RLS override drops legacy AND current core policy names.
+
+## Related skills
+
+- `database-migrations` — RLS policy SQL patterns, migration structure.
+- `service-layer` — `queryWithRLS`/`mutateWithRLS` usage and service classes.
+- `api-bypass-layers` — `can_bypass_rls()`, superadmin/developer bypass.
+- `permissions-system` — team roles, tiers, permission checks.
+- `scheduled-actions` — background/webhook handlers (service-pool actors with no request user).

package/claude/skills/rls-enforcement/evals/RESULTS.md

@@ -0,0 +1,24 @@
+# rls-enforcement — eval results
+
+Methodology: anthropics-skill-creator (autonomous loop; subagents with-skill vs baseline,
+graded against the per-case assertions in evals.json).
+
+## Iteration 1 — core cases (evals.json #0-4)
+With-skill completed runs: 4/4 PASS (3/3 assertions each). Baseline (no skill, repo access)
+also strong (the code + sibling skills are well-documented), so easy cases SATURATE — no
+headroom. Conclusion: measure the skill on HARDER composite/debugging scenarios.
+
+## Iteration 1b — harder gap cases (current skill, pre-improvement)
+gap1 tx-pool-binding: not covered by skill. gap2 0-rows: PASS (agent derived). gap3 api-key:
+PARTIAL 2/3 — agent explicitly hedged ("skill doesn't specify api-key routing"). gap4
+don't-over-service: PASS. gap8 test-as-nextspark_app: PASS (derived).
+
+## Improvements applied (deltas A-F + description)
+A tx bound to one pool+GUC / atomicity; B api-key vs session asymmetry; C "0 rows after cutover"
+triage + test-as-nextspark_app mechanics; D inverse footgun (don't over-service); E lean checklist;
+F webhooks/scheduler actors + related skill; sharper symptom-based description.
+
+## Iteration 2 — same gap cases (improved skill)
+5/5 PASS (15/15 assertions). gap1 now a precise PASS; gap3 PASS 3/3 with NO hedge (the
+skill-attributable win). Pass-rate on completed runs: ~87.5% -> 100%. Agents now cite the
+skill's encoded sections instead of deriving (lower reasoning burden / higher reliability).

package/claude/skills/rls-enforcement/evals/evals.json

@@ -0,0 +1,56 @@
+{
+  "skill_name": "rls-enforcement",
+  "notes": "Autonomous eval. Each case is a realistic NextSpark developer task whose CORRECT answer depends on knowledge in the rls-enforcement skill. We compare with-skill vs no-skill (baseline), grade against objective assertions, then improve and re-run to measure pass-rate delta.",
+  "evals": [
+    {
+      "id": 0,
+      "name": "bootstrap-service-pool",
+      "prompt": "In @nextsparkjs/core I'm adding a server action `createOrganization(userId, name)` that, in one DB transaction, inserts a new row in `teams` (ownerId = userId), inserts the creator's `team_members` row with role 'owner', and inserts a default `subscriptions` row for the team. The app will run with RLS enabled (DATABASE_URL connects as the non-owner role). Write the data-access code (which db.ts helper do you use and why).",
+      "assertions": [
+        {"text": "Uses the SERVICE pool (getServiceTransactionClient or { service: true } or a non-userId service path), NOT getTransactionClient(userId)/app pool"},
+        {"text": "Explains the reason: it creates the FIRST team_members/subscription so it cannot satisfy the membership-based RLS insert policy under the user's own GUC"},
+        {"text": "Notes that authorization is enforced at the app/action layer, not by RLS, for this bootstrap"}
+      ]
+    },
+    {
+      "id": 1,
+      "name": "bare-query-bypass",
+      "prompt": "A teammate wrote this helper to list the current user's own invoices in @nextsparkjs/core:\n\nimport { query } from '@/core/lib/db'\nexport async function listMyInvoices(userId: string) {\n  return (await query('SELECT * FROM \"invoices\" WHERE \"userId\" = $1', [userId])).rows\n}\n\nUnder the RLS runtime, is this correct? If not, fix it and explain.",
+      "assertions": [
+        {"text": "Identifies that the bare query()/queryOne()/queryRows() family routes to the SERVICE pool and BYPASSES RLS"},
+        {"text": "Recommends queryWithRLS(sql, params, userId) so the query runs on the app pool with the GUC / RLS evaluated"},
+        {"text": "Frames it as a real risk (RLS not enforced) rather than a style nit"}
+      ]
+    },
+    {
+      "id": 2,
+      "name": "team-role-text-extension",
+      "prompt": "Our theme needs a new team role called 'reviewer'. How do I make it real so it can be stored in team_members.role and recognized by permission checks? Do I need a migration?",
+      "assertions": [
+        {"text": "States that team_role is TEXT (not a Postgres ENUM), so no ALTER TYPE / no DB migration is needed to add the value"},
+        {"text": "Says to declare the role via config (availableTeamRoles in app.config + permissions.config.ts)"},
+        {"text": "Explicitly warns against ALTER TYPE team_role ADD VALUE"}
+      ]
+    },
+    {
+      "id": 3,
+      "name": "policy-primitive-ordering",
+      "prompt": "I'm hardening the RLS policy on the `account` table by editing migration 002_auth_tables.sql to use `public.can_bypass_rls()`. On a fresh db:reset it fails with: ERROR: function public.can_bypass_rls() does not exist. Why, and how do I fix it without an incremental migration?",
+      "assertions": [
+        {"text": "Explains the cause: can_bypass_rls (and friends) must exist BEFORE migration 002 runs; defining them later (e.g. 010) is a forward dependency that fails at CREATE POLICY time"},
+        {"text": "Fix: define the primitive in migration 001 (the foundational functions) so 002 can use it"},
+        {"text": "Notes that a SECURITY DEFINER function's table refs resolve at call time, so it can be defined before those tables exist"}
+      ]
+    },
+    {
+      "id": 4,
+      "name": "theme-override-coexistence",
+      "prompt": "My theme ships a phase-2 migration that overrides the core `subscriptions` SELECT policy with a stricter campus-specific one. But after db:reset, a plain team member can still read the team's subscriptions as if the core policy were still active. What's wrong and how do I fix the override?",
+      "assertions": [
+        {"text": "Explains that RLS combines multiple permissive policies with OR, so the core policy and the theme policy COEXIST (the looser core one still grants access)"},
+        {"text": "Fix: the theme override must DROP the core policy by name — and drop BOTH the legacy AND the current (beta.167) core policy names — before creating its own"},
+        {"text": "Mentions the theme override runs in phase 2 (after core) which is why it must drop the core's policies"}
+      ]
+    }
+  ]
+}

package/claude/skills/service-layer/SKILL.md

@@ -2,10 +2,11 @@
 name: service-layer
 description: |
   Service layer patterns for this Next.js application.
-  Covers static class pattern, RLS integration, standard method signatures, and BaseEntityService.
+  Covers static class pattern, passing the RLS userId context (queryWithRLS), standard method signatures, and BaseEntityService.
   Use this skill when implementing business logic or data access services.
+  For the runtime RLS model (service pool vs app pool, when to force service) see rls-enforcement.
 allowed-tools: Read, Glob, Grep
-version: 1.0.0
+version: 1.1.0
 ---
 
 # Service Layer Skill
@@ -203,6 +204,15 @@ export async function mutateWithRLS<T>(
 - RLS policies use this to filter/restrict data access
 - Always pass `userId` parameter for proper isolation
 
+**Dual-pool routing (beta.167) — see the `rls-enforcement` skill:**
+- `*WithRLS` **with** a `userId` → app pool (RLS evaluated). **Without** a `userId` → **service
+  pool (bypass)**. The bare `query`/`queryOne`/`queryRows` family is **always** service/bypass.
+- **System/bootstrap writes** that create the first team membership/subscription must force the
+  service pool: `mutateWithRLS(sql, params, userId, { service: true })` or
+  `getServiceTransactionClient()` (they can't satisfy membership-based insert policies under the
+  new member's own GUC). This is why `TeamService.create` / `TeamMemberService.add` use the
+  service path.
+
 ### Service Implementation with RLS
 
 ```typescript
@@ -585,3 +595,4 @@ Before finalizing service implementation:
 - `entity-api` - API endpoint patterns
 - `permissions-system` - Permission checking
 - `database-migrations` - Migration patterns
+- `rls-enforcement` - Runtime RLS: service pool vs app pool, when to force service, cutover

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nextsparkjs/ai-workflow",
-  "version": "0.1.0-beta.166",
+  "version": "0.1.0-beta.168",
   "description": "AI workflow templates for NextSpark - Claude Code agents, commands, skills, and multi-editor support",
   "license": "MIT",
   "author": "NextSpark <hello@nextspark.dev>",

package/LICENSE

@@ -1,21 +0,0 @@
-MIT License
-
-Copyright (c) 2025 NextSpark
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.