@vxil/feature-configs 0.8.0 → 0.9.0

package/dist/index.d.ts

@@ -6,9 +6,12 @@ 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

package/dist/index.js

@@ -42,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) {
@@ -341,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
@@ -1413,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).
@@ -2127,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}')`);
                 }
@@ -2223,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: {
@@ -2247,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: [],
     },
@@ -2265,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: [],
@@ -2327,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vxil/feature-configs",
-  "version": "0.8.0",
+  "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

@@ -46,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). */
@@ -399,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
@@ -1754,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).
@@ -2567,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}')`);
         }
@@ -2683,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: {
@@ -2707,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: [],
   },
@@ -2725,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: [],
@@ -2787,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: {