Crate sim_codec 

Core decoder/encoder and output-position contracts for the SIM codec layer.

sim-codec is the foundation crate of the sim-codec-* family. The SIM kernel defines the Expr graph and the codec contract types; this crate provides the concrete runtime that every other codec crate implements against: the Decoder/Encoder traits, their located and tree-shaped variants, the DecodePosition/DecodeTarget output-position model (eval, quote, data, pattern), and the CodecRuntime glue that registers a codec as a runtime object. On top of those contracts it carries the shared Expr<->tree encode machinery, domain-codec scaffolding, decode resource limits, portable encode/decode, string-literal coding, and tree validation.

A decoder turns tokens or text into a checked Expr form; an encoder knows its output position and renders an Expr back to text or bytes. Downstream crates (general-purpose and domain codecs) build on these primitives rather than re-implementing them.

Module map (these modules are private; their public items are re-exported at the crate root, so they are listed here in plain text rather than linked):

• implementation: implementation root that aggregates the submodules below and re-exports their public surface.
  • runtime: the Decoder/Encoder runtime contracts, the DecodePosition/DecodeTarget output positions, Input/Output, and the CodecRuntime registration glue.
  • domain: builder scaffolding for domain codec libs (DomainCodecLib) and the shared UTF-8 input helper.
  • domain_form: a generic #(...) domain-form parser and formatter.
  • limits: decode resource ceilings (DecodeLimits), running budgets (DecodeBudget), and the ReadCx decode context.
  • list_encode: the shared list/Expr value-to-expr encode machinery.
  • portable: codec-neutral, lossless portable encode/decode for the data subset of Expr.
  • strings: string-literal encode/decode helpers.
  • tree: structural validation of a LocatedExprTree.
• runtime_api: the eval-facing surface that drives codecs through the kernel (DecodedForm, codec lookup, and decode/encode entry points).

Structs

CodecRuntime

A registered codec as a runtime object: a symbol-named bundle of optional decode/encode capabilities plus the Shapes and default-decode policy it exposes.

DecodeBudget

Running counters for a single decode. Construct one per decode call.

DecodeLimits

Resource ceiling shared by every codec decode path.

DomainCodecLib

A host-registered lib that exports one codec (and optionally the Shapes it uses) built from a decoder and encoder.

DomainForm

A parsed #(name ...) form: a name, keyed fields, and positional values.

LossReport

Loss report for one parse/encode/reparse cycle.

PrismDiagnostic

A parse diagnostic surfaced by the Prism.

PrismEncode

Encode result for one codec surface.

PrismInspection

Metadata describing how input was inspected.

PrismParse

Parse result for one codec surface.

PrismSpan

A half-open byte span belonging to a parsed surface.

ReadCx

The decode context threaded through every Decoder: the kernel context plus the active codec id, read policy, and resource limits.

RoundTrip

Full round-trip proof for one codec surface.

RuntimeCodecPrism

Runtime-backed CodecPrism for an installed codec symbol.

SemanticId

Stable identity for a semantic expression.

Enums

BinaryCarrier

How binary frame bytes are carried at the codec boundary.

CodecDefaultDecode

A codec’s policy for choosing a DecodeTarget from a DecodePosition.

DecodePosition

The syntactic position a decode is targeting, mirroring the kernel’s EncodePosition.

DecodeTarget

The checked form a decode resolves to once a position is known: inert data or an evaluable term.

DecodedForm

The position-resolved result of a default decode: inert data or an evaluable term.

DiagnosticSeverity

Diagnostic severity.

DomainFormError

A domain-form parse or access error.

DomainValue

A parsed domain-form value.

Input

Raw input handed to a Decoder: source text or source bytes.

Output

Rendered output produced by an Encoder: text or bytes.

PrismInputKind

What kind of input the Prism inspected.

PrismOutput

Output from a Prism encode pass.

PrismSurface

The class of codec surface a Prism is driving.

Traits

CodecPrism

A codec-aware editor contract for one codec surface.

Decoder

The core decode contract: turn Input into a checked kernel Expr.

Encoder

The core encode contract: render a kernel Expr to Output.

LocatedDecoder

A decoder that preserves source Origin, producing a LocatedExpr.

LocatedEncoder

An encoder that consumes a LocatedExpr, able to use source origin for a higher-fidelity rendering than the plain Encoder.

TreeDecoder

A decoder that preserves the full source tree as a LocatedExprTree, including trivia, for lossless round-tripping.

TreeEncoder

An encoder that consumes a full LocatedExprTree, able to reproduce trivia and exact layout for lossless round-trips.

Functions

codec_value

Wrap a CodecRuntime as an opaque runtime Value for registry storage.

decode_datum_with_codec

Decode input to a Datum with the codec named symbol, using default DecodeLimits.

decode_datum_with_codec_and_limits

Decode input to a Datum under explicit DecodeLimits, failing if the decoded Expr is not inert data.

decode_default_with_codec

Decode input and resolve it to data or a term per the codec’s policy and the requested position, using default DecodeLimits.

decode_default_with_codec_and_limits

Position-aware decode under explicit DecodeLimits; see decode_default_with_codec.

decode_located_with_codec

Decode input preserving source origin, attributing spans to source_id, using default DecodeLimits.

decode_located_with_codec_and_limits

Origin-preserving decode under explicit DecodeLimits; see decode_located_with_codec.

decode_portable

Parse codec-neutral portable text back into an Expr, failing closed on any malformed input rather than panicking.

decode_string_literal

Parse a double-quoted, escaped string literal back to its value.

decode_term_with_codec

Decode input to an evaluable Term with the codec named symbol, using default DecodeLimits.

decode_term_with_codec_and_limits

Decode input to a Term under explicit DecodeLimits, lowering the decoded Expr to a term per the codec’s CodecDefaultDecode policy.

decode_tree_with_codec

Decode input into a full LocatedExprTree (trivia and layout retained), attributing spans to source_id, using default DecodeLimits.

decode_tree_with_codec_and_limits

Full-tree decode under explicit DecodeLimits; see decode_tree_with_codec.

decode_with_codec

Decode input with the codec named symbol, using default DecodeLimits.

decode_with_codec_and_limits

Decode input with the codec named symbol under explicit DecodeLimits.

domain_input_text

Read a codec Input as UTF-8 text, tagging any error with codec. The shared body of every domain codec’s input_text helper.

encode_datum_with_codec

Encode a Datum with the codec named symbol, lifting it to an Expr first.

encode_located_with_codec

Encode a LocatedExpr with the codec named symbol, using its origin for fidelity when options request lossless-origin output.

encode_portable

Serialize a data-subset Expr into the codec-neutral portable text form.

encode_string_literal

Render value as a double-quoted, backslash-escaped string literal.

encode_term_with_codec

Encode a Term with the codec named symbol, lifting it to an Expr first.

encode_tree_with_codec

Encode a LocatedExprTree with the codec named symbol, reproducing layout and trivia when options request lossless-origin output.

encode_value_expr

Walk a runtime Value into a kernel Expr ready for encoding.

encode_value_with_codec

Encode a runtime Value with the codec named symbol, forcing lists and tables into an Expr via encode_value_expr before encoding.

encode_with_codec

Encode expr with the codec named symbol under options.

force_list_for_encode

Force a list value into a bounded Vec for v1 encoding.

format_domain_form

Render a domain form as an ASCII #(...) string. Round-trips through parse_domain_form.

parse_domain_form

Parse a top-level #(...) domain form.

resolve_expr_shape

Resolve a general codec’s expression shape: the primary symbol, then core/Expr, then core/Any, then nil. This is the shared fallback chain that every general-purpose codec (json/binary/binary-base64/algol/lisp/doc) hand-rolled identically before OVERLAP6.07.

resolve_options_shape

Resolve a general codec’s encode-options shape: core/EncodeOptions, then core/Any, then nil. The shared fallback chain those codecs hand-rolled.

validate_expr_tree

Check that a LocatedExprTree is structurally consistent with its Expr.