Plan immutable domain value types with Valibot schemas (1.3.1)

[lodyai]

Summary

This PR adds the ExecPlan for roadmap item 1.3.1 — "Define and validate the core domain value types". It contains no production code; it is the approval draft of the plan that will guide implementation.

The plan is in docs/execplans/1-3-1-immutable-types-with-valibot-schemas.md and proposes implementing RunState, Resources, TechDebtVector, AllocationPolicy, EthicsPolicy, AlignmentState, ProgressionState, and UnlockLedger as immutable, schema-first TypeScript value types under src/domain/model/, validated with Valibot v1.2 and property-tested with fast-check v4.

Status: DRAFT — the plan must be approved before any implementation begins. This PR is the review vehicle for that approval gate.

Key design decisions

• Schema-first: Valibot schemas are the single source of truth; TypeScript types are derived with v.InferOutput, so type/schema drift is structurally impossible.
• AllocationPolicy sum-to-100: the eight allocation fields are non-negative integer percentage points, and the sum-to-100 rule is enforced in the schema via v.check, making the equality check numerically exact (no float-summation pitfall). The schema is the single enforcement point; the 2.1.2 validation service will delegate to it.
• Deep immutability: each aggregate schema is wrapped in v.readonly(), with a compile-time DeepReadonly<RunState> assertion that fails tsc if any reachable field is writable.
• Branded scalars (RunId, Seed, Percent, Decimalish, …) via v.brand; Seed is constrained to the 32-bit unsigned range per ADR 005; Decimalish and unbounded numbers carry v.finite().
• RunState's not-yet-owned references (QualityCoverageVector, MacroState, GameEvent, EventResolution, EndingState) are isolated in an un-exported placeholders.ts with a deletion/migration contract, so later items can reshape them without external coupling.

Scope notes

• 1.3.1 introduces no UI, no player-visible strings, and no DOM, so the translatability, WCAG, and Playwright/css-view requirements are satisfied vacuously; bun ff must still pass green. The plan records this explicitly.
• The UI/design reference docs named in the brief (corbusier-design-language.md, daisyui-v5-guide.md, tailwind-v4-guide.md, etc.) are not present in the repository; they concern later UI slices and are recorded under Surprises.

Process

The plan was drafted with assistance from a research/planning agent team (repo-convention extraction and Valibot 1.x / fast-check v4 idiom research via Firecrawl), then reviewed and revised by a Logisphere community-of-experts panel (contracts, structure, failure modes, and alternatives). The revision note at the foot of the document lists the changes the review produced.

Reviewer focus

• Confirm the principal scope judgement: modelling RunState now with isolated placeholder sub-schemas (vs deferring RunState). The roadmap lists RunState as in-scope.
• Confirm the proposed shapes for AlignmentState, ProgressionState, and UnlockLedger, which the HLD names but does not sketch.

References

• ExecPlan: docs/execplans/1-3-1-immutable-types-with-valibot-schemas.md
• Roadmap item 1.3.1: docs/roadmap.md
• HLD "Core aggregates" and ADR 005 (deterministic simulation and parameter packs)
• Lody session: https://lody.ai/leynos/sessions/427ad97b-9952-4c0c-a51e-e122ae4b5b11

🤖 Generated with Claude Code

[sourcery-ai]

Sorry @LodyAI[bot], you have reached your weekly rate limit of 500000 diff characters.

Please try again later or upgrade to continue using Sourcery

[coderabbitai]

Important

Review skipped

Draft detected.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: e3243f90-2a8b-417a-a409-e170670f53e5

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch 1-3-1-immutable-types-with-valibot-schemas

---

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