@warpgogol/werkstatt-shared 0.2.0

package/src/ontology/schemas/page-entry.ts

@@ -0,0 +1,213 @@
+/*
+<MODULE_CONTRACT>
+<purpose>
+Zod schema for block-declarative page content entries (DNA-24, RFC-0026).
+Every page .md file under apps/<app>/src/content/pages/ must conform to PageEntrySchema.
+Exports BlockEntrySchema and PageEntrySchema — pure declarative schemas, no I/O.
+</purpose>
+<non-goals>
+  <item>Do not implement the buildPage pipeline here — that lives in @warpgogol/werkstatt-shared/share/page.</item>
+  <item>Do not parse YAML here; callers provide parsed objects to schema.parse().</item>
+  <item>Do not validate cross-system.yaml references — that is page.block.validate's job.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>Wave 1 (RFC-0026): Initial creation.</item>
+  <item>Architecture review 2026-07-10: extracted getSectionPropsSchema into manifest-resolver.ts — page-entry.ts is now pure declarative schemas with no I/O.</item>
+</CHANGE_SUMMARY>
+*/
+
+import { z } from "zod";
+import { MoonCatalog, PlanetCatalog, StarCatalog } from "../cosmic/index.ts";
+
+const PRINT_ORIENTATIONS = ["portrait", "landscape", "auto"] as const;
+const PRINT_PAGE_SIZES = ["a4", "letter", "legal"] as const;
+const PRINT_MARGINS = ["normal", "narrow", "none"] as const;
+const PRINT_BACKGROUND_MODES = ["preserve", "flatten"] as const;
+const PRINT_REGIONS = [
+  "navigation",
+  "breadcrumbs",
+  "cta",
+  "footer-links",
+  "header-logo",
+  "site-background",
+  "hero-animation",
+] as const;
+
+// ---------------------------------------------------------------------------
+// VisibilityExprSchema (re-declared here to avoid cross-package dep on @warpgogol/werkstatt-shared/share)
+// page.block.validate uses the canonical one from @warpgogol/werkstatt-shared/share;
+// the schema here is for Astro content-collection integration.
+// ---------------------------------------------------------------------------
+
+const visibilityExprSchema: z.ZodType<unknown> = z.lazy(() =>
+  z.union([
+    z.object({ feature: z.string().min(1) }),
+    z.object({ locale: z.union([z.string().min(1), z.array(z.string().min(1))]) }),
+    z.object({ segment: z.union([z.string().min(1), z.array(z.string().min(1))]) }),
+    z.object({ flag: z.string().min(1) }),
+    z.object({ all: z.array(visibilityExprSchema).min(1) }),
+    z.object({ any: z.array(visibilityExprSchema).min(1) }),
+    z.object({ not: visibilityExprSchema }),
+  ]),
+);
+
+// ---------------------------------------------------------------------------
+// BlockEntrySchema
+// ---------------------------------------------------------------------------
+
+/**
+ * Schema for a single block inside a page content entry.
+ *
+ * `use` is validated against PlanetCatalog — only known planet names are allowed.
+ * `props` is loose here (Record<string, unknown>); strict per-planet validation
+ * against propsSchema runs at build time in page.block.validate.
+ */
+export const BlockEntrySchema = z
+  .object({
+    /**
+     * Optional stable block identifier for analytics, anchor links, and
+     * block-level attribution. Must be kebab-case when provided.
+     * page.block.validate enforces uniqueness within a page.
+     */
+    id: z
+      .string()
+      .regex(/^[a-z0-9-]+$/, "Block id must be kebab-case")
+      .optional(),
+
+    /**
+     * Cosmic name identifying the section/component for this block.
+     * Normally a `PlanetCatalog` value (section archetype). The five
+     * **PASSPORT-RESERVED moons** (`Methone`, `Despina`, `Klarissa`, `Bianca`,
+     * `Adrastea`) are also accepted because the cosmic-passport routes invoke
+     * passport components as page-blocks (see RFC-0028). Other Moon names
+     * remain rejected.
+     * Must be pinned in system.yaml pages[route].planets[].
+     */
+    type: z.string().min(1).optional(),
+
+    use: z
+      .enum([
+        ...PlanetCatalog,
+        ...MoonCatalog.filter((m) =>
+          ["Methone", "Despina", "Klarissa", "Bianca", "Adrastea"].includes(m),
+        ),
+      ] as [string, ...string[]])
+      .optional(),
+
+    /**
+     * Props passed to the section component. Validated against the pinned
+     * manifest's propsSchema (strict mode, no extra keys) by page.block.validate.
+     * Loose here to allow Astro content-collections to parse the entry.
+     */
+    props: z.record(z.string(), z.unknown()).default({}),
+
+    /**
+     * Optional visibility expression. When absent the block is unconditionally visible.
+     * Evaluated at build time by evalVisibility against the RuntimeContext.
+     */
+    visibility: visibilityExprSchema.optional(),
+  })
+  .superRefine((data, ctx) => {
+    if (!data.type && !data.use) {
+      ctx.addIssue({
+        code: "custom",
+        path: ["type"],
+        message: "Block selector is required; use author-facing `type` in page content",
+      });
+    }
+  });
+
+export type BlockEntry = z.infer<typeof BlockEntrySchema>;
+
+// ---------------------------------------------------------------------------
+// PageEntrySchema
+// ---------------------------------------------------------------------------
+
+/**
+ * Schema for a block-declarative page content entry (DNA-24, RFC-0026).
+ *
+ * Stored at: apps/<app>/src/content/pages/<page-id>/<page-id>.<lang>.md
+ * Format: YAML frontmatter only — no markdown body allowed (enforced by mirror.quintet.validate).
+ *
+ * Example:
+ * ```yaml
+ * kind: page
+ * cosmicStar: Vega
+ * title: "Startseite"
+ * description: "Beispielorganisation — Bildung, Gesundheit, Solidarität."
+ * lang: de
+ * blocks:
+ *   - id: hero
+ *     use: Europa
+ *     props:
+ *       headline: "Bildung für Kinder in León"
+ *       subline: "Seit 2008 — jeden Tag."
+ * ```
+ */
+export const PageEntrySchema = z
+  .object({
+    /**
+     * Discriminator identifying the entry kind.
+     * - `page`: standard block-declarative page (must have ≥1 block).
+     * - `redirect`: language-root redirect helper (no blocks required) — used by
+     *   files like `src/content/pages/root-redirect.md` that resolve to a
+     *   client-side redirect script rather than a rendered section sequence.
+     */
+    kind: z.enum(["page", "redirect"]).default("page"),
+
+    /**
+     * IAU star name for this page — must match a StarCatalog entry and
+     * the cosmicName of the page's manifest.yaml.
+     * Cross-reference against system.yaml is validated by page.block.validate.
+     */
+    cosmicStar: z.enum(StarCatalog),
+
+    /** Page <title> and social/SEO title. */
+    title: z.string().min(1),
+
+    /** Page meta description for SEO and social cards. */
+    description: z.string().min(1),
+
+    /**
+     * BCP-47 language code matching the file's language suffix (e.g. "de", "en").
+     * The pipeline uses this as the locale for RuntimeContext.
+     */
+    lang: z.string().min(1),
+
+    /**
+     * Ordered list of blocks composing this page.
+     * For `kind: page`, must have at least one block (enforced by superRefine).
+     * For `kind: redirect`, may be empty.
+     * Every `use` value must be pinned in system.yaml pages[route].planets[].
+     * Props are validated against the pinned manifest's propsSchema by page.block.validate.
+     */
+    blocks: z.array(BlockEntrySchema).default([]),
+
+    /**
+     * RFC-0257: per-page print configuration. Optional — when absent, defaults
+     * are applied by the print validators and PDF generator.
+     */
+    print: z
+      .object({
+        enabled: z.boolean().optional(),
+        orientation: z.enum(PRINT_ORIENTATIONS).optional(),
+        pageSize: z.enum(PRINT_PAGE_SIZES).optional(),
+        margins: z.enum(PRINT_MARGINS).optional(),
+        expandDetails: z.boolean().optional(),
+        hide: z.array(z.enum(PRINT_REGIONS)).optional(),
+        background: z.enum(PRINT_BACKGROUND_MODES).optional(),
+      })
+      .optional(),
+  })
+  .superRefine((data, ctx) => {
+    if (data.kind === "page" && data.blocks.length === 0) {
+      ctx.addIssue({
+        code: "custom",
+        path: ["blocks"],
+        message: "A page must have at least one block",
+      });
+    }
+  });
+
+export type PageEntry = z.infer<typeof PageEntrySchema>;

package/src/ontology/schemas/section-archetype.ts

@@ -0,0 +1,109 @@
+/*
+<MODULE_CONTRACT>
+<purpose>
+Zod schema for RFC-0072 section archetype catalog entries stored under
+packages/werkstatt-site/src/domain/ontology/archetypes/sections/ recursive YAML catalog files.
+</purpose>
+<non-goals>
+  <item>Do not parse YAML here.</item>
+  <item>Do not resolve imports or generate files here.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0072: Initial archetype catalog contract.</item>
+</CHANGE_SUMMARY>
+*/
+
+import { z } from "zod";
+import { cosmicNameSchema } from "../cosmic/index.ts";
+import { industrySchema } from "../enums.ts";
+
+const archetypeIdSchema = z
+  .string()
+  .regex(
+    /^[a-z][a-z0-9-]*(?:\.[a-z][a-z0-9-]*)*$/,
+    "archetype id must be kebab-case segments separated by dots",
+  );
+
+const layoutHintSchema = z.enum([
+  "single-column",
+  "split",
+  "card-grid",
+  "decision-card",
+  "horizontal-row",
+  "stacked-bands",
+]);
+
+/**
+ * RFC-0103: closed enum of canonical body kinds. Each non-composite archetype
+ * declares which body component renders authored content (list / split-list /
+ * stats / cards / paragraphs / comparison / rich). Composite archetypes (hero,
+ * hero-decision-card, founder-trust-card, donation-card, price-card, faq-list,
+ * markdown) declare `bodyKind: composite` and own their bespoke layout.
+ */
+const archetypeBodyKindSchema = z.enum([
+  "list",
+  "split-list",
+  "stats",
+  "cards",
+  "paragraphs",
+  "comparison",
+  "rich",
+  "composite",
+]);
+
+const recommendedItemCountSchema = z
+  .object({
+    min: z.number().int().nonnegative().optional(),
+    max: z.number().int().nonnegative().optional(),
+  })
+  .strict();
+
+/**
+ * RFC-0101 + RFC-0102 + RFC-0103: archetype propsSchema accepts either
+ *   (a) a `shape:` string with a Zod / JSON Schema expression (legacy form), or
+ *   (b) a `compose: [...]` list of shared-section-props fragment ids that the
+ *       runtime resolves through composeManifestPropsSchema().
+ * Both forms may be combined when the archetype needs to add section-specific
+ * fields on top of the shared fragments — see transparency.yaml.
+ */
+const propsSchemaFragmentSchema = z
+  .object({
+    $shape: z.enum(["zod", "json-schema"]).default("zod"),
+    shape: z.string().min(1).optional(),
+    compose: z
+      .array(
+        z
+          .string()
+          .regex(/^[a-z][a-z0-9-]*(@\d+)?$/, "must match `<id>` or `<id>@<version>` (RFC-0119)"),
+      )
+      .optional(),
+  })
+  .refine((v) => Boolean(v.shape) || Boolean(v.compose && v.compose.length > 0), {
+    message: "propsSchema must declare `shape` or non-empty `compose` (or both)",
+  });
+
+export const sectionArchetypeSchema = z.object({
+  id: archetypeIdSchema,
+  displayName: z.string().min(1),
+  version: z.string().regex(/^\d+\.\d+\.\d+(?:-[a-z0-9.-]+)?$/i, "version must be valid semver"),
+  semanticRole: z.string().min(1),
+  description: z.string().min(1),
+  expectedIntents: z.array(z.string().min(1)).min(1),
+  expectedIndustryFit: z.array(industrySchema).default([]),
+  layoutHint: layoutHintSchema,
+  /** RFC-0103: required for non-composite archetypes; composite signals bespoke layout. */
+  bodyKind: archetypeBodyKindSchema.optional(),
+  /** RFC-0072: advisory min/max number of body items the archetype expects. */
+  recommendedItemCount: recommendedItemCountSchema.optional(),
+  propsSchema: propsSchemaFragmentSchema,
+  acceptedCosmicNames: z.array(cosmicNameSchema).min(1),
+  constraints: z.record(z.string(), z.unknown()).default({}),
+});
+
+export type ArchetypeBodyKind = z.infer<typeof archetypeBodyKindSchema>;
+export type RecommendedItemCount = z.infer<typeof recommendedItemCountSchema>;
+
+export type SectionArchetypeContract = z.infer<typeof sectionArchetypeSchema>;
+export type SectionArchetypeId = z.infer<typeof archetypeIdSchema>;
+export type SectionArchetypeLayoutHint = z.infer<typeof layoutHintSchema>;

package/src/ontology/schemas/site-family.ts

@@ -0,0 +1,98 @@
+/*
+<MODULE_CONTRACT>
+<purpose>
+Zod schema for site-family definition files under packages/werkstatt-site/src/domain/ontology/site-families/<id>/family.yaml.
+A Site Family captures reusable onboarding recipes: detection signals, candidate biomes,
+candidate constellations, required section archetypes, audit thresholds, and readiness baselines.
+</purpose>
+<non-goals>
+  <item>Do not read files from disk.</item>
+  <item>Do not validate referenced biome/constellation/archetype files here; runtime validators do that.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0071: Add site-family contract to @warpgogol/werkstatt-shared/ontology.</item>
+</CHANGE_SUMMARY>
+*/
+
+import { z } from "zod";
+
+const kebabId = z
+  .string()
+  .regex(/^[a-z][a-z0-9-]*$/, "id must be kebab-case (lowercase letters, digits, hyphens)");
+const semver = z
+  .string()
+  .regex(/^\d+\.\d+\.\d+(?:-[a-z0-9.-]+)?$/i, "version must be valid semver");
+
+const eventNameSchema = z
+  .string()
+  .regex(/^[a-z][a-z0-9-]*(?:-[a-z0-9-]+)*$/, "eventName must be kebab-case");
+
+const detectionSignalsSchema = z
+  .object({
+    archetypePrimary: kebabId.optional(),
+    audienceAny: z.array(z.string().min(1)).default([]),
+    conversionPrimary: kebabId.optional(),
+    materialMentionsAny: z.array(z.string().min(1)).default([]),
+  })
+  .strict();
+
+export const siteFamilyDetectionSchema = z
+  .object({
+    signals: detectionSignalsSchema,
+    threshold: z.number().min(0).max(1),
+  })
+  .strict();
+
+const conversionGoalSchema = z
+  .object({
+    id: kebabId,
+    eventName: eventNameSchema,
+  })
+  .strict();
+
+const auditThresholdValueSchema = z.enum([
+  "info",
+  "warn",
+  "warning",
+  "required",
+  "error",
+  "forbidden",
+]);
+
+export const siteFamilyRecipeSchema = z
+  .object({
+    candidateBiomes: z.array(kebabId).min(1),
+    candidateConstellations: z.array(kebabId).min(1),
+    requiredSectionArchetypes: z.array(kebabId).min(1),
+    conversionGoals: z
+      .object({
+        primary: conversionGoalSchema,
+        secondary: z.array(conversionGoalSchema).default([]),
+      })
+      .strict(),
+    auditThresholds: z.record(z.string().min(1), auditThresholdValueSchema),
+    agentReadinessBaseline: z
+      .object({
+        maxBytesToCta: z.number().int().positive(),
+        requireStructuredData: z.array(z.string().min(1)).default([]),
+      })
+      .strict(),
+  })
+  .strict();
+
+export const siteFamilySchema = z
+  .object({
+    id: kebabId,
+    displayName: z.string().min(1),
+    version: semver,
+    description: z.string().min(1),
+    detection: siteFamilyDetectionSchema,
+    recipe: siteFamilyRecipeSchema,
+  })
+  .strict();
+
+export type SiteFamilyDetection = z.infer<typeof siteFamilyDetectionSchema>;
+export type SiteFamilyRecipe = z.infer<typeof siteFamilyRecipeSchema>;
+export type SiteFamily = z.infer<typeof siteFamilySchema>;
+export const SiteFamilyContract = siteFamilySchema;

package/src/ontology/schemas/system/growth.ts

@@ -0,0 +1,80 @@
+/*
+<MODULE_CONTRACT>
+<purpose>Growth block schema (RFC-0027) and shared context schema for the system manifest.
+Exports growthVendorSchema as the canonical vendor config shape, reused by @warpgogol/werkstatt-site/growth/config.ts.</purpose>
+<non-goals>
+  <item>Do not introduce app-specific runtime composition or deployment behavior into this reusable package source file.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0303 Phase 3: extracted from schemas/system.ts as part of the domain split.</item>
+  <item>Architecture review 2026-07-10: Extracted growthVendorSchema so @warpgogol/werkstatt-site/growth/config.ts can import it instead of duplicating the shape.</item>
+</CHANGE_SUMMARY>
+*/
+
+import { z } from "zod";
+
+export const systemSharedContextSchema = z.object({
+  requiredPageIds: z.array(z.string().min(1)).optional().default([]),
+});
+
+/**
+ * Vendor adapter binding — the canonical schema for the `growth.vendor` block.
+ * Shared by systemGrowthSchema (ontology) and GrowthConfigSchema (@warpgogol/werkstatt-site/growth/config.ts).
+ *
+ * adapter: id of the GrowthAdapter package (e.g. "null", "matomo").
+ * options: vendor-specific key/value pairs forwarded to GrowthAdapter.init().
+ */
+export const growthVendorSchema = z.object({
+  adapter: z.string().min(1),
+  options: z.record(z.string(), z.string()).optional().default({}),
+});
+
+export type GrowthVendor = z.infer<typeof growthVendorSchema>;
+
+/**
+ * The `growth:` block in src/content/system.md. Activates the vendor-agnostic growth
+ * layer for this app. When absent, <GrowthProvider> is omitted and no events
+ * are emitted (null-adapter mode).
+ *
+ * Example src/content/system.md growth block:
+ *   growth:
+ *     vendor:
+ *       adapter: matomo
+ *       options:
+ *         proxyBaseUrl: /_wg/analytics/
+ *         siteId: "1"
+ *         privacyProfile: bannerfrei-v1
+ *     funnels:
+ *       - donation-intent-to-confirmation
+ *     experiments: []
+ */
+export const systemGrowthSchema = z.object({
+  /**
+   * Vendor adapter binding — uses the canonical growthVendorSchema.
+   */
+  vendor: growthVendorSchema,
+
+  /**
+   * Funnel ids to activate for this app.
+   * Each id must match a file in packages/werkstatt-site/src/domain/ontology/growth/funnels/<id>.yaml.
+   * Validated by growth.funnel.validate.
+   */
+  funnels: z
+    .array(z.string().regex(/^[a-z][a-z0-9-]*$/))
+    .optional()
+    .default([]),
+
+  /**
+   * Experiment ids available for this app.
+   * Each id must match a file in packages/werkstatt-site/src/domain/ontology/growth/experiments/<id>.yaml.
+   * Active experiment assignment per page is resolved server-side.
+   * Validated by growth.experiment.validate.
+   */
+  experiments: z
+    .array(z.string().regex(/^[a-z][a-z0-9-]*$/))
+    .optional()
+    .default([]),
+});
+
+export type SystemGrowth = z.infer<typeof systemGrowthSchema>;

package/src/ontology/schemas/system/integrations.ts

@@ -0,0 +1,143 @@
+/*
+<MODULE_CONTRACT>
+<purpose>Integrations schema for the system manifest: vendor adapter bindings and integration configuration.</purpose>
+<non-goals>
+  <item>Do not introduce app-specific runtime composition or deployment behavior into this reusable package source file.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0303 Phase 3: extracted from schemas/system.ts as part of the domain split.</item>
+</CHANGE_SUMMARY>
+*/
+
+import { z } from "zod";
+
+/**
+ * The `integrations:` block in system.yaml (engineering-owned). Declares which
+ * outbound channel adapters and (optionally) which CRM adapter this app activates
+ * through the Integration Port (RFC-0168).
+ *
+ * Adapter ids are validated against the closed adapter catalog in
+ * @warpgogol/werkstatt-site/integration by `integration.config.validate`; each configured
+ * adapter's required secret names are validated against the generated env schema
+ * by `integration.secrets.validate`.
+ *
+ * When the block is absent, channels self-enable purely by secret presence at
+ * runtime (back-compat) and the validators are a no-op pass.
+ *
+ * Example:
+ *   integrations:
+ *     channels:
+ *       - adapter: telegram
+ *       - adapter: email
+ *         options: { to: "info@example.org" }
+ *     crm:
+ *       adapter: pipedrive
+ */
+export const systemIntegrationsSchema = z.object({
+  /** Outbound channel adapter bindings (telegram | email | whatsapp | null). */
+  channels: z
+    .array(
+      z.object({
+        adapter: z.string().min(1),
+        options: z.record(z.string(), z.string()).optional(),
+      }),
+    )
+    .optional()
+    .default([]),
+
+  /** Optional CRM adapter binding (pipedrive | null). */
+  crm: z
+    .object({
+      adapter: z.string().min(1),
+      options: z.record(z.string(), z.string()).optional(),
+    })
+    .optional(),
+
+  /**
+   * Optional consent-gated chat widget binding (uchat | null) — RFC-0175.
+   * `options` carries PUBLIC vendor values only (e.g. uchat needs widgetId or a
+   * full scriptUrl). Validated by `chat.config.validate`; gated by the
+   * `integrations.chat` entitlement (RFC-0169). The widget is click-to-load: no
+   * third-party script/storage exists before the visitor activates the launcher.
+   */
+  chat: z
+    .object({
+      adapter: z.string().min(1),
+      options: z.record(z.string(), z.string()).optional(),
+    })
+    .optional(),
+
+  /**
+   * RFC-0176: out-of-process source bindings. When a source is enabled (e.g.
+   * `uchat`), the inbound route `/api/integration-inbound` is generated and
+   * requires `INTEGRATION_INBOUND_SECRET` to authenticate posts.
+   */
+  inbound: z
+    .object({
+      sources: z.array(z.string().min(1)).default([]),
+    })
+    .optional(),
+
+  /**
+   * RFC-0176: source-agnostic destination hub. Each destination declares a kind,
+   * a vendor, and an execution mode. `gogol-adapter` (default) runs on the
+   * client's site with the client's tokens; `vendor-native` is executed by an
+   * upstream vendor. Validated by `integration.config.validate`.
+   */
+  destinations: z
+    .array(
+      z.object({
+        kind: z.string().min(1),
+        vendor: z.string().min(1),
+        mode: z.enum(["gogol-adapter", "vendor-native"]).default("gogol-adapter"),
+      }),
+    )
+    .optional()
+    .default([]),
+
+  /**
+   * RFC-0179: the site's placement on the shared, sharded delivery backbone.
+   * `region` pins the site's events to a jurisdiction's queue/dedup shard (data
+   * residency); `tier` is `shared` (the low-volume long tail, hash-fanned across
+   * the region's shared pool) or `dedicated` (a noisy/high-volume client isolated
+   * onto its own queue). Both default so existing apps need no edit. Validated by
+   * `integration.config.validate`; consumed by `integration.infrastructure.generate`
+   * (RFC-0180) to resolve the `ShardAssignment`.
+   */
+  region: z.enum(["eu", "us"]).optional().default("eu"),
+  tier: z.enum(["shared", "dedicated"]).optional().default("shared"),
+
+  /**
+   * RFC-0181: EU-resident delivery substrate. `provider: upstash` routes leads via
+   * Upstash QStash (EU, eu-central-1) with an Upstash Redis (EU) idempotency ledger
+   * — Cloudflare Queues/KV cannot be EU-pinned. `region: eu` keeps lead PII physically
+   * in the EU. Validated by `integration.config.validate`.
+   */
+  delivery: z
+    .object({
+      provider: z.enum(["upstash"]).default("upstash"),
+      region: z.enum(["eu"]).default("eu"),
+    })
+    .optional(),
+
+  /**
+   * RFC-0188: Visitor Sales Funnel binding. The PLATFORM owns the stage/event/
+   * transition graph (@warpgogol/werkstatt-site/integration funnel.ts); this block only declares
+   * which canonical funnel `version` the app renders, which event `sources` feed it
+   * (e.g. uchat, stripe, operator), and whether the pilot is `enabled`. UChat is the
+   * conversation runtime — it renders the funnel and requests transitions; it never
+   * owns the graph, pricing, or canonical state. Make.com is never a source. Validated
+   * by `funnel.contract.validate` / `funnel.stage.validate` / `funnel.lagebild.validate`.
+   * Absent ⇒ the funnel validators are a no-op pass (funnel not yet enabled for the app).
+   */
+  funnel: z
+    .object({
+      version: z.string().min(1),
+      sources: z.array(z.string().min(1)).optional().default([]),
+      enabled: z.boolean().optional().default(false),
+    })
+    .optional(),
+});
+
+export type SystemIntegrations = z.infer<typeof systemIntegrationsSchema>;