chore: drop comments from tsconfig.json, moving their substance to CONTRIBUTING

.changeset/tsconfig-comments.md

@@ -0,0 +1,8 @@
+---
+"@btravstack/entity": patch
+---
+
+Documentation only: the build and publishing rationale that lived as comments
+in `packages/entity/tsconfig.json` moves into CONTRIBUTING, matching the plain
+JSON of `tsconfig.consumer.json`. A stale block describing a consumer-side
+TS4020 hazard — fixed by the exported `ConstructionKey` seal — is dropped.

CONTRIBUTING.md

@@ -37,11 +37,35 @@ Run `pnpm format` (no `--check`) to auto-fix formatting.
 ### Type-level tests
 
 Behaviour that only shows up at the type level — the construction seal, the
-generated/immutable compile-time rules, `add`'s contextual typing — is pinned
-in `packages/entity/src/*.test-d.ts` and checked by
+generated/immutable compile-time rules, `computed`'s contextual typing — is
+pinned in `packages/entity/src/*.test-d.ts` and checked by
 `tsc --noEmit -p tsconfig.test-d.json` (run as part of `pnpm typecheck`). If
-you change a type-level guarantee, update or add the matching `@ts-expect-error`
-assertion.
+you change a type-level guarantee, update or add the matching
+`@ts-expect-error` assertion.
+
+`*.test-d.ts` files are excluded from the main `tsc` pass by
+`tsconfig.json`, so that pass can keep `noUnusedLocals` strict while the
+assertions declare bindings they never read.
+
+### The consumer pass
+
+`pnpm typecheck` ends with `tsc -p tsconfig.consumer.json`, which compiles
+`packages/entity/consumer/` **with declaration emit, against the built
+`dist/*.d.mts`** — a stand-in for a downstream library. That is the only
+configuration that catches a private name leaking out of the published types
+(`TS4020`), because this repo's own `tsc` pass is `noEmit` and never emits
+declarations. Both of that config's overrides are load-bearing; the fixture's
+own doc comment says why.
+
+### Publishing settings
+
+`declarationMap` is off in `packages/entity/tsconfig.json`: `files: ["dist"]`
+excludes `src/`, so published declaration maps would be dead-ends (broken
+go-to-definition). Consumers get the TSDoc'd `.d.ts` instead.
+
+Declaration settings reach further than they look — `tsdown` reads that
+tsconfig for its `--dts` emit, so what is set there shapes the _published_
+types, while the plain `tsc` pass is `noEmit` from the shared base.
 
 ## Design rules (binding)
 

packages/entity/tsconfig.json

@@ -3,23 +3,9 @@
   "compilerOptions": {
     "outDir": "./dist",
     "rootDir": "./src",
-    // `files: ["dist"]` excludes `src/`, so published declaration maps would be
-    // dead-ends (broken go-to-definition); consumers get the TSDoc'd d.ts.
     "declarationMap": false,
-    // Declaration settings reach further than this file. tsdown reads this
-    // tsconfig for its `--dts` emit (the `build` script) — the plain `tsc` pass
-    // is `noEmit`, inherited from the base — so what is set here shapes the
-    // *published* d.ts. That matters for the construction seal: `src/types.ts`
-    // seals classes with the module-private `CtorKey` symbol, and a consumer
-    // that exports an entity subclass with `declaration: true` gets TS4020
-    // ("'extends' clause of exported class has or is using private name") on
-    // `CtorKey` and `BaseInstance`. Measured against TypeScript 5.9.3 and
-    // 7.0.2 with the built d.ts. Note the base sets `declaration: true`, not
-    // `false` as the `CtorKey` comment in `src/types.ts` still says.
     "types": ["node"]
   },
   "include": ["src/**/*"],
-  // Type-level assertions get their own relaxed pass via tsconfig.test-d.json
-  // (see the `typecheck` script) — the main pass keeps noUnusedLocals strict.
   "exclude": ["node_modules", "dist", "src/**/*.test-d.ts"]
 }