@palbase/backend 25.1.0 → 27.0.0

package/dist/{index-CUomTA3e.d.ts → index-NuzRCuxe.d.ts}

@@ -1,285 +1,6 @@
-import { Buckets, BucketTypes } from './stack.js';
-import { AsyncLocalStorage } from 'node:async_hooks';
-import { C as CacheClient, P as PalbaseDocsClient, a as PalbaseFlagsClient, L as Logger, b as PalbaseNotificationsClient, c as PalbaseRealtimeClient, D as DBClient, S as SecretsService, d as PalbaseStorageClient, e as PalbaseBucketClient, f as DBOps, T as TxPlanBody, g as TxPlanResponse, A as AuthSpec } from './endpoint-CTEHhb7A.js';
-import { E as EnvTypedDatabase } from './index-CW21M9Z3.js';
-import { R as RouteMeta } from './registry-dZZ5JKYg.js';
-
-/**
- * runtime.ts — request-scoped service singletons.
- *
- * The backend SDK no longer threads a `ctx` god-object through every handler.
- * Instead, controller methods import PascalCase service singletons directly:
- *
- *   import { Controller, Post, Body, Database } from "@palbase/backend";
- *
- *   \@Controller("/todos")
- *   export default class TodosController {
- *     \@Post("") create(\@Body(CreateTodoBody) body: CreateTodoBody): unknown {
- *       return Database.insert("todos", { title: body.title });
- *     }
- *   }
- *
- * The singletons are thin Proxies. Every property access forwards to the live
- * client for the CURRENT request scope, resolved through {@link __getRuntime}.
- *
- * # Request-scope resolution (persistent app-server)
- *
- * The runtime is a long-running Node process that serves many concurrent
- * requests on one event loop (NOT a fresh subprocess per request). A single
- * module-global slot would let one in-flight request's services bleed into
- * another's. So the services are carried in an {@link AsyncLocalStorage} store
- * ({@link __requestALS}) that the runtime sets per request with
- * {@link __runWithRuntime}; every async continuation of that request reads its
- * own store. `__getRuntime` reads the ALS store first; the module-global slot
- * (set by {@link __setRuntime}) is only a fallback for callers that run OUTSIDE
- * an ALS scope (dev-server, unit tests, the legacy single-shot path). Because
- * each `br-<ref>` pod is single-tenant, there is no cross-tenant leakage; the
- * ALS store is what prevents cross-REQUEST leakage within the shared process.
- *
- * The seam that makes `import { Database } from "@palbase/backend"` resolve to
- * the runtime-injected client: `@palbase/backend` is marked esbuild-EXTERNAL
- * when the tenant bundle is built, and the package is installed globally in the
- * pod (NODE_PATH=/usr/local/lib/node_modules). So worker.js's
- * `require('@palbase/backend')` and the bundle's `import` resolve to ONE shared
- * module instance — the ALS store and `__setRuntime` slot on that instance are
- * visible to the singletons the bundle imported.
- */
-
-/** The set of live clients the runtime injects per request scope.
- *
- * Realtime is BROADCAST-ONLY here (a stateless handler can push an event but
- * cannot hold a subscription socket — `subscribe()` lives on the client SDK).
- *
- * EXCLUDED on purpose: Functions, Links, Analytics, Auth. They are not
- * exposed as backend handler singletons (auth lives on the client SDK; the rest
- * are out of scope for backend endpoints). */
-interface RuntimeServices {
-    Database: DBClient;
-    Secrets: SecretsService;
-    Documents: PalbaseDocsClient;
-    Storage: PalbaseStorageClient;
-    Cache: CacheClient;
-    Log: Logger;
-    Notifications: PalbaseNotificationsClient;
-    Flags: PalbaseFlagsClient;
-    Realtime: PalbaseRealtimeClient;
-}
-/**
- * The per-request ALS box.
- *
- * `runtime` is the service bundle. `userId` is the request's authenticated user
- * id, written by the runtime immediately after it assembles the request object
- * (worker.js: `requestALS.getStore().userId = pbReq.user?.id || null`) and
- * `null` on an anonymous request. It was already being written there for the
- * Flags client's auto-bind; declaring it here makes the existing contract typed
- * instead of implicit, which is what lets `currentSubjectId()` read a
- * server-owned identity rather than trusting anything the caller sent.
- */
-interface RequestStore {
-    runtime: RuntimeServices;
-    userId?: string | null;
-    /** This request's id (`req_…`), written by the runtime. Used as the spend
-     * idempotency scope when the caller supplied no `Idempotency-Key`. */
-    requestId?: string;
-    /** The caller's `Idempotency-Key` header, or `null` when absent. What makes a
-     * client's retry replay its first result instead of charging twice. */
-    idempotencyKey?: string | null;
-}
-/**
- * Per-request store. The persistent runtime runs each request inside
- * {@link __runWithRuntime}, so every async continuation of that request reads
- * its OWN `runtime` (and any other request-scoped fields the runtime adds).
- *
- * Exported with a `__` prefix so the runtime (worker.js) shares the SAME ALS
- * instance across the one module instance — two ALS instances would silently
- * not see each other's stores. NOT part of the public author-facing API.
- */
-declare const __requestALS: AsyncLocalStorage<RequestStore>;
-/** Install the live clients in the process-global fallback slot.
- *
- * Persistent-server requests should use {@link __runWithRuntime} instead; this
- * remains for dev-server / tests / the legacy single-shot path that run without
- * an ALS scope. NOT part of the public author-facing API. */
-declare function __setRuntime(services: RuntimeServices): void;
-/** Run `fn` with `services` bound as the request-scoped runtime.
- *
- * 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>;
-/** Runs one release's shutdown hooks. Handed back by {@link __runStartHooks}
- * and called by the engine's `app.shutdown()`. Idempotent. */
-type ShutdownRunner = () => Promise<void>;
-/**
- * Run `hook` ONCE while the application comes up, before it serves anything.
- *
- * Call it at MODULE SCOPE in a file the application imports — the same rule
- * `defineDefaultAuth` and `@Controller` follow, and for the same reason: the
- * declaration is claimed when the app boots, which is after module loading and
- * before the first request. `name` is not decoration: a hook that throws is
- * reported by that name and the boot is REFUSED, so it is what tells an
- * operator which resource did not come up.
- *
- * There is no request scope yet, so the `Database`/`Secrets`/… singletons are
- * NOT available inside a start hook. A secret is read from `process.env` here
- * (the runtime mirrors the vault into it at boot).
- *
- * @example
- * // resources/graph.ts
- * import neo4j from "neo4j-driver";
- * import { onStart, onShutdown } from "@palbase/backend";
- *
- * export let graph: Driver;
- * onStart("graph", () => {
- *   graph = neo4j.driver(process.env.NEO4J_URL!, neo4j.auth.basic("neo4j", process.env.NEO4J_PASSWORD!));
- * });
- * onShutdown("graph", () => graph.close());
- */
-declare function onStart(name: string, hook: LifecycleHook): void;
-/**
- * Run `hook` while the application shuts down — the place a pool opened in
- * {@link onStart} is closed.
- *
- * Shutdown is BEST-EFFORT by design: a hook that throws is reported by name and
- * the rest still run. A drain that abandoned the remaining hooks on the first
- * failure would leak exactly what this exists to release, and the process is
- * leaving anyway.
- *
- * Hooks run in REVERSE declaration order, so a resource is released before what
- * it was built on.
- */
-declare function onShutdown(name: string, hook: LifecycleHook): void;
-/**
- * CLAIM what has been declared, run the start hooks, and hand back the runner
- * for this release's shutdown hooks. Called by the engine's `createApp`; the
- * `App.shutdown()` it builds calls what comes back. NOT part of the public
- * author-facing API.
- *
- * IT CLAIMS RATHER THAN READS, which is what makes it correct in this runtime:
- * a candidate release is loaded BESIDE the live one in one process
- * (`v2/runtime/src/registry-scope.ts`), and both bundles append to the one
- * shared slot above. If each app read the whole list, the live app's shutdown
- * would close the candidate's pool and the candidate's would close the live
- * app's. Taking the declarations leaves each app holding exactly its own.
- *
- * A start hook that throws REFUSES THE BOOT — with the hook's name in the
- * message — after releasing whatever the earlier hooks already opened. Serving
- * from a half-initialised app is the silence this whole surface replaces, and a
- * boot that dies holding an open pool is the leak it replaces.
- */
-declare function __runStartHooks(): Promise<ShutdownRunner>;
-/** Drop every declaration. For tests, which declare repeatedly in one process.
- * NOT part of the public author-facing API. */
-declare function __resetLifecycleHooks(): void;
-/**
- * The project's own Postgres (pgx, schema `env_<envId>`).
- *
- * Typed by default: `Database.tables.<name>.insert({...})` is typed against
- * the project's generated `palbase-env.d.ts` with NO import and NO generic.
- * The raw string ops (`query`/`insert`/`update`/`delete`/`findById`/`findMany`)
- * are also available for dynamic table names and read-only SQL.
- *
- * RLS is enforced by default (the runtime runs each op as `authenticated` with
- * the verified user's claims). To bypass RLS, call `Database.asService()` —
- * explicit and greppable — which runs as the `service_role` (BYPASSRLS).
- *
- * @example
- * import { Database } from "@palbase/backend";
- *
- * const todo = await Database.tables.todos.insert({ title: req.input.title });
- * todo.id; // string ✓
- * const rows = await Database.query("SELECT id FROM todos WHERE done = $1", [false]);
- * const all  = await Database.asService().tables.todos.findMany({}); // RLS bypass
- */
-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
- * 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.
- *
- * The intermediate `.buckets` is there for the reason `.tables` is: bucket
- * names must not share a namespace with the client's own methods, or the day
- * somebody declares a bucket called `bucket` the surface breaks.
- */
-type EnvBuckets = {
-    [K in keyof Buckets]: TypedBucketClient<Buckets[K] extends BucketTypes ? Buckets[K] : BucketTypes>;
-};
-/** One bucket, with its declared variant names in the type. */
-interface TypedBucketClient<B extends BucketTypes> extends Omit<PalbaseBucketClient, "getPublicUrl"> {
-    /** The public URL for the object, or for one of THIS bucket's declared
-     * renditions. A name the bucket does not declare is a compile error. */
-    getPublicUrl(path: string, options?: {
-        variant?: B["variants"];
-    }): string;
-}
-/**
- * Object storage: buckets, objects, renditions and signed URLs.
- *
- * `Storage.buckets.posts.upload(...)` is the typed path. `Storage.bucket(name)`
- * remains for a name computed at runtime — rare, and it gives up the typing,
- * which is the honest trade rather than a second blessed way to do it.
- */
-declare const Storage: PalbaseStorageClient & {
-    buckets: EnvBuckets;
-};
-/** JSON-typed cache (get/set/incr/getOrSet). */
-declare const Cache: CacheClient;
-/**
- * This tenant's secrets — API keys, provider credentials, signing material the
- * BACKEND owns.
- *
- * `await Secrets.get("STRIPE_KEY")` in a handler. There is no `.env` to read
- * and no file to mount: a secret is written through the vault's authenticated
- * API (or the CLI/MCP that calls it), and this is how the deployed code reads
- * it back. A name this tenant has not set answers null — as does every name
- * the STACK holds, because no route returns a platform secret's value at all.
- */
-declare const Secrets: SecretsService;
-/** Structured logger. */
-declare const Log: Logger;
-/** Push / email / SMS / in-app notifications. */
-declare const Notifications: PalbaseNotificationsClient;
-/**
- * Feature flags.
- *
- * 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()`.
- *
- * @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
- */
-declare const Flags: PalbaseFlagsClient;
-/**
- * The Realtime broadcast singleton for the current request scope. Backend-side
- * Realtime is BROADCAST-ONLY (a stateless handler can push but not subscribe —
- * `subscribe()` lives on the client SDK's `pb.realtime`). Fire-and-forget:
- * `broadcast` resolves once accepted (or with an `error`), never blocking the
- * handler on subscribers.
- *
- * @example
- * import { Realtime } from "@palbase/backend";
- *
- * await Realtime.broadcast("room:42", "message", { text, from: user.id });
- */
-declare const Realtime: PalbaseRealtimeClient;
+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-BrvvxSpn.js';
+import { T as Token } from './module-Dl1KFVtc.js';
+import { R as RouteMeta } from './registry-B0eyOF9x.js';
 
 /**
  * engine/config.ts — settings from the environment, and the gate that refuses
@@ -334,7 +55,7 @@ interface EngineConfig {
      * against it, so changing it changes who the database thinks is asking. */
     dbRole: string;
     /**
-     * The Postgres role `Database.asService()` is bound to. It is the one that
+     * The Postgres role `Database.$asService()` is bound to. It is the one that
      * carries BYPASSRLS, which is the whole of what "as service" means — a name
      * pointing at a role without it does not fail, it returns fewer rows.
      *
@@ -431,10 +152,20 @@ type TxLike = SqlTx | LazyTransaction;
  * page offset. All three used to require dropping to raw SQL, and the docs said
  * so — which is how a tenant's controllers filled up with hand-written SELECTs. */
 interface FindManyOptions {
+    /** Sıralama: tek obje ya da SIRALI liste (FR-008). `nulls` NULL'ların yerini
+     * sabitler — Postgres varsayılanı yöne göre değişir (ASC'de son, DESC'te ilk). */
     orderBy?: {
         column: string;
         direction?: "asc" | "desc";
-    };
+        nulls?: "first" | "last";
+    } | {
+        column: string;
+        direction?: "asc" | "desc";
+        nulls?: "first" | "last";
+    }[];
+    /** Projeksiyon (FR-009): verilmezse `SELECT *`. Kolon adları ŞEMAYA karşı
+     * doğrulanır — bilinmeyen ad SQL'e ulaşmadan, adıyla reddedilir. */
+    select?: string[];
     limit?: number;
     /** Rows to skip before the page starts. Only meaningful with `limit`, and
      * refused without it — see `offsetClause`. */
@@ -442,8 +173,62 @@ interface FindManyOptions {
 }
 /** The six string-keyed operations, plus an interactive `transaction`. */
 declare function createOps(tx: TxLike): {
-    query(sql: string, params?: unknown[]): Promise<Row[]>;
+    query<T = unknown>(sql: string, params?: unknown[]): Promise<T[]>;
     insert(table: string, data: Row): Promise<Row>;
+    /**
+     * Bir ADI kilitle — satırı değil (FR-054).
+     *
+     * "Aynı anda tek bir fatura kapanışı koşsun" gibi, kilitlenecek satırı
+     * OLMAYAN işler için. Anahtar bir metin; Postgres 64-bit tamsayı istediği
+     * için `hashtextextended` ile hash'leniyor ve metin SQL'e hiç GİRMİYOR.
+     *
+     * YALNIZ transaction kapsamlı aile (`pg_advisory_xact_lock`). Oturum
+     * kapsamlı sürüm bırakıldığı yerde KALIR: bağlantı havuza döner, kilit
+     * üstünde kalır ve bir sonraki isteği — hiç bitmeyecek şekilde — bekletir.
+     * Transaction kapsamlısı commit/rollback'te Postgres tarafından bırakılır,
+     * yani unutulması imkânsız.
+     */
+    advisoryXactLock(key: string): Promise<void>;
+    /**
+     * Bu satırları KİLİTLE, ve sırayı KATMAN koysun (FR-035).
+     *
+     * D-017: katman sıralamayı değil, **sıralamayı mümkün kılan primitifi**
+     * verir. Uygulama dokunacağı kümeyi önden bildirir; sırayı burası koyar.
+     * Çağıranın verdiği sıraya güvenmek, iki çağıranın aynı iki satıra ters
+     * sırayla girmesi demektir — ve deadlock'un bedeli ucuz değil:
+     * `deadlock_timeout` varsayılanı **1 saniye**, yani kaybeden işlem bir
+     * saniye bekledikten sonra hata alır.
+     *
+     * `FOR NO KEY UPDATE`, `updateMany`'nin CTE'siyle AYNI kilit modu: iki
+     * yazma yolunun tek bir sırası ve tek bir modu olmak zorunda, yoksa biri
+     * diğerini bekletir.
+     */
+    lockRows(table: string, ids: readonly string[]): Promise<void>;
+    /**
+     * Bir idempotency anahtarını SAHİPLEN (FR-033).
+     *
+     * `{ inserted: true, row }` → bu çağrı yazdı.
+     * `{ inserted: false, row }` → başkası önce yazdı; dönen satır ONUN satırı.
+     *
+     * ÖLÇÜLDÜ (pg16, spec Research Appendix) — üç dalın üçü de farklı davranıyor:
+     *
+     *   plain INSERT           ikinci oturum 2121 ms BLOKLANIR, sonra 23505 alır;
+     *                          birincinin satırı korunur              ← istenen
+     *   ON CONFLICT DO UPDATE  ikincinin verisi birincininkini EZER
+     *   ON CONFLICT DO NOTHING `INSERT 0 0` — sessiz; çağıran ne olduğunu bilemez
+     *
+     * Bu yüzden `ON CONFLICT` KULLANILMIYOR. Ödeme yolunda "ikinci çağrı
+     * birincinin sonucunu görsün" idempotency'nin tanımıdır; ezmek ya da
+     * susmak ikisi de yanlış cevap.
+     *
+     * INSERT bir SAVEPOINT içinde koşuyor: başarısız bir INSERT transaction'ı
+     * ABORT eder (25P02) ve savepoint olmadan yakalama işe yaramaz — hata
+     * yakalanır ama sonraki SELECT de "current transaction is aborted" alır.
+     */
+    claim(table: string, unique: Row, extra?: Row): Promise<{
+        inserted: boolean;
+        row: Row;
+    }>;
     /**
      * INSERT the row, or UPDATE it when it collides on `onConflict`.
      *
@@ -458,7 +243,7 @@ declare function createOps(tx: TxLike): {
      * The conflict columns are excluded from the SET list: they are what MATCHED,
      * so writing them back is at best a no-op and at worst a surprise.
      */
-    upsert(table: string, data: Row, opts: {
+    put(table: string, data: Row, opts: {
         onConflict: readonly string[];
     }): Promise<Row>;
     update(table: string, id: string, data: Row): Promise<Row | null>;
@@ -523,9 +308,6 @@ declare function createOps(tx: TxLike): {
         };
         /** Chunk-modunda satır başına dönen en iyi blok sayısı (1..10, vars. 3; FR-015). */
         blocksPerRow?: number;
-        /** Filtrelenmiş küme üzerinde kolon başına top-20 değer sayacı —
-         * dönüş dizisinin `_facets` özelliği (FR-027). */
-        facets?: string[];
         /** Satır-modunda FTS eşleşme vurgusu: ts_headline ile `_highlight`
          * alanı; chunk-modda no-op — bloklar zaten eşleşen kesittir (FR-025). */
         highlight?: boolean;
@@ -627,10 +409,10 @@ declare function createOps(tx: TxLike): {
      * rolls back only what that handle wrote and the request can keep writing.
      *
      * WHY THE HANDLE IS AN ARGUMENT. The obvious shape — `attempt(async () => {
-     * ... Database.insert(...) ... })`, with no parameter — would have to point
+     * ... Database.$insert(...) ... })`, with no parameter — would have to point
      * the ambient `Database` at the savepoint for the duration, and a request is
-     * concurrent with itself: `Promise.all([Database.insert(a),
-     * Database.attempt(...)])` would put `a` inside the savepoint and roll it
+     * concurrent with itself: `Promise.all([Database.$insert(a),
+     * Database.$attempt(...)])` would put `a` inside the savepoint and roll it
      * back with it. Silent data loss, and the same interleaving this file already
      * refuses for `asService()`. Passing the handle makes the boundary something
      * you can see in the code that crosses it.
@@ -641,7 +423,7 @@ declare function createOps(tx: TxLike): {
      */
     attempt<T>(fn: (tx: DBOps) => Promise<T>): Promise<T>;
     /**
-     * Execute a whole transaction plan — what `Database.transaction(fn)` builds.
+     * Execute a whole transaction plan — what `Database.$transaction(fn)` builds.
      *
      * WHY IT RUNS HERE. The platform used to carry a complete implementation
      * of this at `/internal-api/db/tx`, for tenant code that ran in an isolate
@@ -703,7 +485,7 @@ interface RequestDatabase {
  *
  * The obvious repair — re-issue `set_config('role', …)` around each service op
  * — is worse than the bug. Two statements are not one: `Promise.all([
- * Database.query(…), Database.asService().query(…) ])` interleaves them on the
+ * Database.$query(…), Database.$asService().$query(…) ])` interleaves them on the
  * single connection, and the user's query can execute between the service's
  * set-role and its own statement. That is RLS silently OFF on the DEFAULT path,
  * which is precisely the direction a security seam must never fail.
@@ -745,6 +527,91 @@ declare function createRequestDatabase(sql: SqlDriver, identity: {
     claimsJson: string;
 }): RequestDatabase;
 
+/**
+ * How a container refuses.
+ *
+ * Every refusal is one of these, and every one names the class involved. There
+ * is deliberately no "unknown" member: a failure this list cannot classify is a
+ * failure the error surface has not been taught to explain, and that is a defect
+ * rather than a category.
+ */
+type DiKind = "unresolvable dependency" | "private dependency" | "missing import" | "unowned class" | "dependency cycle" | "metadata missing" | "generic dependency" | "duplicate ownership" | "unknown export" | "unknown import" | "undeclared provider";
+/**
+ * A refusal carries four parts: what kind, the full resolution path, where
+ * exactly, and what to do about it.
+ *
+ * The shape is borrowed on purpose — Angular's path, Awilix's failure kind, and
+ * Nest's list of potential solutions — because each of the three answers a
+ * question the other two leave open: what broke, where in the graph, and what
+ * the author should type next.
+ */
+declare class DiError extends Error {
+    readonly kind: DiKind;
+    readonly path: string[];
+    readonly at: string;
+    readonly fixes: string[];
+    constructor(kind: DiKind, path: string[], at: string, detail: string, fixes: string[]);
+}
+/** How often a module appears in the OTHERS' `imports`. */
+interface ModulePressure {
+    module: string;
+    pct: number;
+    /**
+     * How many OTHER modules there were — the denominator.
+     *
+     * Without it the percentage cannot be read. Measured 2026-09-02: a project
+     * with two modules, one importing the other, reports 100% — which is true and
+     * says nothing, because "all of the others" is one module. A reader deciding
+     * whether a module has become ambient needs to know whether 80% was four
+     * modules or one.
+     */
+    of: number;
+}
+interface Container {
+    get<T>(t: Token<T>): T;
+    /** Every class a module claimed — the set an entry point must be in. */
+    readonly owned: ReadonlySet<Token>;
+    /**
+     * Where `@Global()` pressure is accumulating.
+     *
+     * A module that appears in more than ~80% of the others' `imports` is one the
+     * design is asking to be ambient. That is a JUDGEMENT — how much sharing is
+     * too much depends on the domain — so this is reported as a number and never
+     * enforced as a gate. Lives on the container rather than in a module-level
+     * variable: the runtime builds a candidate's container beside the live app's,
+     * and a shared variable would have one overwrite the other's report.
+     */
+    readonly pressure: readonly ModulePressure[];
+}
+/**
+ * Validates the declared modules and returns a container over them.
+ *
+ * Validation runs in a fixed order, and the order is the point: each stage may
+ * assume the previous one held, so a message never has to hedge. Ownership
+ * before exports, exports before dependencies, dependencies before cycles,
+ * cycles before construction.
+ *
+ * Stages 3-5 (dependencies and visibility, cycles, resolution) are added by the
+ * tasks that follow; this file grows, it is not replaced.
+ */
+declare function buildContainer(): Container;
+
+/**
+ * Refuses an entry point that no module lists (FR-035).
+ *
+ * A decorated class registers itself — `@Controller` pushes into a globalThis
+ * slot the moment its file is imported — so before this check a class listed in
+ * no module still reached the route table, the dispatcher and the OpenAPI
+ * document. It worked, which is the problem: nothing said the module system had
+ * been bypassed.
+ *
+ * After this, a successful boot means the two sets are EQUAL: what decorated
+ * itself and what a module claimed. That equality is what lets `src/openapi/`
+ * stay untouched — it renders the list it is handed, and the list is now the
+ * module's.
+ */
+declare function assertNoOrphanEntryPoints(registered: readonly unknown[], owned: ReadonlySet<Token>): void;
+
 interface RouteEntry {
     method: string;
     /** Path segments; a parameter segment is stored as `:name`. */
@@ -770,7 +637,7 @@ interface RouteEntry {
  *   silence one level down (FR-010): nothing here has an argument to pass, so
  *   the field would simply be `undefined` in production.
  */
-declare function buildRouteTable(controllers: readonly unknown[]): RouteEntry[];
+declare function buildRouteTable(controllers: readonly unknown[], container: Container): RouteEntry[];
 interface RouteMatch {
     entry: RouteEntry;
     params: Record<string, string>;
@@ -1045,6 +912,14 @@ interface App {
     runInServiceScope: <T>(fn: () => T | Promise<T>) => Promise<T>;
     /** Close the pool and release resources. */
     shutdown: () => Promise<void>;
+    /**
+     * The container this app resolved its classes from.
+     *
+     * Exposed because entry points the ENGINE does not own are built elsewhere:
+     * the runtime constructs rooms, jobs and hooks, and they must come from THIS
+     * app's graph rather than a second one built beside it (FR-037, FR-042).
+     */
+    readonly container: Container;
 }
 /**
  * Build the app. Fails fast: the database is reached here, at boot, rather than
@@ -1052,4 +927,4 @@ interface App {
  */
 declare function createApp(opts: CreateAppOptions): Promise<App>;
 
-export { type App as A, BootRefused as B, Cache as C, Database as D, type EgressPolicy as E, Flags as F, createOps as G, createRequestDatabase as H, effectiveAuth as I, hostAllowed as J, installEgressFence as K, type LifecycleHook as L, type ModuleClients as M, Notifications as N, loadConfig as O, makeMemoryCache as P, matchRoute as Q, Realtime as R, Secrets as S, quoteIdent as T, scrubSecrets as U, withTables as V, __getRuntime as _, Documents as a, Log as b, type RequestStore as c, type RuntimeServices as d, type ShutdownRunner as e, Storage as f, __requestALS as g, __resetLifecycleHooks as h, __runStartHooks as i, __runWithRuntime as j, __setRuntime as k, onStart as l, AuthVerifier as m, type CreateAppOptions as n, onShutdown as o, type EngineConfig as p, RateLimiter as q, type RequestDatabase as r, type RouteEntry as s, type RuntimeHooks as t, type ScrubResult as u, type SqlDriver as v, type SqlTx as w, buildRouteTable as x, createApp as y, createLazyTransaction as z };
+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 };