From a2698fb51a803edde735e50fd153b287631c72a9 Mon Sep 17 00:00:00 2001 From: Ajay Ghanwat Date: Wed, 19 Aug 2026 15:58:05 +0530 Subject: [PATCH] docs: correct the api block spec's type-enforcement mechanism Assertions in a .d.ts are inert under skipLibCheck: true, which the root tsconfig sets. Proven during implementation by forcing skipLibCheck: false, where the same assertion fires as TS2344. They move to a generated .ts file, which skipLibCheck does not exempt. Co-Authored-By: Claude Opus 5 --- .../specs/2026-08-19-typed-api-block-design.md | 16 ++++++++++++---- 1 file changed, 12 insertions(+), 4 deletions(-) diff --git a/docs/superpowers/specs/2026-08-19-typed-api-block-design.md b/docs/superpowers/specs/2026-08-19-typed-api-block-design.md index 3a6b980f..b05ba5ac 100644 --- a/docs/superpowers/specs/2026-08-19-typed-api-block-design.md +++ b/docs/superpowers/specs/2026-08-19-typed-api-block-design.md @@ -42,7 +42,7 @@ These are implementation facts, not gaps in documentation: | Execution | Decided by the enclosing mode, not a modifier | | Request values | Declared fields, supplied at the call site | | Type source | Route contract when available, declared types otherwise (with a warning) | -| Type enforcement | `tsc`, via assertions generated into `wrnexus.generated.d.ts` | +| Type enforcement | `tsc`, via assertions generated into `wrnexus.generated.api-checks.ts` | | Failure | `error {}` converts a failure to a value; without it, the call rejects | ## Syntax @@ -112,8 +112,16 @@ concrete case. `wrnexus build` never invokes `tsc`. **Generated build artifacts are not type-checked.** Compiling the block into a typed client and expecting `tsc` to catch mismatches would therefore check nothing. -What _is_ type-checked is `app/types/wrnexus.generated.d.ts`, which lives under `app/`. Enforcement -goes there. +What _is_ type-checked is application source under `app/`. Enforcement goes there. + +**Corrected 2026-08-19, during implementation.** This section originally placed the assertions in +`app/types/wrnexus.generated.d.ts`. That is inert: the root `tsconfig.json` sets +`skipLibCheck: true`, which exempts the _contents_ of every `.d.ts`, so an assertion written there +can never raise a `tsc` error. Proven by forcing `skipLibCheck: false`, under which the same +assertion fires as `TS2344`. The reasoning was right and the file was wrong. Per-block assertions +are emitted into a real `.ts` file instead — `app/types/wrnexus.generated.api-checks.ts` — which +`skipLibCheck` does not exempt and which `include: ["app"]` compiles. The helper types stay in the +`.d.ts`, where being declarations is correct. ### Three pieces @@ -126,7 +134,7 @@ type ApiInput

= ApiContracts[P][M]["input"]; type ApiOutput

= ApiContracts[P][M]["output"]; ``` -**2. Per-block assertions**, generated into the same file. `wrnexus generate types` already parses +**2. Per-block assertions**, generated into `app/types/wrnexus.generated.api-checks.ts`. `wrnexus generate types` already parses `.wrn` sources to build the route list, so it can read each block's declared fields and emit: ```ts