Close materialization boundary proof

[flyingrobots]

Refs #628

Summary

• expand the materialization fallback trap used by checkpoint-tail optic conformance tests to reject materialize(), _materializeGraph(), getNodes(), and getEdges()
• keep the query read-model seam guard focused on provider construction while preserving explicit Observer read-model contract assertions

Deterministic evidence

• Canonical fixture: test/conformance/fixtures/V17MaterializationFallbackTrap.ts
• Behavior witness: test/conformance/v17CheckpointTailOpticReadBasis.test.ts
• Source-shape witness: test/conformance/queryReadModelSeam.test.ts

Validation

• npm exec vitest run test/conformance/v17CheckpointTailOpticReadBasis.test.ts
• npm exec vitest run test/conformance/v17CheckpointTailOpticReadBasis.test.ts test/conformance/v18FirstUseOpticsHonesty.test.ts test/conformance/queryReadModelSeam.test.ts
• npm run typecheck
• npm run lint -- --quiet test/conformance/fixtures/V17MaterializationFallbackTrap.ts test/conformance/queryReadModelSeam.test.ts
• bash scripts/check-anti-sludge.sh test/conformance/fixtures/V17MaterializationFallbackTrap.ts test/conformance/queryReadModelSeam.test.ts
• npm run test:local
• pre-push firewall: link check, lint, markdown gates, source/test/consumer/surface typechecks, policy check, unit tests

ADR checks

• This PR does not implement ADR 2 without satisfying ADR 3
• This PR does not touch persisted op formats; no ADR 3 readiness issue is required
• This PR does not touch wire compatibility; canonical-only wire-op rejection is unchanged
• This PR does not touch schema constants; patch and checkpoint namespaces are unchanged

Summary by CodeRabbit

• Tests
  • Enhanced conformance test infrastructure to validate a broader range of materialization-related methods, improving test coverage and validation accuracy.
  • Refined query read model conformance testing to provide more granular assertions on query pattern validation.

[coderabbitai]

Wondering what really moved? Review this PR in Change Stack to inspect semantic changes, definitions, and references.

📝 Walkthrough

Walkthrough

The PR enhances test infrastructure for materialization validation by expanding V17MaterializationFallbackTrap to intercept multiple graph API methods (materialize, _materializeGraph, getNodes, getEdges) instead of just _materializeGraph. The query read model seam test assertions are refined to validate rejection patterns against a narrowed source set while separately confirming observer source contains expected providers.

Changes

Test Materialization Fallback Validation

Layer / File(s)	Summary
Expanded materialization fallback trap test/conformance/fixtures/V17MaterializationFallbackTrap.ts	Type definitions establish forbidden method names, and the trap class creates a frozen array of spies—one per forbidden method—each configured to reject with method-specific error. expectUnused() now validates that none of the forbidden spies were called.
Query read model seam validation test/conformance/queryReadModelSeam.test.ts	Full-graph-shape rejection test narrows the concatenated source set to exclude observerSource when applying negative pattern matches, then adds explicit positive assertions that observerSource contains QueryReadModelProvider and openQueryReadModel.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Possibly related issues

• #628: The expansion of V17MaterializationFallbackTrap to intercept multiple materialization methods directly implements the materialization-trap mechanism described in the related conformance specification.

Poem

🐰 A trap that catches not one, but four methods with care,
Spies frozen in place, watching materialization's lair,
Each method rejects with a message so fine,
And observers confirm that the query read models align! ✨

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title 'Close materialization boundary proof' clearly relates to the main purpose of the PR: expanding the materialization fallback trap to close a boundary gap in API surface validation.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description check	✅ Passed	The pull request description includes all required sections from the template: Summary, Issue reference (#628), comprehensive Test plan with multiple validation steps, and ADR checks with all items explicitly addressed.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch materialization-boundary-closeout

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[github-actions]

Release Preflight

• package version: 18.0.0
• prerelease: false
• npm dist-tag on release: latest
• npm pack dry-run: passed
• jsr publish dry-run: passed

If you tag this commit as v18.0.0, release workflow will publish.

[flyingrobots]

Code Lawyer Activity Summary

@codex please confirm the remaining merge-gate interpretation.

#	Severity	Source	File / Surface	Issue	Red	Green	Verify	Commit	Outcome
1	P4	PR / CodeRabbit metadata check	PR #642 body	ADR applicability section was missing from the PR description	`gh pr view 642 --json body --jq .body	grep -q ^##\ ADR\ checks$` failed	Edited PR body to include explicit ADR applicability checks	Same body check passed; CI issue-reference rerun passed	N/A metadata-only

No code defects were found in the self-audit of origin/main...HEAD. Existing code commit remains 70e99073.

Validation after the metadata fix:

• npm run lint
• npm run typecheck
• npm exec vitest run test/conformance/v17CheckpointTailOpticReadBasis.test.ts test/conformance/v18FirstUseOpticsHonesty.test.ts test/conformance/queryReadModelSeam.test.ts
• npm run test:local
• gh pr checks 642 --repo git-stunts/git-warp

Status: local validation green, CI green, no unresolved review threads observed before closure.