healer-man/docs/METADATA_DISCOVERY.md

macOS metadata and source discovery

macOS can create AppleDouble companions whose path components start with ._. These files contain filesystem metadata and are not application source. On the external-drive review checkout, the former Vitest include pattern selected src/avatar/._*.test.ts files and attempted to transform their binary contents. TypeScript 5.8 already skips the tested dot-prefixed paths with its existing src include. Its new explicit exclusions document the same metadata policy while preserving compiler options and ordinary input discovery.

Shared source issue #11 owns the default discovery correction:

• vite.config.ts retains configDefaults.exclude and adds **/._* plus **/._*/** to the test exclusions.
• tsconfig.app.json retains its compiler options and include: ["src"]. Its exclusions retain the package-directory defaults and add the same metadata patterns.

The two patterns cover companion files and files inside a companion directory, including nested directories. A component must start with ._; ordinary underscore names and names containing those characters elsewhere remain source. Existing metadata files are retained. This changes root input discovery; TypeScript's normal handling of explicit imports still applies.

tools/verify-appledouble-metadata-discovery.mjs supplies a focused regression proof through actual Vitest discovery/execution and TypeScript configuration input parsing. It uses fresh task-owned fixtures to verify the rejection path and two ordinary test sentinels to verify continued execution. It does not certify full application typechecking, a browser production build, gameplay, balance, character rendering or dungeon behavior.

Exact commands, input identities and observed results accompany the issue and metadata-discovery-validation.json. Shared source issue #9 still owns its separate browser build/live visual acceptance gap. Native checkpoint #292 is already installed and merged. This tooling change requires no native runtime rebuild: the native writable source mirror is a subset without these browser configs.

Run the focused proof after installing the repository dependencies:

node tools/verify-appledouble-metadata-discovery.mjs --evidence-dir /absolute/fresh-path

Use a fresh absolute path outside the checkout. The helper keeps its fixtures and reports; it refuses existing destinations, overlap and symlink paths. It works from another current directory and uses the Node executable that launched it. The final external-drive control records three binary metadata transform failures; fixed Vitest defaults run both ordinary tests. TypeScript API and CLI resolve the same two ordinary inputs, with and without the explicit metadata filters. The Vite/Node configuration typecheck passes.