@turing-machine-js/library-binary-numbers 2.0.2 → 3.0.1

package/CHANGELOG.md

@@ -0,0 +1,47 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [3.0.1] - 2026-04-30
+
+Released in lockstep with `@turing-machine-js/machine` 3.0.1. No source or behavior changes in this package.
+
+## [3.0.0] - 2026-04-30
+
+### Added
+
+- **`minusOneFast`** — a direct borrow-propagation `minusOne` (10 nodes), an alternative to the existing `minusOne` (17 nodes via `~(~x + 1)`). Both kept side-by-side; the heavier composition-based version is pedagogically valuable.
+- Auto-generated [`states.md`](states.md) — rendered Mermaid graph for every exported state, produced by `src/graphs.spec.ts`.
+- Algorithm-explaining comments in `src/index.ts` (node count, intent, composition trade-offs).
+- Tests for `goToNextNumber` and `goToPreviousNumber` (previously `test.todo`).
+
+### Changed
+
+- **BREAKING** — `@turing-machine-js/machine` is now a `peerDependency` (was a regular `dependency`). With npm 7+ this is auto-installed; with older npm you may need to install it explicitly. The change ensures consumer and library share the same singleton sentinels (`haltState`, `ifOtherSymbol`, etc.) — duplicate copies would break `instanceof` checks and identity equality.
+- Peer-dep range bumped to `^3.0.0` to require the v3 line of the engine.
+- Internal source files now import the bare `@turing-machine-js/machine` (was `@turing-machine-js/machine/src`).
+
+### Migration
+
+If you previously had:
+
+```json
+{ "dependencies": { "@turing-machine-js/library-binary-numbers": "^2.0.2" } }
+```
+
+You should now have both as direct dependencies (npm 7+ does this automatically):
+
+```json
+{
+  "dependencies": {
+    "@turing-machine-js/machine": "^3.0.0",
+    "@turing-machine-js/library-binary-numbers": "^3.0.0"
+  }
+}
+```
+
+## [2.0.2] - earlier
+
+Initial public 2.x release.

package/README.md

@@ -1,50 +1,97 @@
 # @turing-machine-js/library-binary-numbers
 
 [![build](https://github.com/mellonis/turing-machine-js/actions/workflows/main.yml/badge.svg)](https://github.com/mellonis/turing-machine-js/actions/workflows/main.yml)
-![npm (tag)](https://img.shields.io/npm/v/@turing-machine-js/library-binary-numbers)
+[![npm (tag)](https://img.shields.io/npm/v/@turing-machine-js/library-binary-numbers)](https://www.npmjs.com/package/@turing-machine-js/library-binary-numbers)
 
-A library for the turing-machine-js.
+Binary arithmetic on a **5-symbol alphabet** (` `, `^`, `$`, `0`, `1`) supporting **multiple numbers per tape**. Numbers are delimited by `^…$` markers — the markers cost extra states per algorithm but enable inter-number navigation. Side-by-side with [`@turing-machine-js/library-binary-numbers-bare`](../library-binary-numbers-bare), which drops the markers for smaller graphs at the cost of single-number-only operation.
 
 ## Install
 
-Using npm:
-
 ```sh
-npm install @turing-machine-js/library-binary-numbers
+npm install @turing-machine-js/machine @turing-machine-js/library-binary-numbers
 ```
 
-## A concept
+`@turing-machine-js/machine` is a peer dependency.
+
+## Concept
+
+A number is a sequence of `0`/`1` cells delimited by `^` (start) and `$` (end). Several numbers can sit on one tape, separated by blanks.
 
-Binary numbers are represented as a sequence of symbols `0` and `1`.
+```
+…blank ^101011$ blank ^110010$ blank…
+       ╰─ 43 ─╯       ╰─ 50 ─╯
+```
 
-A representation of a number starts with symbol `^` and ends with symbol `$`.
+Examples:
+- `^$` represents 0
+- `^1$` represents 1
+- `^10$` represents 2
+- `^11$` represents 3
 
-For example:
-- `^$` stands for 0
-- `^1$` stands for 1
-- `^10$` stands for 2
-- `^11$` stands for 3
-- etc.
+Negative numbers are not currently supported.
 
-There is no ability to work with negative numbers at this time.
+## Algorithms
 
-This library provides following objects to work with binary numbers:
-- `getTapeBlock` - this function returns a `TapeBlock` class instance. It has only one tape. An alphabet of the tape contains the following symbols: `space` as a blank symbol, `^`, `$`, `0` and `1`.
-- `states` - following `States` class instances which represent some algorithms:
-    - `goToNumber` - move the head to the number's end
-    - `goToNextNumber` - move the head to the next number (to the right)
-    - `goToPreviousNumber` - move the head to the previous number (to the left)
-    - `deleteNumber` - delete the current number 
-    - `goToNumbersStart` - move the head to the number's start 
-    - `invertNumber` - change every symbol in the number to it's opposite one (`0` to `1` and `1` to `0`)
-    - `normalizeNumber` - delete leading zeros
-    - `plusOne` - add 1 to the number
-    - `minusOne` - subtract 1 from the number 
+| name | what it does |
+|---|---|
+| `goToNumber` | move the head to the current number's `$` |
+| `goToNextNumber` | move the head to the next number (rightward) |
+| `goToPreviousNumber` | move the head to the previous number (leftward) |
+| `goToNumbersStart` | move the head to the current number's `^` |
+| `deleteNumber` | erase the current number entirely |
+| `invertNumber` | flip every bit (`0` ↔ `1`) |
+| `normalizeNumber` | erase leading zeros (preserving `^$` for the value zero) |
+| `plusOne` | add 1 to the number; extends leftward on overflow (`111 + 1 = 1000`) |
+| `minusOne` | subtract 1, computed via `~(~x + 1)` — composes `invertNumber` → `plusOne` → `invertNumber` → `normalizeNumber` |
+| `minusOneFast` | direct borrow propagation; smaller than `minusOne` and auto-normalizes |
 
-If you want to use states which were described earlier, you must use a tape block received from the `getTapeBlock` function.
+To use these, the tape block **must** come from `getTapeBlock()` — that's the one that interns the `^`/`$`/`01` patterns the states key against.
 
-## Links
+## Usage
+
+```javascript
+import { Tape, TuringMachine } from '@turing-machine-js/machine';
+import binaryNumbers from '@turing-machine-js/library-binary-numbers';
+
+const tapeBlock = binaryNumbers.getTapeBlock();
+const tape = new Tape({
+  alphabet: tapeBlock.alphabets[0],
+  symbols: '^101$'.split(''), // binary 5
+});
+
+tapeBlock.replaceTape(tape);
+
+const machine = new TuringMachine({ tapeBlock });
+
+machine.run({ initialState: binaryNumbers.states.plusOne });
 
-- The information about `TapeBlock` and `State` classes is [here](https://github.com/mellonis/turing-machine-js/tree/master/packages/machine) 
-- [Turing Machine](https://en.wikipedia.org/wiki/Turing_machine) on the Wikipedia
+console.log(tape.symbols.join('').trim()); // "^110$" (binary 6)
+```
+
+To run several algorithms in sequence on the same value, reuse the same `TapeBlock` across `machine.run(...)` calls — every state in `binaryNumbers.states` halts cleanly with the head positioned for the next algorithm to pick up.
+
+## How it compares to the bare library
+
+Both libraries solve the same arithmetic problem; the trade is **alphabet symbols** vs **state-graph size**.
+
+| algorithm | this library (5-symbol) | bare library (3-symbol) |
+|---|---|---|
+| `plusOne` | 5 states | **3** states |
+| `minusOne` | 17 / 10 (`minusOne` / `minusOneFast`) | **3** states |
+| `invertNumber` | 5 states | **2** states |
+| `normalizeNumber` | 7 states | **2** states |
+| **multi-number on tape?** | yes — `goToNumber`, `goToNextNumber`, etc. | no |
+| **head-position flexibility** | anywhere on the number | leftmost digit |
+| **`minusOne` auto-normalizes?** | yes — `minusOneFast` chains into `normalizeNumber` | no — leading `0` kept |
+
+The extra states this library spends are mostly bookkeeping for the `^`/`$` markers (planting `^` on left-overflow, sweeping past it on entry, etc.). The pay-off is multi-number-per-tape support and head-position flexibility — `goToNumber` / `goToNextNumber` / `goToPreviousNumber` / `deleteNumber` / `goToNumbersStart` have no counterpart in the bare library.
+
+For a teaching context, both libraries shipping in parallel makes the cost of representation choices tangible.
+
+See the rendered Mermaid graphs for every state in [`states.md`](states.md) (auto-generated by `src/graphs.spec.ts`).
+
+## Links
 
+- [`@turing-machine-js/machine`](../machine) — the core engine
+- [`@turing-machine-js/library-binary-numbers-bare`](../library-binary-numbers-bare) — the 3-symbol counterpart
+- [Turing Machine](https://en.wikipedia.org/wiki/Turing_machine) on Wikipedia

package/dist/index.cjs

@@ -1,109 +1,147 @@
 'use strict';
 
-var src = require('@turing-machine-js/machine/src');
+var machine = require('@turing-machine-js/machine');
 
-const alphabet = new src.Alphabet(' ^$01'.split(''));
-const tapeBlock = src.TapeBlock.fromAlphabets([alphabet]);
+// 5-symbol alphabet: blank (' '), '^' (number start), '$' (number end), '0', '1'.
+// A tape can hold many numbers, each delimited by '^...$', with blanks between.
+//
+// Compared with @turing-machine-js/library-binary-numbers-bare (3-symbol alphabet,
+// single-number-per-tape), the explicit '^'/'$' markers cost extra states per
+// algorithm but enable safe multi-number navigation (goToNumber / goToNextNumber /
+// goToPreviousNumber). Both libraries exist side-by-side so the trade-off between
+// alphabet size and state-graph size is visible — see ../states.md for diagrams.
+const alphabet = new machine.Alphabet(' ^$01'.split(''));
+const tapeBlock = machine.TapeBlock.fromAlphabets([alphabet]);
 const { symbol } = tapeBlock;
-const goToNumber = new src.State({
+// goToNumber — 2 nodes
+//
+// Walks the head right until '$'. Used as a "go to current number's end" primitive.
+const goToNumber = new machine.State({
     [symbol('$')]: {
-        nextState: src.haltState,
+        nextState: machine.haltState,
     },
-    [src.ifOtherSymbol]: {
+    [machine.ifOtherSymbol]: {
         command: {
-            movement: src.movements.right,
+            movement: machine.movements.right,
         },
     },
 }, 'goToNumber');
-const goToNextNumber = new src.State({
-    [src.ifOtherSymbol]: {
+// goToNextNumber — 3 nodes (composes goToNumber)
+//
+// Steps right one cell (out of the current '$' / blank gap), then hands off to
+// goToNumber to land on the next number's '$'.
+const goToNextNumber = new machine.State({
+    [machine.ifOtherSymbol]: {
         command: {
-            movement: src.movements.right,
+            movement: machine.movements.right,
         },
         nextState: goToNumber,
     },
 }, 'goToNextNumber');
-const goToPreviousNumberInternal = new src.State({
+// goToPreviousNumber — 3 nodes (uses an internal mirror of goToNumber)
+//
+// Steps left one cell, then walks left until '$' of the previous number.
+const goToPreviousNumberInternal = new machine.State({
     [symbol('$')]: {
-        nextState: src.haltState,
+        nextState: machine.haltState,
     },
-    [src.ifOtherSymbol]: {
+    [machine.ifOtherSymbol]: {
         command: {
-            movement: src.movements.left,
+            movement: machine.movements.left,
         },
     },
 }, 'goToPreviousNumberInternal');
-const goToPreviousNumber = new src.State({
-    [src.ifOtherSymbol]: {
+const goToPreviousNumber = new machine.State({
+    [machine.ifOtherSymbol]: {
         command: {
-            movement: src.movements.left,
+            movement: machine.movements.left,
         },
         nextState: goToPreviousNumberInternal,
     },
 }, 'goToPreviousNumber');
-const goToNumbersStart = new src.State({
+// goToNumbersStart — 2 nodes
+//
+// Walks the head left until '^'. Mirror of goToNumber for the start marker.
+const goToNumbersStart = new machine.State({
     [symbol('^')]: {
-        nextState: src.haltState,
+        nextState: machine.haltState,
     },
-    [src.ifOtherSymbol]: {
+    [machine.ifOtherSymbol]: {
         command: {
-            movement: src.movements.left,
+            movement: machine.movements.left,
         },
     },
 }, 'goToNumberStart');
-const deleteNumberInternal = new src.State({
+// deleteNumber — 5 nodes
+//
+// Composition: go to the number's '^', then sweep right erasing every cell
+// (digits, '^', '$') until the number is gone. Implemented as
+// goToNumbersStart.withOverrodeHaltState(deleteNumberInternal): when
+// goToNumbersStart would halt at '^', it falls through to the eraser instead.
+const deleteNumberInternal = new machine.State({
     [symbol('$')]: {
         command: {
-            symbol: src.symbolCommands.erase,
+            symbol: machine.symbolCommands.erase,
         },
-        nextState: src.haltState,
+        nextState: machine.haltState,
     },
-    [src.ifOtherSymbol]: {
+    [machine.ifOtherSymbol]: {
         command: {
-            symbol: src.symbolCommands.erase,
-            movement: src.movements.right,
+            symbol: machine.symbolCommands.erase,
+            movement: machine.movements.right,
         },
     },
 }, 'deleteNumberInternal');
-const deleteNumber = new src.State({
+const deleteNumber = new machine.State({
     [symbol('^10$')]: {
         nextState: goToNumbersStart.withOverrodeHaltState(deleteNumberInternal),
     },
-    [src.ifOtherSymbol]: {
-        nextState: src.haltState,
+    [machine.ifOtherSymbol]: {
+        nextState: machine.haltState,
     },
 }, 'deleteNumber');
-const invertNumberGoToNumberWithInversion = new src.State({
+// invertNumber — 5 nodes
+//
+// Composition: go to '^', then sweep right flipping each bit until '$'.
+// Same shape as deleteNumber (goToNumbersStart.withOverrodeHaltState(...)) but
+// the inner state writes the complement instead of erasing.
+const invertNumberGoToNumberWithInversion = new machine.State({
     [symbol('^')]: {
         command: {
-            movement: src.movements.right,
+            movement: machine.movements.right,
         },
     },
     [symbol('1')]: {
         command: {
             symbol: '0',
-            movement: src.movements.right,
+            movement: machine.movements.right,
         },
     },
     [symbol('0')]: {
         command: {
             symbol: '1',
-            movement: src.movements.right,
+            movement: machine.movements.right,
         },
     },
     [symbol('$')]: {
-        nextState: src.haltState,
+        nextState: machine.haltState,
     },
 }, 'invertNumberGoToNumberWithInversion');
-const invertNumber = new src.State({
+const invertNumber = new machine.State({
     [symbol('^10$')]: {
         nextState: goToNumbersStart.withOverrodeHaltState(invertNumberGoToNumberWithInversion),
     },
-    [src.ifOtherSymbol]: {
-        nextState: src.haltState,
+    [machine.ifOtherSymbol]: {
+        nextState: machine.haltState,
     },
 }, 'invertNumber');
-const normalizeNumberPutNewStartSymbol = new src.State({
+// normalizeNumber — 7 nodes
+//
+// Strips leading zeros by erasing them and re-planting '^' just before the first
+// '1' (or before '$' if the entire number was zero — preserving "0" as "^$").
+// Composition: go to '^', then move-start sweeps right erasing '^' and leading
+// '0's; on first '1' or '$' it backs up one cell and writes a fresh '^' there.
+const normalizeNumberPutNewStartSymbol = new machine.State({
     [symbol(alphabet.blankSymbol)]: {
         command: {
             symbol: '^',
@@ -111,94 +149,115 @@ const normalizeNumberPutNewStartSymbol = new src.State({
         nextState: goToNumber,
     },
 }, 'normalizeNumberPutNewStartSymbol');
-const normalizeNumberMoveNumberStart = new src.State({
+const normalizeNumberMoveNumberStart = new machine.State({
     [symbol('^0')]: {
         command: {
-            symbol: src.symbolCommands.erase,
-            movement: src.movements.right,
+            symbol: machine.symbolCommands.erase,
+            movement: machine.movements.right,
         },
     },
     [symbol('1$')]: {
         command: {
-            movement: src.movements.left,
+            movement: machine.movements.left,
         },
         nextState: normalizeNumberPutNewStartSymbol,
     },
 }, 'normalizeNumberMoveNumberStart');
-const normalizeNumber = new src.State({
+const normalizeNumber = new machine.State({
     [symbol('^10$')]: {
         nextState: goToNumbersStart.withOverrodeHaltState(normalizeNumberMoveNumberStart),
     },
-    [src.ifOtherSymbol]: {
-        nextState: src.haltState,
+    [machine.ifOtherSymbol]: {
+        nextState: machine.haltState,
     },
 }, 'normalizeNumber');
-const plusOneFillZeros = new src.State({
+// plusOne — 5 nodes
+//
+// Walk to '$', step left into the LSB, then carry from the LSB:
+//   1 → 0 (carry continues left)
+//   0 → 1, then fill any 1s to the right with 0s (already done by the chain) and halt at '$'
+//   ^ → 1 (carry overflows the MSB) — write 1, step into the new blank cell on the
+//     left, plant a fresh '^' there, then sweep right turning the old leading 1s
+//     into 0s. This is what plusOneAddNumberStart and plusOneFillZeros handle.
+//
+// The bare-alphabet variant in @turing-machine-js/library-binary-numbers-bare
+// drops to 3 nodes for the same operation by skipping the '^' relocation.
+const plusOneFillZeros = new machine.State({
     [symbol('1')]: {
         command: {
             symbol: '0',
-            movement: src.movements.right,
+            movement: machine.movements.right,
         },
     },
     [symbol('$')]: {
-        nextState: src.haltState,
+        nextState: machine.haltState,
     },
 }, 'plusOneFillZeros');
-const plusOneAddNumberStart = new src.State({
+const plusOneAddNumberStart = new machine.State({
     [symbol(alphabet.blankSymbol)]: {
         command: {
             symbol: '^',
-            movement: src.movements.right,
+            movement: machine.movements.right,
         },
     },
     [symbol('1')]: {
         command: {
-            movement: src.movements.right,
+            movement: machine.movements.right,
         },
         nextState: plusOneFillZeros,
     },
 }, 'plusOneAddNumberStart');
-const plusOneCaryOne = new src.State({
+const plusOneCaryOne = new machine.State({
     [symbol('0')]: {
         command: {
             symbol: '1',
-            movement: src.movements.right,
+            movement: machine.movements.right,
         },
         nextState: plusOneFillZeros,
     },
     [symbol('1')]: {
         command: {
-            movement: src.movements.left,
+            movement: machine.movements.left,
         },
     },
     [symbol('^')]: {
         command: {
             symbol: '1',
-            movement: src.movements.left,
+            movement: machine.movements.left,
         },
         nextState: plusOneAddNumberStart,
     },
 }, 'plusOneCaryOne');
-const plusOne = new src.State({
+const plusOne = new machine.State({
     [symbol('^10')]: {
         command: {
-            movement: src.movements.right,
+            movement: machine.movements.right,
         },
     },
     [symbol('$')]: {
         command: {
-            movement: src.movements.left,
+            movement: machine.movements.left,
         },
         nextState: plusOneCaryOne,
     },
-    [src.ifOtherSymbol]: {
-        nextState: src.haltState,
+    [machine.ifOtherSymbol]: {
+        nextState: machine.haltState,
     },
 }, 'plusOne');
-const minusOne = new src.State({
+// minusOne — 17 nodes (the largest in this library)
+//
+// Computes x − 1 via the two's-complement identity:  x − 1 == ~(~x + 1)
+// (every step is a state we already have), composed with three nested
+// withOverrodeHaltState calls to chain invert → plusOne → invert → normalize.
+//
+// This is *deliberately* the heavy version. It exists side-by-side with
+// minusOneFast (10 nodes, direct borrow) to make the cost of "compose existing
+// pieces" vs "write a dedicated algorithm" visible. See ../states.md for the
+// dotted onHalt edges that show the four-deep subroutine chain.
+const minusOne = new machine.State({
     [symbol('^10')]: {
         command: {
-            movement: src.movements.right,
+            movement: machine.movements.right,
         },
     },
     [symbol('$')]: {
@@ -207,10 +266,53 @@ const minusOne = new src.State({
             .withOverrodeHaltState(invertNumber
             .withOverrodeHaltState(normalizeNumber))),
     },
-    [src.ifOtherSymbol]: {
-        nextState: src.haltState,
+    [machine.ifOtherSymbol]: {
+        nextState: machine.haltState,
     },
 }, 'minusOne');
+// minusOneFast — 10 nodes (direct borrow propagation)
+//
+// Walks left from the LSB: 0→1 keeps borrowing; 1→0 stops; ^ is underflow.
+// Falls through to normalizeNumber to strip the leading zero introduced when the
+// borrow chain reaches the MSB (e.g. ^1000$ - 1 = ^0111$ → ^111$).
+//
+// Same algorithm as minusOne in @turing-machine-js/library-binary-numbers-bare
+// (which is 3 nodes there). The extra 7 nodes here are the cost of: scanning
+// past '^' on entry, the goToNumberStart path and its withOverrodeHaltState
+// wrapper for normalize, and normalizeNumber's own marker-relocation chain.
+const minusOneFastBorrow = new machine.State({
+    [symbol('1')]: {
+        command: {
+            symbol: '0',
+        },
+        nextState: machine.haltState,
+    },
+    [symbol('0')]: {
+        command: {
+            symbol: '1',
+            movement: machine.movements.left,
+        },
+    },
+    [symbol('^')]: {
+        nextState: machine.haltState,
+    },
+}, 'minusOneFastBorrow');
+const minusOneFast = new machine.State({
+    [symbol('^10')]: {
+        command: {
+            movement: machine.movements.right,
+        },
+    },
+    [symbol('$')]: {
+        command: {
+            movement: machine.movements.left,
+        },
+        nextState: minusOneFastBorrow.withOverrodeHaltState(normalizeNumber),
+    },
+    [machine.ifOtherSymbol]: {
+        nextState: machine.haltState,
+    },
+}, 'minusOneFast');
 function getTapeBlock() {
     return tapeBlock.clone();
 }
@@ -226,6 +328,7 @@ var index = {
         normalizeNumber,
         plusOne,
         minusOne,
+        minusOneFast,
     },
 };
 

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { State, TapeBlock } from '@turing-machine-js/machine/src';
+import { State, TapeBlock } from '@turing-machine-js/machine';
 declare function getTapeBlock(): TapeBlock;
 declare const _default: {
     getTapeBlock: typeof getTapeBlock;
@@ -12,6 +12,7 @@ declare const _default: {
         normalizeNumber: State;
         plusOne: State;
         minusOne: State;
+        minusOneFast: State;
     };
 };
 export default _default;

package/dist/index.mjs

@@ -1,8 +1,19 @@
-import { Alphabet, TapeBlock, State, movements, haltState, ifOtherSymbol, symbolCommands } from '@turing-machine-js/machine/src';
+import { Alphabet, TapeBlock, State, movements, haltState, ifOtherSymbol, symbolCommands } from '@turing-machine-js/machine';
 
+// 5-symbol alphabet: blank (' '), '^' (number start), '$' (number end), '0', '1'.
+// A tape can hold many numbers, each delimited by '^...$', with blanks between.
+//
+// Compared with @turing-machine-js/library-binary-numbers-bare (3-symbol alphabet,
+// single-number-per-tape), the explicit '^'/'$' markers cost extra states per
+// algorithm but enable safe multi-number navigation (goToNumber / goToNextNumber /
+// goToPreviousNumber). Both libraries exist side-by-side so the trade-off between
+// alphabet size and state-graph size is visible — see ../states.md for diagrams.
 const alphabet = new Alphabet(' ^$01'.split(''));
 const tapeBlock = TapeBlock.fromAlphabets([alphabet]);
 const { symbol } = tapeBlock;
+// goToNumber — 2 nodes
+//
+// Walks the head right until '$'. Used as a "go to current number's end" primitive.
 const goToNumber = new State({
     [symbol('$')]: {
         nextState: haltState,
@@ -13,6 +24,10 @@ const goToNumber = new State({
         },
     },
 }, 'goToNumber');
+// goToNextNumber — 3 nodes (composes goToNumber)
+//
+// Steps right one cell (out of the current '$' / blank gap), then hands off to
+// goToNumber to land on the next number's '$'.
 const goToNextNumber = new State({
     [ifOtherSymbol]: {
         command: {
@@ -21,6 +36,9 @@ const goToNextNumber = new State({
         nextState: goToNumber,
     },
 }, 'goToNextNumber');
+// goToPreviousNumber — 3 nodes (uses an internal mirror of goToNumber)
+//
+// Steps left one cell, then walks left until '$' of the previous number.
 const goToPreviousNumberInternal = new State({
     [symbol('$')]: {
         nextState: haltState,
@@ -39,6 +57,9 @@ const goToPreviousNumber = new State({
         nextState: goToPreviousNumberInternal,
     },
 }, 'goToPreviousNumber');
+// goToNumbersStart — 2 nodes
+//
+// Walks the head left until '^'. Mirror of goToNumber for the start marker.
 const goToNumbersStart = new State({
     [symbol('^')]: {
         nextState: haltState,
@@ -49,6 +70,12 @@ const goToNumbersStart = new State({
         },
     },
 }, 'goToNumberStart');
+// deleteNumber — 5 nodes
+//
+// Composition: go to the number's '^', then sweep right erasing every cell
+// (digits, '^', '$') until the number is gone. Implemented as
+// goToNumbersStart.withOverrodeHaltState(deleteNumberInternal): when
+// goToNumbersStart would halt at '^', it falls through to the eraser instead.
 const deleteNumberInternal = new State({
     [symbol('$')]: {
         command: {
@@ -71,6 +98,11 @@ const deleteNumber = new State({
         nextState: haltState,
     },
 }, 'deleteNumber');
+// invertNumber — 5 nodes
+//
+// Composition: go to '^', then sweep right flipping each bit until '$'.
+// Same shape as deleteNumber (goToNumbersStart.withOverrodeHaltState(...)) but
+// the inner state writes the complement instead of erasing.
 const invertNumberGoToNumberWithInversion = new State({
     [symbol('^')]: {
         command: {
@@ -101,6 +133,12 @@ const invertNumber = new State({
         nextState: haltState,
     },
 }, 'invertNumber');
+// normalizeNumber — 7 nodes
+//
+// Strips leading zeros by erasing them and re-planting '^' just before the first
+// '1' (or before '$' if the entire number was zero — preserving "0" as "^$").
+// Composition: go to '^', then move-start sweeps right erasing '^' and leading
+// '0's; on first '1' or '$' it backs up one cell and writes a fresh '^' there.
 const normalizeNumberPutNewStartSymbol = new State({
     [symbol(alphabet.blankSymbol)]: {
         command: {
@@ -131,6 +169,17 @@ const normalizeNumber = new State({
         nextState: haltState,
     },
 }, 'normalizeNumber');
+// plusOne — 5 nodes
+//
+// Walk to '$', step left into the LSB, then carry from the LSB:
+//   1 → 0 (carry continues left)
+//   0 → 1, then fill any 1s to the right with 0s (already done by the chain) and halt at '$'
+//   ^ → 1 (carry overflows the MSB) — write 1, step into the new blank cell on the
+//     left, plant a fresh '^' there, then sweep right turning the old leading 1s
+//     into 0s. This is what plusOneAddNumberStart and plusOneFillZeros handle.
+//
+// The bare-alphabet variant in @turing-machine-js/library-binary-numbers-bare
+// drops to 3 nodes for the same operation by skipping the '^' relocation.
 const plusOneFillZeros = new State({
     [symbol('1')]: {
         command: {
@@ -193,6 +242,16 @@ const plusOne = new State({
         nextState: haltState,
     },
 }, 'plusOne');
+// minusOne — 17 nodes (the largest in this library)
+//
+// Computes x − 1 via the two's-complement identity:  x − 1 == ~(~x + 1)
+// (every step is a state we already have), composed with three nested
+// withOverrodeHaltState calls to chain invert → plusOne → invert → normalize.
+//
+// This is *deliberately* the heavy version. It exists side-by-side with
+// minusOneFast (10 nodes, direct borrow) to make the cost of "compose existing
+// pieces" vs "write a dedicated algorithm" visible. See ../states.md for the
+// dotted onHalt edges that show the four-deep subroutine chain.
 const minusOne = new State({
     [symbol('^10')]: {
         command: {
@@ -209,6 +268,49 @@ const minusOne = new State({
         nextState: haltState,
     },
 }, 'minusOne');
+// minusOneFast — 10 nodes (direct borrow propagation)
+//
+// Walks left from the LSB: 0→1 keeps borrowing; 1→0 stops; ^ is underflow.
+// Falls through to normalizeNumber to strip the leading zero introduced when the
+// borrow chain reaches the MSB (e.g. ^1000$ - 1 = ^0111$ → ^111$).
+//
+// Same algorithm as minusOne in @turing-machine-js/library-binary-numbers-bare
+// (which is 3 nodes there). The extra 7 nodes here are the cost of: scanning
+// past '^' on entry, the goToNumberStart path and its withOverrodeHaltState
+// wrapper for normalize, and normalizeNumber's own marker-relocation chain.
+const minusOneFastBorrow = new State({
+    [symbol('1')]: {
+        command: {
+            symbol: '0',
+        },
+        nextState: haltState,
+    },
+    [symbol('0')]: {
+        command: {
+            symbol: '1',
+            movement: movements.left,
+        },
+    },
+    [symbol('^')]: {
+        nextState: haltState,
+    },
+}, 'minusOneFastBorrow');
+const minusOneFast = new State({
+    [symbol('^10')]: {
+        command: {
+            movement: movements.right,
+        },
+    },
+    [symbol('$')]: {
+        command: {
+            movement: movements.left,
+        },
+        nextState: minusOneFastBorrow.withOverrodeHaltState(normalizeNumber),
+    },
+    [ifOtherSymbol]: {
+        nextState: haltState,
+    },
+}, 'minusOneFast');
 function getTapeBlock() {
     return tapeBlock.clone();
 }
@@ -224,6 +326,7 @@ var index = {
         normalizeNumber,
         plusOne,
         minusOne,
+        minusOneFast,
     },
 };
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@turing-machine-js/library-binary-numbers",
-  "version": "2.0.2",
+  "version": "3.0.1",
   "description": "A standard library for working with binary numbers",
   "engines": {
     "npm": ">=7.0.0"
@@ -17,7 +17,7 @@
     "directory": "packages/library-binary-numbers"
   },
   "bugs": {
-    "url": "https://github.com/mellonis/turing-machine-js/issues?utf8=✓&q=is%3Aissue+is%3Aopen+label%3A%22pkg%3A+library-binary-numbers%22+label%3Abug+"
+    "url": "https://github.com/mellonis/turing-machine-js/issues?utf8=✓&q=is%3Aissue+is%3Aopen+label%3A%22pkg%3A+library-binary-numbers%22+label%3Abug"
   },
   "keywords": [
     "turing",
@@ -26,8 +26,8 @@
     "binary",
     "numbers"
   ],
-  "dependencies": {
-    "@turing-machine-js/machine": "^2.0.2"
+  "peerDependencies": {
+    "@turing-machine-js/machine": "^3.0.0"
   },
   "main": "dist/index.cjs",
   "module": "dist/index.mjs",
@@ -40,5 +40,5 @@
       "default": "./dist/index.mjs"
     }
   },
-  "gitHead": "54da1870a45fd78496c6ba56ce1de728d766470b"
+  "gitHead": "0a8d7ff87a3a73ea7ee1844f7f4602cbb23d20fe"
 }

package/states.md

@@ -0,0 +1,266 @@
+# library-binary-numbers — state graphs
+
+## goToNumber
+
+*2 states (including `haltState`)*
+
+```mermaid
+flowchart TD
+%% alphabets: [[" ","^","$","0","1"]]
+  s0(((halt)))
+  s1(("goToNumber"))
+  s1 -- "$ → ·/S" --> s0
+  s1 -- "* → ·/R" --> s1
+```
+
+## goToNextNumber
+
+*3 states (including `haltState`)*
+
+```mermaid
+flowchart TD
+%% alphabets: [[" ","^","$","0","1"]]
+  s0(((halt)))
+  s1["goToNumber"]
+  s2(("goToNextNumber"))
+  s1 -- "$ → ·/S" --> s0
+  s1 -- "* → ·/R" --> s1
+  s2 -- "* → ·/R" --> s1
+```
+
+## goToPreviousNumber
+
+*3 states (including `haltState`)*
+
+```mermaid
+flowchart TD
+%% alphabets: [[" ","^","$","0","1"]]
+  s0(((halt)))
+  s3["goToPreviousNumberInternal"]
+  s4(("goToPreviousNumber"))
+  s3 -- "$ → ·/S" --> s0
+  s3 -- "* → ·/L" --> s3
+  s4 -- "* → ·/L" --> s3
+```
+
+## deleteNumber
+
+*5 states (including `haltState`)*
+
+```mermaid
+flowchart TD
+%% alphabets: [[" ","^","$","0","1"]]
+  s0(((halt)))
+  s5["goToNumberStart"]
+  s6["deleteNumberInternal"]
+  s7["goToNumberStart>deleteNumberInternal"]
+  s8(("deleteNumber"))
+  s5 -- "^ → ·/S" --> s0
+  s5 -- "* → ·/L" --> s5
+  s6 -- "$ → ⌫/S" --> s0
+  s6 -- "* → ⌫/R" --> s6
+  s7 -- "^ → ·/S" --> s0
+  s7 -- "* → ·/L" --> s5
+  s7 -. onHalt .-> s6
+  s8 -- "^|1|0|$ → ·/S" --> s7
+  s8 -- "* → ·/S" --> s0
+```
+
+## goToNumbersStart
+
+*2 states (including `haltState`)*
+
+```mermaid
+flowchart TD
+%% alphabets: [[" ","^","$","0","1"]]
+  s0(((halt)))
+  s5(("goToNumberStart"))
+  s5 -- "^ → ·/S" --> s0
+  s5 -- "* → ·/L" --> s5
+```
+
+## invertNumber
+
+*5 states (including `haltState`)*
+
+```mermaid
+flowchart TD
+%% alphabets: [[" ","^","$","0","1"]]
+  s0(((halt)))
+  s5["goToNumberStart"]
+  s9["invertNumberGoToNumberWithInversion"]
+  s10["goToNumberStart>invertNumberGoToNumberWithInversion"]
+  s11(("invertNumber"))
+  s5 -- "^ → ·/S" --> s0
+  s5 -- "* → ·/L" --> s5
+  s9 -- "^ → ·/R" --> s9
+  s9 -- "1 → 0/R" --> s9
+  s9 -- "0 → 1/R" --> s9
+  s9 -- "$ → ·/S" --> s0
+  s10 -- "^ → ·/S" --> s0
+  s10 -- "* → ·/L" --> s5
+  s10 -. onHalt .-> s9
+  s11 -- "^|1|0|$ → ·/S" --> s10
+  s11 -- "* → ·/S" --> s0
+```
+
+## normalizeNumber
+
+*7 states (including `haltState`)*
+
+```mermaid
+flowchart TD
+%% alphabets: [[" ","^","$","0","1"]]
+  s0(((halt)))
+  s1["goToNumber"]
+  s5["goToNumberStart"]
+  s12["normalizeNumberPutNewStartSymbol"]
+  s13["normalizeNumberMoveNumberStart"]
+  s14["goToNumberStart>normalizeNumberMoveNumberStart"]
+  s15(("normalizeNumber"))
+  s1 -- "$ → ·/S" --> s0
+  s1 -- "* → ·/R" --> s1
+  s5 -- "^ → ·/S" --> s0
+  s5 -- "* → ·/L" --> s5
+  s12 -- "- → ^/S" --> s1
+  s13 -- "^|0 → ⌫/R" --> s13
+  s13 -- "1|$ → ·/L" --> s12
+  s14 -- "^ → ·/S" --> s0
+  s14 -- "* → ·/L" --> s5
+  s14 -. onHalt .-> s13
+  s15 -- "^|1|0|$ → ·/S" --> s14
+  s15 -- "* → ·/S" --> s0
+```
+
+## plusOne
+
+*5 states (including `haltState`)*
+
+```mermaid
+flowchart TD
+%% alphabets: [[" ","^","$","0","1"]]
+  s0(((halt)))
+  s16["plusOneFillZeros"]
+  s17["plusOneAddNumberStart"]
+  s18["plusOneCaryOne"]
+  s19(("plusOne"))
+  s16 -- "1 → 0/R" --> s16
+  s16 -- "$ → ·/S" --> s0
+  s17 -- "- → ^/R" --> s17
+  s17 -- "1 → ·/R" --> s16
+  s18 -- "0 → 1/R" --> s16
+  s18 -- "1 → ·/L" --> s18
+  s18 -- "^ → 1/L" --> s17
+  s19 -- "^|1|0 → ·/R" --> s19
+  s19 -- "$ → ·/L" --> s18
+  s19 -- "* → ·/S" --> s0
+```
+
+## minusOne
+
+*17 states (including `haltState`)*
+
+```mermaid
+flowchart TD
+%% alphabets: [[" ","^","$","0","1"]]
+  s0(((halt)))
+  s1["goToNumber"]
+  s5["goToNumberStart"]
+  s9["invertNumberGoToNumberWithInversion"]
+  s10["goToNumberStart>invertNumberGoToNumberWithInversion"]
+  s12["normalizeNumberPutNewStartSymbol"]
+  s13["normalizeNumberMoveNumberStart"]
+  s14["goToNumberStart>normalizeNumberMoveNumberStart"]
+  s15["normalizeNumber"]
+  s16["plusOneFillZeros"]
+  s17["plusOneAddNumberStart"]
+  s18["plusOneCaryOne"]
+  s19["plusOne"]
+  s20["invertNumber>normalizeNumber"]
+  s21["plusOne>invertNumber>normalizeNumber"]
+  s22["invertNumber>plusOne>invertNumber>normalizeNumber"]
+  s23(("minusOne"))
+  s1 -- "$ → ·/S" --> s0
+  s1 -- "* → ·/R" --> s1
+  s5 -- "^ → ·/S" --> s0
+  s5 -- "* → ·/L" --> s5
+  s9 -- "^ → ·/R" --> s9
+  s9 -- "1 → 0/R" --> s9
+  s9 -- "0 → 1/R" --> s9
+  s9 -- "$ → ·/S" --> s0
+  s10 -- "^ → ·/S" --> s0
+  s10 -- "* → ·/L" --> s5
+  s10 -. onHalt .-> s9
+  s12 -- "- → ^/S" --> s1
+  s13 -- "^|0 → ⌫/R" --> s13
+  s13 -- "1|$ → ·/L" --> s12
+  s14 -- "^ → ·/S" --> s0
+  s14 -- "* → ·/L" --> s5
+  s14 -. onHalt .-> s13
+  s15 -- "^|1|0|$ → ·/S" --> s14
+  s15 -- "* → ·/S" --> s0
+  s16 -- "1 → 0/R" --> s16
+  s16 -- "$ → ·/S" --> s0
+  s17 -- "- → ^/R" --> s17
+  s17 -- "1 → ·/R" --> s16
+  s18 -- "0 → 1/R" --> s16
+  s18 -- "1 → ·/L" --> s18
+  s18 -- "^ → 1/L" --> s17
+  s19 -- "^|1|0 → ·/R" --> s19
+  s19 -- "$ → ·/L" --> s18
+  s19 -- "* → ·/S" --> s0
+  s20 -- "^|1|0|$ → ·/S" --> s10
+  s20 -- "* → ·/S" --> s0
+  s20 -. onHalt .-> s15
+  s21 -- "^|1|0 → ·/R" --> s19
+  s21 -- "$ → ·/L" --> s18
+  s21 -- "* → ·/S" --> s0
+  s21 -. onHalt .-> s20
+  s22 -- "^|1|0|$ → ·/S" --> s10
+  s22 -- "* → ·/S" --> s0
+  s22 -. onHalt .-> s21
+  s23 -- "^|1|0 → ·/R" --> s23
+  s23 -- "$ → ·/S" --> s22
+  s23 -- "* → ·/S" --> s0
+```
+
+## minusOneFast
+
+*10 states (including `haltState`)*
+
+```mermaid
+flowchart TD
+%% alphabets: [[" ","^","$","0","1"]]
+  s0(((halt)))
+  s1["goToNumber"]
+  s5["goToNumberStart"]
+  s12["normalizeNumberPutNewStartSymbol"]
+  s13["normalizeNumberMoveNumberStart"]
+  s14["goToNumberStart>normalizeNumberMoveNumberStart"]
+  s15["normalizeNumber"]
+  s24["minusOneFastBorrow"]
+  s25["minusOneFastBorrow>normalizeNumber"]
+  s26(("minusOneFast"))
+  s1 -- "$ → ·/S" --> s0
+  s1 -- "* → ·/R" --> s1
+  s5 -- "^ → ·/S" --> s0
+  s5 -- "* → ·/L" --> s5
+  s12 -- "- → ^/S" --> s1
+  s13 -- "^|0 → ⌫/R" --> s13
+  s13 -- "1|$ → ·/L" --> s12
+  s14 -- "^ → ·/S" --> s0
+  s14 -- "* → ·/L" --> s5
+  s14 -. onHalt .-> s13
+  s15 -- "^|1|0|$ → ·/S" --> s14
+  s15 -- "* → ·/S" --> s0
+  s24 -- "1 → 0/S" --> s0
+  s24 -- "0 → 1/L" --> s24
+  s24 -- "^ → ·/S" --> s0
+  s25 -- "1 → 0/S" --> s0
+  s25 -- "0 → 1/L" --> s24
+  s25 -- "^ → ·/S" --> s0
+  s25 -. onHalt .-> s15
+  s26 -- "^|1|0 → ·/R" --> s26
+  s26 -- "$ → ·/L" --> s25
+  s26 -- "* → ·/S" --> s0
+```

package/dist/index.js

@@ -1,227 +0,0 @@
-import { Alphabet, haltState, ifOtherSymbol, movements, State, symbolCommands, TapeBlock, } from '@turing-machine-js/machine/src';
-const alphabet = new Alphabet(' ^$01'.split(''));
-const tapeBlock = TapeBlock.fromAlphabets([alphabet]);
-const { symbol } = tapeBlock;
-const goToNumber = new State({
-    [symbol('$')]: {
-        nextState: haltState,
-    },
-    [ifOtherSymbol]: {
-        command: {
-            movement: movements.right,
-        },
-    },
-}, 'goToNumber');
-const goToNextNumber = new State({
-    [ifOtherSymbol]: {
-        command: {
-            movement: movements.right,
-        },
-        nextState: goToNumber,
-    },
-}, 'goToNextNumber');
-const goToPreviousNumberInternal = new State({
-    [symbol('$')]: {
-        nextState: haltState,
-    },
-    [ifOtherSymbol]: {
-        command: {
-            movement: movements.left,
-        },
-    },
-}, 'goToPreviousNumberInternal');
-const goToPreviousNumber = new State({
-    [ifOtherSymbol]: {
-        command: {
-            movement: movements.left,
-        },
-        nextState: goToPreviousNumberInternal,
-    },
-}, 'goToPreviousNumber');
-const goToNumbersStart = new State({
-    [symbol('^')]: {
-        nextState: haltState,
-    },
-    [ifOtherSymbol]: {
-        command: {
-            movement: movements.left,
-        },
-    },
-}, 'goToNumberStart');
-const deleteNumberInternal = new State({
-    [symbol('$')]: {
-        command: {
-            symbol: symbolCommands.erase,
-        },
-        nextState: haltState,
-    },
-    [ifOtherSymbol]: {
-        command: {
-            symbol: symbolCommands.erase,
-            movement: movements.right,
-        },
-    },
-}, 'deleteNumberInternal');
-const deleteNumber = new State({
-    [symbol('^10$')]: {
-        nextState: goToNumbersStart.withOverrodeHaltState(deleteNumberInternal),
-    },
-    [ifOtherSymbol]: {
-        nextState: haltState,
-    },
-}, 'deleteNumber');
-const invertNumberGoToNumberWithInversion = new State({
-    [symbol('^')]: {
-        command: {
-            movement: movements.right,
-        },
-    },
-    [symbol('1')]: {
-        command: {
-            symbol: '0',
-            movement: movements.right,
-        },
-    },
-    [symbol('0')]: {
-        command: {
-            symbol: '1',
-            movement: movements.right,
-        },
-    },
-    [symbol('$')]: {
-        nextState: haltState,
-    },
-}, 'invertNumberGoToNumberWithInversion');
-const invertNumber = new State({
-    [symbol('^10$')]: {
-        nextState: goToNumbersStart.withOverrodeHaltState(invertNumberGoToNumberWithInversion),
-    },
-    [ifOtherSymbol]: {
-        nextState: haltState,
-    },
-}, 'invertNumber');
-const normalizeNumberPutNewStartSymbol = new State({
-    [symbol(alphabet.blankSymbol)]: {
-        command: {
-            symbol: '^',
-        },
-        nextState: goToNumber,
-    },
-}, 'normalizeNumberPutNewStartSymbol');
-const normalizeNumberMoveNumberStart = new State({
-    [symbol('^0')]: {
-        command: {
-            symbol: symbolCommands.erase,
-            movement: movements.right,
-        },
-    },
-    [symbol('1$')]: {
-        command: {
-            movement: movements.left,
-        },
-        nextState: normalizeNumberPutNewStartSymbol,
-    },
-}, 'normalizeNumberMoveNumberStart');
-const normalizeNumber = new State({
-    [symbol('^10$')]: {
-        nextState: goToNumbersStart.withOverrodeHaltState(normalizeNumberMoveNumberStart),
-    },
-    [ifOtherSymbol]: {
-        nextState: haltState,
-    },
-}, 'normalizeNumber');
-const plusOneFillZeros = new State({
-    [symbol('1')]: {
-        command: {
-            symbol: '0',
-            movement: movements.right,
-        },
-    },
-    [symbol('$')]: {
-        nextState: haltState,
-    },
-}, 'plusOneFillZeros');
-const plusOneAddNumberStart = new State({
-    [symbol(alphabet.blankSymbol)]: {
-        command: {
-            symbol: '^',
-            movement: movements.right,
-        },
-    },
-    [symbol('1')]: {
-        command: {
-            movement: movements.right,
-        },
-        nextState: plusOneFillZeros,
-    },
-}, 'plusOneAddNumberStart');
-const plusOneCaryOne = new State({
-    [symbol('0')]: {
-        command: {
-            symbol: '1',
-            movement: movements.right,
-        },
-        nextState: plusOneFillZeros,
-    },
-    [symbol('1')]: {
-        command: {
-            movement: movements.left,
-        },
-    },
-    [symbol('^')]: {
-        command: {
-            symbol: '1',
-            movement: movements.left,
-        },
-        nextState: plusOneAddNumberStart,
-    },
-}, 'plusOneCaryOne');
-const plusOne = new State({
-    [symbol('^10')]: {
-        command: {
-            movement: movements.right,
-        },
-    },
-    [symbol('$')]: {
-        command: {
-            movement: movements.left,
-        },
-        nextState: plusOneCaryOne,
-    },
-    [ifOtherSymbol]: {
-        nextState: haltState,
-    },
-}, 'plusOne');
-const minusOne = new State({
-    [symbol('^10')]: {
-        command: {
-            movement: movements.right,
-        },
-    },
-    [symbol('$')]: {
-        nextState: invertNumber
-            .withOverrodeHaltState(plusOne
-            .withOverrodeHaltState(invertNumber
-            .withOverrodeHaltState(normalizeNumber))),
-    },
-    [ifOtherSymbol]: {
-        nextState: haltState,
-    },
-}, 'minusOne');
-function getTapeBlock() {
-    return tapeBlock.clone();
-}
-export default {
-    getTapeBlock,
-    states: {
-        goToNumber,
-        goToNextNumber,
-        goToPreviousNumber,
-        deleteNumber,
-        goToNumbersStart,
-        invertNumber,
-        normalizeNumber,
-        plusOne,
-        minusOne,
-    },
-};

package/tsconfig.tsbuildinfo

@@ -1 +0,0 @@
-{"root":["./src/index.ts"],"version":"5.9.3"}