@opensaas/stack-core 0.20.1 → 0.22.0

package/.turbo/turbo-build.log

@@ -1,4 +1,4 @@
 
-> @opensaas/stack-core@0.20.1 build /home/runner/work/stack/stack/packages/core
+> @opensaas/stack-core@0.22.0 build /home/runner/work/stack/stack/packages/core
 > tsc
 

package/CHANGELOG.md

@@ -1,5 +1,339 @@
 # @opensaas/stack-core
 
+## 0.22.0
+
+### Minor Changes
+
+- [#497](https://github.com/OpenSaasAU/stack/pull/497) [`be4181a`](https://github.com/OpenSaasAU/stack/commit/be4181ada3f2d6386052df4d4869ad150d360f89) Thanks [@{](https://github.com/{)! - Derive the auth plugin's Auth lists from the better-auth config
+
+  `authPlugin` now mirrors the better-auth config a developer writes instead of hardcoding the keys `User`/`Session`/`Account`/`Verification`. Per-model `modelName` becomes the OpenSaaS list key (and a table `@@map`), and the `fields` column map becomes per-field `@map`s. The plugin only ever adds/extends its own derived keys, so an app's separate domain `User` is never overwritten. The runtime `getUser`/`getCurrentUser` helpers now resolve the user list key from the configured user model instead of a hardcoded `'user'`.
+
+  Default behaviour (no overrides) is unchanged: the lists are still keyed `User`/`Session`/`Account`/`Verification` with the original field shapes and no `@@map`.
+
+  ```typescript
+  // Adopt existing better-auth tables without a destructive migration
+  authPlugin({
+   modelName: 'AuthUser', fields: { name: 'full_name' } },
+    session: { modelName: 'AuthSession', fields: { userId: 'user_id' } },
+    account: { modelName: 'AuthAccount' },
+    verification: { modelName: 'AuthVerification' },
+  })
+  // -> lists keyed AuthUser/AuthSession/AuthAccount/AuthVerification
+  //    with @@map + column @map matching the live tables
+  ```
+
+  Lists also gain a model-level `db.map` option, which emits a `@@map("...")` on the generated Prisma model so a list key can differ from its physical table name.
+
+- [#498](https://github.com/OpenSaasAU/stack/pull/498) [`dc51f23`](https://github.com/OpenSaasAU/stack/commit/dc51f237323ee53a705c4b9831dd8db85efd9bc1) Thanks [@borisno2](https://github.com/borisno2)! - Add an `output` config block so `opensaas generate` can relocate the generated Prisma schema and `.opensaas` bundle (e.g. to coexist with an existing Keystone `prisma/` during migration)
+
+  Set `output.prismaSchema` and/or `output.opensaasDir` in `opensaas.config.ts` to move where the generator writes. Defaults are unchanged (`prisma/schema.prisma`, `.opensaas/`) when the block is omitted. The generated files' cross-references follow the configured locations: `context.ts`/`prisma-extensions.ts` import `opensaas.config` from the resolved bundle, the Prisma client `generator { output }` points back at the relocated bundle, and the top-level `prisma.config.ts` references the configured schema directory so `prisma` CLI commands keep working.
+
+  The pre-existing top-level `opensaasPath` option is preserved: the effective `.opensaas` bundle directory resolves as `output.opensaasDir` > `opensaasPath` > the default `.opensaas`. Setting `opensaasPath` alone still relocates the bundle through the CLI exactly as before; `output.opensaasDir` overrides it when both are set.
+
+  ```typescript
+  export default config({
+    output: {
+      prismaSchema: 'prisma-opensaas/schema.prisma',
+      opensaasDir: 'generated/opensaas',
+    },
+    db: {
+      /* ... */
+    },
+    lists: {
+      /* ... */
+    },
+  })
+  ```
+
+- [#511](https://github.com/OpenSaasAU/stack/pull/511) [`696f5c0`](https://github.com/OpenSaasAU/stack/commit/696f5c08c37d4a18107e48cb6b360c9492c7425c) Thanks [@borisno2](https://github.com/borisno2)! - Add non-destructive multi-column mode to `image()` / `file()` for adopting an existing Keystone database without dropping columns (ADR-0006).
+
+  Keystone stores an image across seven per-part columns (`_url`, `_width`, `_height`, `_filesize`, `_contentType`, `_contentDisposition`, `_pathname`) and a file across three (`_filename`, `_filesize`, `_url`). By default `image()`/`file()` still back a single `Json?` column (greenfield unchanged). Set `db.columns: 'keystone'` to map the field onto the existing per-part columns in place — assembled into an `ImageMetadata`/`FileMetadata` on read and split back on write — so a migrating project reaches a clean schema diff with no data migration and no re-upload of existing assets.
+
+  ```typescript
+  import { image, file } from '@opensaas/stack-storage/fields'
+
+  fields: {
+    // Maps onto image_url, image_width, … image_pathname in place.
+    avatar: image({ storage: 'images', db: { columns: 'keystone' } }),
+
+    // Per-part @map names are configurable for non-default column names.
+    cover: image({
+      storage: 'images',
+      db: { columns: { mode: 'keystone', map: { url: 'cover_link' } } },
+    }),
+
+    resume: file({ storage: 'documents', db: { columns: 'keystone' } }),
+  }
+  ```
+
+  No-re-upload guarantee (both modes): an already-shaped metadata value — or, in multi-column mode, populated columns — is authoritative and never triggers a storage upload; only a `File`-like input uploads.
+
+  Adds a multi-column field-emission contract (`getPrismaColumns`) plus `getColumnNames`/`assembleColumns`/`splitColumns` to the field-authoring surface so any field can map onto several physical columns. The generator emits one `@map`-ped Prisma line per column; reads assemble the logical value from the raw columns and strip them from the result; writes split the logical value back across the columns.
+
+- [#499](https://github.com/OpenSaasAU/stack/pull/499) [`f9e0505`](https://github.com/OpenSaasAU/stack/commit/f9e05053c75c76781751d5d9e5d1ed5cd9be635f) Thanks [@borisno2](https://github.com/borisno2)! - Add opt-in `db.keystoneCompat` mode for Keystone-compatible empty-string text defaults
+
+  When migrating from Keystone 6, every non-null text column carries an implicit empty-string default. Set `db: { keystoneCompat: true }` to mirror that: any non-null `text()` column without an explicit `defaultValue` now generates `String @default("")`, so a migrating schema reaches parity without hand-setting `defaultValue: ''` on dozens of columns.
+
+  The mode is off by default (greenfield schemas stay clean) and never affects nullable text, fields with an explicit `defaultValue`, or any non-text field — an explicit `text({ defaultValue: 'x' })` always wins.
+
+  ```typescript
+  export default config({
+    db: {
+      provider: 'postgresql',
+      keystoneCompat: true, // non-null text without a default → @default("")
+      prismaClientConstructor: (PrismaClient) => {
+        // ... adapter setup
+      },
+    },
+    lists: {
+      Account: list({
+        fields: {
+          // required text → String @default("")
+          name: text({ validation: { isRequired: true } }),
+          // explicit default still wins → String @default("PLEASE_UPDATE")
+          status: text({ validation: { isRequired: true }, defaultValue: 'PLEASE_UPDATE' }),
+          // nullable text is untouched → String?
+          bio: text(),
+        },
+      }),
+    },
+  })
+  ```
+
+  See ADR-0004 for the full Keystone-compatible generator defaults.
+
+- [#501](https://github.com/OpenSaasAU/stack/pull/501) [`e30f6a1`](https://github.com/OpenSaasAU/stack/commit/e30f6a1ef69dc65ae68b37539fa74c3f97823cfd) Thanks [@borisno2](https://github.com/borisno2)! - Auto-timestamps are now OFF by default; opt in with `db.timestamps`
+
+  The generator no longer appends `createdAt`/`updatedAt` to every model. This matches
+  Keystone 6 (which never adds them automatically) and keeps Keystone → stack migrations
+  non-destructive. A list opts in either by declaring the fields itself or by enabling the
+  new `db.timestamps` flag. See ADR-0004.
+
+  Note: this changes a long-standing default. Existing apps that relied on auto-injected
+  timestamps should set `db: { timestamps: true }` to keep them.
+
+  Enable globally:
+
+  ```typescript
+  export default config({
+    db: {
+      provider: 'postgresql',
+      timestamps: true, // re-enable auto createdAt/updatedAt for all lists
+      // ...
+    },
+    lists: {
+      /* ... */
+    },
+  })
+  ```
+
+  Override per list (takes precedence over the global setting):
+
+  ```typescript
+  lists: {
+    // Opt this one list out even though timestamps are on globally
+    Production: list({
+      fields: { name: text() },
+      db: { timestamps: false },
+    }),
+    // Opt this one list in even though the global default is off
+    Audited: list({
+      fields: { name: text() },
+      db: { timestamps: true },
+    }),
+  }
+  ```
+
+  When timestamps are enabled and a list already declares its own `createdAt`/`updatedAt`
+  field, the auto column is skipped for the declared field(s) so Prisma never sees a
+  duplicate (`P1012`):
+
+  ```typescript
+  lists: {
+    Post: list({
+      fields: {
+        title: text(),
+        createdAt: timestamp(), // kept as declared; no duplicate auto column
+      },
+    }),
+  }
+  ```
+
+  The decision is exposed as a pure, testable predicate `resolveListTimestamps(listConfig, dbConfig)`
+  from `@opensaas/stack-cli`, and `DatabaseConfig` is now re-exported from `@opensaas/stack-core`.
+
+- [#503](https://github.com/OpenSaasAU/stack/pull/503) [`f471e3c`](https://github.com/OpenSaasAU/stack/commit/f471e3c95eee2254ac9fde04adc8c5693240e293) Thanks [@borisno2](https://github.com/borisno2)! - Add `select()` db options for Keystone schema parity: `db.isNullable` and `db.enumName`.
+
+  `db.isNullable: true` forces the nullable `?` on the generated column even when a
+  `defaultValue` is present. The default behaviour is unchanged — a select with a
+  `defaultValue` still generates NOT NULL unless you opt in explicitly:
+
+  ```typescript
+  // Optional select with a default, kept nullable for data containing NULLs
+  status: select({
+    options: [
+      { label: 'Draft', value: 'draft' },
+      { label: 'Published', value: 'published' },
+    ],
+    defaultValue: 'draft',
+    db: { isNullable: true },
+  })
+  // Generates: status String? @default("draft")
+
+  // Enum-backed equivalent
+  status: select({
+    options: [{ label: 'Open', value: 'open' }],
+    defaultValue: 'open',
+    db: { type: 'enum', isNullable: true },
+  })
+  // Generates: status <Enum>? @default(open)
+  ```
+
+  `db.enumName` overrides the derived `<List><Field>` name of the generated Prisma
+  enum for native-enum selects, renaming both the `enum` block and every reference
+  to it in the owning model — useful for matching a live DB enum (e.g. Keystone's
+  `…Type` suffix):
+
+  ```typescript
+  status: select({
+    options: [
+      { label: 'Open', value: 'open' },
+      { label: 'Closed', value: 'closed' },
+    ],
+    db: { type: 'enum', enumName: 'AccountNoteStatusType' },
+  })
+  // Generates: enum AccountNoteStatusType { ... } and the column references it
+  ```
+
+- [#493](https://github.com/OpenSaasAU/stack/pull/493) [`acb6100`](https://github.com/OpenSaasAU/stack/commit/acb6100a078aca29e94a82ebe607d2d4f8683af2) Thanks [@borisno2](https://github.com/borisno2)! - Honour `defaultValue` for `text()`, `integer()`, and `json()` fields in the generated Prisma schema
+
+  These three field builders previously dropped `defaultValue` and emitted no `@default(...)`. They now serialise the configured default into a Prisma `@default(...)` literal via a new shared, pure `formatPrismaDefault` module, matching Keystone 6 conventions. The nullable `?` modifier is preserved independently of the default, and fields without a `defaultValue` still emit no `@default(...)`.
+
+  ```typescript
+  fields: {
+    // Int @default(3550)
+    quota: integer({ defaultValue: 3550 }),
+    // String @default("PLEASE_UPDATE")
+    status: text({ defaultValue: 'PLEASE_UPDATE' }),
+    // Json? @default("[1,2,3,4,5]") — Keystone's space-free JSON literal
+    limits: json({ defaultValue: [1, 2, 3, 4, 5] }),
+    // Json? @default("[]")
+    tags: json({ defaultValue: [] }),
+  }
+  ```
+
+  See ADR-0004 for the Keystone-compatibility rationale.
+
+- [#502](https://github.com/OpenSaasAU/stack/pull/502) [`593390c`](https://github.com/OpenSaasAU/stack/commit/593390c57d9844ca7ada8f45b340c849f1d8d647) Thanks [@{](https://github.com/{)! - Add `authPlugin` schema placement so Auth lists can adopt an existing non-`public` better-auth layout (clean-diff adoption)
+
+  The auth lists can now be placed in a non-`public` Postgres schema (e.g. `auth`) so they diff CLEAN against a separate-schema better-auth installation. A plugin-level `schema` option applies `@@schema(...)` to all generated Auth lists, with a per-list override.
+
+  ```typescript
+  authPlugin({
+    schema: 'auth', // all Auth lists get @@schema("auth")
+   modelName: 'AuthUser' },
+    session: { modelName: 'AuthSession' },
+    account: { modelName: 'AuthAccount' },
+    // per-model override: relocate one list to a different schema
+    verification: { modelName: 'AuthVerification', schema: 'auth_internal' },
+  })
+  ```
+
+  The plugin's `beforeGenerate` hook wires the datasource `schemas` array (always including `public`) and defaults any list without an explicit `db.schema` to `public`, producing a valid multi-schema Prisma schema. With no `schema` option the output is unchanged (greenfield default stays in `public`, no `@@schema`).
+
+  Core support added for this (mirroring the `db.map` → `@@map` work):
+  - List-level `db.schema` → the Prisma generator emits `@@schema("...")` on the model.
+  - Database-level `db.schemas` → the generator emits the datasource `schemas = [...]` array and enables the `multiSchema` preview feature.
+
+  ```typescript
+  // Core/generator building blocks
+  db: { provider: 'postgresql', schemas: ['public', 'auth'] }
+  AuthUser: list({ fields: { ... }, db: { map: 'AuthUser', schema: 'auth' } })
+  // Generates: model AuthUser { ... @@map("AuthUser") @@schema("auth") }
+  ```
+
+### Patch Changes
+
+- [#500](https://github.com/OpenSaasAU/stack/pull/500) [`309c666`](https://github.com/OpenSaasAU/stack/commit/309c666388b71e2bfbe16b7da3ee0f923b3bf716) Thanks [@borisno2](https://github.com/borisno2)! - Re-export the fragment query API (`defineFragment`, `runQuery`, `runQueryOne`, and the `ResultOf`, `RelationSelector`, `QueryArgs` types) from the package root so the documented `import { defineFragment, runQuery, runQueryOne, type ResultOf } from '@opensaas/stack-core'` resolves.
+
+- [#511](https://github.com/OpenSaasAU/stack/pull/511) [`696f5c0`](https://github.com/OpenSaasAU/stack/commit/696f5c08c37d4a18107e48cb6b360c9492c7425c) Thanks [@borisno2](https://github.com/borisno2)! - Fix field-level write-access bypass for multi-column `image()`/`file()` fields. The per-part column split now respects the field's own `create`/`update` access (denied fields write none of their columns), matching single-column behaviour.
+
+  Note the known lossy multi-column round-trip when assembling legacy Keystone columns: `originalFilename` collapses to `filename`, `uploadedAt` is `''`, and a NULL `contentType` reads back as `application/octet-stream`.
+
+- [#518](https://github.com/OpenSaasAU/stack/pull/518) [`d152203`](https://github.com/OpenSaasAU/stack/commit/d1522035e21b6ad7ad1b89b05264c54c13dadcf1) Thanks [@borisno2](https://github.com/borisno2)! - Remove leftover debug console.log statements from runtime code (password field resolveInput and MCP tool call handler)
+
+## 0.21.0
+
+### Minor Changes
+
+- [#415](https://github.com/OpenSaasAU/stack/pull/415) [`8980ff3`](https://github.com/OpenSaasAU/stack/commit/8980ff36ffb0879d8f4409740493dd940572cc9d) Thanks [@borisno2](https://github.com/borisno2)! - Curate the `@opensaas/stack-core` public surface into clearly-scoped entry points
+
+  The root entry point now exposes only the everyday consumer surface — `config`,
+  `list`, `getContext`, the naming helpers (`getDbKey`, `getUrlKey`,
+  `getListKeyFromUrl`), `ValidationError`, and the config/access types you annotate
+  with. Plugin and field authoring contracts move to a new `/extend` path, and the
+  plumbing shared with sibling packages and generated code moves to `/internal`.
+
+  ```typescript
+  // Everyday usage (unchanged)
+  import { config, list, getContext } from '@opensaas/stack-core'
+
+  // Authoring a plugin or a third-party field package
+  import type { Plugin, BaseFieldConfig, TypeInfo } from '@opensaas/stack-core/extend'
+  ```
+
+  `@opensaas/stack-core/internal` carries no semver guarantees; application code
+  should never import from it. `Session` stays on the root entry point because it is
+  the module-augmentation target.
+
+  Removed from the public surface (zero callers): the nine `*HookArgs` types and the
+  callerless typed-query runtime types. The other `@opensaas/*` packages and the CLI
+  generator are updated to import from the new paths.
+
+- [#416](https://github.com/OpenSaasAU/stack/pull/416) [`841a836`](https://github.com/OpenSaasAU/stack/commit/841a836494e2647f390ae19a8c4121d38ebd2fa4) Thanks [@borisno2](https://github.com/borisno2)! - Move field-config types to `@opensaas/stack-core/fields`, beside their builders
+
+  The concrete field-config types (`TextField`, `IntegerField`, `CheckboxField`,
+  `TimestampField`, `PasswordField`, `SelectField`, `RelationshipField`,
+  `JsonField`, `VirtualField`, plus `DecimalField`, `CalendarDayField`, and
+  `PrismaRelationResult`) now live on the `/fields` entry point alongside the
+  builders that produce them, instead of the root barrel. One concept, one import
+  path:
+
+  ```typescript
+  import { text, decimal } from '@opensaas/stack-core/fields'
+  import type { TextField, DecimalField } from '@opensaas/stack-core/fields'
+  ```
+
+  `DecimalField` and `CalendarDayField` were previously defined but exported from
+  nowhere — they are now public, and the CLI's lists generator maps `decimal`/
+  `calendarDay` fields to their precise types instead of the generic
+  `BaseFieldConfig` fallback. The umbrella `FieldConfig` stays on the root entry
+  point and `BaseFieldConfig` stays on `/extend`.
+
+### Patch Changes
+
+- [#441](https://github.com/OpenSaasAU/stack/pull/441) [`bc20bf4`](https://github.com/OpenSaasAU/stack/commit/bc20bf447cf724bd0ee153ea9a69d54cc26a6bb2) Thanks [@borisno2](https://github.com/borisno2)! - Validate field self-containment at config load instead of failing deep in generation
+
+  Core now exports `validateFieldConfig(field, fieldKey, listKey?)` and `validateConfigFields(config)` (plus the `FieldConfigValidationError` type). They check each field implements its generation contract — `getPrismaType`, `getTypeScriptType`, and `getZodSchema` (or `getPrismaRelation` for relationships; virtual fields skip `getPrismaType`) — and return structured per-field errors. `opensaas generate` runs this first and fails fast with a clear message naming the list, field, and missing method, rather than throwing an opaque stack trace mid-generation.
+
+- [#428](https://github.com/OpenSaasAU/stack/pull/428) [`50371ea`](https://github.com/OpenSaasAU/stack/commit/50371ea3dd134f6b3718f347fed2c0d3b7dc63ce) Thanks [@borisno2](https://github.com/borisno2)! - Fix outdated SQLite adapter guidance to match the installed `@prisma/adapter-better-sqlite3` API (`PrismaBetterSqlite3` constructed with `{ url }`), so copied examples actually run. Updates the CLI "missing adapter" error message and the migration config it generates, plus the `prismaClientConstructor` JSDoc example.
+
+- [#440](https://github.com/OpenSaasAU/stack/pull/440) [`70b4f53`](https://github.com/OpenSaasAU/stack/commit/70b4f538d380bbf546af50a985d29b48a71d3b4d) Thanks [@borisno2](https://github.com/borisno2)! - Refactor nested-operation dispatch into a handler registry (internal, no behaviour change)
+
+- [#397](https://github.com/OpenSaasAU/stack/pull/397) [`8e394ab`](https://github.com/OpenSaasAU/stack/commit/8e394abe9df2da53ba23b93836853516bb4e25d5) Thanks [@borisno2](https://github.com/borisno2)! - Move relationship Prisma schema generation into the relationship field builder
+
+  The relationship field now exposes a `getPrismaRelation()` method that returns its complete Prisma schema contribution (FK line, relation line, synthetic back-relation). The Prisma generator delegates to this method instead of special-casing relationships, keeping it a neutral coordinator. Generated schemas are unchanged.
+
+- [#455](https://github.com/OpenSaasAU/stack/pull/455) [`d3fdf2a`](https://github.com/OpenSaasAU/stack/commit/d3fdf2a2e5374302bc7fe1fe814cb0f567a349df) Thanks [@borisno2](https://github.com/borisno2)! - Exclude `**/dist/**` from Vitest test discovery and gate coverage on `src/access`, `src/context`, and `src/validation` via per-file thresholds.
+
+- [#403](https://github.com/OpenSaasAU/stack/pull/403) [`0f9c644`](https://github.com/OpenSaasAU/stack/commit/0f9c644a115ad747e338e6138b4762b4a48a9144) Thanks [@borisno2](https://github.com/borisno2)! - Split the access engine into named two-phase-read modules: Access Filter (pre-query), Field Visibility (post-query), and a shared field-access evaluator. No behaviour or public API change.
+
+- [#411](https://github.com/OpenSaasAU/stack/pull/411) [`96258b0`](https://github.com/OpenSaasAU/stack/commit/96258b00bb762d9e38cfb83eacae65ce670b161f) Thanks [@borisno2](https://github.com/borisno2)! - Deduplicate field-level hook execution helpers by promoting them to `hooks/index.ts`, and remove a stray `console.log` that ran on every create/update.
+
+- [#439](https://github.com/OpenSaasAU/stack/pull/439) [`898e477`](https://github.com/OpenSaasAU/stack/commit/898e47747abc02e457a54e2a78939450d16da5fb) Thanks [@borisno2](https://github.com/borisno2)! - Internal refactor: extract the write transform+validate span into a single Hook Pipeline that the Write Pipeline delegates to. No behaviour change.
+
+- [#438](https://github.com/OpenSaasAU/stack/pull/438) [`29966b2`](https://github.com/OpenSaasAU/stack/commit/29966b23597199bcf4233298b1d0de6401b91acd) Thanks [@borisno2](https://github.com/borisno2)! - Refactor the write path into a single Write Pipeline. The canonical secured write sequence (hooks, validation, access, writable-field filtering, nested operations, persistence, after-hooks, Field Visibility) now lives in one module; create/update/delete are thin adapters over it parameterised by a per-operation strategy. Internal refactor only — no public API or behaviour change.
+
 ## 0.20.1
 
 ## 0.20.0

package/CLAUDE.md

@@ -6,6 +6,18 @@ Core stack providing config system, access control engine, hooks, field types, a
 
 The foundation of OpenSaas Stack. Defines the config DSL, executes access control, runs hooks, and generates Prisma schema and TypeScript types from config.
 
+## Entry Points
+
+The package exposes a curated surface across several import paths. Use the narrowest one that fits:
+
+- **`@opensaas/stack-core`** (root) — the everyday consumer surface: `config`, `list`, `getContext`, the naming helpers (`getDbKey`, `getUrlKey`, `getListKeyFromUrl`), `ValidationError`, and the config/access types you annotate with (`OpenSaasConfig`, `ListConfig`, `FieldConfig`, `AccessControl`, `FieldAccess`, `Session`, `AccessContext`, `PrismaFilter`, `OperationAccess`).
+- **`@opensaas/stack-core/fields`** — field builder functions (`text()`, `integer()`, …) and their config types (`TextField`, `IntegerField`, `DecimalField`, `CalendarDayField`, …, plus `PrismaRelationResult`). The builders and the types they produce live together here.
+- **`@opensaas/stack-core/extend`** — authoring contracts: implement these to build a plugin (`Plugin`, `PluginContext`, `GeneratedFiles`) or a third-party field package (`BaseFieldConfig`, `TypeInfo`, `TypeDescriptor`).
+- **`@opensaas/stack-core/mcp`** — MCP runtime handlers.
+- **`@opensaas/stack-core/internal`** — `@internal` plumbing shared between the `@opensaas/*` packages and generated `.opensaas/` code. **No semver guarantees**; application code should never import from here.
+
+`Session` deliberately stays on the root entry point because it is the module-augmentation target (`declare module '@opensaas/stack-core'`).
+
 ## Key Files & Exports
 
 ### Config (`src/config/`)
@@ -115,12 +127,16 @@ Hook types:
 
 Run via CLI: `pnpm generate`
 
-### Utilities (`src/utils.ts`)
+### Utilities (`src/lib/case-utils.ts`)
+
+Public naming helpers (exported from the root entry point):
 
 - `getDbKey(listKey)` - PascalCase → camelCase (e.g., `BlogPost` → `blogPost`)
 - `getUrlKey(listKey)` - PascalCase → kebab-case (e.g., `BlogPost` → `blog-post`)
 - `getListKeyFromUrl(urlKey)` - kebab-case → PascalCase (e.g., `blog-post` → `BlogPost`)
 
+The lower-level converters (`pascalToCamel`, `pascalToKebab`, `kebabToPascal`, `kebabToCamel`) are internal plumbing on `@opensaas/stack-core/internal`.
+
 ## Architecture Patterns
 
 ### Field Self-Containment
@@ -157,21 +173,23 @@ const prismaType = field.getPrismaType(fieldName)
 
 1. List `resolveInput`
 2. Field `resolveInput` (e.g., hash password)
-3. List `validateInput`
-4. Field validation (isRequired, length, min/max)
-5. Field-level access control (filter writable fields)
-6. Field `beforeOperation`
-7. List `beforeOperation`
-8. **Database operation**
-9. List `afterOperation`
-10. Field `afterOperation`
+3. List `validate`
+4. Field `validate`
+5. Field validation (isRequired, length, min/max)
+6. Field-level access control (filter writable fields)
+7. Field `beforeOperation`
+8. List `beforeOperation`
+9. **Database operation**
+10. List `afterOperation`
+11. Field `afterOperation`
 
 ### Hook Execution Order (Read)
 
+Reads run no `afterOperation` (list or field):
+
 1. **Database operation**
 2. Field-level access control (filter readable fields)
 3. Field `resolveOutput`
-4. Field `afterOperation`
 
 ### Context Type Safety
 
@@ -206,7 +224,7 @@ const context = createContext<typeof prisma>(config, prisma, session)
 
 ### With Third-Party Field Packages
 
-- Packages export field builders implementing `BaseFieldConfig`
+- Packages export field builders implementing `BaseFieldConfig` (imported from `@opensaas/stack-core/extend`)
 - No changes needed to core - fields are self-contained
 - Example: `@opensaas/stack-tiptap` provides `richText()` field
 

package/dist/access/access-filter.d.ts

@@ -0,0 +1,29 @@
+import type { Session, AccessContext, PrismaFilter } from './types.js';
+import type { OpenSaasConfig, FieldConfig } from '../config/types.js';
+/**
+ * Access Filter — phase 1 of the two-phase read (pre-query).
+ *
+ * This module scopes which rows and relationships the database is allowed to
+ * return, before the query runs. It evaluates *operation-level* `query` access
+ * on related lists and turns the results into a Prisma `include`/`where` clause,
+ * so denied rows and relations never leave the database.
+ *
+ * Phase 2 (post-query field stripping + `resolveOutput` + virtual computation)
+ * lives in `field-visibility.ts`. The two phases cannot be merged: virtual
+ * fields are computed in JavaScript and post-query field access can depend on
+ * the fetched row, neither of which is expressible in SQL. See
+ * `docs/adr/0001-access-control-is-a-two-phase-read.md` and the access-control
+ * glossary in `CONTEXT.md`.
+ */
+/**
+ * Build Prisma include object with access control filters
+ * This allows us to filter relationships at the database level instead of in memory
+ */
+export declare function buildIncludeWithAccessControl(fieldConfigs: Record<string, FieldConfig>, args: {
+    session: Session | null;
+    context: AccessContext;
+}, config: OpenSaasConfig, depth?: number): Promise<Record<string, boolean | {
+    where?: PrismaFilter;
+    include?: Record<string, boolean | /*elided*/ any>;
+}> | undefined>;
+//# sourceMappingURL=access-filter.d.ts.map

package/dist/access/access-filter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"access-filter.d.ts","sourceRoot":"","sources":["../../src/access/access-filter.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AACtE,OAAO,KAAK,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAA;AAGrE;;;;;;;;;;;;;;GAcG;AAEH;;;GAGG;AACH,wBAAsB,6BAA6B,CACjD,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,EACzC,IAAI,EAAE;IACJ,OAAO,EAAE,OAAO,GAAG,IAAI,CAAA;IACvB,OAAO,EAAE,aAAa,CAAA;CACvB,EACD,MAAM,EAAE,cAAc,EACtB,KAAK,GAAE,MAAU;YAeuB,YAAY;cAAY,MAAM,CAAC,MAAM,2BAAe;gBAkD7F"}

package/dist/access/access-filter.js

@@ -0,0 +1,68 @@
+import { checkAccess, getRelatedListConfig } from './engine.js';
+/**
+ * Access Filter — phase 1 of the two-phase read (pre-query).
+ *
+ * This module scopes which rows and relationships the database is allowed to
+ * return, before the query runs. It evaluates *operation-level* `query` access
+ * on related lists and turns the results into a Prisma `include`/`where` clause,
+ * so denied rows and relations never leave the database.
+ *
+ * Phase 2 (post-query field stripping + `resolveOutput` + virtual computation)
+ * lives in `field-visibility.ts`. The two phases cannot be merged: virtual
+ * fields are computed in JavaScript and post-query field access can depend on
+ * the fetched row, neither of which is expressible in SQL. See
+ * `docs/adr/0001-access-control-is-a-two-phase-read.md` and the access-control
+ * glossary in `CONTEXT.md`.
+ */
+/**
+ * Build Prisma include object with access control filters
+ * This allows us to filter relationships at the database level instead of in memory
+ */
+export async function buildIncludeWithAccessControl(fieldConfigs, args, config, depth = 0) {
+    const MAX_DEPTH = 5;
+    if (depth >= MAX_DEPTH) {
+        return undefined;
+    }
+    // Skip auto-including relationships when inside a resolveOutput hook
+    // This prevents infinite loops when hooks make DB queries that include
+    // relationships back to the same entity (e.g., User virtual field queries Posts
+    // which includes author back to User, triggering the virtual field again)
+    if (args.context._resolveOutputCounter.depth > 0) {
+        return undefined;
+    }
+    const include = {};
+    let hasRelationships = false;
+    for (const [fieldName, fieldConfig] of Object.entries(fieldConfigs)) {
+        if (fieldConfig?.type === 'relationship' && 'ref' in fieldConfig && fieldConfig.ref) {
+            hasRelationships = true;
+            const relatedConfig = getRelatedListConfig(fieldConfig.ref, config);
+            if (relatedConfig) {
+                // Check query access for the related list
+                const queryAccess = relatedConfig.listConfig.access?.operation?.query;
+                const accessResult = await checkAccess(queryAccess, {
+                    session: args.session,
+                    context: args.context,
+                });
+                // If access is completely denied, exclude this relationship
+                if (accessResult === false) {
+                    continue;
+                }
+                // Build the include entry
+                const includeEntry = {};
+                // If access returns a filter, add it to the where clause
+                if (typeof accessResult === 'object') {
+                    includeEntry.where = accessResult;
+                }
+                // Recursively build nested includes
+                const nestedInclude = await buildIncludeWithAccessControl(relatedConfig.listConfig.fields, args, config, depth + 1);
+                if (nestedInclude && Object.keys(nestedInclude).length > 0) {
+                    includeEntry.include = nestedInclude;
+                }
+                // Add to include object
+                include[fieldName] = Object.keys(includeEntry).length > 0 ? includeEntry : true;
+            }
+        }
+    }
+    return hasRelationships ? include : undefined;
+}
+//# sourceMappingURL=access-filter.js.map

package/dist/access/access-filter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"access-filter.js","sourceRoot":"","sources":["../../src/access/access-filter.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,WAAW,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAA;AAE/D;;;;;;;;;;;;;;GAcG;AAEH;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,6BAA6B,CACjD,YAAyC,EACzC,IAGC,EACD,MAAsB,EACtB,QAAgB,CAAC;IAEjB,MAAM,SAAS,GAAG,CAAC,CAAA;IACnB,IAAI,KAAK,IAAI,SAAS,EAAE,CAAC;QACvB,OAAO,SAAS,CAAA;IAClB,CAAC;IAED,qEAAqE;IACrE,uEAAuE;IACvE,gFAAgF;IAChF,0EAA0E;IAC1E,IAAI,IAAI,CAAC,OAAO,CAAC,qBAAqB,CAAC,KAAK,GAAG,CAAC,EAAE,CAAC;QACjD,OAAO,SAAS,CAAA;IAClB,CAAC;IAID,MAAM,OAAO,GAAiC,EAAE,CAAA;IAChD,IAAI,gBAAgB,GAAG,KAAK,CAAA;IAE5B,KAAK,MAAM,CAAC,SAAS,EAAE,WAAW,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,YAAY,CAAC,EAAE,CAAC;QACpE,IAAI,WAAW,EAAE,IAAI,KAAK,cAAc,IAAI,KAAK,IAAI,WAAW,IAAI,WAAW,CAAC,GAAG,EAAE,CAAC;YACpF,gBAAgB,GAAG,IAAI,CAAA;YACvB,MAAM,aAAa,GAAG,oBAAoB,CAAC,WAAW,CAAC,GAAa,EAAE,MAAM,CAAC,CAAA;YAE7E,IAAI,aAAa,EAAE,CAAC;gBAClB,0CAA0C;gBAC1C,MAAM,WAAW,GAAG,aAAa,CAAC,UAAU,CAAC,MAAM,EAAE,SAAS,EAAE,KAAK,CAAA;gBACrE,MAAM,YAAY,GAAG,MAAM,WAAW,CAAC,WAAW,EAAE;oBAClD,OAAO,EAAE,IAAI,CAAC,OAAO;oBACrB,OAAO,EAAE,IAAI,CAAC,OAAO;iBACtB,CAAC,CAAA;gBAEF,4DAA4D;gBAC5D,IAAI,YAAY,KAAK,KAAK,EAAE,CAAC;oBAC3B,SAAQ;gBACV,CAAC;gBAED,0BAA0B;gBAC1B,MAAM,YAAY,GAA4B,EAAE,CAAA;gBAEhD,yDAAyD;gBACzD,IAAI,OAAO,YAAY,KAAK,QAAQ,EAAE,CAAC;oBACrC,YAAY,CAAC,KAAK,GAAG,YAAY,CAAA;gBACnC,CAAC;gBAED,oCAAoC;gBACpC,MAAM,aAAa,GAAG,MAAM,6BAA6B,CACvD,aAAa,CAAC,UAAU,CAAC,MAAM,EAC/B,IAAI,EACJ,MAAM,EACN,KAAK,GAAG,CAAC,CACV,CAAA;gBAED,IAAI,aAAa,IAAI,MAAM,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;oBAC3D,YAAY,CAAC,OAAO,GAAG,aAAa,CAAA;gBACtC,CAAC;gBAED,wBAAwB;gBACxB,OAAO,CAAC,SAAS,CAAC,GAAG,MAAM,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,IAAI,CAAA;YACjF,CAAC;QACH,CAAC;IACH,CAAC;IAED,OAAO,gBAAgB,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,SAAS,CAAA;AAC/C,CAAC"}

package/dist/access/engine.d.ts

@@ -1,6 +1,19 @@
 import type { AccessControl, Session, AccessContext, PrismaFilter } from './types.js';
-import type { FieldAccess } from './types.js';
-import type { OpenSaasConfig, ListConfig, FieldConfig } from '../config/types.js';
+import type { OpenSaasConfig, ListConfig } from '../config/types.js';
+/**
+ * Access engine — operation-level access control and shared helpers.
+ *
+ * This module holds the *operation-level* (list-level) access primitives and
+ * the ref-parsing helper shared across both phases of the two-phase read:
+ *
+ *   - Phase 1, Access Filter (pre-query row/relation scoping): `access-filter.ts`
+ *   - Phase 2, Field Visibility (post-query field stripping + resolveOutput +
+ *     virtual fields): `field-visibility.ts`
+ *
+ * Field-level access evaluation is centralized in `field-access.ts`
+ * (`checkFieldAccess`). See `docs/adr/0001-access-control-is-a-two-phase-read.md`
+ * and the access-control glossary in `CONTEXT.md`.
+ */
 /**
  * Check if access control result is a boolean
  */
@@ -33,50 +46,4 @@ export declare function checkAccess<T = Record<string, unknown>>(accessControl:
  * Merge user filter with access control filter
  */
 export declare function mergeFilters(userFilter: PrismaFilter | undefined, accessFilter: boolean | PrismaFilter): PrismaFilter | null;
-/**
- * Check field-level access for a specific operation
- */
-export declare function checkFieldAccess(fieldAccess: FieldAccess | undefined, operation: 'read' | 'create' | 'update', args: {
-    session: Session | null;
-    item?: Record<string, unknown>;
-    context: AccessContext & {
-        _isSudo?: boolean;
-    };
-    inputData?: Record<string, unknown>;
-}): Promise<boolean>;
-/**
- * Build Prisma include object with access control filters
- * This allows us to filter relationships at the database level instead of in memory
- */
-export declare function buildIncludeWithAccessControl(fieldConfigs: Record<string, FieldConfig>, args: {
-    session: Session | null;
-    context: AccessContext;
-}, config: OpenSaasConfig, depth?: number): Promise<Record<string, boolean | {
-    where?: PrismaFilter;
-    include?: Record<string, boolean | /*elided*/ any>;
-}> | undefined>;
-/**
- * Filter fields from an object based on read access
- * Recursively applies access control to nested relationships
- */
-export declare function filterReadableFields<T extends Record<string, unknown>>(item: T, fieldConfigs: Record<string, FieldConfig>, args: {
-    session: Session | null;
-    context: AccessContext & {
-        _isSudo?: boolean;
-    };
-}, config?: OpenSaasConfig, depth?: number, listKey?: string): Promise<Partial<T>>;
-/**
- * Filter fields from input data based on write access (create/update)
- */
-export declare function filterWritableFields<T extends Record<string, unknown>>(data: T, fieldConfigs: Record<string, {
-    access?: FieldAccess;
-    type?: string;
-}>, operation: 'create' | 'update', args: {
-    session: Session | null;
-    item?: Record<string, unknown>;
-    context: AccessContext & {
-        _isSudo?: boolean;
-    };
-    inputData?: Record<string, unknown>;
-}): Promise<Partial<T>>;
 //# sourceMappingURL=engine.d.ts.map

package/dist/access/engine.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../../src/access/engine.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../../src/access/engine.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,OAAO,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AACrF,OAAO,KAAK,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAA;AAEpE;;;;;;;;;;;;;GAaG;AAEH;;GAEG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,OAAO,CAE1D;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,YAAY,CAEpE;AAED;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAClC,eAAe,EAAE,MAAM,EACvB,MAAM,EAAE,cAAc,GAErB;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,UAAU,CAAC,GAAG,CAAC,CAAA;CAAE,GAAG,IAAI,CAe1D;AAED;;GAEG;AACH,wBAAsB,WAAW,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC3D,aAAa,EAAE,aAAa,CAAC,CAAC,CAAC,GAAG,SAAS,EAC3C,IAAI,EAAE;IACJ,OAAO,EAAE,OAAO,GAAG,IAAI,CAAA;IACvB,IAAI,CAAC,EAAE,CAAC,CAAA;IACR,OAAO,EAAE,aAAa,CAAA;CACvB,GACA,OAAO,CAAC,OAAO,GAAG,YAAY,CAAC,CAAC,CAAC,CAAC,CAUpC;AAED;;GAEG;AACH,wBAAgB,YAAY,CAC1B,UAAU,EAAE,YAAY,GAAG,SAAS,EACpC,YAAY,EAAE,OAAO,GAAG,YAAY,GACnC,YAAY,GAAG,IAAI,CAoBrB"}