# Repository Guidelines

Canonical entry point for contributors and coding agents in `dowdiness/incr`. Read before making changes.

## Project Overview

`incr` is a Salsa-inspired incremental recomputation library in MoonBit. A MoonBit workspace: the library lives under `incr/`, checked docs under `docs/`, examples under `examples/`. See [`docs/architecture.md`](docs/architecture.md) for the package map.

Target facades: `Input`, `Derived`, `ReachableDerived`, `DerivedMap`, `InputField`, `EagerDerived`, `Effect`, `Relation`, `MapRelation`, `Accumulator`, `Scope`, plus `RuntimeContext` / `Freshness` / `InputFieldOwner`. Legacy names (`Signal`/`Memo`/`TrackedCell`/`Reactive`/`FunctionalRelation`/`Database`) are gone — see CHANGELOG for mapping.

## Project Structure

```
moon.work                   ← Workspace root
incr/                       ← Library module
  incr.mbt, traits.mbt      ← Root facade (re-exports + `create_*` helpers)
  types/                    ← Pure value types (CellId, Revision, ReadError, …)
  cells/                    ← Engine: handles, Runtime coordinator
  cells/internal/           ← shared, pull, push, datalog, kernel (compiler-enforced)
  tests/                    ← Integration tests against the public API
docs/                       ← Checked docs workspace member + docs/README.md index
examples/                   ← Standalone workspace modules
scripts/                    ← check-engine-isolation.sh, check-workspace-boundaries.sh, bump-version.sh
```

Tests inside `incr/cells/` live beside source: `*_test.mbt` (black-box) and `*_wbtest.mbt` (white-box, same package). Generated `pkg.generated.mbti` files are regenerated by `moon info` — never edited by hand.

## Build & Test

```bash
moon check          # Type-check; run after every edit
moon build          # Compile
moon test           # Full suite (~1205 test blocks)
moon bench --release
moon fmt            # 2-space indent; `moon fmt` enforces all formatting
moon info           # Regenerate all pkg.generated.mbti files
```

Targeted: `moon test incr/cells/<file>` or `moon test incr/tests`.

CI: `.github/workflows/ci.yml` — runs `moon check` + `moon test` on library, checked docs, and examples (pinned MoonBit toolchain). The parent `canopy` repo also exercises `incr` transitively.

## Coding Style

- Types/traits: `PascalCase`. Methods: `Type::method`. Variables/tests: `snake_case`. Constants: `SCREAMING_SNAKE_CASE`.
- `///` doc comments on every `pub` item in non-test files.
- No tests in `internal/` packages — they block `pub using` facades. Put structural tests alongside source in `cells/`; integration tests in `tests/`.

## Documentation Rules

Code is the source of truth. When docs and code disagree, the doc is wrong — fix or delete it.

| Content | Location |
|---|---|
| Quick pitch, install, minimal example | `incr/README.mbt.md` |
| Tutorial | `docs/getting-started.mbt.md` |
| Concepts, patterns, API reference | `docs/concepts.mbt.md`, `docs/cookbook.mbt.md`, `docs/api-reference.mbt.md` |
| Architecture, design internals | `docs/architecture.md`, `docs/design/internals.md` |
| ADRs, specs, plans | `docs/decisions/`, `docs/design/specs/`, `docs/plans/` |

When adding a doc file, update `docs/README.md` in the same commit.

### Documentation Lifecycle

Current reader docs remain. ADRs are durable and superseded rather than deleted. Completed or superseded plans, research, and unneeded snapshots are deleted; Git history is the recovery path. Every new time-bounded document must state **Reader**, **Decision**, **Keep until**, and **Disposition**. Update the docs index and local links when deleting documentation.

## Comment Rules

Default: no comment. Only add one for the *why* — invariant, workaround, interaction effect, performance constraint. Never restate code in a comment. Public APIs get `///` doc comments with behavior summary and error notes.

## Pre-PR Checklist (in order)

1. `moon fmt` → 2. `moon info` (inspect the `.mbti` diff) → 3. `moon check` → 4. `moon test` → 5. Update `docs/` and `CHANGELOG.md` if API or behavior changed → 6. Ensure no `.mbti` file was hand-edited

### Documentation disposition

- [ ] Reader, decision, and disposition confirmed
- [ ] Completed docs removed or compressed into an ADR
- [ ] Roadmap contains only current work
- [ ] Local links and the docs index updated

### Deprecation status (MoonBit v0.10.0+)

All migrated — no new code should use:
- `@hashmap.new()` / `@hashset.new()` / `@priority_queue.new()` / `Ref::new(x)` → use `HashMap([])` / `HashSet([])` / `PriorityQueue([])` / `Ref(x)`
- `Show`-based `inspect` on containers → use `debug_inspect`
- `gc_tracked(rt, t)` → removed no-op; use `add_input_fields` / `scope.adopt`
- `fn new(..)` inside struct body → use separate `fn Type::Type(...)` toplevel
