Documentation / Core concepts / Results

Results, evidence, cost, and failure

One CallResult answers: what VAANI can prove happened during this call attempt. Unknown provider facts stay unknown; the runtime does not manufacture precision.

Main evidence groups

Group	What it records
outcome, ending, lifecycle_history	terminal classification and progression
transcript	committed/interrupted participant and agent text under capture policy
provider_history	route, provider, model/voice, revision, attempt, disposition
language_history, update_history	configuration changes and decisions
tool_activity	normalized tool execution and external-completion status
timings	monotonic events and measurements
usage, cost	observed quantities, estimated and provider-reported money
failure	primary/secondary normalized errors
telephony	immutable identity plus transfer and recording evidence
judge	optional bounded evaluation that cannot change the base outcome
provenance	schema, runtime, adapters, presets, price book, fingerprint

Known, unknown, not applicable

ObservedText and ObservedDecimal distinguish three states:

• KNOWN: VAANI has an attributable value;
• UNKNOWN: the fact applies but reliable evidence is unavailable;
• NOT_APPLICABLE: the fact does not apply, with a reason.

This distinction flows into usage and cost completeness. A missing provider counter is not silently treated as zero.

Cost is evidence, not billing

The consumer supplies a revisioned PriceBook. VAANI can estimate known usage against those rates and retain separately observed provider costs. COMPLETE, PARTIAL, and UNAVAILABLE describe the evidence—not whether an invoice is correct.

Canonical bytes and digest

body = result.canonical_bytes()
digest = result.result_digest()

The bytes are deterministic call-result.v1 JSON and the digest is full SHA-256 over those exact bytes. Use both to build an append-only ResultPublicationRecord; do not serialize a separate mutable dictionary and call it the canonical result.

Failure model

• A setup problem before call ownership raises InvalidCallSetup and returns no result.
• A failed call after ownership still closes with one result and normalized FailureRecord.
• VoiceRuntimeError carries category, stable code, operation, phase, retry guidance, remediations, and selected action.
• Provider diagnostics are normalized and redacted; raw provider exceptions, payloads, and secrets do not enter the public record.
• Publisher failure happens after Closure and produces a DeliveryReport, not a mutated CallResult.

Next: result/error reference or PostgreSQL publication.