Recording values

LedgeRecording

public init(
    input: (any Encodable & Sendable)? = nil,
    promptTemplate: (any Encodable & Sendable)? = nil,
    outputReferences: [String: any Encodable & Sendable]? = nil
)

Per-call context accepted by respond and withSession. Input/template encoding happens at the recording boundary, before model execution. Encoding failures emit captureFailed and retain an explicit error marker. Later requests do not inherit previous annotations.

JSON and references

LedgeJSONValue is Codable, Equatable, and Sendable, with cases null, bool(Bool), integer(Int64), unsignedInteger(UInt64), number(Double), string(String), array([LedgeJSONValue]), and object([String: LedgeJSONValue]). Optional nil means absent; .null captures a JSON null.

Output references accept strings or your own Encodable & Sendable objects. They must encode as strings or JSON objects; nested fields can contain any JSON value. Invalid values produce captureFailed diagnostics and explicit capture error objects. IDs must contain 1–256 UTF-16 code units; invalid IDs are omitted with a diagnostic. References enrich display while preserving native output.

Status and errors

LedgeStatus has running, success, failure, cancelled, and interrupted. Custom providers complete spans with a terminal status; .running does not complete a span. The HTTP API accepts finalized records only.

LedgeError(error) captures an error's type, domain, code, and message. LedgeDiagnostic and delivery summaries report telemetry problems separately.

Producer metadata

LedgeProducer.capture(serviceName:) captures serviceName, sdkVersion, app version/build, and OS name/version/build. It is Codable, Equatable, and Sendable. Its evaluationInfo supplies producer metadata when creating a native evaluation.

Envelope and transcript serialization types are internal. Custom transports receive encoded bytes; custom HTTP producers follow the trace envelope.