@vxil/cli 0.24.2 → 0.26.0

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

@@ -1,4 +1,4 @@
-import type { DeclaredOrgRole, DeclaredRlPolicy, DeclaredWebhookSubscription } from './_vxil-feature-configs.js';
+import type { DeclaredOrgRole, DeclaredRlPolicy, DeclaredSearchCollection, DeclaredWebhookSubscription } from './_vxil-feature-configs.js';
 /** The target_url path markers of the platform's function-delivery lanes
  *  (control-plane fnCmsHooks.ts FN_CMSHOOK_PATH / FN_AUTHHOOK_PATH /
  *  FN_WEBHOOK_TRIGGER_PATH — mirrored here because this package is
@@ -6,7 +6,7 @@ import type { DeclaredOrgRole, DeclaredRlPolicy, DeclaredWebhookSubscription } f
  *  manifest by the deploy reconciler: never declarable, never "undeclared". */
 export declare const FN_TRIGGER_TARGET_MARKERS: readonly ["/v1/internal/fn/cms-hook/", "/v1/internal/fn/auth-hook/", "/v1/internal/fn/trigger/"];
 export declare function isFnTriggerSubscriptionUrl(targetUrl: string): boolean;
-export type ApiStateDatum = 'policies' | 'subscriptions' | 'templates' | 'roles';
+export type ApiStateDatum = 'policies' | 'subscriptions' | 'templates' | 'roles' | 'collections';
 /** feature → the declared-API-state datum its config block may carry. */
 export declare const API_STATE_DATUMS: ReadonlyArray<{
     feature: string;
@@ -147,6 +147,90 @@ export interface OrgRolePlan {
     undeclared: string[];
 }
 export declare function planOrgRoles(declared: readonly DeclaredOrgRole[], live: readonly LiveOrgRole[]): OrgRolePlan;
+/** ONE row of GET /v1/search/collections. `model` / `api_key_ref` are listed by
+ *  current servers; absent on an older server (then not compared). */
+export interface LiveSearchCollection {
+    collection: string;
+    dimensions: number;
+    provider?: string | null;
+    model?: string | null;
+    api_key_ref?: string | null;
+    /** 'arabic' | 'none'; absent on an older server (then not compared). */
+    keyword_normalize?: string | null;
+    documents?: number;
+    /** WORKSPACE-ROWS Phase 2: listed (true) only on an orgScoped collection */
+    org_scoped?: boolean;
+}
+/** The POST /v1/search/collections body an update sends: always the live
+ *  dimensions (immutable — an omitted width would fall back to the tenant
+ *  default and 422). With the provider UNCHANGED every embed field the
+ *  declaration omits keeps its live value, so a partial declaration never
+ *  resets the rest to the tenant default (the route is an upsert of the whole
+ *  embed config). On a PROVIDER CHANGE only the declared fields are sent — the
+ *  old provider's model / key never carry over to the new one. */
+export interface SearchCollectionBody {
+    collection: string;
+    dimensions?: number;
+    embed?: {
+        provider?: string;
+        model?: string;
+        apiKeyRef?: string;
+    };
+    /** sent only when declared (the route keeps the live fold when omitted) */
+    keywordNormalize?: 'arabic' | 'none';
+    /** create only — immutable after create (an update never sends it, so the
+     *  server keeps the live value) */
+    org_scoped?: boolean;
+}
+export interface SearchCollectionPlan {
+    create: SearchCollectionBody[];
+    /** an embed field the declaration sets differs — POST upserts in place
+     *  (same collection, documents kept). `reembed`: the provider or model
+     *  changes on a collection that holds documents (or whose count the server
+     *  did not list) — the indexed vectors came from the old embedder and new
+     *  queries would use the new one, so the write is destructive-shaped
+     *  (pending without --allow-destructive). An apiKeyRef-only change never is. */
+    update: Array<{
+        body: SearchCollectionBody;
+        changed: string[];
+        reembed: boolean;
+    }>;
+    unchanged: string[];
+    /** declared `dimensions` differ from the live ones — immutable after
+     *  create (422 dimensions_immutable), so never written: a refused row */
+    immutable: Array<{
+        collection: string;
+        declared: number;
+        live: number;
+    }>;
+    /** an update the planner refuses to send (a provider change that does not
+     *  declare the model / apiKeyRef the new provider needs) — a failed row */
+    refused: Array<{
+        collection: string;
+        error: string;
+    }>;
+    /** live collections the config does not declare — reported, never deleted
+     *  (there is no collection delete route) */
+    undeclared: string[];
+}
+export declare function planSearchCollections(declared: readonly DeclaredSearchCollection[], live: readonly LiveSearchCollection[]): SearchCollectionPlan;
+/** The refused-row error of a declared dimensions change. */
+export declare function searchCollectionImmutableError(i: {
+    declared: number;
+    live: number;
+}): string;
+/** `vxil pull`: the `vector-search.collections` leaf from the live list —
+ *  name, dimensions and the pinned embed config, so the pulled file plans
+ *  with zero drift and a second environment gets the same embedder. Past the
+ *  declared cap the leaf is NOT written (a pulled file must validate) and
+ *  `note` says why (the orgs.roles posture). */
+export declare function pulledSearchCollections(rows: readonly Record<string, unknown>[]): {
+    collections?: DeclaredSearchCollection[];
+    note?: string;
+};
+/** = SEARCH_COLLECTION_DECLARED_CAP (index.ts; not imported — this module is
+ *  imported BY index.ts). A parity test pins the two. */
+export declare const SEARCH_COLLECTION_PULL_CAP = 50;
 export interface ApiStateSummary {
     datum: ApiStateDatum;
     created: string[];
@@ -168,7 +252,18 @@ export interface ApiStateSummary {
         key: string;
         error: string;
     }>;
+    /** follow-up the operator must act on for a row that DID converge (e.g. a
+     *  search collection whose keyword fold was turned on needs a re-ingest);
+     *  absent = none (older servers never send it) */
+    notes?: Array<{
+        key: string;
+        note: string;
+    }>;
 }
+/** The note a converge reports when it turned the keyword fold ON for a
+ *  search collection that already holds documents (the server answered
+ *  keyword_reindex_required: true). */
+export declare const SEARCH_KEYWORD_REINDEX_NOTE = "keyword fold turned on \u2014 chunks indexed before it match only their exact spelling until re-ingested (re-ingest, or reset the sync source)";
 export declare function emptyApiStateSummary(datum: ApiStateDatum): ApiStateSummary;
 /** The `api_state` object a config-write response carries (`PUT /v1/config/
  *  :feature` and its dashboard twin, dry-run included — control-plane

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

@@ -97,6 +97,13 @@ export interface HookCaller {
      *  caller object still reads
      *  as "no roles". */
     roles?: readonly string[] | null;
+    /** Workspace scope: the session's ACTIVE org (`caller.org.id` /
+     *  `caller.org.role`), read-only; null outside active-org mode or with no
+     *  active org. Optional so an older caller object reads as "no org". */
+    org?: {
+        id: string;
+        role: string | null;
+    } | null;
 }
 export interface HookContext {
     item: Record<string, unknown>;

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

@@ -33,16 +33,37 @@ interface CdcRuleLike {
     payload?: unknown;
     enabled?: boolean;
 }
+/** The template token: one WHOLE colon-separated segment of a cdc `channel`. */
+export declare const CDC_ORG_TOKEN = "{org}";
+/** Every resolved workspace channel starts with this prefix; realtime-v1 binds
+ *  an end-user connect token for such a channel to the verified `org_id` claim
+ *  (its own copy: `workers/realtime-v1/src/token.ts` ORG_CHANNEL_PREFIX; the
+ *  `cdc-gated-fields` gate pins both copies equal). */
+export declare const ORG_CHANNEL_PREFIX = "org:";
+/** An org id that may enter a channel name: no ':' (it would shift the segment
+ *  realtime compares), the realtime channel alphabet, ≤ 64 chars (orgs ids are
+ *  `org_…`, at most 64 chars). */
+export declare const ORG_CHANNEL_ID_RE: RegExp;
+/** Is `channel` an org template — exactly one segment equal to `{org}`, every
+ *  other segment a non-empty channel-alphabet run, ≤ 128 chars in all? */
+export declare function isOrgChannelTemplate(channel: string): boolean;
+/** Resolve a template for one row's workspace: drop the `{org}` segment and
+ *  prefix `org:<id>:` (`notes:{org}` → `org:<id>:notes`; a bare `{org}` →
+ *  `org:<id>`). Null (publish nothing) for a non-template or an org id that is
+ *  not a string matching ORG_CHANNEL_ID_RE — fail closed. */
+export declare function resolveOrgChannel(template: string, orgId: unknown): string | null;
 /** Cross-field rule for CmsConfig.cdc (called from validateFeatureConfig). */
 export declare function validateCdcConfig(cdc: Record<string, CdcRuleLike> | undefined): string[];
 /** What a payload:'full' change-data rule must know about its target
  *  collection's read gates. `readRoleFields`: fields with a non-empty
  *  `readRoles`; `endUserAccess`: the collection's end-user access mode;
- *  `ownerField`: the end-user owner-scope field (null/absent = none). */
+ *  `ownerField`: the end-user owner-scope field (null/absent = none);
+ *  `orgField`: the workspace-scope field (null/absent = none). */
 export interface CdcCollectionGates {
     readRoleFields?: readonly string[];
     endUserAccess?: 'readwrite' | 'read' | 'none';
     ownerField?: string | null;
+    orgField?: string | null;
 }
 /**
  * A `payload: 'full'` change-data rule inlines the stored row into a realtime
@@ -52,9 +73,21 @@ export interface CdcCollectionGates {
  * an `endUserAccess` of 'read' / 'none' (the frame would bypass the
  * collection's end-user gate), or an `ownerField` (end users read only their
  * own rows, but the frame would carry every user's row to every subscriber —
- * CDC-FULL-OWNER-SCOPED). Pure; one problem line per offending ENABLED
+ * CDC-FULL-OWNER-SCOPED), or an `orgField` (a workspace's rows to every
+ * subscriber — `{org}` frames stay ids-only). Pure; one problem line per offending ENABLED
  * rule (an unknown collection is skipped). The safe shape is `payload: 'ids'`
  * and a re-read through the cms, where every gate applies.
  */
 export declare function cdcFullFramesOverGatedCollections(cdc: unknown, collections: Record<string, CdcCollectionGates>): string[];
+/**
+ * WORKSPACE-ROWS Phase 2: a FIXED-channel change-data rule on a workspace
+ * collection (live `orgField`) sends every workspace's change ids, status and
+ * timing to ONE channel any end user may subscribe to — only the `{org}`
+ * template (`<collection>:{org}` → `org:<org_id>:<collection>`) is valid there.
+ * The config PUT / draft-publish twin of the `workspaceManifestErrors` rule
+ * (which judges only DECLARED collections); the cms runtime floor
+ * (cdc.ts cdcChannelFor) drops such a rule for every door that cannot check.
+ * Pure; one problem line per offending ENABLED rule.
+ */
+export declare function cdcFixedChannelsOverOrgCollections(cdc: unknown, collections: Record<string, CdcCollectionGates>): string[];
 export {};

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

@@ -323,6 +323,7 @@ export declare const AuthConfigSchema: import("@sinclair/typebox").TObject<{
     }>>;
     orgClaims: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TObject<{
         enabled: import("@sinclair/typebox").TBoolean;
+        activeOrg: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TBoolean>;
     }>>;
     security: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TObject<{
         lockout: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TObject<{
@@ -332,8 +333,10 @@ export declare const AuthConfigSchema: import("@sinclair/typebox").TObject<{
         }>>;
         breachedPasswords: import("@sinclair/typebox").TBoolean;
         captchaSecretRef: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+        captchaOnReset: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TBoolean>;
         allowedRedirectOrigins: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TArray<import("@sinclair/typebox").TString>>;
         inviteOnly: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TBoolean>;
+        verifyLinkEvicts: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TBoolean>;
         allowedEmailDomains: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TArray<import("@sinclair/typebox").TString>>;
     }>>;
 }>;
@@ -410,6 +413,10 @@ export declare const FilesConfigSchema: import("@sinclair/typebox").TObject<{
             q: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TInteger>;
         }>>>;
     }>>;
+    orgScope: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TObject<{
+        readRoles: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TArray<import("@sinclair/typebox").TString>>;
+        writeRoles: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TArray<import("@sinclair/typebox").TString>>;
+    }>>;
 }>;
 export type FilesConfig = Static<typeof FilesConfigSchema>;
 export declare const DeclaredWebhookSubscriptionSchema: import("@sinclair/typebox").TObject<{
@@ -579,6 +586,30 @@ export declare const ActivityFeedConfigSchema: import("@sinclair/typebox").TObje
     }>;
 }>;
 export type ActivityFeedConfig = Static<typeof ActivityFeedConfigSchema>;
+/** At most this many declared search collections (the converge's worst-case
+ *  fan-out: one POST per declared entry per push). */
+export declare const SEARCH_COLLECTION_DECLARED_CAP = 50;
+/** One declared search collection — the POST /v1/search/collections
+ *  body (vector-search-v1 core.ts CreateCollectionIn), keyed by `collection`.
+ *  An omitted field is NOT compared against a live collection (it takes the
+ *  vector-search default on create only); `dimensions` are immutable after
+ *  create — a declared change is a refused row, never a recreate. */
+/** The widths a search collection accepts — = vector-search-v1 backend.ts
+ *  ALLOWED_DIMS (one indexed vector column each; a parity test pins them), so
+ *  an unsupported width fails validation instead of only the push. */
+export declare const SEARCH_COLLECTION_DIMS: readonly [256, 384, 512, 768, 1024, 1536, 3072];
+export declare const DeclaredSearchCollectionSchema: import("@sinclair/typebox").TObject<{
+    collection: import("@sinclair/typebox").TString;
+    dimensions: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TUnion<import("@sinclair/typebox").TLiteral<256 | 384 | 512 | 768 | 1024 | 1536 | 3072>[]>>;
+    embed: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TObject<{
+        provider: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"byov">, import("@sinclair/typebox").TLiteral<"mock">, import("@sinclair/typebox").TLiteral<"openai">, import("@sinclair/typebox").TLiteral<"cohere">]>>;
+        model: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+        apiKeyRef: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    }>>;
+    keywordNormalize: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"arabic">, import("@sinclair/typebox").TLiteral<"none">]>>;
+    orgScoped: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TBoolean>;
+}>;
+export type DeclaredSearchCollection = Static<typeof DeclaredSearchCollectionSchema>;
 export declare const VectorSearchConfigSchema: import("@sinclair/typebox").TObject<{
     enabled: import("@sinclair/typebox").TBoolean;
     backend: import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"auto">, import("@sinclair/typebox").TLiteral<"lakebase">, import("@sinclair/typebox").TLiteral<"pgvector">]>;
@@ -616,6 +647,17 @@ export declare const VectorSearchConfigSchema: import("@sinclair/typebox").TObje
         statusFilter: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"published">, import("@sinclair/typebox").TLiteral<"all">]>>;
         cron: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
     }>>>;
+    collections: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TArray<import("@sinclair/typebox").TObject<{
+        collection: import("@sinclair/typebox").TString;
+        dimensions: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TUnion<import("@sinclair/typebox").TLiteral<256 | 384 | 512 | 768 | 1024 | 1536 | 3072>[]>>;
+        embed: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TObject<{
+            provider: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"byov">, import("@sinclair/typebox").TLiteral<"mock">, import("@sinclair/typebox").TLiteral<"openai">, import("@sinclair/typebox").TLiteral<"cohere">]>>;
+            model: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+            apiKeyRef: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+        }>>;
+        keywordNormalize: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"arabic">, import("@sinclair/typebox").TLiteral<"none">]>>;
+        orgScoped: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TBoolean>;
+    }>>>;
 }>;
 export type VectorSearchConfig = Static<typeof VectorSearchConfigSchema>;
 export declare const AI_TEMPLATE_NAME_PATTERN = "^[a-zA-Z0-9_.\\-]+$";
@@ -766,6 +808,12 @@ export declare const FunctionsConfigSchema: import("@sinclair/typebox").TObject<
     metering: import("@sinclair/typebox").TObject<{
         enabled: import("@sinclair/typebox").TBoolean;
     }>;
+    logDrain: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TObject<{
+        url: import("@sinclair/typebox").TString;
+        secretRef: import("@sinclair/typebox").TString;
+        minLevel: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"debug">, import("@sinclair/typebox").TLiteral<"info">, import("@sinclair/typebox").TLiteral<"log">, import("@sinclair/typebox").TLiteral<"warn">, import("@sinclair/typebox").TLiteral<"error">]>>;
+        dailyLines: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TInteger>;
+    }>>;
     functions: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TRecord<import("@sinclair/typebox").TString, import("@sinclair/typebox").TObject<{
         bindings: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TArray<import("@sinclair/typebox").TObject<{
             kind: import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"http">, import("@sinclair/typebox").TLiteral<"queue">, import("@sinclair/typebox").TLiteral<"cron">, import("@sinclair/typebox").TLiteral<"webhook">, import("@sinclair/typebox").TLiteral<"cmsHook">, import("@sinclair/typebox").TLiteral<"authHook">]>;
@@ -920,6 +968,7 @@ export declare function fnServerScopesError(raw: unknown, fnScopes?: readonly st
  *  templateVars parity). */
 export declare function rlTemplateVars(template: string): string[];
 export declare function validateDeclaredRlPolicies(policies: readonly DeclaredRlPolicy[] | undefined): string[];
+export declare function validateDeclaredSearchCollections(collections: readonly DeclaredSearchCollection[] | undefined): string[];
 export declare function validateDeclaredOrgRoles(roles: readonly DeclaredOrgRole[] | undefined): string[];
 export declare function validateDeclaredWebhookSubscriptions(subscriptions: readonly DeclaredWebhookSubscription[] | undefined, maxSubscriptions: number | undefined): string[];
 /** The stored-template `schema` bounds — MIRRORED from @vxil/runtime
@@ -946,3 +995,15 @@ export interface PlannerHint {
     dependsOn: FeatureKey[];
 }
 export declare const FEATURE_HINTS: Record<FeatureKey, PlannerHint>;
+/** = cms-v1 core.ts RETAIN_DAYS_MAX (a parity test pins the two). */
+export declare const CMS_RETAIN_DAYS_MAX = 3650;
+/** A declared `retainDays`: absent = NOT MANAGED (the live value is left as
+ *  is — a collection whose retention was set by API is never silently
+ *  cleared by a push that does not mention it); `null` = keep items until
+ *  deleted; an integer 1..3650 = days. */
+export declare function isDeclaredRetainDays(v: unknown): v is number | null | undefined;
+/** Does moving retention from `remote` to `declared` make the sweep delete
+ *  MORE items (turning retention on, or shortening it)? On an EXISTING
+ *  collection that change applies only under allow-destructive; lengthening
+ *  or clearing keeps more and always applies. */
+export declare function retainDaysShortens(declared: number | null, remote: number | null): boolean;

package/dist/config.d.ts

@@ -132,13 +132,90 @@ export interface CollectionDef {
      *  a config leaf) and carried by BOTH push paths; widening (clearing, or
      *  adding a role) needs `vxil push --allow-destructive`. */
     writeRoles?: string[];
+    /** Retention in days (guide ch. 4): items created more than this many days
+     *  ago are soft-deleted by the nightly sweep (recoverable for 30 days). An
+     *  integer 1..3650, or `null` to keep items until deleted. ABSENT = not
+     *  managed by config — a value set by API or in the dashboard is left as is.
+     *  Set at create; on an existing collection, turning retention on or
+     *  shortening it needs `vxil push --allow-destructive` (lengthening or
+     *  `null` always applies). Carried by BOTH push paths. */
+    retainDays?: number | null;
     /** 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[];
+    /** WORKSPACE SCOPING (guide ch. 4 / 9): names an existing `string` field with
+     *  an `indexSlot` in `s1`–`s4` that holds the row's workspace (an orgs
+     *  `org_id`). A VERIFIED end user then reads and writes only the rows of the
+     *  org their session is ACTIVE in; server keys are unaffected. Needs
+     *  `features.auth.orgClaims: { enabled: true, activeOrg: true }`. May coexist
+     *  with `ownerField` (both predicates apply). Not together with a `cdc` rule or
+     *  a vector-search `sync[]` source in this release. Carried by BOTH push paths
+     *  (wire `org_field`); clearing it WIDENS access and needs
+     *  `vxil push --allow-destructive`. */
+    orgField?: string;
+    /** The ACTIVE-ORG role slugs one of which an end user must hold to READ this
+     *  `orgField` collection (absent = any member of the workspace). Up to 16 slugs
+     *  (`^[a-z0-9][a-z0-9_-]{0,31}$`); refused without `orgField`. Carried by BOTH
+     *  push paths (wire `org_read_roles`); clearing it, or adding a role, WIDENS
+     *  access and needs `vxil push --allow-destructive`. */
+    orgReadRoles?: string[];
 }
+/** The cms role-slug alphabet (workers/cms-v1/src/readRoles.ts READ_ROLE_RE):
+ *  gate slugs are at most 32 characters. */
+export declare const CMS_ROLE_SLUG_RE: RegExp;
+/** At most this many `orgReadRoles` slugs per collection (cms/0195 CHECK). */
+export declare const CMS_ORG_READ_ROLES_MAX = 16;
+/** A collection's declared orgField in either spelling (config `orgField`, wire
+ *  `org_field` — the /v1/apply bundle accepts both); a non-empty string or null. */
+export declare function declaredOrgField(def: unknown): string | null;
+/** Collection-local WORKSPACE rules — the same refusals cms-v1 makes on the
+ *  collection upsert, so a config fails at `defineConfig` / `collection()` /
+ *  `/v1/apply` instead of mid-push. Accepts both spellings (`orgField` /
+ *  `org_field`, `orgReadRoles` / `org_read_roles`, `indexSlot` / `index_slot`).
+ *  Returns every violation (empty = valid). */
+export declare function workspaceCollectionErrors(name: string, def: unknown): string[];
+/** Throwing form of `workspaceCollectionErrors` (first violation). */
+export declare function assertWorkspaceCollection(name: string, def: unknown): void;
+/** The manifest shape `workspaceManifestErrors` reads: a `VxilConfig` or a
+ *  `/v1/apply` bundle (features keyed by feature id, cms collections in either
+ *  spelling). */
+export interface WorkspaceManifestInput {
+    features?: Record<string, unknown> | VxilConfig['features'];
+    cms?: {
+        collections?: Record<string, unknown>;
+    };
+}
+/** CROSS-FEATURE workspace rules — the ones only the WHOLE manifest can see
+ *  (the cms reconciler sees one collection). Run by `defineConfig` (so every
+ *  CLI push evaluates it) and by control-plane `/v1/apply` (the server-side
+ *  authority). Returns every violation (empty = valid):
+ *   - orgField needs `features.auth.orgClaims.enabled` AND `.activeOrg`;
+ *   - a `features.cms.cdc` rule on an orgField collection must use the
+ *     `{org}` channel template (Phase 2), stay ids-only, and not target a
+ *     collection with `orgReadRoles` (the channel admits every member); a
+ *     template on a declared collection WITHOUT orgField is refused;
+ *   - a vector-search `sync[]` source reading an orgField collection must
+ *     target a collection declared in `vector-search.collections[]` with
+ *     `orgScoped: true` (Phase 2 — each document takes the row's orgField as
+ *     its org), and an unscoped source never feeds an orgScoped collection;
+ *   - an orgScoped search collection needs `auth.orgClaims.activeOrg` too;
+ *   - a read model materializing an orgField source must target an orgField
+ *     collection whose orgField has the SAME name, and group (or partition) by
+ *     the source orgField — so each rollup row lands in its own workspace;
+ *   - an `orgs.roles` key over 32 characters cannot be named in a gate
+ *     (orgReadRoles / writeRoles / field readRoles) of an orgField collection. */
+export declare function workspaceManifestErrors(config: WorkspaceManifestInput, 
+/** `checkAuth: false` skips the activeOrg rule — `/v1/apply` passes it when
+ *  the bundle neither declares an orgField collection nor features.auth, so
+ *  pre-existing live state alone never blocks an unrelated apply. */
+opts?: {
+    checkAuth?: boolean;
+}): string[];
+/** Throwing form of `workspaceManifestErrors` — run by `defineConfig`. */
+export declare function assertWorkspaceManifest(config: WorkspaceManifestInput): void;
 /** 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:

package/dist/config.js

@@ -16,6 +16,166 @@ function assertIndexedFields(name, def) {
     throw new Error(`vxil.config: cms.${name} has ${n} indexed fields \u2014 at most ${CMS_INDEXED_FIELD_BUDGET} per collection`);
   }
 }
+var CMS_ROLE_SLUG_RE = /^[a-z0-9][a-z0-9_-]{0,31}$/;
+var CMS_ORG_READ_ROLES_MAX = 16;
+var ORG_FIELD_SLOTS = /* @__PURE__ */ new Set(["s1", "s2", "s3", "s4"]);
+var isObj = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+function declaredOrgField(def) {
+  if (!isObj(def)) return null;
+  const v = def.orgField ?? def.org_field;
+  return typeof v === "string" && v.length > 0 ? v : null;
+}
+function workspaceCollectionErrors(name, def) {
+  if (!isObj(def)) return [];
+  const errs = [];
+  const at = `cms.collections.${name}`;
+  const camel = def.orgField;
+  const snake = def.org_field;
+  if (camel !== void 0 && snake !== void 0 && camel !== snake) {
+    errs.push(`${at} sets orgField and org_field to different values \u2014 send one`);
+  }
+  const rawOrg = camel ?? snake;
+  let orgField = null;
+  if (rawOrg !== void 0 && rawOrg !== null) {
+    if (typeof rawOrg !== "string" || rawOrg.length === 0) {
+      errs.push(`${at}.orgField must be a field name (got ${JSON.stringify(rawOrg)})`);
+    } else {
+      orgField = rawOrg;
+      const f = isObj(def.fields) ? def.fields[rawOrg] : void 0;
+      if (!isObj(f)) {
+        errs.push(`${at}.orgField '${rawOrg}' names no declared field`);
+      } else {
+        if (f.type !== "string") {
+          errs.push(`${at}.orgField '${rawOrg}' must be a string field (is ${JSON.stringify(f.type)})`);
+        }
+        const slot = f.indexSlot ?? f.index_slot;
+        if (typeof slot !== "string" || !ORG_FIELD_SLOTS.has(slot)) {
+          errs.push(`${at}.orgField '${rawOrg}' needs an indexSlot in s1\u2013s4 (every end-user read filters on it)`);
+        }
+      }
+    }
+  }
+  const owner = def.ownerField ?? def.owner_field;
+  if (orgField !== null && owner === orgField) {
+    errs.push(`${at}.orgField and ownerField must name different fields (both are '${orgField}')`);
+  }
+  const rrCamel = def.orgReadRoles;
+  const rrSnake = def.org_read_roles;
+  if (rrCamel !== void 0 && rrSnake !== void 0 && JSON.stringify(rrCamel) !== JSON.stringify(rrSnake)) {
+    errs.push(`${at} sets orgReadRoles and org_read_roles to different values \u2014 send one`);
+  }
+  const rr = rrCamel ?? rrSnake;
+  if (rr !== void 0 && rr !== null) {
+    if (!Array.isArray(rr) || rr.some((r) => typeof r !== "string" || !CMS_ROLE_SLUG_RE.test(r))) {
+      errs.push(`${at}.orgReadRoles must be an array of role slugs matching ${CMS_ROLE_SLUG_RE} (got ${JSON.stringify(rr)})`);
+    } else if (rr.length > CMS_ORG_READ_ROLES_MAX) {
+      errs.push(`${at}.orgReadRoles has ${rr.length} entries \u2014 at most ${CMS_ORG_READ_ROLES_MAX}`);
+    } else if (rr.length > 0 && orgField === null) {
+      errs.push(`${at}.orgReadRoles needs orgField (it gates reads of a workspace-scoped collection)`);
+    }
+  }
+  return errs;
+}
+function assertWorkspaceCollection(name, def) {
+  const errs = workspaceCollectionErrors(name, def);
+  if (errs.length) throw new Error(`vxil.config: ${errs[0]}`);
+}
+var isOrgTemplateChannel = (ch) => typeof ch === "string" && ch.split(":").includes("{org}");
+var orgReadRolesOfDef = (def) => isObj(def) ? def.orgReadRoles ?? def.org_read_roles : void 0;
+var ownerFieldOfDef = (def) => {
+  const v = isObj(def) ? def.ownerField ?? def.owner_field : void 0;
+  return typeof v === "string" && v.length > 0;
+};
+var asList = (v) => Array.isArray(v) ? v : v === void 0 || v === null ? [] : [v];
+var stringsOf = (v) => asList(v).filter((s) => typeof s === "string");
+function workspaceManifestErrors(config, opts = {}) {
+  const errs = [];
+  const rawCollections = config.cms?.collections;
+  const collections = isObj(rawCollections) ? rawCollections : {};
+  const orgCols = /* @__PURE__ */ new Map();
+  for (const [name, def] of Object.entries(collections)) {
+    const of = declaredOrgField(def);
+    if (of) orgCols.set(name, of);
+  }
+  const features = isObj(config.features) ? config.features : {};
+  const cms = isObj(features.cms) ? features.cms : {};
+  const cdcRules = Object.entries(isObj(cms.cdc) ? cms.cdc : {});
+  for (const [rule, r] of cdcRules) {
+    if (isObj(r) && typeof r.collection === "string" && isOrgTemplateChannel(r.channel) && Object.prototype.hasOwnProperty.call(collections, r.collection) && !orgCols.has(r.collection)) {
+      errs.push(`features.cms.cdc.${rule}: a '{org}' channel needs an orgField collection \u2014 '${r.collection}' declares no orgField, so no row has a workspace to publish to`);
+    }
+  }
+  const vs = isObj(features["vector-search"]) ? features["vector-search"] : {};
+  const orgScopedTargets = new Set(asList(vs.collections).filter((c) => isObj(c) && (c.orgScoped === true || c.org_scoped === true) && typeof c.collection === "string").map((c) => c.collection));
+  if (orgCols.size === 0 && orgScopedTargets.size === 0) return errs;
+  const names = [...orgCols.keys()].join(", ");
+  const auth = isObj(features.auth) ? features.auth : {};
+  const oc = isObj(auth.orgClaims) ? auth.orgClaims : {};
+  if (opts.checkAuth !== false && (oc.enabled !== true || oc.activeOrg !== true)) {
+    if (orgCols.size) {
+      errs.push(`cms.collections ${names} set orgField, which needs features.auth.orgClaims { enabled: true, activeOrg: true } \u2014 without an active org the session carries no stable workspace`);
+    }
+    if (orgScopedTargets.size) {
+      errs.push(`vector-search.collections ${[...orgScopedTargets].join(", ")} set orgScoped, which needs features.auth.orgClaims { enabled: true, activeOrg: true } \u2014 without an active org no end user can read them`);
+    }
+  }
+  for (const [rule, r] of cdcRules) {
+    if (!isObj(r) || typeof r.collection !== "string" || !orgCols.has(r.collection)) continue;
+    if (!isOrgTemplateChannel(r.channel)) {
+      errs.push(`features.cms.cdc.${rule}: collection '${r.collection}' is workspace-scoped (orgField) \u2014 a fixed cdc channel is not access control; use a workspace channel template, e.g. channel: '${r.collection}:{org}' (each row publishes to org:<its org id>:${r.collection}, which only members of that workspace can subscribe to)`);
+    } else if (r.payload === "full") {
+      errs.push(`features.cms.cdc.${rule}: collection '${r.collection}' is workspace-scoped (orgField) \u2014 frames stay ids-only (payload: 'ids'); subscribers re-read through cms, where the workspace predicate applies`);
+    } else if (stringsOf(orgReadRolesOfDef(collections[r.collection])).length > 0) {
+      errs.push(`features.cms.cdc.${rule}: collection '${r.collection}' sets orgReadRoles \u2014 an org:<id> channel admits every member of the workspace, so its frames (item ids, status, timing) would reach roles that cannot read the collection; drop the rule or the orgReadRoles`);
+    }
+  }
+  asList(vs.sync).forEach((s, i) => {
+    if (!isObj(s) || typeof s.cmsCollection !== "string") return;
+    const target = typeof s.collection === "string" ? s.collection : "";
+    if (orgCols.has(s.cmsCollection) && !orgScopedTargets.has(target)) {
+      errs.push(`features.vector-search.sync[${i}]: cmsCollection '${s.cmsCollection}' is workspace-scoped (orgField) \u2014 the target '${target}' must be declared in vector-search.collections[] with orgScoped: true, or every workspace's rows become searchable by any end user`);
+    } else if (orgCols.has(s.cmsCollection) && (stringsOf(orgReadRolesOfDef(collections[s.cmsCollection])).length > 0 || ownerFieldOfDef(collections[s.cmsCollection]))) {
+      const which = stringsOf(orgReadRolesOfDef(collections[s.cmsCollection])).length > 0 ? "orgReadRoles" : "ownerField";
+      errs.push(`features.vector-search.sync[${i}]: cmsCollection '${s.cmsCollection}' sets ${which} \u2014 synced documents are shared by every member of the workspace, so a member could search rows cms refuses them; drop the sync or the ${which}`);
+    } else if (!orgCols.has(s.cmsCollection) && orgScopedTargets.has(target)) {
+      errs.push(`features.vector-search.sync[${i}]: target '${target}' is orgScoped but cmsCollection '${s.cmsCollection}' is not workspace-scoped (orgField) \u2014 its documents would carry no workspace`);
+    }
+  });
+  for (const [rmName, rm] of Object.entries(isObj(cms.readModels) ? cms.readModels : {})) {
+    if (!isObj(rm) || typeof rm.collection !== "string") continue;
+    const srcOrg = orgCols.get(rm.collection);
+    const to = isObj(rm.materialize) ? rm.materialize.to : void 0;
+    if (!srcOrg || typeof to !== "string") continue;
+    const tOrg = orgCols.get(to);
+    const spec = isObj(rm.spec) ? rm.spec : {};
+    const groups = [...stringsOf(spec.groupBy), ...stringsOf(spec.partitionBy)];
+    if (tOrg !== srcOrg || !groups.includes(srcOrg)) {
+      errs.push(`features.cms.readModels.${rmName}: materializes workspace-scoped '${rm.collection}' into '${to}' \u2014 the target must be an orgField collection with orgField '${srcOrg}' and the read model must group by '${srcOrg}', or one workspace's rollup rows land where every end user can read them`);
+    }
+  }
+  const orgs = isObj(features.orgs) ? features.orgs : {};
+  const longRoles = new Set(asList(orgs.roles).map((r) => isObj(r) ? r.role_key : void 0).filter((k) => typeof k === "string" && k.length > 32));
+  for (const [name] of orgCols) {
+    const def = collections[name];
+    const gate = /* @__PURE__ */ new Set([
+      ...stringsOf(def.orgReadRoles ?? def.org_read_roles),
+      ...stringsOf(def.writeRoles ?? def.write_roles)
+    ]);
+    for (const f of Object.values(isObj(def.fields) ? def.fields : {})) {
+      if (isObj(f)) for (const r of stringsOf(f.readRoles ?? f.read_roles)) gate.add(r);
+    }
+    for (const r of gate) {
+      if (r.length > 32 || longRoles.has(r)) {
+        errs.push(`cms.collections.${name}: gate role '${r}' is longer than 32 characters \u2014 an orgs role named in a cms gate must be 32 characters or fewer (longer keys stay legal in orgs)`);
+      }
+    }
+  }
+  return errs;
+}
+function assertWorkspaceManifest(config) {
+  const errs = workspaceManifestErrors(config);
+  if (errs.length) throw new Error(`vxil.config: ${errs.join("; ")}`);
+}
 var RELEASED_API_VERSIONS = ["v1"];
 function defineConfig(c) {
   if (c.apiVersion !== void 0 && !RELEASED_API_VERSIONS.includes(c.apiVersion)) {
@@ -23,7 +183,11 @@ 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);
+  for (const [name, def] of Object.entries(c.cms?.collections ?? {})) {
+    assertIndexedFields(name, def);
+    assertWorkspaceCollection(name, def);
+  }
+  assertWorkspaceManifest(c);
   return c;
 }
 function field(type, opts = {}) {
@@ -31,13 +195,21 @@ function field(type, opts = {}) {
 }
 function collection(def) {
   assertIndexedFields(def.singular ?? "collection", def);
+  assertWorkspaceCollection(def.singular ?? "collection", def);
   return def;
 }
 export {
   CMS_INDEXED_FIELD_BUDGET,
+  CMS_ORG_READ_ROLES_MAX,
+  CMS_ROLE_SLUG_RE,
   RELEASED_API_VERSIONS,
   assertIndexedFields,
+  assertWorkspaceCollection,
+  assertWorkspaceManifest,
   collection,
+  declaredOrgField,
   defineConfig,
-  field
+  field,
+  workspaceCollectionErrors,
+  workspaceManifestErrors
 };