grid_exploration library

Exploration-protocol host for the_grid.

Hosts a GridControllerPlugin speaking lenny's ext.exploration.* wire protocol (handshake / get_stable_observation / namespaced tools) via dart:developer service extensions. Until lenny's exploration_contract extraction lands (lenny M0), wire shapes are mirrored here and verified against lenny source. See ADR-0001 Decision 6.

Classes

DevModeSeat

The exploration host, read-only runtime, and advertised VM-service URI for one JIT station.

GridControllerPlugin

The grid plugin: namespace grid, contributing the read/observe tools over a GridControllerRuntime. Pure — every method returns plain JSON maps, so the whole plugin is unit-testable without a VM service. The host (GridExplorationHost) wires these into dart:developer extensions.

GridExplorationHost

Minimal pure-Dart exploration host for the_grid (ADR-0001 Decision 6).

GridToolDescriptor

Declared shape of a grid tool — its bare name, description, and input schema — surfaced in the handshake and (eventually) to the exploration agent's tool catalog.

JoinedWorkReader

Reads a station's already-joined work graph.

ReassembleTool

Contributes the single dev-mode reload tool into the grid namespace.

Constants

kExplorationPrefix → const String

VM-service extension prefix for the_grid's exploration host.

kExtensionsKey → const String

Serialized map key carrying the per-namespace extension entries/fragments in both the handshake (extensions: [{namespace, tools}]) and the stable observation (extensions: {<ns>: <fragment>}).

kGridNamespace → const String

The grid plugin's namespace; tools are exposed at ext.exploration.grid.<tool>.

kProtocolVersion → const String

Exploration protocol version this host speaks.

Functions

armDevMode({required String? vmServiceUri, required StationReassemble hotReload, required StationReassemble hotRestart, required GraphSnapshot latest(), required String readPath()}) → Future<DevModeSeat?>

Arms a dev-mode seat only when this process exposes vmServiceUri.

beadSummary(Bead bead) → Map<String, Object?>

A compact, bounded JSON summary of a bead (events/observations carry these rather than full beads to stay within observation budgets).

coreExtension(String suffix) → String

Fully-qualified extension method name for a core method.

graphEventToWire(GraphEvent event) → Map<String, Object?>

Serializes a GraphEvent to a compact wire object. Exhaustive over the sealed union (compiler-checked), so a new event variant forces an update.

gridExtension(String tool) → String

Fully-qualified extension method name for a grid tool.

stationVmServiceUri() → Future<String?>

This station's own VM-service URI, or null when it is not running under --enable-vm-service (an AOT binary). A JIT runner advertises it in the 0600 station.lock so the reload client can find the target; an AOT runner never calls it, and the client then classifies the station as not-dev-mode.

statsToWire(GraphSyncStats stats) → Map<String, Object?>

Serializes sync-loop stats for the stats tool / observation stability.

Typedefs

StationReassemble = Future<Map<String, Object?>> Function()

One reassemble verb, as the host sees it: a callback returning the wire body of what the re-composition DID.