msd-core/docs/adr/457-generated-cjs-single-source.md

# ADR 457: Generation model for `bin/lib/*.cjs` type safety [Accepted]

- **Status:** Accepted
- **Date:** 2026-05-28 (rewritten and accepted 2026-05-31 after correcting fabricated context)

> **Accepted direction:** build-at-publish (model 2 below). Implementation is
> tracked in a separate migration issue and proceeds module-by-module. The sole
> prerequisite — the ESLint harness (ADR 452) — is already **accepted/merged**.
>
> **Provenance note.** An earlier draft of this ADR (and issue #457) was authored
> by an agent and asserted a codebase state that did not exist — "~13 files
> generated from `.ts` via `tsc`", `gsd-core/src/` / `sdk/src/` source trees,
> and a `tests/cjs-ts-parity.test.cjs`. None of those existed. This rewrite
> grounds the decision in verified ground truth. Do not restore the earlier
> "natural completion of the 13 generated files" framing; it was fiction.

## Context

### What actually exists today (verified 2026-05-31)

- `gsd-core/bin/lib/` holds **84** `.cjs` files. **Exactly one** carries a
  `// @generated` header: `package-identity.cjs`.
- That one generated file is **not** `tsc` output. It is produced by
  `scripts/generate-package-identity.cjs` — a plain Node script that reads
  `package.json` and **bakes literal coordinate values** into a CJS module.
- There is **no** `gsd-core/src/` or `sdk/src/` TypeScript tree. There is
  **no** TS→CJS transpilation pipeline. There is **no**
  `tests/cjs-ts-parity.test.cjs`. The only parity test is
  `tests/issue-498-package-identity.test.cjs`, scoped to the one baked file: it
  regenerates from `package.json` and asserts the committed output is not stale.
- `tsconfig.lint.json` exists with `allowJs` + `checkJs`, but it is **not**
  wired into `eslint.config.mjs`. The `.cjs` config block (`eslint.config.mjs`
  lines 61–92) sets only `sourceType`/`globals` — **no `parser`, no
  `parserOptions.project`, no `projectService`, and no `@typescript-eslint`
  rule** is enabled. A comment on line 60 nonetheless *claims* "Type-aware via
  parserOptions.project=tsconfig.lint.json" — so the file is linted **without**
  type information while the config advertises the opposite.
- `eslint.config.mjs` lists 12 files in `GENERATED_CJS_IGNORES` and treats them
  as generated (never linted) — but those 12 are all **hand-written** (verified:
  none carry an `@generated` header). This is a latent inconsistency: the lint
  config already pretends a generation pipeline exists for them.

So the real situation is: **83 hand-written `.cjs`, 1 value-baked `.cjs`, and a
lint config that already advertises — in a comment and in a 12-file ignore list
— a type-aware generation pipeline that was never built.**

### Two different things are both called "generation"

This distinction is the crux of the decision, and the earlier draft erased it:

- **Value baking (exists, forced).** `package-identity.cjs` must be generated
  because the *installed* tree ships a synthetic `{"type":"commonjs"}`
  `package.json` with no `.name`, so a runtime `require('package.json').name`
  is `undefined` (bug #378). The values literally cannot be read at runtime;
  baking them at build time is the only option. **Deletion test:** remove the
  generator and the complexity reappears across every consumer. It is a deep
  seam and earns its keep.

- **Transpilation (proposed, optional).** Authoring `bin/lib` logic as TS and
  emitting `.cjs` via `tsc`. **Deletion test:** remove it and *nothing*
  reappears — a hand-written `.cjs` and a `tsc`-emitted `.cjs` are behaviorally
  identical at runtime. The seam buys **no runtime leverage**. Its entire value
  is **author-time and CI type checking**.

`package-identity` is therefore **not** precedent for the proposed transpilation
work. They are different techniques with different forcing functions.

### The problem actually worth solving

Type safety on the hand-written runtime surface is **second-class**: type errors
surface (if at all) as lint findings via the un-wired `tsconfig.lint.json`, not
as compile errors. Any contributor — human or agent — adding a `bin/lib` file
must decide hand-write vs generate, with no enforced answer. That inconsistency
is real and grows.

## The decision this ADR must make

Type-checking TS sources is the goal. The load-bearing question the earlier
draft skipped is: **do we check the generated `.cjs` into git, or treat it as a
build artifact?** Three models:

1. **Check in both `.ts` source and `.cjs` output.** Creates a permanent
   "two copies must match" invariant, requiring parity tests, dual commits, and
   a pre-commit/CI drift gate. This is the model the earlier draft assumed —
   inherited from value-baking, where checking in output is *forced*. For
   transpilation, nothing forces it, so this imports maximum friction for no
   runtime gain.

2. **Build at publish (recommended).** `bin/lib/*.cjs` becomes a gitignored
   build artifact emitted from a TS `src/` tree by `tsc`; npm publishes the
   built output. **Feasible today:** `package.json` already ships `gsd-core`
   and `scripts` via its `files` array, and already runs a pre-publish build
   step (`"prepublishOnly": "npm run build:hooks"`) — the `.cjs` emit hooks into
   the same step, and `npm pack` includes on-disk artifacts regardless of
   `.gitignore`. No drift invariant, no parity test, no dual commits — the
   "Negative" consequences below mostly evaporate. Cost: contributors run a
   build to exercise local changes, and CI must build before test.

3. **Build at install.** Rejected: fragile across Node versions and platforms
   (CONTEXT.md notes Windows / Node 24 hazards) and slows every install.

## Decision [Accepted]

1. **Pursue type safety via a TS `src/` tree compiled with `tsc`**, adopting
   **model 2 (build at publish)**: TS source is canonical, `.cjs` is a
   gitignored artifact. This dissolves the drift-policing machinery rather than
   building it.
2. **Keep value baking separate.** `package-identity.cjs` stays a checked-in
   baked artifact under its existing generator and parity test; the install-tree
   #378 constraint is unaffected by this ADR.
3. **Migrate incrementally, lowest-coupling module first**, behind one pilot PR
   that stands up the `src/` tree + build wiring for a single module before any
   bulk move.
4. **Reconcile the lint config to reality first.** The 12-entry
   `GENERATED_CJS_IGNORES` list currently lies about hand-written files; it must
   be corrected (those files linted as hand-written) before, not after, a
   pipeline exists — otherwise the inconsistency masks the migration's progress.
5. **Wire type-aware linting** to the real `tsconfig.json` as modules become TS;
   retire `tsconfig.lint.json` only when the last hand-written `.cjs` is gone.

## Consequences

### Positive
- Type-aware `typescript-eslint` rules apply to migrated runtime code.
- No checked-in generated `.cjs`, so **no** drift invariant and **no** parity
  test to maintain for the transpiled surface (contrast: the rejected model 1).
- One enforced answer to "hand-write or generate?" for new `bin/lib` code.

### Negative
- A build step now sits between editing `src/*.ts` and running `bin/lib/*.cjs`.
  Local dev and CI must build before exercising runtime behavior.
- Migration touches ~83 files; each may surface latent type errors to fix.
- Tooling that today reads `bin/lib/*.cjs` from a checkout (not an install) must
  build first or read from `src/`.

### For testing
- Tests importing `bin/lib/*.cjs` keep working **only if** the build has run;
  the test command must depend on the build. This is the main behavioral change
  versus today, where the `.cjs` is always present in the tree.

## Rejected Alternatives

- **(a) Keep the split indefinitely** — leaves the type-aware gap and the
  un-wired `tsconfig.lint.json` permanently. Rejected as a final state.
- **(b) Check in `.ts` + generated `.cjs` (model 1)** — imports a drift
  invariant, parity tests, and dual commits for zero runtime benefit. Rejected
  in favor of build-at-publish.
- **(c) Full ESM rewrite** — breaks `require()` consumers (no `"type":"module"`
  today); semver-major. Out of scope.
- **(d) Wire `tsconfig.lint.json` into ESLint and stop there** — keeps the
  stopgap permanent and never delivers compile-level (vs lint-level) type
  errors. Rejected as the final state, but acceptable as an interim while the
  pilot proves out.

## Open questions

- Does any consumer rely on `bin/lib/*.cjs` being present in a raw (un-built)
  checkout? If so, build-at-publish needs a `prepare`-script bridge.
- `tsc` CJS interop details (`esModuleInterop`, `__importDefault` shims) for the
  modules that re-`require` each other.
- Whether the pilot should be a leaf utility or one of the 12 mislabeled
  `GENERATED_CJS_IGNORES` files (which already advertise themselves as generated).

## References

- ESLint harness prerequisite (**accepted**): `452-eslint-lint-harness.md`
- Test-rigor policies (**accepted**): `456-test-rigor-architecture.md`
- Single-runtime collapse (**accepted**): `0174-retire-gsd-sdk-package-boundary.md`
- Superseded shared-module seam: `3524-cjs-sdk-hard-seam.md`
- Tracking issue: [#457](https://github.com/open-gsd/gsd-core/issues/457)
- Value-baking precedent (distinct technique): `scripts/generate-package-identity.cjs`,
  `tests/issue-498-package-identity.test.cjs`