@palbase/backend 22.0.1 → 23.0.0

package/dist/{registry-3BLYv4si.d.ts → registry-C3H2uPeZ.d.cts}

@@ -1,155 +1,6 @@
-import { A as AuthSpec, R as RateLimitConfig } from './endpoint-B0LpZixz.js';
+import { A as AuthSpec, R as RateLimitConfig } from './endpoint-i8TTCohk.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)`. */
@@ -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,8 +48,8 @@ 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;
 /**
@@ -250,19 +107,6 @@ interface UploadedObject {
  * `UploadedObject` carries BOTH the decorator value and the type annotation.
  */
 declare function UploadedObject(): 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.
- *
- * 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.
- *
- * `routeLabel` is used only for error messages (e.g. `docs.upload`).
- */
-declare function validateUploadAgainstStorage(uploadConfig: UploadConfig, storage: StorageConfig, routeLabel: string): void;
 
 /** The HTTP verbs a route may declare, upper-cased (the runtime router +
  * OpenAPI lower-case on their own). */
@@ -335,4 +179,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 ThrowDescriptor as T, type UploadConfig as U, type RouteOptions as a, type ParamKind as b, Upload as c, UploadedObject as d, getRoutes as g, recordThrows as r };

package/dist/{registry-Cw0YEYCg.d.cts → registry-DY3d9l1k.d.ts}

@@ -1,155 +1,6 @@
-import { A as AuthSpec, R as RateLimitConfig } from './endpoint-B0LpZixz.cjs';
+import { A as AuthSpec, R as RateLimitConfig } from './endpoint-BavvbW4P.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)`. */
@@ -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,8 +48,8 @@ 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;
 /**
@@ -250,19 +107,6 @@ interface UploadedObject {
  * `UploadedObject` carries BOTH the decorator value and the type annotation.
  */
 declare function UploadedObject(): 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.
- *
- * 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.
- *
- * `routeLabel` is used only for error messages (e.g. `docs.upload`).
- */
-declare function validateUploadAgainstStorage(uploadConfig: UploadConfig, storage: StorageConfig, routeLabel: string): void;
 
 /** The HTTP verbs a route may declare, upper-cased (the runtime router +
  * OpenAPI lower-case on their own). */
@@ -335,4 +179,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 ThrowDescriptor as T, type UploadConfig as U, type RouteOptions as a, type ParamKind as b, Upload as c, UploadedObject as d, getRoutes as g, recordThrows as r };

package/dist/{purchases/keys.cjs → stack.cjs}

@@ -13,7 +13,7 @@ var __copyProps = (to, from, except, desc) => {
 };
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 
-// src/purchases/keys.ts
-var keys_exports = {};
-module.exports = __toCommonJS(keys_exports);
-//# sourceMappingURL=keys.cjs.map
+// src/stack.ts
+var stack_exports = {};
+module.exports = __toCommonJS(stack_exports);
+//# sourceMappingURL=stack.cjs.map

package/dist/stack.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/stack.ts"],"sourcesContent":["/**\n * `@palbase/backend/stack` — the controlled global augmentation target for the\n * names the project's STACK holds.\n *\n * `Secrets.get(...)`, the Flags client's key parameters and `@Upload({ bucket })`\n * take these unions, never a raw string, so a name the stack does not hold is a\n * COMPILE error rather than a 500 in production — or, worse, a silent read of a\n * secret nobody set.\n *\n * Three interfaces in ONE module because the three share a source and a refresh\n * moment: they all come from the linked environment's stack, and any `palbase\n * secret set` / `flags add` / `storage add` moves them together. `@palbase/\n * backend/env` and `@palbase/backend/purchases` stay separate for the opposite\n * reason — their sources are the schema and the catalog.\n *\n * All three are EMPTY by default; the generated `palbase-stack.d.ts` augments\n * them with one member per name:\n *\n *   // palbase-stack.d.ts (generated — do not edit)\n *   declare module \"@palbase/backend/stack\" {\n *     interface Secrets { OPENAI_API_KEY: true }\n *     interface Flags { newCheckout: true }\n *     interface Buckets { avatars: true }\n *   }\n *\n * A project that has not generated the file therefore has NO valid names, and\n * every call fails to compile until it does. That is the intended behaviour,\n * not a rough edge: it is the ONLY shape in which the gate is not optional. A\n * permissive `string` fallback would make the check opt-in, and an opt-in gate\n * is the same as no gate — which is precisely the hole the retired\n * `config/secrets.ts` push-check used to paper over.\n *\n * THIS REPLACED A DECLARATION, and the direction matters. `config/secrets.ts`\n * asked the author to restate, in the repo, names the vault already held; the\n * deploy then compared the two lists. Here the stack is simply read and the\n * result is a type. There is no second list to drift.\n */\n\n/** The secret names this project's vault holds. EMPTY by default; filled by the\n * generated `palbase-stack.d.ts`. */\n// biome-ignore lint/suspicious/noEmptyInterface: augmentation target — filled by generated palbase-stack.d.ts.\nexport interface Secrets {}\n\n/** The flag keys this project's store defines. EMPTY by default; filled by the\n * generated `palbase-stack.d.ts`. */\n// biome-ignore lint/suspicious/noEmptyInterface: augmentation target — filled by generated palbase-stack.d.ts.\nexport interface Flags {}\n\n/**\n * One typed bucket: which renditions the stack declared for it.\n *\n * `variants` is a UNION of the declared names, so asking for one the bucket does\n * not have is a compile error rather than a 404 somebody finds in production.\n * The default `never` means a bucket with no variants accepts no variant name at\n * all, which is exactly right.\n *\n * THIS MOVED HERE FROM `db/env.ts` (2026-08-29). It lived there because\n * `config/storage.ts` fed it through `palbase-env.d.ts`, alongside the schema's\n * tables. Buckets do not come from the schema — they come from the STACK — so\n * they belong in the file generated off the stack. Two `Buckets` interfaces for\n * one concept is how `Storage.buckets.docs` and `@Upload({ bucket: \"docs\" })`\n * came to disagree about whether \"docs\" exists.\n */\nexport interface BucketTypes {\n  variants: string;\n}\n\n/** The buckets this project's storage carries, keyed by name. EMPTY by default;\n * filled by the generated `palbase-stack.d.ts`. Drives BOTH `Storage.buckets.*`\n * (through `EnvBuckets`) and `@Upload({ bucket })`. */\n// biome-ignore lint/suspicious/noEmptyInterface: augmentation target — filled by generated palbase-stack.d.ts.\nexport interface Buckets {}\n\n/** Every secret name the stack holds. */\nexport type PalbaseSecretName = keyof Secrets & string;\n\n/** Every flag key the stack defines. */\nexport type PalbaseFlagKey = keyof Flags & string;\n\n/** Every bucket the stack carries. */\nexport type PalbaseBucketName = keyof Buckets & string;\n"],"mappings":";;;;;;;;;;;;;;;;AAAA;AAAA;","names":[]}

package/dist/stack.d.cts

@@ -0,0 +1,76 @@
+/**
+ * `@palbase/backend/stack` — the controlled global augmentation target for the
+ * names the project's STACK holds.
+ *
+ * `Secrets.get(...)`, the Flags client's key parameters and `@Upload({ bucket })`
+ * take these unions, never a raw string, so a name the stack does not hold is a
+ * COMPILE error rather than a 500 in production — or, worse, a silent read of a
+ * secret nobody set.
+ *
+ * Three interfaces in ONE module because the three share a source and a refresh
+ * moment: they all come from the linked environment's stack, and any `palbase
+ * secret set` / `flags add` / `storage add` moves them together. `@palbase/
+ * backend/env` and `@palbase/backend/purchases` stay separate for the opposite
+ * reason — their sources are the schema and the catalog.
+ *
+ * All three are EMPTY by default; the generated `palbase-stack.d.ts` augments
+ * them with one member per name:
+ *
+ *   // palbase-stack.d.ts (generated — do not edit)
+ *   declare module "@palbase/backend/stack" {
+ *     interface Secrets { OPENAI_API_KEY: true }
+ *     interface Flags { newCheckout: true }
+ *     interface Buckets { avatars: true }
+ *   }
+ *
+ * A project that has not generated the file therefore has NO valid names, and
+ * every call fails to compile until it does. That is the intended behaviour,
+ * not a rough edge: it is the ONLY shape in which the gate is not optional. A
+ * permissive `string` fallback would make the check opt-in, and an opt-in gate
+ * is the same as no gate — which is precisely the hole the retired
+ * `config/secrets.ts` push-check used to paper over.
+ *
+ * THIS REPLACED A DECLARATION, and the direction matters. `config/secrets.ts`
+ * asked the author to restate, in the repo, names the vault already held; the
+ * deploy then compared the two lists. Here the stack is simply read and the
+ * result is a type. There is no second list to drift.
+ */
+/** The secret names this project's vault holds. EMPTY by default; filled by the
+ * generated `palbase-stack.d.ts`. */
+interface Secrets {
+}
+/** The flag keys this project's store defines. EMPTY by default; filled by the
+ * generated `palbase-stack.d.ts`. */
+interface Flags {
+}
+/**
+ * One typed bucket: which renditions the stack declared for it.
+ *
+ * `variants` is a UNION of the declared names, so asking for one the bucket does
+ * not have is a compile error rather than a 404 somebody finds in production.
+ * The default `never` means a bucket with no variants accepts no variant name at
+ * all, which is exactly right.
+ *
+ * THIS MOVED HERE FROM `db/env.ts` (2026-08-29). It lived there because
+ * `config/storage.ts` fed it through `palbase-env.d.ts`, alongside the schema's
+ * tables. Buckets do not come from the schema — they come from the STACK — so
+ * they belong in the file generated off the stack. Two `Buckets` interfaces for
+ * one concept is how `Storage.buckets.docs` and `@Upload({ bucket: "docs" })`
+ * came to disagree about whether "docs" exists.
+ */
+interface BucketTypes {
+    variants: string;
+}
+/** The buckets this project's storage carries, keyed by name. EMPTY by default;
+ * filled by the generated `palbase-stack.d.ts`. Drives BOTH `Storage.buckets.*`
+ * (through `EnvBuckets`) and `@Upload({ bucket })`. */
+interface Buckets {
+}
+/** Every secret name the stack holds. */
+type PalbaseSecretName = keyof Secrets & string;
+/** Every flag key the stack defines. */
+type PalbaseFlagKey = keyof Flags & string;
+/** Every bucket the stack carries. */
+type PalbaseBucketName = keyof Buckets & string;
+
+export type { BucketTypes, Buckets, Flags, PalbaseBucketName, PalbaseFlagKey, PalbaseSecretName, Secrets };

package/dist/stack.d.ts

@@ -0,0 +1,76 @@
+/**
+ * `@palbase/backend/stack` — the controlled global augmentation target for the
+ * names the project's STACK holds.
+ *
+ * `Secrets.get(...)`, the Flags client's key parameters and `@Upload({ bucket })`
+ * take these unions, never a raw string, so a name the stack does not hold is a
+ * COMPILE error rather than a 500 in production — or, worse, a silent read of a
+ * secret nobody set.
+ *
+ * Three interfaces in ONE module because the three share a source and a refresh
+ * moment: they all come from the linked environment's stack, and any `palbase
+ * secret set` / `flags add` / `storage add` moves them together. `@palbase/
+ * backend/env` and `@palbase/backend/purchases` stay separate for the opposite
+ * reason — their sources are the schema and the catalog.
+ *
+ * All three are EMPTY by default; the generated `palbase-stack.d.ts` augments
+ * them with one member per name:
+ *
+ *   // palbase-stack.d.ts (generated — do not edit)
+ *   declare module "@palbase/backend/stack" {
+ *     interface Secrets { OPENAI_API_KEY: true }
+ *     interface Flags { newCheckout: true }
+ *     interface Buckets { avatars: true }
+ *   }
+ *
+ * A project that has not generated the file therefore has NO valid names, and
+ * every call fails to compile until it does. That is the intended behaviour,
+ * not a rough edge: it is the ONLY shape in which the gate is not optional. A
+ * permissive `string` fallback would make the check opt-in, and an opt-in gate
+ * is the same as no gate — which is precisely the hole the retired
+ * `config/secrets.ts` push-check used to paper over.
+ *
+ * THIS REPLACED A DECLARATION, and the direction matters. `config/secrets.ts`
+ * asked the author to restate, in the repo, names the vault already held; the
+ * deploy then compared the two lists. Here the stack is simply read and the
+ * result is a type. There is no second list to drift.
+ */
+/** The secret names this project's vault holds. EMPTY by default; filled by the
+ * generated `palbase-stack.d.ts`. */
+interface Secrets {
+}
+/** The flag keys this project's store defines. EMPTY by default; filled by the
+ * generated `palbase-stack.d.ts`. */
+interface Flags {
+}
+/**
+ * One typed bucket: which renditions the stack declared for it.
+ *
+ * `variants` is a UNION of the declared names, so asking for one the bucket does
+ * not have is a compile error rather than a 404 somebody finds in production.
+ * The default `never` means a bucket with no variants accepts no variant name at
+ * all, which is exactly right.
+ *
+ * THIS MOVED HERE FROM `db/env.ts` (2026-08-29). It lived there because
+ * `config/storage.ts` fed it through `palbase-env.d.ts`, alongside the schema's
+ * tables. Buckets do not come from the schema — they come from the STACK — so
+ * they belong in the file generated off the stack. Two `Buckets` interfaces for
+ * one concept is how `Storage.buckets.docs` and `@Upload({ bucket: "docs" })`
+ * came to disagree about whether "docs" exists.
+ */
+interface BucketTypes {
+    variants: string;
+}
+/** The buckets this project's storage carries, keyed by name. EMPTY by default;
+ * filled by the generated `palbase-stack.d.ts`. Drives BOTH `Storage.buckets.*`
+ * (through `EnvBuckets`) and `@Upload({ bucket })`. */
+interface Buckets {
+}
+/** Every secret name the stack holds. */
+type PalbaseSecretName = keyof Secrets & string;
+/** Every flag key the stack defines. */
+type PalbaseFlagKey = keyof Flags & string;
+/** Every bucket the stack carries. */
+type PalbaseBucketName = keyof Buckets & string;
+
+export type { BucketTypes, Buckets, Flags, PalbaseBucketName, PalbaseFlagKey, PalbaseSecretName, Secrets };

package/dist/stack.js

@@ -0,0 +1 @@
+//# sourceMappingURL=stack.js.map

package/docs/README.md

@@ -24,8 +24,8 @@ db/schema.ts                        # config-as-code Postgres schema (tables, co
 ```
 
 The four folders above are the daily surface. These also exist (own docs, linked
-below): `resources/` (external connections — [resources.md](./resources.md)),
-`seeds/` (seed data), `jobs/` (background — [background.md](./background.md)),
+below): `resources/` (plain modules a controller imports — a client, a
+formatter, anything shared), `seeds/` (seed data), `jobs/` (background — [background.md](./background.md)),
 `webhooks/` + `hooks/` (events — [events.md](./events.md)), `middleware/`.
 
 ### The 7 rules (checklist)
@@ -203,9 +203,11 @@ generated client surface) changes; the verb/path do not affect it.
   secrets in its environment. There is no `.env` file: nothing writes one and
   nothing reads one, so the values live in one child process and are gone when it
   exits.
-- `config/secrets.ts` — `defineSecrets({ secrets: [secret("NAME")] })` declares
-  WHICH secrets the backend needs (never a value). `push` refuses the deploy when
-  a required one is missing from the target Environment, naming it.
+- Secrets are written to the stack (`palbase secret set NAME --stdin`) and read
+  with `Secrets.get(name)`. The NAME is typed: `palbase-stack.d.ts` is generated
+  from the stack, so a secret it does not hold cannot be spelled — a compile
+  error rather than a 500. There is no `config/secrets.ts`: it asked you to
+  restate names the vault already had, and the deploy compared the two lists.
 - `tsconfig.json` needs `"experimentalDecorators": true` (the scaffold sets it).
 
 ## Mental model
@@ -266,7 +268,6 @@ HTTP endpoints are **not** file-path routed. You author a class controller
 | Schema & typed DB | [schema.md](./schema.md) |
 | Migrations (additive vs type-change + drift-gate) | [migrations.md](./migrations.md) |
 | Services (Cache, Queue, Storage, …) | [services.md](./services.md) |
-| Resources (external connections) | [resources.md](./resources.md) |
 | Errors | [errors.md](./errors.md) |
 | Workers & Jobs | [background.md](./background.md) |
 | Hooks & Webhooks | [events.md](./events.md) |

package/docs/endpoints.md

@@ -86,7 +86,7 @@ query (RFC semantics), so a QUERY route carries its whole input there.
 | `@Body(schema)` | request body | `: T` (`z.infer<schema>`, same name) | requestBody |
 | `@QueryParams(schema)` | query params | `: T` | query parameters |
 | `@Param("id")` | one path param | `: string` | path parameter |
-| `@Headers(schema?)` | request headers | `Record<string,string>` (+ typed with schema) | header parameters |
+| `@Headers(schema?)` | request headers (lowercase keys); with a schema, the **parsed** value — declared keys only, matched case-insensitively, and a violating request is refused 400 | `Record<string,string>`, or `z.infer<schema>` | header parameters |
 | `@User()` | authenticated user | `: UserT` | — (from token) |
 | `@OptionalUser()` | user, possibly anon | `: UserT \| null` | — |
 | `@Client()` | parsed client info | `: ClientInfo` | — |