@palbase/backend 32.0.0 → 33.0.1

package/dist/engine/index.d.cts

@@ -1,8 +1,8 @@
-import '../index-DgYkdNT9.cjs';
-export { A as App, g as AuthVerifier, B as BootRefused, h as CreateAppOptions, D as DECLARATION_REFUSAL, a as DeclarationRefused, E as EgressPolicy, j as EngineConfig, M as ModuleClients, R as RateLimiter, k as RequestDatabase, l as RouteEntry, m as RuntimeHooks, S as ScrubResult, n as SqlDriver, o as SqlTx, p as buildRouteTable, q as createApp, r as createLazyTransaction, s as createOps, t as createRequestDatabase, u as effectiveAuth, v as hostAllowed, w as installEgressFence, i as isDeclarationRefused, x as loadConfig, y as makeMemoryCache, z as matchRoute, F as quoteIdent, G as scrubSecrets, H as withTables } from '../index-CWGiJ2Up.cjs';
+import '../index-DB_nW-AV.cjs';
+export { A as App, g as AuthVerifier, B as BootRefused, h as CreateAppOptions, D as DECLARATION_REFUSAL, a as DeclarationRefused, E as EgressPolicy, j as EngineConfig, M as ModuleClients, R as RateLimiter, k as RequestDatabase, l as RouteEntry, m as RuntimeHooks, S as ScrubResult, n as SqlDriver, o as SqlTx, p as buildRouteTable, q as createApp, r as createLazyTransaction, s as createOps, t as createRequestDatabase, u as effectiveAuth, v as hostAllowed, w as installEgressFence, i as isDeclarationRefused, x as loadConfig, y as makeMemoryCache, z as matchRoute, F as quoteIdent, G as scrubSecrets, H as withTables } from '../index-DLveQoOf.cjs';
 import '../db/env.cjs';
 import '../stack.cjs';
 import 'zod';
 import 'node:async_hooks';
 import '../module-Dl1KFVtc.cjs';
-import '../registry-BcRYIQ-R.cjs';
+import '../registry-DSTThhKf.cjs';

package/dist/engine/index.d.ts

@@ -1,8 +1,8 @@
-import '../index-BgWnP07a.js';
-export { A as App, g as AuthVerifier, B as BootRefused, h as CreateAppOptions, D as DECLARATION_REFUSAL, a as DeclarationRefused, E as EgressPolicy, j as EngineConfig, M as ModuleClients, R as RateLimiter, k as RequestDatabase, l as RouteEntry, m as RuntimeHooks, S as ScrubResult, n as SqlDriver, o as SqlTx, p as buildRouteTable, q as createApp, r as createLazyTransaction, s as createOps, t as createRequestDatabase, u as effectiveAuth, v as hostAllowed, w as installEgressFence, i as isDeclarationRefused, x as loadConfig, y as makeMemoryCache, z as matchRoute, F as quoteIdent, G as scrubSecrets, H as withTables } from '../index-BILC9WwS.js';
+import '../index-DMZG3kpo.js';
+export { A as App, g as AuthVerifier, B as BootRefused, h as CreateAppOptions, D as DECLARATION_REFUSAL, a as DeclarationRefused, E as EgressPolicy, j as EngineConfig, M as ModuleClients, R as RateLimiter, k as RequestDatabase, l as RouteEntry, m as RuntimeHooks, S as ScrubResult, n as SqlDriver, o as SqlTx, p as buildRouteTable, q as createApp, r as createLazyTransaction, s as createOps, t as createRequestDatabase, u as effectiveAuth, v as hostAllowed, w as installEgressFence, i as isDeclarationRefused, x as loadConfig, y as makeMemoryCache, z as matchRoute, F as quoteIdent, G as scrubSecrets, H as withTables } from '../index-D-3duy8Y.js';
 import '../db/env.js';
 import '../stack.js';
 import 'zod';
 import 'node:async_hooks';
 import '../module-Dl1KFVtc.js';
-import '../registry-ClzjxIWy.js';
+import '../registry-JjF5lcj4.js';

package/dist/engine/index.js

@@ -16,15 +16,15 @@ import {
   quoteIdent,
   scrubSecrets,
   withTables
-} from "../chunk-AZJIKCOR.js";
+} from "../chunk-IKDONZ5D.js";
 import {
   DECLARATION_REFUSAL,
   DeclarationRefused,
   isDeclarationRefused
-} from "../chunk-5C5UCILO.js";
-import "../chunk-XEGZ3S2Q.js";
-import "../chunk-KGP6ALIU.js";
-import "../chunk-IXAX5CON.js";
+} from "../chunk-WWUG2QXF.js";
+import "../chunk-TVCCR6SO.js";
+import "../chunk-XOX6RFPZ.js";
+import "../chunk-SI4KGEM3.js";
 import "../chunk-BRLJOXWS.js";
 import "../chunk-KATPXCJ5.js";
 export {

package/dist/{index-BILC9WwS.d.ts → index-D-3duy8Y.d.ts}

@@ -1,6 +1,6 @@
-import { D as DBClient, b as DBOps, T as TxPlanBody, c as TxPlanResponse, A as AuthSpec, C as CacheClient, a as RuntimeServices, _ as __runWithRuntime, d as __requestALS } from './index-BgWnP07a.js';
+import { D as DBClient, b as DBOps, T as TxPlanBody, c as TxPlanResponse, A as AuthSpec, C as CacheClient, a as RuntimeServices, _ as __runWithRuntime, d as __requestALS } from './index-DMZG3kpo.js';
 import { T as Token } from './module-Dl1KFVtc.js';
-import { R as RouteMeta } from './registry-ClzjxIWy.js';
+import { R as RouteMeta } from './registry-JjF5lcj4.js';
 
 /**
  * engine/config.ts — settings from the environment, and the gate that refuses

package/dist/{index-DgYkdNT9.d.cts → index-DB_nW-AV.d.cts}

@@ -28,16 +28,32 @@ interface User {
     /**
      * Whether that email address has been confirmed.
      *
-     * Server-resolved from the verified user profile, not read from the JWT: a
-     * token claim is only true as of when the token was minted, so a user who
-     * verifies mid-session would keep reporting `false` until it expired.
+     * READ FROM THE VERIFIED TOKEN (`email_verified`), so it says what was true
+     * when that token was minted: a user who confirms their address mid-session
+     * keeps reporting `false` until their next one. {@link User.roles} is the
+     * deliberate exception — it is read from the table on every request.
+     *
+     * This paragraph used to claim the opposite ("server-resolved from the
+     * verified profile, not read from the JWT") and to describe a ~30-second
+     * profile cache. Measured 2026-09-04: the engine fills this field from
+     * `claims.email_verified` and no such cache exists anywhere in the runtime.
+     * Whether the claim or a profile read is the RIGHT source is a separate
+     * question and an open one — but the type may not answer it wrongly while it
+     * is open.
      *
      * `false` for a phone-only user (no address to confirm) and for any user who
-     * has not clicked through yet. Before this field existed, answering "is this
-     * address confirmed" in a handler cost an extra network round-trip PER
-     * REQUEST for one boolean the runtime already had.
+     * has not clicked through yet.
      */
     emailVerified: boolean;
+    /**
+     * The caller's DATABASE role — the string RLS reads, not an application role.
+     *
+     * It is the literal `"authenticated"` for every signed-in caller and
+     * `"anon"` for every unauthenticated one, so `user.role === "admin"` is
+     * ALWAYS false and reads like a working check. Application roles are
+     * {@link User.roles}; this field says which Postgres role the request runs
+     * as, and that is the only question it answers.
+     */
     role: string;
     /**
      * The caller's APPLICATION roles, as assigned in `auth.user_roles`.
@@ -2241,7 +2257,7 @@ interface PalbaseFunctionsClient {
     invoke<T = unknown>(fnName: string, options?: PalbaseInvokeOptions): Promise<PalbaseResult<T>>;
 }
 /**
- * Cross-user admin write surface, reached via `Flags.asService()`.
+ * Cross-user admin write surface, reached via `Flags.$asService()`.
  *
  * These five methods set/clear overrides for an ARBITRARY user (named
  * explicitly), so they bypass the current-request-user scope that `Flags.*`
@@ -2249,10 +2265,10 @@ interface PalbaseFunctionsClient {
  * `Database` / `Database.$asService()` split: the privileged, cross-user path
  * is moved OFF the default surface so it is greppable and intentional — a
  * handler that calls `Flags.setOverrideForUser(...)` on the default surface is
- * a compile error and must reach for `Flags.asService()` first.
+ * a compile error and must reach for `Flags.$asService()` first.
  *
  * @example
- * await Flags.asService().setOverrideForUser("user_123", "new_checkout", true);
+ * await Flags.$asService().setOverrideForUser("user_123", "new_checkout", true);
  */
 interface PalbaseFlagsServiceClient {
     /**
@@ -2315,7 +2331,7 @@ interface PalbaseFlagsClient {
      * user until cleared.
      *
      * Errors when there is no signed-in user (an anonymous request); reach for
-     * `Flags.asService().setOverrideForUser(userId, key, value)` to write a flag
+     * `Flags.$asService().setOverrideForUser(userId, key, value)` to write a flag
      * for an arbitrary (cross-user) target.
      *
      * @example
@@ -2325,8 +2341,12 @@ interface PalbaseFlagsClient {
     /**
      * Return the cross-user admin write surface ({@link PalbaseFlagsServiceClient}).
      * Use sparingly and explicitly — the default `Flags.setOverride(...)` path is
-     * bound to the current request user; `asService()` is how you write a flag
-     * override for an ARBITRARY user. Mirrors `Database.$asService()`.
+     * bound to the current request user; this is how you write a flag override for
+     * an ARBITRARY user. Mirrors `Database.$asService()`.
+     *
+     * NOT the name a handler writes: the ambient `Flags` singleton OMITS this
+     * member and exposes `$asService()` instead — `Flags.asService()` still
+     * type-checks there and THROWS, naming its replacement (H1).
      */
     asService(): PalbaseFlagsServiceClient;
 }
@@ -2603,7 +2623,7 @@ interface PalbaseLinksClient {
  *   \@Controller("/todos")
  *   export default class TodosController {
  *     \@Post("") create(\@Body(CreateTodoBody) body: CreateTodoBody): unknown {
- *       return Database.insert("todos", { title: body.title });
+ *       return Database.public.todos.insert({ title: body.title });
  *     }
  *   }
  *
@@ -2688,11 +2708,6 @@ declare function __setRuntime(services: RuntimeServices): void;
  * The persistent worker calls this once per request so concurrent requests
  * never share a services slot. NOT part of the public author-facing API. */
 declare function __runWithRuntime<T>(services: RuntimeServices, fn: () => T): T;
-/** Read the live clients, throwing if accessed outside a request scope.
- *
- * Resolves the ALS store first (persistent server, per-request), then the
- * process-global fallback (dev-server / tests). NOT part of the public
- * author-facing API — used by the runtime and the singleton Proxies. */
 declare function __getRuntime(): RuntimeServices;
 /** A lifecycle hook. Sync or async; the runtime awaits what it returns. */
 type LifecycleHook = () => void | Promise<void>;
@@ -2805,7 +2820,7 @@ declare const Database: EnvTypedDatabase;
 /** Firestore-like document client (PalDocs). */
 declare const Documents: PalbaseDocsClient;
 /**
- * `buckets.<name>` — the storage twin of `Database.tables.<name>`, and the same
+ * `buckets.<name>` — the storage twin of `Database.public.<name>`, and the same
  * mechanism: `config/storage.ts` generates a `Buckets` augmentation into
  * `palbase-env.d.ts`, so a bucket name is a property with no import and no
  * generic, and a typo is a compile error.
@@ -2869,21 +2884,46 @@ declare const Notifications: PalbaseNotificationsClient;
 /**
  * Feature flags.
  *
- * Mirrors the `Database` / `Database.asService()` model. The default surface is
+ * Mirrors the `Database` / `Database.$asService()` model. The default surface is
  * RLS-equivalent for flags: reads resolve against the CURRENT request user and
  * `Flags.setOverride(key, value)` writes an override for that same signed-in
  * user (no userId argument, no admin power). Cross-user admin writes
- * (`setOverrideForUser`, …) live behind `Flags.asService()` — explicit and
- * greppable, just like `Database.asService()`.
+ * (`setOverrideForUser`, …) live behind `Flags.$asService()` — explicit and
+ * greppable, just like `Database.$asService()`.
  *
  * @example
  * import { Flags } from "@palbase/backend";
  *
  * if (await Flags.isEnabled("new_checkout")) { ... }            // current user
  * await Flags.setOverride("new_checkout", true);                // current user
- * await Flags.asService().setOverrideForUser("u_9", "x", true); // cross-user
+ * await Flags.$asService().setOverrideForUser("u_9", "x", true); // cross-user
+ */
+/**
+ * The ambient `Flags` singleton's own surface — NOT the raw client's.
+ *
+ * MEASURED, as a consumer, against the built tarball: annotating the singleton
+ * as `PalbaseFlagsClient` ERASED the `$asService` that `Object.assign` adds, so
+ * `Flags.$asService()` did not exist for anyone outside this package —
+ *
+ *   TS2551: Property '$asService' does not exist on type 'PalbaseFlagsClient'.
+ *           Did you mean 'asService'?
+ *
+ * — while the only path that DID compile (`asService()`) throws by design. The
+ * feature was written and unreachable, which is the defect class this surface
+ * exists to remove.
+ *
+ * `Database` never had the problem because its singleton carries its OWN type
+ * (`EnvTypedDatabase`) rather than the raw client's (`DBClient`). This is that,
+ * for `Flags`. The raw `PalbaseFlagsClient.asService()` is untouched (FR-023) —
+ * it is the seam this forwards to.
  */
-declare const Flags: PalbaseFlagsClient;
+type PalbaseFlagsAmbient = Omit<PalbaseFlagsClient, "asService"> & {
+    /** RLS'i aşan, kullanıcılar arası yazma yüzeyi. */
+    $asService(): PalbaseFlagsServiceClient;
+    /** 31.0.0 öncesinin adı — SESSİZCE çalışmaz, yerini söyleyerek fırlatır. */
+    asService(): never;
+};
+declare const Flags: PalbaseFlagsAmbient;
 /**
  * The Realtime broadcast singleton for the current request scope. Backend-side
  * Realtime is BROADCAST-ONLY (a stateless handler can push but not subscribe —
@@ -3454,8 +3494,20 @@ type WithRowOf<Rels, R extends keyof Rels, Q> = Rels[R] extends {
  * özdeş değil" hâle getirirdi ve tam eşitlik iddiaları kırılırdı. Ölçüldü:
  * `toEqualTypeOf` dört yerde düştü.
  */
-type WithResult<Rels, W> = [keyof W] extends [never] ? unknown : {
-    [R in keyof W & keyof Rels]: WithRowOf<Rels, R, W[R]>;
+/**
+ * Yalnız GERÇEKTEN istenen dallar. `undefined extends W[R]` olan anahtarlar
+ * düşüyor — ve bu, `ReturnType<typeof t.findMany>` yazan herkes için kritik:
+ * generic bir imzada `ReturnType` tip parametrelerini VARSAYILANLA değil
+ * KISITLA örnekliyor, yani `W = WithInput<Rels>` oluyor ve her ilişki
+ * (`?:` ile, dolayısıyla `| undefined`) zorunlu bir alana dönüşüyordu.
+ * Gerçek projede ölçüldü: `type MemberRow = Awaited<ReturnType<…findMany>>[number]`
+ * 32 ilişkiyi birden ister hâle geldi ve 4 yerde kırıldı.
+ */
+type RequestedWith<W> = {
+    [R in keyof W]-?: undefined extends W[R] ? never : R;
+}[keyof W];
+type WithResult<Rels, W> = [RequestedWith<W>] extends [never] ? unknown : {
+    [R in RequestedWith<W> & keyof Rels]: WithRowOf<Rels, R, W[R]>;
 };
 type QueryInput<Row, K extends keyof Row = keyof Row, Rels = unknown> = {
     /**
@@ -3987,12 +4039,17 @@ type EnvServiceDatabase = EnvSchemaSurface & {
     }): Promise<Materialized<T>>;
 };
 /**
- * The typed-by-default Database surface: the raw string-keyed `DBClient` ops
- * PLUS a `tables` map typed against the project's generated `palbase-env.d.ts`,
- * a `transaction` that runs a whole plan in one request, and `asService()` for
+ * The typed-by-default Database surface: the `$`-prefixed string-keyed
+ * `DBClient` ops PLUS one property per schema — `public` and every schema the
+ * project declares — typed against the generated `palbase-env.d.ts`, a
+ * `$transaction` that runs a whole plan in one request, and `$asService()` for
  * the explicit RLS-bypass sibling.
  *
- * The low-level `txPlan` op is deliberately NOT re-exposed here: `transaction`
+ * NOT `tables`: that intermediate layer was removed (FR-001) and this sentence
+ * outlived it by two majors, teaching a spelling that is TS2339. Pinned in
+ * `src/database-ambient.test-d.ts`.
+ *
+ * The low-level `txPlan` op is deliberately NOT re-exposed here: `$transaction`
  * is the surface, and a hand-built plan would bypass the ref/guard machinery
  * that makes one safe to write.
  */

package/dist/{index-CWGiJ2Up.d.cts → index-DLveQoOf.d.cts}

@@ -1,6 +1,6 @@
-import { D as DBClient, b as DBOps, T as TxPlanBody, c as TxPlanResponse, A as AuthSpec, C as CacheClient, a as RuntimeServices, _ as __runWithRuntime, d as __requestALS } from './index-DgYkdNT9.cjs';
+import { D as DBClient, b as DBOps, T as TxPlanBody, c as TxPlanResponse, A as AuthSpec, C as CacheClient, a as RuntimeServices, _ as __runWithRuntime, d as __requestALS } from './index-DB_nW-AV.cjs';
 import { T as Token } from './module-Dl1KFVtc.cjs';
-import { R as RouteMeta } from './registry-BcRYIQ-R.cjs';
+import { R as RouteMeta } from './registry-DSTThhKf.cjs';
 
 /**
  * engine/config.ts — settings from the environment, and the gate that refuses

package/dist/{index-BgWnP07a.d.ts → index-DMZG3kpo.d.ts}

@@ -28,16 +28,32 @@ interface User {
     /**
      * Whether that email address has been confirmed.
      *
-     * Server-resolved from the verified user profile, not read from the JWT: a
-     * token claim is only true as of when the token was minted, so a user who
-     * verifies mid-session would keep reporting `false` until it expired.
+     * READ FROM THE VERIFIED TOKEN (`email_verified`), so it says what was true
+     * when that token was minted: a user who confirms their address mid-session
+     * keeps reporting `false` until their next one. {@link User.roles} is the
+     * deliberate exception — it is read from the table on every request.
+     *
+     * This paragraph used to claim the opposite ("server-resolved from the
+     * verified profile, not read from the JWT") and to describe a ~30-second
+     * profile cache. Measured 2026-09-04: the engine fills this field from
+     * `claims.email_verified` and no such cache exists anywhere in the runtime.
+     * Whether the claim or a profile read is the RIGHT source is a separate
+     * question and an open one — but the type may not answer it wrongly while it
+     * is open.
      *
      * `false` for a phone-only user (no address to confirm) and for any user who
-     * has not clicked through yet. Before this field existed, answering "is this
-     * address confirmed" in a handler cost an extra network round-trip PER
-     * REQUEST for one boolean the runtime already had.
+     * has not clicked through yet.
      */
     emailVerified: boolean;
+    /**
+     * The caller's DATABASE role — the string RLS reads, not an application role.
+     *
+     * It is the literal `"authenticated"` for every signed-in caller and
+     * `"anon"` for every unauthenticated one, so `user.role === "admin"` is
+     * ALWAYS false and reads like a working check. Application roles are
+     * {@link User.roles}; this field says which Postgres role the request runs
+     * as, and that is the only question it answers.
+     */
     role: string;
     /**
      * The caller's APPLICATION roles, as assigned in `auth.user_roles`.
@@ -2241,7 +2257,7 @@ interface PalbaseFunctionsClient {
     invoke<T = unknown>(fnName: string, options?: PalbaseInvokeOptions): Promise<PalbaseResult<T>>;
 }
 /**
- * Cross-user admin write surface, reached via `Flags.asService()`.
+ * Cross-user admin write surface, reached via `Flags.$asService()`.
  *
  * These five methods set/clear overrides for an ARBITRARY user (named
  * explicitly), so they bypass the current-request-user scope that `Flags.*`
@@ -2249,10 +2265,10 @@ interface PalbaseFunctionsClient {
  * `Database` / `Database.$asService()` split: the privileged, cross-user path
  * is moved OFF the default surface so it is greppable and intentional — a
  * handler that calls `Flags.setOverrideForUser(...)` on the default surface is
- * a compile error and must reach for `Flags.asService()` first.
+ * a compile error and must reach for `Flags.$asService()` first.
  *
  * @example
- * await Flags.asService().setOverrideForUser("user_123", "new_checkout", true);
+ * await Flags.$asService().setOverrideForUser("user_123", "new_checkout", true);
  */
 interface PalbaseFlagsServiceClient {
     /**
@@ -2315,7 +2331,7 @@ interface PalbaseFlagsClient {
      * user until cleared.
      *
      * Errors when there is no signed-in user (an anonymous request); reach for
-     * `Flags.asService().setOverrideForUser(userId, key, value)` to write a flag
+     * `Flags.$asService().setOverrideForUser(userId, key, value)` to write a flag
      * for an arbitrary (cross-user) target.
      *
      * @example
@@ -2325,8 +2341,12 @@ interface PalbaseFlagsClient {
     /**
      * Return the cross-user admin write surface ({@link PalbaseFlagsServiceClient}).
      * Use sparingly and explicitly — the default `Flags.setOverride(...)` path is
-     * bound to the current request user; `asService()` is how you write a flag
-     * override for an ARBITRARY user. Mirrors `Database.$asService()`.
+     * bound to the current request user; this is how you write a flag override for
+     * an ARBITRARY user. Mirrors `Database.$asService()`.
+     *
+     * NOT the name a handler writes: the ambient `Flags` singleton OMITS this
+     * member and exposes `$asService()` instead — `Flags.asService()` still
+     * type-checks there and THROWS, naming its replacement (H1).
      */
     asService(): PalbaseFlagsServiceClient;
 }
@@ -2603,7 +2623,7 @@ interface PalbaseLinksClient {
  *   \@Controller("/todos")
  *   export default class TodosController {
  *     \@Post("") create(\@Body(CreateTodoBody) body: CreateTodoBody): unknown {
- *       return Database.insert("todos", { title: body.title });
+ *       return Database.public.todos.insert({ title: body.title });
  *     }
  *   }
  *
@@ -2688,11 +2708,6 @@ declare function __setRuntime(services: RuntimeServices): void;
  * The persistent worker calls this once per request so concurrent requests
  * never share a services slot. NOT part of the public author-facing API. */
 declare function __runWithRuntime<T>(services: RuntimeServices, fn: () => T): T;
-/** Read the live clients, throwing if accessed outside a request scope.
- *
- * Resolves the ALS store first (persistent server, per-request), then the
- * process-global fallback (dev-server / tests). NOT part of the public
- * author-facing API — used by the runtime and the singleton Proxies. */
 declare function __getRuntime(): RuntimeServices;
 /** A lifecycle hook. Sync or async; the runtime awaits what it returns. */
 type LifecycleHook = () => void | Promise<void>;
@@ -2805,7 +2820,7 @@ declare const Database: EnvTypedDatabase;
 /** Firestore-like document client (PalDocs). */
 declare const Documents: PalbaseDocsClient;
 /**
- * `buckets.<name>` — the storage twin of `Database.tables.<name>`, and the same
+ * `buckets.<name>` — the storage twin of `Database.public.<name>`, and the same
  * mechanism: `config/storage.ts` generates a `Buckets` augmentation into
  * `palbase-env.d.ts`, so a bucket name is a property with no import and no
  * generic, and a typo is a compile error.
@@ -2869,21 +2884,46 @@ declare const Notifications: PalbaseNotificationsClient;
 /**
  * Feature flags.
  *
- * Mirrors the `Database` / `Database.asService()` model. The default surface is
+ * Mirrors the `Database` / `Database.$asService()` model. The default surface is
  * RLS-equivalent for flags: reads resolve against the CURRENT request user and
  * `Flags.setOverride(key, value)` writes an override for that same signed-in
  * user (no userId argument, no admin power). Cross-user admin writes
- * (`setOverrideForUser`, …) live behind `Flags.asService()` — explicit and
- * greppable, just like `Database.asService()`.
+ * (`setOverrideForUser`, …) live behind `Flags.$asService()` — explicit and
+ * greppable, just like `Database.$asService()`.
  *
  * @example
  * import { Flags } from "@palbase/backend";
  *
  * if (await Flags.isEnabled("new_checkout")) { ... }            // current user
  * await Flags.setOverride("new_checkout", true);                // current user
- * await Flags.asService().setOverrideForUser("u_9", "x", true); // cross-user
+ * await Flags.$asService().setOverrideForUser("u_9", "x", true); // cross-user
+ */
+/**
+ * The ambient `Flags` singleton's own surface — NOT the raw client's.
+ *
+ * MEASURED, as a consumer, against the built tarball: annotating the singleton
+ * as `PalbaseFlagsClient` ERASED the `$asService` that `Object.assign` adds, so
+ * `Flags.$asService()` did not exist for anyone outside this package —
+ *
+ *   TS2551: Property '$asService' does not exist on type 'PalbaseFlagsClient'.
+ *           Did you mean 'asService'?
+ *
+ * — while the only path that DID compile (`asService()`) throws by design. The
+ * feature was written and unreachable, which is the defect class this surface
+ * exists to remove.
+ *
+ * `Database` never had the problem because its singleton carries its OWN type
+ * (`EnvTypedDatabase`) rather than the raw client's (`DBClient`). This is that,
+ * for `Flags`. The raw `PalbaseFlagsClient.asService()` is untouched (FR-023) —
+ * it is the seam this forwards to.
  */
-declare const Flags: PalbaseFlagsClient;
+type PalbaseFlagsAmbient = Omit<PalbaseFlagsClient, "asService"> & {
+    /** RLS'i aşan, kullanıcılar arası yazma yüzeyi. */
+    $asService(): PalbaseFlagsServiceClient;
+    /** 31.0.0 öncesinin adı — SESSİZCE çalışmaz, yerini söyleyerek fırlatır. */
+    asService(): never;
+};
+declare const Flags: PalbaseFlagsAmbient;
 /**
  * The Realtime broadcast singleton for the current request scope. Backend-side
  * Realtime is BROADCAST-ONLY (a stateless handler can push but not subscribe —
@@ -3454,8 +3494,20 @@ type WithRowOf<Rels, R extends keyof Rels, Q> = Rels[R] extends {
  * özdeş değil" hâle getirirdi ve tam eşitlik iddiaları kırılırdı. Ölçüldü:
  * `toEqualTypeOf` dört yerde düştü.
  */
-type WithResult<Rels, W> = [keyof W] extends [never] ? unknown : {
-    [R in keyof W & keyof Rels]: WithRowOf<Rels, R, W[R]>;
+/**
+ * Yalnız GERÇEKTEN istenen dallar. `undefined extends W[R]` olan anahtarlar
+ * düşüyor — ve bu, `ReturnType<typeof t.findMany>` yazan herkes için kritik:
+ * generic bir imzada `ReturnType` tip parametrelerini VARSAYILANLA değil
+ * KISITLA örnekliyor, yani `W = WithInput<Rels>` oluyor ve her ilişki
+ * (`?:` ile, dolayısıyla `| undefined`) zorunlu bir alana dönüşüyordu.
+ * Gerçek projede ölçüldü: `type MemberRow = Awaited<ReturnType<…findMany>>[number]`
+ * 32 ilişkiyi birden ister hâle geldi ve 4 yerde kırıldı.
+ */
+type RequestedWith<W> = {
+    [R in keyof W]-?: undefined extends W[R] ? never : R;
+}[keyof W];
+type WithResult<Rels, W> = [RequestedWith<W>] extends [never] ? unknown : {
+    [R in RequestedWith<W> & keyof Rels]: WithRowOf<Rels, R, W[R]>;
 };
 type QueryInput<Row, K extends keyof Row = keyof Row, Rels = unknown> = {
     /**
@@ -3987,12 +4039,17 @@ type EnvServiceDatabase = EnvSchemaSurface & {
     }): Promise<Materialized<T>>;
 };
 /**
- * The typed-by-default Database surface: the raw string-keyed `DBClient` ops
- * PLUS a `tables` map typed against the project's generated `palbase-env.d.ts`,
- * a `transaction` that runs a whole plan in one request, and `asService()` for
+ * The typed-by-default Database surface: the `$`-prefixed string-keyed
+ * `DBClient` ops PLUS one property per schema — `public` and every schema the
+ * project declares — typed against the generated `palbase-env.d.ts`, a
+ * `$transaction` that runs a whole plan in one request, and `$asService()` for
  * the explicit RLS-bypass sibling.
  *
- * The low-level `txPlan` op is deliberately NOT re-exposed here: `transaction`
+ * NOT `tables`: that intermediate layer was removed (FR-001) and this sentence
+ * outlived it by two majors, teaching a spelling that is TS2339. Pinned in
+ * `src/database-ambient.test-d.ts`.
+ *
+ * The low-level `txPlan` op is deliberately NOT re-exposed here: `$transaction`
  * is the surface, and a hand-built plan would bypass the ref/guard machinery
  * that makes one safe to write.
  */

package/dist/index.cjs

@@ -1286,9 +1286,29 @@ function __runWithRuntime(services, fn) {
   }, fn);
 }
 __name(__runWithRuntime, "__runWithRuntime");
+var REQUIRED_SERVICES = [
+  "Database",
+  "Auth",
+  "Secrets",
+  "Documents",
+  "Storage",
+  "Cache",
+  "Log",
+  "Notifications",
+  "Flags",
+  "Realtime"
+];
+function refuseIncompleteBox(services) {
+  const missing = REQUIRED_SERVICES.filter((k) => services[k] === void 0);
+  if (missing.length > 0) {
+    throw new Error(`the request scope is missing ${missing.join(", ")} \u2014 this box was most likely written by a DIFFERENT @palbase/backend major sharing the same process (the request store is a process-wide well-known Symbol, deliberately, so two bundles of ONE version can share it). Align the versions, or pass every service when building the scope yourself.`);
+  }
+  return services;
+}
+__name(refuseIncompleteBox, "refuseIncompleteBox");
 function __getRuntime() {
   const scoped = __requestALS.getStore();
-  if (scoped) return scoped.runtime;
+  if (scoped) return refuseIncompleteBox(scoped.runtime);
   if (runtime === null) {
     throw new Error("Palbase services accessed outside a request scope. The Database/Documents/\u2026 singletons are only available inside an endpoint handler (or after the runtime has called __runWithRuntime / __setRuntime).");
   }
@@ -1430,7 +1450,12 @@ function makeTypedSurface(raw2) {
     $findById: /* @__PURE__ */ __name((table, id) => raw2.findById(table, id), "$findById"),
     $findMany: /* @__PURE__ */ __name((table, query, opts) => raw2.findMany(table, query, opts), "$findMany"),
     $put: /* @__PURE__ */ __name((table, data, opts) => raw2.put(table, data, opts), "$put"),
-    $updateMany: /* @__PURE__ */ __name((table, where, set) => raw2.updateMany(table, where, set), "$updateMany"),
+    // `opts` İLETİLİR. Düşürüldüğü sürece `Database.$updateMany(t, w, s,
+    // { returning: false })` sessizce SATIRLARI döndürüyordu, sayıyı değil —
+    // ve `if (n === 0) throw new Conflict(...)` guard'ı HİÇ çalışmıyordu,
+    // çünkü `[] === 0` yanlıştır. Komşu forwarder'lar (`$findMany`, `$put`)
+    // kendi opsiyonlarını zaten iletiyordu; bu biri unutulmuştu.
+    $updateMany: /* @__PURE__ */ __name((table, where, set, opts) => raw2.updateMany(table, where, set, opts), "$updateMany"),
     $deleteMany: /* @__PURE__ */ __name((table, where) => raw2.deleteMany(table, where), "$deleteMany"),
     $count: /* @__PURE__ */ __name((table, where) => raw2.count(table, where), "$count"),
     $search: /* @__PURE__ */ __name((table, params) => raw2.search(table, params), "$search"),
@@ -1561,13 +1586,13 @@ var Flags = Object.assign({
    * Lazily resolve the runtime's cross-user sibling on each call. We do NOT
    * cache it: `rawFlags.asService()` reads the CURRENT request scope through
    * the runtime proxy, so caching would leak one request's sibling into
-   * another concurrent request. Mirrors `Database.asService()`.
+   * another concurrent request. Mirrors `Database.$asService()`.
    */
   $asService() {
     return rawFlags.asService();
   },
   /**
-   * The name this member carried before 31.0.0.
+   * The name this member carried before 32.0.0.
    *
    * It does NOT work silently. A retired member that quietly keeps returning
    * is how a rename becomes a mystery: the old call site goes on compiling,
@@ -1577,7 +1602,7 @@ var Flags = Object.assign({
    * Database.$asService()" while the promise went unkept.
    */
   asService() {
-    throw new Error("Flags.asService() was renamed to Flags.$asService() in 31.0.0 \u2014 system members carry the `$` prefix, like Database.$asService().");
+    throw new Error("Flags.asService() was renamed to Flags.$asService() in 32.0.0 \u2014 system members carry the `$` prefix, like Database.$asService().");
   }
 });
 var Realtime = makeServiceProxy("Realtime");
@@ -3317,15 +3342,27 @@ var CODECS = {
   // not representable and the author wants `asDecimal()` instead.
   number: {
     fromDb: /* @__PURE__ */ __name((v) => Number(v), "fromDb"),
-    toDb: /* @__PURE__ */ __name((v) => String(v), "toDb"),
+    // YAZMA YOLUNDA SESSİZ BOZULMA YOK. `toDb(9007199254740993)` bir zamanlar
+    // "9007199254740992" yazıyordu: uygulamanın tuttuğundan BAŞKA bir sayı
+    // kolona gidiyordu ve hiçbir şey söylemiyordu. `asNumber()`'ın JSDoc'u
+    // "2^53'ün altında güvenli" diyordu ama bunu uygulayan bir şey yoktu.
+    toDb: /* @__PURE__ */ __name((v) => {
+      if (typeof v === "number" && !Number.isSafeInteger(v)) {
+        throw new Error(`asNumber() cannot write ${v}: it is outside the safe integer range and would be stored as a different number. Declare .asDecimal() and hand this column a string.`);
+      }
+      return String(v);
+    }, "toDb"),
     tsType: "number"
   },
   // Exact-precision column → the string Postgres sent. It exists so the
   // DECLARATION is explicit: "this column is a decimal I handle as text",
   // rather than the ABSENCE of a declaration meaning the same thing by default.
+  // NULL güvencesi ÇİFTİN KENDİSİNDE. Motor NULL'ı zaten atlıyor (üç ayrı
+  // yerde), ama bir değişmez, onu koruyan üç `if`'in DIŞINDA yazılmalı: biri
+  // düşerse `String(null)` kolonu "null" dizesine çevirirdi.
   decimal: {
-    fromDb: /* @__PURE__ */ __name((v) => String(v), "fromDb"),
-    toDb: /* @__PURE__ */ __name((v) => String(v), "toDb"),
+    fromDb: /* @__PURE__ */ __name((v) => v === null || v === void 0 ? v : String(v), "fromDb"),
+    toDb: /* @__PURE__ */ __name((v) => v === null || v === void 0 ? v : String(v), "toDb"),
     tsType: "string"
   }
 };
@@ -3558,12 +3595,22 @@ var ColumnBuilder = class _ColumnBuilder {
     if (this._def.transform !== void 0) {
       throw new Error(`.${method}() and .transform() are two ways to say the same thing on one column \u2014 keep .${method}().`);
     }
-    this._def.codec = codec;
-    return new _ColumnBuilder(this._def.type, this._def);
+    if (this._def.codec !== void 0) {
+      throw new Error(`column already declares .as${this._def.codec === "number" ? "Number" : "Decimal"}(); a column has ONE codec.`);
+    }
+    return new _ColumnBuilder(this._def.type, {
+      ...this._def,
+      codec
+    });
   }
   transform(fns) {
-    this._def.transform = fns;
-    return new _ColumnBuilder(this._def.type, this._def);
+    if (this._def.codec !== void 0) {
+      throw new Error(`column already declares a named codec; .transform() and .as*() are two ways to say the same thing \u2014 keep the codec.`);
+    }
+    return new _ColumnBuilder(this._def.type, {
+      ...this._def,
+      transform: fns
+    });
   }
 };
 function uuid() {