xln

BrainVault agent contract

Read this file at task start and again after context compaction. It applies only inside this package. The parent repository rules still apply.

Mission

Preserve BrainVault V1 forever. Optimization, portability, UX, and packaging may change. The same semantic inputs must always produce the same root.

Ask the owner before making a new protocol choice. Never reinterpret a frozen constant, encoding, normalization rule, salt, domain, factor, or wallet path.

Work order

  1. Reproduce the smallest observable failure or establish a measured baseline.
  2. For a bug, add the smallest regression test and observe it fail.
  3. Change only the owning layer. Do not refactor unrelated code.
  4. Run the focused test, then bun run check.
  5. Run release-only gates only when a release is explicitly authorized.

Boundaries

CLI / workers / native schedulers
             |
             v
      public wallet API
             |
             v
  ordered canonical root fold
             |
             v
   V1 encoding / salt / KDF

Keep lower-level mechanics behind their existing module. A new export or wider visibility is an API change and requires a concrete caller, test, and rationale.

Code

Do not perform style-only rewrites while fixing behavior. Existing public APIs and boolean parameters remain unchanged unless the task explicitly owns them.

Security

Verification

Never approve from comments or benchmark output alone. Report the exact command, pass/fail counts, root where relevant, and remaining unverified boundary.

Git and releases

Work only on main and only inside brainvault/. Before a commit run git diff --check; before push run bun run check.

Use a concise imperative commit subject. Explain why in the body when the reason is not obvious from the diff.

Never publish, tag, replace an archive, or update a frozen historical hash unless the owner explicitly authorizes that release operation.