as-contract-cast-smell

as Contract casts are a serializer-bypass smell

The smell

// ❌ WRONG — bypasses the family ContractSerializer seam
const contract = JSON.parse(raw) as Contract;
const contract = JSON.parse(raw) as Contract<SqlStorage>;

Casting JSON.parse(...) directly to Contract looks innocent in review — Contract is a structural interface, so the cast compiles cleanly. The runtime cost is silent: structural arktype validation, IR-class hydration, and polymorphic-slot discriminator dispatch are all skipped, and the program proceeds with a JSON envelope masquerading as a hydrated Contract. That hides the class of bugs TML-2536 surfaced (untagged storage.types entries that crashed downstream consumers).

The fix

Route every on-disk contract read through the family ContractSerializer seam:

// ✅ CORRECT — crosses the family deserializer seam
const raw = await readFile(path, 'utf-8');
const familyInstance = config.family.create(createControlStack(config));
const contract = familyInstance.deserializeContract(JSON.parse(raw) as unknown);

The as unknown half is the explicit JSON.parse → unknown step — JSON.parse is typed any in TS today and the unknown narrowing makes the deserializer call the only place where structural assumptions get checked. This matches the pattern documented in typed-contract-in-tests.mdc.

In production code that already has a Contract value validated upstream and just needs to pass it along, no cast is needed — the existing typing carries through.

Lint scope

The lint:no-contract-cast workspace script enforces the cast-keyword variant of this smell (as Contract and as Contract<...> outside the allowlist). Structural-assignment variants — e.g. const c: Contract = JSON.parse(raw), or passing a JSON.parse'd value into a function whose parameter is annotated Contract — are NOT lint-enforced, because TypeScript's structural typing makes complete coverage arbitrarily hard. The seam-of-record is the lint plus the convention: every on-disk contract read must be a familyInstance.deserializeContract(...) call at the read site, reviewed in PR.