nt-lite/docs.md

# nt-lite development notes

nt-lite is a clean-design hobby kernel. It is not a stable compatibility platform. Prefer the right design over preserving old APIs, shims, or compatibility aliases.

## Principles

- Break old code when the new model is better.
- Breaking ABI is encouraged.
- Do not keep compatibility paths unless they have a clear purpose.
- Plan the model before writing the patch.
- Make one architectural move at a time.
- Delete stale paths once the real path works.
- Prefer compile failures over wrappers that hide stale users.
- Keep the tree internally consistent.
- Keep one canonical API for each operation.
- A small patch can still represent the final model.
- Do not land temporary architecture just to make a feature appear to work.
- Put policy in the layer that owns it.
- Shared state should have one clear owner.

## Workflow

- Keep patches reviewable.
- Boot-test meaningful changes.
- Add diagnostics before optimizing.
- Use logs, counters, and assertions instead of guessing.
- Remove stale comments and dead code as part of the same cleanup.
- Treat a fallback as either a supported mode or delete it before it becomes permanent.
- Ask design questions before changing API shape, object lifetime, ownership, cancellation, persistence, or compatibility behavior.
- Do not add a side path to avoid updating callers.
- When changing an interface, update every caller in the same patch.
- When adding a build artifact, update build, packaging, copy, and runtime discovery paths in the same patch.
- Do not count apply checks or syntax-only checks as a real build.
- Be precise about what was actually validated.
- If behavior can be tested cheaply, include a focused runtime test or a visible diagnostic.
- Prefer counters that prove both success and non-use.

## Breaking changes

Breaking changes are allowed. When making one:

1. Define the new model.
2. Move every user to it.
3. Delete the old path.
4. Keep informational ABI or version constants unchanged while no loader or runtime path checks them. Once a version is enforced, bump it whenever the checked contract changes.
5. Let stale users fail to compile.

## Patch expectations for AI agents

- Generate patches from the repository root.
- Paths must be rooted as `code/...`.
- `git apply <patch>` should work from the repository root.
- Do not require `--directory=code`.
- Keep generated artifacts out of the source tree unless requested.
- When asked to provide the full tree, also provide the patch.
- The patch is for review; the full tree is for reproducing the exact baseline.
- Avoid optimistic claims.
- Say exactly whether a change was apply-checked, syntax-checked, built, booted, or runtime-tested.
- Do not introduce compatibility aliases unless they are intentionally supported API.

## Comment style

- Comments explain why, not what the next line already says.
- Use `//` comments only.
- Use sentence case.
- End every sentence with a period.
- Every owned source file should start with a short file comment.
- Every function should have a comment, even if it is only a one-line summary.
- Keep the tone practical and technical.
- Humor is allowed rarely, but never instead of the real explanation.
- Debugging history belongs in comments only when it explains a lasting constraint.
- Document workarounds by saying what looks strange, why it is necessary, and what breaks if it is simplified.
- Avoid trailing comments except for flags, bitfields, register tables, and packed layouts.
- Keep real limitations as normal prose.

## Development lessons

- Ask before changing the shape of an API or the ownership model behind it.
- The right model matters more than minimizing the diff.
- A patch should be small enough to review, but not so small that it creates a temporary model.
- If a compatibility path is not meant to stay, do not add it.
- If the old path is replaced, remove it.
- Ergonomics matter. A clean API should not make common calls annoying.
- Debug by evidence, not by the subsystem that changed most recently.
- Poison values, fault addresses, counters, and reproduction steps are more useful than guesses.
- Performance fixes need tail-latency checks, not only average throughput.
- Diagnostics must reach every active output path that developers rely on.
- Runtime tests should clean up after themselves and say clearly when they use temporary data.
- A passing test should leave the system in a sane state, not only print `PASS`.
- Build integration is part of the feature.
- Packaging mistakes are real bugs, not clerical issues.
- When a change crosses layers, verify every layer that knows about the new object, file, syscall, or artifact.
- Prefer finishing the feature the user needs over endlessly polishing the audit around it.
- Do not hide uncertainty. Say what was checked and what still needs a real build or boot test.

## comments from developer

- 0x%016llX over %p, it looks prettier and is standard.
- never add Ex, it makes me mad, never, rearchitect instead
- i do put a focus on overengineering if it means it will be cleaner and futureproof
- ASK QUESTIONS! never assume you know the right answer, if you do, you are probably wrong
- shift the syscall number table every time you add a syscall, do not append to the end
- do not worry if a patch breaks something, it's better to break, document and fix rather than work around it.