wanderland-witness

Wanderland Witness

Oculus API regression test suite. The diff IS the error signal from the attractor.

Overview

Wanderland Witness is an external test harness that exercises core Oculus API operations and compares output against a known-good reference. Any drift from the reference represents an error signal - the system deviating from its stable attractor.

Control Theory Framing: In control systems, an attractor is a stable state the system naturally evolves toward. The reference file represents our attractor - the expected behavior. When the actual output drifts from the reference, the diff quantifies the error signal that needs correction.

Usage

# Run tests, show diff if any
wanderland-witness

# Update reference from current output
wanderland-witness --update

# Show full output
wanderland-witness --verbose

# Write results to this node
wanderland-witness --node

Files

File	Purpose
`~/.local/bin/wanderland-witness`	Test script
`~/.local/share/wanderland/witness/reference.txt`	Expected output (attractor)
`~/.local/share/wanderland/witness/output.txt`	Latest run output
`~/.local/share/wanderland/witness/diff.txt`	Error signal (when present)

Tests

1. Basic Node Read

Tests the fundamental node retrieval at all sprouting levels.

Endpoints: GET /api/oculus/node/{slug}?level={level}

Sprouting Levels (Jack and the Beanstalk pattern):

🌱 seed/raw - Magic bean, raw markdown
🌿 sprout/substituted - Variables resolved
🪴 stalk/interpolated - Includes assembled
☁️ clouds/rendered - Fences executed (default)

Implementation: api.py:583-613

source: $REPOS/wanderland/oculus-api/oculus/api.py
lines: 583-613
title: Node Read Implementation

Test	Status	Notes
Read node (default)	✅	Returns markdown
Read node (seed/raw)	✅	No processing
Read node (sprout)	✅	Variables resolved
Read node (clouds)	✅	Fences executed

2. Peek Operations

Tests reading values at deep paths using unified addressing grammar.

Endpoint: GET /api/oculus/peek/{slug}?path={path}&level={level}

Unified Addressing Grammar:

section → prose + rendered fences
section.yaml → first YAML fence data
section.yaml[0] → explicit first YAML fence
section.pantry → fence with label="pantry"
section.fences[*] → all fences
section.fences[type=ruby] → filtered fences

ISA Levels (Q/K/V attention semantics):

@L3 → Code: raw fence content ("what are you made of?")
@L4 → Data: parsed/executed result ("what do you produce?")
@L5 → Document: formatted for display ("how do you present?")

Implementation: api.py:1864-1894

source: $REPOS/wanderland/oculus-api/oculus/api.py
lines: 1864-1894
title: Peek Implementation

Test	Status	Notes
Peek prose section	✅	PathResolutionError if no fences (expected)
Peek YAML data	✅	Returns parsed fence data
Peek at L3 (sprout)	✅	Variables resolved
Peek at L4 (stalk)	✅	Interpolated
Peek at L5 (clouds)	✅	Fully rendered

3. Fence Discovery

Tests querying and retrieving fence metadata.

Endpoints:

GET /api/oculus/fences - List all fences
GET /api/oculus/fences?type={type} - Filter by fence type
GET /api/oculus/fences?slug={slug} - Filter by node
GET /api/oculus/fences/{fence_id} - Get specific fence

Addressing Modes:

Label: list-bookmarks (global lookup)
Slug:Label: fence-bookmarks:list-bookmarks
Slug:Index: fence-bookmarks:3

Implementation: api.py:3623-3675 and api.py:4340-4434

source: $REPOS/wanderland/oculus-api/oculus/api.py
lines: 3623-3675
title: Get Fence by ID

source: $REPOS/wanderland/oculus-api/oculus/api.py
lines: 4340-4380
title: List/Query Fences

Test	Status	Notes
List all fences	✅	Returns 414+ fences
Query by type	✅	Filters by python, yaml, etc
Query by slug	✅	Returns fences for specific node
Get fence by label	✅	Global label lookup
Get fence by slug:label	✅	Scoped lookup

4. Fence Execution

Tests executing fences with various addressing modes.

Endpoints:

POST /api/oculus/fences/{fence_id}/execute - By label
POST /api/oculus/nodes/{slug}/fences/{fence_id}/execute - By slug

Request Body:

{
  "params": {"key": "value"},
  "format": "json",
  "force": false
}

Implementation: api.py:4000-4340 and api.py:4603-4802

source: $REPOS/wanderland/oculus-api/oculus/api.py
lines: 4000-4060
title: Fence Execute Endpoint

Test	Status	Notes
Execute by label	✅	Global fence lookup
Execute by slug:label	✅	Scoped execution
Execute by slug:index	✅	Positional addressing
Execute with params	✅	Passes config to fence

5. Virtual Fences

Tests detection and querying of virtual fences (TODO lists, tables, etc).

Endpoints:

GET /api/oculus/virtual-fences - List all virtual fences
GET /api/oculus/virtual-fences?fence_type={type} - Filter by type

Virtual Fence Types:

virtual:todo-list - Markdown checklists
virtual:table - Markdown tables
virtual:callout - Admonition blocks

Implementation: api.py:5199-5258

source: $REPOS/wanderland/oculus-api/oculus/api.py
lines: 5199-5258
title: Virtual Fences Query

Test	Status	Notes
List virtual fences	✅	Returns 200+ detected patterns
Query by type	✅	Filters todo-list, table, etc

6. Graph Structure

Tests graph navigation and structure queries.

Endpoints:

GET /api/oculus/edges/{slug} - Get directional links
GET /api/oculus/edges/{slug}?depth={n} - Multi-hop traversal
GET /api/oculus/nodes - List all nodes
GET /api/oculus/nodes/similar/{slug} - Fuzzy search

Direction Convention:

North: Parent/overview
South: Children/details
East/West: Siblings/related

Implementation: api.py:1426-1572

source: $REPOS/wanderland/oculus-api/oculus/api.py
lines: 1426-1480
title: Get Node Edges

source: $REPOS/wanderland/oculus-api/oculus/api.py
lines: 1508-1572
title: List Nodes & Similar

Test	Status	Notes
Get node edges	✅	Returns N/S/E/W links
Get edges (depth=2)	✅	Multi-hop traversal
List nodes	✅	Returns 1800+ nodes
Find similar	✅	Fuzzy matching works

7. Tags

Tests tag-based discovery and filtering.

Endpoints:

GET /api/oculus/tags - List all tags with counts
GET /api/oculus/tags/find/{tag} - Find nodes with tag

Tag Conventions:

namespace:value for categories (e.g., status:active)
Simple tags for topics

Implementation: api.py:2873-2919

source: $REPOS/wanderland/oculus-api/oculus/api.py
lines: 2873-2919
title: Tag Operations

Test	Status	Notes
List all tags	✅	Returns taxonomy with counts
Find by tag	✅	Returns matching node slugs

8. Reading Lists

Tests the reading list pattern (semantic bookmarking).

Fences:

get-reading-list - Get slugs for a topic
execute-reading-list - Load all nodes

Implementation: See [[required-reading]] node

Test	Status	Notes
Get reading list fence	✅	Fence metadata returned
Execute reading list	✅	Returns slugs for topic

9. Search & Grep

Tests full-text search using ripgrep.

Endpoints:

GET /api/oculus/grep?q={query} - Search content
GET /api/oculus/grep?q={query}&mode=count - Match counts

Options:

mode: matches, files, count
limit: max results
context: lines around match
glob: file pattern filter

Implementation: api.py:2697-2873

source: $REPOS/wanderland/oculus-api/oculus/api.py
lines: 2697-2760
title: Grep/Search Endpoint

Test	Status	Notes
Grep search	✅	Returns results array
Grep count mode	✅	Returns match count

Run History

runs:
- timestamp: "2026-01-10T20:53:33-05:00"
  status: PASS
  tests: 30
  drift_lines: 0
  note: Reference updated with correct API routes

Run Tracking Fence

{
  "timestamp": "2026-01-27T14:44:21.392854",
  "status": "UNKNOWN",
  "tests": 0,
  "drift_lines": 0,
  "note": ""
}

Latest Run

Full output: ~/.local/share/wanderland/witness/output.txt Reference: ~/.local/share/wanderland/witness/reference.txt Diff (if any): ~/.local/share/wanderland/witness/diff.txt

Run wanderland-witness --verbose to see full test output.

[[cmd-peek]] - Peek command documentation
[[cmd-poke]] - Poke command documentation
[[fence-architecture-pattern]] - Fence system design
[[required-reading]] - Reading list pattern

Slots

North

slots:
- slug: oculus
  context:
  - Linking witness to main oculus node

South

slots: []

East

slots:
- slug: wtf-am-i-doing
  context:
  - Linking to activity introspection dashboard

West

slots: []

Provenance

Document

Status: 🔴 Unverified

Changelog

2026-01-11 01:54: Node created by mcp - Creating wanderland-witness documentation node with API test coverage

North

East

↑ northoculus

→ eastwtf-am-i-doing

Wanderland Witness

Overview

Usage

Files

Tests

1. Basic Node Read

2. Peek Operations

3. Fence Discovery

4. Fence Execution

5. Virtual Fences

6. Graph Structure

7. Tags

8. Reading Lists

9. Search & Grep

Run History

Run Tracking Fence

Latest Run

Related

Slots

North

South

East

West

Provenance

Document

Changelog

North

East