Trace and span APIs

Scoped and manual traces

public func withTrace<Result>(
    _ name: String, version: Int = 1,
    input: (any Encodable & Sendable)? = nil,
    operation: (LedgeTrace) async throws -> Result
) async throws -> Result

public func startTrace(
    _ name: String, version: Int = 1,
    input: (any Encodable & Sendable)? = nil
) async throws -> LedgeTrace

withTrace finishes, fails, or cancels automatically and preserves the closure's original return value or thrown error. It supports caller-isolated operations. startTrace validates setup and returns a nonoptional actor with public id: UUID.

LedgeTrace.session(model:tools:instructions:agent:) creates a native adapter. Manual owners call finish(), fail(error), or cancel(), all async and nonthrowing. Repeated finalization is a no-op. Finishing early marks unfinished spans interrupted; empty traces are not uploaded. See workflow examples.

Session-owned spans

Create model sessions through client.session(...) or trace.session(...). LedgeKit captures the prepared request before execution and the generated response from the native session. Span creation and completion are internal. There is no public API for manually supplying modelInput, modelOutput, or providerCapture.

Retries, tool continuations, and fallbacks create separate recorded attempts. Completed inputs and outputs are immutable. App arguments, prompt templates, and output references are supplied through LedgeRecording before execution.