# Module System Policy

Default stance:

- **Services and shared libraries** ship as ESM (`"type": "module"`) with
  TypeScript `module`/`moduleResolution` set to `NodeNext`.
- **Jest configs** stay in `.cjs` but must treat `.js` and `.ts` as ESM (use
  `ts-jest/presets/default-esm` where TS is involved).
- **`.cjs` files** are allowed only for compatibility shims (e.g., adapters
  around third-party CommonJS code).

Guidelines:

- When adding a new service, use the scaffold (`scripts/scaffold-service.sh`)
  which emits ESM-ready package metadata and Jest config.
- Prefer `import`/`export` everywhere; if a legacy CommonJS dependency is
  unavoidable, isolate it in a `.cjs` wrapper or use `createRequire`.
- Always include explicit file extensions in relative imports (`./foo.js`) to
  keep NodeNext resolution predictable.
- Share code via published/shared packages (token-core, meditation-core,
  transaction-core, common, lib) instead of cross-importing another service’s
  source.
