[jackmisner]

What this does

Makes the module-scope defaults provably pure so a bundler can drop them. A consumer importing one function from the root entry goes from 1,347 bytes to 303.

bundler	before	after
esbuild, static import	1,347	303
Rolldown (Vite 8), static	994	302
webpack 5, static	469	307
webpack 5, require	1,109	516
Rollup, static	362	362 (already pruned)

esbuild and Rolldown cannot prove an array or object spread pure — an array spread invokes an iterator, an object spread can invoke getters — so they retained DEFAULT_CONFIG and everything it reaches even when nothing referenced it. Rollup could already prove it.

This is the first change in the recent sequence to help a CommonJS consumer at all (webpack require, −53%). It also removes the dead top-level statement from dist/server/index.js, the residue of the same spread.

How it is built

DEFAULT_PII_FILTER_CONFIG and DEFAULT_CONFIG are built by non-exported factory functions whose single call site carries the annotation. The spreads inside are character-identical to those on main — the diff shows each one as a -/+ pair differing only by indentation — so the copy semantics are the original code, not a re-expression of it.

That shape was proposed in review, after a first attempt that annotated each copy individually (Object.assign({}, x), x.slice()). Measured, the factory form dominates it for four bytes:

	annotated copies	factory
one-symbol import	303 B	303 B
annotations in defaults.ts	6	2
lost annotation caught by the budget	4 of 6	2 of 2
Object.assign Get/Set hazard	present	none
consumer using the defaults	988 B	992 B

It closes a guard coverage gap rather than documenting one, and removes a hazard — Object.assign reads sources with Get and writes the target with Set, so a getter, a __proto__ key or a Proxy on any of those public constants would have made an annotation false, invisibly to both the tests and the byte budget. Spread syntax cannot be subverted that way.

The invariant that had no coverage

The spreads exist to copy: DEFAULT_CONFIG.sanitize must not alias DEFAULT_SANITIZE_CONFIG, because both are public API and a consumer mutating one default must not change another. Nothing tested that — grep 'DEFAULT_CONFIG\.' __tests__/ returned nothing.

Tests were written first, confirmed passing on unmodified main, then checked against the mistake they exist to catch: replacing the five copies with references. 5 of 8 failed — and all 21 other test files still passed. That mistake was undetectable by 635 tests.

Four of those tests were later removed on review: with no getter or Proxy involved they are strictly implied by the identity assertions, and they were the only tests in the repo writing to exported module state, which CLAUDE.md warns against. One replaced them, pinning what identity does not cover — the patterns array is copied while its member objects stay shared.

The guard, and what it does not cover

scripts/assert-bundle-budget.js runs in check:package. Annotations are comments, so losing one costs every consumer a kilobyte and changes nothing a test can see. It weighs the bundle and executes it, because an annotation on a call that is not pure would license a bundler to drop something needed and nothing else here prunes an entry and runs the result.

Verified: 303 bytes clean; 671 and 1,228 when either annotation is lost; a dist tampered to answer wrongly is caught; a missing build gives a clear message. Stable at 303 bytes on every run across Node 20/22/24/26, aarch64 and x86_64, Debian 12 and 13, and macOS. Costs 0.065s.

It does not cover the two annotations in src/common/keys.ts, worth 153 and 21 bytes: catching 21 would need a ceiling 17 bytes above baseline. A breach is therefore most likely one of the defaults.ts pair, and the prose says so rather than implying full coverage.

What review found in my work

Five reviewers and two claim audits. The substantive catches were all mine to own:

• I verified "the guard catches a lost annotation" against one annotation — a defaults.ts one worth ~920 bytes — and wrote three claims on that sample. The two in keys.ts measure 456 and 324 bytes and pass the 600 budget. The cheapest is worth 21 bytes, not the ~170 I stated.
• I stranded two public doc comments. The factory refactor left "Default configuration with all values set" above a non-exported function, so dist/defaults-*.d.ts shipped a bare declare const DEFAULT_CONFIG while every sibling kept its description — two commits after I had moved an internal note out of those same declarations.
• "A bundler cannot prove a spread pure" was wrong twice. First with the wrong reason (an iterator, which is true of array spreads only), then with the right reason but an overgeneral subject — Rollup can.
• A CLAUDE.md bullet inserted between two others left "The flag saves a consumer bytes..." sitting under a bullet about annotations, referent gone.
• A test comment described a shape that no longer existed once the factory restored the spreads.
• My own archeology grep — the one CLAUDE.md says to run before every commit — tripped on "no longer works" in a script header.

Release implication

Compared against the tarball published on npm as 0.3.2: 73 exports, none added, none removed, no type changes; DEFAULT_CONFIG JSON and key order identical; toSnakeCase parity. Published files +268 B (root), +236 B (react), −13 B (server) to save each consumer up to a kilobyte. That is a patch.

Follow-ups, not in this PR

• A source-level annotation check would cover the two keys.ts annotations no byte budget can reach. Raised in review; it is a different guard from the one agreed, so it is an offer.
• npm run type-check never checks test files. tsconfig.json excludes __tests__, hiding 19 type errors across eight existing test files. This branch's new tests are clean and do not widen it.
• Node 20 cannot run the test suite (vitest workers fail on undici), while engines.node still says >=20.0.0. Pre-existing, documented, and the declared floor remains apart from the testable one.