The Helper API is the application-facing surface for participating in the SADAR audit fabric. Application code — agents, tools, and orchestrator-adjacent components — calls Helper API methods at appropriate points during invocation processing; the Helper API translates those calls into validated, phase-aware writes to thein-flight Telemetry Record.
This document covers the six methods exposed to application code, the boundary between SAI-internal and application-facing fields, how phase-immutability is enforced through the API and the structural guarantees that result. The exact method signatures,request/response envelopes, and authorization requirements live in the 7. searchAndInvoke companion document, Helper API surface section. This page is the orientation and the architectural framing.
Audience: implementers writing application code that participates in SADAR-conformant invocation flows; architects scoping integration patterns for SADAR adoption; and audit-tooling teams reasoning about what guarantees the resulting Telemetry Records carry.
The Helper API is a structured interface between application code and the SADAR audit infrastructure. It is provided by searchAndInvoke (SAI), the invocation orchestrator that drives the four-phase Telemetry Record lifecycle. Each invocation receives a Helper API handle (or context); calls on that handle target the corresponding in-flight Telemetry Record.
The API exists as an intermediation layer rather than a direct field-write surface for several reasons:
• Schema enforcement. Writes are validated against the Telemetry Record schema; malformed writes are rejected at the API boundary, not at audit-time during a forensic investigation.
• Phase enforcement. Writes against sealed sections are rejected. Phase ordering is enforced. The application cannot accidentally (or intentionally) violate phase-immutability.
• Authorization. Only entitled application code may call specific methods. Authorization is checked centrally at the API boundary.
• Schema evolution. The application-facing API can remain stable while the underlying record schema evolves; SAI mediates between them.
• Cryptographic centralization. Signing, parity computation, attribution, and integrity operations stay in SAI. Application code does not implement these and cannot subvert them.
The result is a clean separation: application code writes its domain content through a small set of well-defined methods; SAI handles everything else. The boundary is the subject of the next section.
The Helper API exposes exactlysix methods to application code: five writes (one per phase or any-phase) and one read. The method set is deliberately small. Anything more would risk exposing structural fields that SAI must own; anything less would not give application code enough to contribute its domain knowledge to the audit trail.
All writes go through schema validation and phase-validity checking before taking effect on the in-flight record. Calls against sealed phases or with non-conforming payloads fail with a structured error in the urn:sadar:error:v1 namespace. Successful calls produce no return value beyond an acknowledgment; the modification is reflected in the in-flight record and will be visible to subsequent get_invocation_context calls and in the finalized record.
Telemetry Record fields fall into two categories. The boundary between them is the most important architectural property of the Helper API design — it is what allows the resulting records to carry strong audit guarantees.
These are the fields the Helper API exposes for write access. They capture what the application knows that SAI does not: domain-specific extensions to matching criteria, summaries of opaque payloads, business-context tags, and risk signals from application-level monitoring.
These are the fields SAI populates from its own knowledge — the structural, attributional, cryptographic, and lifecycle content that makes the record a coherent and trustworthy audit artifact. The Helper API does not expose write access to these. Application code cannot modify them.
The boundary is not a contingent design choice; it is the source of the record's audit value. Fields the application could subvert would be useless as audit evidence — an auditor could not rely on values an arbitrary application might have written. By keeping the structural fields SAI-internal and the domain fields application-facing, the Helper API produces records whose structural content is trustworthy and whose domain content is rich.
Phase-immutability is a property of the Telemetry Record (covered in Telemetry Record, sibling page) —once a phase ends, its sealed sections become permanently immutable. The Helper API is the mechanism that enforces this property mechanically, in the active path.
Enforcement works at the API boundary. Each write method has a defined set of phases in which it is valid. A call outside those phases is rejected with a structured error before any modification reaches the in-flight record.
• set_criteria_extension is valid during the Search phase only, and only before the resolver executes. After the resolver runs, or once Search seals, the call fails.
• set_input_summary is valid during the Invocation phase. Calls during Search, Selection, or Outcome fail.
• set_output_summary is valid during the Outcome phase. Calls during earlier phases fail.
• add_audit_metadata and add_risk_adjustment are valid during any active phase, with each call attaching to whichever phase is currently active. Calls after finalize fail.
• get_invocation_context is read-only and valid at any time during the in-flight lifecycle.
The application does not need to track phase transitions explicitly to use the API correctly: the lifecycle is driven by SAI, and the API simply rejects calls that arrive at the wrong time. Out-of-phase errors surface immediately in development; production code that is structured correctly never sees them.
The deeper property: phase-immutability does not depend on application-developer discipline. A SADAR-conformant implementation enforces the invariant whether the application author intended to respect it or not. This is the difference between a guideline (which any team can violate by accident or design) and a structural property (which the implementation produces by construction).
The result of the field boundary plus phase-immutability enforcement is a set of structural guarantees that the Helper API produces about every Telemetry Record it builds. These are the properties that make the resulting records usable as audit evidence — not because the auditor trusts the application, but because the auditor can rely on what the implementation enforces.
In a typical audit context, trustworthiness depends on every participating application following audit discipline correctly. If any application skips audit, fabricates entries, or rewrites history, the audit story breaks. The Helper API inverts this: trustworthiness is a property of the implementation. Applications that use the Helper API correctly produce trustworthy records by construction; applications that try to subvert the audit story cannot, because the Helper API does not expose the means to do so. This inversion is what allows the resulting records to carry weight in cross-organizational audit scenarios where auditors do not know— and cannot reasonably verify — the discipline of every application that participated in a flow.
This page covers the Helper API as an architectural surface. Several adjacent topics are intentionally out of scope here and live in dedicated documents:
• Telemetry Record — the per-invocation audit artifact the Helper API writes to; covers six sections, four phases, phase-immutability as a structural property.
• Observability Overview — the cross-cutting summary of SADAR observability; how the Telemetry Record (and therefore the Helper API) composes with OTel baggage, Repatriation, and Risk Score.
• Repatriation — the mechanism by which Telemetry Records produced through the Helper API cross trust boundaries to authorized recipients.
• Provenance Attribution — the span-level attribution mechanism whose values are SAI-internal and not Helper-API-writable.
• Authentication Scopes — the urn:sadar:scope:v1 namespace that authorizes Helper API method calls.
• 2. Scope §5.1.14 — Observability umbrella; the normative source for Telemetry Record requirements at the spec level.
• 4. SCT Operations — full SCT cryptographic semantics; SCT chain link references in the invocation section are managed by SAI per these operations.
• 6. Telemetry Record and Repatriation — the full normative content for the Telemetry Record schema, including which fields are SAI-internal versus Helper-API-writable.
• 7. searchAndInvoke — the orchestrator that provides the Helper API; full method signatures, request/response envelopes, error conditions, and invocation lifecycle.
• 8. Risk Score Specification — how SAI's canonical Risk Score computation incorporates risk_adjustments contributed via add_risk_adjustment.