🌳 fix: keep the Symbol.metadata install through tree-shaking

`sideEffects` named metadata.js, the module holding the global install, but not the
barrel that re-exports it. A side-effect-free barrel is droppable whole, so every
bundler pruned the `export * from './metadata.js'` edge before metadata.js's own
marking was ever consulted, and the install vanished.

Measured on `import { configure } from 'cereale'`: 145 bytes through esbuild, 143
through webpack, 144 through rollup, with `Symbol.metadata` absent from all three.
It matters because tsc's decorator emit reads the well-known symbol directly —

    const _metadata = typeof Symbol === "function" && Symbol.metadata
      ? Object.create(null) : void 0;

so without it a decorated class is handed `metadata: undefined` and ends up with no
rules at all. Two places in the source promised this survived bundling; it did not.

index.js and index.ts are listed now. The cost is ~100 bytes and lands only on
imports that reach nothing else: the single-decorator, validateSync, toPlainSync,
toInstanceSync and whole-library cases are byte-identical before and after, across
all three bundlers. dist/cjs needs nothing — tsc emits `__exportStar(require(...))`,
an unconditional statement no bundler can drop.

Two new cases in treeshake.test.ts pin it, one on src and one on dist/esm, since
those are separate manifest paths and a typo in either is invisible from the other.
Both were checked by removing the entry and watching them fail.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01SAcqrz3FcadkYr3xG32CjK

src/metadata.ts

@@ -15,8 +15,22 @@ import type { ClassConstructor } from './interfaces.js';
  */
 const METADATA_KEY: symbol = (Symbol as { metadata?: symbol }).metadata ?? Symbol.for('Symbol.metadata');
 
-// Also installed globally, because a consumer's own compiler emit may read `Symbol.metadata`
-// directly. package.json marks this module as having side effects so it survives bundling.
+// Also installed globally, because a consumer's own compiler emit reads `Symbol.metadata`
+// directly and does not share our fallback. tsc emits
+//
+//   const _metadata = typeof Symbol === "function" && Symbol.metadata ? Object.create(null) : void 0;
+//
+// so on a runtime without the well-known symbol the class is decorated with `metadata:
+// undefined` and ends up with no metadata at all. (esbuild's `__knownSymbol` has the same
+// `Symbol.for` fallback we do and needs nothing from us; tsc does.)
+//
+// `sideEffects` in package.json is what keeps this statement through bundling — and it has to
+// name `index.ts`/`index.js` as well as this module. Marking only this one is not enough: the
+// barrel is then itself side-effect-free, so a bundler drops the `export * from './metadata.js'`
+// edge before this module's own marking is ever consulted, and the install silently vanishes.
+// Measured on `import { configure } from 'cereale'`: absent from all three of esbuild, webpack
+// and rollup until the barrel was listed too. It costs ~100 bytes, and only for imports that
+// pull in nothing else — every entry point that touches a model was already byte-identical.
 ((Symbol as { metadata?: symbol }).metadata as symbol | undefined) ??= METADATA_KEY;
 
 export interface ValidationArguments {

src/treeshake.test.ts

@@ -117,6 +117,27 @@ describe('tree-shaking', () => {
     expectShaken(code, [MARKER.validator], [MARKER.serializer, MARKER.deserializer, MARKER.isString]);
   });
 
+  /**
+   * The `Symbol.metadata` install at the top of metadata.ts is a bare statement, not an export,
+   * so it survives only because `sideEffects` names that module — and naming it is one hop short
+   * of enough. The barrel that re-exports it is side-effect-free too, so a bundler prunes the
+   * `export * from './metadata.js'` edge before metadata.js's own marking is ever consulted.
+   *
+   * Nothing notices, in the usual way. `import { configure } from 'cereale'` came out at 145
+   * bytes through esbuild, 143 through webpack and 144 through rollup with `Symbol.metadata`
+   * absent from all three — and a tsc-compiled consumer on a runtime without the well-known
+   * symbol is then decorated with `metadata: undefined`, which is to say with no rules at all.
+   */
+  it('installs Symbol.metadata even when nothing model-shaped is imported', async () => {
+    const code = await bundle(`
+      import { configure } from CEREALE;
+      export const f = (o) => configure(o);
+    `);
+
+    expect(code, 'the Symbol.metadata install was pruned along with the barrel').toContain('Symbol.metadata');
+    expectShaken(code, [], [MARKER.isString, MARKER.serializer, MARKER.deserializer, MARKER.validator]);
+  });
+
   it('costs almost nothing to import only an error helper', async () => {
     const code = await bundle(`
       import { flattenErrors } from CEREALE;
@@ -160,6 +181,22 @@ describe('tree-shaking', () => {
       expect(code.length).toBeLessThan(3000);
     });
 
+    /**
+     * The source-level case above proves the `sideEffects` mechanism works; this one proves the
+     * two entries are spelled the way the published tree is laid out. `./src/index.ts` and
+     * `./dist/esm/index.js` are separate paths in the manifest, and a typo in either is invisible
+     * from the other side.
+     */
+    it.runIf(built)('installs Symbol.metadata from the published barrel too', async () => {
+      const code = await bundle(`
+        import { configure } from ${JSON.stringify(path.join(dist, 'esm/index.js'))};
+        export const f = (o) => configure(o);
+      `.replace('CEREALE', 'unused'));
+
+      expect(code, 'the Symbol.metadata install was pruned from dist/esm').toContain('Symbol.metadata');
+      expectShaken(code, [], [MARKER.isString, MARKER.serializer, MARKER.deserializer]);
+    });
+
     it.runIf(built)('keeps its purity annotations through minification', async () => {
       const flat = readFileSync(path.join(dist, 'cereale.min.js'), 'utf8');
       const perModule = readFileSync(path.join(dist, 'esm/decorators.js'), 'utf8');