Library API and, optionally, Maven Central

[paulhoadley]

The README suggests using PAL as a compiler-course target; a course's own test suite would want to run programs in-process rather than shelling out.

After #25 and #35:

• Public API: Program Loader.load(Reader source, String name), ExitStatus Machine.run(Program, InputStream, PrintStream, PrintStream), plus read access to the final stack for assertions.
• Decide on a module descriptor (module net.logicsquad.pal); it is a single package, so this is cheap.
• Optionally publish to Maven Central under net.logicsquad:pal and show the dependency snippet in the README.

---

Effort: L. Priority: P3. From the September 2026 project review (T26).

[paulhoadley]

Moved to the 1.1 milestone. The API itself is deliberately not going into 1.0.0, but one part of this could not wait, and is done in 6877468.

Done now: the module name. Put on the module path, the jar is an automatic module whose name is derived from the file name, so it was pal — confirmed with jar --describe-module, which reported pal@0.8-SNAPSHOT automatic before the change and net.logicsquad.pal@0.8-SNAPSHOT automatic after it. Had 1.0.0 shipped that way, a 1.1.0 adding module net.logicsquad.pal would have renamed the module and broken anyone's requires pal; — a major break arriving in a minor release. Automatic-Module-Name in the manifest reserves the name, so the eventual module-info.java agrees with what 1.0.0 already promised. The module descriptor decision in this ticket is therefore settled in name, and only the declaration is left.

Deferred: the API. Adding public API is a minor-version change, so nothing is lost by waiting, and there are two reasons to want the wait.

The first is that this ticket's sketch has already drifted from the code: it proposes Loader.load(Reader source, String name) where the method takes an InputStream, and ExitStatus Machine.run(Program, InputStream, PrintStream, PrintStream) where the machine is a constructor plus execute(). Those are easy to reconcile, but they show the shape was sketched rather than designed.

The second is more serious. "Read access to the final stack for assertions" means exposing Datum, which is a sealed interface with five permitted records. Making it public makes the seal a compatibility commitment: a consumer writing an exhaustive switch over Datum would have their compile broken by a sixth type. That is a permanent promise to make at 1.0.0 on behalf of a consumer who does not exist yet. It may still be the right call — but it wants deciding with a real course test suite in front of us, not guessed at to hit a version number. A narrower accessor that does not leak the hierarchy is the obvious alternative worth weighing.

Today PAL is the only public type in the project, so 1.0.0 promises exactly the CLI and the exit-status contract, both of which are now documented and tested.