Wanderland Core: Developer Guide

The developer's entry into wanderland-core. Orientation, reading paths, and the concepts, shapes, and boundaries that compose the gem.

This guide learns

These nodes hold the shared working memory for people and agents building against wanderland-core. Reading them means reading the current distillation — the shapes that held up in real work, the best practices that surfaced, the framings the team has arrived at.

New understanding folds back in. When something sharper surfaces in the course of the work — a cleaner framing, an undocumented constraint, a pattern worth elevating — the node gets updated as part of that work. The code is the source of truth for mechanics; these nodes are the source of truth for framing. Drift between the two is a bug to fix.

What it is

A Ruby gem that reads YAML and runs as a service. Every request walks a chain of small callable units — boundaries. Every boundary produces a crossing: a signed, hash-linked record of what it did. The chain of crossings is a Merkle DAG over the request lifecycle. Audit, tracing, and provenance fall out of running the service at all.

The same YAML boots an HTTP server (Rack) and a CLI binary (Commander). Routes are commands. Adapters swap above the dispatch seam; the substrate below stays the same.

The four big ideas

Boundary. A callable with declared identity, capabilities, requirements, and an optional when_shape: guard. Wraps a single logical operation. Registered by name; invoked by name.

Crossing. The signed record produced by a boundary execution. Carries boundary name, from/caller/to addresses, requirements, capabilities, result, timestamp, type_addr, signature, and a trace field linking back to the previous crossing. The unit of audit.

Context. An append-only stack of crossings. Boundaries read from it; the engine writes to it. context["key"] gives the last-wins value projection; context.boundary_name gives the full provenance record. Chainable filters (.signed, .by_identity, .for_boundary, .with_capability, .since(n)) narrow before resolution.

Chain. An ordered list of boundary slots. Each slot has a when: guard. The walker visits every slot, evaluates the guard against the current context, and runs or skips. Exception handling, signal routing, and cleanup all fall out of when: plus the type_addr prefix vocabulary.

How to read this guide

The guide mirrors the product site's Diataxis layout — reference, tutorials, how-to, explanation. This section is reference. Five categories break down the engine:

Engine        request lifecycle: routing, chains, context, dispatch, flow control
Storage       crossings on disk, IOU extraction, the Merkle DAG, format
Identity      identity, authorization, IDP, PKI
Patterns      the primitives patterns compose on — boundary, shape-matcher,
              archetype, overlay, template engine, scenario, injections
Observability logging and tracing

Each category has an index page with distilled shapes, best practices, and worked examples, plus links to the leaves that go deeper.

Contents

• Engine — The request lifecycle. How a YAML config becomes a listening service, how a request walks a boundary chain, and how the context accumulates crossings along the way.
• Storage — How crossings persist. Prefix-mount routing, append-only driver contracts, IOU extraction for large payloads, format boundaries, and the hash-linked Merkle DAG that makes the trace tamper-evident.
• Identity and Compliance — Who signs what. The identity model, the authorization gate protocol, the identity provider backend, and PKI as storage.
• Patterns — The primitives every boundary leans on. Registration, shape matching, archetypes, injections, overlay operators, the template engine, scenarios, and the game dispatcher.
• Observability — Block-based lazy logging and the tracer that records every crossing.

Related

• Wanderland Core — Landing page for the gem itself. Install, license, quick start.
• Scenarios How-to — Task-oriented guide for writing scenario YAML.
• Hello World tutorial — First crossing, walk-through.