@vxil/config 0.1.2 → 0.3.0

package/dist/index.d.ts

@@ -14,7 +14,64 @@ export interface FieldDef {
     relationTo?: string;
     computed?: boolean;
     compute?: unknown;
+    /** Claims-table-enforced value uniqueness across live items (cms.md §9.3):
+     *  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
+     *  RECONCILES it on an existing same-type field (in-place alter via the REST
+     *  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
+     *  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
+     *  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
+     *  depth / the write-response echo / read-hook payloads) unless the session's
+     *  verified `roles` claim intersects the list, it is UNQUERYABLE (a filter /
+     *  sort / group-by naming it is a 422, so it cannot be a value oracle), and it
+     *  is NEVER served on the anonymous public lane. A trusted SERVER caller (an
+     *  API key with no end-user session) still sees every field — this gates END
+     *  USERS, not the tenant. ≤16 entries, each `^[a-z0-9][a-z0-9_-]{0,31}$` (the
+     *  `orgs` role alphabet). The gate
+     *  never affects WRITES. Carried by BOTH push paths and alterable in place. */
+    readRoles?: string[];
 }
+/** One config-declared per-record ACTION button (cms.md §17): 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
+ *  /^[a-z][a-z0-9_]{0,31}$/, `fn` is a function name (/^[a-z][a-z0-9-]{0,47}$/),
+ *  ≤8 per collection. */
+export interface CmsActionDef {
+    key: string;
+    label: string;
+    fn: string;
+}
+/** The CANONICAL field-attribute name set (config-side spelling), DERIVED from
+ *  `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
+ *  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
+ *  `FieldDef` WITHOUT threading it through BOTH push paths is a tsc error naming
+ *  the uncovered key, not a silent half-carriage. */
+export type FieldAttrName = Exclude<keyof FieldDef, 'type'>;
+/** Compile-time exact-key closure helper: resolves to `Set` iff `Covered`
+ *  covers EVERY member of `Required` (i.e. `Required` is assignable to
+ *  `Covered`), else to the specific uncovered key literal(s) — so a `satisfies`
+ *  against the covered literal union produces a tsc error naming the field the
+ *  developer forgot to thread through the carriage table. Used by both push
+ *  paths' carriage tables to gate additions to `FieldAttrName`. */
+export type CoversFieldAttrs<Covered extends FieldAttrName> = [
+    FieldAttrName
+] extends [Covered] ? Covered : Exclude<FieldAttrName, Covered>;
 /** A CMS collection-as-code: collection slug → fields. */
 export interface CollectionDef {
     singular?: string;
@@ -23,13 +80,35 @@ export interface CollectionDef {
      *  existing `string` field on this collection that holds the owner (end-user)
      *  id. When set, the cms worker auto-scopes owned reads/writes to the VERIFIED
      *  end-user principal in end-user mode (default-deny) — and is a no-op in
-     *  server-caller mode. NOT an RLS predicate; a single declarative flag the
-     *  typed worker consults. Omit for shared/reference collections. */
+     *  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
+     *  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
+     *  BOTH push paths (the `vxil push` cms reconciler AND control-plane /v1/apply)
+     *  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
+     *  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
+ * 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';
 /** A function trigger (the §7.3 crossing). cmsHook fires on a CMS write;
- * authHook is the post-signup hook (fires on `auth.user.created`,
- * at-least-once, ~1min fanout latency). */
+ * authHook fires on ONE auth lifecycle event (default `user.created` — the
+ * post-signup hook; at-least-once, ~1min fanout latency). */
 export type FunctionTrigger = {
     kind: 'http';
     path?: string;
@@ -48,7 +127,7 @@ export type FunctionTrigger = {
     event: 'beforeCreate' | 'beforeUpdate' | 'beforeWrite';
 } | {
     kind: 'authHook';
-    event?: 'user.created';
+    event?: AuthHookEvent;
 };
 /** A deployed tenant function — source in functions/, deployed on `vxil push`. */
 export interface FunctionDef {
@@ -77,7 +156,7 @@ export interface FunctionDef {
 }
 /** A secret REFERENCE (never a value). `vxil secrets set <name>` writes the value. */
 export interface SecretRef {
-    /** which feature's KEK the value is envelope-encrypted under. */
+    /** which feature the value is encrypted at rest under. */
     feature: string;
     description?: string;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vxil/config",
-  "version": "0.1.2",
+  "version": "0.3.0",
   "description": "defineConfig() — one typed source of truth for a whole vxil backend (features + CMS schema + functions + secret refs + seed). INTERNAL workspace package: bundled into the published `vxil` package's `vxil/config` subpath, not published separately.",
   "license": "MIT",
   "homepage": "https://vxil.com",
@@ -22,7 +22,7 @@
     "src"
   ],
   "dependencies": {
-    "@vxil/feature-configs": "0.1.1"
+    "@vxil/feature-configs": "0.3.0"
   },
   "publishConfig": {
     "access": "public"

package/src/index.ts

@@ -33,8 +33,67 @@ export interface FieldDef {
   relationTo?: string;
   computed?: boolean;
   compute?: unknown;
+  /** Claims-table-enforced value uniqueness across live items (cms.md §9.3):
+   *  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
+   *  RECONCILES it on an existing same-type field (in-place alter via the REST
+   *  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
+   *  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
+   *  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
+   *  depth / the write-response echo / read-hook payloads) unless the session's
+   *  verified `roles` claim intersects the list, it is UNQUERYABLE (a filter /
+   *  sort / group-by naming it is a 422, so it cannot be a value oracle), and it
+   *  is NEVER served on the anonymous public lane. A trusted SERVER caller (an
+   *  API key with no end-user session) still sees every field — this gates END
+   *  USERS, not the tenant. ≤16 entries, each `^[a-z0-9][a-z0-9_-]{0,31}$` (the
+   *  `orgs` role alphabet). The gate
+   *  never affects WRITES. Carried by BOTH push paths and alterable in place. */
+  readRoles?: string[];
 }
 
+/** One config-declared per-record ACTION button (cms.md §17): 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
+ *  /^[a-z][a-z0-9_]{0,31}$/, `fn` is a function name (/^[a-z][a-z0-9-]{0,47}$/),
+ *  ≤8 per collection. */
+export interface CmsActionDef {
+  key: string;
+  label: string;
+  fn: string;
+}
+
+/** The CANONICAL field-attribute name set (config-side spelling), DERIVED from
+ *  `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
+ *  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
+ *  `FieldDef` WITHOUT threading it through BOTH push paths is a tsc error naming
+ *  the uncovered key, not a silent half-carriage. */
+export type FieldAttrName = Exclude<keyof FieldDef, 'type'>;
+
+/** Compile-time exact-key closure helper: resolves to `Set` iff `Covered`
+ *  covers EVERY member of `Required` (i.e. `Required` is assignable to
+ *  `Covered`), else to the specific uncovered key literal(s) — so a `satisfies`
+ *  against the covered literal union produces a tsc error naming the field the
+ *  developer forgot to thread through the carriage table. Used by both push
+ *  paths' carriage tables to gate additions to `FieldAttrName`. */
+export type CoversFieldAttrs<Covered extends FieldAttrName> =
+  [FieldAttrName] extends [Covered] ? Covered : Exclude<FieldAttrName, Covered>;
+
 /** A CMS collection-as-code: collection slug → fields. */
 export interface CollectionDef {
   singular?: string;
@@ -43,21 +102,44 @@ export interface CollectionDef {
    *  existing `string` field on this collection that holds the owner (end-user)
    *  id. When set, the cms worker auto-scopes owned reads/writes to the VERIFIED
    *  end-user principal in end-user mode (default-deny) — and is a no-op in
-   *  server-caller mode. NOT an RLS predicate; a single declarative flag the
-   *  typed worker consults. Omit for shared/reference collections. */
+   *  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
+   *  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
+   *  BOTH push paths (the `vxil push` cms reconciler AND control-plane /v1/apply)
+   *  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
+   *  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
+ * 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';
+
 /** A function trigger (the §7.3 crossing). cmsHook fires on a CMS write;
- * authHook is the post-signup hook (fires on `auth.user.created`,
- * at-least-once, ~1min fanout latency). */
+ * authHook fires on ONE auth lifecycle event (default `user.created` — the
+ * post-signup hook; at-least-once, ~1min fanout latency). */
 export type FunctionTrigger =
   | { kind: 'http'; path?: string }
   | { kind: 'cron'; schedule: string }
   | { kind: 'queue'; source: string }
   | { kind: 'webhook'; source: string }
   | { kind: 'cmsHook'; collection: string; event: 'beforeCreate' | 'beforeUpdate' | 'beforeWrite' }
-  | { kind: 'authHook'; event?: 'user.created' };
+  | { kind: 'authHook'; event?: AuthHookEvent };
 
 /** A deployed tenant function — source in functions/, deployed on `vxil push`. */
 export interface FunctionDef {
@@ -80,7 +162,7 @@ export interface FunctionDef {
 
 /** A secret REFERENCE (never a value). `vxil secrets set <name>` writes the value. */
 export interface SecretRef {
-  /** which feature's KEK the value is envelope-encrypted under. */
+  /** which feature the value is encrypted at rest under. */
   feature: string;
   description?: string;
 }