zap library

ZAP — Zuraffa Agent Protocol (spec 071, issue #809) public API.

Import this barrel to drive a ZAP host (or embed one) from your own code — no package:zuraffa/src/... implementation imports needed:

import 'package:zuraffa/zap.dart';

final host = await Process.start('dart', ['bin/zfa.dart', 'zap', 'serve']);
final client = ZapClient.overProcess(host)..start();
final receipt = await client.submit(mission);
if (!client.verifyReceipt(receipt)) throw 'the host lied';

The wire contract itself lives in specs/071-zuraffa-agent-protocol/contracts/zap.md; the schemas and golden examples third parties build against are under specs/071-zuraffa-agent-protocol/schemas/ and golden/.

Classes

CheckpointMessage
Agent ↔ host: save/restore session state.
EvidencePacket
Host → agent: certified step outcome.
MissionEnvelope
Agent → host: request work under budget and policy.
MissionStep
One mission step — a unit of work under budget and policy.
ScriptedZapStepExecutor
Deterministic executor for tests and the conformance suite.
SubprocessZapStepExecutor
The production executor: real subprocess, no shell.
ZapCheck
One receipt check (mission-schema, budget, ...).
ZapCheckpointStore
Checkpoint persistence: atomic tmp+rename writes (the SnapshotStore discipline from #808), restorable across host processes when the directory is shared.
ZapClient
The reference ZAP client.
ZapConformance
Runs the ZAP conformance suite.
ZapConformanceCheck
One conformance check: named, boolean, with a detail line.
ZapConformanceReport
The suite's verdict.
ZapError
Host → agent: structural rejection (the auxiliary type).
ZapGoldens
Golden examples for the four core message types.
ZapHost
The ZAP host: one line in, zero or more reply lines out.
ZapMessage
The sealed ZAP message family.
ZapProtocol
NDJSON envelope helpers for the ZAP wire protocol.
ZapReceipt
Host → agent: the verified verdict.
ZapSchema
Access to the five ZAP schemas (draft-07 maps).
ZapSession
One session's certified state.
ZapStepExecutor
Executes one mission step.
ZapStepRun
The result of executing one mission step.
ZapValidationIssue
One validation failure: where (path) and why (message).
ZapValidationResult
The outcome of validating one document.
ZapValidator
Validates raw ZAP documents against the ZAP schemas.

Constants

zapCoreTypes → const List<String>
The message types of the protocol.
zapDraft → const String
The draft-07 subset this implementation's schemas are limited to.
The first link of the chain (nothing hashed yet).
zapInboundTypes → const List<String>
Types an agent may send to the host (the inbound direction).
zapJsonEncoder → const JsonEncoder
The JSON encoding the exporter writes: two-space indent.
zapMessageTypes → const List<String>
All wire types (core + the auxiliary error).
zapOutputCap → const int
The evidence output preview cap (bytes→chars of the printed preview).
zapProtocolVersion → const String
The protocol version spoken by this implementation.
zapTimeoutExit → const int
The exit code convention for a step killed by its timeout.

Functions

zapCanonicalJson(Object? value) → String
The exact file bytes zfa zap schema --export writes for value — two-space-indented JSON plus one trailing newline. Every drift gate byte-compares committed files against this, so the published contract is writer-canonical, not merely structurally equal.
One chain link: sha256 over the payload.
zapChainPayload(Map<String, Object?> fact, String prevLink) → String
The payload of one chain link: version + certified facts + the previous link, null-separated (byte-stable, order-stable).
zapEvidenceChain(Iterable<Map<String, Object?>> facts) → String
The chain head over ordered evidence facts (maps carrying the certified facts: missionId, stepId, phase, command, exit, digest, at — exactly EvidencePacket.chainFact shape).
zapScriptedRun(MissionStep step, int exit, String output) → ZapStepRun
Builds a deterministic scripted run.

Exceptions / Errors

ZapSchemaException
Thrown when a message fails structural validation.