@vxil/feature-configs 0.1.0

package/src/index.test.ts

@@ -0,0 +1,739 @@
+import { describe, expect, it } from 'vitest';
+import {
+  CONFIG_FLAG_CAP,
+  CopilotConfigSchema,
+  FEATURE_SCHEMAS,
+  NotificationsConfigSchema,
+  countLeaves,
+  setKnownMcpTools,
+  validateFeatureConfig,
+} from './index.js';
+// The LIVE mcp catalog (zero-import pure data) — the same relative-import
+// convention as packages/cli/src/mcp.ts. Test-only: the publish build
+// (tsconfig.build.json) excludes tests, so rootDir stays clean.
+import { TOOLS } from '../../../workers/mcp-v1/src/tools.js';
+
+describe('15-flag cap analyzer (architecture §6)', () => {
+  it('notifications schema has 14 leaves — under the cap', () => {
+    expect(countLeaves(NotificationsConfigSchema)).toBe(14);
+    expect(countLeaves(NotificationsConfigSchema)).toBeLessThanOrEqual(CONFIG_FLAG_CAP);
+  });
+
+  it('EVERY registered feature schema is ≤ 15 leaves (the CI gate)', () => {
+    for (const [feature, schema] of Object.entries(FEATURE_SCHEMAS)) {
+      expect(countLeaves(schema), `${feature} exceeds the flag cap`).toBeLessThanOrEqual(
+        CONFIG_FLAG_CAP,
+      );
+    }
+  });
+
+  it('every shipped feature has a registered config schema (typebox-config-required)', () => {
+    const SHIPPED_FEATURES = ['notifications', 'jobs', 'auth'];
+    for (const f of SHIPPED_FEATURES) {
+      expect(FEATURE_SCHEMAS[f], `feature '${f}' has no TypeBox config schema`).toBeDefined();
+    }
+  });
+
+  it('auth schema sits AT the cap (optional bags = 1 leaf each)', () => {
+    // enabled(1) + methods(6) + providers(1) + session(1) + password(1)
+    // + emailVerification(1) + magicLink(1) + otp(1) + anonymous(1)
+    // + orgClaims(1) = 15. The OTP/anonymous/orgClaims wave funded itself by
+    // collapsing session/password to optional bags and dropping the
+    // consumer-less emailVerification.tokenTtlHours (same precedent as the
+    // dropped `redirects` block). The cap check is `>`, so 15 passes.
+    expect(countLeaves(FEATURE_SCHEMAS['auth']!)).toBe(15);
+    expect(countLeaves(FEATURE_SCHEMAS['auth']!)).toBeLessThanOrEqual(CONFIG_FLAG_CAP);
+  });
+
+  it('files schema is 14 leaves after the ttl/extractText optional bags', () => {
+    expect(countLeaves(FEATURE_SCHEMAS['files']!)).toBe(14);
+    expect(countLeaves(FEATURE_SCHEMAS['files']!)).toBeLessThanOrEqual(CONFIG_FLAG_CAP);
+  });
+
+  it('jobs schema is 13 leaves (generation gains reserve caps: +2 = 6 generation leaves)', () => {
+    // enabled(1) + retry(1) + retention(2) + dlqDailyQuota(1) + schedules(1)
+    // + concurrency(1) + generation(6: maxConcurrent, defaultTimeoutMs,
+    // maxTimeoutMs, pollMaxAttempts, maxReserveCredits, maxOutstandingReserveCredits)
+    // = 13, with 2 leaves of headroom under the cap.
+    expect(countLeaves(FEATURE_SCHEMAS['jobs']!)).toBe(13);
+    expect(countLeaves(FEATURE_SCHEMAS['jobs']!)).toBeLessThanOrEqual(CONFIG_FLAG_CAP);
+  });
+
+  it('vector-search schema is 14 leaves (rerank optional object +1, sync array +1)', () => {
+    expect(countLeaves(FEATURE_SCHEMAS['vector-search']!)).toBe(14);
+    expect(countLeaves(FEATURE_SCHEMAS['vector-search']!)).toBeLessThanOrEqual(CONFIG_FLAG_CAP);
+  });
+
+  it('ai schema is exactly 15 leaves — providers.compat (Optional object) counts as ONE; ZERO headroom', () => {
+    // enabled + defaultProvider + 3 keyRefs + compat(1) + defaults(3) + cache(1)
+    // + limits(2) + streaming(3) = 15. Any future ai knob must ride inside
+    // compat (free) or another optional object.
+    expect(countLeaves(FEATURE_SCHEMAS['ai']!)).toBe(15);
+    expect(countLeaves(FEATURE_SCHEMAS['ai']!)).toBeLessThanOrEqual(CONFIG_FLAG_CAP);
+  });
+});
+
+describe('ai config — compat.openaiBaseUrl write-time validation', () => {
+  it('accepts a public https base + an openrouter default provider', () => {
+    const v = validateFeatureConfig('ai', {
+      defaultProvider: 'openrouter',
+      providers: { compat: { openrouterKeyRef: 'secret:openrouter', openaiBaseUrl: 'https://api.deepseek.com/v1' } },
+    });
+    expect(v.ok).toBe(true);
+    const manifest = v.value as { providers: { compat?: { openrouterKeyRef?: string } } };
+    expect(manifest.providers.compat?.openrouterKeyRef).toBe('secret:openrouter');
+  });
+
+  it('rejects http://, private-IP and internal-host bases before they can publish', () => {
+    for (const bad of ['http://api.example.com/v1', 'https://10.1.2.3/v1', 'https://metadata.google.internal/v1', 'https://localhost:8080/v1']) {
+      const v = validateFeatureConfig('ai', { providers: { compat: { openaiBaseUrl: bad } } });
+      expect(v.ok, bad).toBe(false);
+      expect(v.errors?.[0]).toContain('/providers/compat/openaiBaseUrl');
+    }
+  });
+
+  it('defaults leave compat absent (the optional-object leaf is free until used)', () => {
+    const v = validateFeatureConfig('ai', {});
+    expect(v.ok).toBe(true);
+    expect((v.value as { providers: { compat?: unknown } }).providers.compat).toBeUndefined();
+  });
+});
+
+describe('validateFeatureConfig', () => {
+  const minimal = {
+    fromEmail: 'noreply@acme.com',
+    resendApiKeyRef: 'secret:resend_api_key',
+  };
+
+  it('accepts a minimal config and applies defaults', () => {
+    const r = validateFeatureConfig('notifications', minimal);
+    expect(r.ok).toBe(true);
+    const v = r.value as Record<string, unknown>;
+    expect(v.enabled).toBe(true);
+    expect(v.provider).toBe('resend');
+    expect((v.retry as Record<string, unknown>).maxAttempts).toBe(5);
+    expect((v.rateLimit as Record<string, unknown>).perTenantSec).toBe(50);
+  });
+
+  it('rejects a malformed fromEmail', () => {
+    const r = validateFeatureConfig('notifications', { ...minimal, fromEmail: 'not-an-email' });
+    expect(r.ok).toBe(false);
+    expect(r.errors.join(' ')).toContain('fromEmail');
+  });
+
+  it('rejects retry.maxAttempts out of range', () => {
+    const r = validateFeatureConfig('notifications', {
+      ...minimal,
+      retry: { maxAttempts: 99, backoff: 'exponential' },
+    });
+    expect(r.ok).toBe(false);
+  });
+
+  it('rejects an unknown feature', () => {
+    const r = validateFeatureConfig('telepathy', { enabled: true });
+    expect(r.ok).toBe(false);
+    expect(r.errors[0]).toContain('unknown feature');
+  });
+
+  it('rejects an unknown provider', () => {
+    const r = validateFeatureConfig('notifications', { ...minimal, provider: 'sendgrid' });
+    expect(r.ok).toBe(false);
+  });
+
+  it("provider 'mock' needs no resendApiKeyRef (zero-config); provider 'resend' still requires it", () => {
+    const mock = validateFeatureConfig('notifications', {
+      fromEmail: 'noreply@acme.com', provider: 'mock', inboxEnabled: true,
+    });
+    expect(mock.ok).toBe(true);
+
+    const resendNoRef = validateFeatureConfig('notifications', {
+      fromEmail: 'noreply@acme.com', provider: 'resend',
+    });
+    expect(resendNoRef.ok).toBe(false);
+    expect(resendNoRef.errors.join(' ')).toContain('resendApiKeyRef');
+  });
+
+  it('strips unknown top-level AND nested keys so they are never persisted (audit #112/#118)', () => {
+    const r = validateFeatureConfig('notifications', {
+      ...minimal,
+      bogusTopLevel: 'evil',
+      retry: { maxAttempts: 3, backoff: 'linear', sneaky: 'nope' },
+    });
+    expect(r.ok).toBe(true);
+    const v = r.value as Record<string, unknown>;
+    // declared keys survive (incl. materialized defaults)
+    expect(v.fromEmail).toBe('noreply@acme.com');
+    expect((v.retry as Record<string, unknown>).maxAttempts).toBe(3);
+    // unknown keys at every depth are removed — the stored manifest is closed
+    expect(v).not.toHaveProperty('bogusTopLevel');
+    expect(v.retry).not.toHaveProperty('sneaky');
+  });
+
+  it('auth: accepts apple + facebook provider config blocks + method toggles (§6.4)', () => {
+    const r = validateFeatureConfig('auth', {
+      methods: { google: false, github: false, apple: true, facebook: true },
+      providers: {
+        apple: {
+          servicesId: 'com.acme.web',
+          teamId: 'TEAM123456',
+          keyId: 'KEY7890AB',
+          p8KeyRef: 'secret:apple_signin_p8',
+        },
+        facebook: {
+          clientIdRef: 'secret:facebook_app_id',
+          clientSecretRef: 'secret:facebook_app_secret',
+        },
+      },
+    });
+    expect(r.ok).toBe(true);
+    const v = r.value as { providers?: Record<string, Record<string, unknown>> };
+    // the apple/facebook BYO refs survive Value.Clean (declared → persisted)
+    expect(v.providers?.apple).toEqual({
+      servicesId: 'com.acme.web',
+      teamId: 'TEAM123456',
+      keyId: 'KEY7890AB',
+      p8KeyRef: 'secret:apple_signin_p8',
+    });
+    expect(v.providers?.facebook).toEqual({
+      clientIdRef: 'secret:facebook_app_id',
+      clientSecretRef: 'secret:facebook_app_secret',
+    });
+    // The enable toggles survive Value.Clean — the regression that made the
+    // shipped oauthCore apple/facebook flow un-enablable via the pipeline.
+    const m = (r.value as { methods: Record<string, boolean> }).methods;
+    expect(m.apple).toBe(true);
+    expect(m.facebook).toBe(true);
+  });
+
+  it('files: extractText + ttl round-trip WITHOUT being stripped (the Value.Clean regression)', () => {
+    const r = validateFeatureConfig('files', {
+      extractText: { enabled: true, provider: 'gcv', keyRef: 'secret:ocr_api_key' },
+      ttl: { enabled: true, defaultExpiresInSeconds: 3600 },
+    });
+    expect(r.ok).toBe(true);
+    const v = r.value as {
+      extractText?: Record<string, unknown>;
+      ttl?: Record<string, unknown>;
+    };
+    expect(v.extractText).toMatchObject({
+      enabled: true,
+      provider: 'gcv',
+      keyRef: 'secret:ocr_api_key',
+      // inner defaults materialize on a provided bag
+      asyncOverJobs: true,
+      boundingBoxes: false,
+    });
+    expect(v.ttl).toMatchObject({
+      enabled: true,
+      defaultExpiresInSeconds: 3600,
+      sweepCron: '0 * * * *',
+    });
+    // omitted bags stay omitted (optional — no default:{} materialization)
+    const bare = validateFeatureConfig('files', { enabled: true });
+    expect(bare.ok).toBe(true);
+    expect(bare.value).not.toHaveProperty('extractText');
+    expect(bare.value).not.toHaveProperty('ttl');
+    // unknown providers are rejected, not silently coerced
+    const bad = validateFeatureConfig('files', { extractText: { enabled: true, provider: 'tesseract' } });
+    expect(bad.ok).toBe(false);
+  });
+
+  it('auth: facebook accepts optional audRefs (extra native-aud allow-list)', () => {
+    const r = validateFeatureConfig('auth', {
+      providers: {
+        facebook: {
+          clientIdRef: 'secret:fb_app_id',
+          clientSecretRef: 'secret:fb_app_secret',
+          audRefs: ['secret:fb_ios_client', 'secret:fb_android_client'],
+        },
+      },
+    });
+    expect(r.ok).toBe(true);
+    const v = r.value as { providers?: { facebook?: { audRefs?: string[] } } };
+    expect(v.providers?.facebook?.audRefs).toEqual(['secret:fb_ios_client', 'secret:fb_android_client']);
+  });
+
+  it('auth: apple bundleIds round-trip through validateFeatureConfig (native iOS aud)', () => {
+    // Regression: before the schema carried bundleIds, Value.Clean STRIPPED the
+    // field on publish, so genuine iOS ASAuthorization id_tokens (aud = bundle
+    // id) could never be allow-listed via the pipeline (the worker already
+    // reads providers.apple.bundleIds — oauthCore.ts).
+    const r = validateFeatureConfig('auth', {
+      providers: {
+        apple: {
+          servicesId: 'com.acme.web', teamId: 'TEAM123456', keyId: 'KEY7890AB',
+          p8KeyRef: 'secret:apple_p8', bundleIds: ['com.acme.app', 'com.acme.app.dev'],
+        },
+      },
+    });
+    expect(r.ok).toBe(true);
+    const v = r.value as { providers?: { apple?: { bundleIds?: string[] } } };
+    expect(v.providers?.apple?.bundleIds).toEqual(['com.acme.app', 'com.acme.app.dev']);
+  });
+
+  it('auth: otp/anonymous/orgClaims optional bags round-trip; session/password stay materialized', () => {
+    const r = validateFeatureConfig('auth', {
+      otp: { enabled: true, codeTtlMinutes: 5 },
+      anonymous: { enabled: true },
+      orgClaims: { enabled: true },
+    });
+    expect(r.ok).toBe(true);
+    const v = r.value as Record<string, unknown>;
+    // provided bags survive Value.Clean with inner defaults materialized
+    expect(v.otp).toEqual({ enabled: true, codeTtlMinutes: 5, maxAttempts: 5, resendCooldownSec: 60 });
+    expect(v.anonymous).toEqual({ enabled: true });
+    expect(v.orgClaims).toEqual({ enabled: true });
+    // session/password are optional bags but keep `{ default: {} }`, so a bare
+    // publish still materializes the knobs the worker reads (back-compat).
+    expect(v.session).toEqual({ ttlMinutes: 60, refreshTtlDays: 30 });
+    expect(v.password).toEqual({ minLength: 8, requireMixed: false });
+    // tokenTtlHours is GONE (consumer-less — dropped for cap headroom)
+    expect(v.emailVerification).toEqual({ required: false });
+
+    // omitted new bags stay omitted (absent = disabled at the worker gate)
+    const bare = validateFeatureConfig('auth', {});
+    expect(bare.ok).toBe(true);
+    expect(bare.value).not.toHaveProperty('otp');
+    expect(bare.value).not.toHaveProperty('anonymous');
+    expect(bare.value).not.toHaveProperty('orgClaims');
+  });
+
+  it('auth: otp knob bounds are enforced (maxAttempts 3..10)', () => {
+    expect(validateFeatureConfig('auth', { otp: { enabled: true, maxAttempts: 2 } }).ok).toBe(false);
+    expect(validateFeatureConfig('auth', { otp: { enabled: true, maxAttempts: 11 } }).ok).toBe(false);
+    expect(validateFeatureConfig('auth', { otp: { enabled: true, maxAttempts: 10 } }).ok).toBe(true);
+  });
+
+  it('functions: an authHook binding is accepted; a bad event is rejected', () => {
+    const fn = (bindings: unknown[]) => ({
+      functions: { provision: { scriptRef: 'fn-t-provision-abc', bindings } },
+    });
+    const okCfg = validateFeatureConfig('functions', fn([{ kind: 'authHook' }]));
+    expect(okCfg.ok).toBe(true);
+    const explicit = validateFeatureConfig('functions', fn([{ kind: 'authHook', event: 'user.created' }]));
+    expect(explicit.ok).toBe(true);
+    const bad = validateFeatureConfig('functions', fn([{ kind: 'authHook', event: 'user.deleted' }]));
+    expect(bad.ok).toBe(false);
+    expect(bad.errors.join(' ')).toContain("must be 'user.created'");
+  });
+
+  it('functions: DENY_FUNCTION_SCOPES rejects cross-tenant/self-integrity scopes but ALLOWS business scopes', () => {
+    const fn = (scopes: string[]) => ({ functions: { f: { scriptRef: 'fn-t-f-abc', scopes } } });
+    // ALLOWED — legitimate function business actions (checkout saga, email, user
+    // mgmt, fn→fn composition).
+    for (const s of ['payments:write', 'notifications:send', 'users:write', 'users:read', 'cms:write', 'functions:invoke']) {
+      expect(validateFeatureConfig('functions', fn([s])).ok, `expected '${s}' allowed`).toBe(true);
+    }
+    // DENIED — cross-tenant (admin/*) + self-integrity (features:write/functions:write/secrets:write).
+    for (const s of ['admin', '*', 'features:write', 'functions:write', 'secrets:write']) {
+      const r = validateFeatureConfig('functions', fn([s]));
+      expect(r.ok, `expected '${s}' denied`).toBe(false);
+      expect(r.errors.join(' ')).toContain('never grantable');
+    }
+  });
+
+  it('auth: rejects an apple block missing a required field (teamId)', () => {
+    const r = validateFeatureConfig('auth', {
+      providers: {
+        apple: { servicesId: 'com.acme.web', keyId: 'KEY7890AB', p8KeyRef: 'secret:apple_p8' },
+      },
+    });
+    expect(r.ok).toBe(false);
+    expect(r.errors.join(' ')).toContain('teamId');
+  });
+
+  it('auth: strips an unknown provider key (config is closed — only the 4 known providers)', () => {
+    const r = validateFeatureConfig('auth', {
+      providers: {
+        google: { clientIdRef: 'secret:g_id', clientSecretRef: 'secret:g_secret' },
+        twitter: { clientIdRef: 'secret:x_id', clientSecretRef: 'secret:x_secret' },
+      },
+    });
+    expect(r.ok).toBe(true);
+    const v = r.value as { providers?: Record<string, unknown> };
+    expect(v.providers).toHaveProperty('google');
+    expect(v.providers).not.toHaveProperty('twitter');
+  });
+
+  it('a non-schema key named like a prototype pollutant is dropped, not persisted', () => {
+    // Closing the schema (Value.Clean) means an attacker-supplied own key —
+    // including an own enumerable "__proto__" string key smuggled via JSON —
+    // never reaches the stored manifest. (Deep-merge proto-pollution itself is
+    // guarded in the control-plane merge layer; this asserts the validator
+    // doesn't widen the persisted object.)
+    const raw = JSON.parse(`{"fromEmail":"a@b.c","resendApiKeyRef":"r","__proto__":{"polluted":true}}`) as Record<string, unknown>;
+    const r = validateFeatureConfig('notifications', raw);
+    expect(r.ok).toBe(true);
+    // The persisted manifest is its OWN enumerable keys (what csql.json /
+    // JSON.stringify serialize) — none of them is the smuggled pollutant.
+    const ownKeys = Object.keys(r.value as object);
+    expect(ownKeys).not.toContain('__proto__');
+    expect(ownKeys).not.toContain('polluted');
+    expect(Object.prototype.hasOwnProperty.call(r.value, 'polluted')).toBe(false);
+    expect(JSON.parse(JSON.stringify(r.value)) as Record<string, unknown>).not.toHaveProperty('polluted');
+  });
+});
+
+describe('mcp config: custom tools + prompts (mcp.md §6.5/§11)', () => {
+  it('McpConfigSchema stays at 9 leaves (customTools/prompts are ONE Record leaf each)', () => {
+    expect(countLeaves(FEATURE_SCHEMAS['mcp']!)).toBe(9);
+    expect(countLeaves(FEATURE_SCHEMAS['mcp']!)).toBeLessThanOrEqual(CONFIG_FLAG_CAP);
+  });
+
+  const tool = (over: Record<string, unknown> = {}) => ({
+    customTools: {
+      crm_lookup: {
+        description: 'Look up a CRM contact by email.',
+        url: 'https://api.acme.example/mcp/crm-lookup',
+        ...over,
+      },
+    },
+  });
+
+  it('accepts a well-formed custom tool (config round-trips)', () => {
+    const r = validateFeatureConfig('mcp', tool({
+      inputSchema: { type: 'object', properties: { email: { type: 'string' } } },
+      timeoutMs: 5000,
+    }));
+    expect(r.ok).toBe(true);
+    const v = r.value as { customTools: Record<string, { url: string; timeoutMs: number }> };
+    expect(v.customTools.crm_lookup!.url).toBe('https://api.acme.example/mcp/crm-lookup');
+    expect(v.customTools.crm_lookup!.timeoutMs).toBe(5000);
+  });
+
+  it('rejects a bad tool name, an http:// URL, and internal/private hosts', () => {
+    const badName = validateFeatureConfig('mcp', {
+      customTools: { 'Bad-Name': { description: 'x', url: 'https://ok.example/a' } },
+    });
+    expect(badName.ok).toBe(false);
+    expect(badName.errors.join(' ')).toContain('name must match');
+
+    for (const url of [
+      'http://api.acme.example/hook', // scheme
+      'https://user:pass@api.acme.example/hook', // embedded creds
+      'https://localhost/hook',
+      'https://foo.localhost/hook',
+      'https://db.internal/hook',
+      'https://printer.local/hook',
+      'https://10.1.2.3/hook',
+      'https://169.254.169.254/latest/meta-data',
+      'https://[::1]/hook',
+      'not a url',
+    ]) {
+      const r = validateFeatureConfig('mcp', tool({ url }));
+      expect(r.ok, `should reject ${url}`).toBe(false);
+      expect(r.errors.join(' ')).toContain('/customTools/crm_lookup/url');
+    }
+  });
+
+  it('rejects >32 custom tools and an oversized inputSchema', () => {
+    const many: Record<string, unknown> = {};
+    for (let i = 0; i < 33; i++) {
+      many[`tool_${i}`] = { description: 'x', url: 'https://ok.example/t' };
+    }
+    const over = validateFeatureConfig('mcp', { customTools: many });
+    expect(over.ok).toBe(false);
+    expect(over.errors.join(' ')).toContain('at most 32');
+
+    const fat = validateFeatureConfig('mcp', tool({
+      inputSchema: { type: 'object', description: 'x'.repeat(9000) },
+    }));
+    expect(fat.ok).toBe(false);
+    expect(fat.errors.join(' ')).toContain('8KB');
+  });
+
+  it('prompts: placeholders must be declared arguments; declared-but-unused is fine', () => {
+    const good = validateFeatureConfig('mcp', {
+      prompts: {
+        draft_reply: {
+          description: 'Draft a support reply.',
+          template: 'Reply to {{customer}} about {{topic}}. Be concise.',
+          arguments: [
+            { name: 'customer', required: true },
+            { name: 'topic' },
+            { name: 'unused_extra' }, // allowed
+          ],
+        },
+      },
+    });
+    expect(good.ok).toBe(true);
+
+    const bad = validateFeatureConfig('mcp', {
+      prompts: {
+        draft_reply: { template: 'Reply to {{customer}}.', arguments: [{ name: 'topic' }] },
+      },
+    });
+    expect(bad.ok).toBe(false);
+    expect(bad.errors.join(' ')).toContain('{{customer}}');
+  });
+
+  it('prompts: rejects a bad name and >32 prompts', () => {
+    const badName = validateFeatureConfig('mcp', {
+      prompts: { 'Bad Name': { template: 'x' } },
+    });
+    expect(badName.ok).toBe(false);
+
+    const many: Record<string, unknown> = {};
+    for (let i = 0; i < 33; i++) many[`p_${i}`] = { template: 'x' };
+    const over = validateFeatureConfig('mcp', { prompts: many });
+    expect(over.ok).toBe(false);
+    expect(over.errors.join(' ')).toContain('at most 32');
+  });
+
+  it('a bare mcp config (no customTools/prompts) still validates with defaults', () => {
+    const r = validateFeatureConfig('mcp', { enabled: true });
+    expect(r.ok).toBe(true);
+    expect(r.value).not.toHaveProperty('customTools');
+    expect(r.value).not.toHaveProperty('prompts');
+  });
+});
+
+describe('copilot config (docs/copilot-agents-sku-design.md §4)', () => {
+  it('has exactly 9 leaves — under the cap (agents/allow/collections are DATA)', () => {
+    expect(countLeaves(CopilotConfigSchema)).toBe(9);
+    expect(countLeaves(CopilotConfigSchema)).toBeLessThanOrEqual(CONFIG_FLAG_CAP);
+  });
+
+  it('quickstart minimal body materializes a valid zero-agent manifest', () => {
+    const r = validateFeatureConfig('copilot', { enabled: true });
+    expect(r.ok).toBe(true);
+    const v = r.value as Record<string, unknown>;
+    expect(v.agents).toEqual({});
+    expect((v.widget as Record<string, unknown>).enabled).toBe(false);
+    expect((v.limits as Record<string, unknown>).consumeCredits).toBe(false);
+  });
+
+  // NOTE: runs BEFORE the setKnownMcpTools registration below (vitest executes
+  // tests in file order) — asserts the published-package posture where no
+  // catalog is available and the name-existence rule is skipped.
+  it('without a registered catalog, unknown tool names pass (name rule skipped)', () => {
+    const r = validateFeatureConfig('copilot', {
+      agents: { a: { name: 'A', actions: { mode: 'actions', allow: { not_a_tool: {} } } } },
+    });
+    expect(r.ok).toBe(true);
+  });
+
+  it('with the live catalog registered, an unknown allow key is rejected; real names pass', () => {
+    setKnownMcpTools(TOOLS.map((t) => t.name));
+    const bad = validateFeatureConfig('copilot', {
+      agents: { a: { name: 'A', actions: { mode: 'actions', allow: { not_a_tool: {} } } } },
+    });
+    expect(bad.ok).toBe(false);
+    expect(bad.errors.join(' ')).toContain('not_a_tool');
+
+    const good = validateFeatureConfig('copilot', {
+      agents: {
+        a: {
+          name: 'A',
+          actions: { mode: 'actions', allow: { cms_query_items: {}, cms_create_item: { requireConfirm: true } } },
+        },
+      },
+    });
+    expect(good.ok).toBe(true);
+  });
+
+  it('guestToolAllow must be a subset of actions.allow', () => {
+    const r = validateFeatureConfig('copilot', {
+      agents: {
+        a: {
+          name: 'A',
+          actions: { mode: 'actions', allow: { cms_query_items: {} } },
+          guardrails: { allowGuest: true, guestToolAllow: ['cms_create_item'] },
+        },
+      },
+    });
+    expect(r.ok).toBe(false);
+    expect(r.errors.join(' ')).toContain('not in actions.allow');
+  });
+
+  it('a non-empty guestToolAllow requires allowGuest: true', () => {
+    const r = validateFeatureConfig('copilot', {
+      agents: {
+        a: {
+          name: 'A',
+          actions: { mode: 'actions', allow: { cms_query_items: {} } },
+          guardrails: { allowGuest: false, guestToolAllow: ['cms_query_items'] },
+        },
+      },
+    });
+    expect(r.ok).toBe(false);
+    expect(r.errors.join(' ')).toContain('allowGuest');
+  });
+
+  it('widget.requireAuth=false requires ≥1 agent with allowGuest', () => {
+    const bad = validateFeatureConfig('copilot', {
+      agents: { a: { name: 'A' } },
+      widget: { enabled: true, requireAuth: false, allowedOrigins: ['https://example.com'] },
+    });
+    expect(bad.ok).toBe(false);
+    expect(bad.errors.join(' ')).toContain('allowGuest');
+
+    const good = validateFeatureConfig('copilot', {
+      agents: { a: { name: 'A', guardrails: { allowGuest: true } } },
+      widget: { enabled: true, requireAuth: false, allowedOrigins: ['https://example.com'] },
+    });
+    expect(good.ok).toBe(true);
+  });
+
+  it("escalation.handler 'notifications' requires notifyTemplate", () => {
+    const bad = validateFeatureConfig('copilot', {
+      agents: {},
+      escalation: { enabled: true, handler: 'notifications' },
+    });
+    expect(bad.ok).toBe(false);
+    expect(bad.errors.join(' ')).toContain('notifyTemplate');
+
+    const good = validateFeatureConfig('copilot', {
+      agents: {},
+      escalation: { enabled: true, handler: 'notifications', notifyTemplate: 'escalation' },
+    });
+    expect(good.ok).toBe(true);
+  });
+});
+
+// fn-online-typed-io: the per-function `signature` (Level-1 typed I/O) is
+// DECLARED schema data inside the functions Type.Record value — Value.Clean
+// must keep it, the size guard must bound it, and the leaf count must not move.
+describe('functions config — signature (Level-1 typed I/O)', () => {
+  const entry = (extra: Record<string, unknown> = {}) => ({
+    enabled: true,
+    functions: {
+      hello: { scriptRef: 'fn-t-hello-0123456789ab', ...extra },
+    },
+  });
+
+  it('signature survives validateFeatureConfig (Value.Clean keeps declared keys)', () => {
+    const sig = { input: { name: 'string' }, output: { ok: 'boolean' } };
+    const r = validateFeatureConfig('functions', entry({ signature: sig }));
+    expect(r.ok).toBe(true);
+    const fns = (r.value as { functions: Record<string, { signature?: unknown }> }).functions;
+    expect(fns.hello!.signature).toEqual(sig);
+  });
+
+  it('rejects an oversize signature (manifest bloat guard), naming the path', () => {
+    const big = { input: { blob: 'x'.repeat(9_000) } };
+    const r = validateFeatureConfig('functions', entry({ signature: big }));
+    expect(r.ok).toBe(false);
+    expect(r.errors.join(' ')).toContain('/functions/hello/signature');
+  });
+
+  it('functions schema stays at 7 leaves (signature is DATA in the map)', () => {
+    expect(countLeaves(FEATURE_SCHEMAS['functions']!)).toBe(7);
+  });
+});
+
+describe('cms-rel config: readModels + cdc (cms-relational-depth §3/§4)', () => {
+  it('cms schema lands at 15 leaves (relations +3, readModels +1, cdc +1, strictEndUserScope +1) — AT the cap', () => {
+    expect(countLeaves(FEATURE_SCHEMAS['cms']!)).toBe(15);
+    expect(countLeaves(FEATURE_SCHEMAS['cms']!)).toBeLessThanOrEqual(CONFIG_FLAG_CAP);
+  });
+
+  it('relations block defaults + range enforcement', () => {
+    const r = validateFeatureConfig('cms', {});
+    expect(r.ok).toBe(true);
+    const rel = (r.value as { relations: Record<string, number> }).relations;
+    expect(rel).toEqual({ maxExpandDepth: 1, maxExpandFields: 5, maxComputedFieldsPerCollection: 10 });
+    expect(validateFeatureConfig('cms', { relations: { maxExpandDepth: 3 } }).ok).toBe(false);
+  });
+
+  const Z1 = {
+    readModels: {
+      discover_featured: {
+        collection: 'posts', kind: 'rank',
+        spec: {
+          groupBy: 'channel', metric: { fn: 'sum', field: 'view_count' },
+          rank: 'percent_rank', direction: 'desc',
+          filter: { $status: 'published', 'channel.visibility': 'public' },
+          window: { field: 'created_at', sinceDays: 30 },
+        },
+        materialize: { cron: '0 3 * * *', to: 'discover_rollup' },
+      },
+    },
+  };
+
+  it('accepts the Zaawi Z1 declared read-model (rank + join filter + cron)', () => {
+    const r = validateFeatureConfig('cms', Z1);
+    expect(r.errors ?? []).toEqual([]);
+    expect(r.ok).toBe(true);
+    // Value.Clean must NOT hollow out the opaque spec (the functions signature idiom)
+    const kept = (r.value as { readModels: Record<string, { spec: Record<string, unknown> }> })
+      .readModels.discover_featured!.spec;
+    expect(kept.groupBy).toBe('channel');
+    expect((kept.filter as Record<string, unknown>)['channel.visibility']).toBe('public');
+  });
+
+  it('accepts a Z3-style aggregate read-model', () => {
+    const r = validateFeatureConfig('cms', {
+      readModels: {
+        daily_bookings: {
+          collection: 'bookings', kind: 'aggregate',
+          spec: {
+            aggregates: [{ fn: 'count' }, { fn: 'sum', field: 'amount', as: 'revenue' }],
+            groupBy: ['space'], window: { field: 'created_at', sinceDays: 1 },
+          },
+          materialize: { cron: '0 2 * * *', to: 'analytics_daily' },
+        },
+      },
+    });
+    expect(r.errors ?? []).toEqual([]);
+  });
+
+  it('rejects fn/rank outside the allow-lists at CONFIG-WRITE time', () => {
+    const bad = (spec: object, kind = 'aggregate') => validateFeatureConfig('cms', {
+      readModels: { m: { collection: 'c', kind, spec, materialize: { cron: '* * * * *', to: 't' } } },
+    });
+    expect(bad({ aggregates: [{ fn: 'array_agg', field: 'x' }] }).ok).toBe(false);
+    expect(bad({ groupBy: 'x', rank: 'ntile' }, 'rank').ok).toBe(false);
+    expect(bad({ groupBy: 'x', rank: 'rank() OVER (ROWS BETWEEN 1 PRECEDING AND 1 FOLLOWING)' }, 'rank').ok).toBe(false);
+  });
+
+  it('rejects structural violations: arity, window, spec size, names, cron, limit smuggling', () => {
+    const rm = (over: object) => validateFeatureConfig('cms', {
+      readModels: {
+        m: {
+          collection: 'c', kind: 'aggregate', spec: { aggregates: [{ fn: 'count' }] },
+          materialize: { cron: '0 2 * * *', to: 't' }, ...over,
+        },
+      },
+    });
+    expect(rm({ spec: { aggregates: [{ fn: 'count' }], groupBy: ['a', 'b', 'c'] } }).ok).toBe(false);
+    expect(rm({ spec: { aggregates: [{ fn: 'count' }], window: { field: 'x', sinceDays: 999 } } }).ok).toBe(false);
+    expect(rm({ spec: { aggregates: [{ fn: 'count' }], limit: 10 } }).ok).toBe(false);
+    expect(rm({ spec: { aggregates: [{ fn: 'count' }], filter: { 'a.b.c': 1 } } }).ok).toBe(false);
+    expect(rm({ spec: { aggregates: [{ fn: 'count' }], filter: { 'a.x': 1, 'b.y': 2 } } }).ok).toBe(false);
+    expect(rm({ materialize: { cron: 'not-a-cron', to: 't' } }).ok).toBe(false);
+    expect(rm({ materialize: { cron: '0 2 * * *', to: 'Bad Slug!' } }).ok).toBe(false);
+    // an over-large serialized spec
+    expect(rm({ spec: { aggregates: [{ fn: 'count' }], filter: { note: 'x'.repeat(5000) } } }).ok).toBe(false);
+    // bad read-model name
+    const r = validateFeatureConfig('cms', {
+      readModels: { 'Bad Name': { collection: 'c', kind: 'aggregate', spec: { aggregates: [{ fn: 'count' }] } } },
+    });
+    expect(r.ok).toBe(false);
+  });
+
+  it('caps the bag at 20 read-models', () => {
+    const bag: Record<string, unknown> = {};
+    for (let i = 0; i < 21; i++) {
+      bag[`m${i}`] = { collection: 'c', kind: 'aggregate', spec: { aggregates: [{ fn: 'count' }] } };
+    }
+    expect(validateFeatureConfig('cms', { readModels: bag }).ok).toBe(false);
+  });
+
+  it('cdc: accepts a rule bag; rejects bad channel/events/payload and >25 rules', () => {
+    const ok = validateFeatureConfig('cms', {
+      cdc: {
+        posts_live: { collection: 'posts', channel: 'posts:live', events: ['created', 'updated'], payload: 'ids' },
+      },
+    });
+    expect(ok.errors ?? []).toEqual([]);
+    const bad = (rule: object) => validateFeatureConfig('cms', { cdc: { r: rule } });
+    expect(bad({ collection: 'posts', channel: 'has spaces!' }).ok).toBe(false);
+    expect(bad({ collection: 'posts', channel: 'c', events: ['archived'] }).ok).toBe(false);
+    expect(bad({ collection: 'posts', channel: 'c', payload: 'everything' }).ok).toBe(false);
+    expect(bad({ channel: 'c' }).ok).toBe(false);
+    const bag: Record<string, unknown> = {};
+    for (let i = 0; i < 26; i++) bag[`r${i}`] = { collection: 'c', channel: `ch${i}` };
+    expect(validateFeatureConfig('cms', { cdc: bag }).ok).toBe(false);
+  });
+});