Lace-100 · Developer Surfaces Overview

Tags: overview, dx, event-stream, porcelain, non-normative

Lace’s durable truth is record bytes, record facts, Datalog policy, exchange plans, and interlace convergence. Applications should not have to drive raw protocol phases or inspect store internals to use that truth. This document summarizes the normal developer-facing surface above specs 010–060.

The main surface is an event-driven interlace runtime. Porcelain helpers such as get, list, and store are convenience APIs that construct and drive interlaces; they are not direct store access.

Core truth remains record-based

The lower specs define the protocol machinery:

010 records
020 record facts and views
030 Datalog
040 exchange policy
050 interlace
060 ILTP

Those layers are explicit about hashes, validated facts, peer advertisement claims, query views, exchange plans, and transfer invariants. Developer surfaces compile to or operate through those layers. They do not replace them with remote commands, raw database access, WebSocket-specific objects, or application-level truth shortcuts.

Records are table-shaped for developers

A validated record can be presented as an immutable row. Its hash is the row identity, and fields are columns. A projection, or table view, chooses field names such as Group, App, Name, TAI, Signed-By, and Data-Length, then shows one row per record hash with those fields as columns.

This table shape is a developer surface over validated record facts. It does not make rows mutable, does not make Group/App/Name unique, and does not expose raw store iteration. Public APIs still use interlace-backed porcelain and store machine boundaries.

Rules and selector DSLs define dynamic subsets of rows. Those subsets may depend on other rows, such as membership evidence, link targets, manifests, or current name records. Interlace converges the rows selected by both sides.

The normal runtime shape

A runtime package exposes a small application model:

FilesystemLace::open(...)
IndexedDbLace::open(...)
Lace::connect_websocket(...)

start_open_interlace(left, right, policy_or_plan) -> OpenInterlace
bounded_interlace(left, right, policy_or_plan) -> BoundedInterlace

list(target, selector_or_coordinate, options) -> ListOutcome
get(target, selector_or_coordinate, options) -> GetOutcome
store(target, records, policy_or_options) -> StoreOutcome
for_each(target, selector_or_coordinate, options) -> Open observation stream

Exact method names may differ by language/runtime, but the ownership cuts are stable:

Lace is a record-set authority backed by a runtime-owned record store machine. It owns validated record storage, StoreRecordId wake state, and runtime lifecycle state.
LaceHandle is a shareable participant capability. It is not a raw store, transaction, socket, WebSocket, or already-running protocol machine.
OpenInterlace and BoundedInterlace are runtime-owned drivers around a core interlace machine. They own runtime IO, timers, waiting, event queues, cancellation, and transport adapters.
Core remains sans-IO. Runtime packages own sockets, tasks, browser callbacks, wake routing, and lifecycle integration.
Record store machines own record persistence, local StoreRecordId assignment, policy-neutral record-fact access, record loads, and typed-record stores. Public app APIs do not expose raw record insertion, hash-existence checks, record counts, or store iteration.

Lace::connect_websocket(...) and similar transport helpers create or wrap a typed peer stream capability over ILTP bytes. They are not store-like objects and not remote command clients.

Starting an open interlace constructs an OpenInterlace driver. It is not the async wait point by itself. Waiting or await belongs to driving work: polling next_event, running a bounded interlace to completion, or using interlace-backed porcelain such as list, get, store, and for_each. Manual runtimes drive the same objects with explicit try_next_event-style steps.

Interlace event streams are the primary surface

Applications observe interlace progress through record/lifecycle event streams. Raw protocol facts, advertisements, side-machine phases, store-machine vtables, and InterlaceStepOutcome values are advanced/internal driver surfaces, not normal application events.

Conceptual public events are:

pub enum InterlaceEvent {
    RecordSent { side: InterlaceSide, record_hash: RecordHash },
    RecordSaved { side: InterlaceSide, record_hash: RecordHash, store_id: Option<StoreRecordId> },
    RecordListed { side: InterlaceSide, record_hash: RecordHash },
    FixedPoint,
    Complete { outcome: BoundedInterlaceOutcome },
    PeerClosed,
    Closed,
    LogicError { error: LogicError },
    RuntimeIoError { error: RuntimeIoError },
    RuntimeStoreError { error: RuntimeStoreError },
}

A runtime may include record bytes in events when doing so is cheap and well-owned, or may expose record hashes plus a follow-up record result. The event must remain record/lifecycle-oriented. It must not expose protocol fact blocks, MaySend/MayRequest internals, peer advertisement records, store cursors, raw NotAvailable machinery, or low-level side-machine phases as normal app API.

InterlaceSide is an event-correlation label for this interlace. It does not mean authority, source/sink direction, durable receipt, initiator, locality, or transport.

try_next_event-style APIs perform at most one natural core unit plus minimal runtime interpretation, then return an event or no-event/would-block status. next_event-style APIs may drive natural units until an event is available or a runtime wait point is reached, then wait on runtime-owned IO, store readiness, timers, or cancellation. Runtime wrappers must not hide an unbounded pump behind a callback or invoke application observers while store locks or transport callbacks are active.

After a terminal event (Complete, Closed, PeerClosed, or fatal error), later polls report stream exhaustion rather than rerunning closed work.

Event queues and transport buffers are bounded. If an application stops consuming events, or a peer stops accepting bytes, the runtime must backpressure, stop reading, cancel/close, or drop only explicitly diagnostic data according to a documented policy. It must not grow unbounded buffers or collapse record accounting events.

Porcelain is interlace-backed

get, list, store, and for_each are developer conveniences over interlace. They are allowed record access paths because they construct operation laces and run the same convergence machinery as explicit interlaces.

list(target, selector_or_coordinate, limit/options) is a bounded one-shot operation against any LaceHandle. It returns a finite result collection plus an operation status such as complete, more-may-exist, stale/incomplete, cancelled, or failed. It may use a trusted direct local list route when both the handle and policy allow it; otherwise it uses ordinary interlace.
get(target, selector_or_coordinate, options) is the bounded one-result form over the same selection machinery and returns an optional record/hash plus an operation status.
store(target, records, policy/options) creates or uses a source lace with typed validated records, runs a bounded provide/store interlace to the target, and returns a store operation outcome rather than an unbounded raw event buffer.
for_each(target, selector_or_coordinate, options) is the open/subscription porcelain. It runs an open interlace and invokes or yields record-lifecycle observations for each newly matching record until cancelled or closed.

Porcelain result types report operation-level outcomes: complete, more-may-exist, stale/incomplete, policy-refused or invalid input records, duplicate/no-op saves, cancellation, and failure. The public event stream used while driving the operation remains record/lifecycle-only.

Porcelain must not mutate a target store directly, inspect raw target store contents, or bypass store-machine boundaries. Trusted/direct local routes are optimized interlace routes over store-machine boundaries, not raw store bypasses.

Coordinates and DSLs are helper layers

Coordinates (110) and higher-level selector DSLs help applications name common record sets: coordinate prefixes, latest versions, linked closures, signed records, or application surfaces. They are developer input languages. They compile to explicit Lace policy artifacts: canonical lacegrams, exchange-plan operands, local executable policies, query-exposure constraints, and list/get, store, or for_each configuration.

A coordinate lookup may use a runtime/store index internally, but selected truth still comes from validated record facts and policy evaluation. A coordinate is not a replacement for record hashes, lacegrams, exchange plans, or store-machine boundaries.

Debuggability is diagnostic, not the normal event stream

Faceted exchange plans, operand scopes, origin-aware fact resolution, and query views are hard to inspect. Developer tooling should provide diagnostics such as source maps, rule ids, traces, and route reports explaining:

why a record was or was not selected;
why a fact was or was not queryable by a peer;
which rule generated MaySend(P) or MayRequest(P);
which local constraint blocked exposure or transfer;
which route an interlace chose and why;
which store operation was pending, blocked, incomplete, or failed at runtime.

These diagnostics are separate from the normal record/lifecycle event stream. Canonical protocol text remains annotation-free. Authoring tools may keep source annotations and map them back to canonical policy, but those annotations are not protocol facts.

Direction

The developer-facing layer should be convenient without hiding Lace’s ownership model: records are validated bytes, facts are explicit, query views control peer visibility, interlace converges record sets, runtimes own IO and waiting, and record store machines own persistence plus local StoreRecordId assignment. Normal applications should use interlace event streams and interlace-backed porcelain instead of raw protocol or store APIs.