[IR-P0][WS1] Invariant spec: parity, hydration ABI, and typed null semantics

[0x054]

Problem statement

Current invariants are distributed; Phase 0 needs a consolidated executable spec for IR-first correctness.

Intended invariant

Parity, hydration ABI behavior, and typed-null semantics are specified as non-negotiable rules with testable acceptance criteria.

Scope boundaries

• Invariant specification and acceptance criteria
• No production implementation changes

Deliverable checklist

• Define parity invariants by artifact class
• Define hydration ABI expectations
• Define typed-null bind/fetch invariants
• Map each invariant to planned test harness entry points

Validation plan

Architecture review approval plus documented mapping to CI checks.

Rollback/failure mode

If any invariant is ambiguous, keep issue open and split into clarifying follow-ups.

Roadmap reference

Roadmap reference: docs/plans/2026-06-19-001-ir-first-roadmap.md (Phase 0)

Migration impact

none - Specification-only work; does not directly change user behavior.

Documentation impact

update-existing - Roadmap and migration guide must reflect finalized invariant language and acceptance criteria.

Sync status

Synced with roadmap: 2026-06-19

[0x054]

Roadmap sync update (2026-06-19): IR work branch policy is now explicit -- implementation branches must be created from feat/ir-first and PRs must target feat/ir-first. main promotion is deferred until the full IR program is complete and release-ready.

[0x054]

Phase 0 artifact update (branch feat/ir-first):

• Invariant spec drafted: docs/solutions/patterns/ir-invariants.md
• Source invariants anchored to AGENTS.md, typed-null parity docs, and hydration tests.
  Validation harness references added in tests/test_ir_vectors_contract.py and tests/fixtures/ir_vectors/README.md.
  Roadmap sync updated in docs/plans/2026-06-19-001-ir-first-roadmap.md in same work session.

[0x054]

Completed in PR #75 (merged): #75

Evidence:

• Invariant spec: docs/solutions/patterns/ir-invariants.md
• Cross-reference anchors to AGENTS and existing parity/null/hydration solution docs are included.