@btravstack/prisma 0.28.0 → 0.29.0

package/README.md

@@ -79,6 +79,11 @@ the per-query observation below comes from.
   transactions, and a database that does not answer fails the boot with
   `DatabaseUnreachable` — the database's name and the driver's cause, never the
   URL.
+- **A role row security applies to.** Where any table has row-level security
+  enabled, a role that is a superuser, has `BYPASSRLS`, or owns a row-secured
+  table that is not `FORCE`d fails the boot with `RowSecurityBypassed`, naming
+  the role and the tables it would bypass — every policy would admit every row
+  for it.
 - **A health check**, named after the starter — `SELECT 1` through the raw
   lane, folded into the kernel's `GET /healthz` with nothing wired. `/readyz`
   does not read it: failing readiness on a dependency every replica shares
@@ -95,7 +100,9 @@ Prisma 8 throws a **structured** error carrying PostgreSQL's own SQLSTATE.
 `tryQuery` turns that into a `Result` with three modeled arms —
 `UniqueConstraintViolation` (`23505`, with the `constraint` the database
 named), `ForeignKeyViolation` (`23503`) and `NotAuthorized` (`42501`,
-including a write a row-security policy refused). Anything else is a defect.
+including a write a row-security policy refused). Anything else is a defect,
+unless you list it in `raises` — a SQLSTATE your own trigger raises on purpose
+then arrives as a `RaisedException` carrying that code.
 
 <!-- doctest: isolate
 import { tryQuery } from "@btravstack/prisma/result";
@@ -151,7 +158,7 @@ Two halves stay the deployment's, and both fail quietly when forgotten: Prisma 8
 authors policies but no `GRANT`s, and it emits `ENABLE ROW LEVEL SECURITY` with
 no way to say `FORCE` — so the table's **owner**, which is the role that ran the
 migrations, bypasses every policy. Connect as a role that is neither the owner
-nor a superuser. The
+nor a superuser — the boot refuses either with `RowSecurityBypassed`. The
 [reference page](https://btravstack.github.io/btravstack/reference/prisma)
 carries the DDL and the smaller lines that fail the same way.
 
@@ -177,12 +184,13 @@ package's.
 
 ## Options
 
-| Option         | Where                                         | What it is                                                                               |
-| -------------- | --------------------------------------------- | ---------------------------------------------------------------------------------------- |
-| `name`         | `prismaDatabase(name)`                        | the port's id and the health check's name — required                                     |
-| `client`       | `prismaDatabase(name)({ client })`            | builds your client from the URL and middleware this package bound — required             |
-| `DATABASE_URL` | environment, read by `prismaDatabase(name)`   | the connection string — required, validated at graph build; blank is an error, exit `78` |
-| `setting`      | `tenantPinned(db, tenant, work, { setting })` | the PostgreSQL run-time setting the policy reads — default `app.tenant_id`               |
+| Option         | Where                                                      | What it is                                                                               |
+| -------------- | ---------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
+| `name`         | `prismaDatabase(name)`                                     | the port's id and the health check's name — required                                     |
+| `client`       | `prismaDatabase(name)({ client })`                         | builds your client from the URL and middleware this package bound — required             |
+| `DATABASE_URL` | environment, read by `prismaDatabase(name)`                | the connection string — required, validated at graph build; blank is an error, exit `78` |
+| `setting`      | `tenantPinned(db, tenant, work, { setting })`              | the PostgreSQL run-time setting the policy reads — default `app.tenant_id`               |
+| `raises`       | `tryQuery(run, { raises })`, `tenantPinned(…, { raises })` | SQLSTATEs modeled as `RaisedException` rather than defects — default none                |
 
 There is **no `instrumented` flag**: observation is a set port every call is
 handed to, so a graph composing no observability pays one inert call and no

package/dist/index.cjs

@@ -66,6 +66,21 @@ const queryObserver = (observers) => {
 /** The one place the cast above is spelled. */
 const probeable = (db) => db;
 const probe = (db) => probeable(db).runtime().query(probeable(db).raw.sql`SELECT 1`.affectedCount().build());
+const exemptions = (db) => probeable(db).runtime().query(probeable(db).raw.sql`SELECT current_user::text AS role, c.oid::regclass::text AS relation, CASE WHEN r.rolsuper THEN 'superuser' WHEN r.rolbypassrls THEN 'bypassrls' ELSE 'owner' END AS bypass FROM pg_class c JOIN pg_roles r ON r.rolname = current_user WHERE c.relrowsecurity AND (r.rolsuper OR r.rolbypassrls OR (NOT c.relforcerowsecurity AND pg_has_role(current_user, c.relowner, 'USAGE'))) ORDER BY 2`.returnsRow({
+	role: "pg/text@1",
+	relation: "pg/text@1",
+	bypass: "pg/text@1"
+}).build());
+/**
+* The role the client connected as is exempt from row-level security on a
+* table that has it enabled: a superuser, a role with `BYPASSRLS`, or the
+* owner of a table whose security is not `FORCE`d — which Prisma 8 cannot
+* declare, so every table a migration created qualifies for the role that ran
+* it. Every policy would admit every row, so the boot is refused rather than
+* served without isolation. `tables` are the ones it would bypass; the URL is
+* never carried.
+*/
+var RowSecurityBypassed = class extends (0, unthrown.TaggedError)("RowSecurityBypassed") {};
 /**
 * The database did not answer when the scope opened. Carries the database's
 * name and the driver's own failure, never the URL, which holds credentials.
@@ -84,6 +99,12 @@ var DatabaseUnreachable = class extends (0, unthrown.TaggedError)("DatabaseUnrea
 * database that does not answer fails the boot with
 * {@link DatabaseUnreachable}.
 *
+* **Row-level security has to apply to the role it connected as.** Where any
+* table has it enabled, a role that is a superuser, has `BYPASSRLS`, or owns
+* such a table without `FORCE` fails the boot with {@link RowSecurityBypassed}.
+* A database with no row-secured table passes as it is. The health check does
+* not repeat it: a role does not change under a running pool.
+*
 * **The pool closes on every exit path**, including a boot that fails after
 * this provider ran — that is what makes it resourceful rather than a plain
 * value. `runtime().close()` ends the pool; Prisma dials again lazily on the
@@ -97,7 +118,12 @@ var DatabaseUnreachable = class extends (0, unthrown.TaggedError)("DatabaseUnrea
 const prismaDatabase = (name) => ({ client }) => {
 	const config = _btravstack_config.Config.provider(`${name}Config`)(_btravstack_config.Config.object({ url: _btravstack_config.Config.string("DATABASE_URL") }));
 	const DatabasePort = (0, _btravstack_di.Port)(name);
-	const verified = (db) => (0, unthrown.fromPromise)(probe(db).then(() => db, (cause) => probeable(db).runtime().close().finally(() => Promise.reject(cause))), (cause) => new DatabaseUnreachable({
+	const verified = (db) => (0, unthrown.fromPromise)(probe(db).then(() => exemptions(db)).then((exempt) => exempt[0] === void 0 ? db : Promise.reject(new RowSecurityBypassed({
+		database: name,
+		role: exempt[0].role,
+		bypass: exempt[0].bypass,
+		tables: exempt.map(({ relation }) => relation)
+	}))).catch((cause) => probeable(db).runtime().close().finally(() => Promise.reject(cause))), (cause) => cause instanceof RowSecurityBypassed ? cause : new DatabaseUnreachable({
 		database: name,
 		cause
 	}));
@@ -134,4 +160,5 @@ const prismaDatabase = (name) => ({ client }) => {
 };
 //#endregion
 exports.DatabaseUnreachable = DatabaseUnreachable;
+exports.RowSecurityBypassed = RowSecurityBypassed;
 exports.prismaDatabase = prismaDatabase;

package/dist/index.d.cts

@@ -66,6 +66,24 @@ type PrismaLike = {
    */
   readonly runtime: unknown;
 };
+/** Why row-level security does not apply to the role, as {@link RowSecurityBypassed} names it. */
+type RowSecurityBypass = "superuser" | "bypassrls" | "owner";
+declare const RowSecurityBypassed_base: import("unthrown").TaggedErrorConstructor<"RowSecurityBypassed">;
+/**
+ * The role the client connected as is exempt from row-level security on a
+ * table that has it enabled: a superuser, a role with `BYPASSRLS`, or the
+ * owner of a table whose security is not `FORCE`d — which Prisma 8 cannot
+ * declare, so every table a migration created qualifies for the role that ran
+ * it. Every policy would admit every row, so the boot is refused rather than
+ * served without isolation. `tables` are the ones it would bypass; the URL is
+ * never carried.
+ */
+export declare class RowSecurityBypassed extends RowSecurityBypassed_base<{
+  readonly database: string;
+  readonly role: string;
+  readonly bypass: RowSecurityBypass;
+  readonly tables: readonly string[];
+}> {}
 declare const DatabaseUnreachable_base: import("unthrown").TaggedErrorConstructor<"DatabaseUnreachable">;
 /**
  * The database did not answer when the scope opened. Carries the database's
@@ -119,6 +137,12 @@ type PrismaOptions<C extends PrismaLike> = {
  * database that does not answer fails the boot with
  * {@link DatabaseUnreachable}.
  *
+ * **Row-level security has to apply to the role it connected as.** Where any
+ * table has it enabled, a role that is a superuser, has `BYPASSRLS`, or owns
+ * such a table without `FORCE` fails the boot with {@link RowSecurityBypassed}.
+ * A database with no row-secured table passes as it is. The health check does
+ * not repeat it: a role does not change under a running pool.
+ *
  * **The pool closes on every exit path**, including a boot that fails after
  * this provider ran — that is what makes it resourceful rather than a plain
  * value. `runtime().close()` ends the pool; Prisma dials again lazily on the
@@ -129,10 +153,10 @@ type PrismaOptions<C extends PrismaLike> = {
  * against this same URL *before the process starts*; an application that
  * migrates itself at boot races every other replica.
  */
-export declare const prismaDatabase: <const N extends string>(name: N) => <C extends PrismaLike>({ client }: PrismaOptions<C>) => Module<HealthChecks | (PortClassOf<N, C> extends (infer T) ? T extends PortClassOf<N, C> ? T extends import("@btravstack/di").AnyPort ? InstanceType<T> : T extends import("@btravstack/di").AnyProvider ? InstanceType<T["port"]> : never : never : never), import("@btravstack/config").ConfigInvalid | DatabaseUnreachable, Exclude<import("@btravstack/config").EnvReading<"DATABASE_URL", never>, HealthChecks | Observers | import("@btravstack/di").PortInstance<string, C> | import("@btravstack/di").PortInstance<`${N}Config`, {
+export declare const prismaDatabase: <const N extends string>(name: N) => <C extends PrismaLike>({ client }: PrismaOptions<C>) => Module<HealthChecks | (PortClassOf<N, C> extends (infer T) ? T extends PortClassOf<N, C> ? T extends import("@btravstack/di").AnyPort ? InstanceType<T> : T extends import("@btravstack/di").AnyProvider ? InstanceType<T["port"]> : never : never : never), import("@btravstack/config").ConfigInvalid | DatabaseUnreachable | RowSecurityBypassed, Exclude<import("@btravstack/config").EnvReading<"DATABASE_URL", never>, HealthChecks | Observers | import("@btravstack/di").PortInstance<string, C> | import("@btravstack/di").PortInstance<`${N}Config`, {
   readonly url: string;
 }>>> & {
   readonly port: PortClassOf<N, C>;
 };
 //#endregion
-export type { PrismaBinding, PrismaLike, PrismaOptions, SqlMiddlewareLike };
+export type { PrismaBinding, PrismaLike, PrismaOptions, RowSecurityBypass, SqlMiddlewareLike };

package/dist/index.d.mts

@@ -66,6 +66,24 @@ type PrismaLike = {
    */
   readonly runtime: unknown;
 };
+/** Why row-level security does not apply to the role, as {@link RowSecurityBypassed} names it. */
+type RowSecurityBypass = "superuser" | "bypassrls" | "owner";
+declare const RowSecurityBypassed_base: import("unthrown").TaggedErrorConstructor<"RowSecurityBypassed">;
+/**
+ * The role the client connected as is exempt from row-level security on a
+ * table that has it enabled: a superuser, a role with `BYPASSRLS`, or the
+ * owner of a table whose security is not `FORCE`d — which Prisma 8 cannot
+ * declare, so every table a migration created qualifies for the role that ran
+ * it. Every policy would admit every row, so the boot is refused rather than
+ * served without isolation. `tables` are the ones it would bypass; the URL is
+ * never carried.
+ */
+export declare class RowSecurityBypassed extends RowSecurityBypassed_base<{
+  readonly database: string;
+  readonly role: string;
+  readonly bypass: RowSecurityBypass;
+  readonly tables: readonly string[];
+}> {}
 declare const DatabaseUnreachable_base: import("unthrown").TaggedErrorConstructor<"DatabaseUnreachable">;
 /**
  * The database did not answer when the scope opened. Carries the database's
@@ -119,6 +137,12 @@ type PrismaOptions<C extends PrismaLike> = {
  * database that does not answer fails the boot with
  * {@link DatabaseUnreachable}.
  *
+ * **Row-level security has to apply to the role it connected as.** Where any
+ * table has it enabled, a role that is a superuser, has `BYPASSRLS`, or owns
+ * such a table without `FORCE` fails the boot with {@link RowSecurityBypassed}.
+ * A database with no row-secured table passes as it is. The health check does
+ * not repeat it: a role does not change under a running pool.
+ *
  * **The pool closes on every exit path**, including a boot that fails after
  * this provider ran — that is what makes it resourceful rather than a plain
  * value. `runtime().close()` ends the pool; Prisma dials again lazily on the
@@ -129,10 +153,10 @@ type PrismaOptions<C extends PrismaLike> = {
  * against this same URL *before the process starts*; an application that
  * migrates itself at boot races every other replica.
  */
-export declare const prismaDatabase: <const N extends string>(name: N) => <C extends PrismaLike>({ client }: PrismaOptions<C>) => Module<HealthChecks | (PortClassOf<N, C> extends (infer T) ? T extends PortClassOf<N, C> ? T extends import("@btravstack/di").AnyPort ? InstanceType<T> : T extends import("@btravstack/di").AnyProvider ? InstanceType<T["port"]> : never : never : never), import("@btravstack/config").ConfigInvalid | DatabaseUnreachable, Exclude<import("@btravstack/config").EnvReading<"DATABASE_URL", never>, HealthChecks | Observers | import("@btravstack/di").PortInstance<string, C> | import("@btravstack/di").PortInstance<`${N}Config`, {
+export declare const prismaDatabase: <const N extends string>(name: N) => <C extends PrismaLike>({ client }: PrismaOptions<C>) => Module<HealthChecks | (PortClassOf<N, C> extends (infer T) ? T extends PortClassOf<N, C> ? T extends import("@btravstack/di").AnyPort ? InstanceType<T> : T extends import("@btravstack/di").AnyProvider ? InstanceType<T["port"]> : never : never : never), import("@btravstack/config").ConfigInvalid | DatabaseUnreachable | RowSecurityBypassed, Exclude<import("@btravstack/config").EnvReading<"DATABASE_URL", never>, HealthChecks | Observers | import("@btravstack/di").PortInstance<string, C> | import("@btravstack/di").PortInstance<`${N}Config`, {
   readonly url: string;
 }>>> & {
   readonly port: PortClassOf<N, C>;
 };
 //#endregion
-export type { PrismaBinding, PrismaLike, PrismaOptions, SqlMiddlewareLike };
+export type { PrismaBinding, PrismaLike, PrismaOptions, RowSecurityBypass, SqlMiddlewareLike };

package/dist/index.mjs

@@ -65,6 +65,21 @@ const queryObserver = (observers) => {
 /** The one place the cast above is spelled. */
 const probeable = (db) => db;
 const probe = (db) => probeable(db).runtime().query(probeable(db).raw.sql`SELECT 1`.affectedCount().build());
+const exemptions = (db) => probeable(db).runtime().query(probeable(db).raw.sql`SELECT current_user::text AS role, c.oid::regclass::text AS relation, CASE WHEN r.rolsuper THEN 'superuser' WHEN r.rolbypassrls THEN 'bypassrls' ELSE 'owner' END AS bypass FROM pg_class c JOIN pg_roles r ON r.rolname = current_user WHERE c.relrowsecurity AND (r.rolsuper OR r.rolbypassrls OR (NOT c.relforcerowsecurity AND pg_has_role(current_user, c.relowner, 'USAGE'))) ORDER BY 2`.returnsRow({
+	role: "pg/text@1",
+	relation: "pg/text@1",
+	bypass: "pg/text@1"
+}).build());
+/**
+* The role the client connected as is exempt from row-level security on a
+* table that has it enabled: a superuser, a role with `BYPASSRLS`, or the
+* owner of a table whose security is not `FORCE`d — which Prisma 8 cannot
+* declare, so every table a migration created qualifies for the role that ran
+* it. Every policy would admit every row, so the boot is refused rather than
+* served without isolation. `tables` are the ones it would bypass; the URL is
+* never carried.
+*/
+var RowSecurityBypassed = class extends TaggedError("RowSecurityBypassed") {};
 /**
 * The database did not answer when the scope opened. Carries the database's
 * name and the driver's own failure, never the URL, which holds credentials.
@@ -83,6 +98,12 @@ var DatabaseUnreachable = class extends TaggedError("DatabaseUnreachable") {};
 * database that does not answer fails the boot with
 * {@link DatabaseUnreachable}.
 *
+* **Row-level security has to apply to the role it connected as.** Where any
+* table has it enabled, a role that is a superuser, has `BYPASSRLS`, or owns
+* such a table without `FORCE` fails the boot with {@link RowSecurityBypassed}.
+* A database with no row-secured table passes as it is. The health check does
+* not repeat it: a role does not change under a running pool.
+*
 * **The pool closes on every exit path**, including a boot that fails after
 * this provider ran — that is what makes it resourceful rather than a plain
 * value. `runtime().close()` ends the pool; Prisma dials again lazily on the
@@ -96,7 +117,12 @@ var DatabaseUnreachable = class extends TaggedError("DatabaseUnreachable") {};
 const prismaDatabase = (name) => ({ client }) => {
 	const config = Config.provider(`${name}Config`)(Config.object({ url: Config.string("DATABASE_URL") }));
 	const DatabasePort = Port(name);
-	const verified = (db) => fromPromise(probe(db).then(() => db, (cause) => probeable(db).runtime().close().finally(() => Promise.reject(cause))), (cause) => new DatabaseUnreachable({
+	const verified = (db) => fromPromise(probe(db).then(() => exemptions(db)).then((exempt) => exempt[0] === void 0 ? db : Promise.reject(new RowSecurityBypassed({
+		database: name,
+		role: exempt[0].role,
+		bypass: exempt[0].bypass,
+		tables: exempt.map(({ relation }) => relation)
+	}))).catch((cause) => probeable(db).runtime().close().finally(() => Promise.reject(cause))), (cause) => cause instanceof RowSecurityBypassed ? cause : new DatabaseUnreachable({
 		database: name,
 		cause
 	}));
@@ -132,4 +158,4 @@ const prismaDatabase = (name) => ({ client }) => {
 	return Object.assign(database, { port: DatabasePort });
 };
 //#endregion
-export { DatabaseUnreachable, prismaDatabase };
+export { DatabaseUnreachable, RowSecurityBypassed, prismaDatabase };

package/dist/result.cjs

@@ -27,16 +27,31 @@ var ForeignKeyViolation = class extends (0, unthrown.TaggedError)("ForeignKeyVio
 */
 var NotAuthorized = class extends (0, unthrown.TaggedError)("NotAuthorized") {};
 /**
+* A SQLSTATE the application raises on purpose — a trigger or a function
+* refusing a write the schema cannot express with `RAISE EXCEPTION … USING
+* ERRCODE = '…'` — modeled because the caller listed it in `raises`.
+*
+* `message` is the one the `RAISE` wrote. Raise in a class of your own rather
+* than in `XX`, which PostgreSQL reserves for its internal errors.
+*/
+var RaisedException = class extends (0, unthrown.TaggedError)("RaisedException") {
+	constructor({ message, ...fields }) {
+		super(fields);
+		this.message = message;
+	}
+};
+/**
 * SQLSTATE → a tagged error, or the caller's defect for anything unmodeled.
 *
 * The three arms are the ones an application triages. Everything else — a
 * syntax error, a dead connection, a deadlock — is infrastructure a caller
 * cannot act on differently, and belongs on the defect channel where an
-* unexpected failure already goes.
+* unexpected failure already goes — unless the caller listed its SQLSTATE in
+* `raises`.
 */
-const qualify = (cause, defect) => {
-	const error = cause;
-	switch (error?.sqlState) {
+const qualify = (cause, defect, options) => {
+	const error = cause ?? {};
+	switch (error.sqlState) {
 		case "23505": return new UniqueConstraintViolation({
 			constraint: error.constraint,
 			table: error.table
@@ -46,7 +61,15 @@ const qualify = (cause, defect) => {
 			table: error.table
 		});
 		case "42501": return new NotAuthorized({ table: error.table });
-		default: return defect(cause);
+		default: {
+			const raised = options?.raises?.find((code) => code === error.sqlState);
+			return raised === void 0 ? defect(cause) : new RaisedException({
+				sqlState: raised,
+				message: error.message,
+				constraint: error.constraint,
+				table: error.table
+			});
+		}
 	}
 };
 /**
@@ -68,11 +91,21 @@ const qualify = (cause, defect) => {
 *         .with(P.tag("NotAuthorized"), (refused) => defect(refused)),
 *   );
 * ```
+*
+* A trigger's own refusal arrives as a {@link RaisedException} once its
+* SQLSTATE is listed:
+*
+* ```ts
+* tryQuery(() => db.orm.orders.Order.create(row), { raises: ["OR001"] });
+* ```
 */
-const tryQuery = (run) => (0, unthrown.fromPromise)(Promise.resolve().then(run), qualify);
+const tryQuery = (run, options) => {
+	return (0, unthrown.fromPromise)(Promise.resolve().then(run), (cause, defect) => qualify(cause, defect, options));
+};
 //#endregion
 exports.ForeignKeyViolation = ForeignKeyViolation;
 exports.NotAuthorized = NotAuthorized;
+exports.RaisedException = RaisedException;
 exports.UniqueConstraintViolation = UniqueConstraintViolation;
 exports.qualify = qualify;
 exports.tryQuery = tryQuery;

package/dist/result.d.cts

@@ -36,17 +36,53 @@ declare const NotAuthorized_base: import("unthrown").TaggedErrorConstructor<"Not
 export declare class NotAuthorized extends NotAuthorized_base<{
   readonly table: string | undefined;
 }> {}
+declare const RaisedException_base: import("unthrown").TaggedErrorConstructor<"RaisedException">;
+/**
+ * A SQLSTATE the application raises on purpose — a trigger or a function
+ * refusing a write the schema cannot express with `RAISE EXCEPTION … USING
+ * ERRCODE = '…'` — modeled because the caller listed it in `raises`.
+ *
+ * `message` is the one the `RAISE` wrote. Raise in a class of your own rather
+ * than in `XX`, which PostgreSQL reserves for its internal errors.
+ */
+export declare class RaisedException<S extends string = string> extends RaisedException_base<{
+  readonly sqlState: S;
+  readonly constraint: string | undefined;
+  readonly table: string | undefined;
+}> {
+  constructor({ message, ...fields }: {
+    readonly sqlState: S;
+    readonly message: string;
+    readonly constraint: string | undefined;
+    readonly table: string | undefined;
+  });
+}
 /** What {@link qualify} models. Anything else is a defect. */
 export type SqlError = UniqueConstraintViolation | ForeignKeyViolation | NotAuthorized;
+/**
+ * One {@link RaisedException} per SQLSTATE listed, and nothing when none is,
+ * so a caller that lists no code keeps the three arms it already matches.
+ */
+export type Raised<S extends string> = S extends string ? RaisedException<S> : never;
+/** Options of {@link tryQuery} and {@link qualify}. */
+export type QualifyOptions<S extends string> = {
+  /**
+   * The SQLSTATEs the application raises on purpose and wants as a
+   * {@link RaisedException} rather than a defect. The three SQLSTATEs
+   * {@link SqlError} already models keep their own arms.
+   */
+  readonly raises?: readonly S[];
+};
 /**
  * SQLSTATE → a tagged error, or the caller's defect for anything unmodeled.
  *
  * The three arms are the ones an application triages. Everything else — a
  * syntax error, a dead connection, a deadlock — is infrastructure a caller
  * cannot act on differently, and belongs on the defect channel where an
- * unexpected failure already goes.
+ * unexpected failure already goes — unless the caller listed its SQLSTATE in
+ * `raises`.
  */
-export declare const qualify: <D>(cause: unknown, defect: (cause: unknown) => D) => SqlError | D;
+export declare const qualify: <D, const S extends string = never>(cause: unknown, defect: (cause: unknown) => D, options?: QualifyOptions<S>) => SqlError | Raised<S> | D;
 /**
  * Runs a query and answers a `Result` instead of rejecting.
  *
@@ -66,6 +102,13 @@ export declare const qualify: <D>(cause: unknown, defect: (cause: unknown) => D)
  *         .with(P.tag("NotAuthorized"), (refused) => defect(refused)),
  *   );
  * ```
+ *
+ * A trigger's own refusal arrives as a {@link RaisedException} once its
+ * SQLSTATE is listed:
+ *
+ * ```ts
+ * tryQuery(() => db.orm.orders.Order.create(row), { raises: ["OR001"] });
+ * ```
  */
-export declare const tryQuery: <T>(run: () => PromiseLike<T>) => AsyncResult<T, SqlError>;
+export declare const tryQuery: <T, const S extends string = never>(run: () => PromiseLike<T>, options?: QualifyOptions<S>) => AsyncResult<T, SqlError | Raised<S>>;
 //#endregion

package/dist/result.d.mts

@@ -36,17 +36,53 @@ declare const NotAuthorized_base: import("unthrown").TaggedErrorConstructor<"Not
 export declare class NotAuthorized extends NotAuthorized_base<{
   readonly table: string | undefined;
 }> {}
+declare const RaisedException_base: import("unthrown").TaggedErrorConstructor<"RaisedException">;
+/**
+ * A SQLSTATE the application raises on purpose — a trigger or a function
+ * refusing a write the schema cannot express with `RAISE EXCEPTION … USING
+ * ERRCODE = '…'` — modeled because the caller listed it in `raises`.
+ *
+ * `message` is the one the `RAISE` wrote. Raise in a class of your own rather
+ * than in `XX`, which PostgreSQL reserves for its internal errors.
+ */
+export declare class RaisedException<S extends string = string> extends RaisedException_base<{
+  readonly sqlState: S;
+  readonly constraint: string | undefined;
+  readonly table: string | undefined;
+}> {
+  constructor({ message, ...fields }: {
+    readonly sqlState: S;
+    readonly message: string;
+    readonly constraint: string | undefined;
+    readonly table: string | undefined;
+  });
+}
 /** What {@link qualify} models. Anything else is a defect. */
 export type SqlError = UniqueConstraintViolation | ForeignKeyViolation | NotAuthorized;
+/**
+ * One {@link RaisedException} per SQLSTATE listed, and nothing when none is,
+ * so a caller that lists no code keeps the three arms it already matches.
+ */
+export type Raised<S extends string> = S extends string ? RaisedException<S> : never;
+/** Options of {@link tryQuery} and {@link qualify}. */
+export type QualifyOptions<S extends string> = {
+  /**
+   * The SQLSTATEs the application raises on purpose and wants as a
+   * {@link RaisedException} rather than a defect. The three SQLSTATEs
+   * {@link SqlError} already models keep their own arms.
+   */
+  readonly raises?: readonly S[];
+};
 /**
  * SQLSTATE → a tagged error, or the caller's defect for anything unmodeled.
  *
  * The three arms are the ones an application triages. Everything else — a
  * syntax error, a dead connection, a deadlock — is infrastructure a caller
  * cannot act on differently, and belongs on the defect channel where an
- * unexpected failure already goes.
+ * unexpected failure already goes — unless the caller listed its SQLSTATE in
+ * `raises`.
  */
-export declare const qualify: <D>(cause: unknown, defect: (cause: unknown) => D) => SqlError | D;
+export declare const qualify: <D, const S extends string = never>(cause: unknown, defect: (cause: unknown) => D, options?: QualifyOptions<S>) => SqlError | Raised<S> | D;
 /**
  * Runs a query and answers a `Result` instead of rejecting.
  *
@@ -66,6 +102,13 @@ export declare const qualify: <D>(cause: unknown, defect: (cause: unknown) => D)
  *         .with(P.tag("NotAuthorized"), (refused) => defect(refused)),
  *   );
  * ```
+ *
+ * A trigger's own refusal arrives as a {@link RaisedException} once its
+ * SQLSTATE is listed:
+ *
+ * ```ts
+ * tryQuery(() => db.orm.orders.Order.create(row), { raises: ["OR001"] });
+ * ```
  */
-export declare const tryQuery: <T>(run: () => PromiseLike<T>) => AsyncResult<T, SqlError>;
+export declare const tryQuery: <T, const S extends string = never>(run: () => PromiseLike<T>, options?: QualifyOptions<S>) => AsyncResult<T, SqlError | Raised<S>>;
 //#endregion

package/dist/result.mjs

@@ -26,16 +26,31 @@ var ForeignKeyViolation = class extends TaggedError("ForeignKeyViolation") {};
 */
 var NotAuthorized = class extends TaggedError("NotAuthorized") {};
 /**
+* A SQLSTATE the application raises on purpose — a trigger or a function
+* refusing a write the schema cannot express with `RAISE EXCEPTION … USING
+* ERRCODE = '…'` — modeled because the caller listed it in `raises`.
+*
+* `message` is the one the `RAISE` wrote. Raise in a class of your own rather
+* than in `XX`, which PostgreSQL reserves for its internal errors.
+*/
+var RaisedException = class extends TaggedError("RaisedException") {
+	constructor({ message, ...fields }) {
+		super(fields);
+		this.message = message;
+	}
+};
+/**
 * SQLSTATE → a tagged error, or the caller's defect for anything unmodeled.
 *
 * The three arms are the ones an application triages. Everything else — a
 * syntax error, a dead connection, a deadlock — is infrastructure a caller
 * cannot act on differently, and belongs on the defect channel where an
-* unexpected failure already goes.
+* unexpected failure already goes — unless the caller listed its SQLSTATE in
+* `raises`.
 */
-const qualify = (cause, defect) => {
-	const error = cause;
-	switch (error?.sqlState) {
+const qualify = (cause, defect, options) => {
+	const error = cause ?? {};
+	switch (error.sqlState) {
 		case "23505": return new UniqueConstraintViolation({
 			constraint: error.constraint,
 			table: error.table
@@ -45,7 +60,15 @@ const qualify = (cause, defect) => {
 			table: error.table
 		});
 		case "42501": return new NotAuthorized({ table: error.table });
-		default: return defect(cause);
+		default: {
+			const raised = options?.raises?.find((code) => code === error.sqlState);
+			return raised === void 0 ? defect(cause) : new RaisedException({
+				sqlState: raised,
+				message: error.message,
+				constraint: error.constraint,
+				table: error.table
+			});
+		}
 	}
 };
 /**
@@ -67,7 +90,16 @@ const qualify = (cause, defect) => {
 *         .with(P.tag("NotAuthorized"), (refused) => defect(refused)),
 *   );
 * ```
+*
+* A trigger's own refusal arrives as a {@link RaisedException} once its
+* SQLSTATE is listed:
+*
+* ```ts
+* tryQuery(() => db.orm.orders.Order.create(row), { raises: ["OR001"] });
+* ```
 */
-const tryQuery = (run) => fromPromise(Promise.resolve().then(run), qualify);
+const tryQuery = (run, options) => {
+	return fromPromise(Promise.resolve().then(run), (cause, defect) => qualify(cause, defect, options));
+};
 //#endregion
-export { ForeignKeyViolation, NotAuthorized, UniqueConstraintViolation, qualify, tryQuery };
+export { ForeignKeyViolation, NotAuthorized, RaisedException, UniqueConstraintViolation, qualify, tryQuery };

package/dist/rls.cjs

@@ -13,7 +13,8 @@ const require_result = require("./result.cjs");
 * the first time it does not; it is the shape a middleware would take, and it
 * is why there is no middleware here.
 *
-* It answers an `AsyncResult`, qualified by {@link tryQuery}: the pin and the
+* It answers an `AsyncResult`, qualified by {@link tryQuery} — with
+* `raises` as it takes it: the pin and the
 * work run on one connection and fail on one channel, so a caller never wraps
 * this in a second combinator. `work` still hands back a `PromiseLike`, because
 * that is what Prisma's own transaction callback is.
@@ -34,7 +35,7 @@ const tenantPinned = (db, tenant, work, options) => {
 	return require_result.tryQuery(() => db.transaction(async (tx) => {
 		await tx.query(plan);
 		return work(tx);
-	}));
+	}), options);
 };
 //#endregion
 exports.tenantPinned = tenantPinned;

package/dist/rls.d.cts

@@ -1,8 +1,11 @@
-import { SqlError } from "./result.cjs";
+import { QualifyOptions, Raised, SqlError } from "./result.cjs";
 import { AsyncResult } from "unthrown";
 //#region src/rls.d.ts
-/** Options of {@link tenantPinned}. */
-export type TenantPinnedOptions = {
+/**
+ * Options of {@link tenantPinned}: `raises`, as {@link tryQuery} takes it,
+ * and the setting the pin writes.
+ */
+export type TenantPinnedOptions<S extends string = never> = QualifyOptions<S> & {
   /**
    * The PostgreSQL run-time setting the policy reads. Defaults to
    * `app.tenant_id`, matching `current_setting('app.tenant_id', true)`.
@@ -43,7 +46,8 @@ type Queryable = {
  * the first time it does not; it is the shape a middleware would take, and it
  * is why there is no middleware here.
  *
- * It answers an `AsyncResult`, qualified by {@link tryQuery}: the pin and the
+ * It answers an `AsyncResult`, qualified by {@link tryQuery} — with
+ * `raises` as it takes it: the pin and the
  * work run on one connection and fail on one channel, so a caller never wraps
  * this in a second combinator. `work` still hands back a `PromiseLike`, because
  * that is what Prisma's own transaction callback is.
@@ -58,5 +62,5 @@ type Queryable = {
  * const orders = await tenantPinned(db, tenant, (tx) => tx.orm.orders.Order.all());
  * ```
  */
-export declare const tenantPinned: <Tx extends Queryable, R>(db: Pinnable<Tx>, tenant: string, work: (tx: Tx) => PromiseLike<R>, options?: TenantPinnedOptions) => AsyncResult<R, SqlError>;
+export declare const tenantPinned: <Tx extends Queryable, R, const S extends string = never>(db: Pinnable<Tx>, tenant: string, work: (tx: Tx) => PromiseLike<R>, options?: TenantPinnedOptions<S>) => AsyncResult<R, SqlError | Raised<S>>;
 //#endregion

package/dist/rls.d.mts

@@ -1,8 +1,11 @@
-import { SqlError } from "./result.mjs";
+import { QualifyOptions, Raised, SqlError } from "./result.mjs";
 import { AsyncResult } from "unthrown";
 //#region src/rls.d.ts
-/** Options of {@link tenantPinned}. */
-export type TenantPinnedOptions = {
+/**
+ * Options of {@link tenantPinned}: `raises`, as {@link tryQuery} takes it,
+ * and the setting the pin writes.
+ */
+export type TenantPinnedOptions<S extends string = never> = QualifyOptions<S> & {
   /**
    * The PostgreSQL run-time setting the policy reads. Defaults to
    * `app.tenant_id`, matching `current_setting('app.tenant_id', true)`.
@@ -43,7 +46,8 @@ type Queryable = {
  * the first time it does not; it is the shape a middleware would take, and it
  * is why there is no middleware here.
  *
- * It answers an `AsyncResult`, qualified by {@link tryQuery}: the pin and the
+ * It answers an `AsyncResult`, qualified by {@link tryQuery} — with
+ * `raises` as it takes it: the pin and the
  * work run on one connection and fail on one channel, so a caller never wraps
  * this in a second combinator. `work` still hands back a `PromiseLike`, because
  * that is what Prisma's own transaction callback is.
@@ -58,5 +62,5 @@ type Queryable = {
  * const orders = await tenantPinned(db, tenant, (tx) => tx.orm.orders.Order.all());
  * ```
  */
-export declare const tenantPinned: <Tx extends Queryable, R>(db: Pinnable<Tx>, tenant: string, work: (tx: Tx) => PromiseLike<R>, options?: TenantPinnedOptions) => AsyncResult<R, SqlError>;
+export declare const tenantPinned: <Tx extends Queryable, R, const S extends string = never>(db: Pinnable<Tx>, tenant: string, work: (tx: Tx) => PromiseLike<R>, options?: TenantPinnedOptions<S>) => AsyncResult<R, SqlError | Raised<S>>;
 //#endregion

package/dist/rls.mjs

@@ -12,7 +12,8 @@ import { tryQuery } from "./result.mjs";
 * the first time it does not; it is the shape a middleware would take, and it
 * is why there is no middleware here.
 *
-* It answers an `AsyncResult`, qualified by {@link tryQuery}: the pin and the
+* It answers an `AsyncResult`, qualified by {@link tryQuery} — with
+* `raises` as it takes it: the pin and the
 * work run on one connection and fail on one channel, so a caller never wraps
 * this in a second combinator. `work` still hands back a `PromiseLike`, because
 * that is what Prisma's own transaction callback is.
@@ -33,7 +34,7 @@ const tenantPinned = (db, tenant, work, options) => {
 	return tryQuery(() => db.transaction(async (tx) => {
 		await tx.query(plan);
 		return work(tx);
-	}));
+	}), options);
 };
 //#endregion
 export { tenantPinned };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@btravstack/prisma",
-  "version": "0.28.0",
+  "version": "0.29.0",
   "description": "The Prisma starter for @btravstack/core: DATABASE_URL through Config, the Postgres driver adapter, and a client whose pool is the application scope's",
   "keywords": [
     "database",
@@ -63,9 +63,9 @@
     "./package.json": "./package.json"
   },
   "devDependencies": {
-    "@btravstack/config": "0.28.0",
-    "@btravstack/core": "0.28.0",
-    "@btravstack/di": "0.28.0",
+    "@btravstack/config": "0.29.0",
+    "@btravstack/core": "0.29.0",
+    "@btravstack/di": "0.29.0",
     "@btravstack/tsconfig": "0.4.0",
     "@prisma/orm-postgres": "8.0.0-rc.11",
     "@types/node": "26.6.4",
@@ -77,9 +77,9 @@
     "vitest": "5.0.3"
   },
   "peerDependencies": {
-    "@btravstack/config": "^0.28.0",
-    "@btravstack/core": "^0.28.0",
-    "@btravstack/di": "^0.28.0",
+    "@btravstack/config": "^0.29.0",
+    "@btravstack/core": "^0.29.0",
+    "@btravstack/di": "^0.29.0",
     "@prisma/orm-postgres": "^8.0.0-rc.11",
     "unthrown": "^5.0.0"
   },