w1n5t0n/memlnaut-nisps
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
memlnaut-nisps/firmware/MEMLNaut-NISPS/lib/memllib/reference/README.md
monkey-w1n5t0n 1f0eecfe78 docs(firmware): vendor InterfaceRL as read-only reference 
InterfaceRL.{hpp,cpp,tpp} + InterfaceRLFileFormat.hpp are the upstream
reference implementation of the entire NISPS feedback subsystem —
nisps/ml/{geo_push,replay,feedback,jolt,ou_noise}.hpp are all ports of it,
several still carrying `// upstream InterfaceRL.hpp:NNN` line references.
The Phase-4 vendoring dropped examples/ because nothing compiled it. That
was correct for the build and wrong for the codebase: with the source of
truth out of tree, upstream redesigned the geometric dislike (deleted the
/(1+len) taper, doubled kGeometricPushScale, tripled the negative-LR base,
moved to batch training over all negatives every tick) and we did not notice
for months.

Copied verbatim from memllib @ e291192 — the same commit the rest of the
vendored tree pins — into lib/memllib/reference/, which sits OUTSIDE src/
and is therefore never compiled: PlatformIO's LDF only recursively builds an
Arduino-format library's src/ folder. Verified: slpworkshop still builds
(RAM 28.8%, flash 2.1%).

reference/README.md states the two rules (never compiled, never edited — a
divergence from upstream is a recorded decision, not an edit here) and
VENDORED.md's "what was dropped" section now tells the truth.

Resolves ALIGNMENT defect 6c.
2026-07-25 11:14:35 +02:00

1.8 KiB
Raw Blame History

reference/ — upstream source of truth, never compiled

These four files are examples/InterfaceRL.{hpp,cpp,tpp} + examples/InterfaceRLFileFormat.hpp, copied verbatim from MusicallyEmbodiedML/memllib at commit e291192d8e4f2fca7b79670c4df9c2ec8bdf03cd — the same commit the rest of this vendored tree pins (see ../VENDORED.md).

Why they are here

InterfaceRL is the reference implementation of the whole NISPS feedback subsystem. nisps/ml/geo_push.hpp, nisps/ml/replay.hpp, nisps/ml/feedback.hpp, nisps/ml/jolt.hpp and nisps/ml/ou_noise.hpp are all ports of it, and several of them still carry // upstream InterfaceRL.hpp:NNN line references.

The Phase-4 vendoring dropped examples/ because nothing compiled it. That was correct for the build and wrong for the codebase: with the source of truth out of tree, upstream redesigned the geometric dislike (deleted the /(1+len) taper, doubled kGeometricPushScale, tripled the negative-LR base, moved to batch training over all negatives every tick) and we did not notice for months. Keeping these files in-tree turns the next upstream drift into a diff instead of an archaeology session.

Rules

  • Never compiled. This directory sits OUTSIDE ../src/, and PlatformIO's Library Dependency Finder only recursively compiles an Arduino-format library's src/ folder (../VENDORED.md explains that mechanism at length). Do not move these under src/ and do not add them to any build.
  • Never edited. They are upstream's bytes. Our behaviour lives in nisps/ml/. A divergence from upstream is a decision recorded in ALIGNMENT.md or a task, not an edit here.
  • Re-sync with the rest of the tree, in the same step and to the same commit — ../VENDORED.md § "Re-syncing with upstream".