@synap-core/workspace-templates 0.7.2 → 0.7.4

package/src/the-arch.yaml

@@ -21,6 +21,7 @@
 
 meta:
   slug: the-arch
+  domain: company
   name: The Arch
   description: The complete private company brain — the whole Enterprise OS plus the grant pipeline, the web3 ecosystem overlay, and the dev dashboard.
   icon: landmark
@@ -108,6 +109,16 @@ views:
     config:
       groupBy: stage
 
+# The Arch now OWNS the per-client comms digest capability. `client-comms-report`
+# is the one capability no constituent template installs today — the portable,
+# message-only client digest that any pod can run. The Arch, as the full company
+# brain, is where it belongs: it rides in alongside the operations-native durable
+# briefing so the founder has BOTH the entity-first record and the lightweight
+# recap. (discord-bot / agency-skills / stellar-grant-client already ride in via
+# the `grants` constituent's own integrations, so they are not re-declared here.)
+integrations:
+  - templateKey: client-comms-report
+
 onboarding:
   goal: >
     Name the cross-workspace initiatives that span the operating system and its

package/src/types.ts

@@ -524,6 +524,15 @@ export interface TemplateMeta {
   color: string;
   tags?: string[];
   isPublic?: boolean;
+  /**
+   * Human-facing subject area used to SECTION the marketplace (CLI `market
+   * list`, browser New Space + catalog). Authored here so grouping is a
+   * property of the template, read by every surface — never re-derived from a
+   * hardcoded slug→group map in a consumer. NOT `category` (that is the
+   * PACKAGE TYPE — `workspace`/`capability`/…). Optional and open: an unknown
+   * or missing value is grouped, never dropped — see `./domains.ts`.
+   */
+  domain?: string;
 }
 
 export interface WorkspaceYaml {

package/src/validate.test.ts

@@ -0,0 +1,81 @@
+/**
+ * Unit tests proving the extracted `validateTemplate` actually fires.
+ *
+ * The whole point of moving the rule logic out of build.mjs / check-converters.mjs
+ * into `src/validate.ts` is that the CLI, the CP, and the pod can call it. These
+ * tests exercise it directly (not through the build) with a deliberately-bad
+ * template and a clean one, so a regression that silently stops enforcing a rule
+ * is caught here rather than on a live pod.
+ */
+
+import { describe, expect, it } from "vitest";
+import { validateTemplate } from "./validate.js";
+import type { WorkspaceYaml } from "./types.js";
+
+describe("validateTemplate — fires on a bad template", () => {
+  const bad = {
+    // meta.slug MISSING — required field.
+    meta: { name: "Bad", description: "d", icon: "x", color: "#000000" },
+    workspace: { name: "Bad", description: "d" },
+    profiles: [{ slug: "gadget", displayName: "Gadget", properties: [] }],
+    automations: [
+      {
+        name: "notify",
+        triggerType: "event",
+        // profileSlug at an author-chosen depth points at a profile that
+        // exists nowhere — own, system, or a dependency base.
+        triggerConfig: { config: { profileSlug: "does-not-exist" } },
+        flow: { nodes: [], edges: [] },
+      },
+    ],
+  } as unknown as WorkspaceYaml;
+
+  const result = validateTemplate(bad, {});
+
+  it("returns ok:false with structured errors", () => {
+    expect(result.ok).toBe(false);
+    expect(result.errors.length).toBeGreaterThan(0);
+    for (const e of result.errors) {
+      expect(typeof e.rule).toBe("string");
+      expect(typeof e.path).toBe("string");
+      expect(typeof e.message).toBe("string");
+    }
+  });
+
+  it("flags the missing required meta field", () => {
+    const missingSlug = result.errors.find(
+      (e) => e.rule === "meta-field-required" && e.path === "meta.slug"
+    );
+    expect(missingSlug, JSON.stringify(result.errors)).toBeDefined();
+  });
+
+  it("flags the unknown profileSlug buried in an automation", () => {
+    const dangling = result.errors.find(
+      (e) => e.rule === "automation-ref-unknown" && e.message.includes("does-not-exist")
+    );
+    expect(dangling, JSON.stringify(result.errors)).toBeDefined();
+  });
+});
+
+describe("validateTemplate — clean template", () => {
+  it("returns ok:true with no errors", () => {
+    const good = {
+      meta: {
+        slug: "good",
+        name: "Good",
+        description: "d",
+        icon: "x",
+        color: "#000000",
+      },
+      workspace: { name: "Good", description: "d" },
+      profiles: [{ slug: "gadget", displayName: "Gadget", properties: [] }],
+      // references a SYSTEM profile (task) — resolves without declaring it.
+      views: [
+        { name: "Tasks", type: "table", scopeProfileSlug: "task" },
+      ],
+    } as unknown as WorkspaceYaml;
+
+    const result = validateTemplate(good, {});
+    expect(result, JSON.stringify(result.errors)).toEqual({ ok: true, errors: [] });
+  });
+});

package/src/validate.ts

@@ -0,0 +1,561 @@
+/**
+ * The ONE importable template validator.
+ * ======================================
+ *
+ * Historically the only real per-template guards lived in build-only scripts
+ * OUTSIDE `src/` — `build.mjs`'s `validate()` and `scripts/check-converters.mjs`
+ * — so no other repo could call them. The CP publish path, the pod install/apply
+ * path, and the CLI all re-implemented (or skipped) these checks. This module
+ * moves the per-template rule logic into `src/`, as a PURE function that
+ * RETURNS structured results (never `process.exit`), so all four callers share
+ * ONE validator:
+ *
+ *   • `build.mjs`                — loops the corpus, exits non-zero on errors.
+ *   • `scripts/check-converters.mjs` — injects the real converters, exits non-zero.
+ *   • CP / pod / CLI (from dist) — import `validateTemplate` + `SYSTEM_PROFILES`.
+ *
+ * ZERO RUNTIME IMPORTS BY DESIGN. `build.mjs` loads this file directly under
+ * Node's type-stripping BEFORE `tsup` builds `dist/`. A static
+ * `import { toWorkspaceDefinition } from "./define.js"` would fail to resolve at
+ * that moment (define → templates.js does not exist pre-build, and Node's
+ * type-stripper does not remap a `.js` specifier to its `.ts` source). So the
+ * converters are INJECTED via `opts.converters` rather than imported: the pure
+ * YAML/bento rules run everywhere; the converter-parity rules run wherever the
+ * caller can supply the compiled converters (check-converters.mjs, from dist).
+ * `import type` lines are fully erased by the type-stripper, so they are safe.
+ */
+
+import type {
+  WorkspaceYaml,
+  TemplateBentoBlock,
+  TemplateProfile,
+} from "./types.js";
+
+// ── Result shape ─────────────────────────────────────────────────────────────
+
+export interface ValidationError {
+  /** Stable machine code for the rule that fired (e.g. "profile-ref-unknown"). */
+  rule: string;
+  /** Dotted location inside the template, for error messages. */
+  path: string;
+  /** Human-readable description of the violation. */
+  message: string;
+}
+
+export interface ValidateResult {
+  ok: boolean;
+  errors: ValidationError[];
+}
+
+/**
+ * Structural view of the two converters, INJECTED (not imported) — see the file
+ * header. `check-converters.mjs` passes the real `toWorkspaceDefinition` /
+ * `toPackageDefinition` from `dist/`; their concrete types are structurally
+ * compatible with these minimal shapes.
+ */
+export interface TemplateConverters {
+  toWorkspaceDefinition: (tpl: WorkspaceYaml) => {
+    definition: {
+      bentoLayout?: Array<{ widgetType?: unknown }>;
+      bentoViewBlocks?: Array<{ viewName?: unknown; kind?: unknown }>;
+      bentoViewName?: string;
+      capabilities?: unknown[];
+    };
+  };
+  toPackageDefinition: (tpl: WorkspaceYaml) => {
+    bentoLayout?: Array<{ widgetType?: unknown }>;
+    bentoViewBlocks?: Array<{ viewName?: unknown; kind?: unknown }>;
+    bentoViewName?: string;
+    capabilities?: unknown[];
+  };
+}
+
+export interface ValidateOptions {
+  /**
+   * The whole corpus (parsed template data objects). Used to resolve a
+   * `compose`/`require` base's profile vocabulary. Keyed by `meta.slug`. Ignored
+   * when `resolveDep` is given.
+   */
+  corpus?: WorkspaceYaml[];
+  /** Direct dependency resolver — supersedes `corpus` when provided. */
+  resolveDep?: (slug: string) => WorkspaceYaml | undefined;
+  /**
+   * Compiled converters. When present, the converter-parity rules run (bento
+   * union split, wire-field shape, bentoViewName + capabilities parity across
+   * both install doors). When absent, only the pure YAML/bento rules run.
+   */
+  converters?: TemplateConverters;
+}
+
+// ── Static rule data ─────────────────────────────────────────────────────────
+
+// Types we validate against — kept in sync with types.ts.
+export const REQUIRED_META_FIELDS = [
+  "slug",
+  "name",
+  "description",
+  "icon",
+  "color",
+] as const;
+export const REQUIRED_WORKSPACE_FIELDS = ["name", "description"] as const;
+
+// Mirrors the backend's view-repository rule: every "structured" view (any type
+// except whiteboard/mindmap/bento) MUST declare a scope, else workspace creation
+// throws "scopeProfileIds is required for structured views".
+const SCOPE_EXEMPT = new Set(["whiteboard", "mindmap", "bento"]);
+
+/**
+ * System profiles a template may reference without defining. This MUST mirror
+ * the profiles seeded by synap-backend `ensure-system-profiles.ts` (the
+ * `profiles` array) — that seeder is the ground truth for what exists on every
+ * pod. A slug present here but NOT seeded lets a dangling ref validate green (the
+ * old bug: `project`/`document` were listed here after both were removed from the
+ * seeder — `project` became a first-class table in migration 0151, `document`
+ * never existed as a profile). A slug seeded but MISSING here forces every
+ * template to re-declare it, which is the exact pressure that spawns vocabulary
+ * forks. Keep the two lists in lockstep.
+ *
+ * SINGLE SOURCE OF TRUTH: this set lived in build.mjs; it now lives HERE and
+ * build.mjs imports it, so there is one list to keep in lockstep with the seeder.
+ */
+export const SYSTEM_PROFILES = new Set([
+  // Core capture hierarchy
+  "note",
+  "task",
+  "event",
+  "bookmark",
+  "website",
+  "article",
+  // People / orgs / CRM
+  "person",
+  "contact",
+  "company",
+  "deal",
+  // Files + programmatic kinds
+  "file",
+  "anchor",
+  "signal_item",
+  // Knowledge-work flow
+  "decision",
+  "question",
+  "research",
+  "knowledge",
+  "user_observation",
+]);
+
+// ── Dependency-vocabulary closure (compose vs require semantics) ─────────────
+
+/**
+ * Only `scope: shared` is a pod-wide row visible outside its origin workspace.
+ */
+function isPodWideProfile(p: TemplateProfile): boolean {
+  return String(p.scope || "").toLowerCase() === "shared";
+}
+
+/**
+ * Profile slugs a template may reference by virtue of its dependencies.
+ *
+ * `compose` and `require` are NOT the same for what a consumer may reference:
+ *   • `compose` MERGES the overlay into the base's ONE workspace, so the consumer
+ *     legitimately references ALL of the base's profiles (workspace-scoped ones
+ *     included) — that is the point of composing.
+ *   • `require` creates a SEPARATE workspace (installed first). Only the base's
+ *     POD-WIDE profiles (`scope: shared`; system profiles are handled separately)
+ *     cross that boundary and are visible to the consumer. The base's
+ *     `scope: WORKSPACE` profiles live in the base's OWN workspace and resolve
+ *     against NOTHING when referenced across a `require` — that is the class of
+ *     bug the social→content-os fork hit (a view/link/prop pointing at the base's
+ *     workspace-scoped profile provisions dangling and throws at runtime).
+ *
+ * Resolved TRANSITIVELY (a base's own bases count too, each by its own relation).
+ * Without this the validator is per-file and a real overlay can only reference
+ * system profiles + its own (blocks e.g. communication composing on brand-library).
+ *
+ * Moved verbatim out of build.mjs (semantics unchanged); it now resolves bases
+ * through the injected `resolveDep` rather than a hand-built `dataBySlug` map, so
+ * the same closure serves every caller.
+ */
+export function collectBaseProfileSlugs(
+  data: WorkspaceYaml,
+  resolveDep: (slug: string) => WorkspaceYaml | undefined,
+  seen = new Set<string>()
+): Set<string> {
+  const out = new Set<string>();
+  for (const dep of data.dependencies || []) {
+    if (dep.relation !== "compose" && dep.relation !== "require") continue;
+    if (seen.has(dep.slug)) continue;
+    seen.add(dep.slug);
+    const base = resolveDep(dep.slug);
+    if (!base) continue; // unresolved dep is caught by the corpus check, not here
+    // compose → all of the base's profiles; require → only its pod-wide ones.
+    const podWideOnly = dep.relation === "require";
+    for (const p of base.profiles || []) {
+      if (podWideOnly && !isPodWideProfile(p)) continue;
+      out.add(p.slug);
+    }
+    for (const s of collectBaseProfileSlugs(base, resolveDep, seen)) out.add(s);
+  }
+  return out;
+}
+
+/**
+ * Recursively collect every `profileSlug` string value under `node`, tagged with
+ * a dotted path for error messages. Used for `automations` (whose flow-node /
+ * trigger-config profile references live at author-chosen depths — e.g. an
+ * `entity_create` node keeps its target at `data.config.profileSlug`), so the
+ * validator covers ALL of them instead of one hard-coded field. Interpolated
+ * values (`{{...}}`) are runtime refs, not literal slugs — skipped.
+ */
+function collectProfileSlugRefs(
+  node: unknown,
+  path: string,
+  out: Array<{ where: string; slug: string }>
+): void {
+  if (node == null || typeof node !== "object") return;
+  if (Array.isArray(node)) {
+    node.forEach((v, i) => collectProfileSlugRefs(v, `${path}[${i}]`, out));
+    return;
+  }
+  for (const [k, v] of Object.entries(node as Record<string, unknown>)) {
+    if (k === "profileSlug" && typeof v === "string" && !v.includes("{{")) {
+      out.push({ where: `${path}.profileSlug`, slug: v });
+    } else {
+      collectProfileSlugRefs(v, `${path}.${k}`, out);
+    }
+  }
+}
+
+function resolveDepFrom(
+  opts: ValidateOptions
+): (slug: string) => WorkspaceYaml | undefined {
+  if (opts.resolveDep) return opts.resolveDep;
+  if (opts.corpus) {
+    const bySlug = new Map<string, WorkspaceYaml>();
+    for (const t of opts.corpus) {
+      const s = t.meta?.slug;
+      if (s) bySlug.set(s, t);
+    }
+    return (slug: string) => bySlug.get(slug);
+  }
+  return () => undefined;
+}
+
+// ── The validator ────────────────────────────────────────────────────────────
+
+/**
+ * Validate ONE template. Pure: returns `{ ok, errors }`, never exits. Covers the
+ * per-template rules formerly split across build.mjs `validate()` (required
+ * fields, ≥1 profile, structured-view-needs-scope, profileSlug referential
+ * integrity against `own ∪ SYSTEM_PROFILES ∪ dependency-vocab`, overlay safety,
+ * entityLink `type`) and check-converters.mjs (bento union split, widgetType /
+ * viewName present, bentoViewName + capabilities parity — the last group only
+ * when `opts.converters` is supplied).
+ */
+export function validateTemplate(
+  tpl: WorkspaceYaml,
+  opts: ValidateOptions = {}
+): ValidateResult {
+  const errors: ValidationError[] = [];
+  const add = (rule: string, path: string, message: string) =>
+    errors.push({ rule, path, message });
+
+  // ── Required fields ────────────────────────────────────────────────────────
+  if (!tpl.meta) add("meta-required", "meta", "Missing required field: meta");
+  else {
+    for (const f of REQUIRED_META_FIELDS) {
+      if (!tpl.meta[f]) add("meta-field-required", `meta.${f}`, `meta.${f} is required`);
+    }
+  }
+  if (!tpl.workspace)
+    add("workspace-required", "workspace", "Missing required field: workspace");
+  else {
+    for (const f of REQUIRED_WORKSPACE_FIELDS) {
+      if (!tpl.workspace[f])
+        add("workspace-field-required", `workspace.${f}`, `workspace.${f} is required`);
+    }
+  }
+  if (!tpl.profiles || tpl.profiles.length === 0) {
+    add("profiles-required", "profiles", "At least one profile is required");
+  }
+
+  // ── Referential integrity: build the known-profile predicate ──────────────
+  const baseProfileSlugs = collectBaseProfileSlugs(tpl, resolveDepFrom(opts));
+  const slugs = new Set((tpl.profiles || []).map((p) => p.slug));
+  const known = (s: string) =>
+    slugs.has(s) || SYSTEM_PROFILES.has(s) || baseProfileSlugs.has(s);
+
+  // Views: structured views need a scope; scoped profiles must resolve.
+  for (const v of tpl.views || []) {
+    const type = String(v.type || "").toLowerCase();
+    const scoped =
+      v.scopeProfileSlug || (v.scopeProfileSlugs && v.scopeProfileSlugs.length);
+    if (!SCOPE_EXEMPT.has(type) && !scoped) {
+      add(
+        "view-missing-scope",
+        `views."${v.name}"`,
+        `view "${v.name}" (${type}) needs scopeProfileSlug(s) — structured views require a scope`
+      );
+    }
+    if (v.scopeProfileSlug && !known(v.scopeProfileSlug))
+      add(
+        "view-scope-unknown",
+        `views."${v.name}".scopeProfileSlug`,
+        `view "${v.name}" scopes unknown profile "${v.scopeProfileSlug}"`
+      );
+    for (const s of v.scopeProfileSlugs || [])
+      if (!known(s))
+        add(
+          "view-scope-unknown",
+          `views."${v.name}".scopeProfileSlugs`,
+          `view "${v.name}" scopes unknown profile "${s}"`
+        );
+  }
+
+  // Property target refs.
+  for (const p of tpl.profiles || []) {
+    for (const pr of p.properties || []) {
+      if (pr.targetProfileSlug && !known(pr.targetProfileSlug)) {
+        add(
+          "property-target-unknown",
+          `profiles.${p.slug}.${pr.slug}.targetProfileSlug`,
+          `property ${p.slug}.${pr.slug} targets unknown profile "${pr.targetProfileSlug}"`
+        );
+      }
+    }
+  }
+
+  // Entity links: endpoints resolve + predicate `type` present.
+  for (const el of tpl.entityLinks || []) {
+    if (!known(el.sourceProfileSlug))
+      add(
+        "entitylink-source-unknown",
+        "entityLinks",
+        `entityLink source "${el.sourceProfileSlug}" is unknown`
+      );
+    if (!known(el.targetProfileSlug))
+      add(
+        "entitylink-target-unknown",
+        "entityLinks",
+        `entityLink target "${el.targetProfileSlug}" is unknown`
+      );
+    // The predicate field is `type` — a link with no `type` provisions a
+    // malformed relation at runtime; catch it here.
+    if (typeof el.type !== "string" || !el.type) {
+      add(
+        "entitylink-missing-type",
+        "entityLinks",
+        `entityLink ${el.sourceProfileSlug}→${el.targetProfileSlug} is missing its \`type\` (the predicate)`
+      );
+    }
+  }
+
+  for (const c of tpl.onboarding?.collect || []) {
+    if (!known(c.profileSlug))
+      add(
+        "onboarding-ref-unknown",
+        "onboarding.collect",
+        `onboarding.collect references unknown profile "${c.profileSlug}"`
+      );
+  }
+  for (const s of tpl.seedEntities || []) {
+    if (!known(s.profileSlug))
+      add(
+        "seedentity-ref-unknown",
+        "seedEntities",
+        `seedEntity references unknown profile "${s.profileSlug}"`
+      );
+  }
+
+  // profileSlug referential integrity, part 2 — every OTHER site that names a
+  // profile by slug, validated against the same closure. A bogus slug here fails
+  // SILENTLY at runtime.
+  for (const a of tpl.automations || []) {
+    const refs: Array<{ where: string; slug: string }> = [];
+    collectProfileSlugRefs(a.triggerConfig, `automation "${a.name}".triggerConfig`, refs);
+    collectProfileSlugRefs(a.flow, `automation "${a.name}".flow`, refs);
+    for (const r of refs)
+      if (!known(r.slug))
+        add("automation-ref-unknown", r.where, `${r.where} references unknown profile "${r.slug}"`);
+  }
+  for (const pb of tpl.playbooks || []) {
+    const ps = pb.subjectProfile?.profileSlug;
+    if (ps && !known(ps))
+      add(
+        "playbook-ref-unknown",
+        `playbooks."${pb.name}".subjectProfile`,
+        `playbook "${pb.name}".subjectProfile references unknown profile "${ps}"`
+      );
+  }
+  for (const ap of tpl.actionPlacements || []) {
+    if (ap.profileSlug && !known(ap.profileSlug)) {
+      add(
+        "actionplacement-ref-unknown",
+        "actionPlacements",
+        `actionPlacement "${ap.label ?? ap.ref}" references unknown profile "${ap.profileSlug}"`
+      );
+    }
+  }
+  for (const si of tpl.layout?.sidebarItems || []) {
+    if (si.profileSlug && !known(si.profileSlug)) {
+      add(
+        "sidebar-ref-unknown",
+        "layout.sidebarItems",
+        `layout.sidebarItems ("${si.label ?? si.profileSlug}") references unknown profile "${si.profileSlug}"`
+      );
+    }
+  }
+  for (const dt of tpl.displayTemplates || []) {
+    if (dt.entityType && !known(dt.entityType)) {
+      add(
+        "displaytemplate-ref-unknown",
+        `displayTemplates."${dt.name}".entityType`,
+        `displayTemplate "${dt.name}" targets unknown profile "${dt.entityType}" (entityType)`
+      );
+    }
+  }
+  for (const key of Object.keys(tpl.profileEntityBentoTemplates || {})) {
+    if (!known(key))
+      add(
+        "bentotemplate-ref-unknown",
+        "profileEntityBentoTemplates",
+        `profileEntityBentoTemplates has an entry for unknown profile "${key}"`
+      );
+  }
+
+  // ── Overlay-safety: an overlay (compose relation) is layered additively onto
+  // its base's workspace. The additive reconcile OVERWRITES workspace-level
+  // settings, so an overlay MUST set workspace.subtype to its compose-base's slug
+  // and MUST OMIT workspace.visibility — else it clobbers the base's identity.
+  const composeDeps = (tpl.dependencies || []).filter((d) => d.relation === "compose");
+  for (const dep of composeDeps) {
+    if (tpl.workspace?.visibility !== undefined) {
+      add(
+        "overlay-visibility",
+        "workspace.visibility",
+        `overlay (compose on "${dep.slug}") must OMIT workspace.visibility — it overwrites the base's on additive reconcile`
+      );
+    }
+    if (tpl.workspace?.subtype !== dep.slug) {
+      add(
+        "overlay-subtype",
+        "workspace.subtype",
+        `overlay (compose on "${dep.slug}") must set workspace.subtype to "${dep.slug}" (found "${tpl.workspace?.subtype}")`
+      );
+    }
+  }
+
+  // ── Bento union: pure checks (no converters needed) ───────────────────────
+  const blocks: TemplateBentoBlock[] = tpl.bento?.blocks ?? [];
+  const authoredWidgets = blocks.filter((b) => b.kind === "widget");
+  const authoredViews = blocks.filter((b) => b.kind === "view");
+  const unknownKind = blocks.filter((b) => b.kind !== "widget" && b.kind !== "view");
+  if (unknownKind.length) {
+    add(
+      "bento-unknown-kind",
+      "bento.blocks",
+      `${unknownKind.length} bento block(s) with unknown kind: ${unknownKind
+        .map((b) => String(b.kind))
+        .join(", ")}`
+    );
+  }
+  const badWidgets = authoredWidgets.filter((b) => !b.widgetType);
+  const badViews = authoredViews.filter((b) => !b.viewName);
+  if (badWidgets.length) {
+    add(
+      "bento-widget-missing-type",
+      "bento.blocks",
+      `${badWidgets.length} widget block(s) missing widgetType`
+    );
+  }
+  if (badViews.length) {
+    add(
+      "bento-view-missing-name",
+      "bento.blocks",
+      `${badViews.length} view block(s) missing viewName`
+    );
+  }
+
+  // ── Converter parity: only when the compiled converters are injected ──────
+  if (opts.converters) {
+    const { toWorkspaceDefinition, toPackageDefinition } = opts.converters;
+    const { definition } = toWorkspaceDefinition(tpl);
+    const pkg = toPackageDefinition(tpl);
+
+    if (blocks.length > 0) {
+      const expectW = authoredWidgets.length - badWidgets.length;
+      const expectV = authoredViews.length - badViews.length;
+
+      const doors: Array<[string, Array<{ widgetType?: unknown }>, Array<{ viewName?: unknown; kind?: unknown }>]> = [
+        ["tRPC createFromDefinition", definition.bentoLayout ?? [], definition.bentoViewBlocks ?? []],
+        ["CP packages/apply", pkg.bentoLayout ?? [], pkg.bentoViewBlocks ?? []],
+      ];
+      for (const [door, layout, viewBlocks] of doors) {
+        if (layout.length !== expectW || viewBlocks.length !== expectV) {
+          add(
+            "bento-split-count",
+            "bento.blocks",
+            `[${door}]: authored ${expectW} widget/${expectV} view → got ${layout.length} bentoLayout/${viewBlocks.length} bentoViewBlocks`
+          );
+        }
+        const layoutBad = layout.filter((b) => typeof b.widgetType !== "string");
+        const viewsBad = viewBlocks.filter(
+          (b) => typeof b.viewName !== "string" || b.kind !== "view"
+        );
+        if (layoutBad.length) {
+          add(
+            "bento-layout-shape",
+            "bento.blocks",
+            `[${door}]: ${layoutBad.length} bentoLayout block(s) without a string widgetType (mis-routed view block?)`
+          );
+        }
+        if (viewsBad.length) {
+          add(
+            "bento-viewblocks-shape",
+            "bento.blocks",
+            `[${door}]: ${viewsBad.length} bentoViewBlocks entry(s) without kind:'view' + string viewName (mis-routed widget block?)`
+          );
+        }
+      }
+    }
+
+    // bentoViewName parity — both converters MUST carry the authored bento.viewName.
+    const authoredViewName = tpl.bento?.viewName;
+    if (authoredViewName) {
+      if (definition.bentoViewName !== authoredViewName) {
+        add(
+          "bento-viewname-parity",
+          "bento.viewName",
+          `[tRPC]: authored bento.viewName "${authoredViewName}" → got "${definition.bentoViewName}"`
+        );
+      }
+      if (pkg.bentoViewName !== authoredViewName) {
+        add(
+          "bento-viewname-parity",
+          "bento.viewName",
+          `[CP]: authored bento.viewName "${authoredViewName}" → got "${pkg.bentoViewName}"`
+        );
+      }
+    }
+
+    // Capabilities parity — both doors emit integrations → capabilities.
+    const authored = tpl.integrations ?? [];
+    const wsCaps = definition.capabilities ?? [];
+    const pkgCaps = pkg.capabilities ?? [];
+    if (wsCaps.length !== authored.length) {
+      add(
+        "capabilities-count",
+        "integrations",
+        `[tRPC]: authored ${authored.length} integration(s) → got ${wsCaps.length} capabilities`
+      );
+    }
+    if (JSON.stringify(wsCaps) !== JSON.stringify(pkgCaps)) {
+      add(
+        "capabilities-parity",
+        "integrations",
+        `capability parity mismatch — tRPC door and CP door emit different capabilities`
+      );
+    }
+  }
+
+  return { ok: errors.length === 0, errors };
+}