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. Bump ABI or version constants when a 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.