Design Document: Hallucination-Tolerant State Machine (HTSM)
Objective:
To build a Node.js-based Proof of Concept (PoC) for an Actor-Model state
machine that bridges deterministic logic and probabilistic LLM outputs. The
system treats natural language hallucinations as unresolved pointers,
utilizing late-binding to instantiate "imagined" concepts into physical,
universally routable network objects via file-based mailboxes.
1. Core Architecture & Identity
 * The Harness: A generic Node.js runner that acts as the control plane.
 * Self-Identity: Upon startup, the machine generates a unique, routable ID
(e.g., MACHINE#a1b2c3) or accepts one via startup parameters. The machine uses
this ID to identify itself in all outbound envelopes and expects inbound
messages to be routed to this ID.
 * Epistemic Isolation: The state machine has no direct database connections
to external objects. It relies entirely on message-passing and only knows the
last-known state of the external world as derived from its mailbox.
2. Memory Topography
The state machine manages state across three distinct operational layers:
 * Conceptual Memory (Volatile): A flat Key-Value map storing ungrounded
concepts (e.g., THE_CUSTOMER, NEW_TASK). These are extracted from natural
language. They carry no operational weight, have no routable address, and are
subject to timestamp-based garbage collection (LRU cache) if not referenced
recently.
 * Inventory (Instantiated): Objects that have crossed the threshold into
physical existence. When the system or user commands it, a concept is
"minted," receiving a unique routable ID (e.g., TASK#4fA92b). The state
machine tracks these IDs and their metadata.
 * Local Cache (Perception): The state machine's memory of the external
environment. When a message is received from an external entity (e.g.,
CUSTOMER#Zv82q9), its state and narrative context are cached here for
immediate, lock-free retrieval without querying the external source of truth.
3. Environment & I/O (File-Based Mailbox)
Communication is entirely asynchronous and file-system based, allowing
external scripts, humans, or AI to drop files into the machine's scope.
 * Environment Initialization: On startup, the machine reads <cwd>/state-machin
e-environment.json (or a CLI-provided path). This seeds the machine with known
external routing tables, existing inventory, and configuration parameters.
 * Mailbox Polling/Watching: The system monitors a designated inbox/ directory
for incoming text files.
 * Message Format (AST-MD): All mailbox communication uses a strict Multipart
Markdown format to separate deterministic routing from fluid narrative:
---
from: ENVIRONMENT
refs: [CUSTOMER#Zv82q9, TASK#4fA92b]
---
> [EVENT]
> UPDATE CUSTOMER#Zv82q9 : status = "REJECTED"

The customer sounded frustrated on the call.

4. Execution Loop & REPL
The core runtime operates synchronously via a Node.js REPL (Read-Eval-Print
Loop), ensuring it can be driven interactively by a human, an automated test
runner, or eventually a local AI model.
 * Startup Sequence: Load state-machine-environment.json -> Initialize
Identity -> Start File Watcher on Mailbox -> Drop into REPL.
 * REPL Loop: Awaiting stdin. If a command is passed via the command line on
boot (e.g., node machine.js --exec "mint THE_CUSTOMER"), it executes and exits
(or drops to REPL depending on flags).
 * parse_input(raw_string): The central command parser. It intercepts string
inputs from the REPL (and later, internal AI triggers).
Core parse_input Commands (PoC Scope)
 * /mint [CONCEPT] -> Moves a concept from Conceptual Memory to Inventory,
assigning a Hash ID.
 * /status [ID] -> Prints the last known state from the Local Cache.
 * /send [ID] [ACTION] [NARRATIVE] -> Triggers the compiler.
 * /concept [TERM] -> Manually adds an ALL_CAPS concept to volatile memory.
 * /env -> Dumps the current parsed environment state.
5. Outbound Message Compilation
The state machine never relies on raw LLM output to format network payloads.
When parse_input() processes a /send command (or when the internal logic
dictates a response), it routes the intent through a deterministic compiler
routine.
 * Intent Assembly: The target ID, the system action, and the narrative string
are gathered.
 * AST-MD Generation: The compiler builds the strict YAML frontmatter, the >
[EVENT] blockquote wrapper for actions, and appends the narrative.
 * Dispatch: The compiled Markdown is written to the target's designated file
mailbox (e.g., ../outbox/[TARGET_ID].md), to be picked up by the external
environment or mesh router.