@palbase/backend 27.1.0 → 29.0.0

package/dist/{index-CAKOgAlP.d.ts → index-BYDUKexK.d.ts}

@@ -1,6 +1,6 @@
-import { D as DBClient, a as DBOps, T as TxPlanBody, b as TxPlanResponse, A as AuthSpec, C as CacheClient, c as RuntimeServices, _ as __runWithRuntime, d as __requestALS } from './index-V7QRh1wg.js';
+import { D as DBClient, a as DBOps, T as TxPlanBody, b as TxPlanResponse, A as AuthSpec, C as CacheClient, c as RuntimeServices, _ as __runWithRuntime, d as __requestALS } from './index-BOe82fsK.js';
 import { T as Token } from './module-Dl1KFVtc.js';
-import { R as RouteMeta } from './registry-4EI8aaFs.js';
+import { R as RouteMeta } from './registry-DaqHsOq8.js';
 
 /**
  * engine/config.ts — settings from the environment, and the gate that refuses
@@ -66,7 +66,15 @@ interface EngineConfig {
     dbServiceRole: string;
     poolMax: number;
 }
-/** Thrown when a mandatory module is unconfigured. Carries the missing names. */
+/**
+ * THE ENVIRONMENT THIS STACK WAS HANDED IS UNUSABLE. Carries the missing names.
+ *
+ * ONLY the environment. A refusal about the author's own declarations is
+ * `DeclarationRefused` (see `src/refusals.ts`) and the difference is not
+ * severity, it is the CURE: no push fixes a missing DATABASE_URL, so the
+ * runtime must keep treating this one as fatal rather than waiting for an
+ * artifact that would change nothing.
+ */
 declare class BootRefused extends Error {
     readonly missing: readonly string[];
     constructor(missing: readonly string[], message: string);
@@ -171,10 +179,27 @@ interface FindManyOptions {
      * refused without it — see `offsetClause`. */
     offset?: number;
 }
-/** The six string-keyed operations, plus an interactive `transaction`. */
 declare function createOps(tx: TxLike): {
     query<T = unknown>(sql: string, params?: unknown[]): Promise<T[]>;
     insert(table: string, data: Row): Promise<Row>;
+    /**
+     * Çok satırı TEK statement'la ekle.
+     *
+     * Motor bunu zaten yapıyordu ve yalnız PLAN yolundan erişilebiliyordu
+     * (`tx.public.x.insertMany`). Dışarıda tek kapı `insert(row)` olduğu için
+     * "şu 200 satırı yaz" ya 200 gidiş-dönüş ya da ham SQL oluyordu — ölçüldü:
+     * bir müşteri projesinde bir seed rutini satırları tek tek siliyor
+     * (`deleteMany` VARKEN) ve tek tek ekliyor.
+     *
+     * SATIRLARIN ANAHTAR KÜMESİ AYNI OLMAK ZORUNDA. Kolon listesi tek bir
+     * statement'ta paylaşıldığı için ilk satırdan türer; farklı anahtar taşıyan
+     * bir satırın fazla kolonu SESSİZCE YAZILMAZDI. Eksik kolon için `null`
+     * yazın ya da varsayılanı istiyorsanız o satırları ayrı çağrıda ekleyin.
+     */
+    insertMany(table: string, rows: readonly Row[], opts?: {
+        onConflict: readonly string[];
+        action?: "ignore" | "update";
+    }): Promise<Row[]>;
     /**
      * Bir ADI kilitle — satırı değil (FR-054).
      *
@@ -266,7 +291,9 @@ declare function createOps(tx: TxLike): {
      * should not silently succeed. Callers who mean every row say so with a
      * predicate that is true for every row.
      */
-    updateMany(table: string, where: Row, set: Row): Promise<Row[]>;
+    updateMany(table: string, where: Row, set: Row, opts?: {
+        returning?: boolean;
+    }): Promise<Row[] | number>;
     /**
      * Delete every row the filter matches, in ONE statement; resolves to how
      * many went. Same filter language, same empty-filter refusal as
@@ -282,6 +309,27 @@ declare function createOps(tx: TxLike): {
      * An empty filter is legitimate HERE: counting a whole table is a read, and
      * reads do not destroy anything.
      */
+    /**
+     * Toplama — `count`'un yanına `sum`/`avg`/`min`/`max` ve `groupBy`.
+     *
+     * Var olma nedeni: bunlar olmadan "bu hesabın toplamı" ya `$query`'ye ya da
+     * TÜM satırları çekip JS'te toplamaya düşüyor. İkincisi hem N+1 hem de para
+     * için YANLIŞ — `numeric` JS `number`'ına uğradığı anda kesinliğini
+     * kaybeder.
+     *
+     * `groupBy` verilirse SATIRLAR döner, verilmezse TEK sonuç. Boş kümede
+     * Postgres NULL döndürür, 0 değil — ve bu SDK onu `null` olarak geçiriyor:
+     * "hiç satır yoktu" ile "toplam sıfırdı" farklı şeyler.
+     */
+    aggregate(table: string, q?: {
+        where?: Row;
+        sum?: readonly string[];
+        avg?: readonly string[];
+        min?: readonly string[];
+        max?: readonly string[];
+        count?: boolean;
+        groupBy?: readonly string[];
+    }): Promise<Record<string, unknown> | Record<string, unknown>[]>;
     count(table: string, where?: Row): Promise<number>;
     findById(table: string, id: string): Promise<Row | null>;
     findMany(table: string, query?: Row, opts?: FindManyOptions): Promise<Row[]>;
@@ -527,6 +575,80 @@ declare function createRequestDatabase(sql: SqlDriver, identity: {
     claimsJson: string;
 }): RequestDatabase;
 
+/**
+ * The two ways a stack refuses to boot — and they are two because their CURES
+ * are two.
+ *
+ * A LEAF MODULE ON PURPOSE. `db/` does not import from `engine/` and must not
+ * start: the schema layer is below the engine, and a refusal both of them raise
+ * cannot live in either. Anything imported here would invert that.
+ *
+ * WHY THE SPLIT EXISTS AT ALL — measured live on 2026-09-04.
+ *
+ * `8qitbtucm` ran for days on an image whose `setSchema` did not build
+ * relations. Moved onto one that does, the same artifact hit
+ * `buildRelations` at boot, threw a bare `Error`, and the runtime — which waits
+ * only on its own `ArtifactRefused` — treated it as fatal. The supervisor took
+ * the pod down, palsvc with it. CrashLoopBackOff, back-off 5m, and palsvc is
+ * THE PROCESS THAT ACCEPTS THE PUSH the message asks for.
+ *
+ * That is verbatim the lesson `v2/runtime/src/loader.ts` already carries for
+ * ABI refusals: *"the cure was named in the error and made impossible by the
+ * exit that carried it."* It cost a tenant a third time because the second
+ * refusal had no type to be recognised by.
+ *
+ * SO THE RULE IS THE CURE, NOT THE SEVERITY:
+ *
+ *   {@link DeclarationRefused} — what was PUSHED cannot be built. Restarting
+ *     re-reads the same bytes and fails identically; only a new artifact
+ *     changes the answer. The runtime WAITS on this, keeps palsvc alive, and
+ *     says the reason out loud.
+ *
+ *   {@link BootRefused} — the ENVIRONMENT this stack was handed is unusable
+ *     (no DATABASE_URL, an unparseable PORT, no SQL driver). No push fixes it;
+ *     waiting for one would be a lie told in a log line forever. Stays fatal.
+ *
+ * NOT A MESSAGE PATTERN. The runtime's loader already says why: *"The
+ * distinction is the loader's TYPE, not a pattern over its wording."* A gate
+ * that reads wording drifts from the thing it claims to measure the first time
+ * someone improves an error message.
+ */
+/**
+ * The tag that survives a realm boundary.
+ *
+ * `instanceof` compares constructor identity, and identity is per module
+ * instance. In the pod today the runtime and the bundle share one install
+ * (measured: both frames resolve to `/app/node_modules/@palbase/backend`), so
+ * `instanceof` would work — but it works by a coincidence of packaging, and a
+ * bundle that ever carries its own copy would make every declaration refusal
+ * silently fatal again. `Symbol.for` reads from the process-wide registry, so
+ * the tag means the same thing in every copy.
+ *
+ * Exported so the runtime can recognise the refusal without importing the
+ * class — see {@link isDeclarationRefused}.
+ */
+declare const DECLARATION_REFUSAL: unique symbol;
+/**
+ * What was pushed cannot be built. The cure is a NEW ARTIFACT.
+ *
+ * Thrown by the declaration layer — relation naming, ownership, entry points —
+ * wherever a fact about the author's code makes the app impossible to
+ * construct. Never thrown for anything the environment could change.
+ */
+declare class DeclarationRefused extends Error {
+    /** @see DECLARATION_REFUSAL — realm-safe, unlike `instanceof`. */
+    readonly [DECLARATION_REFUSAL]: true;
+    constructor(message: string);
+}
+/**
+ * True for a refusal whose only cure is a new artifact — across realms.
+ *
+ * Takes `unknown` because every caller is a `catch`. A non-object, a null, a
+ * plain `Error`: all false, and false is the safe answer — it means "keep
+ * treating this as fatal", which is what the code did before this type existed.
+ */
+declare function isDeclarationRefused(e: unknown): e is DeclarationRefused;
+
 /**
  * How a container refuses.
  *
@@ -550,6 +672,14 @@ declare class DiError extends Error {
     readonly path: string[];
     readonly at: string;
     readonly fixes: string[];
+    /**
+     * EVERY `DiKind` IS A FACT ABOUT THE AUTHOR'S DECLARATIONS — an unresolvable
+     * dependency, a cycle, a class no module owns. Not one of them is something
+     * the environment could change, so restarting re-reads the same bytes and
+     * fails identically. The cure is a new artifact, and the tag is how the
+     * runtime learns that without matching on wording.
+     */
+    readonly [DECLARATION_REFUSAL]: true;
     constructor(kind: DiKind, path: string[], at: string, detail: string, fixes: string[]);
 }
 /** How often a module appears in the OTHERS' `imports`. */
@@ -702,6 +832,9 @@ declare class AuthVerifier {
 interface EffectiveAuth {
     required: boolean;
     role?: string;
+    /** The permission the route demands, as `resource.action`. Resolved against
+     * `auth.has_permission(...)` at the gate — see AuthConfig.permission. */
+    permission?: string;
     verifiedEmail: boolean;
 }
 /**
@@ -921,10 +1054,6 @@ interface App {
      */
     readonly container: Container;
 }
-/**
- * Build the app. Fails fast: the database is reached here, at boot, rather than
- * on the first request that needs it.
- */
 declare function createApp(opts: CreateAppOptions): Promise<App>;
 
-export { type App as A, BootRefused as B, type Container as C, DiError as D, type EgressPolicy as E, type ModuleClients as M, RateLimiter as R, type ScrubResult as S, type DiKind as a, type ModulePressure as b, assertNoOrphanEntryPoints as c, buildContainer as d, AuthVerifier as e, type CreateAppOptions as f, type EngineConfig as g, type RequestDatabase as h, type RouteEntry as i, type RuntimeHooks as j, type SqlDriver as k, type SqlTx as l, buildRouteTable as m, createApp as n, createLazyTransaction as o, createOps as p, createRequestDatabase as q, effectiveAuth as r, hostAllowed as s, installEgressFence as t, loadConfig as u, makeMemoryCache as v, matchRoute as w, quoteIdent as x, scrubSecrets as y, withTables as z };
+export { type App as A, BootRefused as B, type Container as C, DECLARATION_REFUSAL as D, type EgressPolicy as E, quoteIdent as F, scrubSecrets as G, withTables as H, type ModuleClients as M, RateLimiter as R, type ScrubResult as S, DeclarationRefused as a, DiError as b, type DiKind as c, type ModulePressure as d, assertNoOrphanEntryPoints as e, buildContainer as f, AuthVerifier as g, type CreateAppOptions as h, isDeclarationRefused as i, type EngineConfig as j, type RequestDatabase as k, type RouteEntry as l, type RuntimeHooks as m, type SqlDriver as n, type SqlTx as o, buildRouteTable as p, createApp as q, createLazyTransaction as r, createOps as s, createRequestDatabase as t, effectiveAuth as u, hostAllowed as v, installEgressFence as w, loadConfig as x, makeMemoryCache as y, matchRoute as z };

package/dist/{index-H-0qv5d4.d.cts → index-BZfmdRmh.d.cts}

@@ -1,6 +1,6 @@
-import { D as DBClient, a as DBOps, T as TxPlanBody, b as TxPlanResponse, A as AuthSpec, C as CacheClient, c as RuntimeServices, _ as __runWithRuntime, d as __requestALS } from './index-CgE4sVhg.cjs';
+import { D as DBClient, a as DBOps, T as TxPlanBody, b as TxPlanResponse, A as AuthSpec, C as CacheClient, c as RuntimeServices, _ as __runWithRuntime, d as __requestALS } from './index-ChvoVczS.cjs';
 import { T as Token } from './module-Dl1KFVtc.cjs';
-import { R as RouteMeta } from './registry-DHsPDY0_.cjs';
+import { R as RouteMeta } from './registry-B2KfKWv1.cjs';
 
 /**
  * engine/config.ts — settings from the environment, and the gate that refuses
@@ -66,7 +66,15 @@ interface EngineConfig {
     dbServiceRole: string;
     poolMax: number;
 }
-/** Thrown when a mandatory module is unconfigured. Carries the missing names. */
+/**
+ * THE ENVIRONMENT THIS STACK WAS HANDED IS UNUSABLE. Carries the missing names.
+ *
+ * ONLY the environment. A refusal about the author's own declarations is
+ * `DeclarationRefused` (see `src/refusals.ts`) and the difference is not
+ * severity, it is the CURE: no push fixes a missing DATABASE_URL, so the
+ * runtime must keep treating this one as fatal rather than waiting for an
+ * artifact that would change nothing.
+ */
 declare class BootRefused extends Error {
     readonly missing: readonly string[];
     constructor(missing: readonly string[], message: string);
@@ -171,10 +179,27 @@ interface FindManyOptions {
      * refused without it — see `offsetClause`. */
     offset?: number;
 }
-/** The six string-keyed operations, plus an interactive `transaction`. */
 declare function createOps(tx: TxLike): {
     query<T = unknown>(sql: string, params?: unknown[]): Promise<T[]>;
     insert(table: string, data: Row): Promise<Row>;
+    /**
+     * Çok satırı TEK statement'la ekle.
+     *
+     * Motor bunu zaten yapıyordu ve yalnız PLAN yolundan erişilebiliyordu
+     * (`tx.public.x.insertMany`). Dışarıda tek kapı `insert(row)` olduğu için
+     * "şu 200 satırı yaz" ya 200 gidiş-dönüş ya da ham SQL oluyordu — ölçüldü:
+     * bir müşteri projesinde bir seed rutini satırları tek tek siliyor
+     * (`deleteMany` VARKEN) ve tek tek ekliyor.
+     *
+     * SATIRLARIN ANAHTAR KÜMESİ AYNI OLMAK ZORUNDA. Kolon listesi tek bir
+     * statement'ta paylaşıldığı için ilk satırdan türer; farklı anahtar taşıyan
+     * bir satırın fazla kolonu SESSİZCE YAZILMAZDI. Eksik kolon için `null`
+     * yazın ya da varsayılanı istiyorsanız o satırları ayrı çağrıda ekleyin.
+     */
+    insertMany(table: string, rows: readonly Row[], opts?: {
+        onConflict: readonly string[];
+        action?: "ignore" | "update";
+    }): Promise<Row[]>;
     /**
      * Bir ADI kilitle — satırı değil (FR-054).
      *
@@ -266,7 +291,9 @@ declare function createOps(tx: TxLike): {
      * should not silently succeed. Callers who mean every row say so with a
      * predicate that is true for every row.
      */
-    updateMany(table: string, where: Row, set: Row): Promise<Row[]>;
+    updateMany(table: string, where: Row, set: Row, opts?: {
+        returning?: boolean;
+    }): Promise<Row[] | number>;
     /**
      * Delete every row the filter matches, in ONE statement; resolves to how
      * many went. Same filter language, same empty-filter refusal as
@@ -282,6 +309,27 @@ declare function createOps(tx: TxLike): {
      * An empty filter is legitimate HERE: counting a whole table is a read, and
      * reads do not destroy anything.
      */
+    /**
+     * Toplama — `count`'un yanına `sum`/`avg`/`min`/`max` ve `groupBy`.
+     *
+     * Var olma nedeni: bunlar olmadan "bu hesabın toplamı" ya `$query`'ye ya da
+     * TÜM satırları çekip JS'te toplamaya düşüyor. İkincisi hem N+1 hem de para
+     * için YANLIŞ — `numeric` JS `number`'ına uğradığı anda kesinliğini
+     * kaybeder.
+     *
+     * `groupBy` verilirse SATIRLAR döner, verilmezse TEK sonuç. Boş kümede
+     * Postgres NULL döndürür, 0 değil — ve bu SDK onu `null` olarak geçiriyor:
+     * "hiç satır yoktu" ile "toplam sıfırdı" farklı şeyler.
+     */
+    aggregate(table: string, q?: {
+        where?: Row;
+        sum?: readonly string[];
+        avg?: readonly string[];
+        min?: readonly string[];
+        max?: readonly string[];
+        count?: boolean;
+        groupBy?: readonly string[];
+    }): Promise<Record<string, unknown> | Record<string, unknown>[]>;
     count(table: string, where?: Row): Promise<number>;
     findById(table: string, id: string): Promise<Row | null>;
     findMany(table: string, query?: Row, opts?: FindManyOptions): Promise<Row[]>;
@@ -527,6 +575,80 @@ declare function createRequestDatabase(sql: SqlDriver, identity: {
     claimsJson: string;
 }): RequestDatabase;
 
+/**
+ * The two ways a stack refuses to boot — and they are two because their CURES
+ * are two.
+ *
+ * A LEAF MODULE ON PURPOSE. `db/` does not import from `engine/` and must not
+ * start: the schema layer is below the engine, and a refusal both of them raise
+ * cannot live in either. Anything imported here would invert that.
+ *
+ * WHY THE SPLIT EXISTS AT ALL — measured live on 2026-09-04.
+ *
+ * `8qitbtucm` ran for days on an image whose `setSchema` did not build
+ * relations. Moved onto one that does, the same artifact hit
+ * `buildRelations` at boot, threw a bare `Error`, and the runtime — which waits
+ * only on its own `ArtifactRefused` — treated it as fatal. The supervisor took
+ * the pod down, palsvc with it. CrashLoopBackOff, back-off 5m, and palsvc is
+ * THE PROCESS THAT ACCEPTS THE PUSH the message asks for.
+ *
+ * That is verbatim the lesson `v2/runtime/src/loader.ts` already carries for
+ * ABI refusals: *"the cure was named in the error and made impossible by the
+ * exit that carried it."* It cost a tenant a third time because the second
+ * refusal had no type to be recognised by.
+ *
+ * SO THE RULE IS THE CURE, NOT THE SEVERITY:
+ *
+ *   {@link DeclarationRefused} — what was PUSHED cannot be built. Restarting
+ *     re-reads the same bytes and fails identically; only a new artifact
+ *     changes the answer. The runtime WAITS on this, keeps palsvc alive, and
+ *     says the reason out loud.
+ *
+ *   {@link BootRefused} — the ENVIRONMENT this stack was handed is unusable
+ *     (no DATABASE_URL, an unparseable PORT, no SQL driver). No push fixes it;
+ *     waiting for one would be a lie told in a log line forever. Stays fatal.
+ *
+ * NOT A MESSAGE PATTERN. The runtime's loader already says why: *"The
+ * distinction is the loader's TYPE, not a pattern over its wording."* A gate
+ * that reads wording drifts from the thing it claims to measure the first time
+ * someone improves an error message.
+ */
+/**
+ * The tag that survives a realm boundary.
+ *
+ * `instanceof` compares constructor identity, and identity is per module
+ * instance. In the pod today the runtime and the bundle share one install
+ * (measured: both frames resolve to `/app/node_modules/@palbase/backend`), so
+ * `instanceof` would work — but it works by a coincidence of packaging, and a
+ * bundle that ever carries its own copy would make every declaration refusal
+ * silently fatal again. `Symbol.for` reads from the process-wide registry, so
+ * the tag means the same thing in every copy.
+ *
+ * Exported so the runtime can recognise the refusal without importing the
+ * class — see {@link isDeclarationRefused}.
+ */
+declare const DECLARATION_REFUSAL: unique symbol;
+/**
+ * What was pushed cannot be built. The cure is a NEW ARTIFACT.
+ *
+ * Thrown by the declaration layer — relation naming, ownership, entry points —
+ * wherever a fact about the author's code makes the app impossible to
+ * construct. Never thrown for anything the environment could change.
+ */
+declare class DeclarationRefused extends Error {
+    /** @see DECLARATION_REFUSAL — realm-safe, unlike `instanceof`. */
+    readonly [DECLARATION_REFUSAL]: true;
+    constructor(message: string);
+}
+/**
+ * True for a refusal whose only cure is a new artifact — across realms.
+ *
+ * Takes `unknown` because every caller is a `catch`. A non-object, a null, a
+ * plain `Error`: all false, and false is the safe answer — it means "keep
+ * treating this as fatal", which is what the code did before this type existed.
+ */
+declare function isDeclarationRefused(e: unknown): e is DeclarationRefused;
+
 /**
  * How a container refuses.
  *
@@ -550,6 +672,14 @@ declare class DiError extends Error {
     readonly path: string[];
     readonly at: string;
     readonly fixes: string[];
+    /**
+     * EVERY `DiKind` IS A FACT ABOUT THE AUTHOR'S DECLARATIONS — an unresolvable
+     * dependency, a cycle, a class no module owns. Not one of them is something
+     * the environment could change, so restarting re-reads the same bytes and
+     * fails identically. The cure is a new artifact, and the tag is how the
+     * runtime learns that without matching on wording.
+     */
+    readonly [DECLARATION_REFUSAL]: true;
     constructor(kind: DiKind, path: string[], at: string, detail: string, fixes: string[]);
 }
 /** How often a module appears in the OTHERS' `imports`. */
@@ -702,6 +832,9 @@ declare class AuthVerifier {
 interface EffectiveAuth {
     required: boolean;
     role?: string;
+    /** The permission the route demands, as `resource.action`. Resolved against
+     * `auth.has_permission(...)` at the gate — see AuthConfig.permission. */
+    permission?: string;
     verifiedEmail: boolean;
 }
 /**
@@ -921,10 +1054,6 @@ interface App {
      */
     readonly container: Container;
 }
-/**
- * Build the app. Fails fast: the database is reached here, at boot, rather than
- * on the first request that needs it.
- */
 declare function createApp(opts: CreateAppOptions): Promise<App>;
 
-export { type App as A, BootRefused as B, type Container as C, DiError as D, type EgressPolicy as E, type ModuleClients as M, RateLimiter as R, type ScrubResult as S, type DiKind as a, type ModulePressure as b, assertNoOrphanEntryPoints as c, buildContainer as d, AuthVerifier as e, type CreateAppOptions as f, type EngineConfig as g, type RequestDatabase as h, type RouteEntry as i, type RuntimeHooks as j, type SqlDriver as k, type SqlTx as l, buildRouteTable as m, createApp as n, createLazyTransaction as o, createOps as p, createRequestDatabase as q, effectiveAuth as r, hostAllowed as s, installEgressFence as t, loadConfig as u, makeMemoryCache as v, matchRoute as w, quoteIdent as x, scrubSecrets as y, withTables as z };
+export { type App as A, BootRefused as B, type Container as C, DECLARATION_REFUSAL as D, type EgressPolicy as E, quoteIdent as F, scrubSecrets as G, withTables as H, type ModuleClients as M, RateLimiter as R, type ScrubResult as S, DeclarationRefused as a, DiError as b, type DiKind as c, type ModulePressure as d, assertNoOrphanEntryPoints as e, buildContainer as f, AuthVerifier as g, type CreateAppOptions as h, isDeclarationRefused as i, type EngineConfig as j, type RequestDatabase as k, type RouteEntry as l, type RuntimeHooks as m, type SqlDriver as n, type SqlTx as o, buildRouteTable as p, createApp as q, createLazyTransaction as r, createOps as s, createRequestDatabase as t, effectiveAuth as u, hostAllowed as v, installEgressFence as w, loadConfig as x, makeMemoryCache as y, matchRoute as z };