From bcbdc6462f857f1918dc9ddb550c76768670401d Mon Sep 17 00:00:00 2001 From: Dan Lynch Date: Tue, 17 Nov 2026 00:04:23 +0000 Subject: [PATCH] docs(skills): sync hand-written skills with main; drop duplicate skills and stale zip --- .../constructive-plan-cascade-sdk/SKILL.md | 277 ----------------- .../skills/constructive-principals/SKILL.md | 279 ------------------ .../references/principal-fields.md | 71 ----- .agents/skills/constructive-starter-kits.zip | Bin 1610 -> 0 bytes .agents/skills/constructive-testing/SKILL.md | 2 +- .../references/pgsql-test-transactions.md | 21 ++ .agents/skills/graphile-search/SKILL.md | 8 +- .../references/bm25-adapter.md | 8 +- .../references/codegen-sdk-queries.md | 71 ++--- .../references/pgvector-adapter.md | 2 +- .agents/skills/pgpm/SKILL.md | 1 + .agents/skills/pgpm/references/cli.md | 12 +- 12 files changed, 78 insertions(+), 674 deletions(-) delete mode 100644 .agents/skills/constructive-plan-cascade-sdk/SKILL.md delete mode 100644 .agents/skills/constructive-principals/SKILL.md delete mode 100644 .agents/skills/constructive-principals/references/principal-fields.md delete mode 100644 .agents/skills/constructive-starter-kits.zip diff --git a/.agents/skills/constructive-plan-cascade-sdk/SKILL.md b/.agents/skills/constructive-plan-cascade-sdk/SKILL.md deleted file mode 100644 index bd40401a5d..0000000000 --- a/.agents/skills/constructive-plan-cascade-sdk/SKILL.md +++ /dev/null @@ -1,277 +0,0 @@ ---- -name: constructive-plan-cascade-sdk -description: SDK guide for the plan cascade system — how to configure plans, limits, billing quotas, feature flags (caps), and meter defaults for a Constructive app. Covers the 4 access-control layers, ORM/CLI usage, seeding defaults, and the recommended configuration workflow. Use when asked about 'configuring plans', 'setting up billing', 'feature flags', 'app limits', 'cap tables', 'resolve_cap', 'meter defaults', or 'plan subscription'. ---- - -# Plan Cascade: SDK & Configuration Guide - -When an entity subscribes to a plan, a database trigger atomically cascades -the plan's configuration into three subsystems: **limits**, **billing quotas**, -and **feature flags**. This document covers how to configure and use this -system from the SDK/ORM/CLI. - -## The Four Access-Control Layers - -| Layer | What it controls | SDK surface | Example | -|-------|-----------------|-------------|---------| -| **Permission** | Can user X do action Y? | `db.appPermission`, `db.orgGrant` | Admin-only settings page | -| **Feature flag** | Is feature Y enabled for entity Z? | `db.appLimitCap`, `db.appLimitCapsDefault` | AI module, advanced analytics | -| **Limit** | How many of Y can entity Z have? | `db.appLimit`, `db.appLimitDefault` | Max 10 databases per org | -| **Billing meter** | How much quota used this period? | `balances`, `record_usage()` | 5k/10k API calls this month | - -Permissions are managed via RLS and membership grants. The other three are -driven by **plans** when the plan cascade is enabled. - ---- - -## Configuration Workflow - -### Step 1: Define Your Plans - -```typescript -// ORM -const starter = await db.appPlan.create({ - data: { name: 'starter', isActive: true }, - select: { id: true } -}).execute(); - -const pro = await db.appPlan.create({ - data: { name: 'pro', isActive: true }, - select: { id: true } -}).execute(); -``` - -```bash -# CLI -csdk app-plan create --name starter --isActive true -csdk app-plan create --name pro --isActive true -``` - -### Step 2: Configure Plan Limits (Metered Counters) - -These drive the `limits` table — tracked counters with increment/decrement. - -```typescript -// Starter: max 3 databases, 10 members -await db.appPlanLimit.create({ - data: { planId: starter.id, limitName: 'databases', maxValue: 3 } -}).execute(); -await db.appPlanLimit.create({ - data: { planId: starter.id, limitName: 'members', maxValue: 10 } -}).execute(); - -// Pro: max 20 databases, 100 members -await db.appPlanLimit.create({ - data: { planId: pro.id, limitName: 'databases', maxValue: 20 } -}).execute(); -await db.appPlanLimit.create({ - data: { planId: pro.id, limitName: 'members', maxValue: 100 } -}).execute(); -``` - -### Step 3: Configure Feature Flags (Caps) - -These drive the `limit_caps` table — static config read by `resolve_cap()`. -Convention: `0 = disabled`, `1 = enabled`, `>1 = numeric config`. - -```typescript -// Starter: no AI, 10MB file limit -await db.appPlanCap.create({ - data: { planId: starter.id, capName: 'advanced_analytics', capValue: 0 } -}).execute(); -await db.appPlanCap.create({ - data: { planId: starter.id, capName: 'max_file_size_mb', capValue: 10 } -}).execute(); - -// Pro: AI enabled, 100MB file limit -await db.appPlanCap.create({ - data: { planId: pro.id, capName: 'advanced_analytics', capValue: 1 } -}).execute(); -await db.appPlanCap.create({ - data: { planId: pro.id, capName: 'max_file_size_mb', capValue: 100 } -}).execute(); -``` - -### Step 4: Configure Billing Quotas (Meter Limits) - -These drive the `balances` table — usage tracking with credits, rollover, etc. - -First, seed the meter catalog (the meters your app uses): - -```typescript -// Define which meters exist (via meter_defaults or direct INSERT) -await db.appMeterDefault.create({ - data: { slug: 'api_calls', displayName: 'API Calls', meterType: 'quota', defaultPlanLimit: 0 } -}).execute(); -await db.appMeterDefault.create({ - data: { slug: 'storage_gb', displayName: 'Storage (GB)', meterType: 'quota', defaultPlanLimit: 0 } -}).execute(); -``` - -Then assign billing quotas per plan: - -```typescript -// Starter: 10k API calls, 5GB storage -await db.appPlanMeterLimit.create({ - data: { planId: starter.id, meterSlug: 'api_calls', planLimit: 10000 } -}).execute(); -await db.appPlanMeterLimit.create({ - data: { planId: starter.id, meterSlug: 'storage_gb', planLimit: 5 } -}).execute(); - -// Pro: 100k API calls, 50GB storage -await db.appPlanMeterLimit.create({ - data: { planId: pro.id, meterSlug: 'api_calls', planLimit: 100000 } -}).execute(); -await db.appPlanMeterLimit.create({ - data: { planId: pro.id, meterSlug: 'storage_gb', planLimit: 50 } -}).execute(); -``` - -### Step 5: Subscribe an Entity to a Plan - -This fires the cascade trigger — all limits, caps, and billing quotas are -applied atomically. - -```typescript -await db.appPlanSubscription.create({ - data: { - entityId: orgId, - planId: pro.id, - // organizationId and entityType are needed for billing cascade - // (these columns are on plan_subscriptions) - } -}).execute(); - -// Now the org has: -// - limits: databases=20, members=100 -// - caps: advanced_analytics=1, max_file_size_mb=100 -// - billing: api_calls quota=100k, storage_gb quota=50 -``` - -### Changing Plans (Upgrade/Downgrade) - -Update the subscription's `planId` — the trigger fires again, overwriting -values via upsert: - -```typescript -await db.appPlanSubscription.update({ - where: { id: subscriptionId }, - data: { planId: starter.id } -}).execute(); - -// Limits, caps, and billing quotas now reflect the starter plan -``` - ---- - -## Reading Feature Flags from the SDK - -Query `appLimitCap` for per-entity overrides, or `appLimitCapsDefault` for -app-scope defaults: - -```typescript -// Per-entity cap (e.g. does this org have advanced_analytics?) -const cap = await db.appLimitCap.findFirst({ - where: { name: { equalTo: 'advanced_analytics' }, entityId: { equalTo: orgId } }, - select: { max: true } -}).execute(); - -const isEnabled = cap && Number(cap.max) > 0; - -// App-scope default (fallback when no per-entity override exists) -const defaultCap = await db.appLimitCapsDefault.findFirst({ - where: { name: { equalTo: 'advanced_analytics' } }, - select: { max: true } -}).execute(); -``` - -Convention: `0 = disabled`, `1 = enabled`, `>1 = numeric config` (e.g. max file size in MB). - -For SQL-level details on the `resolve_cap()` COALESCE chain used inside RLS -policies and triggers, see the `constructive-db-plan-cascade` skill in the -constructive-db repo. - ---- - -## Setting App-Level Defaults (Without Plans) - -You can configure defaults independently of plans for apps that don't -use the plan system yet: - -### Limit Defaults - -```typescript -// Set default max for all users (no plan needed) -await db.appLimitDefault.create({ - data: { name: 'databases', max: 5, softMax: 4 } -}).execute(); -``` - -### Cap Defaults (Feature Flags) - -```typescript -// Disable advanced_analytics by default for all entities -await db.appLimitCapsDefault.create({ - data: { name: 'advanced_analytics', max: 0 } -}).execute(); - -// Per-entity override: enable for a specific org -await db.appLimitCap.create({ - data: { name: 'advanced_analytics', entityId: orgId, max: 1 } -}).execute(); -``` - -### Meter Defaults (Billing) - -```typescript -// Define the app's meter catalog -await db.appMeterDefault.create({ - data: { slug: 'api_calls', displayName: 'API Calls', meterType: 'quota', defaultPlanLimit: 1000 } -}).execute(); -``` - ---- - -## SDK Table Reference - -### Plans - -| ORM Table | Purpose | -|-----------|---------| -| `db.appPlan` | Plan definitions (starter, pro, enterprise) | -| `db.appPlanLimit` | Plan → limit_name → max_value (metered counters) | -| `db.appPlanMeterLimit` | Plan → meter_slug → billing quota | -| `db.appPlanCap` | Plan → feature flag → cap value | -| `db.appPlanPricing` | Billing intervals and prices | -| `db.appPlanOverride` | Per-entity VIP limit overrides | -| `db.appPlanSubscription` | Entity → plan assignment (triggers cascade) | - -### Limits - -| ORM Table | Purpose | -|-----------|---------| -| `db.appLimit` | Per-actor metered counters (databases, members, etc.) | -| `db.appLimitDefault` | App-scope default limits | -| `db.orgLimit` | Org-scope aggregate limits | -| `db.orgLimitDefault` | Org-scope default limits | -| `db.appLimitCap` | Per-entity feature flag overrides | -| `db.appLimitCapsDefault` | App-scope default caps/feature flags | -| `db.orgLimitCap` | Org-scope per-entity caps | -| `db.orgLimitCapsDefault` | Org-scope default caps | - -### Billing - -| ORM Table | Purpose | -|-----------|---------| -| `db.appMeterDefault` | Default meter catalog for the app | - -Note: `balances`, `ledger`, and `usage_summary` are in the private schema -and accessed via SQL functions (`record_usage`, `check_billing_quota`), -not directly from the ORM. - - - -**For testing:** Use the test utilities in `constructive-limits` to seed -defaults in `beforeAll`. See the `constructive-db-plan-cascade` skill in -the constructive-db repo for SQL-level test patterns. diff --git a/.agents/skills/constructive-principals/SKILL.md b/.agents/skills/constructive-principals/SKILL.md deleted file mode 100644 index 04a4eeab85..0000000000 --- a/.agents/skills/constructive-principals/SKILL.md +++ /dev/null @@ -1,279 +0,0 @@ ---- -name: constructive-principals -description: "Principal identity system at the application layer — ORM, CLI, and hooks usage for creating/managing principals (scoped sub-identities). Covers the dual-claim JWT model, principal lifecycle via SDK, org scoping with principal_entities, and AuthzHumanOnly enforcement. Use when asked to 'create a principal', 'manage API agents', 'scope an API key', 'use principals', or when building principal management features." -metadata: - author: constructive-io - version: "1.0.0" - triggers: "user, model" ---- - -# Principals — Application Layer - -Principals are scoped sub-identities (user type=3) that authenticate via API keys with a subset of their parent human's permissions. This skill covers how to use principals from the ORM, CLI, and React hooks. - -For SQL-level internals, see the `constructive-db-principals` skill in the `constructive-db` repo. - -## When to Apply - -Use this skill when: -- Creating or deleting principals via ORM, CLI, or hooks -- Building UI for principal management -- Scoping a principal to specific orgs via `principal_entities` -- Understanding the dual-claim JWT model at the application layer - -## Core Concepts - -### Dual-Claim JWT Model - -Two JWT claims are always present. For normal human sessions, both are identical: - -| Claim | Resolves To | Application Use | -|-------|-------------|-----------------| -| `jwt.claims.user_id` | Always the human | Billing, ownership, peoplestamps | -| `jwt.claims.principal_id` | The principal (or same as user_id for humans) | SPRT permission lookups | - -When authenticating with a principal's API key, `user_id` stays the human owner and `principal_id` becomes the principal's identity. All existing ownership checks (`created_by`, `updated_by`, billing) continue to attribute to the human. - -### User Types - -``` -1 = User (human) -2 = Organization -3 = Principal (scoped sub-identity) -``` - -### AuthzHumanOnly - -All principal management mutations (`create_principal`, `delete_principal`) are guarded by `AuthzHumanOnly` — only the owning human can call them. A principal session cannot create or delete other principals. - -### Org Scoping - -Principals can be restricted to specific orgs via `principal_entities`: -- **No entries** = unrestricted (inherits access to all parent's orgs) -- **1+ entries** = restricted to only those specific orgs - -## ORM Usage - -### Create a principal - -```typescript -const result = await db.createPrincipal({ - data: { - name: 'billing-bot', - allowedMask: null, // null = inherit all parent permissions - isReadOnly: false, - bypassStepUp: true, - entityIds: null // null = unrestricted org access - }, - select: { - id: true, - userId: true, - name: true, - ownerIdId: true - } -}).execute(); - -const principal = result.unwrap(); -``` - -### Create a principal scoped to specific orgs - -```typescript -const result = await db.createPrincipal({ - data: { - name: 'org-a-only-bot', - allowedMask: null, - isReadOnly: true, - bypassStepUp: true, - entityIds: [orgAId, orgBId] // restrict to these orgs - }, - select: { id: true, name: true } -}).execute(); -``` - -### Delete a principal - -```typescript -const result = await db.deletePrincipal({ - data: { - principalId: principalId - }, - select: { success: true } -}).execute(); -``` - -### Query principals (owner sees own only) - -```typescript -const principals = await db.principal.findMany({ - select: { - id: true, - name: true, - userId: true, - allowedMask: true, - isReadOnly: true, - bypassStepUp: true - } -}).execute(); -``` - -### Query principal entity scoping - -```typescript -const scoping = await db.principalEntity.findMany({ - where: { principalId: principalId }, - select: { - id: true, - principalId: true, - entityId: true - } -}).execute(); -``` - -## CLI Usage - -### Create a principal - -```bash -csdk create-principal \ - --name "ci-deploy" \ - --is-read-only false \ - --bypass-step-up true -``` - -### Create with org scoping - -```bash -csdk create-principal \ - --name "org-scoped-bot" \ - --entity-ids "," \ - --is-read-only true -``` - -### Delete a principal - -```bash -csdk delete-principal --principal-id "" -``` - -### List principals - -```bash -csdk principal list -``` - -### List principal entities (org scoping) - -```bash -csdk principal-entity list --principal-id "" -``` - -## React Hooks Usage - -### Create a principal - -```typescript -import { useCreatePrincipalMutation } from './hooks'; - -const { mutate: createPrincipal } = useCreatePrincipalMutation(); - -createPrincipal({ - input: { - name: 'my-bot', - allowedMask: null, - isReadOnly: false, - bypassStepUp: true, - entityIds: null - } -}); -``` - -### Delete a principal - -```typescript -import { useDeletePrincipalMutation } from './hooks'; - -const { mutate: deletePrincipal } = useDeletePrincipalMutation(); - -deletePrincipal({ - input: { principalId: principalId } -}); -``` - -### Query principals - -```typescript -import { usePrincipalsQuery } from './hooks'; - -const { data, isLoading } = usePrincipalsQuery({ - selection: { - fields: { - id: true, - name: true, - userId: true, - isReadOnly: true - } - } -}); -``` - -## Error Handling - -All principal mutations return discriminated union results. Handle errors with `.unwrap()` or `.unwrapOr()`: - -```typescript -const result = await db.createPrincipal({ - data: { name: 'bot', allowedMask: null, isReadOnly: false, bypassStepUp: true, entityIds: null }, - select: { id: true } -}).execute(); - -// Throws on error -const principal = result.unwrap(); - -// Or handle gracefully -const principal = result.unwrapOr(null); -if (!principal) { - // handle error -} -``` - -### Expected errors - -| Error | Cause | -|-------|-------| -| `NOT_AUTHENTICATED` | No valid session | -| `PRINCIPAL_CANNOT_CREATE_PRINCIPAL` | A principal session tried to create another principal (AuthzHumanOnly) | -| `PRINCIPAL_CANNOT_DELETE_PRINCIPAL` | A principal session tried to delete a principal (AuthzHumanOnly) | -| `PRINCIPAL_NOT_FOUND` | The principal ID doesn't exist | -| `NOT_OWNER` | Caller doesn't own the principal | - -## Workflow: Create a Principal with an API Key - -A typical workflow to create a fully usable principal: - -```typescript -// 1. Create the principal (human session required) -const principal = (await db.createPrincipal({ - data: { name: 'deploy-bot', allowedMask: null, isReadOnly: false, bypassStepUp: true, entityIds: null }, - select: { id: true, userId: true } -}).execute()).unwrap(); - -// 2. Create an API key for the principal -const apiKey = (await db.createApiKey({ - data: { - principalId: principal.id, - name: 'deploy-bot-key' - }, - select: { id: true, secret: true } -}).execute()).unwrap(); - -// 3. The API key secret can now be used to authenticate as this principal -// When authenticated, jwt.claims.principal_id = principal.userId -// and jwt.claims.user_id = the human who created it -``` - -## References - -- `constructive-db-principals` skill — SQL-level internals (module generator, SPRT integration, RLS policies) -- `constructive-db-security` skill — AuthzHumanOnly policy details -- `references/principal-fields.md` — Field reference for principals and principal_entities tables diff --git a/.agents/skills/constructive-principals/references/principal-fields.md b/.agents/skills/constructive-principals/references/principal-fields.md deleted file mode 100644 index 331e5aae75..0000000000 --- a/.agents/skills/constructive-principals/references/principal-fields.md +++ /dev/null @@ -1,71 +0,0 @@ ---- -name: constructive-principals-fields -description: Field reference for principals and principal_entities tables — columns, types, defaults, and constraints. ---- - -# Principal Field Reference - -## `principals` table - -| Field | GraphQL Name | Type | Default | Description | -|-------|-------------|------|---------|-------------| -| `id` | `id` | UUID | auto | Primary key | -| `owner_id` | `ownerId` | UUID (FK → users) | — | Parent human who owns this principal | -| `user_id` | `userId` | UUID (FK → users) | — | Principal's identity row (type=3) | -| `name` | `name` | String | — | Display name (e.g., `'billing-bot'`) | -| `allowed_mask` | `allowedMask` | BitVarying | NULL | Permission subset bitmask. NULL = all parent permissions | -| `is_read_only` | `isReadOnly` | Boolean | false | Read-only mode flag | -| `bypass_step_up` | `bypassStepUp` | Boolean | true | Skip MFA step-up (principals can't do MFA) | -| `created_at` | `createdAt` | DateTime | now() | Creation timestamp | -| `updated_at` | `updatedAt` | DateTime | now() | Last update timestamp | - -**RLS:** `AuthzDirectOwner` on `owner_id` — users can only SELECT their own principals. - -**Mutations:** `create_principal` and `delete_principal` (both AuthzHumanOnly, SECURITY DEFINER). - -## `principal_entities` table - -| Field | GraphQL Name | Type | Default | Description | -|-------|-------------|------|---------|-------------| -| `id` | `id` | UUID | auto | Primary key | -| `principal_id` | `principalId` | UUID (FK → principals, CASCADE) | — | The principal being scoped | -| `entity_id` | `entityId` | UUID (FK → users) | — | The org this principal can access | - -**Unique constraint:** `(principal_id, entity_id)` — no duplicate scoping. - -**RLS:** `AuthzDirectOwner` via the principal's `owner_id` (joined through `principal_id → principals.owner_id`). - -**Scoping semantics:** -- No rows = unrestricted (principal inherits access to all parent's orgs) -- 1+ rows = restricted to only those specific orgs - -## `create_principal` mutation - -| Parameter | GraphQL Name | Type | Required | Description | -|-----------|-------------|------|----------|-------------| -| `name` | `name` | String | Yes | Display name | -| `allowed_mask` | `allowedMask` | BitVarying | No | Permission bitmask (NULL = all) | -| `entity_ids` | `entityIds` | [UUID] | No | Org IDs to scope to (NULL = unrestricted) | -| `is_read_only` | `isReadOnly` | Boolean | No | Default: false | -| `bypass_step_up` | `bypassStepUp` | Boolean | No | Default: true | - -**Returns:** The created principal record. - -**Guards:** AuthzHumanOnly — only callable by human sessions. - -**Side effects:** -1. Creates a `users` row with `type = 3` -2. Creates a `principals` row -3. If `entity_ids` provided, creates `principal_entities` rows - -## `delete_principal` mutation - -| Parameter | GraphQL Name | Type | Required | Description | -|-----------|-------------|------|----------|-------------| -| `principal_id` | `principalId` | UUID | Yes | The principal to delete | - -**Returns:** Success indicator. - -**Guards:** AuthzHumanOnly + ownership check (must own the principal). - -**Side effects:** CASCADE deletes the principal's `users` row, `principal_entities` rows, SPRT entries, and any associated credentials/sessions. diff --git a/.agents/skills/constructive-starter-kits.zip b/.agents/skills/constructive-starter-kits.zip deleted file mode 100644 index 7e30993e825d051fc7caddc4336a3523316370fa..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 1610 zcmWIWW@h1H009xEk1=2dl#pVOVMxx;D=sN2O)kkSOVuqdNh~T!Ez-@-EGgCx4dG;9 zPA`efngGP572FJrEH9WD7{EjT&`c4aDI8!k6RviK?O|bHxXI1HpoG`VU~f+!AHCcZ zxY;1{(ai1*yPbF2LZJ3}IM1B+-eB){-!4{i$>a!Z;oY=z0e?5sGSyp2IuoNNbtNC* z|J(8R(BDaO7v@co-7d|t!MEsyW%@Zuqb{Xo6^dySGE(QR6jG0OO_4SCn~|YBH+AKP z&WTGWN1c6O_;B^qbHM>g+@BTLycWm1JkrTodU`?3bXE^l*+0J@%iqY_yiwKv$d(J4 zQ@INkX%xR}Y5n|r_V4uvLb<+||9Co8`sCEjk2!bv9GF{C{IQ!gZrX+`M&ifXeHB)& zx$L@~Um`F|d#+i~jn4ae5qx`!B>h&F@|+JlU?$A9<8Ft@oVLKEmiQ-zrUq`p5;w)P z-!sbeTrbGjaC^x^z6sX*XVg6^n9wIL#7C2V5I42kbgPnBEne7+rcMksd5os&z?EWLg9)r6nZZ*$&x84{2+->x>HwZP_S z-+2j>961lStT~mU$Es%b)b-mRlXur~s@=GGVSt=;lilPUH)_wCZ&{KwF`@NkyP~kh z*Dwj4>qYF{e3uVpuTEUFT437#bzX~`L#IAhd6D8Q6CE*Ac#GNV*<5c*QXTR`?PZO> zP4VRZasJ_>L#ZAME{Zzs+|lt+^L5Iz9mhMrSS*xz^5d}3ZIz7qf0^F6J^PuzEi_tW zk$F;UM5xoV4HgY$8)x_^Ijm>UbSxLlbKm)+)=udSAECERYBs&sVtf2JfvNc7spEDbUO!JPe9iXgtJeOx z=hoYH)`tm+zS?{6M$*QJqS+IRqvroMyJ`Gwp<>ThzW!}GJRH%>uh-1}s=$)XqL16oD)-CXd9Xw0gK4O)$;TzRJpuVGQL}!$ z>pJ;LcTvrre>~X>1(+-UrhL-6*G{axwBqj682^CzVb4p7=e10H@+surR}s};?DvWf|7$Ac-Su5=U&h`{4)Kb6 z>&oWGyLnxH>c8{Nl`^fV1&pd+-hQ}v{i=}q{FiY~${PA_a*w_2y^Bxwt@Ix|KXMfKoS9qgZSHrO{l%s|$Ch)Kg_tzPT%Wb_?$w;Qf}__LE$}OP zSA0;KFNn9sm4E7irpMk@!Z#is?TFU>cxb6GyRKk%@cg=9ZPCex%SDwmKkWH(;-34* zA8u<-Rkg2=%Dlh)?~ML4rH57uKZ^F7ZdbZ6PIXqtzRmv`0=yZS}7?Ny=Y}4#C%*OFT{LCpvg-bL-3l9D2H*`!^#G7Arlau0Ma?EARYiUm9(k= diff --git a/.agents/skills/constructive-testing/SKILL.md b/.agents/skills/constructive-testing/SKILL.md index cd05e9bbd4..b08626884d 100644 --- a/.agents/skills/constructive-testing/SKILL.md +++ b/.agents/skills/constructive-testing/SKILL.md @@ -91,7 +91,7 @@ Choose the **highest-level framework** that fits your test scenario: | [pgsql-test-snapshot.md](./references/pgsql-test-snapshot.md) | Snapshot testing | pruneIds, pruneDates, deterministic assertions | | [pgsql-test-helpers.md](./references/pgsql-test-helpers.md) | Helper utilities | Common test helper functions | | [pgsql-test-jwt-context.md](./references/pgsql-test-jwt-context.md) | JWT context testing | Setting JWT claims, testing authenticated queries | -| [pgsql-test-transactions.md](./references/pgsql-test-transactions.md) | Transaction-local context & roles | `beforeAll` context gotcha, three roles (superuser/administrator/authenticated), `pg` vs `db` | +| [pgsql-test-transactions.md](./references/pgsql-test-transactions.md) | Transaction-local context & roles | `beforeAll` context gotcha, `deferredConstraints` (commit-time checks under rollback), three roles (superuser/administrator/authenticated), `pg` vs `db` | | [pgsql-test-scenario-setup.md](./references/pgsql-test-scenario-setup.md) | Complex scenario setup | Multi-client scenarios, complex test arrangements | ### Additional Frameworks diff --git a/.agents/skills/constructive-testing/references/pgsql-test-transactions.md b/.agents/skills/constructive-testing/references/pgsql-test-transactions.md index aa1443bb1e..51a5dd40de 100644 --- a/.agents/skills/constructive-testing/references/pgsql-test-transactions.md +++ b/.agents/skills/constructive-testing/references/pgsql-test-transactions.md @@ -43,6 +43,27 @@ db.setContext({ role: 'authenticated', 'jwt.claims.user_id': ADMIN_ID }); await db.query(`INSERT INTO app.teams (...) VALUES (...)`); // ERROR: no context ``` +## Deferred Constraints Under Rollback Isolation + +`beforeEach()`/`afterEach()` roll back instead of committing, so checks Postgres runs only at COMMIT never run in a test. A `DEFERRABLE INITIALLY DEFERRED` FK / UNIQUE / EXCLUDE / `CONSTRAINT TRIGGER` violation therefore passes silently by default. Choose a mode with `db.deferredConstraints` (env `DB_DEFERRED_CONSTRAINTS`): + +| Mode | Behaviour | +|------|-----------| +| `'off'` (default) | Nothing; deferred violations pass | +| `'check'` | `afterEach()` runs `SET CONSTRAINTS ALL IMMEDIATE` before rolling back, so a pending violation fails the test (in `afterEach`, naming the constraint). Skipped if the test already raised a Postgres error | +| `'immediate'` | `beforeEach()` (and `publish()`) run `SET CONSTRAINTS ALL IMMEDIATE`, so each statement is checked on its own line. Code that relies on deferral (child before parent) fails in tests | + +```typescript +const { db, teardown } = await getConnections({ db: { deferredConstraints: 'check' } }); + +it('rejects orphan children at commit', async () => { + await db.query(`INSERT INTO children (parent_id) VALUES (999)`); + await expect(db.checkConstraints()).rejects.toThrow(/children_parent_id_fkey/); +}); +``` + +`db.checkConstraints()` runs the commit-time checks now without committing (it issues `SET CONSTRAINTS ALL IMMEDIATE`, so constraints stay immediate for the rest of that test). `NOTIFY` delivery and visibility to other sessions are not covered by any mode; use `publish()` (which really commits) for those. + ## Role Patterns for RLS Testing PostgreSQL supports multiple roles with different privilege levels. `pgsql-test` gives you `pg` (superuser) and `db` (app-level) to test against them: diff --git a/.agents/skills/graphile-search/SKILL.md b/.agents/skills/graphile-search/SKILL.md index 9b5a737247..30cbf966e1 100644 --- a/.agents/skills/graphile-search/SKILL.md +++ b/.agents/skills/graphile-search/SKILL.md @@ -126,9 +126,9 @@ Computed via **Reciprocal Rank Fusion (RRF)**: each active adapter ranks its res | Adapter | Filter Field | Input Type | |---------|-------------|------------| | tsvector | `fullTextSearchTsv` | `String` (search query) | -| BM25 | `bm25Body` | `Bm25SearchInput` (`{ query, indexName }`) | +| BM25 | `bm25Body` | `Bm25SearchInput` (`{ query, threshold? }`) | | trgm | `trgmTitle` | `TrgmSearchInput` (`{ value, threshold? }`) | -| pgvector | `vectorEmbedding` | `VectorSearchInput` (`{ query: [Float!]!, metric? }`) | +| pgvector | `vectorEmbedding` | `VectorNearbyInput` (`{ vector: [Float!]!, model?, metric?, distance?, includeChunks? }`) | **Naming pattern:** `{filterPrefix}{CamelCase(column)}` @@ -228,9 +228,9 @@ After running `cnc codegen`, the generated SDK client exposes search filters, sc - **Composite fields** — `unifiedSearch` (multi-strategy filter) and `searchScore` (0..1 relevance) - **TSVector queries** — `fullTextSearchTsv`, `searchTsvRank`, pagination, combined filters -- **BM25 queries** — `bm25Content`, `bm25ContentScore` (negative, sort ASC) +- **BM25 queries** — `bm25Content`, `contentBm25Score` (negative, sort ASC) - **Trigram queries** — `similarTo`/`wordSimilarTo` via `StringTrgmFilter`, adapter-level `trgmTitle`, ILIKE -- **pgvector queries** — `vectorEmbedding`, `embeddingDistance`, distance metrics (COSINE/L2/IP) +- **pgvector queries** — `vectorEmbedding`, `embeddingVectorDistance`, distance metrics (COSINE/L2/IP) - **Chunk-aware search** — `includeChunks` toggle for RAG tables with `@hasChunks`, transparent parent + chunk distance - **Multi-strategy patterns** — fuzzy fallback, autocomplete pipeline, semantic + keyword hybrid diff --git a/.agents/skills/graphile-search/references/bm25-adapter.md b/.agents/skills/graphile-search/references/bm25-adapter.md index 55394f74e0..930e0c0af6 100644 --- a/.agents/skills/graphile-search/references/bm25-adapter.md +++ b/.agents/skills/graphile-search/references/bm25-adapter.md @@ -7,7 +7,7 @@ Relevance-ranked search using BM25 scoring via the `pg_textsearch` extension. Be The BM25 adapter: 1. **Gathers** BM25 index information during the Graphile gather phase (via `Bm25CodecPlugin`) 2. **Detects** text columns that have a BM25 index (stored in the `bm25IndexStore`) -3. **Registers** a `Bm25SearchInput` type (`{ query: String!, indexName: String }`) +3. **Registers** a `Bm25SearchInput` type (`{ query: String!, threshold: Float }`) 4. **Generates** BM25 score as a computed field and orderBy enum ## Adapter Configuration @@ -54,6 +54,12 @@ enum DocumentsOrderBy { } ``` +## Filter Semantics + +- A BM25 score is negative for a row the query matches and `0` for a row it does not. The filter keeps negative scores only, so without `threshold` the connection holds exactly the matching rows and `totalCount` equals that count (with or without a BM25 `orderBy`, and through `unifiedSearch`). +- `threshold` is a maximum score and inclusive: `{ query, threshold: -1.5 }` keeps rows scoring `<= -1.5`; a row scoring exactly the threshold is kept. +- `CONTENT_BM25_SCORE_ASC/DESC` requires `bm25Content` (or `unifiedSearch`) in `where`; without it the query errors and names the filter to add. This check also applies when `orderBy` is passed as a variable, and a variable `orderBy` keeps the requested order of a composite list. + ## Score Semantics | Property | Value | diff --git a/.agents/skills/graphile-search/references/codegen-sdk-queries.md b/.agents/skills/graphile-search/references/codegen-sdk-queries.md index f691b13b1e..5e1246eb33 100644 --- a/.agents/skills/graphile-search/references/codegen-sdk-queries.md +++ b/.agents/skills/graphile-search/references/codegen-sdk-queries.md @@ -154,17 +154,17 @@ const result = await db.document.findMany({ where: { bm25Content: { query: 'postgres full text search' }, }, - orderBy: 'BM25_CONTENT_SCORE_ASC', + orderBy: 'CONTENT_BM25_SCORE_ASC', select: { id: true, title: true, - bm25ContentScore: true, + contentBm25Score: true, }, }).execute(); if (result.ok) { result.data.documents.nodes.forEach(d => { - console.log(`${d.title} (score: ${d.bm25ContentScore})`); + console.log(`${d.title} (score: ${d.contentBm25Score})`); }); } ``` @@ -178,13 +178,13 @@ const result = await db.document.findMany({ where: { bm25Content: { query: 'machine learning' }, }, - orderBy: 'BM25_CONTENT_SCORE_ASC', + orderBy: 'CONTENT_BM25_SCORE_ASC', first: 10, after: cursor, select: { id: true, title: true, - bm25ContentScore: true, + contentBm25Score: true, }, }).execute(); ``` @@ -198,13 +198,13 @@ const result = await db.document.findMany({ isPublished: { equalTo: true }, category: { equalTo: 'devops' }, }, - orderBy: 'BM25_CONTENT_SCORE_ASC', + orderBy: 'CONTENT_BM25_SCORE_ASC', first: 20, select: { id: true, title: true, category: true, - bm25ContentScore: true, + contentBm25Score: true, }, }).execute(); ``` @@ -213,13 +213,14 @@ const result = await db.document.findMany({ | DB Column | Filter Field | Score Field | OrderBy | |-----------|-------------|-------------|---------| -| `content` | `bm25Content` | `bm25ContentScore` | `BM25_CONTENT_SCORE_ASC/DESC` | -| `body` | `bm25Body` | `bm25BodyScore` | `BM25_BODY_SCORE_ASC/DESC` | +| `content` | `bm25Content` | `contentBm25Score` | `CONTENT_BM25_SCORE_ASC/DESC` | +| `body` | `bm25Body` | `bodyBm25Score` | `BODY_BM25_SCORE_ASC/DESC` | **Pattern:** -- Filter: `bm25` + CamelCase(column) — accepts `{ query: String }` input -- Score: `bm25` + CamelCase(column) + `Score` (Float, negative, more negative = better, null when no filter active) -- OrderBy: `BM25_` + SCREAMING_SNAKE(column) + `_SCORE_ASC/DESC` +- Filter: `bm25` + CamelCase(column) — accepts `{ query: String!, threshold?: Float }` +- Score: camelCase(column) + `Bm25Score` (Float, negative, more negative = better, null when no filter active) +- OrderBy: SCREAMING_SNAKE(column) + `_BM25_SCORE_ASC/DESC` +- Without `threshold` only rows the query matches (negative score) are returned, so `totalCount` equals the number of matching rows. `threshold` is a maximum score and inclusive: a row scoring exactly the threshold is kept. --- @@ -326,18 +327,18 @@ const result = await db.document.findMany({ metric: 'COSINE', }, }, - orderBy: 'EMBEDDING_DISTANCE_ASC', + orderBy: 'EMBEDDING_VECTOR_DISTANCE_ASC', first: 10, select: { id: true, title: true, - embeddingDistance: true, + embeddingVectorDistance: true, }, }).execute(); if (result.ok) { result.data.documents.nodes.forEach(d => { - console.log(`${d.title} (distance: ${d.embeddingDistance})`); + console.log(`${d.title} (distance: ${d.embeddingVectorDistance})`); }); } ``` @@ -353,11 +354,11 @@ const result = await db.document.findMany({ distance: 0.5, // filter out results beyond threshold }, }, - orderBy: 'EMBEDDING_DISTANCE_ASC', + orderBy: 'EMBEDDING_VECTOR_DISTANCE_ASC', select: { id: true, title: true, - embeddingDistance: true, + embeddingVectorDistance: true, }, }).execute(); ``` @@ -374,13 +375,13 @@ const result = await db.document.findMany({ isPublished: { equalTo: true }, category: { equalTo: 'tech' }, }, - orderBy: 'EMBEDDING_DISTANCE_ASC', + orderBy: 'EMBEDDING_VECTOR_DISTANCE_ASC', first: 10, select: { id: true, title: true, category: true, - embeddingDistance: true, + embeddingVectorDistance: true, }, }).execute(); ``` @@ -397,13 +398,13 @@ const result = await db.document.findMany({ | DB Column | Filter Field | Distance Field | OrderBy | |-----------|-------------|----------------|---------| -| `embedding` | `vectorEmbedding` | `embeddingDistance` | `EMBEDDING_DISTANCE_ASC/DESC` | -| `content_vec` | `vectorContentVec` | `contentVecDistance` | `CONTENT_VEC_DISTANCE_ASC/DESC` | +| `embedding` | `vectorEmbedding` | `embeddingVectorDistance` | `EMBEDDING_VECTOR_DISTANCE_ASC/DESC` | +| `content_vec` | `vectorContentVec` | `contentVecVectorDistance` | `CONTENT_VEC_VECTOR_DISTANCE_ASC/DESC` | **Pattern:** -- Filter: `vector` + CamelCase(column) — accepts `{ vector: [Float!]!, metric?: String, distance?: Float, includeChunks?: Boolean }` -- Distance: camelCase(column) + `Distance` (Float, lower = closer, null when no filter active) -- OrderBy: SCREAMING_SNAKE(column) + `_DISTANCE_ASC/DESC` +- Filter: `vector` + CamelCase(column) — accepts `{ vector: [Float!]!, model?: String, metric?: String, distance?: Float, includeChunks?: Boolean }` +- Distance: camelCase(column) + `VectorDistance` (Float, lower = closer, null when no filter active) +- OrderBy: SCREAMING_SNAKE(column) + `_VECTOR_DISTANCE_ASC/DESC` ### Chunk-Aware Vector Search @@ -422,18 +423,18 @@ const result = await db.document.findMany({ // includeChunks defaults to true when @hasChunks is present }, }, - orderBy: 'EMBEDDING_DISTANCE_ASC', + orderBy: 'EMBEDDING_VECTOR_DISTANCE_ASC', first: 10, select: { id: true, title: true, - embeddingDistance: true, // best distance across parent + all chunks + embeddingVectorDistance: true, // best distance across parent + all chunks }, }).execute(); if (result.ok) { result.data.documents.nodes.forEach(d => { - console.log(`${d.title} (distance: ${d.embeddingDistance})`); + console.log(`${d.title} (distance: ${d.embeddingVectorDistance})`); }); } ``` @@ -451,12 +452,12 @@ const result = await db.document.findMany({ includeChunks: false, // only use parent embedding }, }, - orderBy: 'EMBEDDING_DISTANCE_ASC', + orderBy: 'EMBEDDING_VECTOR_DISTANCE_ASC', first: 10, select: { id: true, title: true, - embeddingDistance: true, // parent distance only + embeddingVectorDistance: true, // parent distance only }, }).execute(); ``` @@ -475,12 +476,12 @@ const result = await db.document.findMany({ }, isPublished: { equalTo: true }, }, - orderBy: 'EMBEDDING_DISTANCE_ASC', + orderBy: 'EMBEDDING_VECTOR_DISTANCE_ASC', first: 20, select: { id: true, title: true, - embeddingDistance: true, + embeddingVectorDistance: true, searchScore: true, // composite 0..1 relevance }, }).execute(); @@ -498,9 +499,9 @@ const result = await db.document.findMany({ // Primary: BM25 search const bm25Result = await db.document.findMany({ where: { bm25Content: { query: userQuery } }, - orderBy: 'BM25_CONTENT_SCORE_ASC', + orderBy: 'CONTENT_BM25_SCORE_ASC', first: 10, - select: { id: true, title: true, bm25ContentScore: true }, + select: { id: true, title: true, contentBm25Score: true }, }).execute(); const bm25Docs = bm25Result.ok ? bm25Result.data.documents.nodes : []; @@ -546,9 +547,9 @@ const search = await db.article.findMany({ // Semantic search const semanticResult = await db.document.findMany({ where: { vectorEmbedding: { vector: queryEmbedding, metric: 'COSINE' } }, - orderBy: 'EMBEDDING_DISTANCE_ASC', + orderBy: 'EMBEDDING_VECTOR_DISTANCE_ASC', first: 20, - select: { id: true, title: true, embeddingDistance: true }, + select: { id: true, title: true, embeddingVectorDistance: true }, }).execute(); // Keyword search diff --git a/.agents/skills/graphile-search/references/pgvector-adapter.md b/.agents/skills/graphile-search/references/pgvector-adapter.md index 3c04235eed..4a46f507e1 100644 --- a/.agents/skills/graphile-search/references/pgvector-adapter.md +++ b/.agents/skills/graphile-search/references/pgvector-adapter.md @@ -6,7 +6,7 @@ Semantic similarity search using the `pgvector` extension. Supports cosine, L2, The pgvector adapter: 1. **Detects** `vector(N)` columns on tables (via `VectorCodecPlugin` codec registration) -2. **Registers** `VectorSearchInput` type (`{ query: [Float!]!, metric: VectorMetric }`) +2. **Registers** `VectorNearbyInput` type (`{ vector: [Float!]!, model: String, metric: VectorMetric, distance: Float, includeChunks: Boolean }`) 3. **Generates** distance score as a computed field and orderBy enum ## Adapter Configuration diff --git a/.agents/skills/pgpm/SKILL.md b/.agents/skills/pgpm/SKILL.md index 9fd1585080..bf041850b3 100644 --- a/.agents/skills/pgpm/SKILL.md +++ b/.agents/skills/pgpm/SKILL.md @@ -358,6 +358,7 @@ Consult these reference files for detailed documentation on specific topics: | Reference | Topic | Consult When | |-----------|-------|--------------| | [references/cli.md](references/cli.md) | Complete CLI command reference | Looking up command flags, options, or less common commands | +| `pgpm-projections` skill | `pgpm import` / `pgpm transform` / `pgpm diff` (semantic schema diff, emitted migration modules, `--append-module`, `--verify`) | Diffing two schema sources or generating a migration from a diff | | [references/workspace.md](references/workspace.md) | Creating and managing workspaces | Setting up a new project, understanding workspace structure | | [references/changes.md](references/changes.md) | Authoring database changes | Writing deploy/revert/verify scripts, using `pgpm add` | | [references/sql-conventions.md](references/sql-conventions.md) | SQL file format and conventions | Writing SQL files, naming conventions, header format | diff --git a/.agents/skills/pgpm/references/cli.md b/.agents/skills/pgpm/references/cli.md index 75283acbea..415e0b408a 100644 --- a/.agents/skills/pgpm/references/cli.md +++ b/.agents/skills/pgpm/references/cli.md @@ -341,8 +341,8 @@ pgpm admin-users bootstrap # Add specific user pgpm admin-users add --username myuser --password "$PGPASSWORD" --yes -# Opt-in RLS bypass for a platform service login (never for a request role) -pgpm admin-users add --username platform_service --password "$PGPASSWORD" --bypassrls --yes +# Opt-in RLS bypass (never for a request role or a Constructive platform login) +pgpm admin-users add --username migrator --password "$PGPASSWORD" --bypassrls --yes # Remove user pgpm admin-users remove myuser @@ -350,9 +350,11 @@ pgpm admin-users remove myuser User provisioning reconciles LOGIN, INHERIT, NOSUPERUSER, NOCREATEDB, NOCREATEROLE, NOREPLICATION and the supplied password on every run. RLS bypass -is off unless `--bypassrls` is passed. Platform components use one such login -via `PGUSER`/`PGPASSWORD`; requests still switch to `authenticated`/`anonymous`, -whose current-role attributes enforce RLS. No role environment variable is needed. +is off unless `--bypassrls` is passed; `--bypassrls` cannot be combined with +`--test`. Constructive platform components connect through one `NOBYPASSRLS` +login via `PGUSER`/`PGPASSWORD` (do not pass `--bypassrls` for it); requests +still switch to `authenticated`/`anonymous`, whose current-role attributes +enforce RLS. No role environment variable is needed. ### Utilities