FORAY Protocol Specification

A FORAY record is JSON in which every Root-substance key is a catalog code matching F[0-9]+, placed directly at its level, and every other key is envelope apparatus. There are no wrapper objects between substance and envelope (the lexical boundary rule — amendment §1). Within the value of an F-coded member, inner keys are the fact's catalog-defined structure, never independently F-coded: party entries and allocation entries are the models.

The readable names used in prose — Root fact names ("settled amount") and the foray_* implementer register (foray_settled_amount) — are human-facing vocabulary for field-map sheets, adaptor code, and pages like this one. They are compiled to F-codes at emission and never appear in hashed bytes. Four layers, one fact: client schema → Reference display names → implementer register → the F-coded wire (hashed, anchored, persisted).

Envelope apparatus at the transaction level: schema_version (the constant "4.2"), timestamp, the four component arrays, attestations (optional — see the trust model's attestation posture), component_hashes, merkle_root, blockchain_anchor, and the optional audit_data_anchor and privacy_metadata. Inside a component element the only envelope member is id. In-record timestamps are submitter assertions; the trust model states what anchoring proves about time.

The ratified fact catalog. F-numbers are permanent: additions extend, nothing renumbers, gaps are meaningless. (Catalog and register: ratification decision sheet v1.1; wire placement per its D-W ruling; scope corrections per amendment §2.)

Retired at 4.2, rejected with the culprit named: the pre-4.2 English wire spellings, all wrapper objects, terms, description, entity_hash, dependencies, condition, the period wrapper, compliance flags as a field (they ride in F25 as recorded assertions when the record's author supplies them), any foray_* register name used as a wire key, and residue outside F25's two positions (amendment §2.1, §5.3).

Four component classes — Arrangements (contractual and authority setup), Accruals (economic obligations and policy evaluations), Anticipations (expected flows and behaviors), Actions (executed settlements and performed acts) — with at least one element of any class per record, and any class a legal entry point. Element requiredness: Arrangement id/F4/F5/F11; Accrual id/F22; Anticipation id/F22/F23/F27/F28; Action id/F22/F23/F24/F9.

References are many-to-many arrays resolving to element ids inside the same record; a dangling reference is invalid. An Action settling multiple references attributes the amount in F21, and entry amounts must equal F9 exactly, compared as decimal values (amendment §7.1.5) — no float tolerance; zero-decimal and three-decimal currencies need no special casing.

Every numeric wire value MUST be exactly representable in at most 15 significant decimal digits — the guaranteed-exact regime of binary64 (amendment §7.1.2). Its canonical spelling is the shortest decimal representation that round-trips the value, in plain decimal notation at every magnitude: no exponent form (0.00000001, never 1e-8), no trailing fractional zeros (5000, never 5000.00), no superfluous leading zeros, no negative zero, no explicit plus. Exactly one byte spelling per value.

The canonical byte form of a record — the form that is hashed — applies JCS (RFC 8785) encoding with a spec-defined member order and the stricter number rule above (amendment §7.1): within every fact-bearing object, F-coded members serialize first in ascending numeric F-number, then envelope members in their fixed enumeration; inside a component element, id serializes last; envelope-object interiors and F25 residue interiors sort lexicographically; arrays are never reordered — element order is content, not encoding.

Below the record sits the anchored-value byte layout (the batch-header struct and its exact field-order encoding, amendment §7.2): big-endian multi-byte integers, segments in ascending (stream_id, first_seq) order, and a single legal byte encoding for the anchored value. Interop vectors derived from these rules are the core of the conformance suite.

A conformant validator judges "4.2" records against the canonical 4.2 schema plus the coded cross-field rules: the decimal profile, currency resolution through the F8 inheritance chain, exact-decimal allocation sums, reference resolution, the named-culprit presence rules, and F2 presence with its equality semantics (amendment §5.1).

Legacy acceptance is permanent. Records carrying schema_version "4.1" or "4.0" are accepted indefinitely: validated against their own version's canonical shape (the 4.1 record remains that authority), converted through the deterministic migration chain (amendment §4 — mechanical, never semantic; fails loudly with a named error rather than guess), and labeled legacy. Evidence is long-lived; the acceptance path never sunsets.

The conformance terminus is in effect. As of the 4.2 publication of this site, emitting pre-4.2 wire is non-conformant production (amendment §5.4): such records are still accepted, converted, and labeled — the evidence is innocent of the producer's lateness — and the validation response carries a stated non-conformance notice. The teeth are conformance status and engagement terms, never service refusal.

The live validator is public: POST https://foray.dunin7.com/api/validate-foray.

Independent verification is specified, not promised. The Verifier Specification (also served as markdown) defines the complete verifier law — input classes, per-class algorithms, the finding taxonomy, and the byte-exact serialization procedures — so that "verification requires no access to DUNIN7" is an implementable statement, not a claim. Behind it stands an offline conformance suite (repository DUNIN7/foray-api, conformance/): 66 vectors across five families with a one-command, no-network runner that executes any candidate verifier through a documented interface.

The wire's opacity is a deliberate implementation control. A wire key like F7 cannot be plausibly guessed — there is no English word to autocomplete toward — so every field an implementation emits, human- or AI-authored, is a field that was looked up in the catalog above. The opacity forces the lookup: guessed-name drift, the classic failure of AI-written integrations, has nothing to attach to. What it does not prevent is semantic misuse — a correctly spelled F-code carrying the wrong source fact is still possible, which is what the validator's rules and the field-map conversation exist to catch.

The working discipline is a closed loop: generate a record, POST it to /api/validate-foray, and repair every error and every W3 canonical-spelling warning before shipping. The endpoint is the conformance arbiter — not any reading of this page, however careful. An implementation that passes the validator with zero findings conforms; one that relies on prose interpretation does not get to argue with the error list.

The machine-authoritative texts this page presents are the canonical 4.2 JSON Schema (the sole owner of wire names) and the F-Wire Migration Amendment. Point tooling at those and the validator; use this page and the implementer register (foray_*) for the human side of the field-map conversation.

Everything in this section is a choice of the reference deployment, not the protocol. An implementation may vary these without affecting wire conformance.

Anchoring substrate. The reference implementation anchors to Kaspa — the first reference substrate, not a constitutive part of the protocol. The protocol defines the anchoring envelope and its byte discipline; the substrate records it. Substrate assurance classes, rotation, and archive pairing are governed by the anchor-assurance amendment lineage.

Anchoring modes and cadence. Direct mode (one record, one write) serves demonstrations and low-frequency streams; batched mode (one write per window per lane) is the production design. Lane windows, congestion caps, and each lane's declared worst-case bound (T_max) are registered deployment parameters — contractual per lane, not protocol constants.

Capacity posture. The reference deployment budgets a small absolute write rate to the substrate, chosen to be negligible to the network rather than derived from its capacity; high-frequency streams route through aggregation tiers.

Body availability and custody. The chain holds commitments, never records. Proof material (bodies, trees, salts) is holder-side custody: retention periods, dual-write storage, archive independence, and retention attestations are service and engagement parameters. A lost salt or body makes an anchor an unprovable commitment — custody is where that risk is managed, and the Evidence Custody Model states the holder's package, retention discipline, and completeness instrument in full.

FORAY records are tamper-evident. Validation PASS attests conformance to the ruled shape, never truth of content. Residue (F25) is recorded, not validated. A salted formula identifier proves definition retention — which formula was declared and that it is unaltered since — never that the formula ran, or ran correctly. FORAY makes the originating system's declarations tamper-evident; it does not make them true. The full statement of what FORAY proves and does not prove is the trust model, and it is normative over every claim on this site.

Normative instruments behind this edition: the F-Wire Migration Amendment (Protocol v4.2) and its governing catalog ratification; the canonical 4.2 JSON Schema (the sole owner of wire names — served here byte-identically to the committed instrument); the batch-anchoring amendment lineage for the anchoring layer (its publication edition is served on this site) and the anchor-assurance lineage; the 4.1 specification record for the legacy shape. Where this page and any of those instruments could be read to differ, the instrument governs.