@opensaas/stack-core 0.39.2 → 0.41.0

package/src/context/write-pipeline.ts

@@ -2,6 +2,7 @@ import type { OpenSaasConfig, ListConfig } from '../config/types.js'
 import type { AccessContext, PrismaClientLike } from '../access/types.js'
 import {
   checkAccess,
+  checkCreateAccess,
   mergeFilters,
   filterReadableFields,
   filterWritableFields,
@@ -22,10 +23,11 @@ import { enumerateInvolvedLists, runWithTransactionBoundary } from './transactio
 import { TransactionRegistry } from '../access/transaction-registry.js'
 import { getDbKey } from '../lib/case-utils.js'
 // NOTE: `index.ts` imports from this module too — this is an intentional cyclic
-// dependency. It is safe because `buildDbDelegate` is only INVOKED at write
-// time (never during module evaluation), so by the time it runs the export is
-// fully initialised.
-import { buildDbDelegate } from './index.js'
+// dependency. It is safe because `getContext` is only INVOKED at write time
+// (never during module evaluation), so by the time it runs the export is fully
+// initialised.
+import { getContext } from './index.js'
+import type { StackContext } from './index.js'
 
 /**
  * Write Pipeline — runs the canonical, secured write sequence for one
@@ -165,6 +167,22 @@ export interface WritePipelineArgs<TPrisma extends PrismaClientLike> {
   preResolvedTarget?: TargetResolution
 }
 
+/**
+ * {@link WritePipelineArgs} narrowed to the in-transaction phase: `context` is
+ * the full {@link StackContext} `bindContextToTransaction` rebuilds (issue
+ * #1176), not the plain {@link AccessContext} the pre-transaction gate and the
+ * transaction-boundary hooks use. `StackContext` is a structural superset of
+ * `AccessContext` (it carries `_resolveOutputChain`/`_transactionOwner` too),
+ * so nothing downstream of {@link runWriteInTransaction} that only needs
+ * `AccessContext` requires any change.
+ */
+type WriteInTransactionArgs<TPrisma extends PrismaClientLike> = Omit<
+  WritePipelineArgs<TPrisma>,
+  'context'
+> & {
+  context: StackContext<TPrisma>
+}
+
 /**
  * Run the canonical secured write sequence once. Phase order matches the
  * "Write Pipeline" glossary entry in CONTEXT.md.
@@ -241,41 +259,44 @@ export async function runWritePipeline<TPrisma extends PrismaClientLike>(
 }
 
 /**
- * Build an {@link AccessContext} whose `db`/`prisma` target the transaction
- * client `tx`, so a `context.db` write a hook performs runs inside — and rolls
- * back with — this write's transaction (ADR-0010).
+ * Build the full {@link StackContext} a hook's `context` is (issue #1176):
+ * bound to the transaction client `tx`, so a `context.db` write a hook
+ * performs runs inside — and rolls back with — this write's transaction
+ * (ADR-0010), and carrying `sudo()`/`withSession()`/`transaction()` so a hook
+ * can reach an elevated or substituted read/write that stays on the SAME
+ * transaction client rather than escaping to the base one.
  *
- * The access-controlled `db` delegates capture their Prisma client at
- * construction, so swapping `context.prisma` alone would not rebind `db` — we
- * rebuild the delegates against `tx` via {@link buildDbDelegate}, reusing the
- * request context's `session`, `storage`, `plugins`, `_isSudo`, and
- * `_resolveOutputChain` as-is (so a write from inside a `resolveOutput` hook
- * keeps that hook's chain). Plugin runtimes are NOT re-executed.
+ * Goes through the same {@link getContext} factory `context.transaction()`
+ * already rebuilds through (ADR-0012), rather than hand-assembling a plain
+ * object literal — reusing the request context's `session`, `storage`,
+ * `_isSudo`, `plugins` (as `_sharedPlugins`, so plugin `runtime()` is NOT
+ * re-executed on the rebind), and `_resolveOutputChain` (so a write issued
+ * from inside a `resolveOutput` hook keeps that hook's cycle-guard chain,
+ * ADR-0023) as-is.
  *
  * `transactionOwner` (ADR-0028) is carried onto the rebuilt context so a hook's
- * own `context.db` write defers its transaction-boundary bracket to that owner
- * instead of firing eagerly.
+ * own `context.db` write — and any write reached through its `sudo()`/
+ * `withSession()` — defers its transaction-boundary bracket to that owner
+ * instead of firing eagerly; `context.transaction()` called from a hook joins
+ * this same owner rather than opening a nested transaction, for the same
+ * reason.
  */
 function bindContextToTransaction<TPrisma extends PrismaClientLike>(
   args: WritePipelineArgs<TPrisma>,
   tx: TPrisma,
   transactionOwner: TransactionRegistry | undefined,
-): AccessContext<TPrisma> {
+): StackContext<TPrisma> {
   const { context, config } = args
-  const txContext: AccessContext<TPrisma> = {
-    session: context.session,
-    prisma: tx,
-    db: context.db,
-    storage: context.storage,
-    plugins: context.plugins,
-    _isSudo: context._isSudo,
-    _resolveOutputChain: context._resolveOutputChain,
-    _transactionOwner: transactionOwner,
-  }
-  // Rebuild `db` against `tx`, referencing `txContext` itself so hooks reached
-  // through it see the transactional context.
-  txContext.db = buildDbDelegate(config, tx, txContext)
-  return txContext
+  return getContext(
+    config,
+    tx,
+    context.session,
+    context.storage,
+    context._isSudo,
+    context.plugins,
+    transactionOwner,
+    context._resolveOutputChain,
+  )
 }
 
 /**
@@ -285,7 +306,7 @@ function bindContextToTransaction<TPrisma extends PrismaClientLike>(
  * `runInTransaction` and rolls the transaction back.
  */
 async function runWriteInTransaction<TPrisma extends PrismaClientLike>(
-  args: WritePipelineArgs<TPrisma>,
+  args: WriteInTransactionArgs<TPrisma>,
 ): Promise<Record<string, unknown> | null> {
   const { listName, listConfig, prisma: tx, context, config, inputData, strategy } = args
   const { operation } = strategy
@@ -330,6 +351,8 @@ async function runWriteInTransaction<TPrisma extends PrismaClientLike>(
     item: originalItem,
     context: { ...context, _isSudo: context._isSudo },
     inputData: input,
+    listName,
+    config,
   })
 
   // ── Phase 5.5: process nested relationship operations ───────────────────────
@@ -482,7 +505,7 @@ async function runDeletePath(args: {
   listName: string
   // eslint-disable-next-line @typescript-eslint/no-explicit-any -- ListConfig must accept any TypeInfo
   listConfig: ListConfig<any>
-  context: AccessContext
+  context: StackContext
   originalItem: Record<string, unknown> | undefined
   model: PrismaModel
   strategy: WriteStrategy
@@ -560,8 +583,9 @@ async function runDeletePath(args: {
  * Create strategy for {@link WriteStrategy}.
  *
  * Axis 1: checks `create` access with no existing row; a filter result
- * proceeds with no re-check (unlike update/delete). Enforces the
- * singleton-create constraint even under sudo.
+ * throws `InvalidCreateAccessResultError` rather than proceeding unchecked —
+ * create has no row to re-check a filter against, unlike update/delete
+ * (#1009). Enforces the singleton-create constraint even under sudo.
  * Axis 2: runs all input phases.
  * Axis 3: `model.create({ data })`, prepending `id: 1` for singleton lists.
  */
@@ -588,11 +612,11 @@ export function createWriteStrategy(
       }
 
       if (!context._isSudo) {
-        const accessResult = await checkAccess(listConfig.access?.operation?.create, {
+        const allowed = await checkCreateAccess(listName, listConfig.access?.operation?.create, {
           session: context.session,
           context,
         })
-        if (accessResult === false) {
+        if (!allowed) {
           return { status: 'denied' }
         }
       }

package/src/fields/index.ts

@@ -229,9 +229,16 @@ export function integer<
         modifiers += ` @map("${db.map}")`
       }
 
+      // Unique modifier — non-unique index routes through `index` below,
+      // same as `text()`'s getPrismaType.
+      if (options?.isIndexed === 'unique') {
+        modifiers += ' @unique'
+      }
+
       return {
         type: 'Int',
         modifiers: modifiers.trimStart() || undefined,
+        index: options?.isIndexed === true ? true : undefined,
       }
     },
     getTypeScriptType: () => {
@@ -657,9 +664,16 @@ export function timestamp<
         modifiers += ` @map("${db.map}")`
       }
 
+      // Unique modifier — non-unique index routes through `index` below,
+      // same as `text()`'s getPrismaType.
+      if (options?.isIndexed === 'unique') {
+        modifiers += ' @unique'
+      }
+
       return {
         type: 'DateTime',
         modifiers: modifiers.trimStart() || undefined,
+        index: options?.isIndexed === true ? true : undefined,
       }
     },
     getTypeScriptType: () => {
@@ -930,7 +944,10 @@ function formatCalendarDay(value: unknown): string | null | undefined {
  * ```
  *
  * **Important Notes:**
- * - Password fields are excluded from read operations by default in access control
+ * - Password field values are redacted to `{ isSet: boolean }` on serialization
+ *   (`JSON.stringify`, the admin UI). Field-level `read` access is not denied by
+ *   default — configure `access.field.read` if the raw value should never reach
+ *   `context.db` callers at all.
  * - Always use the `compare()` method to verify passwords - never compare strings directly
  * - The password field value has type `HashedPassword` which extends string with compare()
  * - Empty strings and undefined values are skipped (not hashed) to allow partial updates
@@ -955,6 +972,13 @@ export function password<TTypeInfo extends import('../config/types.js').TypeInfo
     },
     ui: {
       ...options?.ui,
+      // Excluded from default admin table columns (issue #1018) — declared
+      // via the flag rather than matched by field type/name, so an app can
+      // still opt a real password field back in with `ui.listView.defaultColumn: true`.
+      listView: {
+        defaultColumn: false,
+        ...options?.ui?.listView,
+      },
       valueForClientSerialization: ({ value }) => ({ isSet: !!value }),
     },
     hooks: {
@@ -1129,10 +1153,17 @@ export function select<
           modifiers += ` @map("${options.db.map}")`
         }
 
+        // Unique modifier — non-unique index routes through `index` below,
+        // same as `text()`'s getPrismaType.
+        if (options.isIndexed === 'unique') {
+          modifiers += ' @unique'
+        }
+
         return {
           type: enumName,
           modifiers: modifiers || undefined,
           enumValues: options.options.map((opt) => opt.value),
+          index: options.isIndexed === true ? true : undefined,
         }
       }
 
@@ -1146,9 +1177,14 @@ export function select<
         modifiers += ` @map("${options.db.map}")`
       }
 
+      if (options.isIndexed === 'unique') {
+        modifiers += ' @unique'
+      }
+
       return {
         type: 'String',
         modifiers: modifiers || undefined,
+        index: options.isIndexed === true ? true : undefined,
       }
     },
     getTypeScriptType: () => {
@@ -1366,6 +1402,18 @@ function computeManyToManyRelationName(
   return undefined
 }
 
+/**
+ * The name Prisma generation synthesizes for the back-relation a list-only
+ * `ref` (`ref: 'ListName'`, no target field) creates on its target model —
+ * Prisma requires an opposite field, and the config never declares one.
+ * Exported so runtime nested-write resolution (`resolveSyntheticReverseRelation`
+ * in `access/engine.ts`) can recognise the same name rather than re-deriving
+ * the format by string parsing (#978).
+ */
+export function getSyntheticFieldName(listKey: string, fieldName: string): string {
+  return `from_${listKey}_${fieldName}`
+}
+
 function getPrismaRelation(
   field: RelationshipField,
   fieldName: string,
@@ -1378,7 +1426,7 @@ function getPrismaRelation(
   // Synthetic back-relation for list-only refs (Prisma requires an opposite field)
   let backRelation: PrismaRelationResult['backRelation']
   if (!targetField) {
-    const syntheticFieldName = `from_${listKey}_${fieldName}`
+    const syntheticFieldName = getSyntheticFieldName(listKey, fieldName)
     const relationName = field.db?.relationName ?? `${listKey}_${fieldName}`
     backRelation = {
       targetList,
@@ -1494,10 +1542,12 @@ export function relationship<
       )
     }
 
-    if (refParts.length === 1) {
+    if (refParts.length === 1 && typeof options.db.foreignKey === 'boolean') {
       throw new Error(
-        'db.foreignKey can only be used on bidirectional relationships (ref: "ListName.fieldName"). ' +
-          'List-only refs (ref: "ListName") always create foreign keys automatically.',
+        'db.foreignKey cannot be a boolean on list-only refs (ref: "ListName"). ' +
+          'List-only refs always create foreign keys automatically, so the ownership sense of ' +
+          'db.foreignKey is meaningless here. Use db.foreignKey: { map: "columnName" } to rename ' +
+          'the foreign key column instead.',
       )
     }
   }

package/src/fields/relationship-foreign-key.test.ts

@@ -0,0 +1,29 @@
+import { describe, it, expect } from 'vitest'
+import { relationship } from './index.js'
+
+describe('relationship field builder: db.foreignKey validation', () => {
+  it('rejects a boolean db.foreignKey on a list-only ref', () => {
+    expect(() => relationship({ ref: 'User', db: { foreignKey: true } })).toThrow(
+      'db.foreignKey cannot be a boolean on list-only refs',
+    )
+    expect(() => relationship({ ref: 'User', db: { foreignKey: false } })).toThrow(
+      'db.foreignKey cannot be a boolean on list-only refs',
+    )
+  })
+
+  it('allows an object db.foreignKey (map) on a list-only ref', () => {
+    expect(() =>
+      relationship({ ref: 'User', db: { foreignKey: { map: 'user_id' } } }),
+    ).not.toThrow()
+  })
+
+  it('still allows a boolean db.foreignKey on a bidirectional ref', () => {
+    expect(() => relationship({ ref: 'User.posts', db: { foreignKey: true } })).not.toThrow()
+  })
+
+  it('still rejects db.foreignKey on a many relationship regardless of ref shape', () => {
+    expect(() =>
+      relationship({ ref: 'User', many: true, db: { foreignKey: { map: 'user_id' } } }),
+    ).toThrow('db.foreignKey can only be used on single relationships')
+  })
+})

package/src/hooks/index.ts

@@ -1,6 +1,13 @@
 import type { Hooks } from '../config/types.js'
 import type { AccessContext } from '../access/types.js'
 import type { FieldConfig } from '../config/types.js'
+// #1176: resolveInput/validate/beforeOperation/afterOperation (list AND field
+// level) receive the full secured `StackContext` — sudo()/withSession()/
+// transaction() bound to the write's own transaction client — not the plain
+// `AccessContext`. Transaction-boundary hooks (beforeTransaction/
+// afterTransaction) are unaffected: they stay on `AccessContext`/the base
+// client by ADR-0028 design.
+import type { StackContext } from '../context/index.js'
 import { validateWithZod } from '../validation/schema.js'
 import { checkFieldAccess } from '../access/field-access.js'
 
@@ -42,7 +49,7 @@ export async function executeResolveInput<
         inputData: TCreateInput
         resolvedData: TCreateInput
         item: undefined
-        context: AccessContext
+        context: StackContext
       }
     | {
         listKey: string
@@ -50,7 +57,7 @@ export async function executeResolveInput<
         inputData: TUpdateInput
         resolvedData: TUpdateInput
         item: TOutput
-        context: AccessContext
+        context: StackContext
       },
 ): Promise<TCreateInput | TUpdateInput> {
   if (!hooks?.resolveInput) {
@@ -75,7 +82,7 @@ export async function executeValidate<
         inputData: TCreateInput
         resolvedData: TCreateInput
         item: undefined
-        context: AccessContext
+        context: StackContext
       }
     | {
         listKey: string
@@ -83,13 +90,13 @@ export async function executeValidate<
         inputData: TUpdateInput
         resolvedData: TUpdateInput
         item: TOutput
-        context: AccessContext
+        context: StackContext
       }
     | {
         listKey: string
         operation: 'delete'
         item: TOutput
-        context: AccessContext
+        context: StackContext
       },
 ): Promise<void> {
   const validateHook = hooks?.validate || hooks?.validateInput
@@ -131,7 +138,7 @@ export async function executeBeforeOperation<
         operation: 'create'
         inputData: TCreateInput
         resolvedData: TCreateInput
-        context: AccessContext
+        context: StackContext
       }
     | {
         listKey: string
@@ -139,13 +146,13 @@ export async function executeBeforeOperation<
         inputData: TUpdateInput
         item: TOutput
         resolvedData: TUpdateInput
-        context: AccessContext
+        context: StackContext
       }
     | {
         listKey: string
         operation: 'delete'
         item: TOutput
-        context: AccessContext
+        context: StackContext
       },
 ): Promise<void> {
   if (!hooks?.beforeOperation) {
@@ -168,7 +175,7 @@ export async function executeAfterOperation<
         inputData: TCreateInput
         item: TOutput
         resolvedData: TCreateInput
-        context: AccessContext
+        context: StackContext
       }
     | {
         listKey: string
@@ -177,13 +184,13 @@ export async function executeAfterOperation<
         originalItem: TOutput
         item: TOutput
         resolvedData: TUpdateInput
-        context: AccessContext
+        context: StackContext
       }
     | {
         listKey: string
         operation: 'delete'
         originalItem: TOutput
-        context: AccessContext
+        context: StackContext
       },
 ): Promise<void> {
   if (!hooks?.afterOperation) {
@@ -472,7 +479,7 @@ export async function executeFieldResolveInputHooks(
   resolvedData: Record<string, any>,
   fields: Record<string, FieldConfig>,
   operation: 'create' | 'update',
-  context: AccessContext,
+  context: StackContext,
   listKey: string,
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
   item?: any,
@@ -575,7 +582,7 @@ export async function executeFieldValidateHooks(
   resolvedData: Record<string, any> | undefined,
   fields: Record<string, FieldConfig>,
   operation: 'create' | 'update' | 'delete',
-  context: AccessContext,
+  context: StackContext,
   listKey: string,
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
   item?: any,
@@ -640,7 +647,7 @@ export async function executeFieldBeforeOperationHooks(
   resolvedData: Record<string, any>,
   fields: Record<string, FieldConfig>,
   operation: 'create' | 'update' | 'delete',
-  context: AccessContext,
+  context: StackContext,
   listKey: string,
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
   item?: any,
@@ -687,7 +694,7 @@ export async function executeFieldAfterOperationHooks(
   resolvedData: Record<string, unknown> | undefined,
   fields: Record<string, FieldConfig>,
   operation: 'create' | 'update' | 'delete',
-  context: AccessContext,
+  context: StackContext,
   listKey: string,
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
   originalItem?: any,

package/src/index.ts

@@ -50,7 +50,7 @@ export type {
 } from './context/index.js'
 
 // Naming utilities (documented public helpers; used for URLs and db keys)
-export { getDbKey, getUrlKey, getListKeyFromUrl } from './lib/case-utils.js'
+export { getDbKey, getUrlKey, getListKeyFromUrl, resolveListKeyFromUrl } from './lib/case-utils.js'
 
 // Label seam — resolves the field that represents a row as a single label
 // (projection) and reads it off a row (render). Used by the admin UI for
@@ -64,6 +64,14 @@ export { resolveNavCounts, isListQueryStaticallyDenied } from './config/nav-coun
 // Validation error surfaced by write operations
 export { ValidationError } from './hooks/index.js'
 
+// Resolves which columns (and, where recoverable, which named constraint) a
+// caught P2002 unique-constraint violation hit — normalising Prisma 7 driver
+// adapters' undocumented error shape to the documented `meta.target` one, so
+// a caller of `context.db.*` never needs to reach into adapter internals
+// (see issue #979).
+export { uniqueConstraintOf } from './lib/prisma-errors.js'
+export type { UniqueConstraintInfo } from './lib/prisma-errors.js'
+
 // Thrown by a read when a caller-supplied `include` names a relation nested
 // deeper than the Access Filter can scope (see ADR-0022). Distinct from
 // `ValidationError` — this is the engine refusing to return unscoped data, not
@@ -83,6 +91,14 @@ export { ResolveOutputCycleError } from './access/index.js'
 // validation failure.
 export { InvalidFieldAccessResultError } from './access/index.js'
 
+// Thrown by the write pipeline's create strategy and by the nested-create
+// path when operation-level `create` access returns anything other than a
+// strict boolean (see #1009, ADR-0022, and ADR-0030). A filter — the shape
+// `query`/`update`/`delete` legitimately return — cannot be honoured on
+// create: there is no existing row and no way to test it against input data,
+// so it is refused loudly rather than silently treated as a full allow.
+export { InvalidCreateAccessResultError } from './access/index.js'
+
 // Thrown by a read when a caller-supplied `where` filters on a relation whose
 // related list denies operation-level `query` access outright (see #916 and
 // ADR-0022). Distinct from `ValidationError` for the same reason as

package/src/lib/case-utils.test.ts

@@ -7,6 +7,7 @@ import {
   getDbKey,
   getUrlKey,
   getListKeyFromUrl,
+  resolveListKeyFromUrl,
 } from './case-utils.js'
 
 describe('Case Conversion Utilities', () => {
@@ -97,6 +98,37 @@ describe('Case Conversion Utilities', () => {
     })
   })
 
+  describe('resolveListKeyFromUrl', () => {
+    it('resolves a PascalCase list key from its URL segment', () => {
+      expect(resolveListKeyFromUrl('blog-post', ['User', 'BlogPost'])).toBe('BlogPost')
+    })
+
+    it('resolves a camelCase list key (e.g. a derived plugin list) from its URL segment', () => {
+      // getListKeyFromUrl('oauth-application') would reconstruct 'OauthApplication',
+      // which isn't a key in this list — that's the bug this resolver fixes.
+      expect(resolveListKeyFromUrl('oauth-application', ['oauthApplication'])).toBe(
+        'oauthApplication',
+      )
+    })
+
+    it('returns undefined for a URL segment matching no list key', () => {
+      expect(resolveListKeyFromUrl('does-not-exist', ['User', 'BlogPost'])).toBeUndefined()
+    })
+
+    it('throws when two distinct list keys produce the same URL segment', () => {
+      expect(() =>
+        resolveListKeyFromUrl('oauth-application', ['oauthApplication', 'OauthApplication']),
+      ).toThrow(/Ambiguous list URL/)
+    })
+
+    it('is derived from getUrlKey, so it cannot drift from how URLs are built', () => {
+      const listKeys = ['User', 'AuthUser', 'BlogPost', 'oauthApplication']
+      for (const listKey of listKeys) {
+        expect(resolveListKeyFromUrl(getUrlKey(listKey), listKeys)).toBe(listKey)
+      }
+    })
+  })
+
   describe('Round-trip conversions', () => {
     it('should maintain consistency: PascalCase -> kebab-case -> PascalCase', () => {
       const original = 'BlogPost'

package/src/lib/case-utils.ts

@@ -40,3 +40,29 @@ export function getUrlKey(listKey: string): string {
 export function getListKeyFromUrl(urlSegment: string): string {
   return kebabToPascal(urlSegment)
 }
+
+/**
+ * Resolves a URL segment back to the list key that produced it, by checking
+ * each candidate key against `getUrlKey` — the same helper that builds the
+ * URL — rather than reconstructing a key by string transformation the way
+ * `getListKeyFromUrl` does. That reconstruction is lossy for any list key
+ * that isn't strict PascalCase (e.g. a camelCase key from a derived list),
+ * so this is the config-aware resolver route lookups should use instead.
+ *
+ * Returns `undefined` when no candidate key's URL matches — callers render
+ * their usual "not found" state rather than treating this as an error.
+ * Throws if more than one candidate key produces the same URL segment: that
+ * is a configuration error (two list keys collide once case-folded to a
+ * URL) and must be reported, not resolved by silently picking one.
+ */
+export function resolveListKeyFromUrl(urlSegment: string, listKeys: string[]): string | undefined {
+  const matches = listKeys.filter((listKey) => getUrlKey(listKey) === urlSegment)
+
+  if (matches.length > 1) {
+    throw new Error(
+      `Ambiguous list URL "${urlSegment}": list keys ${matches.map((key) => `"${key}"`).join(', ')} all resolve to this URL. Rename these lists so their URLs are unique.`,
+    )
+  }
+
+  return matches[0]
+}

package/src/lib/prisma-errors.ts

@@ -0,0 +1,86 @@
+type PrismaP2002Meta = {
+  target?: string[]
+  driverAdapterError?: {
+    cause?: {
+      originalMessage?: string
+      constraint?: { fields?: unknown[] }
+    }
+  }
+}
+
+// Postgres quotes an identifier in `constraint.fields` only when it needed
+// quoting (e.g. camelCase columns), so `"tenantId"` and `slug` are both valid
+// entries for the same array.
+function stripIdentifierQuotes(field: string): string {
+  const match = field.match(/^"(.*)"$/)
+  return match ? match[1] : field
+}
+
+export interface UniqueConstraintInfo {
+  /** Column names covered by the violated constraint, quote-stripped. */
+  fields: string[]
+  /**
+   * The violated constraint's name, when recoverable from the error.
+   *
+   * Known limit: this is parsed out of Postgres' English-locale error text
+   * (`cause.originalMessage`) — the adapter exposes no structured field for
+   * it. A server running under a non-English `lc_messages` locale will not
+   * match, leaving this `undefined` while `fields` (structured data) still
+   * resolves correctly.
+   */
+  constraintName?: string
+}
+
+/**
+ * Resolve which columns — and, where recoverable, which named constraint — a
+ * Prisma `P2002` unique-constraint violation hit.
+ *
+ * Prisma documents `error.meta.target` for this. Under Prisma 7 driver
+ * adapters (verified against `@prisma/adapter-pg` and PGlite; see issue #979)
+ * that field is `undefined` instead — the same information sits at
+ * `error.meta.driverAdapterError.cause`, with the constraint name only
+ * recoverable as free text inside `cause.originalMessage`. This normalises
+ * both shapes to one stable result so callers never need to reach into that
+ * adapter-specific structure themselves.
+ *
+ * A derived constraint name is truncated by Postgres at its 63-character
+ * identifier limit, and one row can violate two unique indexes at once (with
+ * Postgres reporting whichever it checked first) — an index an application
+ * means to branch on should be named explicitly, and a caller may still need
+ * to re-read the colliding row to fully disambiguate.
+ *
+ * Returns `undefined` when `error` isn't a `P2002` with any recoverable
+ * column or constraint information — never throws, since the adapter error
+ * shape is untrusted and every level of it may be absent.
+ */
+export function uniqueConstraintOf(error: unknown): UniqueConstraintInfo | undefined {
+  if (
+    !error ||
+    typeof error !== 'object' ||
+    !('code' in error) ||
+    (error as { code?: unknown }).code !== 'P2002'
+  ) {
+    return undefined
+  }
+
+  const meta = (error as { meta?: PrismaP2002Meta }).meta
+
+  if (meta?.target && Array.isArray(meta.target)) {
+    return { fields: meta.target }
+  }
+
+  const cause = meta?.driverAdapterError?.cause
+  const rawFields = cause?.constraint?.fields
+  const fields = Array.isArray(rawFields)
+    ? rawFields.filter((f): f is string => typeof f === 'string').map(stripIdentifierQuotes)
+    : []
+
+  const constraintName =
+    typeof cause?.originalMessage === 'string'
+      ? cause.originalMessage.match(/unique constraint "([^"]+)"/)?.[1]
+      : undefined
+
+  if (fields.length === 0 && !constraintName) return undefined
+
+  return constraintName ? { fields, constraintName } : { fields }
+}