implementation-strategy

name	implementation-strategy
description	Use before editing architecture boundaries, shared IR, host lowering, request/response schema, source mapping, or the JS↔Rust bridge. Trigger when a task could accidentally move logic into the wrong layer, blur the waddler/postgres.js adapter boundary, or weaken unsupported/degradation behavior.

Implementation Strategy

Goal

Produce a small implementation plan that preserves the intended architecture and the current phase boundary.

Use this when

• The task changes shared IR or diagnostics.
• The task changes host lowering or source mapping.
• The task changes the JS plugin ↔ Rust core interface.
• The task touches adapter boundaries between waddler and postgres.js.
• The task introduces a new capability and it is unclear which layer should own it.

Required output

Return a compact strategy with these sections:

1. Target phase
   • Which phase this work belongs to now.
2. Layer ownership
   • Which layer owns the logic.
3. Minimal diff
   • Smallest safe implementation slice.
4. Unsupported / degrade path
   • What stays unsupported and how it is diagnosed.
5. Verification
   • What must be checked before merge.

Rules

• Keep the JS/TS side limited to extraction, span capture, config interpretation, and report formatting.
• Keep semantic SQL analysis in Rust.
• Prefer N-API over WASM for the initial bridge unless the task explicitly requires portability beyond Node.
• Preserve waddler as the easier first adapter; do not introduce postgres.js-specific assumptions into shared IR.
• If a feature cannot be made sound in the current phase, route it to explicit unsupported diagnostics rather than broad heuristics.
• Never convert an explicit unsupported case into silent skip.

Phase guardrails

• Phase 0: shared IR and diagnostics only.
• Phase 1: waddler lowering only.
• Phase 2: parser / normalize / fingerprint only.
• Phase 3: DB-assisted metadata only.
• Phase 4: thin oxlint bridge only.
• Phase 5: limited semantic refinement only.
• Phase 6+: postgres.js adapter and hardening.

Checklist

• Did the plan keep host semantics in the adapter?
• Did it preserve source mapping stability?
• Did it keep parser mismatch and unsupported syntax separate?
• Did it avoid introducing TypeScript type-checker dependence into the JS plugin?
• Did it keep DB access read-only by default?