ambitgraph 0.8.0__tar.gz → 0.8.2__tar.gz

{ambitgraph-0.8.0 → ambitgraph-0.8.2}/MANIFEST.in

@@ -7,15 +7,16 @@ prune docs
 prune build
 prune dist
 
-# Internal-only packages -- also excluded from the wheel via the packages list.
-prune ambit_contracts
-prune ambit_telegraph
-
 # Development evidence directories (screenshots, transcripts, review notes).
 # Both spellings: the dated evidence-* folders and the single evidence/ folder they moved into.
 prune evidence-*
 prune evidence
 
+# The repository's own responsibility record (.ambit/responsibility.jsonl):
+# it describes THIS repository's people and travels with the source tree,
+# never with the installed package.
+prune .ambit
+
 # Internal process documents.
 exclude AGENTS.md
 exclude CHANGELOG.md

{ambitgraph-0.8.0/ambitgraph.egg-info → ambitgraph-0.8.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ambitgraph
-Version: 0.8.0
+Version: 0.8.2
 Summary: Read-only codebase scan: reusable units, families, roles, ownership candidates, duplication.
 Author: AmbitGraph
 License: Proprietary

ambitgraph-0.8.2/ambit_contracts/__init__.py

@@ -0,0 +1,125 @@
+"""ambit_contracts -- dataclasses, JSON-schema dicts, validators and the
+shared text sanitizer for the Telegraph's wire, grant, household and edge
+contracts.
+
+Pure functions, stdlib only. NO I/O, NO file locking, NO clock, NO id
+minting: every id and timestamp used here is checked, never generated --
+that is why every validator in this package is testable with fixed inputs
+and no fixtures, and why `grant_is_active` takes `now` as an argument.
+
+The asymmetric import wall: `ambitgraph` (the engine) and `ambit_telegraph`
+(the message service) are BOTH permitted to import this package; it imports
+neither of them, nor anything outside the standard library.
+`tests/test_import_boundaries.py` is the mechanical guard and the ground
+truth for what the wall's other directions allow; read it, not this
+docstring, for their specifics.
+
+Reject, never repair: `clean` is what a CALLER uses to make a value
+acceptable before building a wire, and what every print boundary uses on
+the way out. The `validate_*` functions never mutate their argument -- an
+invalid value is refused, not silently cleaned up, so a corrupt or hostile
+wire is visible as corrupt rather than quietly repaired.
+"""
+from .edge import (
+    EDGE_EVENT_SCHEMA,
+    EDGE_STATES,
+    EdgeEvent,
+    edge_key,
+    edge_state,
+    has_channel,
+    validate_channel,
+    validate_edge_event,
+)
+from .envelope import (
+    EDGE_KINDS,
+    WIRE_KINDS,
+    WIRE_SCHEMA,
+    Wire,
+    validate_wire,
+    wire_from_dict,
+    wire_to_dict,
+)
+from .fields import (
+    CAPS,
+    CONTRACT_VERSION,
+    MAX_SEATS,
+    ContractError,
+    clean,
+    normalize_address,
+    validate_address,
+)
+from .grant import (
+    GRANT_SCHEMA,
+    GRANT_VERDICTS,
+    MASTER_OFF_SCHEMA,
+    REVOKE_SCHEMA,
+    Grant,
+    MasterOffEvent,
+    RevokeEvent,
+    grant_is_active,
+    grant_liveness,
+    validate_grant,
+    validate_master_off,
+    validate_revoke,
+)
+from .household import (
+    DESIGNATION_SCHEMA,
+    ROLES,
+    UNDESIGNATION_SCHEMA,
+    Designation,
+    Undesignation,
+    is_guest,
+    role_of,
+    validate_authorship,
+    validate_delivery,
+    validate_designation,
+    validate_undesignation,
+)
+
+__all__ = [
+    "CAPS",
+    "CONTRACT_VERSION",
+    "MAX_SEATS",
+    "ContractError",
+    "clean",
+    "normalize_address",
+    "EDGE_KINDS",
+    "WIRE_KINDS",
+    "WIRE_SCHEMA",
+    "Wire",
+    "validate_wire",
+    "wire_from_dict",
+    "wire_to_dict",
+    "GRANT_SCHEMA",
+    "Grant",
+    "validate_grant",
+    "grant_is_active",
+    "GRANT_VERDICTS",
+    "grant_liveness",
+    "REVOKE_SCHEMA",
+    "RevokeEvent",
+    "validate_revoke",
+    "MASTER_OFF_SCHEMA",
+    "MasterOffEvent",
+    "validate_master_off",
+    "DESIGNATION_SCHEMA",
+    "ROLES",
+    "Designation",
+    "role_of",
+    "is_guest",
+    "validate_delivery",
+    "validate_authorship",
+    "UNDESIGNATION_SCHEMA",
+    "Undesignation",
+    "validate_designation",
+    "validate_undesignation",
+    "validate_address",
+    "EdgeEvent",
+    "EDGE_EVENT_SCHEMA",
+    "EDGE_STATES",
+    "validate_edge_event",
+    "edge_key",
+    "edge_state",
+    "validate_channel",
+    "has_channel",
+]

ambitgraph-0.8.2/ambit_contracts/edge.py

@@ -0,0 +1,200 @@
+"""ambit_contracts.edge -- the edge model: a pure record and pure rules for
+authority and affinity edges between seats. This module lives BESIDE the
+five founding contracts, not inside ambit_telegraph, for the same reuse
+reason every shared type in this package exists: the CLI and the Household
+surface will both need to read an edge event, and a contract type living
+outside the contract layer would be re-derived by each of them -- reuse,
+never a second copy of a shape.
+
+In the local era the Household IS the org graph -- there is no separate
+graph file. An AUTHORITY edge exists IMPLICITLY from the principal to every
+seat whose role is exactly `member`: never written, derived from the
+registry on every call. Every OTHER edge -- authority in either direction,
+affinity between any two peers -- is an EXPLICIT ledger event that only the
+principal may append, switchable on and off by later events, latest-wins in
+append order. `edge_state` returns `None`, not `"off"`, when no event
+exists, which is the whole reason the implicit edge composes cleanly with
+the explicit ones: an explicit event ALWAYS beats the implicit edge, so the
+operator can write `authority FOUNDER->DEV off` and have it actually mean
+something, rather than being silently ignored.
+
+Authority edges are DIRECTED (either lexical order is a legal, distinct
+pair). Affinity edges are SYMMETRIC -- affinity is defined as "the two
+seats are related and can see each other's news", a mutual predicate
+with no word for a half-open state -- and `validate_edge_event` makes that
+symmetry MECHANICAL rather than a comparison scattered around every caller:
+an affinity event must name its two seats in canonical (normalized,
+ascending) order, so one relationship can never split across two spellings
+and two different latest-wins histories.
+
+Stdlib only (wall (c) of the Telegraph's import wall). No I/O, no clock:
+`edge_state` and `validate_channel` take the events list and the roles they
+need as arguments, the same purity line `role_of` already holds.
+"""
+from dataclasses import dataclass
+
+from .envelope import EDGE_KINDS
+from .fields import (
+    CAPS,
+    ContractError,
+    _require_address,
+    _require_id,
+    _require_timestamp,
+    _require_version,
+    build_schema,
+    normalize_address,
+)
+
+EDGE_STATES = frozenset({"on", "off"})
+
+# Same address shape as envelope.py's _ADDRESS_RE -- duplicated as a literal
+# rather than imported across modules, matching this package's own posture
+# toward small shared regexes (see envelope.py's own comment on caps).
+_ADDRESS_RE = r"^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$"
+
+
+@dataclass
+class EdgeEvent:
+    """A dumb, frozen-in-spirit record -- no validation in __post_init__,
+    same posture as Wire: the validator, not the dataclass, is the law."""
+    v: int
+    id: str
+    edge_kind: str      # authority | affinity (EDGE_KINDS)
+    seat_a: str
+    seat_b: str
+    state: str           # "on" | "off" -- a STRING enum, not a bool
+    ts: str               # informational, the ts law
+    set_by: str            # the principal's address
+
+
+EDGE_EVENT_SCHEMA = build_schema(EdgeEvent, "EdgeEvent", {
+    "v": {"type": "integer", "const": 1},
+    "id": {"type": "string", "pattern": r"^e-[a-z0-9]{8,62}$", "maxLength": CAPS["id"]},
+    "edge_kind": {"type": "string", "enum": sorted(EDGE_KINDS), "maxLength": CAPS["enum"]},
+    "seat_a": {"type": "string", "pattern": _ADDRESS_RE, "maxLength": CAPS["address"]},
+    "seat_b": {"type": "string", "pattern": _ADDRESS_RE, "maxLength": CAPS["address"]},
+    "state": {"type": "string", "enum": sorted(EDGE_STATES), "maxLength": CAPS["enum"]},
+    "ts": {"type": "string", "maxLength": CAPS["timestamp"]},
+    "set_by": {"type": "string", "maxLength": CAPS["address"]},
+})
+
+
+def validate_edge_event(event: EdgeEvent) -> None:
+    """Shape and enums; `seat_a != seat_b` case-insensitively (a self-edge
+    is the wire contract's self-address law, twin -- a seat authorising or
+    befriending itself is exactly what an edge exists to describe between
+    TWO seats); and, for affinity only, the canonical ascending seat order
+    that makes symmetry mechanical. `state` is checked against the STRING
+    enum only -- `isinstance(True, str)` is False, so a bool is refused by
+    the same branch as any other non-string, no special case needed."""
+    _require_version(event.v, "v")
+    _require_id(event.id, "e", "edge event id")
+    if not isinstance(event.edge_kind, str) or event.edge_kind not in EDGE_KINDS:
+        raise ContractError("edge event edge_kind is not one of authority or affinity")
+    _require_address(event.seat_a, "edge event seat_a")
+    _require_address(event.seat_b, "edge event seat_b")
+    if normalize_address(event.seat_a) == normalize_address(event.seat_b):
+        raise ContractError(
+            "edge event seat_a and seat_b are the same address; a seat may "
+            "not hold an edge with itself")
+    if not isinstance(event.state, str) or event.state not in EDGE_STATES:
+        raise ContractError("edge event state is not one of on or off")
+    _require_timestamp(event.ts, "edge event ts")
+    _require_address(event.set_by, "edge event set_by")
+
+    if event.edge_kind == "affinity":
+        if not normalize_address(event.seat_a) < normalize_address(event.seat_b):
+            raise ContractError(
+                "an affinity edge event must name seat_a and seat_b in "
+                "canonical (normalized, ascending) order; the relationship "
+                "is symmetric and must have exactly one spelling")
+
+
+def edge_key(edge_kind, seat_a, seat_b) -> tuple:
+    """authority -> (kind, norm(a), norm(b)), DIRECTED -- order preserved.
+    affinity -> (kind, min, max), SYMMETRIC -- the same key regardless of
+    argument order, so latest-wins can never split one relationship across
+    two orderings of the same pair."""
+    a, b = normalize_address(seat_a), normalize_address(seat_b)
+    if edge_kind == "affinity":
+        return (edge_kind, min(a, b), max(a, b))
+    return (edge_kind, a, b)
+
+
+def edge_state(edge_events, edge_kind, seat_a, seat_b):
+    """`None` means NO EVENT EXISTS -- never `"off"`. That distinction is
+    the whole reason the implicit edge composes cleanly with the explicit
+    ones (see the module docstring). The LAST matching event in LIST order
+    wins -- never sorted by `ts`, the same ordering law as every other
+    reduction in this contract (`role_of`'s twin)."""
+    target = edge_key(edge_kind, seat_a, seat_b)
+    result = None
+    for ev in edge_events:
+        if edge_key(ev.edge_kind, ev.seat_a, ev.seat_b) == target:
+            result = ev.state
+    return result
+
+
+_NO_AUTHORITY_CHANNEL = (
+    "there is no live authority edge from the sender to the recipient; a "
+    "wire needs an edge of its claimed kind, in its direction, and only "
+    "the principal may switch one on")
+_NO_AFFINITY_CHANNEL = (
+    "there is no live affinity edge between the sender and the recipient; "
+    "a wire needs an edge of its claimed kind, in its direction, and only "
+    "the principal may switch one on")
+
+
+def validate_channel(wire, sender_role, to_role, edge_events) -> None:
+    """The complete channel law -- the ledger law the wire contract defers
+    to: `edge_kind` is a CLAIM the wire makes about itself, and this
+    is where the claim is checked against the real edge. Mirrors the
+    household contract's `validate_delivery(wire, sender_role, to_role)`:
+    the caller looks up both roles (I/O), this function does none. Raises
+    `ContractError`, not a new type -- a wire travelling an edge that does
+    not exist is a false claim about itself, the same class as the nine
+    WIRE LAWS, and this package cannot see `TelegraphError` anyway (wall
+    (c): stdlib only).
+
+    (1) affinity -- live iff an explicit event says "on"; there is no
+        implicit affinity edge, ever, so no event at all refuses.
+    (2) authority -- a `receipt` travels the edge backwards ("a receipt for
+        a binding travels the same authority edge, backwards; edge_kind
+        names the edge, not the direction"), every other kind needs it
+        forwards. An explicit event on that directed pair always wins;
+        only when none exists does the implicit principal->member rule
+        apply, read in the direction the wire actually needs.
+    (3) not live -> ContractError naming no value.
+    """
+    if wire.edge_kind == "affinity":
+        if edge_state(edge_events, "affinity", wire.sender, wire.to) == "on":
+            return
+        raise ContractError(_NO_AFFINITY_CHANNEL)
+
+    if wire.kind == "receipt":
+        src, dst = wire.to, wire.sender
+    else:
+        src, dst = wire.sender, wire.to
+
+    explicit = edge_state(edge_events, "authority", src, dst)
+    if explicit is not None:
+        live = explicit == "on"
+    else:
+        role_src = (sender_role if normalize_address(src) == normalize_address(wire.sender)
+                    else to_role)
+        role_dst = (to_role if normalize_address(dst) == normalize_address(wire.to)
+                    else sender_role)
+        live = role_src == "principal" and role_dst == "member"
+
+    if not live:
+        raise ContractError(_NO_AUTHORITY_CHANNEL)
+
+
+def has_channel(wire, sender_role, to_role, edge_events) -> bool:
+    """The boolean twin of `validate_channel`, for a caller that wants a
+    yes/no answer rather than a raised, plain-words reason."""
+    try:
+        validate_channel(wire, sender_role, to_role, edge_events)
+        return True
+    except ContractError:
+        return False

ambitgraph-0.8.2/ambit_contracts/envelope.py

@@ -0,0 +1,237 @@
+"""The Wire -- the CONTRACT is the envelope; the OBJECT is a Wire.
+
+Four kinds travel it: receipt | status | ask | binding. A binding wire
+carries an instruction and MUST travel an authority edge with an
+acknowledgment demanded and a grant named; every other kind is news or a
+question and may never demand an ack or name a grant. These are the nine
+WIRE LAWS; `validate_wire`/`wire_from_dict` are the AUTHORITATIVE
+enforcement of all nine (`wire_from_dict` validates before it ever
+constructs a `Wire` that callers keep). `WIRE_SCHEMA` independently encodes
+six of the nine (shape, caps, control chars, and the four kind-conditional
+laws) so a consumer validating a raw dict against the published schema
+alone gets most of the same refusals -- see its `allOf` definition below
+for exactly which one law it cannot express.
+
+What this file CANNOT prove, stated rather than faked: `edge_kind` is a
+CLAIM the wire makes about itself. This module checks only that the claim
+is internally coherent (a binding wire claims an authority edge); checking
+the claim against the real graph edge, and matching a receipt to the
+binding it acknowledges, needs the ledger and is a ledger law, not a static one.
+"""
+from dataclasses import dataclass
+
+from .fields import (
+    CAPS,
+    ContractError,
+    _require_address,
+    _require_id,
+    _require_text_cap,
+    _require_timestamp,
+    _require_version,
+    build_schema,
+    normalize_address,
+)
+
+WIRE_KINDS = frozenset({"receipt", "status", "ask", "binding"})
+EDGE_KINDS = frozenset({"authority", "affinity"})
+
+
+@dataclass
+class Wire:
+    """A dumb, frozen-in-spirit record. No validation in `__post_init__` --
+    that would make it impossible to construct an invalid one for a test,
+    and the validator, not the dataclass, is the law."""
+    v: int
+    id: str
+    ts: str
+    sender: str
+    to: str
+    kind: str
+    edge_kind: str
+    body: str
+    requires_ack: bool
+    grant_id: object       # str (g-...) or None
+    in_reply_to: object    # str (w-...) or None
+    # OPTIONAL. One sentence a reader with zero context
+    # understands -- principle 16's line, as its own field rather than a
+    # marker inside the body. Defaults to None because 728 wires predate it
+    # and the ledger is append-only: every historical line must still read.
+    # Its rules are the body's law at a shorter cap: 200 characters, and
+    # control/bidi characters REFUSED, never scrubbed.
+    plain: object = None   # str (<=200, clean) or None
+
+
+# Same character-exclusion set as `clean`, spelled as a regex so the
+# published schema can refuse a bidi/control payload too, not only the
+# hand-written validator -- a schema without it once accepted a body
+# carrying a bidi override. Every code point
+# is an \x/\u escape, never a literal glyph -- this file's own bytes must
+# not carry the characters it exists to refuse.
+_NO_CONTROL_OR_BIDI = (
+    r"^[^\x00-\x1f\x7f-\x9f\u2028\u2029\u200e\u200f"
+    r"\u202a-\u202e\u2066-\u2069]*$")
+_ADDRESS_RE = r"^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$"
+# Deliberately loose -- shape only, matching `_require_timestamp`'s own
+# stated scope ("nothing checked but shape, parseability, tz-awareness"):
+# YYYY-MM-DD, a T or space, HH:MM:SS, optional fractional seconds, and
+# either Z or a +HH:MM/-HH:MM offset. Enough to refuse 'pwned' outright.
+_TIMESTAMP_RE = (
+    r"^\d{4}-\d{2}-\d{2}[T ]\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[+-]\d{2}:\d{2})$")
+
+WIRE_SCHEMA = build_schema(Wire, "Wire", {
+    "v": {"type": "integer", "const": 1},
+    "id": {"type": "string", "pattern": r"^w-[a-z0-9]{8,62}$", "maxLength": CAPS["id"]},
+    "ts": {"type": "string", "pattern": _TIMESTAMP_RE, "maxLength": CAPS["timestamp"]},
+    "sender": {"type": "string", "pattern": _ADDRESS_RE, "maxLength": CAPS["address"]},
+    "to": {"type": "string", "pattern": _ADDRESS_RE, "maxLength": CAPS["address"]},
+    "kind": {"type": "string", "enum": sorted(WIRE_KINDS), "maxLength": CAPS["enum"]},
+    "edge_kind": {"type": "string", "enum": sorted(EDGE_KINDS), "maxLength": CAPS["enum"]},
+    "body": {"type": "string", "pattern": _NO_CONTROL_OR_BIDI, "maxLength": CAPS["body"]},
+    "plain": {"type": ["string", "null"], "pattern": _NO_CONTROL_OR_BIDI,
+              "minLength": 1, "maxLength": CAPS["plain"]},
+    "requires_ack": {"type": "boolean"},
+    "grant_id": {"type": ["string", "null"], "pattern": r"^g-[a-z0-9]{8,62}$", "maxLength": CAPS["id"]},
+    "in_reply_to": {"type": ["string", "null"], "pattern": r"^w-[a-z0-9]{8,62}$", "maxLength": CAPS["id"]},
+})
+
+# The four kind-conditional WIRE LAWS (1/2/3, 4/5, 6), encoded so a consumer
+# validating a raw dict against WIRE_SCHEMA alone -- never having seen
+# `validate_wire` -- gets the same refusals. WHAT THIS CANNOT EXPRESS (same
+# honesty posture as the module docstring above): sender != to (the
+# self-address law) needs cross-field comparison that plain JSON Schema has
+# no keyword for; that law is enforced by `validate_wire` only.
+WIRE_SCHEMA["allOf"] = [
+    # LAW 1 -- binding travels authority only.
+    {
+        "if": {"properties": {"kind": {"const": "binding"}}, "required": ["kind"]},
+        "then": {"properties": {"edge_kind": {"const": "authority"}},
+                  "required": ["edge_kind"]},
+    },
+    # LAW 2 / 3 -- only binding may demand an ack, and it must.
+    {
+        "if": {"properties": {"kind": {"const": "binding"}}, "required": ["kind"]},
+        "then": {"properties": {"requires_ack": {"const": True}},
+                  "required": ["requires_ack"]},
+        "else": {"properties": {"requires_ack": {"const": False}},
+                  "required": ["requires_ack"]},
+    },
+    # LAW 4 / 5 -- only binding names a grant, and it must, well-formed.
+    {
+        "if": {"properties": {"kind": {"const": "binding"}}, "required": ["kind"]},
+        "then": {"properties": {
+            "grant_id": {"type": "string", "pattern": r"^g-[a-z0-9]{8,62}$"}}},
+        "else": {"properties": {"grant_id": {"type": "null"}}},
+    },
+    # LAW 6 -- a receipt names what it acknowledges.
+    {
+        "if": {"properties": {"kind": {"const": "receipt"}}, "required": ["kind"]},
+        "then": {"properties": {
+            "in_reply_to": {"type": "string", "pattern": r"^w-[a-z0-9]{8,62}$"}},
+            "required": ["in_reply_to"]},
+    },
+]
+
+
+def validate_wire(wire: Wire) -> None:
+    """The nine WIRE LAWS, in order: shape first (LAW 7, caps LAW 8,
+    control chars LAW 9), then the four semantic laws that read `kind`
+    against `edge_kind`/`requires_ack`/`grant_id`/`in_reply_to`."""
+    _require_version(wire.v, "v")
+    _require_id(wire.id, "w", "wire id")
+    _require_timestamp(wire.ts, "ts")
+    _require_address(wire.sender, "sender")
+    _require_address(wire.to, "to")
+    if normalize_address(wire.sender) == normalize_address(wire.to):
+        raise ContractError("wire sender and to are the same address; a wire may not address itself")
+    if not isinstance(wire.kind, str) or wire.kind not in WIRE_KINDS:
+        raise ContractError("wire kind is not one of receipt, status, ask or binding")
+    if not isinstance(wire.edge_kind, str) or wire.edge_kind not in EDGE_KINDS:
+        raise ContractError("wire edge_kind is not one of authority or affinity")
+    _require_text_cap(wire.body, CAPS["body"], "wire body")
+    if wire.plain is not None:
+        # Same law, shorter cap. An empty line is refused rather than
+        # stored: an author who wrote nothing wrote nothing, and absent
+        # already means that.
+        _require_text_cap(wire.plain, CAPS["plain"], "wire plain line",
+                          allow_empty=False)
+    if wire.requires_ack is not True and wire.requires_ack is not False:
+        raise ContractError("wire requires_ack is not a bool")
+
+    # WIRE LAW 1 -- binding travels authority only.
+    if wire.kind == "binding" and wire.edge_kind == "affinity":
+        raise ContractError(
+            "a binding wire may travel only an authority edge; this one is "
+            "addressed along an affinity edge, and affinity edges carry "
+            "news, never instructions")
+
+    # WIRE LAW 2 / 3 -- only binding may demand an ack, and it must.
+    if wire.kind == "binding":
+        if wire.requires_ack is not True:
+            raise ContractError("a binding wire must require an acknowledgment")
+    elif wire.requires_ack is not False:
+        raise ContractError("only a binding wire may require an acknowledgment")
+
+    # WIRE LAW 4 / 5 -- only binding names a grant, and it must, well-formed.
+    if wire.kind == "binding":
+        if wire.grant_id is None:
+            raise ContractError(
+                "a binding wire must name the grant that authorizes it; "
+                "absence of a grant is off")
+        _require_id(wire.grant_id, "g", "wire grant_id")
+    elif wire.grant_id is not None:
+        raise ContractError("only a binding wire may name a grant_id")
+
+    # WIRE LAW 6 -- a receipt names what it acknowledges; others may.
+    if wire.kind == "receipt":
+        if wire.in_reply_to is None:
+            raise ContractError(
+                "a receipt wire must name the wire it acknowledges in in_reply_to")
+        _require_id(wire.in_reply_to, "w", "wire in_reply_to")
+    elif wire.in_reply_to is not None:
+        _require_id(wire.in_reply_to, "w", "wire in_reply_to")
+
+
+def wire_from_dict(d: dict) -> Wire:
+    """Validate BEFORE constructing -- an invalid dict never becomes a Wire
+    a caller can hold onto."""
+    if not isinstance(d, dict):
+        raise ContractError("wire payload is not an object")
+    required = set(WIRE_SCHEMA["required"])
+    # OPTIONAL fields are known but not demanded: a wire written before the
+    # field existed must still read (the append-only law), and a wire carrying
+    # it must not be refused as "unknown". Everything outside this union is
+    # still refused outright -- one field became optional, the contract did
+    # not become permissive.
+    optional = set(WIRE_SCHEMA["properties"]) - required
+    actual = set(d.keys())
+    missing = required - actual
+    if missing:
+        raise ContractError(
+            f"wire is missing required field(s): {', '.join(sorted(missing))}")
+    if actual - required - optional:
+        # the extra key NAME came from outside the program -- DATA, never
+        # interpolated into the message: an error message must never carry
+        # a value an outsider chose.
+        raise ContractError(
+            "wire has an unknown field that is not part of the wire contract")
+    wire = Wire(**d)
+    validate_wire(wire)
+    return wire
+
+
+def wire_to_dict(wire: Wire) -> dict:
+    return {
+        "v": wire.v,
+        "id": wire.id,
+        "ts": wire.ts,
+        "sender": wire.sender,
+        "to": wire.to,
+        "kind": wire.kind,
+        "edge_kind": wire.edge_kind,
+        "body": wire.body,
+        "requires_ack": wire.requires_ack,
+        "grant_id": wire.grant_id,
+        "in_reply_to": wire.in_reply_to,
+        "plain": wire.plain,
+    }
+