@vxil/feature-configs 0.7.1 → 0.9.0

package/dist/index.d.ts

@@ -3,11 +3,15 @@ export * from './hooks.js';
 export * from './readmodels.js';
 export * from './apiState.js';
 export * from './canonicalJson.js';
+export * from './publicAssets.js';
 export declare const RESERVED_CREDIT_TYPES: ReadonlySet<string>;
 /** A function binding's `retry.maxAttempts` ceiling, and the
- *  binding kinds that may carry `retry` — the platform-delivered event lanes
- *  (an http invoke returns its own status; a cron tick's retry would overlap
- *  the next tick). Read by the schema, the deploy clamp and the CLI. */
+ *  binding kinds that may carry `retry` — every lane the platform delivers
+ *  through jobs. Since 2026-10-03 (JT-9) that includes `cron` (a failed tick is
+ *  re-delivered on the ladder; pair it with `overlap: 'skip'` so a retrying
+ *  tick never runs beside the next one) and `http` (the ASYNC lane only — a
+ *  synchronous invoke always hands its caller the function's own status).
+ *  Read by the schema, the deploy clamp and the CLI. */
 export declare const FN_RETRY_MAX_ATTEMPTS = 5;
 export declare const FN_RETRY_BINDING_KINDS: ReadonlySet<string>;
 /** True when a credit_type is a vxil-COGS reserved type (grant/consume/config
@@ -378,6 +382,17 @@ export declare const FilesConfigSchema: import("@sinclair/typebox").TObject<{
         asyncOverJobs: import("@sinclair/typebox").TBoolean;
         boundingBoxes: import("@sinclair/typebox").TBoolean;
     }>>;
+    publicAssets: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TObject<{
+        enabled: import("@sinclair/typebox").TBoolean;
+        corsOrigins: import("@sinclair/typebox").TArray<import("@sinclair/typebox").TString>;
+        variants: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TRecord<import("@sinclair/typebox").TString, import("@sinclair/typebox").TObject<{
+            w: import("@sinclair/typebox").TInteger;
+            h: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TInteger>;
+            fit: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"scale-down">, import("@sinclair/typebox").TLiteral<"contain">, import("@sinclair/typebox").TLiteral<"cover">, import("@sinclair/typebox").TLiteral<"crop">, import("@sinclair/typebox").TLiteral<"pad">]>>;
+            fmt: import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"webp">, import("@sinclair/typebox").TLiteral<"avif">, import("@sinclair/typebox").TLiteral<"jpeg">, import("@sinclair/typebox").TLiteral<"png">]>;
+            q: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TInteger>;
+        }>>>;
+    }>>;
 }>;
 export type FilesConfig = Static<typeof FilesConfigSchema>;
 export declare const DeclaredWebhookSubscriptionSchema: import("@sinclair/typebox").TObject<{

package/dist/index.js

@@ -8,6 +8,7 @@ import { Value } from '@sinclair/typebox/value';
 import { validateHooksConfig } from './hooks.js';
 import { validateCdcConfig, validateReadModelsConfig } from './readmodels.js';
 import { isFnTriggerSubscriptionUrl } from './apiState.js';
+import { PublicAssetsConfigSchema, VARIANT_PRESET_NAME_PATTERN } from './publicAssets.js';
 // Re-export the CMS lifecycle-hook engine so feature workers (cms-v1, runtime
 // eval) and the control plane (config-time validation) share one definition.
 export * from './hooks.js';
@@ -21,6 +22,10 @@ export * from './apiState.js';
 // Key-order-insensitive JSON: the one declared-vs-stored manifest compare
 // (control-plane shallowDiff, CLI diffManifest).
 export * from './canonicalJson.js';
+// Public asset delivery (files.publicAssets): the publishable content-type
+// allowlist, the URL/key shape and the variant presets — shared by files-v1
+// (publish) and files-cdn (serve), which never import each other.
+export * from './publicAssets.js';
 // TypeBox validates `format:` only for registered formats — register the ones
 // our schemas use (pragmatic RFC-lite email check; providers do the real one).
 if (!FormatRegistry.Has('email')) {
@@ -37,11 +42,14 @@ if (!FormatRegistry.Has('email')) {
 // config-write refusal share ONE list. payments-v1/core.ts re-exports these.
 export const RESERVED_CREDIT_TYPES = new Set(['fn_cpu_ms']);
 /** A function binding's `retry.maxAttempts` ceiling, and the
- *  binding kinds that may carry `retry` — the platform-delivered event lanes
- *  (an http invoke returns its own status; a cron tick's retry would overlap
- *  the next tick). Read by the schema, the deploy clamp and the CLI. */
+ *  binding kinds that may carry `retry` — every lane the platform delivers
+ *  through jobs. Since 2026-10-03 (JT-9) that includes `cron` (a failed tick is
+ *  re-delivered on the ladder; pair it with `overlap: 'skip'` so a retrying
+ *  tick never runs beside the next one) and `http` (the ASYNC lane only — a
+ *  synchronous invoke always hands its caller the function's own status).
+ *  Read by the schema, the deploy clamp and the CLI. */
 export const FN_RETRY_MAX_ATTEMPTS = 5;
-export const FN_RETRY_BINDING_KINDS = new Set(['queue', 'webhook', 'cmsHook', 'authHook']);
+export const FN_RETRY_BINDING_KINDS = new Set(['queue', 'webhook', 'cmsHook', 'authHook', 'cron', 'http']);
 /** True when a credit_type is a vxil-COGS reserved type (grant/consume/config
  *  of which is restricted to internal platform machinery). */
 export function isReservedCreditType(creditType) {
@@ -336,7 +344,24 @@ export const JobsConfigSchema = Type.Object({
      * pathological target (e.g. an always-throwing function) can generate. */
     dlqDailyQuota: Type.Integer({ default: 0, minimum: 0, maximum: 100_000 }),
     schedules: Type.Object({ maxPerTenant: Type.Integer({ default: 50, minimum: 1, maximum: 1000 }) }, { default: {} }),
-    concurrency: Type.Object({ maxConcurrent: Type.Integer({ default: 10, minimum: 1, maximum: 100 }) }, { default: {} }),
+    concurrency: Type.Object(
+    /** Per-tenant cap on PLAIN runs (queue / cron / event deliveries,
+     * incl. platform-delivered function triggers) in flight at once; generation
+     * runs have their own `generation.maxConcurrent`. EFFECTIVE value =
+     * min(this, the tenant's fair share of the shared delivery consumer): the
+     * platform runs at most 75 queue-lane deliveries in flight for ALL tenants
+     * together, and one tenant may hold at most 25 of them (jobs-v1 core.ts
+     * TENANT_FAIR_SHARE). Values 26..100 still validate (existing configs keep
+     * working) but buy nothing past the share. Over-cap runs wait (deferred,
+     * never rejected). The schema `description` below is the tenant-facing
+     * copy of this (planner catalog, generated config schema) — keep both in
+     * step. */
+    {
+        maxConcurrent: Type.Integer({
+            default: 10, minimum: 1, maximum: 100,
+            description: 'Plain runs (queued jobs, cron fires, event deliveries, platform-delivered function triggers) delivered at once; generation runs have their own generation.maxConcurrent. Effective at most 25 (the per-project share of the shared delivery capacity): 26..100 validate but buy nothing more. Over-cap runs wait, never rejected.',
+        }),
+    }, { default: {} }),
     // Generation lifecycle knobs (guide ch. 6, jobs). The defaults and bounds are
     // declared ONCE, as GENERATION_DEFAULTS / GENERATION_BOUNDS below this schema
     // (2026-09-25): jobs-v1's resolveGenerationConfig imports them and clamps a
@@ -712,6 +737,11 @@ export const FilesConfigSchema = Type.Object({
         asyncOverJobs: Type.Boolean({ default: true }), // large/multi-page → jobs
         boundingBoxes: Type.Boolean({ default: false }),
     })),
+    // Public asset delivery (2026-10-03, guide ch. 6 files): publish
+    // an object to the cache-forever public host (POST /v1/files/{id}/publish).
+    // ONE optional bag: { enabled, corsOrigins, variants }. The published-bytes
+    // ceiling is a PLAN line (control-plane plans.ts), never a tenant knob.
+    publicAssets: Type.Optional(PublicAssetsConfigSchema),
 });
 // webhooks-out (wishlist feature): outbound event fan-out over the jobs delivery
 // engine. Subscriptions live in their own store (one writer per datum); config is just the capability gate + a cap.
@@ -1403,8 +1433,8 @@ export const FunctionsConfigSchema = Type.Object({
             collection: Type.Optional(Type.String()), // cmsHook: the CMS collection slug
             event: Type.Optional(Type.String()), // cmsHook: beforeCreate|beforeUpdate|beforeWrite · authHook: 'user.created'
             // (2026-09-25) the per-binding opt-in to re-delivery on
-            // queue / webhook / cmsHook / authHook (the cross-field rule
-            // rejects it on http / cron). Absent = the ACK-200 default. The
+            // queue / webhook / cmsHook / authHook, and since 2026-10-03 on
+            // cron and http (the async lane only). Absent = the ACK-200 default. The
             // receiver answers a failed attempt as an enveloped 503 (ladder)
             // and the last one as a terminal 409 (dead + job.dead_lettered);
             // effective attempts = min(maxAttempts, jobs.retry.defaultMaxAttempts).
@@ -1810,6 +1840,13 @@ export function validateDeclaredAiTemplates(templates) {
     });
     return errs;
 }
+function badVariantPresetNames(raw) {
+    const variants = raw?.publicAssets?.variants;
+    if (!variants || typeof variants !== 'object' || Array.isArray(variants))
+        return [];
+    const re = new RegExp(VARIANT_PRESET_NAME_PATTERN);
+    return Object.keys(variants).filter((k) => !re.test(k));
+}
 export function validateFeatureConfig(feature, raw) {
     const schema = FEATURE_SCHEMAS[feature];
     if (!schema) {
@@ -1818,6 +1855,18 @@ export function validateFeatureConfig(feature, raw) {
     if (countLeaves(schema) > CONFIG_FLAG_CAP) {
         return { ok: false, errors: [`schema for '${feature}' exceeds the ${CONFIG_FLAG_CAP}-flag cap`] };
     }
+    // files.publicAssets.variants is a pattern-keyed record: Value.Clean below
+    // would silently DROP a preset whose name is not URL-safe, and the tenant
+    // would wonder why `/v/My Thumb` 404s. Refuse it by name instead.
+    if (feature === 'files') {
+        const bad = badVariantPresetNames(raw);
+        if (bad.length > 0) {
+            return {
+                ok: false,
+                errors: bad.map((n) => `/publicAssets/variants/${n}: a preset name is lower-case letters, numbers, '-' or '_' (at most 32 characters, starting with a letter or number)`),
+            };
+        }
+    }
     // Apply defaults to a clone, then STRIP any property the schema does not
     // declare, then check. Value.Clean makes the validator TOTAL:
     // the schemas are open Type.Object()s, so without it Value.Check passes on —
@@ -2098,9 +2147,8 @@ export function validateFeatureConfig(feature, raw) {
                 if (b.overlap !== undefined && b.kind !== 'cron') {
                     errs.push(`/functions/${name}/bindings/${i}: 'overlap' applies to cron bindings only (not '${b.kind}')`);
                 }
-                // retry is an opt-in for the platform-delivered event lanes only —
-                // an http invoke returns its real status to its caller, and a cron
-                // tick's retry would overlap the next tick.
+                // retry is an opt-in for the platform-delivered lanes
+                // (FN_RETRY_BINDING_KINDS — every binding kind since JT-9)
                 if (b.retry !== undefined && !FN_RETRY_BINDING_KINDS.has(b.kind)) {
                     errs.push(`/functions/${name}/bindings/${i}: 'retry' applies to ${[...FN_RETRY_BINDING_KINDS].join(' | ')} bindings only (not '${b.kind}')`);
                 }
@@ -2194,15 +2242,15 @@ export const FEATURE_KEYS = [
 ];
 export const FEATURE_HINTS = {
     notifications: {
-        whenToUse: 'Sending email (transactional or broadcast) or in-app inbox messages to end-users: welcomes, receipts, reminders, alerts, digests.',
+        whenToUse: 'Sending email (transactional or broadcast) or in-app inbox messages to end-users: welcomes, receipts, reminders, alerts, digests. A send can be scheduled for a known time (send_at), so a one-off reminder needs no job or function.',
         signals: ['email', 'notify', 'alert', 'reminder', 'welcome', 'receipt', 'digest', 'inbox'],
         notFor: 'Live in-page updates (realtime) or activity timelines (activity-feed).',
         dependsOn: [],
     },
     jobs: {
-        whenToUse: 'Background work: scheduled/cron tasks, delayed sends, retries, queues, long-running or periodic processing, durable multi-step waits.',
-        signals: ['schedule', 'cron', 'daily', 'background', 'queue', 'later', 'recurring', 'batch'],
-        notFor: 'Simple request-response logic that completes inline.',
+        whenToUse: 'Background work: scheduled/cron tasks, delayed runs, retries, queues, runs that wait for an event, per-user serialisation (concurrency keys), debounced bursts, start deadlines, fan-in (a batch completion event), per-user schedules in their own time zone. Also the bookkeeping for LONG work that runs on the tenant\'s own runtime (renders, transcodes, model calls): a generation run holds reserved credits, a deadline, a signed completion callback and live progress mirrored onto a cms row.',
+        signals: ['schedule', 'cron', 'daily', 'background', 'queue', 'later', 'recurring', 'batch', 'render', 'transcode', 'progress', 'long-running'],
+        notFor: 'Simple request-response logic that completes inline; it is a queue with controls, not a workflow engine, and it never runs the heavy compute itself.',
         dependsOn: [],
     },
     auth: {
@@ -2218,8 +2266,8 @@ export const FEATURE_HINTS = {
         dependsOn: [],
     },
     files: {
-        whenToUse: 'End-users upload or download files/images/documents: avatars, attachments, photos, PDFs, media libraries.',
-        signals: ['upload', 'image', 'photo', 'file', 'attachment', 'document', 'avatar', 'media'],
+        whenToUse: 'End-users upload or download files/images/documents: avatars, attachments, photos, PDFs, media libraries. Media shown publicly (galleries, product photos, video, audio, fonts) is published to a public CDN URL, with named image variant presets such as thumbnails (publicAssets).',
+        signals: ['upload', 'image', 'photo', 'file', 'attachment', 'document', 'avatar', 'media', 'gallery', 'thumbnail', 'video', 'CDN'],
         notFor: 'Structured records (cms) or text content authored in-app.',
         dependsOn: [],
     },
@@ -2236,7 +2284,7 @@ export const FEATURE_HINTS = {
         dependsOn: [],
     },
     cms: {
-        whenToUse: 'The data spine: typed record collections with fields, relations, owner-scoping, draft/publish, and optional keyless public reads. Most apps are, underneath, cms collections.',
+        whenToUse: 'The data spine: typed record collections with fields, relations, owner-scoping, draft/publish, indexed filters, and optional keyless public reads. Most apps are, underneath, cms collections.',
         signals: ['store', 'list', 'catalog', 'posts', 'products', 'records', 'items', 'content', 'blog', 'tasks', 'listings'],
         notFor: 'End-user identity (auth) or file bytes (files).',
         dependsOn: [],
@@ -2298,7 +2346,7 @@ export const FEATURE_HINTS = {
     functions: {
         whenToUse: 'ONLY for truly-unique server logic no feature or cms rule can express: bespoke sagas, custom integrations over the egress guard, computed endpoints. Prefer features/cms first; functions are the escape hatch.',
         signals: ['custom logic', 'custom backend', 'integration with', 'workflow', 'saga'],
-        notFor: 'Anything a shipped feature or a cms lifecycle hook already covers.',
+        notFor: 'Anything a shipped feature or a cms lifecycle hook already covers, and heavy or long compute (renders, ffmpeg, ML) — that runs on the tenant\'s own runtime, tracked by a jobs generation run.',
         dependsOn: [],
     },
     copilot: {

package/dist/publicAssets.d.ts

@@ -0,0 +1,73 @@
+import { type Static } from '@sinclair/typebox';
+/** extension → the exact Content-Type served for it. */
+export declare const PUBLIC_ASSET_TYPES: Readonly<Record<string, string>>;
+/** The extension a stored content type publishes under, or null when the type
+ *  may not be published (html, svg, pdf, zip, octet-stream, …). */
+export declare function publicExtForContentType(contentType: string | null | undefined): string | null;
+/** Raster image extensions a variant preset may transform. */
+export declare const VARIANT_SOURCE_EXTS: ReadonlySet<string>;
+/** Video/audio types served `inline` (playable) by shared links and the public
+ *  host — media formats a browser plays in a player, never as a document. */
+export declare const INLINE_MEDIA_TYPES: ReadonlySet<string>;
+/** The public-asset URL path shape: `/<tenant_id>/<sha256>.<ext>` with an
+ *  optional `/v/<preset>` variant suffix. The tenant is bound from THIS path
+ *  (never a Host header). */
+export declare const PUBLIC_ASSET_PATH_RE: RegExp;
+/** The object key in the public bucket: `<tenant_id>/<sha256>.<ext>` —
+ *  tenant-prefixed (no cross-tenant dedupe, so no hash-existence oracle across
+ *  tenants) and content-addressed (immutable: a URL never changes meaning). */
+export declare function publicAssetKey(tenantId: string, sha256: string, ext: string): string;
+/** Most variant presets one tenant may declare (the schema bound; the plan
+ *  ceiling in control-plane plans.ts may be lower). */
+export declare const MAX_VARIANT_PRESETS = 8;
+/** Most CORS origins one tenant may declare. */
+export declare const MAX_CORS_ORIGINS = 20;
+/** Most object ids one bulk publish accepts (the batch download-urls bound). */
+export declare const MAX_BULK_PUBLISH = 100;
+/** Largest object that may be published (bytes): 512 MiB — the largest
+ *  object the public host's edge cache holds, so every published object
+ *  (and every Range of it) is served from the cache after its first read.
+ *  Bigger media belongs on a streaming/transcoding vendor, not a
+ *  cache-forever host. */
+export declare const MAX_PUBLISH_OBJECT_BYTES: number;
+/** Most bytes ONE bulk publish call may stream (hashing an object without a
+ *  recorded checksum reads it once, copying reads it again). Ids past the
+ *  budget land in `errors[]` as `batch_budget_exceeded` — publish them in a
+ *  further call. */
+export declare const MAX_BULK_PUBLISH_BYTES: number;
+/** Largest source image a variant preset transforms (bytes). */
+export declare const MAX_VARIANT_SOURCE_BYTES: number;
+/** A CORS origin: `*`, an https origin, or a localhost http origin (dev). No
+ *  path, no trailing slash, no wildcard sub-domains. */
+export declare const CORS_ORIGIN_PATTERN = "^(\\*|https://[a-z0-9]([a-z0-9-]*[a-z0-9])?(\\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)*(:[0-9]{1,5})?|http://(localhost|127\\.0\\.0\\.1)(:[0-9]{1,5})?)$";
+/** A preset name: lower-case, URL-safe, ≤ 32 chars (it is a path segment). */
+export declare const VARIANT_PRESET_NAME_PATTERN = "^[a-z0-9][a-z0-9_-]{0,31}$";
+export declare const VariantPresetSchema: import("@sinclair/typebox").TObject<{
+    w: import("@sinclair/typebox").TInteger;
+    h: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TInteger>;
+    fit: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"scale-down">, import("@sinclair/typebox").TLiteral<"contain">, import("@sinclair/typebox").TLiteral<"cover">, import("@sinclair/typebox").TLiteral<"crop">, import("@sinclair/typebox").TLiteral<"pad">]>>;
+    fmt: import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"webp">, import("@sinclair/typebox").TLiteral<"avif">, import("@sinclair/typebox").TLiteral<"jpeg">, import("@sinclair/typebox").TLiteral<"png">]>;
+    q: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TInteger>;
+}>;
+export type VariantPreset = Static<typeof VariantPresetSchema>;
+/** `files.publicAssets` — ONE optional bag (one leaf against the 15-leaf cap).
+ *  `enabled` is the tenant's own kill switch: false ⇒ publish refuses and the
+ *  public host answers 404 for every one of the tenant's assets. */
+export declare const PublicAssetsConfigSchema: import("@sinclair/typebox").TObject<{
+    enabled: import("@sinclair/typebox").TBoolean;
+    corsOrigins: import("@sinclair/typebox").TArray<import("@sinclair/typebox").TString>;
+    variants: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TRecord<import("@sinclair/typebox").TString, import("@sinclair/typebox").TObject<{
+        w: import("@sinclair/typebox").TInteger;
+        h: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TInteger>;
+        fit: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"scale-down">, import("@sinclair/typebox").TLiteral<"contain">, import("@sinclair/typebox").TLiteral<"cover">, import("@sinclair/typebox").TLiteral<"crop">, import("@sinclair/typebox").TLiteral<"pad">]>>;
+        fmt: import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"webp">, import("@sinclair/typebox").TLiteral<"avif">, import("@sinclair/typebox").TLiteral<"jpeg">, import("@sinclair/typebox").TLiteral<"png">]>;
+        q: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TInteger>;
+    }>>>;
+}>;
+export type PublicAssetsConfig = Static<typeof PublicAssetsConfigSchema>;
+/** The MIME type a variant `fmt` outputs. */
+export declare function variantOutputType(fmt: VariantPreset['fmt']): 'image/webp' | 'image/avif' | 'image/jpeg' | 'image/png';
+/** A stable short fingerprint of a preset definition — part of the variant
+ *  cache key, so editing a preset never serves the old rendition. FNV-1a over
+ *  the canonical field order (no crypto needed: it only has to change). */
+export declare function presetFingerprint(p: VariantPreset): string;

package/dist/publicAssets.js

@@ -0,0 +1,130 @@
+// files PUBLIC ASSET DELIVERY (2026-10-03) — the one definition of
+// what may be published to the public asset host, shared by the publish path
+// (files-v1), the serving Worker (files-cdn), the config schema below and the
+// docs gates. A feature worker never imports another worker's code, so the
+// constants that BOTH sides must agree on live in this shared package.
+//
+// THE CONTENT-TYPE ALLOWLIST is the security boundary of a public, cookie-less,
+// cache-forever host: only types a browser never executes as a document.
+// `text/html` is absent by construction, and `image/svg+xml` is REFUSED (an SVG
+// is a document that can run script; serving it under a CSP sandbox was the
+// alternative, refusing is the smaller surface). The serving Worker derives the
+// served Content-Type from the URL's extension through THIS map — never from
+// stored metadata — and adds `X-Content-Type-Options: nosniff`, so bytes that
+// lie about their type are still never rendered as HTML.
+import { Type } from '@sinclair/typebox';
+/** extension → the exact Content-Type served for it. */
+export const PUBLIC_ASSET_TYPES = {
+    png: 'image/png',
+    jpg: 'image/jpeg',
+    webp: 'image/webp',
+    avif: 'image/avif',
+    gif: 'image/gif',
+    mp4: 'video/mp4',
+    webm: 'video/webm',
+    mp3: 'audio/mpeg',
+    m4a: 'audio/mp4',
+    ogg: 'audio/ogg',
+    woff2: 'font/woff2',
+    woff: 'font/woff',
+    json: 'application/json',
+};
+/** Stored content types (lower-cased, parameters stripped) accepted at publish
+ *  → the extension they are published under. The canonical type of each
+ *  extension plus a few common aliases uploaders send. */
+const TYPE_TO_EXT = {
+    ...Object.fromEntries(Object.entries(PUBLIC_ASSET_TYPES).map(([ext, ct]) => [ct, ext])),
+    'image/jpg': 'jpg',
+    'image/pjpeg': 'jpg',
+    'audio/mp3': 'mp3',
+    'audio/x-m4a': 'm4a',
+    'audio/m4a': 'm4a',
+    'application/font-woff': 'woff',
+    'application/font-woff2': 'woff2',
+};
+/** The extension a stored content type publishes under, or null when the type
+ *  may not be published (html, svg, pdf, zip, octet-stream, …). */
+export function publicExtForContentType(contentType) {
+    if (!contentType)
+        return null;
+    const base = contentType.split(';')[0].trim().toLowerCase();
+    return TYPE_TO_EXT[base] ?? null;
+}
+/** Raster image extensions a variant preset may transform. */
+export const VARIANT_SOURCE_EXTS = new Set(['png', 'jpg', 'webp', 'avif', 'gif']);
+/** Video/audio types served `inline` (playable) by shared links and the public
+ *  host — media formats a browser plays in a player, never as a document. */
+export const INLINE_MEDIA_TYPES = new Set([
+    'video/mp4', 'video/webm', 'audio/mpeg', 'audio/mp4', 'audio/ogg',
+]);
+/** The public-asset URL path shape: `/<tenant_id>/<sha256>.<ext>` with an
+ *  optional `/v/<preset>` variant suffix. The tenant is bound from THIS path
+ *  (never a Host header). */
+export const PUBLIC_ASSET_PATH_RE = /^\/([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})\/([0-9a-f]{64})\.([a-z0-9]{2,5})(?:\/v\/([a-z0-9][a-z0-9_-]{0,31}))?$/;
+/** The object key in the public bucket: `<tenant_id>/<sha256>.<ext>` —
+ *  tenant-prefixed (no cross-tenant dedupe, so no hash-existence oracle across
+ *  tenants) and content-addressed (immutable: a URL never changes meaning). */
+export function publicAssetKey(tenantId, sha256, ext) {
+    return `${tenantId}/${sha256}.${ext}`;
+}
+/** Most variant presets one tenant may declare (the schema bound; the plan
+ *  ceiling in control-plane plans.ts may be lower). */
+export const MAX_VARIANT_PRESETS = 8;
+/** Most CORS origins one tenant may declare. */
+export const MAX_CORS_ORIGINS = 20;
+/** Most object ids one bulk publish accepts (the batch download-urls bound). */
+export const MAX_BULK_PUBLISH = 100;
+/** Largest object that may be published (bytes): 512 MiB — the largest
+ *  object the public host's edge cache holds, so every published object
+ *  (and every Range of it) is served from the cache after its first read.
+ *  Bigger media belongs on a streaming/transcoding vendor, not a
+ *  cache-forever host. */
+export const MAX_PUBLISH_OBJECT_BYTES = 512 * 1024 * 1024;
+/** Most bytes ONE bulk publish call may stream (hashing an object without a
+ *  recorded checksum reads it once, copying reads it again). Ids past the
+ *  budget land in `errors[]` as `batch_budget_exceeded` — publish them in a
+ *  further call. */
+export const MAX_BULK_PUBLISH_BYTES = 2 * 1024 * 1024 * 1024;
+/** Largest source image a variant preset transforms (bytes). */
+export const MAX_VARIANT_SOURCE_BYTES = 25 * 1024 * 1024;
+/** A CORS origin: `*`, an https origin, or a localhost http origin (dev). No
+ *  path, no trailing slash, no wildcard sub-domains. */
+export const CORS_ORIGIN_PATTERN = '^(\\*|https://[a-z0-9]([a-z0-9-]*[a-z0-9])?(\\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)*(:[0-9]{1,5})?|http://(localhost|127\\.0\\.0\\.1)(:[0-9]{1,5})?)$';
+/** A preset name: lower-case, URL-safe, ≤ 32 chars (it is a path segment). */
+export const VARIANT_PRESET_NAME_PATTERN = '^[a-z0-9][a-z0-9_-]{0,31}$';
+export const VariantPresetSchema = Type.Object({
+    w: Type.Integer({ minimum: 1, maximum: 4096 }),
+    h: Type.Optional(Type.Integer({ minimum: 1, maximum: 4096 })),
+    fit: Type.Optional(Type.Union([
+        Type.Literal('scale-down'), Type.Literal('contain'), Type.Literal('cover'),
+        Type.Literal('crop'), Type.Literal('pad'),
+    ])),
+    fmt: Type.Union([Type.Literal('webp'), Type.Literal('avif'), Type.Literal('jpeg'), Type.Literal('png')]),
+    q: Type.Optional(Type.Integer({ minimum: 1, maximum: 100 })),
+});
+/** `files.publicAssets` — ONE optional bag (one leaf against the 15-leaf cap).
+ *  `enabled` is the tenant's own kill switch: false ⇒ publish refuses and the
+ *  public host answers 404 for every one of the tenant's assets. */
+export const PublicAssetsConfigSchema = Type.Object({
+    enabled: Type.Boolean({ default: false }),
+    corsOrigins: Type.Array(Type.String({ pattern: CORS_ORIGIN_PATTERN, maxLength: 253 }), {
+        default: [], maxItems: MAX_CORS_ORIGINS,
+    }),
+    variants: Type.Optional(Type.Record(Type.String({ pattern: VARIANT_PRESET_NAME_PATTERN }), VariantPresetSchema, { maxProperties: MAX_VARIANT_PRESETS })),
+});
+/** The MIME type a variant `fmt` outputs. */
+export function variantOutputType(fmt) {
+    return `image/${fmt}`;
+}
+/** A stable short fingerprint of a preset definition — part of the variant
+ *  cache key, so editing a preset never serves the old rendition. FNV-1a over
+ *  the canonical field order (no crypto needed: it only has to change). */
+export function presetFingerprint(p) {
+    const s = `${p.w}|${p.h ?? ''}|${p.fit ?? ''}|${p.fmt}|${p.q ?? ''}`;
+    let h = 0x811c9dc5;
+    for (let i = 0; i < s.length; i++) {
+        h ^= s.charCodeAt(i);
+        h = Math.imul(h, 0x01000193) >>> 0;
+    }
+    return h.toString(16).padStart(8, '0');
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vxil/feature-configs",
-  "version": "0.7.1",
+  "version": "0.9.0",
   "description": "The per-feature configuration schemas and validators behind vxil.config.ts (published for @vxil/cli and @vxil/config).",
   "license": "MIT",
   "homepage": "https://vxil.com",

package/src/index.ts

@@ -8,6 +8,7 @@ import { Value } from '@sinclair/typebox/value';
 import { validateHooksConfig, type HookDef } from './hooks.js';
 import { validateCdcConfig, validateReadModelsConfig } from './readmodels.js';
 import { isFnTriggerSubscriptionUrl } from './apiState.js';
+import { PublicAssetsConfigSchema, VARIANT_PRESET_NAME_PATTERN } from './publicAssets.js';
 
 // Re-export the CMS lifecycle-hook engine so feature workers (cms-v1, runtime
 // eval) and the control plane (config-time validation) share one definition.
@@ -22,6 +23,10 @@ export * from './apiState.js';
 // Key-order-insensitive JSON: the one declared-vs-stored manifest compare
 // (control-plane shallowDiff, CLI diffManifest).
 export * from './canonicalJson.js';
+// Public asset delivery (files.publicAssets): the publishable content-type
+// allowlist, the URL/key shape and the variant presets — shared by files-v1
+// (publish) and files-cdn (serve), which never import each other.
+export * from './publicAssets.js';
 
 // TypeBox validates `format:` only for registered formats — register the ones
 // our schemas use (pragmatic RFC-lite email check; providers do the real one).
@@ -41,11 +46,14 @@ if (!FormatRegistry.Has('email')) {
 export const RESERVED_CREDIT_TYPES: ReadonlySet<string> = new Set<string>(['fn_cpu_ms']);
 
 /** A function binding's `retry.maxAttempts` ceiling, and the
- *  binding kinds that may carry `retry` — the platform-delivered event lanes
- *  (an http invoke returns its own status; a cron tick's retry would overlap
- *  the next tick). Read by the schema, the deploy clamp and the CLI. */
+ *  binding kinds that may carry `retry` — every lane the platform delivers
+ *  through jobs. Since 2026-10-03 (JT-9) that includes `cron` (a failed tick is
+ *  re-delivered on the ladder; pair it with `overlap: 'skip'` so a retrying
+ *  tick never runs beside the next one) and `http` (the ASYNC lane only — a
+ *  synchronous invoke always hands its caller the function's own status).
+ *  Read by the schema, the deploy clamp and the CLI. */
 export const FN_RETRY_MAX_ATTEMPTS = 5;
-export const FN_RETRY_BINDING_KINDS: ReadonlySet<string> = new Set(['queue', 'webhook', 'cmsHook', 'authHook']);
+export const FN_RETRY_BINDING_KINDS: ReadonlySet<string> = new Set(['queue', 'webhook', 'cmsHook', 'authHook', 'cron', 'http']);
 
 /** True when a credit_type is a vxil-COGS reserved type (grant/consume/config
  *  of which is restricted to internal platform machinery). */
@@ -394,7 +402,23 @@ export const JobsConfigSchema = Type.Object({
     { default: {} },
   ),
   concurrency: Type.Object(
-    { maxConcurrent: Type.Integer({ default: 10, minimum: 1, maximum: 100 }) },
+    /** Per-tenant cap on PLAIN runs (queue / cron / event deliveries,
+     * incl. platform-delivered function triggers) in flight at once; generation
+     * runs have their own `generation.maxConcurrent`. EFFECTIVE value =
+     * min(this, the tenant's fair share of the shared delivery consumer): the
+     * platform runs at most 75 queue-lane deliveries in flight for ALL tenants
+     * together, and one tenant may hold at most 25 of them (jobs-v1 core.ts
+     * TENANT_FAIR_SHARE). Values 26..100 still validate (existing configs keep
+     * working) but buy nothing past the share. Over-cap runs wait (deferred,
+     * never rejected). The schema `description` below is the tenant-facing
+     * copy of this (planner catalog, generated config schema) — keep both in
+     * step. */
+    {
+      maxConcurrent: Type.Integer({
+        default: 10, minimum: 1, maximum: 100,
+        description: 'Plain runs (queued jobs, cron fires, event deliveries, platform-delivered function triggers) delivered at once; generation runs have their own generation.maxConcurrent. Effective at most 25 (the per-project share of the shared delivery capacity): 26..100 validate but buy nothing more. Over-cap runs wait, never rejected.',
+      }),
+    },
     { default: {} },
   ),
   // Generation lifecycle knobs (guide ch. 6, jobs). The defaults and bounds are
@@ -844,8 +868,13 @@ export const FilesConfigSchema = Type.Object({
     asyncOverJobs: Type.Boolean({ default: true }), // large/multi-page → jobs
     boundingBoxes: Type.Boolean({ default: false }),
   })),
+  // Public asset delivery (2026-10-03, guide ch. 6 files): publish
+  // an object to the cache-forever public host (POST /v1/files/{id}/publish).
+  // ONE optional bag: { enabled, corsOrigins, variants }. The published-bytes
+  // ceiling is a PLAN line (control-plane plans.ts), never a tenant knob.
+  publicAssets: Type.Optional(PublicAssetsConfigSchema),
 });
-// Leaves: 9 + ttl(1, optional bag) + extractText(1, optional bag) = 11. Cap = 15.
+// Leaves: 9 + ttl(1) + extractText(1) + publicAssets(1, optional bags) = 12. Cap = 15.
 // (was 14 — 2026-09-11 deleted the inert bucketRef leaf and the inert contentScan bag.)
 
 export type FilesConfig = Static<typeof FilesConfigSchema>;
@@ -1744,8 +1773,8 @@ export const FunctionsConfigSchema = Type.Object({
               collection: Type.Optional(Type.String()), // cmsHook: the CMS collection slug
               event: Type.Optional(Type.String()), // cmsHook: beforeCreate|beforeUpdate|beforeWrite · authHook: 'user.created'
               // (2026-09-25) the per-binding opt-in to re-delivery on
-              // queue / webhook / cmsHook / authHook (the cross-field rule
-              // rejects it on http / cron). Absent = the ACK-200 default. The
+              // queue / webhook / cmsHook / authHook, and since 2026-10-03 on
+              // cron and http (the async lane only). Absent = the ACK-200 default. The
               // receiver answers a failed attempt as an enveloped 503 (ladder)
               // and the last one as a terminal 409 (dead + job.dead_lettered);
               // effective attempts = min(maxAttempts, jobs.retry.defaultMaxAttempts).
@@ -2210,6 +2239,13 @@ export function validateDeclaredAiTemplates(templates: readonly DeclaredAiTempla
   return errs;
 }
 
+function badVariantPresetNames(raw: unknown): string[] {
+  const variants = (raw as { publicAssets?: { variants?: unknown } } | null)?.publicAssets?.variants;
+  if (!variants || typeof variants !== 'object' || Array.isArray(variants)) return [];
+  const re = new RegExp(VARIANT_PRESET_NAME_PATTERN);
+  return Object.keys(variants).filter((k) => !re.test(k));
+}
+
 export function validateFeatureConfig(feature: string, raw: unknown): ConfigValidation {
   const schema = FEATURE_SCHEMAS[feature];
   if (!schema) {
@@ -2218,6 +2254,18 @@ export function validateFeatureConfig(feature: string, raw: unknown): ConfigVali
   if (countLeaves(schema) > CONFIG_FLAG_CAP) {
     return { ok: false, errors: [`schema for '${feature}' exceeds the ${CONFIG_FLAG_CAP}-flag cap`] };
   }
+  // files.publicAssets.variants is a pattern-keyed record: Value.Clean below
+  // would silently DROP a preset whose name is not URL-safe, and the tenant
+  // would wonder why `/v/My Thumb` 404s. Refuse it by name instead.
+  if (feature === 'files') {
+    const bad = badVariantPresetNames(raw);
+    if (bad.length > 0) {
+      return {
+        ok: false,
+        errors: bad.map((n) => `/publicAssets/variants/${n}: a preset name is lower-case letters, numbers, '-' or '_' (at most 32 characters, starting with a letter or number)`),
+      };
+    }
+  }
   // Apply defaults to a clone, then STRIP any property the schema does not
   // declare, then check. Value.Clean makes the validator TOTAL:
   // the schemas are open Type.Object()s, so without it Value.Check passes on —
@@ -2538,9 +2586,8 @@ export function validateFeatureConfig(feature: string, raw: unknown): ConfigVali
         if (b.overlap !== undefined && b.kind !== 'cron') {
           errs.push(`/functions/${name}/bindings/${i}: 'overlap' applies to cron bindings only (not '${b.kind}')`);
         }
-        // retry is an opt-in for the platform-delivered event lanes only —
-        // an http invoke returns its real status to its caller, and a cron
-        // tick's retry would overlap the next tick.
+        // retry is an opt-in for the platform-delivered lanes
+        // (FN_RETRY_BINDING_KINDS — every binding kind since JT-9)
         if (b.retry !== undefined && !FN_RETRY_BINDING_KINDS.has(b.kind)) {
           errs.push(`/functions/${name}/bindings/${i}: 'retry' applies to ${[...FN_RETRY_BINDING_KINDS].join(' | ')} bindings only (not '${b.kind}')`);
         }
@@ -2654,15 +2701,15 @@ export interface PlannerHint {
 
 export const FEATURE_HINTS: Record<FeatureKey, PlannerHint> = {
   notifications: {
-    whenToUse: 'Sending email (transactional or broadcast) or in-app inbox messages to end-users: welcomes, receipts, reminders, alerts, digests.',
+    whenToUse: 'Sending email (transactional or broadcast) or in-app inbox messages to end-users: welcomes, receipts, reminders, alerts, digests. A send can be scheduled for a known time (send_at), so a one-off reminder needs no job or function.',
     signals: ['email', 'notify', 'alert', 'reminder', 'welcome', 'receipt', 'digest', 'inbox'],
     notFor: 'Live in-page updates (realtime) or activity timelines (activity-feed).',
     dependsOn: [],
   },
   jobs: {
-    whenToUse: 'Background work: scheduled/cron tasks, delayed sends, retries, queues, long-running or periodic processing, durable multi-step waits.',
-    signals: ['schedule', 'cron', 'daily', 'background', 'queue', 'later', 'recurring', 'batch'],
-    notFor: 'Simple request-response logic that completes inline.',
+    whenToUse: 'Background work: scheduled/cron tasks, delayed runs, retries, queues, runs that wait for an event, per-user serialisation (concurrency keys), debounced bursts, start deadlines, fan-in (a batch completion event), per-user schedules in their own time zone. Also the bookkeeping for LONG work that runs on the tenant\'s own runtime (renders, transcodes, model calls): a generation run holds reserved credits, a deadline, a signed completion callback and live progress mirrored onto a cms row.',
+    signals: ['schedule', 'cron', 'daily', 'background', 'queue', 'later', 'recurring', 'batch', 'render', 'transcode', 'progress', 'long-running'],
+    notFor: 'Simple request-response logic that completes inline; it is a queue with controls, not a workflow engine, and it never runs the heavy compute itself.',
     dependsOn: [],
   },
   auth: {
@@ -2678,8 +2725,8 @@ export const FEATURE_HINTS: Record<FeatureKey, PlannerHint> = {
     dependsOn: [],
   },
   files: {
-    whenToUse: 'End-users upload or download files/images/documents: avatars, attachments, photos, PDFs, media libraries.',
-    signals: ['upload', 'image', 'photo', 'file', 'attachment', 'document', 'avatar', 'media'],
+    whenToUse: 'End-users upload or download files/images/documents: avatars, attachments, photos, PDFs, media libraries. Media shown publicly (galleries, product photos, video, audio, fonts) is published to a public CDN URL, with named image variant presets such as thumbnails (publicAssets).',
+    signals: ['upload', 'image', 'photo', 'file', 'attachment', 'document', 'avatar', 'media', 'gallery', 'thumbnail', 'video', 'CDN'],
     notFor: 'Structured records (cms) or text content authored in-app.',
     dependsOn: [],
   },
@@ -2696,7 +2743,7 @@ export const FEATURE_HINTS: Record<FeatureKey, PlannerHint> = {
     dependsOn: [],
   },
   cms: {
-    whenToUse: 'The data spine: typed record collections with fields, relations, owner-scoping, draft/publish, and optional keyless public reads. Most apps are, underneath, cms collections.',
+    whenToUse: 'The data spine: typed record collections with fields, relations, owner-scoping, draft/publish, indexed filters, and optional keyless public reads. Most apps are, underneath, cms collections.',
     signals: ['store', 'list', 'catalog', 'posts', 'products', 'records', 'items', 'content', 'blog', 'tasks', 'listings'],
     notFor: 'End-user identity (auth) or file bytes (files).',
     dependsOn: [],
@@ -2758,7 +2805,7 @@ export const FEATURE_HINTS: Record<FeatureKey, PlannerHint> = {
   functions: {
     whenToUse: 'ONLY for truly-unique server logic no feature or cms rule can express: bespoke sagas, custom integrations over the egress guard, computed endpoints. Prefer features/cms first; functions are the escape hatch.',
     signals: ['custom logic', 'custom backend', 'integration with', 'workflow', 'saga'],
-    notFor: 'Anything a shipped feature or a cms lifecycle hook already covers.',
+    notFor: 'Anything a shipped feature or a cms lifecycle hook already covers, and heavy or long compute (renders, ffmpeg, ML) — that runs on the tenant\'s own runtime, tracked by a jobs generation run.',
     dependsOn: [],
   },
   copilot: {

package/src/publicAssets.ts

@@ -0,0 +1,151 @@
+// files PUBLIC ASSET DELIVERY (2026-10-03) — the one definition of
+// what may be published to the public asset host, shared by the publish path
+// (files-v1), the serving Worker (files-cdn), the config schema below and the
+// docs gates. A feature worker never imports another worker's code, so the
+// constants that BOTH sides must agree on live in this shared package.
+//
+// THE CONTENT-TYPE ALLOWLIST is the security boundary of a public, cookie-less,
+// cache-forever host: only types a browser never executes as a document.
+// `text/html` is absent by construction, and `image/svg+xml` is REFUSED (an SVG
+// is a document that can run script; serving it under a CSP sandbox was the
+// alternative, refusing is the smaller surface). The serving Worker derives the
+// served Content-Type from the URL's extension through THIS map — never from
+// stored metadata — and adds `X-Content-Type-Options: nosniff`, so bytes that
+// lie about their type are still never rendered as HTML.
+import { Type, type Static } from '@sinclair/typebox';
+
+/** extension → the exact Content-Type served for it. */
+export const PUBLIC_ASSET_TYPES: Readonly<Record<string, string>> = {
+  png: 'image/png',
+  jpg: 'image/jpeg',
+  webp: 'image/webp',
+  avif: 'image/avif',
+  gif: 'image/gif',
+  mp4: 'video/mp4',
+  webm: 'video/webm',
+  mp3: 'audio/mpeg',
+  m4a: 'audio/mp4',
+  ogg: 'audio/ogg',
+  woff2: 'font/woff2',
+  woff: 'font/woff',
+  json: 'application/json',
+};
+
+/** Stored content types (lower-cased, parameters stripped) accepted at publish
+ *  → the extension they are published under. The canonical type of each
+ *  extension plus a few common aliases uploaders send. */
+const TYPE_TO_EXT: Readonly<Record<string, string>> = {
+  ...Object.fromEntries(Object.entries(PUBLIC_ASSET_TYPES).map(([ext, ct]) => [ct, ext])),
+  'image/jpg': 'jpg',
+  'image/pjpeg': 'jpg',
+  'audio/mp3': 'mp3',
+  'audio/x-m4a': 'm4a',
+  'audio/m4a': 'm4a',
+  'application/font-woff': 'woff',
+  'application/font-woff2': 'woff2',
+};
+
+/** The extension a stored content type publishes under, or null when the type
+ *  may not be published (html, svg, pdf, zip, octet-stream, …). */
+export function publicExtForContentType(contentType: string | null | undefined): string | null {
+  if (!contentType) return null;
+  const base = contentType.split(';')[0]!.trim().toLowerCase();
+  return TYPE_TO_EXT[base] ?? null;
+}
+
+/** Raster image extensions a variant preset may transform. */
+export const VARIANT_SOURCE_EXTS: ReadonlySet<string> = new Set(['png', 'jpg', 'webp', 'avif', 'gif']);
+
+/** Video/audio types served `inline` (playable) by shared links and the public
+ *  host — media formats a browser plays in a player, never as a document. */
+export const INLINE_MEDIA_TYPES: ReadonlySet<string> = new Set([
+  'video/mp4', 'video/webm', 'audio/mpeg', 'audio/mp4', 'audio/ogg',
+]);
+
+/** The public-asset URL path shape: `/<tenant_id>/<sha256>.<ext>` with an
+ *  optional `/v/<preset>` variant suffix. The tenant is bound from THIS path
+ *  (never a Host header). */
+export const PUBLIC_ASSET_PATH_RE =
+  /^\/([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})\/([0-9a-f]{64})\.([a-z0-9]{2,5})(?:\/v\/([a-z0-9][a-z0-9_-]{0,31}))?$/;
+
+/** The object key in the public bucket: `<tenant_id>/<sha256>.<ext>` —
+ *  tenant-prefixed (no cross-tenant dedupe, so no hash-existence oracle across
+ *  tenants) and content-addressed (immutable: a URL never changes meaning). */
+export function publicAssetKey(tenantId: string, sha256: string, ext: string): string {
+  return `${tenantId}/${sha256}.${ext}`;
+}
+
+/** Most variant presets one tenant may declare (the schema bound; the plan
+ *  ceiling in control-plane plans.ts may be lower). */
+export const MAX_VARIANT_PRESETS = 8;
+/** Most CORS origins one tenant may declare. */
+export const MAX_CORS_ORIGINS = 20;
+/** Most object ids one bulk publish accepts (the batch download-urls bound). */
+export const MAX_BULK_PUBLISH = 100;
+/** Largest object that may be published (bytes): 512 MiB — the largest
+ *  object the public host's edge cache holds, so every published object
+ *  (and every Range of it) is served from the cache after its first read.
+ *  Bigger media belongs on a streaming/transcoding vendor, not a
+ *  cache-forever host. */
+export const MAX_PUBLISH_OBJECT_BYTES = 512 * 1024 * 1024;
+/** Most bytes ONE bulk publish call may stream (hashing an object without a
+ *  recorded checksum reads it once, copying reads it again). Ids past the
+ *  budget land in `errors[]` as `batch_budget_exceeded` — publish them in a
+ *  further call. */
+export const MAX_BULK_PUBLISH_BYTES = 2 * 1024 * 1024 * 1024;
+/** Largest source image a variant preset transforms (bytes). */
+export const MAX_VARIANT_SOURCE_BYTES = 25 * 1024 * 1024;
+
+/** A CORS origin: `*`, an https origin, or a localhost http origin (dev). No
+ *  path, no trailing slash, no wildcard sub-domains. */
+export const CORS_ORIGIN_PATTERN =
+  '^(\\*|https://[a-z0-9]([a-z0-9-]*[a-z0-9])?(\\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)*(:[0-9]{1,5})?|http://(localhost|127\\.0\\.0\\.1)(:[0-9]{1,5})?)$';
+
+/** A preset name: lower-case, URL-safe, ≤ 32 chars (it is a path segment). */
+export const VARIANT_PRESET_NAME_PATTERN = '^[a-z0-9][a-z0-9_-]{0,31}$';
+
+export const VariantPresetSchema = Type.Object({
+  w: Type.Integer({ minimum: 1, maximum: 4096 }),
+  h: Type.Optional(Type.Integer({ minimum: 1, maximum: 4096 })),
+  fit: Type.Optional(Type.Union([
+    Type.Literal('scale-down'), Type.Literal('contain'), Type.Literal('cover'),
+    Type.Literal('crop'), Type.Literal('pad'),
+  ])),
+  fmt: Type.Union([Type.Literal('webp'), Type.Literal('avif'), Type.Literal('jpeg'), Type.Literal('png')]),
+  q: Type.Optional(Type.Integer({ minimum: 1, maximum: 100 })),
+});
+export type VariantPreset = Static<typeof VariantPresetSchema>;
+
+/** `files.publicAssets` — ONE optional bag (one leaf against the 15-leaf cap).
+ *  `enabled` is the tenant's own kill switch: false ⇒ publish refuses and the
+ *  public host answers 404 for every one of the tenant's assets. */
+export const PublicAssetsConfigSchema = Type.Object({
+  enabled: Type.Boolean({ default: false }),
+  corsOrigins: Type.Array(Type.String({ pattern: CORS_ORIGIN_PATTERN, maxLength: 253 }), {
+    default: [], maxItems: MAX_CORS_ORIGINS,
+  }),
+  variants: Type.Optional(Type.Record(
+    Type.String({ pattern: VARIANT_PRESET_NAME_PATTERN }),
+    VariantPresetSchema,
+    { maxProperties: MAX_VARIANT_PRESETS },
+  )),
+});
+export type PublicAssetsConfig = Static<typeof PublicAssetsConfigSchema>;
+
+/** The MIME type a variant `fmt` outputs. */
+export function variantOutputType(fmt: VariantPreset['fmt']): 'image/webp' | 'image/avif' | 'image/jpeg' | 'image/png' {
+  return `image/${fmt}` as 'image/webp' | 'image/avif' | 'image/jpeg' | 'image/png';
+}
+
+/** A stable short fingerprint of a preset definition — part of the variant
+ *  cache key, so editing a preset never serves the old rendition. FNV-1a over
+ *  the canonical field order (no crypto needed: it only has to change). */
+export function presetFingerprint(p: VariantPreset): string {
+  const s = `${p.w}|${p.h ?? ''}|${p.fit ?? ''}|${p.fmt}|${p.q ?? ''}`;
+  let h = 0x811c9dc5;
+  for (let i = 0; i < s.length; i++) {
+    h ^= s.charCodeAt(i);
+    h = Math.imul(h, 0x01000193) >>> 0;
+  }
+  return h.toString(16).padStart(8, '0');
+}