worm

# Worm Protocol > Two-ended cursor (head + tail) that can ingest, parse, shuttle, and emit data across the filesystem with reversible verbs. ## Core Concept A worm is a **two-pointer cursor** that spans structures: ```yaml # Worm: two-pointer cursor spanning structures worm_anatomy: tail: position: "left side" action: "emit here (POOP)" buffer: "payload / active_tokens" head: position: "right side" action: "ingest here (EAT/CHOMP)" ``` - **Head**: Where the worm looks, reads, ingests - **Tail**: Where the worm drops, writes, emits - **Buffer**: What the worm is carrying (normalized tokens) - **Length**: Head–tail distance (zero-length = NOP cursor) ## The Reversible Verb Basis The worm's verbs form a reversible basis for undo/redo: | Verb | Action | Reverse | |------|--------|---------| | **EAT** | Ingest content at head | BARF | | **CHOMP** | Pattern-scan then ingest | BARF | | **POOP** | Emit buffer at tail | EAT | | **BARF** | Emit buffer at head | EAT | | **STICK-UP-BUM** | Inject external data at tail | POOP | This maps to: - **serialize/deserialize**: EAT → normalize → POOP - **undo/redo**: Every verb has an inverse - **copy/transform**: CHOMP source → BARF target ## Movement Verbs ### Worm Movement ``` MOVE-WORM Move head (and optionally tail) MOVE-HEAD Move head only MOVE-ASS Move tail only ``` Movement modes: - `mode: abs` - Absolute path - `mode: rel` - Relative steps - `direction: up/down/in/out/left/right` - Spatial navigation - `tail: follow | stay` - Whether tail follows head ### Unit-Based Cursor ``` NEXT-UNIT Advance head by unit PREV-UNIT Move head backward by unit SELECT-RANGE Select N units into buffer ``` Units: `char | word | sentence | paragraph | section | page | line` ### Tree Navigation ``` TREE-UP Move to parent TREE-DOWN Move to child (by index/name) TREE-NEXT Move to next sibling TREE-PREV Move to previous sibling TREE-OPEN Expand node (view hint) TREE-CLOSE Collapse node (view hint) TREE-HIDE Hide subtree (view hint) TREE-SHOW Show hidden subtree ``` ## Data Flow Verbs ### EAT - Ingest at Head ```yaml invoke: EAT effect: Read content at head, parse tokens, normalize to digestive_format updates: - buffer: filled with content - active_tokens: parsed tokens - payload: last consumed chunk ``` ### CHOMP - Pattern-Anchored Ingest ```yaml invoke: CHOMP params: pattern: "regex or anchor string" effect: Scan for pattern, ingest following content use_when: "Need to find specific section then consume it" ``` ### POOP - Emit at Tail ```yaml invoke: POOP effect: Write buffer/payload at tail position options: - Append to file - Write YAML to emit_dir - Emit selected tokens only ``` ### BARF - Emit at Head ```yaml invoke: BARF effect: Write buffer/payload at head position (regurgitate) use_when: "Need to emit where you just read" ``` ### STICK-UP-BUM - Inject External Data ```yaml invoke: STICK-UP-BUM params: data: "External data to inject" effect: Normalize and store in buffer/payload use_when: "Loading data from outside the worm's crawl path" ``` ## State Shape ```yaml state: head: "." # Current head position (path) tail: "." # Current tail position (path) buffer: [] # Interior ingestion buffer payload: null # Last consumed chunk digestive_format: "neutral" # Normalization format active_tokens: [] # Parsed tokens in worm's "brain" scan_pattern: "" # Pattern for CHOMP anchoring scan_mode: "pattern-then-chomp" emit_dir: ".moollm/skills/worm/out" # Where YAML output goes reversible: true # Enable undo/redo verb basis ``` ## Worm Variants Different worm personalities for different tasks: | Variant | Behavior | |---------|----------| | **Bulldozer** | Moves and overwrites as it goes | | **Link-hopper** | Prefers symlinks; inchworms across references | | **Mapper** | Maps directory trees; leaves markers/indexes | | **Dream** | Speed-of-light synthesis; ephemeral payloads | | **Tree** | Climbs hierarchies; maintains parent/child context | | **Search** | Crawls through search results | ## Usage Patterns ### Copy with Transform ``` 1. Position head at source, tail at destination 2. CHOMP source (pattern-aware) 3. Tokens normalize in buffer 4. POOP to destination ``` ### Link Walking ``` 1. MOVE-WORM head=symlink tail=follow 2. Worm "inchworms" across the link 3. EAT to capture target content 4. Continue crawling ``` ### Doc-to-Doc Pipeline ``` 1. Head in doc A, tail in doc B 2. EAT from A → buffer fills 3. POOP to B → content transfers 4. Repeat for streaming pipeline ``` ### Casting Network ``` Worm A: CHOMP source → POOP to emit_dir/casting.yml Worm B: EAT from emit_dir/casting.yml → process → POOP Worm C: Consumes B's output → builds taxonomy ``` ## Safety Guidelines - **Default to NOP** if path unclear or permissions uncertain - **Avoid ingesting secrets/PII** - skip sensitive patterns - **Respect read/write boundaries** - don't write outside workspace - **Log reversible ops** - enable rollback if something goes wrong - **Don't cross trust boundaries** - stay in permitted zones ## Integration Points | Skill | Integration | |-------|-------------| | **adventure** | Worm traverses rooms; head = current location | | **room** | Rooms can expose worm-friendly ads (FEED-WORM) | | **buff** | Worms receive buffs (FAST-CRAWL, CLEAN-CASTINGS) | | **character** | Worms as NPCs or companions in party | | **data-flow** | Worms are streaming cursors for pipelines | ## Example Session ``` > MOVE-WORM head="skills/adventure/" tail=follow Worm positioned at skills/adventure/ > EAT Ingested CARD.yml (467 lines), SKILL.md (1143 lines) Buffer: 12 sections, 3 methods, 15 advertisements > MOVE-WORM head="skills/bootstrap/" Head moved to skills/bootstrap/ (tail stayed at adventure/) > CHOMP pattern="methods:" Chomped methods section (8 methods found) > POOP Emitted to .moollm/skills/worm/out/methods-comparison.yml ```