Oculus Homoiconicity

The system exhibits homoiconic properties - code and data share the same representation, and the boundary between them is a matter of execution context, not structure.

Provider Override

Execute just takes a provider. The fence type is the default provider, but you can override it:

# Default provider (Python interpreter)
fence.execute()

# Override provider (AST extraction)
fence.execute(provider='tree-sitter')

# Override provider (doc extraction)  
fence.execute(provider='docstring-extractor')

Same content, different execution context. The fence type label is just "if nobody says otherwise, use this provider."

This completes the homoiconic picture:

• Content is neutral (just text)
• Fence type is default routing
• Provider is overridable at execute time
• Structure can be extracted or executed, depending on what you need

The Unified Model

Everything is read-write-execute. Everything is one of three fence types:

Fence Type	Storage	Example	Execute Means
Data Fence	YAML/JSON blocks	Config, state	Render/interpolate → data
Code Fence	Python, Bash, etc.	Scripts, queries	Run → data (output)
Prose Fence	Markdown tokens	Documentation	Parse virtual patterns → data

The Homoiconic Property

Executing code  → code becomes data (output)
Executing data  → data becomes data (rendered/interpolated)
Executing prose → prose becomes data (virtual fence extraction)

The transformation is always: thing → data

This is why a TODO list can be "executed" (toggle item) even though it's stored as prose - there's a little machine (virtual fence) living in the tokens.

Storage Layers

Three ways content lives in a node:

• Tokens - Raw prose, the rug that ties the room together
• Fenced blocks - Structured data (YAML) or executable (Python)
• Virtual patterns - Machines hiding in prose (TODO lists, tables)

The Snippet Manager Emergence

Example: Paste text into a data block, peek at it, pipe to pbcopy.

oculus peek cookie-jar-state-machine.my-snippet | pbcopy

You didn't build a snippet manager. You used read-write-execute primitives and a snippet manager emerged.

See a thing → have a thing. Want a thing → have a thing.

What Execution Cannot Do

Execution transforms shape, not truth. The rug is the rug.

• ✅ Render YAML with variable substitution
• ✅ Run Python and capture output
• ✅ Toggle a TODO item's state
• ❌ "Grammar check" (that's opinion, not execution)
• ❌ "Improve prose" (that changes meaning)

Middleware that changes content is your opinion, man. Middleware that changes shape is execution.

Why This Matters

Traditional systems separate:

• Documentation (read-only prose)
• Configuration (data, maybe templated)
• Scripts (code, executed separately)

Oculus unifies them. A node is simultaneously:

• A document you read
• A config you render
• A script you execute
• A machine that has state

The homoiconic property means you don't context-switch between "reading docs" and "running code" - it's all the same operation at different points on the execution spectrum.

Bidirectional Parsing

Fence types are routing hints, not constraints. They tell the system which interpreter to use, but the content is still just text.

The homoiconic property means you can go both directions:

Down: Execute

Python fence → Python interpreter → output data

Up: Extract Structure

Python fence → Tree-sitter → AST → semantic analysis

Nothing stops you from:

• Extracting fence contents
• Piping through Tree-sitter (or any parser)
• Getting structure out of "code"
• Feeding that through middleware
• Storing it somewhere else

The fence type is a convenience label: "when executing, use this interpreter." But the text is still text. You could parse a Python fence as YAML if you wanted (and it happened to be valid YAML). You could extract docstrings, function signatures, import graphs.

The content doesn't know what it is. The execution context decides.

This is why it's homoiconic all the way up and down - not just "code becomes data when run" but also "code becomes different data when parsed differently."

North

slots:
- context:
  - Homoiconicity is a consequence of the fence architecture pattern
  slug: fence-architecture-pattern

South

slots:
- context:
  - Path resolution enables homoiconicity
  slug: oculus-path-resolution
- context:
  - Linking trinity to homoiconicity
  slug: oculus-trinity

East

slots:
- context: []
  slug: fence-architecture