add loom.md

Signed-off-by: Jason Hall <imjasonh@gmail.com>

loom.md

@@ -0,0 +1,107 @@
+This specification defines **Loom v1.0**, a domain-specific language (DSL) and execution protocol optimized for Large Language Model (LLM) agents. Loom is designed to minimize token waste, eliminate ambiguity, and provide a mathematically provable link between human intent and code execution.
+
+---
+
+## 1. Design Philosophy
+
+Loom moves away from "Scripting" and toward **"Circuit Design."**
+
+* **Token Density:** Keywords are single characters or high-probability sub-tokens.
+* **Zero Waste:** The compiler rejects any code that does not contribute to a final output (The Sink).
+* **Traceable Intent:** Natural language requirements are compiled into functional constraints.
+
+---
+
+## 2. Grammar & Symbols
+
+| Symbol | Name | Description |
+| --- | --- | --- |
+| **`$`** | **Node** | Defines a scoped process or function. |
+| **`->`** | **Pipe** | The primary operator; moves data and focus from one transformation to the next. |
+| **`!`** | **Sink** | A terminal point where a value is "committed" to memory or output. |
+| **`?`** | **Guard** | An assertion. If false, execution halts and returns a trace to the agent. |
+| **`%`** | **Gate** | A probabilistic branch based on model confidence (e.g., `%90`). |
+| **`~>`** | **Journal** | A non-executable string used by the agent to record reasoning for a specific path. |
+| **`^`** | **Probe** | Meta-syntax for static analysis (e.g., `^can(X)`). |
+
+---
+
+## 3. Structural Specification
+
+### 3.1 Metadata & Contracts
+
+Every Loom file begins with **Directives** that bind the code to the user's high-level request.
+
+* **`@origin`**: A compressed hash or string of the user's original prompt.
+* **`@should`**: A **Contract**. It defines a behavior that the LVM must be able to prove via the `^probe` system.
+
+### 3.2 The Scoping Rule (State-Pinning)
+
+Loom does not have a "Global Namespace."
+
+1. All data enters a `$` block via explicit parameters.
+2. Once a value enters a **Pipe (`->`)**, it is consumed.
+3. If a value needs to be used multiple times, it must be **Cloned** or **Committed** to a named Sink (`!var`).
+
+---
+
+## 4. The LVM (Loom Virtual Machine) Protocol
+
+The LVM acts as the "Operating System" for the agent. It enforces three strict phases:
+
+### Phase 1: Pruning (The "Dead Code" Filter)
+
+The LVM scans the generated code. Any variable declaration or transformation that does not eventually flow into a `!Sink` or a `? Guard` triggers a `PRUNE_ERR`. The LLM must remove these tokens before execution.
+
+### Phase 2: Static Verification
+
+The LVM checks the `@should` contracts against the logic. If a contract says `@should "never be negative"` but a path exists where a value is subtracted without a `? (val >= amount)` guard, the LVM rejects the code.
+
+### Phase 3: Streaming Execution
+
+The LVM executes the circuit. After every `->` pipe, it provides the agent with a **State Snapshot**—a minimal, token-efficient representation of the current stack.
+
+---
+
+## 5. Formal Syntax Example
+
+```loom
+@origin "Process a refund while checking for fraud"
+@should "Only refund if original payment exists"
+@should "Flag refunds over $500 for human review"
+
+$refund_logic(user_id, tx_id, amount):
+  #1. Verify state
+  api.get_tx(tx_id) -> !tx
+  ? (tx.status == "paid") // Guard 1: Existence
+  
+  #2. Probabilistic Fraud Check
+  model.fraud_score(user_id, amount) -> !p_fraud
+  
+  %95 {
+    (amount > 500) 
+      ~> "Amount exceeds auto-limit, routing to human"
+      -> human.review(!tx) -> !result
+    :
+      ~> "Low risk and amount, processing auto-refund"
+      -> gateway.refund(tx_id, amount) -> !result
+  } : {
+    ~> "Model confidence low ({p_fraud}), forcing manual check"
+    human.review(!tx) -> !result
+  }
+
+  #3. Final Integrity Sink
+  ? (result.success == true -> tx.refund_flag == true)
+  !result
+
+```
+
+---
+
+## 6. Verification Queries (The `^Probe`)
+
+A human can query the Loom code via the agent using the `^` operator.
+
+* **Human:** "Can a refund ever happen without a transaction check?"
+* **Agent (Loom Query):** `^can($refund_logic && !api.get_tx)`
+* **LVM Response:** `PROVABLY_FALSE. Path to !result is blocked by ? (tx.status == "paid") at Line 6.`