spec + tooling: x-entity annotation and storyboard context-entity lint (#2660)

[bokelley]

Summary

Closes rule 3 of the #2634 contradiction trio. Adds a non-validating x-entity schema annotation that tags identity-bearing fields with the entity type they resolve against, plus a cross-storyboard lint that catches the class of bug fixed manually in #2627 — a value captured from a field of one entity type (advertiser_brand) consumed as a field of a different entity type (rights_holder_brand), with both sites passing local schema validation.

This is phase 1 of #2660: the mechanism ships end-to-end with the brand/ domain annotated (the canonical conflation case). Follow-up PRs will sweep the remaining six domains — the lint is silent on un-annotated fields so partial rollout is safe.

What's in this PR

• Registry: static/schemas/source/core/x-entity-types.json — 24 entity types with definitions (e.g., advertiser_brand, rights_holder_brand, rights_grant, media_buy, package, signal, signal_activation_id)
• Lint: scripts/lint-storyboard-context-entity.cjs
  • Walks context_outputs capture sites and $context.* consume sites
  • Accepts both bracket (rights[0].rights_id) and dotted paths — bracket is the canonical authoring form per storyboard-schema.yaml
  • Follows $ref; composes oneOf / anyOf / allOf variants
  • Rules: entity_mismatch, unknown_entity (with Levenshtein did-you-mean), capture_name_collision
  • Silent on fields without x-entity — partial rollout is safe
• Phase 1 annotations: brand/ schemas (request + response) plus core/brand-id.json tagged advertiser_brand so every $ref site inherits the scope. Canonical split: brand_id on get_brand_identity → advertiser_brand, brand_id inside get_rights result items → rights_holder_brand.
• Docs: docs/contributing/x-entity-annotation.md authoring guide, cross-linked from storyboard-authoring.md and .agents/playbook.md
• CI: wired into npm test and npm run build:compliance alongside the existing storyboard lints

Naming decisions reviewers may want to push on

• rights_contract → rights_grant — grants cover pending/rejected states, not just signed contracts (per AI licensing convention)
• signal vs signal_activation_id — two distinct referents (catalog ref vs. opaque activation handle)
• media_plan vs governance_plan — same plan_id field, genuinely different referent domains; kept split rather than collapsed
• core/brand-id.json gets x-entity: advertiser_brand — every $ref inherits advertiser scope. Rights-holder brand ids must use a separate shared type even if the string shape is identical. Docs call this out as the "shared-type invariant."

Why vertical slice

#2660 said "PR sequence." Shipping the mechanism end-to-end with one domain proves the approach against the canonical case (#2627) before we ask reviewers to agree on taxonomy for 60+ fields. Taxonomy debate now runs against concrete annotations, not hypotheticals.

Not in this PR (follow-ups)

• Annotation passes for media-buy/, creative/, signals/, account/, governance/, property/, sponsored-intelligence/ — one PR per domain (or paired by flow, TBD)
• Adoption signals: a coverage counter in CI output and a warn-only check for new *_id fields added without x-entity
• Preemptive core/rights-holder-brand-id.json shared type (not needed until a rights-roster id field materialises)

Test plan

• npm run test:storyboard-context-entity — 10 tests pass (source-tree guard, canonical brand_rights storyboard conflates advertiser brand_id with talent brand_id #2627 mismatch, bracket-notation regression guard, happy-path, silent-on-missing, collision, unknown_entity did-you-mean, $ref walker, oneOf walker, registry validity)
• npm run test:storyboard-branch-sets and test:storyboard-scoping still pass
• npm run test:schemas — all 484 schemas validate with new annotations
• npm run build:compliance — new lint runs clean against the source tree
• npm run test:unit (pre-commit) — 631 tests pass, typecheck clean

🤖 Generated with Claude Code