@vxil/feature-configs 0.5.0 → 0.5.1

package/dist/apiState.d.ts

@@ -149,14 +149,12 @@ export interface ApiStateSummary {
 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
- *  handlers/apiState.ts apiStateResponseField) and the shape `vxil push` READS
- *  back instead of converging a second time (review 2026-09-23, finding 1: the
- *  server's converge is the one that ran with the key's scopes; a client-side
- *  repeat re-listed a KV-backed datum ~100 ms later and could double-create).
- *  `ok:false` + `deferred:true` = the feature worker has not seen the config
- *  yet (the client may converge after its own wait); `ok:false` otherwise =
- *  a DEFINITE, named refusal (nothing to retry); `note` = converged nothing on
- *  purpose (a disabled feature). */
+ *  handlers/apiState.ts apiStateResponseField) and the shape `vxil push` /
+ *  `vxil plan` print. `ok:false` + `deferred:true` = not converged for an
+ *  INDEFINITE reason — the feature worker has not seen the config yet, or a
+ *  transient failure (a push asks again through POST /v1/apply after its
+ *  wait); `ok:false` otherwise = a DEFINITE, named refusal (nothing to retry);
+ *  `note` = converged nothing on purpose (a disabled feature). */
 export interface ApiStateResponseField extends ApiStateSummary {
     ok: boolean;
     dry_run?: boolean;
@@ -170,8 +168,8 @@ export interface ApiStateResponseField extends ApiStateSummary {
 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). Both executors
- *  refuse with this message instead. */
+ *  re-POST every declared name the cap hid (review finding 5). 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;
 /** `+2 created · ~1 updated · =3 unchanged · 1 undeclared (left in place)` —

package/dist/apiState.js

@@ -165,8 +165,8 @@ export function emptyApiStateSummary(datum) {
 export const API_STATE_DISABLED_NOTE = 'feature disabled — 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). Both executors
- *  refuse with this message instead. */
+ *  re-POST every declared name the cap hid (review finding 5). The server's
+ *  converge and the CLI's read-only plan refuse with this message instead. */
 export function rlPolicyListCapError(liveCount) {
     if (liveCount < RL_POLICY_LIST_CAP)
         return null;

package/dist/canonicalJson.d.ts

@@ -0,0 +1,7 @@
+/** JSON.stringify with object keys sorted at every depth (arrays keep their
+ *  order; undefined-valued keys are dropped, as JSON.stringify drops them).
+ *  Two values with equal output are equal in CONTENT. A stored manifest comes
+ *  back from storage with its object keys re-ordered, so every declared-vs-
+ *  stored config compare (the server's shallowDiff, the CLI's diffManifest)
+ *  must go through this, never through plain JSON.stringify. */
+export declare function canonicalJson(v: unknown): string | undefined;

package/dist/canonicalJson.js

@@ -0,0 +1,16 @@
+/** JSON.stringify with object keys sorted at every depth (arrays keep their
+ *  order; undefined-valued keys are dropped, as JSON.stringify drops them).
+ *  Two values with equal output are equal in CONTENT. A stored manifest comes
+ *  back from storage with its object keys re-ordered, so every declared-vs-
+ *  stored config compare (the server's shallowDiff, the CLI's diffManifest)
+ *  must go through this, never through plain JSON.stringify. */
+export function canonicalJson(v) {
+    if (Array.isArray(v))
+        return `[${v.map((x) => canonicalJson(x) ?? 'null').join(',')}]`;
+    if (v !== null && typeof v === 'object') {
+        const o = v;
+        const keys = Object.keys(o).filter((k) => o[k] !== undefined).sort();
+        return `{${keys.map((k) => `${JSON.stringify(k)}:${canonicalJson(o[k])}`).join(',')}}`;
+    }
+    return JSON.stringify(v);
+}

package/dist/index.d.ts

@@ -2,6 +2,7 @@ import { type Static, type TSchema } from '@sinclair/typebox';
 export * from './hooks.js';
 export * from './readmodels.js';
 export * from './apiState.js';
+export * from './canonicalJson.js';
 export declare const RESERVED_CREDIT_TYPES: ReadonlySet<string>;
 /** True when a credit_type is a vxil-COGS reserved type (grant/consume/config
  *  of which is restricted to internal platform machinery). */

package/dist/index.js

@@ -18,6 +18,9 @@ export * from './readmodels.js';
 // declared-vs-live reconciliation, shared by the control-plane apply path and
 // the CLI (`vxil plan/diff/push`), so the two push paths can never diverge.
 export * from './apiState.js';
+// Key-order-insensitive JSON: the one declared-vs-stored manifest compare
+// (control-plane shallowDiff, CLI diffManifest).
+export * from './canonicalJson.js';
 // TypeBox validates `format:` only for registered formats — register the ones
 // our schemas use (pragmatic RFC-lite email check; providers do the real one).
 if (!FormatRegistry.Has('email')) {
@@ -1956,8 +1959,14 @@ export function validateFeatureConfig(feature, raw) {
         for (const [id, agent] of Object.entries(v.agents ?? {})) {
             const allow = agent.actions?.allow ?? {};
             const guestAllow = agent.guardrails?.guestToolAllow ?? [];
-            if (agent.guardrails?.allowGuest === true)
+            if (agent.guardrails?.allowGuest === true) {
                 anyGuestAgent = true;
+                // Guests share ONE tenant-wide bucket that spends the tenant's own AI
+                // key: an unlimited (0) daily cap is never allowed alongside them.
+                if (agent.guardrails.rateLimitPerUserPerDay === 0) {
+                    errs.push(`/agents/${id}/guardrails/rateLimitPerUserPerDay: 0 (unlimited) is not allowed with allowGuest: true — set a finite daily cap (guests share one tenant-wide bucket)`);
+                }
+            }
             if (knownMcpTools) {
                 for (const tool of Object.keys(allow)) {
                     if (!knownMcpTools.has(tool)) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vxil/feature-configs",
-  "version": "0.5.0",
+  "version": "0.5.1",
   "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/apiState.ts

@@ -14,12 +14,14 @@
 //
 // ONE WRITER PER DATUM, AND THE WRITER IS THE REPOSITORY. The planner below is
 // PURE (no I/O, no clock): it takes the declared list and the live rows and
-// returns the exact operation set. Two executors drive it against two
-// transports — the control-plane (handlers/apiState.ts: the feature's own
-// routes with the caller's scopes, or its own table in-process) and the CLI
-// (packages/cli/src/apiState.ts: the tenant's API key) — and a parity test pins
-// that the same fixtures produce the same plan on both, the cms-schema
-// precedent.
+// returns the exact operation set. ONE executor drives it: the control-plane
+// (handlers/apiState.ts convergeApiState — the feature's own routes with the
+// caller's scopes, or its own table in-process), after every config write and
+// as the api-state step of POST /v1/apply. The CLI (packages/cli/src/
+// apiState.ts) never writes these rows: `vxil push` asks the server, and
+// `vxil plan` / `vxil diff` run this planner READ-ONLY when the server's dry
+// run could not plan. packages/cli/src/apiState.e2e.test.ts drives the real
+// CLI binary against the real convergeApiState.
 //
 // THE NON-DESTRUCTIVE DEFAULT. A live row the config does NOT declare is
 // LEFT IN PLACE and reported as `undeclared` — deleted only when the caller
@@ -285,14 +287,12 @@ export 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
- *  handlers/apiState.ts apiStateResponseField) and the shape `vxil push` READS
- *  back instead of converging a second time (review 2026-09-23, finding 1: the
- *  server's converge is the one that ran with the key's scopes; a client-side
- *  repeat re-listed a KV-backed datum ~100 ms later and could double-create).
- *  `ok:false` + `deferred:true` = the feature worker has not seen the config
- *  yet (the client may converge after its own wait); `ok:false` otherwise =
- *  a DEFINITE, named refusal (nothing to retry); `note` = converged nothing on
- *  purpose (a disabled feature). */
+ *  handlers/apiState.ts apiStateResponseField) and the shape `vxil push` /
+ *  `vxil plan` print. `ok:false` + `deferred:true` = not converged for an
+ *  INDEFINITE reason — the feature worker has not seen the config yet, or a
+ *  transient failure (a push asks again through POST /v1/apply after its
+ *  wait); `ok:false` otherwise = a DEFINITE, named refusal (nothing to retry);
+ *  `note` = converged nothing on purpose (a disabled feature). */
 export interface ApiStateResponseField extends ApiStateSummary {
   ok: boolean;
   dry_run?: boolean;
@@ -308,8 +308,8 @@ export const API_STATE_DISABLED_NOTE = 'feature disabled — declaration kept, n
 
 /** `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). Both executors
- *  refuse with this message instead. */
+ *  re-POST every declared name the cap hid (review finding 5). The server's
+ *  converge and the CLI's read-only plan refuse with this message instead. */
 export function rlPolicyListCapError(liveCount: number): string | null {
   if (liveCount < RL_POLICY_LIST_CAP) return null;
   return `the policy list is at its ${RL_POLICY_LIST_CAP}-row hard cap (no cursor) — the live set may be incomplete; delete undeclared policies before converging`;

package/src/canonicalJson.ts

@@ -0,0 +1,15 @@
+/** JSON.stringify with object keys sorted at every depth (arrays keep their
+ *  order; undefined-valued keys are dropped, as JSON.stringify drops them).
+ *  Two values with equal output are equal in CONTENT. A stored manifest comes
+ *  back from storage with its object keys re-ordered, so every declared-vs-
+ *  stored config compare (the server's shallowDiff, the CLI's diffManifest)
+ *  must go through this, never through plain JSON.stringify. */
+export function canonicalJson(v: unknown): string | undefined {
+  if (Array.isArray(v)) return `[${v.map((x) => canonicalJson(x) ?? 'null').join(',')}]`;
+  if (v !== null && typeof v === 'object') {
+    const o = v as Record<string, unknown>;
+    const keys = Object.keys(o).filter((k) => o[k] !== undefined).sort();
+    return `{${keys.map((k) => `${JSON.stringify(k)}:${canonicalJson(o[k])}`).join(',')}}`;
+  }
+  return JSON.stringify(v);
+}

package/src/index.ts

@@ -19,6 +19,9 @@ export * from './readmodels.js';
 // declared-vs-live reconciliation, shared by the control-plane apply path and
 // the CLI (`vxil plan/diff/push`), so the two push paths can never diverge.
 export * from './apiState.js';
+// Key-order-insensitive JSON: the one declared-vs-stored manifest compare
+// (control-plane shallowDiff, CLI diffManifest).
+export * from './canonicalJson.js';
 
 // TypeBox validates `format:` only for registered formats — register the ones
 // our schemas use (pragmatic RFC-lite email check; providers do the real one).
@@ -2377,7 +2380,7 @@ export function validateFeatureConfig(feature: string, raw: unknown): ConfigVali
     const v = withDefaults as {
       agents?: Record<string, {
         actions?: { mode?: string; allow?: Record<string, unknown> };
-        guardrails?: { allowGuest?: boolean; guestToolAllow?: string[] };
+        guardrails?: { allowGuest?: boolean; guestToolAllow?: string[]; rateLimitPerUserPerDay?: number };
       }>;
       widget?: { requireAuth?: boolean };
     };
@@ -2386,7 +2389,14 @@ export function validateFeatureConfig(feature: string, raw: unknown): ConfigVali
     for (const [id, agent] of Object.entries(v.agents ?? {})) {
       const allow = agent.actions?.allow ?? {};
       const guestAllow = agent.guardrails?.guestToolAllow ?? [];
-      if (agent.guardrails?.allowGuest === true) anyGuestAgent = true;
+      if (agent.guardrails?.allowGuest === true) {
+        anyGuestAgent = true;
+        // Guests share ONE tenant-wide bucket that spends the tenant's own AI
+        // key: an unlimited (0) daily cap is never allowed alongside them.
+        if (agent.guardrails.rateLimitPerUserPerDay === 0) {
+          errs.push(`/agents/${id}/guardrails/rateLimitPerUserPerDay: 0 (unlimited) is not allowed with allowGuest: true — set a finite daily cap (guests share one tenant-wide bucket)`);
+        }
+      }
       if (knownMcpTools) {
         for (const tool of Object.keys(allow)) {
           if (!knownMcpTools.has(tool)) {