Skip to content

AGENTS.md

Latest commit

 

History

History
62 lines (43 loc) · 4.26 KB

AGENTS.md

File metadata and controls

62 lines (43 loc) · 4.26 KB
Raw

Koharu Project Rules

Document only durable, repository-specific constraints here. Do not record current file layouts, temporary paths, model inventories, helper names, or other implementation details that may change during a refactor. Normal Rust, TypeScript, testing, formatting, and Git practices are assumed.

Change Policy

  • Never add backward compatibility. When an API, schema, configuration, or ownership boundary changes, update every in-repository consumer and remove the replaced form.
  • Prefer a coherent ownership redesign over aliases, forwarding layers, compatibility parsers, or cosmetic renaming.
  • Keep responsibilities self-contained. Defaults and provider-specific behavior belong to the component that owns them rather than a central list of special cases.
  • Remove dead abstractions and one-use helpers when direct code is clearer.

Source Boundaries

  • Keep safe public APIs separate from unsafe FFI, dynamic loading, and build integration.
  • Do not hand-edit generated or derived source. Change its authoritative input and run the generator.
  • Do not commit credentials, model weights, datasets, generated outputs, or machine-specific artifacts.

ML Architecture

  • Keep a consistent public lifecycle across models while allowing model-specific inputs and outputs.
  • Separate network ownership and weight loading from preprocessing, postprocessing, slicing, and public result types.
  • Avoid pass-through types and layers that do not own a real responsibility.
  • Accept a device abstraction at the model boundary, convert it once, and avoid unnecessary transfers or synchronization.
  • Use the established runtime and variable-store loading paths unless they are proven insufficient.
  • Disable gradient tracking during inference.

Upstream Alignment

  • Keep ports structurally traceable to a commit-pinned authoritative implementation.
  • Preserve checkpoint-affecting names, construction order, parameter paths, tensor layouts, execution order, and postprocessing semantics.
  • Treat missing or unexpected weights as an architecture or parameter-name mismatch before changing the loader.
  • Explain intentional divergences next to the affected code.
  • Compare ports on identical inputs using structured outputs such as shapes, ranges, boxes, scores, masks, and ordering.

Performance

  • Optimize and benchmark the actual target device with representative inputs.
  • Remove redundant transfers, synchronization, allocations, and per-pixel host loops before adding concurrency or caching.
  • Account for asynchronous accelerator execution when timing work.
  • Load assets and warm models outside measured regions.
  • Report the device, input size, baseline, result, and correctness difference.

Verification

  • Optimize for fast development and iteration. By default, run the smallest relevant check or focused test once using the debug profile.
  • Do not run full test suites, repeatedly rerun unchanged tests or builds, or build and test profiles other than debug unless the user explicitly requests it.
  • Run end-to-end tests only when the user explicitly asks for them.

Desktop UI Debugging

  • The default Windows debugging setup must define WEBVIEW2_ADDITIONAL_BROWSER_ARGUMENTS=--remote-debugging-port=4000 before launching Koharu. Treat http://127.0.0.1:4000 as the default local CDP endpoint.
  • Connect chrome-devtools-mcp with --browser-url=http://127.0.0.1:4000 and prefer its tools for WebView inspection and automation. Use semantic targets and observable conditions instead of coordinate-only actions or fixed delays.
  • Use a lower-level CDP client only when chrome-devtools-mcp does not expose a required protocol operation. Use native window capture when CDP cannot observe the composited desktop output.

Desktop Rendering

  • Koharu composites native WGPU-rendered canvas pixels beneath a transparent WebView. Preserve WebView transparency wherever native output must remain visible, keep interface rendering in the WebView and canvas rendering in WGPU, and validate their final composition through the desktop window rather than either layer alone.

Documentation

  • Comments should explain ownership, invariants, upstream mapping, or deliberate divergence; do not narrate straightforward code.
  • Keep this file focused on long-lived decision rules rather than the current implementation.