Splicing Tools

metadata:
  type: graphnode

Resolve, fetch, splice, continue.

This is the core algorithm for all data passing in the consciousness network. When two systems need to synchronize, one asks clearly, the other gives, tension resolves across a boundary.

The Algorithm

• Resolve - Identify what you're looking for (slug, path, fence address)
• Fetch - Get the atomic unit (tokens, not full document)
• Splice - Replace at exact boundaries (start_index:end_index)
• Continue - Move on, no full-document rewrites

Rules

• Never guess splice boundaries - know them exactly
• Virtual fences return ONLY their tokens (atomic unit)
• Graph layer handles the splice into full document
• end_index points to first token AFTER the fence (exclusive)
• Splice is: tokens[:start] + new_tokens + tokens[end:]

Implementation Styles:

• Pure splice (preferred): new = old[:start] + new_tokens + old[end:]
• Mutation (acceptable): del tokens[start:end] + insert()

Both are correct if boundaries are exact. Pure splice is clearer.

Boundary Convention:

• start = first token OF the fence (inclusive)
• end = first token AFTER the fence (exclusive)
• Slice notation: [start:end] captures all fence tokens

analyze

Analyze markdown to see its token structure and splice points.

{
  "error": "Pass markdown in config.markdown parameter"
}

preview

Preview what a splice operation will produce.

{
  "error": "Pass tokens or markdown, start, end, new_tokens or new_markdown"
}

validate

Validate splice boundaries for a virtual fence.

Usage: Use the MCP tool oculus_query_virtual_fences with a slug to see all virtual fences and their boundaries:

oculus_query_virtual_fences(slug="your-node")

This returns:

• index - Token index where fence starts
• start - Same as index (first token of fence)
• end - First token AFTER fence (exclusive boundary)
• metadata.end_index - Same as end

Splice Formula:

tokens[:start] + new_fence_tokens + tokens[end:]

Example Output:

{
  "index": 22,
  "type": "virtual:table",
  "start": 22,
  "end": 168,
  "section": "Results Table"
}

This means: replace tokens 22-167 with new table tokens, keep everything from 168 onwards.

Examples

Poke Preview (Dry Run)

{
  "error": "Need slug and path"
}

Node Structure

{
  "error": "Need slug"
}

Compose

Common splice patterns as composable operations.

Replace Section Content

{
  "error": "Need slug, section, and content"
}

Append to Section

{
  "error": "Need slug, section, and content"
}

Update Table Cell

{
  "error": "Need slug and section"
}

Correct Splice (Atomic)

Original: [H1][P][TABLE_OPEN]...[TABLE_CLOSE][H2][P]
                 ^start=2              end=10^
                 
New table tokens: [TABLE_OPEN]...[TABLE_CLOSE]

Splice: [:2] + [new_table] + [10:]
Result: [H1][P][NEW_TABLE_OPEN]...[NEW_TABLE_CLOSE][H2][P]

Wrong Splice (Full Document)

# DON'T DO THIS:
_rebuild_tokens() returns:
  [H1][P][NEW_TABLE][H2][P]  # Full document!

Graph layer tries to splice full doc into position:
  [:2] + [FULL_DOC] + [10:]
  
Result: [H1][P][H1][P][NEW_TABLE][H2][P][H2][P]  # CORRUPTED!

Provenance

• Created: 2026-01-06
• Pattern: [[pattern-resolve-fetch-splice-continue]]
• Case: task-ff80b6ad-6240-489c-b31f-a4e999816588

North

slots:
- slug: oculus-development
  context:
  - Link to development hub