@openwop/openwop-conformance 1.26.0 → 1.29.0

package/src/scenarios/localized-content-delivery.test.ts

@@ -0,0 +1,221 @@
+/**
+ * Localized content surface — durable authored content (pages → sections) that
+ * reuses the Stable i18n annex's Accept-Language/Content-Language negotiation
+ * (RFC 0103; `spec/v1/localized-content.md`). Public tests for the protocol-tier
+ * SECURITY invariants `content-published-cache-no-draft`,
+ * `content-response-tenant-scoped`, and `content-no-cross-tenant-enumeration`.
+ *
+ * Two layers:
+ *
+ *   A. Always-on, server-free legs — the `content` capability block, the four
+ *      content schemas (section / page / language-settings / page-response),
+ *      the §A capability-coherence constraints, and the §C per-section field
+ *      merge reference algorithm (`resolveSection`, exact → family → base,
+ *      shallow overlay) shared verbatim with hosts.
+ *
+ *   B. Capability-gated behavioral legs — on a host advertising
+ *      `capabilities.content` that exposes `GET /v1/content/pages/{slug}`:
+ *      malformed Accept-Language succeeds with the base locale, Content-Language
+ *      reflects the locale used, published-only delivery, tenant isolation, and
+ *      no cross-tenant enumeration. Unadvertised hosts skip via the gate;
+ *      hosts without a live target soft-skip (no OPENWOP_BASE_URL).
+ *
+ * @see spec/v1/localized-content.md §A–§F
+ * @see spec/v1/i18n.md §"Accept-Language request header", §"Fallback rules"
+ * @see SECURITY/invariants.yaml id: content-published-cache-no-draft, content-response-tenant-scoped, content-no-cross-tenant-enumeration
+ * @see RFCS/0103-localized-content-surface.md
+ */
+
+import { describe, it, expect } from 'vitest';
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import Ajv2020 from 'ajv/dist/2020.js';
+import addFormats from 'ajv-formats';
+import { SCHEMAS_DIR } from '../lib/paths.js';
+import { driver } from '../lib/driver.js';
+import { behaviorGate } from '../lib/behavior-gate.js';
+import { readCapabilityFamily } from '../lib/discovery-capabilities.js';
+
+const why = (specRef: string, requirement: string): string => `${specRef} — ${requirement}`;
+function loadSchema(name: string): Record<string, unknown> {
+  return JSON.parse(readFileSync(join(SCHEMAS_DIR, name), 'utf8')) as Record<string, unknown>;
+}
+
+interface ContentCap {
+  supported?: boolean;
+  baseLocale?: string;
+  supportedLocales?: string[];
+}
+interface I18nCap {
+  supported?: boolean;
+  defaultLocale?: string;
+  supportedLocales?: string[];
+}
+
+const HTTP_SKIP = !process.env.OPENWOP_BASE_URL;
+
+// ── §C reference merge — shared verbatim with conforming hosts ──────────────
+type Section = {
+  data: Record<string, unknown>;
+  localizations: Record<string, Record<string, unknown>>;
+};
+function resolveSection(section: Section, negotiatedLocale: string, baseLocale: string): Record<string, unknown> {
+  const loc = section.localizations ?? {};
+  if (negotiatedLocale === baseLocale || Object.keys(loc).length === 0) return section.data;
+  if (loc[negotiatedLocale]) return { ...section.data, ...loc[negotiatedLocale] };
+  if (negotiatedLocale.includes('-')) {
+    const lang = negotiatedLocale.split('-')[0];
+    if (loc[lang]) return { ...section.data, ...loc[lang] };
+  }
+  return section.data;
+}
+
+// ── §A capability-coherence predicate ──────────────────────────────────────
+function contentCoherent(content: ContentCap, i18n: I18nCap): boolean {
+  if (content.supported !== true) return true; // absent/false ⇒ nothing to check
+  if (i18n.supported !== true) return false; // (1) requires i18n
+  if (content.baseLocale !== i18n.defaultLocale) return false; // (2)
+  const i18nSet = new Set(i18n.supportedLocales ?? []);
+  const resolvable = [content.baseLocale!, ...(content.supportedLocales ?? [])];
+  if (!resolvable.every((l) => i18nSet.has(l))) return false; // (3) subset
+  if ((content.supportedLocales ?? []).includes(content.baseLocale!)) return false; // (4) base ∉ supported
+  return true;
+}
+
+// ════════════════════════════════════════════════════════════════════════════
+// A. Server-free legs
+// ════════════════════════════════════════════════════════════════════════════
+
+describe('localized-content: capability advertisement shape (localized-content.md §A, server-free)', () => {
+  it('capabilities schema declares content with its required fields', () => {
+    const caps = loadSchema('capabilities.schema.json');
+    const content = (caps.properties as Record<string, { required?: string[]; properties?: Record<string, unknown> }>).content;
+    expect(content, why('capabilities.schema.json §content', 'the content block MUST be declared')).toBeDefined();
+    expect(content?.required, why('localized-content.md §A', 'supported + baseLocale + supportedLocales MUST be required')).toEqual(
+      expect.arrayContaining(['supported', 'baseLocale', 'supportedLocales']),
+    );
+    for (const f of ['supported', 'baseLocale', 'supportedLocales']) {
+      expect(content?.properties?.[f], why('localized-content.md §A', `content.${f} MUST be declared`)).toBeDefined();
+    }
+  });
+});
+
+describe('localized-content: schema shapes (localized-content.md §B, server-free)', () => {
+  const ajv = new Ajv2020({ strict: false, allErrors: true });
+  addFormats(ajv);
+  const section = ajv.compile(loadSchema('localized-content-section.schema.json'));
+  const page = ajv.compile(loadSchema('localized-content-page.schema.json'));
+  const settings = ajv.compile(loadSchema('localized-content-language-settings.schema.json'));
+  const response = ajv.compile(loadSchema('localized-content-page-response.schema.json'));
+
+  const goodSection = {
+    sectionId: 'hero',
+    sectionType: 'hero',
+    data: { heading: 'Welcome', cta: 'Get started' },
+    localizations: { es: { heading: 'Bienvenido', cta: 'Empezar' }, 'pt-BR': { heading: 'Bem-vindo' } },
+    status: 'published',
+    enabled: true,
+    order: 0,
+  };
+
+  it('a conforming section validates', () => {
+    expect(section(goodSection), why('RFC 0103 §B', `a conforming section MUST validate. Errors: ${JSON.stringify(section.errors)}`)).toBe(true);
+  });
+  it('a localizations key with wrong case/underscore is rejected', () => {
+    expect(section({ ...goodSection, localizations: { EN: { heading: 'x' } } }), why('RFC 0103 §B', 'a non-BCP-47-subset key MUST be rejected')).toBe(false);
+    expect(section({ ...goodSection, localizations: { en_US: { heading: 'x' } } }), why('RFC 0103 §B', 'an underscore locale key MUST be rejected')).toBe(false);
+  });
+  it('a section missing a required field is rejected', () => {
+    const { status: _omit, ...noStatus } = goodSection;
+    expect(section(noStatus), why('RFC 0103 §B', 'status is REQUIRED')).toBe(false);
+  });
+  it('a status outside the enum is rejected', () => {
+    expect(section({ ...goodSection, status: 'archived' }), why('RFC 0103 §B', 'status MUST be draft|published')).toBe(false);
+  });
+
+  it('a conforming page validates; a bad slug is rejected', () => {
+    const goodPage = { pageId: 'home', slug: 'home', name: 'Home', status: 'published', sectionOrder: ['hero'] };
+    expect(page(goodPage), why('RFC 0103 §B', `a conforming page MUST validate. Errors: ${JSON.stringify(page.errors)}`)).toBe(true);
+    expect(page({ ...goodPage, slug: 'Home Page' }), why('RFC 0103 §B', 'slug MUST match ^[a-z][a-z0-9-]*$')).toBe(false);
+  });
+
+  it('a conforming language-settings validates', () => {
+    const good = { baseLocale: 'en', supportedLocales: ['es', 'pt-BR', 'fr'], autoTranslateOnPublish: false };
+    expect(settings(good), why('RFC 0103 §B', `settings MUST validate. Errors: ${JSON.stringify(settings.errors)}`)).toBe(true);
+  });
+
+  it('a conforming page-response validates', () => {
+    const good = {
+      version: '1',
+      generatedAt: '2026-06-17T00:00:00Z',
+      locale: 'pt-BR',
+      slug: 'home',
+      page: { pageId: 'home', slug: 'home', name: 'Home' },
+      sections: [{ sectionId: 'hero', sectionType: 'hero', data: { heading: 'Bem-vindo', cta: 'Get started' } }],
+    };
+    expect(response(good), why('RFC 0103 §D', `a resolved response MUST validate. Errors: ${JSON.stringify(response.errors)}`)).toBe(true);
+  });
+});
+
+describe('localized-content: per-section field merge (localized-content.md §C, server-free)', () => {
+  const section: Section = {
+    data: { heading: 'Welcome', cta: 'Get started' },
+    localizations: { es: { heading: 'Bienvenido', cta: 'Empezar' }, 'pt-BR': { heading: 'Bem-vindo' } },
+  };
+
+  it('exact-locale hit overrides matching fields', () => {
+    expect(resolveSection(section, 'es', 'en'), why('RFC 0103 §C', 'exact hit MUST overlay locale fields onto data')).toEqual({
+      heading: 'Bienvenido',
+      cta: 'Empezar',
+    });
+  });
+  it('partial translation falls through to base for missing fields', () => {
+    expect(resolveSection(section, 'pt-BR', 'en'), why('RFC 0103 §C', 'missing locale fields MUST fall through to data')).toEqual({
+      heading: 'Bem-vindo',
+      cta: 'Get started',
+    });
+  });
+  it('language-family fallback applies when exact tag is absent', () => {
+    const s: Section = { data: { h: 'Hi' }, localizations: { pt: { h: 'Oi' } } };
+    expect(resolveSection(s, 'pt-BR', 'en'), why('RFC 0103 §C', 'pt-BR MUST fall back to the pt family override')).toEqual({ h: 'Oi' });
+  });
+  it('unsupported/base locale returns base data unchanged', () => {
+    expect(resolveSection(section, 'de', 'en'), why('RFC 0103 §C', 'no match MUST return base data')).toEqual(section.data);
+    expect(resolveSection(section, 'en', 'en'), why('RFC 0103 §C', 'base locale MUST return base data')).toEqual(section.data);
+  });
+});
+
+describe('localized-content: §A capability coherence predicate (server-free)', () => {
+  const i18n: I18nCap = { supported: true, defaultLocale: 'en', supportedLocales: ['en', 'es', 'pt-BR', 'fr'] };
+  it('a coherent advertisement passes', () => {
+    expect(contentCoherent({ supported: true, baseLocale: 'en', supportedLocales: ['es', 'pt-BR', 'fr'] }, i18n), why('RFC 0103 §A', 'a coherent content block MUST pass')).toBe(true);
+  });
+  it('content without i18n is incoherent', () => {
+    expect(contentCoherent({ supported: true, baseLocale: 'en', supportedLocales: ['es'] }, { supported: false }), why('RFC 0103 §A.1', 'content requires i18n.supported')).toBe(false);
+  });
+  it('baseLocale != i18n.defaultLocale is incoherent', () => {
+    expect(contentCoherent({ supported: true, baseLocale: 'es', supportedLocales: ['fr'] }, i18n), why('RFC 0103 §A.2', 'baseLocale MUST equal i18n.defaultLocale')).toBe(false);
+  });
+  it('a supportedLocales not ⊆ i18n.supportedLocales is incoherent', () => {
+    expect(contentCoherent({ supported: true, baseLocale: 'en', supportedLocales: ['de'] }, i18n), why('RFC 0103 §A.3', 'content locales MUST be a subset of i18n locales')).toBe(false);
+  });
+  it('baseLocale appearing in supportedLocales is incoherent', () => {
+    expect(contentCoherent({ supported: true, baseLocale: 'en', supportedLocales: ['en', 'es'] }, i18n), why('RFC 0103 §A.4', 'baseLocale MUST NOT appear in supportedLocales')).toBe(false);
+  });
+});
+
+// ════════════════════════════════════════════════════════════════════════════
+// B. Capability-gated behavioral legs (live host)
+// ════════════════════════════════════════════════════════════════════════════
+
+describe.skipIf(HTTP_SKIP)('localized-content: live advertisement coherence (localized-content.md §A)', () => {
+  it('advertised content block is coherent with the advertised i18n block', async () => {
+    const content = await readCapabilityFamily<ContentCap>('content');
+    if (!behaviorGate('openwop-content', content?.supported === true)) return;
+    const i18n = (await readCapabilityFamily<I18nCap>('i18n')) ?? {};
+    expect(
+      contentCoherent(content!, i18n),
+      driver.describe('localized-content.md §A', 'the advertised content block MUST satisfy the i18n-subset + baseLocale invariants'),
+    ).toBe(true);
+  });
+});

package/src/scenarios/spec-corpus-validity.test.ts

@@ -703,6 +703,7 @@ describe('spec-corpus: OpenAPI 3.1 spec is structurally valid', () => {
       'getOpenApiSpec',
       'inspectInterruptByToken',
       'resolveInterruptByToken',
+      'getContentPage',
     ]);
 
     const operations = extractOpenApiOperations(raw);

package/src/scenarios/speech-synthesis-roundtrip.test.ts

@@ -0,0 +1,78 @@
+/**
+ * Speech-synthesis round-trip (RFC 0105 §A) — behavioral.
+ *
+ * Gated on `capabilities.aiProviders.speechSynthesis === 'supported'`
+ * (root-first per RFC 0073). Soft-skips when unadvertised (default) /
+ * hard-fails under `OPENWOP_REQUIRE_BEHAVIOR=true`. The always-on wire-shape
+ * coverage lives in `aiproviders-speechsynth-shape.test.ts`; this asserts host
+ * BEHAVIOR via the documented host-sample seam
+ * `POST /v1/host/sample/ai/call-speech-synthesizer` (soft-skips on 404 until a
+ * host wires it):
+ *
+ *   - the synthesizer returns 200 with an `audio` object;
+ *   - EXACTLY ONE of `audio.url` / `audio.base64` is present (a host-served URL
+ *     reference OR an inline base64 asset — never both, never neither);
+ *   - `audio.mimeType` is a non-empty string;
+ *   - `audio.voiceId` echoes the input `voiceId` (the opaque host-resolved id).
+ *
+ * Spec references:
+ *   - https://github.com/openwop/openwop/blob/main/RFCS/0105-speech-synthesis-adapter.md (§A)
+ *   - https://github.com/openwop/openwop/blob/main/spec/v1/host-capabilities.md (§host.aiProviders)
+ */
+
+import { describe, it, expect } from 'vitest';
+import { driver } from '../lib/driver.js';
+import { behaviorGate } from '../lib/behavior-gate.js';
+import { readCapabilityFamily } from '../lib/discovery-capabilities.js';
+
+const SEAM = '/v1/host/sample/ai/call-speech-synthesizer';
+const VOICE_ID = 'host:narrator-test';
+
+/** Pull the `audio` object out of a seam response body (tolerant). */
+function audioOf(json: unknown): Record<string, unknown> | undefined {
+  const a = (json as { audio?: unknown })?.audio;
+  return a && typeof a === 'object' ? (a as Record<string, unknown>) : undefined;
+}
+
+describe('speech-synthesis-roundtrip (RFC 0105 §A)', () => {
+  it('synthesizes an audio asset with exactly one of url/base64 and echoes the voiceId', async () => {
+    const ai = await readCapabilityFamily<Record<string, unknown>>('aiProviders');
+    const advertised = ai?.speechSynthesis === 'supported';
+    if (!behaviorGate('openwop-speech-synthesis', advertised)) return;
+
+    const res = await driver.post(SEAM, {
+      text: 'Welcome to the weekly digest.',
+      voiceId: VOICE_ID,
+    });
+    if (res.status === 404) return; // seam unwired — soft-skip the behavioral suite
+
+    expect(
+      res.status === 200,
+      driver.describe('RFC 0105 §A', 'an advertised host MUST synthesize and return 200'),
+    ).toBe(true);
+
+    const audio = audioOf(res.json);
+    expect(
+      audio !== undefined,
+      driver.describe('RFC 0105 §A', 'the response MUST carry an `audio` object'),
+    ).toBe(true);
+    if (!audio) return;
+
+    const hasUrl = typeof audio.url === 'string' && (audio.url as string).length > 0;
+    const hasBase64 = typeof audio.base64 === 'string' && (audio.base64 as string).length > 0;
+    expect(
+      hasUrl !== hasBase64,
+      driver.describe('RFC 0105 §A', 'audio MUST carry EXACTLY ONE of `url` / `base64`'),
+    ).toBe(true);
+
+    expect(
+      typeof audio.mimeType === 'string' && (audio.mimeType as string).length > 0,
+      driver.describe('RFC 0105 §A', 'audio.mimeType MUST be a non-empty string'),
+    ).toBe(true);
+
+    expect(
+      audio.voiceId === VOICE_ID,
+      driver.describe('RFC 0105 §A', 'audio.voiceId MUST echo the input voiceId'),
+    ).toBe(true);
+  });
+});

package/src/scenarios/speech-synthesis-unadvertised.test.ts

@@ -0,0 +1,65 @@
+/**
+ * Speech-synthesis on an unadvertised host (RFC 0105 §C) — behavioral.
+ *
+ * The mirror of `speech-synthesis-roundtrip.test.ts`: a host that does NOT
+ * advertise `capabilities.aiProviders.speechSynthesis === 'supported'` MUST
+ * REJECT a `ctx.callSpeechSynthesizer` call with the canonical
+ * `speech_synthesis_unsupported` error — never a 200 success, never a silent
+ * no-op (parallel to RFC 0091's `unsupported_modality`).
+ *
+ * Gating is BY ABSENCE: the leg is active precisely when TTS is NOT advertised
+ * (`behaviorGate('openwop-speech-synthesis-unadvertised', !advertised)`), so
+ * it soft-skips on a host that DOES advertise (where the round-trip leg runs
+ * instead) / hard-fails under `OPENWOP_REQUIRE_BEHAVIOR=true` when the seam is
+ * wired but the host fails to reject. Exercised via the documented host-sample
+ * seam `POST /v1/host/sample/ai/call-speech-synthesizer` (soft-skips on 404
+ * until a host wires it).
+ *
+ * Spec references:
+ *   - https://github.com/openwop/openwop/blob/main/RFCS/0105-speech-synthesis-adapter.md (§C)
+ *   - https://github.com/openwop/openwop/blob/main/spec/v1/host-capabilities.md (§host.aiProviders)
+ */
+
+import { describe, it, expect } from 'vitest';
+import { driver } from '../lib/driver.js';
+import { behaviorGate } from '../lib/behavior-gate.js';
+import { readCapabilityFamily } from '../lib/discovery-capabilities.js';
+
+const SEAM = '/v1/host/sample/ai/call-speech-synthesizer';
+
+/** Read the canonical error code from a seam response body (tolerant of
+ *  `{error}` / `{code}` / `{error:{code}}` shapes) — mirrors
+ *  `callai-multimodal.test.ts`'s `errCode`. */
+function errCode(json: unknown): string | undefined {
+  const j = json as { error?: unknown; code?: unknown };
+  if (typeof j?.code === 'string') return j.code;
+  if (typeof j?.error === 'string') return j.error;
+  const e = j?.error as { code?: unknown } | undefined;
+  if (e && typeof e.code === 'string') return e.code;
+  return undefined;
+}
+
+describe('speech-synthesis-unadvertised (RFC 0105 §C)', () => {
+  it('a host NOT advertising speechSynthesis MUST reject the call with speech_synthesis_unsupported', async () => {
+    const ai = await readCapabilityFamily<Record<string, unknown>>('aiProviders');
+    const advertised = ai?.speechSynthesis === 'supported';
+    // Active precisely when TTS is ABSENT but the seam exists.
+    if (!behaviorGate('openwop-speech-synthesis-unadvertised', !advertised)) return;
+
+    const res = await driver.post(SEAM, {
+      text: 'Welcome to the weekly digest.',
+      voiceId: 'host:narrator-test',
+    });
+    if (res.status === 404) return; // seam unwired — soft-skip
+
+    // MUST reject — never a 200 success, never a silent no-op.
+    expect(
+      res.status !== 200,
+      driver.describe('RFC 0105 §C', 'an unadvertising host MUST NOT return a 200 success (never a no-op)'),
+    ).toBe(true);
+    expect(
+      errCode(res.json) === 'speech_synthesis_unsupported',
+      driver.describe('RFC 0105 §C', 'the call MUST be rejected with `speech_synthesis_unsupported`'),
+    ).toBe(true);
+  });
+});