Allow target-native files to override generated output

Status: Accepted Date: 2026-05-29

Context

Some target behavior cannot be generated faithfully from a Claude component. In particular, Pi integrations sometimes require target-specific TypeScript extensions or other glue that has no source-format equivalent. Keeping those files outside the source plugin made the conversion incomplete; embedding them in generic generation logic made target behavior harder to maintain.

Evidence: PR #16, merged as 0218de2cd0f393a95a49557d1f2958a52a8145f9, records the custom Pi extension use case and the explicit collision rule.

Decision

A source plugin may contain targets/<target>/... files. The selected emitter copies those files to the target's natural root after generated output, so a target-native file wins an exact path collision. Target roots and copied paths must pass containment and symlink checks.

Consequences

Plugins can carry intentional target-specific implementations without weakening the shared IR. Overrides are explicit and reviewable, but they are less portable and must be tested with the target runtime. A native override replaces generated bytes at its exact path; it does not grant ownership of arbitrary pre-existing output.