Skip to content

zettelkasten.synapse.memdsl.schema

zettelkasten.synapse.memdsl.schema

In-memory contract types for MemDSL — the machine-checkable synapse protocol.

MemDSL is the versioned, bidirectional CONTRACT through which the deterministic synapse engine renders a heterogeneous knowledge substrate to a reasoning agent (the RENDER direction) and the agent returns actions plus a cited reasoning-DAG that the engine can verify (the OUTPUT direction). It is a contract, not a compression scheme: its job is to make epistemic honesty structurally enforceable — the engine emits every node's epistemic status, the agent can only cite, and any hole in coverage is rendered as a first-class gap rather than silently dropped.

This module defines the domain-agnostic in-memory representation only; the line-oriented (de)serializers live in :mod:zettelkasten.synapse.memdsl.parser. Nothing here bakes in domain content: the same types serve a schema table, a document passage, a temporal series, or any of the zettelkasten note types.

Design invariants pinned here:

  • Unified addressing (:class:Address) — store:source:id plus an optional locator that encodes external-dataset provenance shapes (a passage char-offset span, a temporal as-of stamp) without a schema change. The session/work store prefixes are RESERVED for future session-scoped mutable working state (v1 never emits them, but the scheme does not preclude them).
  • Engine-owned epistemics (:class:EpistemicStatus) — a node's status is emitted BY the engine on the render side. The OUTPUT side (:class:Claim) carries only an :class:InferenceForm; there is deliberately no field through which an agent could assert grounded. Its values mirror :data:zettelkasten.graph.VALID_EPISTEMIC_STATUS so the vocabulary cannot drift (guarded by a round-trip test).
  • First-class gaps (:class:GapToken) — stale / unresolved / missing / elided absence is a rendered token, never a silent drop, so calibrated abstention can see the hole.
  • Open action registry (:data:ACTION_REGISTRY) — the v1 read actions (expand/join/ground/prune/abstain/answer) are entries in a registry that new write/apply actions can extend WITHOUT re-cutting the grammar.
  • Registry-driven per-type bodies (:data:NODE_TYPE_REGISTRY) — a new node type resolves to a default text body codec and degrades gracefully instead of crashing the parser.
  • Versioning (:data:FORMAT_VERSION) — every serialized artifact embeds the version, and the action-response fragment is shaped to later report state mutations + impact sets even though v1 emits only read results.

MemDSLError

Bases: Exception

Base class for every MemDSL contract error.

Source code in zettelkasten/synapse/memdsl/schema.py 
77
78
class MemDSLError(Exception):
    """Base class for every MemDSL contract error."""

MemDSLParseError

Bases: MemDSLError

A serialized MemDSL artifact was malformed or of an unsupported version.

Raised by the parser on a missing/wrong header, an unparseable address, an unknown or badly-ar'd action, or a malformed reasoning-DAG. Unknown NODE TYPES are NOT an error — they degrade to the default body codec — so this is reserved for genuine grammar violations.

Source code in zettelkasten/synapse/memdsl/schema.py 
81
82
83
84
85
86
87
88
class MemDSLParseError(MemDSLError):
    """A serialized MemDSL artifact was malformed or of an unsupported version.

    Raised by the parser on a missing/wrong header, an unparseable address, an
    unknown or badly-ar'd action, or a malformed reasoning-DAG. Unknown NODE
    TYPES are NOT an error — they degrade to the default body codec — so this is
    reserved for genuine grammar violations.
    """

EpistemicStatus

Bases: str, Enum

The machine-checkable epistemic status the engine stamps on a node.

Values mirror :data:zettelkasten.graph.VALID_EPISTEMIC_STATUS exactly so the render contract and the note store share one vocabulary. This status is engine-emitted on the RENDER side only; nothing on the OUTPUT side lets an agent assert it. UNKNOWN/unresolved absence is represented by a :class:GapToken, not by a status value, so it is never confused with a positive claim of groundedness.

Source code in zettelkasten/synapse/memdsl/schema.py 
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
class EpistemicStatus(str, Enum):
    """The machine-checkable epistemic status the engine stamps on a node.

    Values mirror :data:`zettelkasten.graph.VALID_EPISTEMIC_STATUS` exactly so
    the render contract and the note store share one vocabulary. This status is
    engine-emitted on the RENDER side only; nothing on the OUTPUT side lets an
    agent assert it. ``UNKNOWN``/unresolved absence is represented by a
    :class:`GapToken`, not by a status value, so it is never confused with a
    positive claim of groundedness.
    """

    GROUNDED = "grounded"
    MEASURED = "measured"
    INFERRED = "inferred"

InferenceForm

Bases: str, Enum

The reasoning form connecting a claim's cited nodes to the claim.

Domain-agnostic taxonomy the epistemics layer later maps onto :data:zettelkasten.graph.VALID_RELATIONS for status propagation. Carried on the OUTPUT side (:class:Claim) so the engine can re-derive a claim's status from its cited nodes and its form, rather than trusting an agent assertion.

Source code in zettelkasten/synapse/memdsl/schema.py 
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
class InferenceForm(str, Enum):
    """The reasoning form connecting a claim's cited nodes to the claim.

    Domain-agnostic taxonomy the epistemics layer later maps onto
    :data:`zettelkasten.graph.VALID_RELATIONS` for status propagation. Carried on
    the OUTPUT side (:class:`Claim`) so the engine can re-derive a claim's status
    from its cited nodes and its form, rather than trusting an agent assertion.
    """

    RESTATEMENT = "restatement"  # a direct, verbatim grounding in one node
    DEDUCTION = "deduction"      # necessarily follows from the cited premises
    INDUCTION = "induction"      # generalized from cited instances
    ABDUCTION = "abduction"      # best explanation of the cited evidence
    CALCULATION = "calculation"  # computed via ``derivation`` from cited numbers
    COMPARISON = "comparison"    # relation established by comparing cited nodes
    CAUSAL = "causal"            # a cause/effect link asserted over cited nodes
    ANALOGY = "analogy"          # mapped from a cited analogue
    ASSUMPTION = "assumption"    # asserted without a mechanical ground (inferred)

GapKind

Bases: str, Enum

The kind of a first-class absence token.

Absence is always rendered, never dropped, so a coverage-gated abstention can reason about the hole:

  • STALE — the node's tether drifted since it was pinned.
  • UNRESOLVED — a referenced address did not resolve to a node.
  • MISSING — an expected hop/relation is absent from the substrate.
  • ELIDED — a body was truncated to a lossy view; a ground re-fetches it. Truncation must never silently break a verbatim-quote check, so the elision is explicit.
  • OUTDATED — the node's git pin is a faithfully-cited-but-SUPERSEDED commit: the pinned bytes are still a retrievable immutable git object (so the node stays GROUNDED — this is a DISCLOSURE, not an abstain-forcing taint like STALE), but HEAD has since moved on, so a consumer must be told "grounded as of the pinned sha; the current file may differ".
Source code in zettelkasten/synapse/memdsl/schema.py 
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
class GapKind(str, Enum):
    """The kind of a first-class absence token.

    Absence is always rendered, never dropped, so a coverage-gated abstention can
    reason about the hole:

    * ``STALE`` — the node's tether drifted since it was pinned.
    * ``UNRESOLVED`` — a referenced address did not resolve to a node.
    * ``MISSING`` — an expected hop/relation is absent from the substrate.
    * ``ELIDED`` — a body was truncated to a lossy view; a ``ground`` re-fetches
      it. Truncation must never silently break a verbatim-quote check, so the
      elision is explicit.
    * ``OUTDATED`` — the node's git pin is a faithfully-cited-but-SUPERSEDED
      commit: the pinned bytes are still a retrievable immutable git object (so
      the node stays GROUNDED — this is a DISCLOSURE, not an abstain-forcing
      taint like ``STALE``), but HEAD has since moved on, so a consumer must be
      told "grounded as of the pinned sha; the current file may differ".
    """

    STALE = "stale"
    UNRESOLVED = "unresolved"
    MISSING = "missing"
    ELIDED = "elided"
    OUTDATED = "outdated"

Address dataclass

A stable, collision-free, short unified address for a substrate node.

Canonical form is store:source:id with an optional trailing {locator} that encodes external-dataset provenance shapes without changing the scheme:

  • a passage char-offset span → {#<start>-<end>};
  • a temporal as-of stamp → {@<stamp>} (e.g. an ISO 8601 instant);
  • both, in that order → {#<start>-<end>@<stamp>}.

A schema table.column provenance needs no locator: the dotted column is the natural id (e.g. sql:salesdb:orders.total). store, source and id must be non-empty and free of the :/{/}/,/whitespace separators; id may contain dots. , is forbidden because address tokens are embedded in ,-delimited lines (cites/prov/aff/ impact); a comma inside a component would silently split one token into two on parse. The session/work stores are reserved (see :data:RESERVED_STORES).

Source code in zettelkasten/synapse/memdsl/schema.py 
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
@dataclass(frozen=True)
class Address:
    """A stable, collision-free, short unified address for a substrate node.

    Canonical form is ``store:source:id`` with an optional trailing ``{locator}``
    that encodes external-dataset provenance shapes without changing the scheme:

    * a passage char-offset span → ``{#<start>-<end>}``;
    * a temporal as-of stamp → ``{@<stamp>}`` (e.g. an ISO 8601 instant);
    * both, in that order → ``{#<start>-<end>@<stamp>}``.

    A schema ``table.column`` provenance needs no locator: the dotted column is
    the natural ``id`` (e.g. ``sql:salesdb:orders.total``). ``store``, ``source``
    and ``id`` must be non-empty and free of the ``:``/``{``/``}``/``,``/whitespace
    separators; ``id`` may contain dots. ``,`` is forbidden because address
    tokens are embedded in ``, ``-delimited lines (``cites``/``prov``/``aff``/
    ``impact``); a comma inside a component would silently split one token into
    two on parse. The ``session``/``work`` stores are reserved (see
    :data:`RESERVED_STORES`).
    """

    store: str
    source: str
    id: str
    # Optional locators for external-dataset provenance shapes. ``None`` on the
    # overwhelming majority of nodes (a plain store node), so the token stays the
    # short ``store:source:id`` form.
    span: tuple[int, int] | None = None  # a passage char-offset [start, end)
    as_of: str | None = None             # a temporal as-of stamp

    def __post_init__(self) -> None:
        # ``,`` joins the ':'/'{'/'}'/whitespace separators here: an address token
        # is embedded verbatim in ``, ``-delimited lines (cites/prov/aff/impact)
        # and whitespace-delimited node/gap headers, so a component carrying any
        # of these would corrupt the surrounding line on parse.
        for name, value in (("store", self.store), ("source", self.source), ("id", self.id)):
            if not value:
                raise MemDSLParseError(f"Address {name!r} must be non-empty")
            if any(c in value for c in (":", "{", "}", ",")) or any(c.isspace() for c in value):
                raise MemDSLParseError(
                    f"Address {name!r}={value!r} may not contain ':', '{{', '}}', ',', or whitespace"
                )
        if self.span is not None:
            start, end = self.span
            if start < 0 or end < start:
                raise MemDSLParseError(f"Address span {self.span!r} must satisfy 0 <= start <= end")
        if self.as_of is not None:
            # ``as_of`` may legitimately contain ':' and '-' (ISO 8601 stamps), but
            # NOT whitespace/newlines (would break whitespace-delimited headers or
            # inject a new physical line), ',' (would split ``, ``-delimited lines),
            # or the '{'/'}' locator braces (would corrupt the address token).
            if any(c in self.as_of for c in ("{", "}", ",")) or any(c.isspace() for c in self.as_of):
                raise MemDSLParseError(
                    "Address as_of may not contain whitespace, ',', '{', or '}'"
                )

    def to_token(self) -> str:
        """Serialize to the canonical ``store:source:id[{locator}]`` string."""
        token = f"{self.store}:{self.source}:{self.id}"
        locator = ""
        if self.span is not None:
            locator += f"#{self.span[0]}-{self.span[1]}"
        if self.as_of is not None:
            locator += f"@{self.as_of}"
        return f"{token}{{{locator}}}" if locator else token

    @classmethod
    def parse(cls, token: str) -> "Address":
        """Parse a canonical address token back into an :class:`Address`.

        Raises :class:`MemDSLParseError` on anything that is not a well-formed
        ``store:source:id[{locator}]`` string.
        """
        token = (token or "").strip()
        if not token:
            raise MemDSLParseError("empty address token")
        locator: str | None = None
        base = token
        if token.endswith("}"):
            open_at = token.find("{")
            if open_at == -1:
                raise MemDSLParseError(f"unbalanced locator braces in address {token!r}")
            base = token[:open_at]
            locator = token[open_at + 1 : -1]
        parts = base.split(":", 2)
        if len(parts) != 3:
            raise MemDSLParseError(f"address {token!r} must have the form store:source:id")
        store, source, node_id = parts
        span: tuple[int, int] | None = None
        as_of: str | None = None
        if locator is not None:
            span, as_of = _parse_locator(locator, token)
        return cls(store=store, source=source, id=node_id, span=span, as_of=as_of)

to_token 

to_token() -> str

Serialize to the canonical store:source:id[{locator}] string.

Source code in zettelkasten/synapse/memdsl/schema.py 
226
227
228
229
230
231
232
233
234
def to_token(self) -> str:
    """Serialize to the canonical ``store:source:id[{locator}]`` string."""
    token = f"{self.store}:{self.source}:{self.id}"
    locator = ""
    if self.span is not None:
        locator += f"#{self.span[0]}-{self.span[1]}"
    if self.as_of is not None:
        locator += f"@{self.as_of}"
    return f"{token}{{{locator}}}" if locator else token

parse classmethod 

parse(token: str) -> 'Address'

Parse a canonical address token back into an :class:Address.

Raises :class:MemDSLParseError on anything that is not a well-formed store:source:id[{locator}] string.

Source code in zettelkasten/synapse/memdsl/schema.py 
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
@classmethod
def parse(cls, token: str) -> "Address":
    """Parse a canonical address token back into an :class:`Address`.

    Raises :class:`MemDSLParseError` on anything that is not a well-formed
    ``store:source:id[{locator}]`` string.
    """
    token = (token or "").strip()
    if not token:
        raise MemDSLParseError("empty address token")
    locator: str | None = None
    base = token
    if token.endswith("}"):
        open_at = token.find("{")
        if open_at == -1:
            raise MemDSLParseError(f"unbalanced locator braces in address {token!r}")
        base = token[:open_at]
        locator = token[open_at + 1 : -1]
    parts = base.split(":", 2)
    if len(parts) != 3:
        raise MemDSLParseError(f"address {token!r} must have the form store:source:id")
    store, source, node_id = parts
    span: tuple[int, int] | None = None
    as_of: str | None = None
    if locator is not None:
        span, as_of = _parse_locator(locator, token)
    return cls(store=store, source=source, id=node_id, span=span, as_of=as_of)

Affordance dataclass

A navigation handle the engine advertises FROM a rendered node.

verb is one of :data:AFFORDANCE_VERBS and target is the address token (or a node ref) the move applies to — e.g. expand the neighborhood of this node, or join it with another. Advisory: the engine still validates any action the agent returns.

Source code in zettelkasten/synapse/memdsl/schema.py 
290
291
292
293
294
295
296
297
298
299
300
301
@dataclass
class Affordance:
    """A navigation handle the engine advertises FROM a rendered node.

    ``verb`` is one of :data:`AFFORDANCE_VERBS` and ``target`` is the address
    token (or a node ref) the move applies to — e.g. ``expand`` the neighborhood
    of this node, or ``join`` it with another. Advisory: the engine still
    validates any action the agent returns.
    """

    verb: str
    target: str

RenderedNode dataclass

One node as rendered to the agent.

Carries a short, stable, envelope-local ref (e.g. n1) the agent cites instead of the full address, the unified address, the node type (from :data:zettelkasten.graph.VALID_TYPES, or an unknown type that degrades to the default body codec), a single-line title, a body (which may be a lossy view — see elided), the engine-emitted status, provenance handles, and the affordance handles available from here.

When elided is True the body is a truncated/lossy view and a ground(ref) re-fetches the full body; a verbatim-quote check must treat an elided body as not-yet-fetched rather than authoritative.

Source code in zettelkasten/synapse/memdsl/schema.py 
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
@dataclass
class RenderedNode:
    """One node as rendered to the agent.

    Carries a short, stable, envelope-local ``ref`` (e.g. ``n1``) the agent cites
    instead of the full address, the unified ``address``, the node ``type`` (from
    :data:`zettelkasten.graph.VALID_TYPES`, or an unknown type that degrades to
    the default body codec), a single-line ``title``, a ``body`` (which may be a
    lossy view — see ``elided``), the engine-emitted ``status``, provenance
    handles, and the affordance handles available from here.

    When ``elided`` is True the ``body`` is a truncated/lossy view and a
    ``ground(ref)`` re-fetches the full body; a verbatim-quote check must treat an
    elided body as not-yet-fetched rather than authoritative.
    """

    ref: str
    address: Address
    type: str
    title: str = ""
    body: str = ""
    status: EpistemicStatus = EpistemicStatus.INFERRED
    provenance: list[str] = field(default_factory=list)
    affordances: list[Affordance] = field(default_factory=list)
    elided: bool = False

GapToken dataclass

A first-class rendered absence (see :class:GapKind).

address is the node/hop the gap concerns when known (e.g. the unresolved reference, or the elided node), else None. detail is an optional single-line human note. Rendered explicitly so calibrated abstention can see the hole.

Source code in zettelkasten/synapse/memdsl/schema.py 
331
332
333
334
335
336
337
338
339
340
341
342
343
@dataclass
class GapToken:
    """A first-class rendered absence (see :class:`GapKind`).

    ``address`` is the node/hop the gap concerns when known (e.g. the unresolved
    reference, or the elided node), else ``None``. ``detail`` is an optional
    single-line human note. Rendered explicitly so calibrated abstention can see
    the hole.
    """

    kind: GapKind
    address: Address | None = None
    detail: str = ""

Envelope dataclass

The render-direction payload: nodes + gaps the engine shows the agent.

Determinism is the caller's responsibility for ordering (nodes are rendered in list order with their assigned refs — see :func:zettelkasten.synapse.memdsl.parser.assign_refs) and the serializer is a pure function of the envelope, so identical input yields byte-identical output. focus optionally names the ref the render is centered on.

Source code in zettelkasten/synapse/memdsl/schema.py 
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
@dataclass
class Envelope:
    """The render-direction payload: nodes + gaps the engine shows the agent.

    Determinism is the caller's responsibility for ordering (nodes are rendered
    in list order with their assigned refs — see
    :func:`zettelkasten.synapse.memdsl.parser.assign_refs`) and the serializer is
    a pure function of the envelope, so identical input yields byte-identical
    output. ``focus`` optionally names the ref the render is centered on.
    """

    nodes: list[RenderedNode] = field(default_factory=list)
    gaps: list[GapToken] = field(default_factory=list)
    focus: str | None = None
    format_version: str = FORMAT_VERSION

Mutation dataclass

A state mutation reported by the engine after a write/apply action.

v1 emits none (the navigation loop is read-only), but the fragment is shaped to carry them so v2 write actions need no grammar change. op names the mutation kind, address the node it touched, detail an optional note.

Source code in zettelkasten/synapse/memdsl/schema.py 
366
367
368
369
370
371
372
373
374
375
376
377
@dataclass
class Mutation:
    """A state mutation reported by the engine after a write/apply action.

    v1 emits none (the navigation loop is read-only), but the fragment is shaped
    to carry them so v2 write actions need no grammar change. ``op`` names the
    mutation kind, ``address`` the node it touched, ``detail`` an optional note.
    """

    op: str
    address: Address
    detail: str = ""

ActionResponse dataclass

The engine's versioned reply to a single agent action, mid-loop.

The navigation loop is render → action → action-response → action, so this fragment is a first-class part of the contract. v1 populates only nodes and gaps (read results); mutations and impact (the set of addresses a mutation touched) are reserved for future write/apply actions and stay empty. status is a short machine token (ok by default).

Source code in zettelkasten/synapse/memdsl/schema.py 
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
@dataclass
class ActionResponse:
    """The engine's versioned reply to a single agent action, mid-loop.

    The navigation loop is render → action → action-response → action, so this
    fragment is a first-class part of the contract. v1 populates only ``nodes``
    and ``gaps`` (read results); ``mutations`` and ``impact`` (the set of
    addresses a mutation touched) are reserved for future write/apply actions and
    stay empty. ``status`` is a short machine token (``ok`` by default).
    """

    status: str = "ok"
    nodes: list[RenderedNode] = field(default_factory=list)
    gaps: list[GapToken] = field(default_factory=list)
    mutations: list[Mutation] = field(default_factory=list)
    impact: list[str] = field(default_factory=list)
    format_version: str = FORMAT_VERSION

RuleClass

Bases: str, Enum

The graph-rewrite class of an action, in the sense of a design grammar.

An action is a production over the substrate view, so it carries the topologic/parametric distinction from grammar-based computational design synthesis (Königseder & Shea): a rule either changes the structure (which nodes/edges exist) or the parameters (a node's content/resolution) of the graph. This is engine-side metadata only — advisory, never serialized — that lets the (deferred) navigation/VOI policy reason about which kind of move it is spending budget on, and gives the reserved v2 write actions a principled axis:

  • TOPOLOGIC — changes the graph's structure. Read: expand/join/ prune change which nodes/edges are in view. Write (v2): assert/ retract add/remove a node, link/unlink add/remove an edge.
  • PARAMETRIC — changes a node's content/parameters without changing topology. Read: ground deepens a node's resolution. Write (v2): revise edits a node body in place.
  • TERMINAL — the whole-turn answer/abstain decisions, which end the loop rather than rewriting the graph.
Source code in zettelkasten/synapse/memdsl/schema.py 
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
class RuleClass(str, Enum):
    """The graph-rewrite class of an action, in the sense of a design grammar.

    An action is a production over the substrate view, so it carries the
    topologic/parametric distinction from grammar-based computational design
    synthesis (Königseder & Shea): a rule either changes the *structure* (which
    nodes/edges exist) or the *parameters* (a node's content/resolution) of the
    graph. This is engine-side metadata only — advisory, never serialized — that
    lets the (deferred) navigation/VOI policy reason about *which kind* of move it
    is spending budget on, and gives the reserved v2 write actions a principled
    axis:

    * ``TOPOLOGIC`` — changes the graph's structure. Read: ``expand``/``join``/
      ``prune`` change which nodes/edges are in view. Write (v2): ``assert``/
      ``retract`` add/remove a node, ``link``/``unlink`` add/remove an edge.
    * ``PARAMETRIC`` — changes a node's content/parameters without changing
      topology. Read: ``ground`` deepens a node's resolution. Write (v2):
      ``revise`` edits a node body in place.
    * ``TERMINAL`` — the whole-turn ``answer``/``abstain`` decisions, which end
      the loop rather than rewriting the graph.
    """

    TOPOLOGIC = "topologic"
    PARAMETRIC = "parametric"
    TERMINAL = "terminal"

ActionSpec dataclass

One entry in the open action registry.

kind is read for every v1 action; write is reserved for future apply actions (the registry is the extension seam — a new action is a new entry, not a grammar change). terminal marks the whole-turn decisions (answer/abstain) that end the navigation loop and are expressed with a @-marker rather than the verb(args) call form. min_args/ max_args bound the positional arity (max_args=None is unbounded). rule_class is the optional graph-rewrite class (see :class:RuleClass): advisory engine-side metadata that never touches the wire, so it is purely additive — an unclassified action (None) round-trips exactly as before.

Source code in zettelkasten/synapse/memdsl/schema.py 
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
@dataclass(frozen=True)
class ActionSpec:
    """One entry in the open action registry.

    ``kind`` is ``read`` for every v1 action; ``write`` is reserved for future
    apply actions (the registry is the extension seam — a new action is a new
    entry, not a grammar change). ``terminal`` marks the whole-turn decisions
    (``answer``/``abstain``) that end the navigation loop and are expressed with a
    ``@``-marker rather than the ``verb(args)`` call form. ``min_args``/
    ``max_args`` bound the positional arity (``max_args=None`` is unbounded).
    ``rule_class`` is the optional graph-rewrite class (see :class:`RuleClass`):
    advisory engine-side metadata that never touches the wire, so it is purely
    additive — an unclassified action (``None``) round-trips exactly as before.
    """

    name: str
    kind: str = "read"
    terminal: bool = False
    min_args: int = 0
    max_args: int | None = None
    rule_class: "RuleClass | None" = None

Action dataclass

A single non-terminal navigation action the agent returned.

Generic verb(args, kwargs) shape so the registry can grow. verb is validated against :data:ACTION_REGISTRY at parse time; args are node refs/addresses, kwargs an open map for future parameters.

Source code in zettelkasten/synapse/memdsl/schema.py 
486
487
488
489
490
491
492
493
494
495
496
497
@dataclass
class Action:
    """A single non-terminal navigation action the agent returned.

    Generic ``verb(args, kwargs)`` shape so the registry can grow. ``verb`` is
    validated against :data:`ACTION_REGISTRY` at parse time; ``args`` are node
    refs/addresses, ``kwargs`` an open map for future parameters.
    """

    verb: str
    args: list[str] = field(default_factory=list)
    kwargs: dict[str, str] = field(default_factory=dict)

Claim dataclass

One node of the agent's cited reasoning-DAG.

cites are the node refs (or addresses) the claim rests on; form is the :class:InferenceForm connecting them to the claim; premises are other claim ids this one builds on (making the reasoning a DAG, not a flat list); derivation is an optional derivation-expression (e.g. the arithmetic a CALCULATION claim computed). There is deliberately no epistemic-status field: the engine RE-DERIVES the claim's status from its cited nodes and form, so the agent cannot assert grounded.

Source code in zettelkasten/synapse/memdsl/schema.py 
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
@dataclass
class Claim:
    """One node of the agent's cited reasoning-DAG.

    ``cites`` are the node refs (or addresses) the claim rests on; ``form`` is the
    :class:`InferenceForm` connecting them to the claim; ``premises`` are other
    claim ids this one builds on (making the reasoning a DAG, not a flat list);
    ``derivation`` is an optional derivation-expression (e.g. the arithmetic a
    ``CALCULATION`` claim computed). There is deliberately no epistemic-status
    field: the engine RE-DERIVES the claim's status from its cited nodes and
    form, so the agent cannot assert ``grounded``.
    """

    id: str
    text: str
    form: InferenceForm
    cites: list[str] = field(default_factory=list)
    premises: list[str] = field(default_factory=list)
    derivation: str | None = None

ProseCitation dataclass

A binding from one prose assertion to the claim that licenses it.

MemDSL OUTPUT v2 encodes this binding as an exact quote anchor. The strict parser resolves that quote to one half-open span [start, end) in :attr:ReasoningDAG.prose; zero or multiple matches fail closed. In-memory callers may still construct this type directly for compatibility; validated OUTPUT v2 prose requires exactly one claim id per binding.

The gate enforces per-assertion CITATION-ANCHORING against this binding: the assertion's content tokens must be licensed by a SINGLE cited verified claim (closed vocabulary per claim, never the pooled union), and any prose token outside every citation span is an UNCITED assertion. It is purely additive — ReasoningDAG.prose_citations defaults to empty, so a legacy v1 DAG leaves the gate on its conservative fallback path.

Source code in zettelkasten/synapse/memdsl/schema.py 
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
@dataclass(frozen=True)
class ProseCitation:
    """A binding from one prose assertion to the claim that licenses it.

    MemDSL OUTPUT v2 encodes this binding as an exact quote anchor. The strict
    parser resolves that quote to one half-open ``span`` ``[start, end)`` in
    :attr:`ReasoningDAG.prose`; zero or multiple matches fail closed. In-memory
    callers may still construct this type directly for compatibility; validated
    OUTPUT v2 prose requires exactly one claim id per binding.

    The gate enforces per-assertion CITATION-ANCHORING against this binding: the
    assertion's content tokens must be licensed by a SINGLE cited verified claim
    (closed vocabulary per claim, never the pooled union), and any prose token
    outside every citation span is an UNCITED assertion. It is purely additive —
    ``ReasoningDAG.prose_citations`` defaults to empty, so a legacy v1 DAG leaves
    the gate on its conservative fallback path.
    """

    span: tuple[int, int]
    claim_ids: tuple[str, ...] = ()

    def __post_init__(self) -> None:
        start, end = self.span
        if start < 0 or end < start:
            raise MemDSLParseError(
                f"ProseCitation span {self.span!r} must satisfy 0 <= start <= end"
            )

ReasoningDAG dataclass

The cited reasoning-DAG returned with an answer.

claims are the DAG nodes; conclusion names the claim id that IS the answer (defaults to the last claim when empty). This is what makes "don't fabricate" enforceable: every claim is traceable to cited substrate nodes and an inference form the engine can check.

prose is the answer text licensed for public projection. OUTPUT v2 serializes it with exact quote-anchored prose_citations; OUTPUT v1 omits both fields and remains accepted byte-for-byte. Empty defaults preserve construction compatibility for existing v1 and direct router callers.

The empty-conclusion default is resolved to the last claim id in :meth:__post_init__, so the in-memory form is canonical: an omitted and a last-claim-named conclusion are the same object. That canonicalization is what lets the serializer always emit a conclude line and still satisfy parse(serialize(x)) == x (the round-trip-symmetry guarantee).

Source code in zettelkasten/synapse/memdsl/schema.py 
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
@dataclass
class ReasoningDAG:
    """The cited reasoning-DAG returned with an ``answer``.

    ``claims`` are the DAG nodes; ``conclusion`` names the claim id that IS the
    answer (defaults to the last claim when empty). This is what makes
    "don't fabricate" enforceable: every claim is traceable to cited substrate
    nodes and an inference form the engine can check.

    ``prose`` is the answer text licensed for public projection. OUTPUT v2
    serializes it with exact quote-anchored ``prose_citations``; OUTPUT v1 omits
    both fields and remains accepted byte-for-byte. Empty defaults preserve
    construction compatibility for existing v1 and direct router callers.

    The empty-conclusion default is resolved to the last claim id in
    :meth:`__post_init__`, so the in-memory form is canonical: an omitted and a
    last-claim-named conclusion are the same object. That canonicalization is
    what lets the serializer always emit a ``conclude`` line and still satisfy
    ``parse(serialize(x)) == x`` (the round-trip-symmetry guarantee).
    """

    claims: list[Claim] = field(default_factory=list)
    conclusion: str = ""
    prose: str = ""
    prose_citations: list[ProseCitation] = field(default_factory=list)

    def __post_init__(self) -> None:
        # Canonicalize an omitted conclusion to the last claim id so there is a
        # single in-memory representation of "the answer is the final claim".
        if not self.conclusion and self.claims:
            self.conclusion = self.claims[-1].id

    def validate(self) -> None:
        """Structurally verify the reasoning-DAG (raises :class:`MemDSLParseError`).

        Enforces the epistemic-honesty guarantees the engine relies on, so a
        fabricated or malformed DAG is rejected at parse rather than trusted:

        * **Citation floor** — every non-``assumption`` claim carries at least one
          citation. An ``assumption`` is the only form allowed to cite nothing;
          any grounding-bearing form (deduction/restatement/calculation/…) must
          rest on cited substrate, so an uncited deduction can no longer be the
          whole answer.
        * **Premise integrity** — every ``premises`` reference resolves to a
          defined claim, claim ids are unique, and the premise edges form no
          cycle (the reasoning is a DAG, not a tangle).
        * **Non-empty answer** — a zero-claim ``@answer`` is rejected: an answer
          with no claims has no ground, so it can never be a valid answer (the
          claim-less path is ``@abstain``, which never builds a DAG).
        * **Grounded conclusion** — the conclusion names a defined claim and its
          transitive premise closure bottoms out in at least one cited substrate
          reference, so an answer can never be assembled purely from uncited
          assumptions.

        Direct citation *existence* (does ``n3`` resolve to a rendered node?) is
        deliberately NOT checked here: cites reference substrate the DAG alone
        cannot see, so the grounding gate verifies them against the envelope.
        """
        by_id: dict[str, Claim] = {}
        for claim in self.claims:
            if claim.id in by_id:
                raise MemDSLParseError(f"duplicate claim id {claim.id!r} in reasoning-DAG")
            by_id[claim.id] = claim

        # Citation floor + premise-existence.
        for claim in self.claims:
            if claim.form is not InferenceForm.ASSUMPTION and not claim.cites:
                raise MemDSLParseError(
                    f"claim {claim.id!r} of form {claim.form.value!r} must cite at least one "
                    f"substrate ref (only an 'assumption' may be uncited)"
                )
            for premise in claim.premises:
                if premise not in by_id:
                    raise MemDSLParseError(
                        f"claim {claim.id!r} premise {premise!r} does not resolve to a claim"
                    )

        # Acyclicity: three-colour DFS over the premise edges.
        _WHITE, _GRAY, _BLACK = 0, 1, 2
        colour = {cid: _WHITE for cid in by_id}

        def _visit(cid: str) -> None:
            colour[cid] = _GRAY
            for premise in by_id[cid].premises:
                if colour[premise] == _GRAY:
                    raise MemDSLParseError(
                        f"cycle in reasoning-DAG premises through claim {cid!r}"
                    )
                if colour[premise] == _WHITE:
                    _visit(premise)
            colour[cid] = _BLACK

        for cid in by_id:
            if colour[cid] == _WHITE:
                _visit(cid)

        # A zero-claim ``@answer`` has no ground at all, so it cannot be a valid
        # answer: an answer must carry >=1 grounded claim bottoming out in a
        # citation. (An abstain path never builds a DAG, so ``@abstain`` with no
        # claims stays legal — this only rejects an empty ``@answer``.)
        if not self.claims:
            raise MemDSLParseError(
                "an @answer must carry at least one grounded claim (a zero-claim "
                "answer has no ground); use @abstain to decline"
            )
        # Grounded conclusion: it must name a claim and its premise closure must
        # contain at least one real citation.
        conclusion = self.conclusion or self.claims[-1].id
        if conclusion not in by_id:
            raise MemDSLParseError(f"conclusion {conclusion!r} does not name a claim")
        closure: set[str] = set()
        stack = [conclusion]
        while stack:
            cid = stack.pop()
            if cid in closure:
                continue
            closure.add(cid)
            stack.extend(by_id[cid].premises)
        if not any(by_id[cid].cites for cid in closure):
            raise MemDSLParseError(
                f"conclusion {conclusion!r} and its premise closure cite no substrate ref"
            )

        # OUTPUT v2 prose bindings are intentionally stricter than the router's
        # semantic gate: every proposition-bearing character must lie inside one
        # non-overlapping exact-quote span, and each span must point to exactly
        # one claim in the conclusion closure. This prevents citation splicing,
        # pooled licensing, and disconnected claims from laundering prose.
        if self.prose:
            if not self.prose_citations:
                raise MemDSLParseError("OUTPUT v2 prose requires at least one cite binding")
            covered = [False] * len(self.prose)
            for citation in sorted(self.prose_citations, key=lambda item: item.span):
                start, end = citation.span
                if start == end or end > len(self.prose):
                    raise MemDSLParseError(
                        f"ProseCitation span {citation.span!r} is outside the prose"
                    )
                if len(citation.claim_ids) != 1:
                    raise MemDSLParseError(
                        "each OUTPUT v2 prose assertion must cite exactly one claim"
                    )
                claim_id = citation.claim_ids[0]
                if claim_id not in closure:
                    raise MemDSLParseError(
                        f"prose citation claim {claim_id!r} is outside the conclusion closure"
                    )
                if any(covered[start:end]):
                    raise MemDSLParseError("prose citation spans must not overlap")
                covered[start:end] = [True] * (end - start)
            if any(ch.isalnum() and not covered[index] for index, ch in enumerate(self.prose)):
                raise MemDSLParseError(
                    "OUTPUT v2 prose contains an assertion not covered by an exact cite binding"
                )

validate 

validate() -> None

Structurally verify the reasoning-DAG (raises :class:MemDSLParseError).

Enforces the epistemic-honesty guarantees the engine relies on, so a fabricated or malformed DAG is rejected at parse rather than trusted:

  • Citation floor — every non-assumption claim carries at least one citation. An assumption is the only form allowed to cite nothing; any grounding-bearing form (deduction/restatement/calculation/…) must rest on cited substrate, so an uncited deduction can no longer be the whole answer.
  • Premise integrity — every premises reference resolves to a defined claim, claim ids are unique, and the premise edges form no cycle (the reasoning is a DAG, not a tangle).
  • Non-empty answer — a zero-claim @answer is rejected: an answer with no claims has no ground, so it can never be a valid answer (the claim-less path is @abstain, which never builds a DAG).
  • Grounded conclusion — the conclusion names a defined claim and its transitive premise closure bottoms out in at least one cited substrate reference, so an answer can never be assembled purely from uncited assumptions.

Direct citation existence (does n3 resolve to a rendered node?) is deliberately NOT checked here: cites reference substrate the DAG alone cannot see, so the grounding gate verifies them against the envelope.

Source code in zettelkasten/synapse/memdsl/schema.py 
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
def validate(self) -> None:
    """Structurally verify the reasoning-DAG (raises :class:`MemDSLParseError`).

    Enforces the epistemic-honesty guarantees the engine relies on, so a
    fabricated or malformed DAG is rejected at parse rather than trusted:

    * **Citation floor** — every non-``assumption`` claim carries at least one
      citation. An ``assumption`` is the only form allowed to cite nothing;
      any grounding-bearing form (deduction/restatement/calculation/…) must
      rest on cited substrate, so an uncited deduction can no longer be the
      whole answer.
    * **Premise integrity** — every ``premises`` reference resolves to a
      defined claim, claim ids are unique, and the premise edges form no
      cycle (the reasoning is a DAG, not a tangle).
    * **Non-empty answer** — a zero-claim ``@answer`` is rejected: an answer
      with no claims has no ground, so it can never be a valid answer (the
      claim-less path is ``@abstain``, which never builds a DAG).
    * **Grounded conclusion** — the conclusion names a defined claim and its
      transitive premise closure bottoms out in at least one cited substrate
      reference, so an answer can never be assembled purely from uncited
      assumptions.

    Direct citation *existence* (does ``n3`` resolve to a rendered node?) is
    deliberately NOT checked here: cites reference substrate the DAG alone
    cannot see, so the grounding gate verifies them against the envelope.
    """
    by_id: dict[str, Claim] = {}
    for claim in self.claims:
        if claim.id in by_id:
            raise MemDSLParseError(f"duplicate claim id {claim.id!r} in reasoning-DAG")
        by_id[claim.id] = claim

    # Citation floor + premise-existence.
    for claim in self.claims:
        if claim.form is not InferenceForm.ASSUMPTION and not claim.cites:
            raise MemDSLParseError(
                f"claim {claim.id!r} of form {claim.form.value!r} must cite at least one "
                f"substrate ref (only an 'assumption' may be uncited)"
            )
        for premise in claim.premises:
            if premise not in by_id:
                raise MemDSLParseError(
                    f"claim {claim.id!r} premise {premise!r} does not resolve to a claim"
                )

    # Acyclicity: three-colour DFS over the premise edges.
    _WHITE, _GRAY, _BLACK = 0, 1, 2
    colour = {cid: _WHITE for cid in by_id}

    def _visit(cid: str) -> None:
        colour[cid] = _GRAY
        for premise in by_id[cid].premises:
            if colour[premise] == _GRAY:
                raise MemDSLParseError(
                    f"cycle in reasoning-DAG premises through claim {cid!r}"
                )
            if colour[premise] == _WHITE:
                _visit(premise)
        colour[cid] = _BLACK

    for cid in by_id:
        if colour[cid] == _WHITE:
            _visit(cid)

    # A zero-claim ``@answer`` has no ground at all, so it cannot be a valid
    # answer: an answer must carry >=1 grounded claim bottoming out in a
    # citation. (An abstain path never builds a DAG, so ``@abstain`` with no
    # claims stays legal — this only rejects an empty ``@answer``.)
    if not self.claims:
        raise MemDSLParseError(
            "an @answer must carry at least one grounded claim (a zero-claim "
            "answer has no ground); use @abstain to decline"
        )
    # Grounded conclusion: it must name a claim and its premise closure must
    # contain at least one real citation.
    conclusion = self.conclusion or self.claims[-1].id
    if conclusion not in by_id:
        raise MemDSLParseError(f"conclusion {conclusion!r} does not name a claim")
    closure: set[str] = set()
    stack = [conclusion]
    while stack:
        cid = stack.pop()
        if cid in closure:
            continue
        closure.add(cid)
        stack.extend(by_id[cid].premises)
    if not any(by_id[cid].cites for cid in closure):
        raise MemDSLParseError(
            f"conclusion {conclusion!r} and its premise closure cite no substrate ref"
        )

    # OUTPUT v2 prose bindings are intentionally stricter than the router's
    # semantic gate: every proposition-bearing character must lie inside one
    # non-overlapping exact-quote span, and each span must point to exactly
    # one claim in the conclusion closure. This prevents citation splicing,
    # pooled licensing, and disconnected claims from laundering prose.
    if self.prose:
        if not self.prose_citations:
            raise MemDSLParseError("OUTPUT v2 prose requires at least one cite binding")
        covered = [False] * len(self.prose)
        for citation in sorted(self.prose_citations, key=lambda item: item.span):
            start, end = citation.span
            if start == end or end > len(self.prose):
                raise MemDSLParseError(
                    f"ProseCitation span {citation.span!r} is outside the prose"
                )
            if len(citation.claim_ids) != 1:
                raise MemDSLParseError(
                    "each OUTPUT v2 prose assertion must cite exactly one claim"
                )
            claim_id = citation.claim_ids[0]
            if claim_id not in closure:
                raise MemDSLParseError(
                    f"prose citation claim {claim_id!r} is outside the conclusion closure"
                )
            if any(covered[start:end]):
                raise MemDSLParseError("prose citation spans must not overlap")
            covered[start:end] = [True] * (end - start)
        if any(ch.isalnum() and not covered[index] for index, ch in enumerate(self.prose)):
            raise MemDSLParseError(
                "OUTPUT v2 prose contains an assertion not covered by an exact cite binding"
            )

Abstention dataclass

A labeled, calibrated refusal to answer.

reason is a short label (see :data:ABSTAIN_REASONS for the canonical v1 set — the field stays open so the router may add labels); detail is an optional single-line note.

Source code in zettelkasten/synapse/memdsl/schema.py 
706
707
708
709
710
711
712
713
714
715
716
@dataclass
class Abstention:
    """A labeled, calibrated refusal to answer.

    ``reason`` is a short label (see :data:`ABSTAIN_REASONS` for the canonical v1
    set — the field stays open so the router may add labels); ``detail`` is an
    optional single-line note.
    """

    reason: str
    detail: str = ""

AgentOutput dataclass

The output-direction payload: the actions + terminal decision an agent returned.

actions are the non-terminal navigation moves. Exactly one terminal decision may accompany them: reasoning (an answer with its cited DAG) XOR abstain (a labeled refusal). Both being set is a contract violation the parser rejects.

Source code in zettelkasten/synapse/memdsl/schema.py 
719
720
721
722
723
724
725
726
727
728
729
730
731
732
@dataclass
class AgentOutput:
    """The output-direction payload: the actions + terminal decision an agent returned.

    ``actions`` are the non-terminal navigation moves. Exactly one terminal
    decision may accompany them: ``reasoning`` (an ``answer`` with its cited DAG)
    XOR ``abstain`` (a labeled refusal). Both being set is a contract violation
    the parser rejects.
    """

    actions: list[Action] = field(default_factory=list)
    reasoning: ReasoningDAG | None = None
    abstain: Abstention | None = None
    format_version: str = LEGACY_OUTPUT_FORMAT_VERSION

NodeTypeSpec dataclass

How a node type's compact body is encoded on the wire.

body_kind selects a codec in :data:BODY_CODECS. v1 ships a single text codec (the body is plain, injection-framed text), but the registry is the seam for richer per-type bodies (e.g. a schema descriptor for a data node) without re-cutting the parser. An UNKNOWN type resolves to the default text spec via :func:node_type_spec, so a brand-new node type degrades gracefully instead of crashing.

Source code in zettelkasten/synapse/memdsl/schema.py 
738
739
740
741
742
743
744
745
746
747
748
749
750
751
@dataclass(frozen=True)
class NodeTypeSpec:
    """How a node type's compact body is encoded on the wire.

    ``body_kind`` selects a codec in :data:`BODY_CODECS`. v1 ships a single
    ``text`` codec (the body is plain, injection-framed text), but the registry
    is the seam for richer per-type bodies (e.g. a schema descriptor for a data
    node) without re-cutting the parser. An UNKNOWN type resolves to the default
    text spec via :func:`node_type_spec`, so a brand-new node type degrades
    gracefully instead of crashing.
    """

    type: str
    body_kind: str = "text"

register_action 

register_action(spec: ActionSpec) -> None

Register (or override) an action type in the open registry.

Source code in zettelkasten/synapse/memdsl/schema.py 
459
460
461
def register_action(spec: ActionSpec) -> None:
    """Register (or override) an action type in the open registry."""
    ACTION_REGISTRY[spec.name] = spec

get_action_spec 

get_action_spec(name: str) -> ActionSpec | None

Return the :class:ActionSpec for name, or None if unregistered.

Source code in zettelkasten/synapse/memdsl/schema.py 
464
465
466
def get_action_spec(name: str) -> ActionSpec | None:
    """Return the :class:`ActionSpec` for ``name``, or ``None`` if unregistered."""
    return ACTION_REGISTRY.get(name)

register_node_type 

register_node_type(spec: NodeTypeSpec) -> None

Register (or override) a node type's body spec.

Source code in zettelkasten/synapse/memdsl/schema.py 
757
758
759
def register_node_type(spec: NodeTypeSpec) -> None:
    """Register (or override) a node type's body spec."""
    NODE_TYPE_REGISTRY[spec.type] = spec

node_type_spec 

node_type_spec(node_type: str) -> NodeTypeSpec

Return the :class:NodeTypeSpec for node_type.

Falls back to a default text spec for any unregistered/new type, which is what lets an unknown node type round-trip rather than crash the parser.

Source code in zettelkasten/synapse/memdsl/schema.py 
762
763
764
765
766
767
768
def node_type_spec(node_type: str) -> NodeTypeSpec:
    """Return the :class:`NodeTypeSpec` for ``node_type``.

    Falls back to a default ``text`` spec for any unregistered/new type, which is
    what lets an unknown node type round-trip rather than crash the parser.
    """
    return NODE_TYPE_REGISTRY.get(node_type) or NodeTypeSpec(type=node_type, body_kind="text")

body_codec 

body_codec(body_kind: str) -> BodyCodec

Return the (encode, decode) codec for body_kind, defaulting to text.

Source code in zettelkasten/synapse/memdsl/schema.py 
789
790
791
def body_codec(body_kind: str) -> BodyCodec:
    """Return the (encode, decode) codec for ``body_kind``, defaulting to ``text``."""
    return BODY_CODECS.get(body_kind) or BODY_CODECS["text"]