@wildo-ai/saas-website 1.1.1

package/src/schemas/sections/website-section-definition.shared.schemas.ts

@@ -0,0 +1,120 @@
+import type { ComponentType } from 'react';
+import { z } from 'zod';
+
+import { WebsiteLabelKeySchema } from '../label-keys/website-label-key.schemas';
+import { WebsiteSectionRefSchema } from '../refs/section-ref.schemas';
+import type { WebsiteStructuredDataReturn } from '../structured-data/website-structured-data.shared.schemas';
+import { WebsiteSectionCategorySchema } from './website-section-category.shared';
+
+/**
+ * @wildo_source:part:start saas.website.sections.definition-schema facet:layer:shared facet:family:website
+ *
+ * `WebsiteSectionDefinition` — the runtime contract returned by the
+ * `defineWebsiteSection({ … })` factory (authored as a separate
+ * `core/define-website-section.tsx` module in Phase 2 because it carries
+ * React types in its inputs). The shape is declared in `schemas/`
+ * because it is the **observable contract** the page-manifest
+ * registration, label-pack validator, and SEO dispatcher depend on.
+ *
+ * **Shape rationale** (each field carries semantic weight — see
+ * `design-philosophy.mdc`):
+ *
+ * - `sectionRef` — the section's identity inside its hosting page.
+ *   Uniqueness is enforced **per page** at manifest registration time
+ *   (a section can be reused with the same `sectionRef` across pages
+ *   when its label-key root is intentionally shared).
+ * - `category` — see `WebsiteSectionCategory` JSDoc; tags the section
+ *   for SEO-dispatch, skill-mapping, and analytics labelling.
+ * - `expectedLabelKeys` — the **fully-composed** label keys the section
+ *   commits to consuming. The plan originally proposed leaf-relative
+ *   keys (`'headline'`) resolved at runtime against the
+ *   page+section context, but storing the fully-composed key on the
+ *   definition has three concrete benefits:
+ *     1. The label-pack validator (`validateLabelPackAgainstManifest`)
+ *        runs as a pure function with no need to walk the JSX tree at
+ *        build time to discover the leaf-to-key resolution.
+ *     2. The contract is auditable from outside the React render
+ *        graph — `wildo website audit` can list a page's required keys
+ *        without booting React.
+ *     3. The leaf-relative ergonomics (`useWebsiteLabel('headline')`)
+ *        survive in Phase 2 — the hook composes the leaf with the
+ *        page+section context and validates the result against
+ *        `expectedLabelKeys`.
+ * - `Component` — the React component that renders the section. Typed
+ *   as `ComponentType<unknown>` here because schema-layer cannot lock
+ *   the component's prop shape (props vary per section). The factory
+ *   function (`defineWebsiteSection<TProps>(…)`) preserves the precise
+ *   prop type at the consumer call site via generics; this schema only
+ *   guards the runtime shape of "is callable as a React component".
+ * - `getStructuredData?` — optional pure function the SEO/AEO/GEO
+ *   builder library invokes at static-build time to materialize JSON-LD
+ *   for the section. The return type is intentionally `unknown` here;
+ *   the SEO library narrows by `category` (e.g. `PRICING` →
+ *   `Product | AggregateOffer`).
+ *
+ * **Why not `z.custom<ComponentType>(…)`**: a `z.custom` predicate
+ * cannot meaningfully validate "is a React component" beyond
+ * `typeof === 'function'`, and the false-positive cost (any function
+ * passes) is too high for the value (none — the consumer either
+ * imports a real component or fails at JSX render time with a clearer
+ * error). Using `z.unknown()` + a TS-side type cast keeps the runtime
+ * cost zero and the type-safety contract entirely on the TS side
+ * (where it actually has teeth via the factory's generic).
+ */
+const _WebsiteSectionDefinitionSchema = z.object({
+  sectionRef: WebsiteSectionRefSchema,
+  category: WebsiteSectionCategorySchema,
+  expectedLabelKeys: z.array(WebsiteLabelKeySchema).readonly(),
+  Component: z.unknown(),
+  getStructuredData: z.unknown().optional(),
+});
+
+export const WebsiteSectionDefinitionSchema: typeof _WebsiteSectionDefinitionSchema =
+  _WebsiteSectionDefinitionSchema;
+
+/**
+ * Runtime shape of `WebsiteSectionDefinition`. Note: `Component` and
+ * `getStructuredData` are typed precisely on the factory return type
+ * (`defineWebsiteSection<TProps>` in Phase 2); the schema-inferred
+ * type is the lowest common denominator used at the persistence /
+ * validation boundary only.
+ *
+ * **Why `ComponentType<any>` and NOT `ComponentType<unknown>`**:
+ * React component props are CONTRAVARIANT in `ComponentType<T>` —
+ * a narrower `ComponentType<{ foo: string }>` is NOT assignable to
+ * `ComponentType<unknown>` (because a caller could pass an `unknown`
+ * the narrower component cannot accept). This made every consumer
+ * who built sections via `defineWebsiteSection<TProps>(…)` unable
+ * to feed the resulting `TypedWebsiteSectionDefinition<TProps>` to
+ * helpers typed against the bare `WebsiteSectionDefinition` —
+ * collectors, validators, and registries. Using `any` here is the
+ * exact escape hatch the React typings themselves use for
+ * heterogeneous component containers (`React.forwardRef`,
+ * `React.lazy`'s internal component slot, etc.) and matches the
+ * runtime contract: the framework NEVER instantiates these
+ * components directly with arbitrary props — the consumer's JSX
+ * supplies the right props at the call site.
+ */
+export interface WebsiteSectionDefinition extends z.infer<typeof _WebsiteSectionDefinitionSchema> {
+  Component: ComponentType<any>;
+  /**
+   * Optional pure function the SEO/AEO/GEO renderer invokes at
+   * static-build time to materialize JSON-LD for the section.
+   *
+   * **Why typed as `WebsiteStructuredDataReturn` (not `unknown`)** —
+   * a typed return shape gives section authors autocomplete on
+   * `@type` / `@id` / `@context` (the framework-owned fields) while
+   * keeping all other fields free-form (Schema.org has hundreds of
+   * optional fields per entity; locking them in TS would be both
+   * impractical and brittle as Schema.org evolves). The companion
+   * catalog reconciliation surface catches missing-required and
+   * deprecated-field-used at the SEMANTIC layer (warning-only per
+   * D-AG4), so the runtime type stays loose.
+   *
+   * Returns `null`, `undefined`, or `[]` when the section has no
+   * structured-data contribution for the current state — the
+   * renderer short-circuits all three.
+   */
+  getStructuredData?: () => WebsiteStructuredDataReturn;
+}
+/** @wildo_source:part:end saas.website.sections.definition-schema */

package/src/schemas/structured-data/structured-data-reconciliation.shared.ts

@@ -0,0 +1,579 @@
+export interface StructuredDataDeprecatedField {
+  field: string;
+  replacedBy: string | null;
+  deprecatedSince: string;
+}
+
+export interface StructuredDataCatalogEntry {
+  '@type': string;
+  requiredFields: readonly string[];
+  optionalFields?: readonly string[];
+  deprecatedFields?: readonly StructuredDataDeprecatedField[];
+  recommendOptionals?: boolean;
+}
+
+export interface StructuredDataPayload {
+  '@type': string;
+  '@id'?: string;
+  [key: string]: unknown;
+}
+
+export interface StructuredDataSectionDefinitionLike {
+  sectionRef: string;
+  getStructuredData?: () => unknown;
+}
+
+export interface StructuredDataPageManifestLike {
+  ref: string;
+  routePath: string;
+  sectionRefs: readonly string[];
+}
+
+export interface StructuredDataPagePayloadLike {
+  pageRef: string;
+  routePath?: string;
+  sourceRef?: string;
+  payloads: unknown;
+}
+
+export type StructuredDataSpecViolationCode =
+  | 'invalid-payload-shape'
+  | 'missing-entity-type'
+  | 'missing-required-field'
+  | 'missing-section-definition'
+  | 'orphan-page-payload';
+
+export interface StructuredDataCatalogOverrideFinding {
+  kind: 'catalog-override';
+  entityType: string;
+  count: number;
+  message: string;
+}
+
+export interface StructuredDataCatalogMissFinding {
+  kind: 'catalog-miss';
+  pageRef: string;
+  routePath: string;
+  sectionRef: string;
+  entityType: string;
+  entityId?: string;
+  message: string;
+}
+
+export interface StructuredDataSpecViolationFinding {
+  kind: 'spec-violation';
+  code: StructuredDataSpecViolationCode;
+  pageRef: string;
+  routePath: string;
+  sectionRef: string;
+  entityType?: string;
+  entityId?: string;
+  field?: string;
+  message: string;
+}
+
+export interface StructuredDataDeprecatedFieldFinding {
+  kind: 'deprecated-field';
+  pageRef: string;
+  routePath: string;
+  sectionRef: string;
+  entityType: string;
+  entityId?: string;
+  field: string;
+  replacedBy: string | null;
+  deprecatedSince: string;
+  message: string;
+}
+
+export interface StructuredDataCrossEntityReferenceDriftFinding {
+  kind: 'cross-entity-reference-drift';
+  pageRef: string;
+  routePath: string;
+  sectionRef: string;
+  entityType: string;
+  entityId?: string;
+  missingReferenceId: string;
+  message: string;
+}
+
+export type StructuredDataReconciliationFinding =
+  | StructuredDataCatalogOverrideFinding
+  | StructuredDataCatalogMissFinding
+  | StructuredDataSpecViolationFinding
+  | StructuredDataDeprecatedFieldFinding
+  | StructuredDataCrossEntityReferenceDriftFinding;
+
+export interface StructuredDataReconciliationPageResult {
+  pageRef: string;
+  routePath: string;
+  payloadCount: number;
+  findingCount: number;
+}
+
+export interface StructuredDataReconciliationResult {
+  findings: StructuredDataReconciliationFinding[];
+  pages: StructuredDataReconciliationPageResult[];
+}
+
+export interface ReconcileStructuredDataOptions {
+  catalog: readonly StructuredDataCatalogEntry[];
+  pages: readonly StructuredDataPageManifestLike[];
+  sections: readonly StructuredDataSectionDefinitionLike[];
+  pagePayloads?: readonly StructuredDataPagePayloadLike[];
+}
+
+interface ReconciliationPayloadContext {
+  pageRef: string;
+  routePath: string;
+  sectionRef: string;
+  payload: StructuredDataPayload;
+}
+
+export function reconcileStructuredDataAgainstCatalog(
+  options: ReconcileStructuredDataOptions,
+): StructuredDataReconciliationResult {
+  const findings: StructuredDataReconciliationFinding[] = [];
+  const pages: StructuredDataReconciliationPageResult[] = [];
+  const sectionsByRef = new Map(
+    options.sections.map((section) => [section.sectionRef, section] as const),
+  );
+  const pagePayloadsByPageRef = new Map<string, StructuredDataPagePayloadLike[]>();
+  for (const pagePayload of options.pagePayloads ?? []) {
+    const pagePayloads = pagePayloadsByPageRef.get(pagePayload.pageRef) ?? [];
+    pagePayloads.push(pagePayload);
+    pagePayloadsByPageRef.set(pagePayload.pageRef, pagePayloads);
+  }
+  const catalogByType = new Map<string, StructuredDataCatalogEntry>();
+  const catalogCounts = new Map<string, number>();
+
+  for (const entry of options.catalog) {
+    catalogByType.set(entry['@type'], entry);
+    catalogCounts.set(entry['@type'], (catalogCounts.get(entry['@type']) ?? 0) + 1);
+  }
+
+  for (const [entityType, count] of catalogCounts.entries()) {
+    if (count > 1) {
+      findings.push({
+        kind: 'catalog-override',
+        entityType,
+        count,
+        message:
+          `Merged catalog contains ${count} entries for @type="${entityType}". ` +
+          'Replacement semantics are last-wins; duplicate array entries indicate an unresolved override.',
+      });
+    }
+  }
+
+  for (const page of options.pages) {
+    const pageFindingStart = findings.length;
+    const sectionPayloadContexts: ReconciliationPayloadContext[] = [];
+    const isTemplatedRoute = page.routePath.includes('[');
+
+    for (const sectionRef of page.sectionRefs) {
+      const section = sectionsByRef.get(sectionRef);
+      if (!section) {
+        findings.push({
+          kind: 'spec-violation',
+          code: 'missing-section-definition',
+          pageRef: page.ref,
+          routePath: page.routePath,
+          sectionRef,
+          message:
+            `Page "${page.ref}" references sectionRef "${sectionRef}" but no matching section ` +
+            'definition was supplied to the structured-data reconciliation harness.',
+        });
+        continue;
+      }
+
+      if (!section.getStructuredData) {
+        continue;
+      }
+
+      const rawStructuredData = section.getStructuredData();
+      const normalizedPayloads = normalizeStructuredDataReturn(rawStructuredData);
+
+      if (normalizedPayloads === null) {
+        findings.push({
+          kind: 'spec-violation',
+          code: 'invalid-payload-shape',
+          pageRef: page.ref,
+          routePath: page.routePath,
+          sectionRef,
+          message:
+            `Section "${sectionRef}" on page "${page.ref}" returned an invalid ` +
+            '`getStructuredData()` shape. Expected object, array, null, or undefined.',
+        });
+        continue;
+      }
+
+      for (const candidate of normalizedPayloads) {
+        if (!isPlainObject(candidate)) {
+          findings.push({
+            kind: 'spec-violation',
+            code: 'invalid-payload-shape',
+            pageRef: page.ref,
+            routePath: page.routePath,
+            sectionRef,
+            message:
+              `Section "${sectionRef}" on page "${page.ref}" returned a non-object structured-data payload.`,
+          });
+          continue;
+        }
+
+        if (typeof candidate['@type'] !== 'string' || candidate['@type'].trim().length === 0) {
+          findings.push({
+            kind: 'spec-violation',
+            code: 'missing-entity-type',
+            pageRef: page.ref,
+            routePath: page.routePath,
+            sectionRef,
+            entityId: typeof candidate['@id'] === 'string' ? candidate['@id'] : undefined,
+            message:
+              `Section "${sectionRef}" on page "${page.ref}" returned a structured-data payload ` +
+              'without a non-empty string `@type`.',
+          });
+          continue;
+        }
+
+        sectionPayloadContexts.push({
+          pageRef: page.ref,
+          routePath: page.routePath,
+          sectionRef,
+          payload: candidate as StructuredDataPayload,
+        });
+      }
+    }
+
+    const contextsByRoutePath = new Map<string, ReconciliationPayloadContext[]>();
+    const collectionFindingCountByRoutePath = new Map<string, number>();
+    const pagePayloadsForPage = pagePayloadsByPageRef.get(page.ref) ?? [];
+    pagePayloadsByPageRef.delete(page.ref);
+    const shouldEmitManifestResult =
+      (sectionPayloadContexts.length > 0 && (!isTemplatedRoute || pagePayloadsForPage.length === 0))
+      || findings.length > pageFindingStart
+      || pagePayloadsForPage.length === 0;
+    if (shouldEmitManifestResult) {
+      const manifestPayloadContexts =
+        isTemplatedRoute && pagePayloadsForPage.length > 0
+          ? []
+          : [...sectionPayloadContexts];
+      contextsByRoutePath.set(page.routePath, manifestPayloadContexts);
+      collectionFindingCountByRoutePath.set(page.routePath, findings.length - pageFindingStart);
+    }
+
+    for (const pagePayload of pagePayloadsForPage) {
+      const routePath = pagePayload.routePath ?? page.routePath;
+      const payloadContexts = contextsByRoutePath.get(routePath) ?? [];
+      if (
+        payloadContexts.length === 0
+        && isTemplatedRoute
+        && sectionPayloadContexts.length > 0
+      ) {
+        payloadContexts.push(
+          ...sectionPayloadContexts.map((context) => ({
+            ...context,
+            routePath,
+          })),
+        );
+      }
+      contextsByRoutePath.set(routePath, payloadContexts);
+      const collectionFindingStart = findings.length;
+      collectNormalizedPayloadContexts({
+        rawStructuredData: pagePayload.payloads,
+        pageRef: page.ref,
+        routePath,
+        sectionRef: pagePayload.sourceRef ?? `page:${page.ref}`,
+        findings,
+        into: payloadContexts,
+      });
+      collectionFindingCountByRoutePath.set(
+        routePath,
+        (collectionFindingCountByRoutePath.get(routePath) ?? 0)
+          + findings.length - collectionFindingStart,
+      );
+    }
+
+    for (const [routePath, payloadContexts] of contextsByRoutePath.entries()) {
+      const declaredEntityIds = new Set<string>();
+      for (const payloadContext of payloadContexts) {
+        collectDeclaredEntityIds(payloadContext.payload, declaredEntityIds);
+      }
+
+      const routeFindingStart = findings.length;
+      for (const payloadContext of payloadContexts) {
+        validatePayloadAgainstCatalog(payloadContext, catalogByType, declaredEntityIds, findings);
+      }
+
+      pages.push({
+        pageRef: page.ref,
+        routePath,
+        payloadCount: payloadContexts.length,
+        findingCount:
+          (collectionFindingCountByRoutePath.get(routePath) ?? 0)
+          + findings.length - routeFindingStart,
+      });
+    }
+  }
+
+  for (const [pageRef, pagePayloads] of pagePayloadsByPageRef.entries()) {
+    for (const pagePayload of pagePayloads) {
+      findings.push({
+        kind: 'spec-violation',
+        code: 'orphan-page-payload',
+        pageRef,
+        routePath: pagePayload.routePath ?? '',
+        sectionRef: pagePayload.sourceRef ?? `page:${pageRef}`,
+        message:
+          `Structured-data page payload "${pagePayload.sourceRef ?? `page:${pageRef}`}" ` +
+          `references pageRef "${pageRef}" but no matching page manifest was supplied.`,
+      });
+    }
+  }
+
+  return {
+    findings,
+    pages,
+  };
+}
+
+function collectNormalizedPayloadContexts(input: {
+  rawStructuredData: unknown;
+  pageRef: string;
+  routePath: string;
+  sectionRef: string;
+  findings: StructuredDataReconciliationFinding[];
+  into: ReconciliationPayloadContext[];
+}): void {
+  const {
+    rawStructuredData,
+    pageRef,
+    routePath,
+    sectionRef,
+    findings,
+    into,
+  } = input;
+  const normalizedPayloads = normalizeStructuredDataReturn(rawStructuredData);
+
+  if (normalizedPayloads === null) {
+    findings.push({
+      kind: 'spec-violation',
+      code: 'invalid-payload-shape',
+      pageRef,
+      routePath,
+      sectionRef,
+      message:
+        `Structured-data source "${sectionRef}" on page "${pageRef}" returned an invalid ` +
+        'structured-data shape. Expected object, array, null, or undefined.',
+    });
+    return;
+  }
+
+  for (const candidate of normalizedPayloads) {
+    if (!isPlainObject(candidate)) {
+      findings.push({
+        kind: 'spec-violation',
+        code: 'invalid-payload-shape',
+        pageRef,
+        routePath,
+        sectionRef,
+        message:
+          `Structured-data source "${sectionRef}" on page "${pageRef}" returned a non-object structured-data payload.`,
+      });
+      continue;
+    }
+
+    if (typeof candidate['@type'] !== 'string' || candidate['@type'].trim().length === 0) {
+      findings.push({
+        kind: 'spec-violation',
+        code: 'missing-entity-type',
+        pageRef,
+        routePath,
+        sectionRef,
+        entityId: typeof candidate['@id'] === 'string' ? candidate['@id'] : undefined,
+        message:
+          `Structured-data source "${sectionRef}" on page "${pageRef}" returned a structured-data payload ` +
+          'without a non-empty string `@type`.',
+      });
+      continue;
+    }
+
+    into.push({
+      pageRef,
+      routePath,
+      sectionRef,
+      payload: candidate as StructuredDataPayload,
+    });
+  }
+}
+
+function validatePayloadAgainstCatalog(
+  payloadContext: ReconciliationPayloadContext,
+  catalogByType: ReadonlyMap<string, StructuredDataCatalogEntry>,
+  declaredEntityIds: ReadonlySet<string>,
+  findings: StructuredDataReconciliationFinding[],
+): void {
+  const { payload, pageRef, routePath, sectionRef } = payloadContext;
+  const entityType = payload['@type'];
+  const entityId = typeof payload['@id'] === 'string' ? payload['@id'] : undefined;
+  const catalogEntry = catalogByType.get(entityType);
+
+  if (!catalogEntry) {
+    findings.push({
+      kind: 'catalog-miss',
+      pageRef,
+      routePath,
+      sectionRef,
+      entityType,
+      entityId,
+      message:
+        `Structured-data payload @type="${entityType}" emitted by section "${sectionRef}" ` +
+        `on page "${pageRef}" does not exist in the merged catalog.`,
+    });
+    return;
+  }
+
+  for (const requiredField of catalogEntry.requiredFields) {
+    if (!hasPresentFieldValue(payload, requiredField)) {
+      findings.push({
+        kind: 'spec-violation',
+        code: 'missing-required-field',
+        pageRef,
+        routePath,
+        sectionRef,
+        entityType,
+        entityId,
+        field: requiredField,
+        message:
+          `Structured-data payload @type="${entityType}" emitted by section "${sectionRef}" ` +
+          `on page "${pageRef}" is missing required field "${requiredField}".`,
+      });
+    }
+  }
+
+  for (const deprecatedField of catalogEntry.deprecatedFields ?? []) {
+    if (!hasPresentFieldValue(payload, deprecatedField.field)) {
+      continue;
+    }
+
+    findings.push({
+      kind: 'deprecated-field',
+      pageRef,
+      routePath,
+      sectionRef,
+      entityType,
+      entityId,
+      field: deprecatedField.field,
+      replacedBy: deprecatedField.replacedBy,
+      deprecatedSince: deprecatedField.deprecatedSince,
+      message:
+        deprecatedField.replacedBy === null
+          ? `Structured-data payload @type="${entityType}" emitted by section "${sectionRef}" ` +
+            `on page "${pageRef}" uses deprecated field "${deprecatedField.field}" ` +
+            `(deprecated since ${deprecatedField.deprecatedSince}).`
+          : `Structured-data payload @type="${entityType}" emitted by section "${sectionRef}" ` +
+            `on page "${pageRef}" uses deprecated field "${deprecatedField.field}". ` +
+            `Use "${deprecatedField.replacedBy}" instead ` +
+            `(deprecated since ${deprecatedField.deprecatedSince}).`,
+    });
+  }
+
+  const referencedIds = new Set<string>();
+  collectReferencedEntityIds(payload, referencedIds, true);
+  for (const referencedId of referencedIds) {
+    if (declaredEntityIds.has(referencedId)) {
+      continue;
+    }
+
+    findings.push({
+      kind: 'cross-entity-reference-drift',
+      pageRef,
+      routePath,
+      sectionRef,
+      entityType,
+      entityId,
+      missingReferenceId: referencedId,
+      message:
+        `Structured-data payload @type="${entityType}" emitted by section "${sectionRef}" ` +
+        `on page "${pageRef}" references @id "${referencedId}" but no emitted entity on the page defines it.`,
+    });
+  }
+}
+
+function normalizeStructuredDataReturn(value: unknown): unknown[] | null {
+  if (value === null || value === undefined) {
+    return [];
+  }
+
+  if (Array.isArray(value)) {
+    return value.filter((item) => item !== null && item !== undefined);
+  }
+
+  if (isPlainObject(value)) {
+    return [value];
+  }
+
+  return null;
+}
+
+function hasPresentFieldValue(payload: StructuredDataPayload, fieldName: string): boolean {
+  if (!Object.prototype.hasOwnProperty.call(payload, fieldName)) {
+    return false;
+  }
+
+  const value = payload[fieldName];
+  return value !== null && value !== undefined;
+}
+
+function collectDeclaredEntityIds(value: unknown, into: Set<string>): void {
+  if (Array.isArray(value)) {
+    for (const item of value) {
+      collectDeclaredEntityIds(item, into);
+    }
+    return;
+  }
+
+  if (!isPlainObject(value)) {
+    return;
+  }
+
+  const entityId = typeof value['@id'] === 'string' ? value['@id'] : null;
+  const entityType = typeof value['@type'] === 'string' ? value['@type'] : null;
+  if (entityId && entityType) {
+    into.add(entityId);
+  }
+
+  for (const child of Object.values(value)) {
+    collectDeclaredEntityIds(child, into);
+  }
+}
+
+function collectReferencedEntityIds(
+  value: unknown,
+  into: Set<string>,
+  isRootPayload: boolean,
+): void {
+  if (Array.isArray(value)) {
+    for (const item of value) {
+      collectReferencedEntityIds(item, into, false);
+    }
+    return;
+  }
+
+  if (!isPlainObject(value)) {
+    return;
+  }
+
+  const entityId = typeof value['@id'] === 'string' ? value['@id'] : null;
+  const entityType = typeof value['@type'] === 'string' ? value['@type'] : null;
+  if (!isRootPayload && entityId && !entityType) {
+    into.add(entityId);
+  }
+
+  for (const child of Object.values(value)) {
+    collectReferencedEntityIds(child, into, false);
+  }
+}
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}