feat(domains): domain.yaml as bounded context with exports, suppliers, glossary (FEAT-035)

[easel]

What changed

Domain-Driven Design integration for tablespec. A domain is a directory of UMF tables with a domain.yaml: the bounded context. Its exports are the published language (versioned), its suppliers are the context map (advisory patterns, with consumer pins), and its glossary is the vocabulary that term fields resolve against and that the guidebook and prompts show.

name: claims
owner: claims-data-team
version: 1.0.0                    # published-language version, MAJOR.MINOR.PATCH
exports: [medical_claims]         # each exported table must declare a primary key
glossary: glossary.yaml
suppliers:
  eligibility:
    pattern: customer_supplier    # advisory; only separate_ways is enforced
    consumes: [member]
    version: ">=1.0.0,<2.0.0"     # accepted supplier versions

Models (ADR-020)

• models/domain.py: DomainMetadata, SupplierRelationship, IntegrationPattern, Glossary; load_domain (name must equal directory).
• ForeignKey: references_domain + integration. extra="forbid", so an unknown key fails on load instead of vanishing on save. Legacy references_pipeline is read the same way and never rewritten: a spec that does not use references_domain loads, saves, and compiles byte-for-byte as before.
• UMF.term / UMFColumn.term; canonical_name untouched.
• umf.schema.json regenerated and pinned by a new test (it was already stale).

Validation: one behavior, no mode

tablespec validate <path> validates every table beneath the path at any depth, and applies the rules between domains whenever a domain.yaml applies to the path (the path is a domain, is inside one, or has domains beneath it). Sibling domains are loaded from the directory that holds them, so validating one domain or one table still checks its references into the others. Findings are narrowed to what the path covers.

An earlier commit on this branch used a separate "domain mode". It was removed because it made a metadata file decide whether tables were validated at all, and reported a lone domain's suppliers as "not found". SD-035 records the rejected design.

Rules: DOM-EXPORT, DOM-SUPPLIER, DOM-XREF, DOM-TERM, DOM-WAYS, DOM-PIN, DOM-LOAD, DOM-COMPAT (with --baseline), warnings DOM-VERSION, DOM-DRIFT. No new CLI command.

Published-language versioning (ADR-021)

domain.version is strict SemVer core; suppliers.<d>.version is a small explicit range grammar (not PEP 440). tablespec validate <path> --baseline <old> compares each covered domain's exports across revisions and fails DOM-COMPAT when a breaking change lacks a MAJOR bump. Read-only; no changelog change.

Integration patterns are advisory: only the consumer declares an edge, so bilateral or supplier-side facts cannot be verified. Only separate_ways is enforced. This and the deferral of UMF.kind and subdomain kind came out of a Codex adversarial review of the follow-up plan (BLOCK, 11 blocking findings, all accepted): docs/helix/06-iterate/alignment-reviews/AR-2026-09-15-ddd-follow-up-plan-review.md.

Guidebook and prompts

domains.html domain map (supplier/consumer wording; upstream/downstream stay reserved for lineage per ADR-018). Table pages show each cited term's definition. generate_documentation_prompt(..., glossary=) lists only cited terms.

Docs and governance

ADR-020, ADR-021, FEAT-035, US-051, US-052, SD-035 (surface contract), PRD FR-24.1–24.7, registry/index rows, docs/guide/domains.md, microsite concepts/domains page with a DDD-to-tablespec mapping and sources, CLI reference.

User-facing impact

If you add no domain.yaml:

• Behavior change: directory validation is now recursive. A repo whose tables sit in group folders previously validated zero tables in silence; it will now validate them and may surface real failures. validate_pipeline(..., recursive=False) keeps the old lookup for API callers.
• Breaking: an unknown key on a foreign key now fails at load (previously dropped in silence). No spec in this repo is affected. Check production specs before merging; the one-liner is in the PR conversation.
• Everything else (artifacts, guidebook, prompts, routing, canonical_name, command count) is unchanged.

If you adopt domains: cross-domain references are checked, breaking export changes require a MAJOR bump that consumers must accept, and the guidebook gains the map and term definitions.

Decisions a reviewer should weigh

• Unit is named domain, not context ("context" is the line-of-business axis in this codebase).
• Domains never drive routing (ADR-013 preserved).
• Recursive directory validation changes results for existing grouped layouts.
• One commit carries a throwaway wip: subject; a squash merge makes it moot.

Verification

Check	Result
Full pytest suite	3991 passed, 119 skipped
ruff format --check / ruff check	clean
pyright src	0 errors
Microsite content / link-check	16 / 11 passed

🤖 Generated with Claude Code