@palbase/backend 22.1.0 → 23.1.0

package/dist/{registry-Bsuf-orT.d.ts → registry-B3niOVYp.d.ts}

@@ -1,161 +1,12 @@
-import { A as AuthSpec, R as RateLimitConfig } from './endpoint-BVT6jcVW.js';
+import { A as AuthSpec, R as RateLimitConfig } from './endpoint-CVWXh6oG.js';
 import { ZodTypeAny } from 'zod';
-
-/**
- * storage.ts — the storage-buckets config-as-code DSL.
- *
- * `defineStorage({ buckets })` is the first MODULE config-as-code surface (the
- * sibling of `db/schema.ts`'s `defineSchema`). A `config/storage.ts` file
- * default-exports a `defineStorage(...)` result; on deploy the br-pod evaluates
- * it to JSON and reconciles the declared buckets against the tenant's live
- * buckets via the Storage admin API (create missing, update changed; never
- * auto-delete — dropping a bucket is destructive and warned only).
- *
- * Buckets are DECLARATIVE: name + access + size/mime limits. The FILES inside a
- * bucket are runtime state (uploaded via the SDK), never in git.
- *
- * @example
- * import { defineStorage, bucket } from "@palbase/backend";
- *
- * export default defineStorage({
- *   buckets: {
- *     avatars: bucket({
- *       public: true,
- *       fileSizeLimit: "5MB",
- *       allowedMimeTypes: ["image/png", "image/jpeg", "image/webp"],
- *     }),
- *     invoices: bucket({
- *       public: false,
- *       fileSizeLimit: "20MB",
- *       allowedMimeTypes: ["application/pdf"],
- *     }),
- *   },
- * });
- *
- * The returned value is the EXACT JSON shape the runtime's generic config
- * extractor (`config_extract.js`) emits and the Go apply step parses:
- *   { __config: "storage", buckets: { avatars: { public, fileSizeLimit, allowedMimeTypes }, ... } }
- * `fileSizeLimit` is always normalized to a number of bytes (or null when
- * omitted, meaning "no limit"); the apply step maps it to the Storage API's
- * `file_size_limit` field. `allowedMimeTypes` is the allowlist or null (any).
- */
-/** The discriminant written under `__config` so the eval/apply can tell which
- * module config a `config/*.ts` file describes. Storage is `"storage"`. */
-declare const STORAGE_CONFIG_KIND: "storage";
-/**
- * The author-facing options for a single bucket.
- *
- * - `public`: when true the bucket is served without a signed URL. Defaults to
- *   `false` (private — signed URLs only).
- * - `fileSizeLimit`: the per-object upload cap. Accepts a human string
- *   (`"5MB"`, `"20MB"`, `"1GB"`) or a bare number of BYTES. Omit for no limit.
- * - `allowedMimeTypes`: an allowlist of MIME types accepted on upload. Omit to
- *   allow any type. Each entry must look like `type/subtype` (e.g. `image/png`,
- *   `application/pdf`, or a wildcard `image/*`).
- */
-interface BucketOptions {
-    public?: boolean;
-    fileSizeLimit?: string | number;
-    allowedMimeTypes?: string[];
-    variants?: Record<string, ImageVariant>;
-}
-/**
- * One named rendition of an uploaded image — the same three knobs
- * `getPublicUrl(path, ...)` takes, given a name so the size lives with the
- * bucket instead of being retyped at every call site.
- *
- * At least one of `width` / `height` must be set (a variant that resizes
- * nothing and converts nothing is a typo, not a variant).
- */
-interface ImageVariant {
-    width?: number;
-    height?: number;
-    /**
-     * How the source is made to meet the box. Defaults to `"contain"`.
-     *
-     * - `cover` fills the box exactly and crops the overflow from the centre —
-     *   what a square avatar or a grid cell needs.
-     * - `contain` fits the whole picture inside the box, cropping nothing. One
-     *   side may come out smaller than declared.
-     * - `inside` is `contain` that never ENLARGES. Blowing a 100px image up to
-     *   1000px produces a blurry picture that is bigger on the wire.
-     */
-    fit?: "cover" | "contain" | "inside";
-    format?: "webp" | "avif" | "jpeg" | "png";
-    /** Encoder quality, 1–100. Defaults to 85. JPEG only. */
-    quality?: number;
-}
-/**
- * The compiled, serializable bucket definition — the EXACT shape emitted to
- * JSON and consumed by the Go apply step.
- *
- * - `public`: always present (defaulted to `false`).
- * - `fileSizeLimit`: bytes as a number, or `null` for "no limit".
- * - `allowedMimeTypes`: the MIME allowlist, or `null` for "any type".
- */
-interface BucketDef {
-    public: boolean;
-    fileSizeLimit: number | null;
-    allowedMimeTypes: string[] | null;
-    /** Named renditions, or `null` when none are declared. Rendered AT UPLOAD and
-     * stored as objects of their own, behind immutable URLs. */
-    variants: Record<string, ImageVariant> | null;
-}
-/** A storage config definition: the discriminant + a map of bucket name →
- * {@link BucketDef}. This is the value `defineStorage` returns and the runtime
- * config extractor serializes. */
-interface StorageConfig {
-    __config: typeof STORAGE_CONFIG_KIND;
-    buckets: Record<string, BucketDef>;
-}
-/** The author-facing input to `defineStorage`: a `buckets` map whose keys are
- * the bucket names and whose values are `bucket({...})` builders. */
-interface StorageInput {
-    buckets: Record<string, BucketDef>;
-}
-/**
- * Parse a `fileSizeLimit` into a number of bytes.
- *
- * - A bare number is taken as bytes verbatim (must be a non-negative integer).
- * - A string is `<number><unit>` (e.g. `"5MB"`, `"1.5GB"`, `"500kb"`); the unit
- *   is case-insensitive and optional (a bare numeric string = bytes). Binary
- *   units (1 MB = 1024 squared bytes) to match the Storage module's parser.
- *
- * Throws on a negative value, a non-finite number, or an unrecognized unit so a
- * bad limit fails at config-author time, not silently at deploy.
- */
-declare function parseFileSizeLimit(input: string | number): number;
-/**
- * Define a single bucket. The bucket NAME is supplied by the key in
- * `defineStorage({ buckets: { <name>: bucket({...}) } })`, so `bucket()` takes
- * only the options.
- *
- * Validates eagerly (at config-author time):
- *  - `fileSizeLimit` parses to a valid non-negative byte count.
- *  - each `allowedMimeTypes` entry is a `type/subtype` MIME string.
- *
- * Returns a normalized {@link BucketDef}: `public` defaulted to `false`,
- * `fileSizeLimit` as bytes-or-null, `allowedMimeTypes` deduped-or-null.
- */
-declare function bucket(opts?: BucketOptions): BucketDef;
-/**
- * Define the storage config for a project. The bucket NAME comes from each
- * object key (authors never repeat the name). Returns the discriminated
- * {@link StorageConfig} the runtime config extractor serializes and the Go
- * apply step reconciles.
- *
- * @example
- * export default defineStorage({
- *   buckets: { avatars: bucket({ public: true, fileSizeLimit: "5MB" }) },
- * });
- */
-declare function defineStorage(input: StorageInput): StorageConfig;
+import { PalbaseBucketName } from './stack.js';
 
 /** A legacy method decorator (`experimentalDecorators`): `(prototype, name,
  * descriptor)`. */
-type MethodDecorator = (target: object, propertyKey: string | symbol, descriptor: PropertyDescriptor) => void;
+type MethodDecorator$1 = (target: object, propertyKey: string | symbol, descriptor: PropertyDescriptor) => void;
 /** A legacy parameter decorator: `(prototype, name, paramIndex)`. */
-type ParameterDecorator = (target: object, propertyKey: string | symbol, parameterIndex: number) => void;
+type ParameterDecorator$1 = (target: object, propertyKey: string | symbol, parameterIndex: number) => void;
 /**
  * Direct-storage upload settings for an `@Upload` route. The br-pod validates an
  * authorize request against these (size/type), then mints a signed upload URL
@@ -164,7 +15,13 @@ type ParameterDecorator = (target: object, propertyKey: string | symbol, paramet
  */
 interface UploadConfig {
     /**
-     * Target bucket NAME. MUST exist in `config/storage.ts` `defineStorage(...)`.
+     * Target bucket NAME — one the STACK holds.
+     *
+     * The union comes from the generated `palbase-stack.d.ts`, so a bucket the
+     * stack does not carry is a compile error. It used to say "MUST exist in
+     * `config/storage.ts` defineStorage(...)", and that invariant was carried by
+     * this sentence plus a cross-check nothing called; it is carried by the type
+     * now.
      *
      * The bucket is the SINGLE SOURCE OF TRUTH for the size limit + MIME allowlist:
      * `bucket({ fileSizeLimit, allowedMimeTypes })`. Storage enforces those at the
@@ -174,7 +31,7 @@ interface UploadConfig {
      * enforce (a real bypass: declare 10 bytes at authorize, then PUT up to the
      * bucket ceiling straight at the signed URL). One bucket, one limit, enforced.
      */
-    bucket: string;
+    bucket: PalbaseBucketName;
     /**
      * SERVER-side object key template. The client NEVER chooses the path. Tokens:
      * `{userId}` (authenticated user id), `{uploadId}` (server-minted), and
@@ -191,10 +48,10 @@ interface UploadConfig {
  * @example
  * ＠Upload("/", { bucket: "docs", pathTemplate: "{userId}/{uploadId}-{filename}" })
  * async upload(＠UploadedObject() obj: UploadedObject, ＠User() user): Promise<DocResult> { ... }
- * // The size limit + MIME allowlist come from the "docs" bucket in
- * // config/storage.ts — storage enforces them at the PUT.
+ * // The size limit + MIME allowlist come from the "docs" bucket ON THE STACK
+ * // — storage enforces them at the PUT.
  */
-declare function Upload(subpath: string, config: UploadConfig & Pick<RouteOptions, "auth" | "rateLimit">): MethodDecorator;
+declare function Upload(subpath: string, config: UploadConfig & Pick<RouteOptions, "auth" | "rateLimit">): MethodDecorator$1;
 /**
  * The uploaded object, injected into an `@Upload` method body by
  * `@UploadedObject()` once storage confirms the upload. Bytes are NOT present
@@ -249,20 +106,94 @@ interface UploadedObject {
  * Co-located with the {@link UploadedObject} TYPE so a single exported name
  * `UploadedObject` carries BOTH the decorator value and the type annotation.
  */
-declare function UploadedObject(): ParameterDecorator;
+declare function UploadedObject(): ParameterDecorator$1;
+
+/** A legacy method decorator (`experimentalDecorators`): `(prototype, name,
+ * descriptor)`. */
+type MethodDecorator = (target: object, propertyKey: string | symbol, descriptor: PropertyDescriptor) => void;
+/** A legacy parameter decorator: `(prototype, name, paramIndex)`. */
+type ParameterDecorator = (target: object, propertyKey: string | symbol, parameterIndex: number) => void;
+/**
+ * Settings for an `@Sse` route.
+ *
+ * EMPTY in v1, and deliberately so: the pipeline keys off this object's
+ * PRESENCE, not its contents (see the file header). Declaring the type now means
+ * a later setting arrives as a field on an existing marker rather than as a
+ * second marker nothing downstream reads.
+ */
+interface SseConfig {
+    /**
+     * The shape of ONE frame — what a single `out.write(value)` carries.
+     *
+     * REQUIRED, not optional, and that is the whole point. An `@Sse` handler
+     * returns `Promise<void>`, so the codegen-injected `recordReturn` has no type
+     * to record and nothing downstream can infer what a frame is. A route without
+     * this declares a stream whose element type is unknown, and every generated
+     * client from that contract is opaque — which is precisely the failure
+     * `x-palbase-sse` exists to prevent. Making it optional would have left that
+     * failure one forgotten field away.
+     *
+     * Measured live on a real pushed stack (2026-08-29): the contract gate refused
+     * the deploy with "2 untyped response(s) — every generated client from it is
+     * opaque", naming both routes that omitted it.
+     */
+    frame: ZodTypeAny;
+}
+/**
+ * The writer injected by `@SseOut()`. Each `write` emits ONE SSE `data:` frame
+ * carrying `value` JSON-encoded.
+ *
+ * The FIRST `write` is load-bearing beyond its frame: it settles the request's
+ * database transaction. A streaming response may run for minutes, and the
+ * handler runs inside the request's transaction — holding one open for the life
+ * of a stream exhausts the connection pool, a failure invisible to a unit test
+ * that only dies under load. So the first frame is the point at which the
+ * request phase is declared over, and database access after it is refused by
+ * name rather than silently run against a settled transaction.
+ *
+ * The practical rule for a handler: do the database work BEFORE the first write.
+ */
+interface SseWriter {
+    write(value: unknown): void;
+}
+/**
+ * `@Sse(subpath, config)` — declare a streaming route.
+ *
+ * @example
+ * ＠Sse("/chat", { frame: ChatFrame })
+ * async chat(＠Body() b: ChatInput, ＠SseOut() out: SseWriter, ＠Signal() signal: AbortSignal) {
+ *   const stream = await openai.chat.completions.create(
+ *     { model: "gpt-5.6", messages: b.messages, stream: true },
+ *     { signal },
+ *   );
+ *   for await (const chunk of stream) out.write(chunk);
+ * }
+ * // The client disconnects → `signal` aborts → the provider stops being pulled.
+ * // The signal is a plain AbortSignal, so it goes wherever the provider takes
+ * // one: `{ signal }` for the OpenAI and Anthropic SDKs, `abortSignal:` for the
+ * // Vercel AI SDK, `fetch(url, { signal })` for a raw call.
+ */
+declare function Sse(subpath: string | undefined, config: SseConfig & Pick<RouteOptions, "auth" | "rateLimit">): MethodDecorator;
+/**
+ * `@SseOut()` — inject the frame writer (`: SseWriter`) into an `@Sse` method
+ * body. Only meaningful on an `@Sse` route.
+ */
+declare function SseOut(): ParameterDecorator;
 /**
- * Cross-check one `@Upload` route's uploadConfig against the project's
- * {@link StorageConfig}: the named bucket MUST exist in `defineStorage(...)`.
- * Throws a precise error so a typo fails at deploy, not at the first user upload.
+ * `@Signal()` — inject the request's `AbortSignal`, which enters the aborted
+ * state when the client disconnects.
  *
- * That is the ONLY cross-check: the size limit + MIME allowlist live on the
- * bucket (`bucket({ fileSizeLimit, allowedMimeTypes })`) and are enforced by
- * storage at the PUT. `@Upload` carries no `maxSize`/`allowedTypes` of its own,
- * so there is nothing to compare — one bucket, one limit, no drift.
+ * NOT derivable from `@Req()`: `PBRequest` carries only request-scoped data —
+ * the typed input, route/query params, headers, the authenticated user, calling
+ * client metadata, trace ids, and the declared error throwers — and no signal
+ * (endpoint.ts:358-363).
  *
- * `routeLabel` is used only for error messages (e.g. `docs.upload`).
+ * Measured 2026-08-29 on Bun: an infinite producer guarded by this signal
+ * stopped four frames after the client was killed, and the handler's `finally`
+ * ran. It is the same mechanism a NestJS handler reaches through
+ * `req.on("close")`.
  */
-declare function validateUploadAgainstStorage(uploadConfig: UploadConfig, storage: StorageConfig, routeLabel: string): void;
+declare function Signal(): ParameterDecorator;
 
 /** The HTTP verbs a route may declare, upper-cased (the runtime router +
  * OpenAPI lower-case on their own). */
@@ -279,11 +210,18 @@ interface RouteOptions {
      * openapi → codegen). The bytes go client→storage directly; the method body
      * runs as the completion handler. See {@link UploadConfig} (decorators/upload.ts). */
     uploadConfig?: UploadConfig;
+    /** Streaming config — present ONLY on `@Sse` routes (the `@Get`/`@Post`/…
+     * decorators never set it). Its presence is what MARKS a route as a streaming
+     * route through the whole pipeline (registry → flatten → openapi → codegen),
+     * exactly as `uploadConfig` does for uploads — never a special HTTP verb. An
+     * `@Sse` route registers POST like any input-bearing route, so the verb cannot
+     * carry the distinction. See {@link SseConfig} (decorators/sse.ts). */
+    sseConfig?: SseConfig;
 }
 /** The kind of value a parameter decorator injects. Drives both dispatch
  * (which request slice to inject) and codegen (which OpenAPI parameter source a
  * schema-bearing kind maps to). */
-type ParamKind = "body" | "query" | "param" | "headers" | "user" | "optionalUser" | "client" | "requestId" | "traceId" | "req" | "uploadedObject";
+type ParamKind = "body" | "query" | "param" | "headers" | "user" | "optionalUser" | "client" | "requestId" | "traceId" | "req" | "uploadedObject" | "sseOut" | "signal";
 /** One parameter decorator's recorded metadata. `index` is the parameter
  * position esbuild/tsc preserve; `schema` is present for the schema-bearing
  * kinds (`body`/`query`/`headers`); `name` is the path-param name for `param`. */
@@ -335,4 +273,4 @@ declare function recordThrows(target: object, fnName: string, throws: ThrowDescr
  */
 declare function getRoutes(ctor: object): RouteMeta[];
 
-export { type BucketDef as B, type HttpMethodUpper as H, type ImageVariant as I, type ParamMeta as P, type RouteMeta as R, STORAGE_CONFIG_KIND as S, type ThrowDescriptor as T, type UploadConfig as U, type RouteOptions as a, type BucketOptions as b, type ParamKind as c, type StorageConfig as d, type StorageInput as e, Upload as f, UploadedObject as g, bucket as h, defineStorage as i, getRoutes as j, parseFileSizeLimit as p, recordThrows as r, validateUploadAgainstStorage as v };
+export { type HttpMethodUpper as H, type ParamMeta as P, type RouteMeta as R, type SseConfig as S, type ThrowDescriptor as T, type UploadConfig as U, type RouteOptions as a, type ParamKind as b, Signal as c, Sse as d, SseOut as e, type SseWriter as f, Upload as g, UploadedObject as h, getRoutes as i, recordThrows as r };

package/dist/{registry-BWttGlaT.d.cts → registry-CqPK2Qby.d.cts}

@@ -1,161 +1,12 @@
-import { A as AuthSpec, R as RateLimitConfig } from './endpoint-BVT6jcVW.cjs';
+import { A as AuthSpec, R as RateLimitConfig } from './endpoint-c9h5jriX.cjs';
 import { ZodTypeAny } from 'zod';
-
-/**
- * storage.ts — the storage-buckets config-as-code DSL.
- *
- * `defineStorage({ buckets })` is the first MODULE config-as-code surface (the
- * sibling of `db/schema.ts`'s `defineSchema`). A `config/storage.ts` file
- * default-exports a `defineStorage(...)` result; on deploy the br-pod evaluates
- * it to JSON and reconciles the declared buckets against the tenant's live
- * buckets via the Storage admin API (create missing, update changed; never
- * auto-delete — dropping a bucket is destructive and warned only).
- *
- * Buckets are DECLARATIVE: name + access + size/mime limits. The FILES inside a
- * bucket are runtime state (uploaded via the SDK), never in git.
- *
- * @example
- * import { defineStorage, bucket } from "@palbase/backend";
- *
- * export default defineStorage({
- *   buckets: {
- *     avatars: bucket({
- *       public: true,
- *       fileSizeLimit: "5MB",
- *       allowedMimeTypes: ["image/png", "image/jpeg", "image/webp"],
- *     }),
- *     invoices: bucket({
- *       public: false,
- *       fileSizeLimit: "20MB",
- *       allowedMimeTypes: ["application/pdf"],
- *     }),
- *   },
- * });
- *
- * The returned value is the EXACT JSON shape the runtime's generic config
- * extractor (`config_extract.js`) emits and the Go apply step parses:
- *   { __config: "storage", buckets: { avatars: { public, fileSizeLimit, allowedMimeTypes }, ... } }
- * `fileSizeLimit` is always normalized to a number of bytes (or null when
- * omitted, meaning "no limit"); the apply step maps it to the Storage API's
- * `file_size_limit` field. `allowedMimeTypes` is the allowlist or null (any).
- */
-/** The discriminant written under `__config` so the eval/apply can tell which
- * module config a `config/*.ts` file describes. Storage is `"storage"`. */
-declare const STORAGE_CONFIG_KIND: "storage";
-/**
- * The author-facing options for a single bucket.
- *
- * - `public`: when true the bucket is served without a signed URL. Defaults to
- *   `false` (private — signed URLs only).
- * - `fileSizeLimit`: the per-object upload cap. Accepts a human string
- *   (`"5MB"`, `"20MB"`, `"1GB"`) or a bare number of BYTES. Omit for no limit.
- * - `allowedMimeTypes`: an allowlist of MIME types accepted on upload. Omit to
- *   allow any type. Each entry must look like `type/subtype` (e.g. `image/png`,
- *   `application/pdf`, or a wildcard `image/*`).
- */
-interface BucketOptions {
-    public?: boolean;
-    fileSizeLimit?: string | number;
-    allowedMimeTypes?: string[];
-    variants?: Record<string, ImageVariant>;
-}
-/**
- * One named rendition of an uploaded image — the same three knobs
- * `getPublicUrl(path, ...)` takes, given a name so the size lives with the
- * bucket instead of being retyped at every call site.
- *
- * At least one of `width` / `height` must be set (a variant that resizes
- * nothing and converts nothing is a typo, not a variant).
- */
-interface ImageVariant {
-    width?: number;
-    height?: number;
-    /**
-     * How the source is made to meet the box. Defaults to `"contain"`.
-     *
-     * - `cover` fills the box exactly and crops the overflow from the centre —
-     *   what a square avatar or a grid cell needs.
-     * - `contain` fits the whole picture inside the box, cropping nothing. One
-     *   side may come out smaller than declared.
-     * - `inside` is `contain` that never ENLARGES. Blowing a 100px image up to
-     *   1000px produces a blurry picture that is bigger on the wire.
-     */
-    fit?: "cover" | "contain" | "inside";
-    format?: "webp" | "avif" | "jpeg" | "png";
-    /** Encoder quality, 1–100. Defaults to 85. JPEG only. */
-    quality?: number;
-}
-/**
- * The compiled, serializable bucket definition — the EXACT shape emitted to
- * JSON and consumed by the Go apply step.
- *
- * - `public`: always present (defaulted to `false`).
- * - `fileSizeLimit`: bytes as a number, or `null` for "no limit".
- * - `allowedMimeTypes`: the MIME allowlist, or `null` for "any type".
- */
-interface BucketDef {
-    public: boolean;
-    fileSizeLimit: number | null;
-    allowedMimeTypes: string[] | null;
-    /** Named renditions, or `null` when none are declared. Rendered AT UPLOAD and
-     * stored as objects of their own, behind immutable URLs. */
-    variants: Record<string, ImageVariant> | null;
-}
-/** A storage config definition: the discriminant + a map of bucket name →
- * {@link BucketDef}. This is the value `defineStorage` returns and the runtime
- * config extractor serializes. */
-interface StorageConfig {
-    __config: typeof STORAGE_CONFIG_KIND;
-    buckets: Record<string, BucketDef>;
-}
-/** The author-facing input to `defineStorage`: a `buckets` map whose keys are
- * the bucket names and whose values are `bucket({...})` builders. */
-interface StorageInput {
-    buckets: Record<string, BucketDef>;
-}
-/**
- * Parse a `fileSizeLimit` into a number of bytes.
- *
- * - A bare number is taken as bytes verbatim (must be a non-negative integer).
- * - A string is `<number><unit>` (e.g. `"5MB"`, `"1.5GB"`, `"500kb"`); the unit
- *   is case-insensitive and optional (a bare numeric string = bytes). Binary
- *   units (1 MB = 1024 squared bytes) to match the Storage module's parser.
- *
- * Throws on a negative value, a non-finite number, or an unrecognized unit so a
- * bad limit fails at config-author time, not silently at deploy.
- */
-declare function parseFileSizeLimit(input: string | number): number;
-/**
- * Define a single bucket. The bucket NAME is supplied by the key in
- * `defineStorage({ buckets: { <name>: bucket({...}) } })`, so `bucket()` takes
- * only the options.
- *
- * Validates eagerly (at config-author time):
- *  - `fileSizeLimit` parses to a valid non-negative byte count.
- *  - each `allowedMimeTypes` entry is a `type/subtype` MIME string.
- *
- * Returns a normalized {@link BucketDef}: `public` defaulted to `false`,
- * `fileSizeLimit` as bytes-or-null, `allowedMimeTypes` deduped-or-null.
- */
-declare function bucket(opts?: BucketOptions): BucketDef;
-/**
- * Define the storage config for a project. The bucket NAME comes from each
- * object key (authors never repeat the name). Returns the discriminated
- * {@link StorageConfig} the runtime config extractor serializes and the Go
- * apply step reconciles.
- *
- * @example
- * export default defineStorage({
- *   buckets: { avatars: bucket({ public: true, fileSizeLimit: "5MB" }) },
- * });
- */
-declare function defineStorage(input: StorageInput): StorageConfig;
+import { PalbaseBucketName } from './stack.cjs';
 
 /** A legacy method decorator (`experimentalDecorators`): `(prototype, name,
  * descriptor)`. */
-type MethodDecorator = (target: object, propertyKey: string | symbol, descriptor: PropertyDescriptor) => void;
+type MethodDecorator$1 = (target: object, propertyKey: string | symbol, descriptor: PropertyDescriptor) => void;
 /** A legacy parameter decorator: `(prototype, name, paramIndex)`. */
-type ParameterDecorator = (target: object, propertyKey: string | symbol, parameterIndex: number) => void;
+type ParameterDecorator$1 = (target: object, propertyKey: string | symbol, parameterIndex: number) => void;
 /**
  * Direct-storage upload settings for an `@Upload` route. The br-pod validates an
  * authorize request against these (size/type), then mints a signed upload URL
@@ -164,7 +15,13 @@ type ParameterDecorator = (target: object, propertyKey: string | symbol, paramet
  */
 interface UploadConfig {
     /**
-     * Target bucket NAME. MUST exist in `config/storage.ts` `defineStorage(...)`.
+     * Target bucket NAME — one the STACK holds.
+     *
+     * The union comes from the generated `palbase-stack.d.ts`, so a bucket the
+     * stack does not carry is a compile error. It used to say "MUST exist in
+     * `config/storage.ts` defineStorage(...)", and that invariant was carried by
+     * this sentence plus a cross-check nothing called; it is carried by the type
+     * now.
      *
      * The bucket is the SINGLE SOURCE OF TRUTH for the size limit + MIME allowlist:
      * `bucket({ fileSizeLimit, allowedMimeTypes })`. Storage enforces those at the
@@ -174,7 +31,7 @@ interface UploadConfig {
      * enforce (a real bypass: declare 10 bytes at authorize, then PUT up to the
      * bucket ceiling straight at the signed URL). One bucket, one limit, enforced.
      */
-    bucket: string;
+    bucket: PalbaseBucketName;
     /**
      * SERVER-side object key template. The client NEVER chooses the path. Tokens:
      * `{userId}` (authenticated user id), `{uploadId}` (server-minted), and
@@ -191,10 +48,10 @@ interface UploadConfig {
  * @example
  * ＠Upload("/", { bucket: "docs", pathTemplate: "{userId}/{uploadId}-{filename}" })
  * async upload(＠UploadedObject() obj: UploadedObject, ＠User() user): Promise<DocResult> { ... }
- * // The size limit + MIME allowlist come from the "docs" bucket in
- * // config/storage.ts — storage enforces them at the PUT.
+ * // The size limit + MIME allowlist come from the "docs" bucket ON THE STACK
+ * // — storage enforces them at the PUT.
  */
-declare function Upload(subpath: string, config: UploadConfig & Pick<RouteOptions, "auth" | "rateLimit">): MethodDecorator;
+declare function Upload(subpath: string, config: UploadConfig & Pick<RouteOptions, "auth" | "rateLimit">): MethodDecorator$1;
 /**
  * The uploaded object, injected into an `@Upload` method body by
  * `@UploadedObject()` once storage confirms the upload. Bytes are NOT present
@@ -249,20 +106,94 @@ interface UploadedObject {
  * Co-located with the {@link UploadedObject} TYPE so a single exported name
  * `UploadedObject` carries BOTH the decorator value and the type annotation.
  */
-declare function UploadedObject(): ParameterDecorator;
+declare function UploadedObject(): ParameterDecorator$1;
+
+/** A legacy method decorator (`experimentalDecorators`): `(prototype, name,
+ * descriptor)`. */
+type MethodDecorator = (target: object, propertyKey: string | symbol, descriptor: PropertyDescriptor) => void;
+/** A legacy parameter decorator: `(prototype, name, paramIndex)`. */
+type ParameterDecorator = (target: object, propertyKey: string | symbol, parameterIndex: number) => void;
+/**
+ * Settings for an `@Sse` route.
+ *
+ * EMPTY in v1, and deliberately so: the pipeline keys off this object's
+ * PRESENCE, not its contents (see the file header). Declaring the type now means
+ * a later setting arrives as a field on an existing marker rather than as a
+ * second marker nothing downstream reads.
+ */
+interface SseConfig {
+    /**
+     * The shape of ONE frame — what a single `out.write(value)` carries.
+     *
+     * REQUIRED, not optional, and that is the whole point. An `@Sse` handler
+     * returns `Promise<void>`, so the codegen-injected `recordReturn` has no type
+     * to record and nothing downstream can infer what a frame is. A route without
+     * this declares a stream whose element type is unknown, and every generated
+     * client from that contract is opaque — which is precisely the failure
+     * `x-palbase-sse` exists to prevent. Making it optional would have left that
+     * failure one forgotten field away.
+     *
+     * Measured live on a real pushed stack (2026-08-29): the contract gate refused
+     * the deploy with "2 untyped response(s) — every generated client from it is
+     * opaque", naming both routes that omitted it.
+     */
+    frame: ZodTypeAny;
+}
+/**
+ * The writer injected by `@SseOut()`. Each `write` emits ONE SSE `data:` frame
+ * carrying `value` JSON-encoded.
+ *
+ * The FIRST `write` is load-bearing beyond its frame: it settles the request's
+ * database transaction. A streaming response may run for minutes, and the
+ * handler runs inside the request's transaction — holding one open for the life
+ * of a stream exhausts the connection pool, a failure invisible to a unit test
+ * that only dies under load. So the first frame is the point at which the
+ * request phase is declared over, and database access after it is refused by
+ * name rather than silently run against a settled transaction.
+ *
+ * The practical rule for a handler: do the database work BEFORE the first write.
+ */
+interface SseWriter {
+    write(value: unknown): void;
+}
+/**
+ * `@Sse(subpath, config)` — declare a streaming route.
+ *
+ * @example
+ * ＠Sse("/chat", { frame: ChatFrame })
+ * async chat(＠Body() b: ChatInput, ＠SseOut() out: SseWriter, ＠Signal() signal: AbortSignal) {
+ *   const stream = await openai.chat.completions.create(
+ *     { model: "gpt-5.6", messages: b.messages, stream: true },
+ *     { signal },
+ *   );
+ *   for await (const chunk of stream) out.write(chunk);
+ * }
+ * // The client disconnects → `signal` aborts → the provider stops being pulled.
+ * // The signal is a plain AbortSignal, so it goes wherever the provider takes
+ * // one: `{ signal }` for the OpenAI and Anthropic SDKs, `abortSignal:` for the
+ * // Vercel AI SDK, `fetch(url, { signal })` for a raw call.
+ */
+declare function Sse(subpath: string | undefined, config: SseConfig & Pick<RouteOptions, "auth" | "rateLimit">): MethodDecorator;
+/**
+ * `@SseOut()` — inject the frame writer (`: SseWriter`) into an `@Sse` method
+ * body. Only meaningful on an `@Sse` route.
+ */
+declare function SseOut(): ParameterDecorator;
 /**
- * Cross-check one `@Upload` route's uploadConfig against the project's
- * {@link StorageConfig}: the named bucket MUST exist in `defineStorage(...)`.
- * Throws a precise error so a typo fails at deploy, not at the first user upload.
+ * `@Signal()` — inject the request's `AbortSignal`, which enters the aborted
+ * state when the client disconnects.
  *
- * That is the ONLY cross-check: the size limit + MIME allowlist live on the
- * bucket (`bucket({ fileSizeLimit, allowedMimeTypes })`) and are enforced by
- * storage at the PUT. `@Upload` carries no `maxSize`/`allowedTypes` of its own,
- * so there is nothing to compare — one bucket, one limit, no drift.
+ * NOT derivable from `@Req()`: `PBRequest` carries only request-scoped data —
+ * the typed input, route/query params, headers, the authenticated user, calling
+ * client metadata, trace ids, and the declared error throwers — and no signal
+ * (endpoint.ts:358-363).
  *
- * `routeLabel` is used only for error messages (e.g. `docs.upload`).
+ * Measured 2026-08-29 on Bun: an infinite producer guarded by this signal
+ * stopped four frames after the client was killed, and the handler's `finally`
+ * ran. It is the same mechanism a NestJS handler reaches through
+ * `req.on("close")`.
  */
-declare function validateUploadAgainstStorage(uploadConfig: UploadConfig, storage: StorageConfig, routeLabel: string): void;
+declare function Signal(): ParameterDecorator;
 
 /** The HTTP verbs a route may declare, upper-cased (the runtime router +
  * OpenAPI lower-case on their own). */
@@ -279,11 +210,18 @@ interface RouteOptions {
      * openapi → codegen). The bytes go client→storage directly; the method body
      * runs as the completion handler. See {@link UploadConfig} (decorators/upload.ts). */
     uploadConfig?: UploadConfig;
+    /** Streaming config — present ONLY on `@Sse` routes (the `@Get`/`@Post`/…
+     * decorators never set it). Its presence is what MARKS a route as a streaming
+     * route through the whole pipeline (registry → flatten → openapi → codegen),
+     * exactly as `uploadConfig` does for uploads — never a special HTTP verb. An
+     * `@Sse` route registers POST like any input-bearing route, so the verb cannot
+     * carry the distinction. See {@link SseConfig} (decorators/sse.ts). */
+    sseConfig?: SseConfig;
 }
 /** The kind of value a parameter decorator injects. Drives both dispatch
  * (which request slice to inject) and codegen (which OpenAPI parameter source a
  * schema-bearing kind maps to). */
-type ParamKind = "body" | "query" | "param" | "headers" | "user" | "optionalUser" | "client" | "requestId" | "traceId" | "req" | "uploadedObject";
+type ParamKind = "body" | "query" | "param" | "headers" | "user" | "optionalUser" | "client" | "requestId" | "traceId" | "req" | "uploadedObject" | "sseOut" | "signal";
 /** One parameter decorator's recorded metadata. `index` is the parameter
  * position esbuild/tsc preserve; `schema` is present for the schema-bearing
  * kinds (`body`/`query`/`headers`); `name` is the path-param name for `param`. */
@@ -335,4 +273,4 @@ declare function recordThrows(target: object, fnName: string, throws: ThrowDescr
  */
 declare function getRoutes(ctor: object): RouteMeta[];
 
-export { type BucketDef as B, type HttpMethodUpper as H, type ImageVariant as I, type ParamMeta as P, type RouteMeta as R, STORAGE_CONFIG_KIND as S, type ThrowDescriptor as T, type UploadConfig as U, type RouteOptions as a, type BucketOptions as b, type ParamKind as c, type StorageConfig as d, type StorageInput as e, Upload as f, UploadedObject as g, bucket as h, defineStorage as i, getRoutes as j, parseFileSizeLimit as p, recordThrows as r, validateUploadAgainstStorage as v };
+export { type HttpMethodUpper as H, type ParamMeta as P, type RouteMeta as R, type SseConfig as S, type ThrowDescriptor as T, type UploadConfig as U, type RouteOptions as a, type ParamKind as b, Signal as c, Sse as d, SseOut as e, type SseWriter as f, Upload as g, UploadedObject as h, getRoutes as i, recordThrows as r };