@vxil/cli 0.12.0 → 0.13.1

package/dist/_vxil-feature-configs-apiState.d.ts

@@ -166,11 +166,11 @@ export interface ApiStateResponseField extends ApiStateSummary {
 }
 /** The note every executor reports for a DISABLED feature whose block still
  *  declares rows: the declaration is kept in the manifest and nothing is
- *  converged (a parked feature is not a propagation window — review finding 2). */
+ *  converged (a parked feature is not a propagation window). */
 export declare const API_STATE_DISABLED_NOTE = "feature disabled \u2014 declaration kept, not converged";
 /** `GET /v1/rate-limits/policies` is a 100-row HARD cap with no cursor. A list
  *  AT the cap is not a complete live set, so planning creates against it would
- *  re-POST every declared name the cap hid (review finding 5). The server's
+ *  re-POST every declared name the cap hid. The server's
  *  converge and the CLI's read-only plan refuse with this message instead. */
 export declare function rlPolicyListCapError(liveCount: number): string | null;
 export declare const RL_POLICY_LIST_CAP = 100;

package/dist/_vxil-feature-configs-hooks.d.ts

@@ -69,7 +69,7 @@ export declare function parseExpr(src: string): Node;
 /** Walk the AST and reject anything outside the allow-list, plus depth bounds.
  *  Returns an array of human-readable errors (empty = safe). Pure, no eval. */
 export declare function validateAst(root: Node): string[];
-/** The VERIFIED caller/session context for read hooks (design §5.6). Read-only;
+/** The VERIFIED caller/session context for read hooks (guide ch. 7). Read-only;
  *  present only on the read path in end-user mode. In server mode / write path
  *  the whole object is null. */
 export interface HookCaller {
@@ -142,7 +142,7 @@ export interface ReadHookResult {
  *  HookEvalError (→ a clean 422, never a pinned isolate). Write events never
  *  fire here, and read events never fire in runWriteHooks. */
 export declare function runReadHooks(hooks: Record<string, HookDef> | undefined, collection: string, rows: ReadonlyArray<Record<string, unknown>>, now: string, 
-/** verified caller/session context (design §5.6) — read-only, exposed to
+/** verified caller/session context (guide ch. 7) — read-only, exposed to
  *  expressions as `caller.endUserId` / `caller.principal`. Omitted ⇒ null
  *  (server-caller mode). */
 caller?: HookCaller | null): ReadHookResult;

package/dist/_vxil-feature-configs-readmodels.d.ts

@@ -9,7 +9,7 @@ export declare const READ_MODEL_LIMITS: {
 /**
  * Structural validation of a declared read-model `spec` — shared by the
  * config-write gate here and re-exported for anyone needing the pure check.
- * `kind` selects the §3.1 (aggregate) or §4.1 (rank) grammar.
+ * `kind` selects the aggregate or the rank grammar (guide ch. 4).
  */
 export declare function validateReadModelSpecShape(where: string, kind: 'aggregate' | 'rank', spec: unknown): string[];
 /** Shape of one declared read-model (mirrors the CmsConfigSchema Record). */

package/dist/_vxil-feature-configs.d.ts

@@ -4,7 +4,7 @@ export * from './_vxil-feature-configs-readmodels.js';
 export * from './_vxil-feature-configs-apiState.js';
 export * from './_vxil-feature-configs-canonicalJson.js';
 export declare const RESERVED_CREDIT_TYPES: ReadonlySet<string>;
-/** F33 (2026-09-25): a function binding's `retry.maxAttempts` ceiling, and the
+/** 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. */
@@ -20,14 +20,14 @@ export declare const NOTIFICATION_TEMPLATE_PLACEHOLDERS: Readonly<Record<string,
  * exist and renders EMPTY. Rejected in `subject` for exactly the reason the
  * whole allow-list exists: a silent empty render in a live email. */
 export declare const NOTIFICATION_TEMPLATE_SLOT_PLACEHOLDERS: Readonly<Record<string, readonly string[]>>;
-/** Per-override caps (D4). Bodies are emails, not documents. */
+/** Per-override caps. Bodies are emails, not documents. */
 export declare const NOTIF_OVERRIDE_SUBJECT_MAX = 500;
 export declare const NOTIF_OVERRIDE_BODY_MAX = 20000;
 /** Whole-map caps: keeps one manifest (and the KV row every send reads) small. */
 export declare const NOTIF_OVERRIDE_MAX_LOCALES_PER_TEMPLATE = 20;
 export declare const NOTIF_OVERRIDE_MAX_BYTES: number;
 /**
- * D4 — validate `templates.overrides` at CONFIG-WRITE time. Returns [] when the
+ * Validate `templates.overrides` at CONFIG-WRITE time. Returns [] when the
  * bag is absent or clean. Every rule fails LOUD rather than shipping something
  * that silently renders wrong in a customer's inbox:
  *   • overrides present with `allowOverride:false` → rejected (never inert);
@@ -91,10 +91,10 @@ export declare const NotificationsConfigSchema: import("@sinclair/typebox").TObj
     }>>;
     /** in-app inbox channel (send with channel: 'inbox' | 'both') */
     inboxEnabled: import("@sinclair/typebox").TBoolean;
-    /** §11b.5 broadcast campaigns channel. Optional bag (= 1 leaf): absent means
+    /** Broadcast campaigns channel. Optional bag (= 1 leaf): absent means
      * disabled; per-campaign quiet_hours / freq_cap overrides live on the
      * notifications.campaigns ROW (tenant data), not here. Folded into the
-     * canonical schema 2026-07-18 (M21/#4 — Value.Clean previously STRIPPED the
+     * canonical schema 2026-07-18 (Value.Clean previously STRIPPED the
      * worker-local extension, so campaigns 403'd via the real config path). */
     broadcast: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TObject<{
         enabled: import("@sinclair/typebox").TBoolean;
@@ -114,9 +114,9 @@ export declare const NotificationsConfigSchema: import("@sinclair/typebox").TObj
     }>>;
 }>;
 export type NotificationsConfig = Static<typeof NotificationsConfigSchema>;
-/** The §11b.5 broadcast bag as persisted (present ⇒ leaf defaults applied). */
+/** The broadcast bag as persisted (present ⇒ leaf defaults applied). */
 export type BroadcastConfig = NonNullable<NotificationsConfig['broadcast']>;
-/** Generation-lifecycle config defaults (jobs.md §11 / §5 ≤15-flag budget). */
+/** Generation-lifecycle config defaults (guide ch. 6, jobs). */
 export declare const GENERATION_DEFAULTS: {
     /** per-tenant in-flight generation cap (separate budget from queue jobs) */
     readonly maxConcurrent: 20;
@@ -189,14 +189,14 @@ export declare const JobsConfigSchema: import("@sinclair/typebox").TObject<{
         maxTimeoutMs: import("@sinclair/typebox").TInteger;
         /** poll-mode: how many poll cycles before giving up (→ terminal-fail) */
         pollMaxAttempts: import("@sinclair/typebox").TInteger;
-        /** MANDATORY per-hold cap on a generation `reserve_credits.amount` (jobs.md
-         * §11.8). Every requested amount is CLAMPED to this (never rejected) — a
+        /** MANDATORY per-hold cap on a generation `reserve_credits.amount`
+         * (guide ch. 6, jobs). Every requested amount is CLAMPED to this (never rejected) — a
          * conservative default so an untrusted deployed function that carries a
          * reserve block can never hold more than a bounded amount per run without
          * any tenant action. */
         maxReserveCredits: import("@sinclair/typebox").TInteger;
         /** MANDATORY per-tenant ceiling on the SUM of un-settled provisional
-         * reserve holds across all in-flight generation runs (jobs.md §11.8): a
+         * reserve holds across all in-flight generation runs (guide ch. 6, jobs): a
          * reserve whose amount would push the tenant's outstanding-holds total over
          * this is rejected 429, so a runaway function cannot hold every user at
          * once. Defaulted so no tenant action is required to be safe. */
@@ -318,7 +318,7 @@ export declare const AuthConfigSchema: import("@sinclair/typebox").TObject<{
 }>;
 /** The security bag as persisted (present ⇒ leaf defaults applied). */
 export type AuthSecurityConfig = NonNullable<Static<typeof AuthConfigSchema>['security']>;
-/** The RB-2 generic OIDC / SSO issuer block (`providers.oidc`). */
+/** The generic OIDC / SSO issuer block (`providers.oidc`). */
 export type AuthOidcConfig = Static<typeof OidcProviderSchema>;
 export type AuthConfig = Static<typeof AuthConfigSchema>;
 export declare const RL_POLICY_NAME_PATTERN = "^[a-zA-Z0-9_.:-]+$";
@@ -789,11 +789,11 @@ export declare const CopilotConfigSchema: import("@sinclair/typebox").TObject<{
 export type CopilotConfig = Static<typeof CopilotConfigSchema>;
 export declare const FEATURE_SCHEMAS: Record<string, TSchema>;
 export declare const CONFIG_FLAG_CAP = 15;
-/** Counts leaf flags in a TypeBox object schema (architecture §6).
- * Per features/auth.md §4: an OPTIONAL object (e.g. a provider credential
+/** Counts leaf flags in a TypeBox object schema.
+ * Per guide ch. 6, auth: an OPTIONAL object (e.g. a provider credential
  * block) counts as ONE flag — the tenant's decision is "configure it or
  * not", not each inner ref. */
-/** The auth lifecycle events an `authHook` binding may name (F4-30) — the
+/** The auth lifecycle events an `authHook` binding may name — the
  * closed union `packages/config` types as AuthHookEvent; the control-plane
  * reconciler maps each to its `auth.<event>` audit-event prefix. */
 export declare const AUTH_HOOK_EVENTS: readonly ["user.created", "session.created", "session.revoked", "signin.failure"];
@@ -805,13 +805,13 @@ export type AuthHookEvent = (typeof AUTH_HOOK_EVENTS)[number];
  * else is refused at config write (E-CMSHOOK, 2026-10-01): an unknown name used
  * to fall back to beforeWrite at delivery, so a typo like 'afterCreate' or
  * 'beforeDelete' silently subscribed the function to creates AND updates.
- * tests/ci/src/fn-binding-contracts.test.ts pins every copy to this list. */
+ * A CI gate pins every copy to this list. */
 export declare const CMS_HOOK_EVENTS: readonly ["beforeCreate", "beforeUpdate", "beforeWrite"];
 export type CmsHookEvent = (typeof CMS_HOOK_EVENTS)[number];
 /** The ONE refusal text for an unknown cmsHook binding event (the config
  * validator and the deploy route's early 422 both use it). */
 export declare function cmsHookEventError(event: unknown): string | null;
-/** F4-29 test-recipient entry grammar (shared by the validator and auth-v1's
+/** The OTP test-recipient entry grammar (shared by the validator and auth-v1's
  * matcher): an exact email, a `*@domain` glob, or a +E.164 phone number. */
 export declare const TEST_RECIPIENT_EMAIL_RE: RegExp;
 export declare const TEST_RECIPIENT_GLOB_RE: RegExp;

package/dist/config.d.ts

@@ -14,7 +14,7 @@ export interface FieldDef {
     relationTo?: string;
     computed?: boolean;
     compute?: unknown;
-    /** Claims-table-enforced value uniqueness across live items (cms.md §9.3):
+    /** Claims-table-enforced value uniqueness across live items (guide ch. 4):
      *  a duplicate write is a clean 409 unique_violation. Scalar types only
      *  (string/int/float/datetime/relation/file). Carried on collection/field
      *  CREATE by `vxil push` and server apply; since 2026-07-17 `vxil push` also
@@ -22,12 +22,12 @@ export interface FieldDef {
      *  field re-add — packages/cli/src/cms.ts FIELD_ATTRS); attributes push
      *  cannot reconcile surface as a visible plan warning, never a silent no-op. */
     unique?: boolean;
-    /** Per-relation-field delete behavior (cms.md §11): bounded, atomic fan-out
-     *  when the referenced item is deleted — or `restrict` (§11.1), which REFUSES
+    /** Per-relation-field delete behavior (guide ch. 4): bounded, atomic fan-out
+     *  when the referenced item is deleted — or `restrict`, which REFUSES
      *  the delete with 409 `referenced` while a live reference exists. Same
      *  carriage + reconcile behavior as `unique`. */
     onDelete?: 'cascade' | 'set_null' | 'restrict';
-    /** FIELD-LEVEL READ SECURITY (cms.md §18): the end-user ORG ROLE slugs allowed
+    /** FIELD-LEVEL READ SECURITY (guide ch. 4): the end-user ORG ROLE slugs allowed
      *  to READ this field. Omitted/`[]` = ungated (every caller sees it — today's
      *  behavior). A non-empty list is FAIL-SAFE: in VERIFIED end-user mode the
      *  field is OMITTED from every read (get / list / query / `$expand` at any
@@ -40,8 +40,23 @@ export interface FieldDef {
      *  `orgs` role alphabet). The gate
      *  never affects WRITES. Carried by BOTH push paths and alterable in place. */
     readRoles?: string[];
+    /** EQUALITY INDEX for an UNSLOTTED field (guide ch. 4 "Indexed equality"):
+     *  `=` / `$eq` / `$in` filters on it are index-served instead of a bounded
+     *  scan — results are identical either way. At most 4 per collection (the
+     *  equality-key budget, separate from the 8 index slots); not together with
+     *  `indexSlot` (a slot already indexes equality) and not on a computed field
+     *  (both checked here at define time and again by the server). Carried by
+     *  BOTH push paths and alterable in place; on a collection over 2,000 live
+     *  items `vxil push` also runs the re-index that arms it. */
+    indexed?: boolean;
 }
-/** One config-declared per-record ACTION button (cms.md §17): exactly ONE
+/** The per-collection budget of `indexed: true` fields (cms/0158: e1…e4). */
+export declare const CMS_INDEXED_FIELD_BUDGET = 4;
+/** Define-time checks of a collection's `indexed` fields — the same refusals
+ *  the server makes (422), so a config fails at `defineConfig` / `collection()`
+ *  instead of mid-push. Throws on the first violation. */
+export declare function assertIndexedFields(name: string, def: CollectionDef): void;
+/** One config-declared per-record ACTION button (guide ch. 4): exactly ONE
  *  human-initiated step — pressing it invokes the deployed tenant function `fn`
  *  with `{ collection, item_id, action, actor, item }` and returns its result.
  *  No conditions, no chaining, no scheduling. `key` matches
@@ -56,7 +71,7 @@ export interface CmsActionDef {
  *  `FieldDef` itself so it can never drift from the authoring type: it is every
  *  key of `FieldDef` except `type` (which is required, not an optional carried
  *  attribute). This is the compile-time source of truth for the config-carriage
- *  completeness ratchet (audit 2026-07-15e #2, roadmap §4.5 P3): the CLI carriage
+ *  completeness ratchet: the CLI carriage
  *  table (`packages/cli/src/cms.ts` FIELD_ATTRS) and the server one
  *  (`workers/control-plane/src/handlers/apply.ts` FIELD_ATTR_DELTA) each pin
  *  `keyof` coverage against a set that equals this — so a 9th attribute added to
@@ -83,7 +98,7 @@ export interface CollectionDef {
      *  server-caller mode. Not a hard-isolation predicate; a single declarative
      *  flag the typed worker consults. Omit for shared/reference collections. */
     ownerField?: string;
-    /** Public delivery (roadmap §4.4): when true, this collection's PUBLISHED items
+    /** Public delivery (guide ch. 4): when true, this collection's PUBLISHED items
      *  are servable through the keyless, edge-cached GET /v1/cms/public/:tenantId/
      *  :collection lane (no API key). Owner-UNSCOPED (public content, not per-user);
      *  the owner_field is stripped from every served row. Default false. Carried by
@@ -91,22 +106,22 @@ export interface CollectionDef {
      *  with a regression test on each — an attribute read by no enforcing path ships
      *  inert (the validation.unique / owner_field precedent). */
     public?: boolean;
-    /** Per-record action buttons (cms.md §17): `[{ key, label, fn }]`, stored on
+    /** Per-record action buttons (guide ch. 4): `[{ key, label, fn }]`, stored on
      *  the collection (model data, not a config leaf). The dashboard renders one
      *  button per action on each record row; `POST /v1/cms/items/:coll/:id/actions/
      *  :key` invokes `fn` once. Carried by BOTH push paths (create + reconcile on
      *  existing collections — config is the source of truth; `[]`/absent clears). */
     actions?: CmsActionDef[];
 }
-/** The auth lifecycle events an `authHook` binding may subscribe to (F4-30,
- * auth wave 2026-09-10) — a CLOSED union; ONE event per binding, one audit
+/** The auth lifecycle events an `authHook` binding may subscribe to
+ * (2026-09-10) — a CLOSED union; ONE event per binding, one audit
  * event → one function invocation, no branching inside vxil:
  *   user.created    — auth.user.created  { user_id, method, is_anonymous }
  *   session.created — auth.session.created { user_id, session_id }
  *   session.revoked — auth.session.revoked { user_id, session_id, reason }
  *   signin.failure  — auth.signin.failure { email_hash | user_id, reason } */
 export type AuthHookEvent = 'user.created' | 'session.created' | 'session.revoked' | 'signin.failure';
-/** The opt-in re-delivery of a platform-delivered trigger (F33, 2026-09-25).
+/** The opt-in re-delivery of a platform-delivered trigger (guide ch. 8).
  *  DEFAULT OFF: the platform acknowledges every delivery with a 200 whatever
  *  the handler returned — an application error is observed (`functions.run.failed`),
  *  never re-delivered. With `retry` set on a `queue` / `webhook` / `cmsHook` /
@@ -126,7 +141,7 @@ export interface FunctionTriggerRetry {
     /** 1–5 attempts in all (1 = a failed attempt dead-letters at once, no re-delivery) */
     maxAttempts: number;
 }
-/** A function trigger (the §7.3 crossing). cmsHook fires on a CMS write;
+/** A function trigger (guide ch. 8). cmsHook fires on a CMS write;
  * authHook fires on ONE auth lifecycle event (default `user.created` — the
  * post-signup hook; at-least-once, ~1min fanout latency). */
 export type FunctionTrigger = {
@@ -228,7 +243,7 @@ export interface FunctionDef {
         timeoutMs?: number;
     };
     enabled?: boolean;
-    /** optional typed contract surfaced by `vxil gen` (Level 1, §4.5). */
+    /** optional typed contract surfaced by `vxil gen` (Level 1; guide ch. 8). */
     signature?: {
         input?: unknown;
         output?: unknown;
@@ -263,8 +278,7 @@ export declare const RELEASED_API_VERSIONS: readonly ApiVersion[];
 /** Recursive partial: a `vxil.config.ts` may write any SUBSET of a nested bag
  *  (`auth: { otp: { enabled: true } }`) — the server applies the defaults for
  *  the rest (Value.Default). A shallow `Partial` made `tsc` reject every
- *  partially-written nested bag, including the guide's own skeleton
- *  (found by the 2026-09-19 cvskit dry-run). Arrays and primitives are kept
+ *  partially-written nested bag, including the guide's own skeleton. Arrays and primitives are kept
  *  as-is; only plain object bags recurse. */
 export type DeepPartial<T> = T extends readonly unknown[] ? T : T extends object ? {
     [K in keyof T]?: DeepPartial<T[K]>;
@@ -303,7 +317,7 @@ export interface VxilConfig {
     };
     /** (b) CMS SCHEMA-AS-CODE — collections + fields. `push` reconciles them
      *  additively against GET /v1/cms/collections (no destructive drops without
-     *  --allow-destructive). Lane-A hooks stay in features.cms.hooks (config). */
+     *  --allow-destructive). Validation hooks stay in features.cms.hooks (config). */
     cms?: {
         collections?: Record<string, CollectionDef>;
     };
@@ -319,7 +333,7 @@ export interface VxilConfig {
  *  from JS callers with no compile gate, or a stale generated value) fails fast
  *  here rather than 404-ing every request against a nonexistent major. */
 export declare function defineConfig(c: VxilConfig): VxilConfig;
-/** Authoring helper for split-out cms/<name>.ts collection modules (§6a).
+/** Authoring helper for split-out cms/<name>.ts collection modules (guide ch. 5).
  *  `field('title', 'string', { required: true, indexSlot: 's1' })`. */
 export declare function field(type: FieldType, opts?: Omit<FieldDef, 'type'>): FieldDef;
 /** Authoring helper for a collection module: `export default collection({...})`. */

package/dist/config.js

@@ -1,4 +1,21 @@
 // ../config/src/index.ts
+var CMS_INDEXED_FIELD_BUDGET = 4;
+function assertIndexedFields(name, def) {
+  let n = 0;
+  for (const [fname, f] of Object.entries(def.fields ?? {})) {
+    if (f.indexed !== true) continue;
+    n += 1;
+    if (f.indexSlot) {
+      throw new Error(`vxil.config: cms.${name}.${fname} sets both indexed and indexSlot '${f.indexSlot}' \u2014 a slot already indexes equality; use one`);
+    }
+    if (f.computed) {
+      throw new Error(`vxil.config: cms.${name}.${fname} is computed \u2014 a computed field cannot be indexed (bind it to an indexSlot instead)`);
+    }
+  }
+  if (n > CMS_INDEXED_FIELD_BUDGET) {
+    throw new Error(`vxil.config: cms.${name} has ${n} indexed fields \u2014 at most ${CMS_INDEXED_FIELD_BUDGET} per collection`);
+  }
+}
 var RELEASED_API_VERSIONS = ["v1"];
 function defineConfig(c) {
   if (c.apiVersion !== void 0 && !RELEASED_API_VERSIONS.includes(c.apiVersion)) {
@@ -6,16 +23,20 @@ function defineConfig(c) {
       `vxil.config: apiVersion '${String(c.apiVersion)}' is not a released API major (released: ${RELEASED_API_VERSIONS.map((v) => `'${v}'`).join(", ")}). A new major ships as a new path with its own deprecation window \u2014 see https://vxil.com/docs/guide/12-going-to-production.`
     );
   }
+  for (const [name, def] of Object.entries(c.cms?.collections ?? {})) assertIndexedFields(name, def);
   return c;
 }
 function field(type, opts = {}) {
   return { type, ...opts };
 }
 function collection(def) {
+  assertIndexedFields(def.singular ?? "collection", def);
   return def;
 }
 export {
+  CMS_INDEXED_FIELD_BUDGET,
   RELEASED_API_VERSIONS,
+  assertIndexedFields,
   collection,
   defineConfig,
   field