Erlang ADK 0.5.0 delivery contract

Status: frozen historical contract, completed on 2026-07-14 at branch checkpoint b93a79b. The final gate passed 765 EUnit tests, six Common Test scenarios, and Dialyzer over 160 project files. Unchecked items remain documented limitations.

This document is the implementation and verification contract for the version_0.5.0 branch. Version 0.5.0 focuses on artifacts, memory, and context. It starts from the completed 0.4.0 agent/tool/workflow runtime, but does not treat an existing module or happy-path API as proof that a complete behavior family is implemented.

The comparison target is externally observable behavior in the official ADK artifact, memory, context, context compression, and context caching documentation. Erlang ADK preserves useful behavioral outcomes while using OTP supervision, lightweight processes, monitors, explicit scopes, bounded admission, and message passing instead of copying another SDK's class hierarchy.

Status language

• Implemented means the public behavior, structural failure behavior, deterministic tests, concurrency/crash tests, and Dialyzer contract pass.
• Partial means a useful subset is implemented and tested, with its exact missing behavior documented.
• In progress means a branch change exists but has not passed all required gates.
• Planned means the target contract is agreed but no implementation claim is made.
• Adapter means core defines and tests a conformance contract while a provider- or deployment-specific implementation remains separate.

docs/FEATURE_PARITY.md is the current-state inventory. This document is the 0.5 delivery plan. A planned target here is not an implemented feature.

Evidence-backed starting point

The 0.5 branch begins at commit c7a4a83, the completed 0.4.0 branch. On 2026-07-14 the clean deterministic command passed:

• 654 EUnit tests with no failures;
• four deterministic Common Test scenarios, including the 1,000-invocation concurrency stress case;
• warning-free Dialyzer analysis over 134 project files.

The same command skipped all 14 paid live Gemini cases because ERLANG_ADK_LIVE_GEMINI was not set. Those skips are not counted as passes. The first baseline attempt used an empty Rebar cache and failed to resolve Hex dependencies before compilation; the measured gate above used the repository's configured Erlang toolchain and dependency cache.

The starting implementation is meaningful, but its former broad "Implemented" labels hide important release gaps:

• artifacts have immutable scoped versions, ETS and filesystem adapters, but no context facade, built-in loader, event delta, scoped authorization, bounded streaming data plane, or developer tooling;
• long-term memory has a lexical ETS reference adapter and Runner retrieval/whole-session ingestion, but scope is not mandatory, ingestion is neither sanitized nor idempotent, and no durable memory adapter exists;
• context selection has deterministic filtering, byte/token estimates, bounded compressor workers, and a fingerprint, but it is optional and Runner-only, does not budget the complete provider request, can split tool exchanges, has no automatic compaction, and has no actual provider cache.

Current branch snapshot

The following 0.5 slices are present on the branch as of 2026-07-14. The clean deterministic compile/EUnit/Common Test/Dialyzer gate and the separate packaged CLI gate now pass; the paid live-provider outcome is recorded below:

• artifact adapters share strict validation, quotas, capability discovery, deadline-aware mutations, bounded name/version pagination, metadata-only listing, filesystem staging/publication/repair, and conformance tests. Multi-instance-safe filesystem slots cap lifetime scopes per root and names per scope at max_scan_entries div 2; reservations cap versions per scoped name at max_scan_entries div 3. Scope/name/version-specific errors occur before listing/repair scan exhaustion, and deletion/restart does not restore these durable slots;
• optional bounded artifact and memory shard routers create one stable supervised worker per exact scope. They preserve same-scope ordering while unrelated scopes overlap over the ETS/filesystem and ETS/Mnesia backends; deterministic sharding coverage passes 12 tests, including immediate permit release when an admitted caller dies and rejection of its queued stale route;
• Runner creates owner-bound scope capabilities. Declaring local tools receive only requested state/artifact/memory operations, while remote and opaque tools receive no local handles. Artifact/memory effects are correlated to their tool events. Artifact name-page envelopes carry scope provenance, and all scope-bearing adapter replies are checked against the capability's exact scope/name before data or effects can escape; hostile cross-principal artifact and memory replies fail closed;
• adk_load_artifacts_tool selects verified scoped versions for bounded, ephemeral one-next-request attachment. The durable event keeps only the reference metadata. The targeted checked-in live Gemini selection case passed on 2026-07-14;
• Gemini projects only a small positive legacy tool-schema subset through parameters. Schemas with oneOf, additionalProperties, type unions, boolean subschemas, top-level boolean roots, or unknown keywords use parametersJsonSchema; the targeted artifact/memory live case passes with this boundary;
• memory v2 requires {user, App, User}, provides structured provenance and stable idempotency, bounded lexical ETS and durable local Mnesia adapters, deadline-aware calls, incremental event ingestion, hard retrieval budgets, built-in model-selected search, and entry/session/user erasure. A separate bounded Mnesia outbox provides durable admission, batch checkpoints, bounded runtime adapter resolution, and a renewed/revalidated ownership lease immediately before lease-owned idempotent at-least-once delivery. It does not claim an adapter-generation fence. A targeted checked-in live Gemini model-selected memory case passed on 2026-07-14;
• model-boundary safety canonicalization is mandatory. Context policy v2 uses O(n) complete-exchange selection, and the complete provider envelope has a separate fail-closed byte/token budget and fingerprint;
• automatic compaction and provider-request-prefix caching have strict, owner-bound lifecycle cores with cancellation, deadlines, bounded workers, checkpoints/TTL, single flight, private leases, invalidation, and structural fallback. Successful cache creation synchronously rechecks every absolute waiter deadline before installation and deletes the provider resource when no live waiter remains. Runner compaction atomically persists through the bundled ETS and Mnesia session backends. Runner-to-Gemini cache wiring, create/reuse/bypass, lifecycle, privacy, usage, generate, and stream behavior have deterministic mock-provider coverage. A checked-in live Runner gate now verifies real create/reuse lifecycle and private-resource absence when quota permits. In the full 2026-07-14 run, cached-content creation received HTTP 429 after its one bounded retry, so the case failed as rate-limited and is not a live pass;
• the authenticated developer surface has redacted context diagnostics, content-free compaction/cache lifecycle and confirmed cache-scope invalidation, metadata-only artifact list/delete, scoped memory status/search/erase, CLI commands, and an exact-scope resource_provider contract. Artifact name-page, artifact-version, and memory-hit projections reject adapter results whose embedded scope differs from the requested path. The session-anchored cache operation explicitly invalidates the configured provider/app/user/model/policy scope across sessions;

Open integration work includes pending-outbox erasure coordination, event-effect orphan recovery, credit-based artifact streaming, and a quota-backed successful cache/Search live rerun.

Architectural decisions

These decisions apply across the release.

1. Scopes are explicit authority. Internally, artifacts use explicit app, user, and session tuples; memory uses a mandatory app/user scope with session/event provenance. We will not depend on caller-supplied metadata filters or copy a user: filename convention into storage internals.
2. Contexts are immutable views plus capabilities. An invocation owns the complete runtime context. Callback and model views are redacted/read-only; tools receive only declared state, artifact, memory, auth, or confirmation capabilities. Raw storage handles are not ambient authority.
3. Events are the durable effect boundary. State deltas and committed artifact references are recorded in canonical event actions. Cross-service writes use a staged/committed protocol with explicit orphan recovery rather than implying an impossible distributed transaction.
4. Safety at the model boundary is mandatory. Secret-key pruning, canonical encoding, and request validation always run. Selection, truncation, compression, memory retrieval, and caching remain configurable.
5. Every workload is bounded. Item bytes, total bytes, counts, metadata, queue depth, concurrency, deadlines, retries, and replay/stream credits have finite validated limits. A caller timeout or death must not cause a later invisible "ghost" commit.
6. Independent scopes should overlap. Coordination may serialize one logical artifact name, memory key, session, or cache key, but unrelated scopes run in supervised lightweight workers. One global GenServer must not perform all file I/O, ranking, compression, or provider calls. The direct bundled artifact and memory reference adapters remain serialized reference paths. The opt-in bounded sharded wrappers meet the exact-scope overlap path with stable supervised workers and same-scope ordering. Their current limits are per-shard rather than global quotas and no idle-worker eviction.
7. Local core and managed backends are separate. ETS and Mnesia/filesystem adapters provide deterministic local behavior. Object stores, vector databases, and managed memory systems implement tested behaviors without becoming hard dependencies of the agent runtime.
8. Context caching is not response caching. The current SHA-256 value is a context fingerprint. Real context caching reuses a validated model-request prefix through a provider adapter, has a TTL/lifecycle, and never returns a cached model answer.

Starting capability matrix

Artifacts

Memory and supporting session state

Context, compaction, and caching

Delivery phases

0. Branch truth and contract

• [x] Audit artifact, memory, session/state, context, Runner, developer API, CLI/UI, and current deterministic tests.
• [x] Compare observable behavior with current official ADK documentation.
• [x] Run the inherited clean deterministic baseline.
• [x] Correct branch/version references and downgrade over-broad current-state claims to Partial.
• [x] Record this implementation and verification contract.

A. Shared scopes, contexts, and service contracts

• [x] Define versioned scope, entry, artifact reference, context metadata, and capability types with strict size/count/UTF-8/JSON limits.
• [x] Add immutable invocation and tool context facades; declare per-tool capabilities and retain an explicit compatibility path.
• [ ] Compile service and context policies at Runner creation, reject unknown options, and propagate one absolute deadline/cancellation signal.
• [x] Add adapter capability discovery and shared conformance suites for ETS, filesystem, Mnesia, and test doubles.
• [x] Define canonical artifact, memory, compaction, and cache metadata without placing credentials or opaque runtime handles in events.
• [x] Preserve provider-neutral compiled tool validation while projecting non-legacy JSON Schema, including top-level boolean roots, through Gemini parametersJsonSchema.

B. Artifact behavior and data plane

• [x] Add scoped context save/load/list-names/list-versions/delete helpers and bounded compatibility wrappers.
• [x] Add model-selected load-artifacts behavior for text and multimodal content without permanent history inflation.
• [ ] Introduce scoped capabilities, quotas, per-name coordination, supervised data-plane workers, bounded admission, cancellation, and credit/ack streams.
• [x] Add an opt-in bounded exact-scope shard router so unrelated artifact scopes overlap while operations inside one scope remain ordered.
• [x] Make filesystem publication atomically reader-visible and restart-repairable; preserve reservations so versions are never reused.
• [x] Enforce filesystem lifetime version admission before bounded scan exhaustion plus multi-instance-safe scope/name slot admission, and expose every persistent lifetime ceiling in capabilities.
• [x] Commit metadata-only artifact references through correlated Runner tool event effects.
• [ ] Complete durable orphan recovery when event persistence fails after an artifact mutation.
• [x] Add authenticated metadata-only artifact API/CLI/UI operations. Raw upload/download remains outside this developer surface.
• [ ] Add content-free artifact capacity, repair, and lifecycle telemetry.

C. Scoped and durable memory

• [x] Replace the unscoped memory behavior with a versioned scoped contract; keep compatibility wrappers explicitly documented.
• [x] Define structured memory entries/search hits with source session/events, author, timestamp, digest, score type, and bounded custom metadata.
• [x] Rework ETS memory as a supervised bounded reference adapter and add a durable Mnesia adapter using the same conformance suite.
• [x] Add an opt-in bounded exact-user shard router so unrelated memory scopes overlap while operations for one app/user remain ordered.
• [x] Add sanitized incremental ingestion, stable idempotency keys, and a durable outbox with fail-closed admission, checkpoints, timeout-bounded resolution, pre-mutation ownership renewal/revalidation, idempotent at-least-once retry, and bounded backoff.
• [ ] Coordinate entry/session/user deletion with pending outbox jobs.
• [x] Support both automatic preload and model-selected load-memory retrieval, with hard hit/byte budgets and untrusted-reference framing.
• [x] Add scoped entry/session/user erase and exact-scope developer operations.
• [ ] Add automatic retention/TTL, application consent/policy hooks, and adapter lifecycle telemetry beyond durable-outbox admission.

D. Complete request context, compaction, and caching

• [x] Make canonical safety processing mandatory for every model execution path while keeping selection/compression configuration explicit.
• [x] Build complete provider envelopes and account for instructions, memory, history, current input, tools, parts, and provider framing.
• [x] Implement O(n), exchange-aware selection and validate current-input, chronology, ID, role, multimodal, and tool-pair invariants.
• [x] Move compression into owner-bound workers with absolute deadlines, cancellation, and semantic output validation.
• [x] Add automatic token/turn compaction with retained recent events, persisted summary checkpoints, and an atomic expected-prefix session commit.
• [x] Rename the local digest to context_fingerprint; implement actual provider caching separately.
• [x] Add Gemini cached-content create/reuse/update/delete support for gemini-3.1-flash-lite, supervised single-flight creation, conservative tenant/model scoping, fallback, expiration, cached-token telemetry, and deterministic generate/stream coverage. Live evidence remains a separate gate.
• [x] Recheck all absolute waiter deadlines synchronously before cache result installation and delete a newly created orphan when no live waiter remains.

E. Integrated developer tooling and documentation

• [x] Extend the authenticated /dev/v1 API and dependency-free console with metadata-only artifact, scoped memory, and redacted context diagnostics. Raw artifact transfer and private provider-cache resources are intentionally omitted.
• [x] Add equivalent checked adk inspect/management commands, bounded pagination/streaming, structural errors, and machine-readable output.
• [x] Add content-free compaction checkpoint and cache lifecycle status/invalidate operations without returning leases or provider resource names.
• [x] Reject artifact-version and memory-hit developer projections when the adapter's embedded scope differs from the requested path.
• [x] Document the same endpoints so Phoenix/LiveView integrations can proxy scoped operations without receiving storage root handles or provider keys.
• [x] Add literal deterministic README examples for each public behavior and map every example to a test in docs/README_EXAMPLE_COVERAGE.md.
• [x] Reconcile docs/ARTIFACTS.md, memory/context guides, and docs/FEATURE_PARITY.md with the clean deterministic and live-provider results.

F. Release evidence

• [x] Pass focused unit and adapter-conformance suites.
• [x] Pass crash-injection, property/invariant, and 1,000-operation concurrency Common Test suites with zero orphan workers or unbounded mailboxes.
• [x] Pass every README example and authenticated developer API/CLI/UI test in the clean deterministic gate.
• [x] Pass the clean compile, EUnit, Common Test, and Dialyzer command.
• [x] Pass escript packaging, doctor, and checked config validation.
• [x] Run the separate live Gemini suite with gemini-3.1-flash-lite; 14 cases passed and two failed with HTTP 429 after their bounded retries, with no skips.
• [x] Update package version/status evidence; capability rows remain Partial wherever complete release requirements or documented semantics remain open.

Required failure and concurrency tests

Artifact tests must cover crashes after reservation/data/metadata/publication, restart repair, no version reuse, concurrent service instances, no transient corruption, independent-scope overlap, same-name ordering, overload, caller death, cancellation, stream backpressure, quotas, traversal/symlink attacks, cross-principal denial, staged-event orphan cleanup, and failure before lifetime scope/name/version scan exhaustion with multi-instance admission and deletion/restart persistence of every ceiling.

Memory tests must cover cross-app/user/session isolation, adversarial filters, secret/control-data exclusion, malformed or oversized adapter replies, incremental deduplication across retry/restart/concurrent completion, durable recovery, retention/erasure, bounded ranking, queue pressure, timeout-bounded resolver cleanup, ownership loss before adapter mutation, and 1,000 mixed search/ingest/delete operations. Shard-router tests must also prove that caller death releases a cold-route permit and cannot create an abandoned worker from an already queued route.

Context tests must cover unknown configuration, complete-request budgeting, multimodal messages, tool-pair preservation, immutable current input, compressor crash/heap/timeout/owner death/cancellation, concurrent admission, automatic compaction restart, provider-cache single flight/expiry/invalidation, tenant isolation, fallback, queued provider completion after the last waiter deadline, orphan-resource deletion, and zero secret values in cache resources, telemetry, errors, logs, or developer previews. Developer tests must reject artifact name-page, artifact-version, and memory-hit results whose embedded scope differs from the requested path.

Provider-tool tests must preserve non-legacy JSON Schema through parametersJsonSchema, including nested and top-level boolean schemas, without crashing or weakening the locally compiled contract.

Verification commands

The deterministic release gate is:

./rebar3 do clean, compile, eunit, ct, dialyzer
./rebar3 eunit --module=readme_examples_test
./rebar3 eunit --module=readme_workflow_examples_test
./rebar3 ct --suite test/runtime/invocations/adk_concurrency_stress_SUITE.erl
./rebar3 ct --suite test/integrations/stress/adk_v05_stress_SUITE.erl
./rebar3 escriptize
_build/default/bin/adk doctor
_build/default/bin/adk config validate examples/agent.json

adk_v05_stress_SUITE passes two scenarios: 1,000 bounded artifact/memory writes across isolated scopes, and 128 concurrent cache acquisitions across four exact scopes collapsing to four provider creates/deletes. Live provider behavior remains a separate opt-in gate:

ERLANG_ADK_LIVE_GEMINI=1 ./rebar3 ct \
  --suite test/readme/readme_live_gemini_SUITE.erl

The clean deterministic release command passed on 2026-07-14: 765 EUnit tests and six Common Test scenarios completed with no failures, and Dialyzer reported no warnings across 160 project files. The paid live suite was not enabled in that command, so its 16 cases were skipped and are not counted as passes.

The following focused deterministic evidence was also recorded in the current shared tree:

./rebar3 eunit --module=readme_examples_test
# 29 tests, 0 failures after the v2 scoped-memory README fixture update
./rebar3 eunit --module=adk_context_cache_gemini_test
# 7 cache-wire tests, 0 failures
./rebar3 eunit --module=adk_llm_gemini_test
# 29 Gemini adapter tests, 0 failures; only the positive legacy subset uses
# parameters, while oneOf/additionalProperties/type unions/boolean subschemas
# and top-level boolean roots use parametersJsonSchema
./rebar3 eunit --module=adk_context_cache_test
# 10 tests, 0 failures, including exact-scope lifecycle and synchronous
# waiter-deadline recheck before provider-resource installation
./rebar3 eunit --module=adk_memory_outbox_test
# 6 tests, 0 failures, including resolver timeout, lease renewal, and
# ownership loss before adapter delivery
./rebar3 eunit --module=adk_dev_v05_http_test
# 9 tests, 0 failures, including lifecycle privacy, confirmation, and
# fail-closed embedded-scope mismatch projections
./rebar3 eunit --module=adk_artifact_fs_test
# 15 tests, 0 failures, including multi-instance-safe persistent
# scope/name/version lifetime admission
./rebar3 eunit --module=adk_scope_sharded_test
# 12 tests, 0 failures, including exact-scope ordering, overlap, isolation,
# strict atomic cold-route admission, killed-caller permit cleanup, and
# ETS/filesystem/Mnesia backends
./rebar3 dialyzer
# passed; 160 project files analyzed at that point in the shared tree

The sharded adapters deliberately enforce limits per shard; they do not aggregate a global storage quota, and active scope workers are not idle-evicted in 0.5.

An earlier combined 14-module artifact/memory/context gate covering adapter conformance, ETS/filesystem/Mnesia storage, the durable outbox, context policy and complete envelopes, capabilities, compaction, Runner integration, the provider-neutral cache, and Gemini exact-wire caching passed 90 tests with no failures. Additional Runner and lifecycle cases landed afterward, so 90 is not the final combined 0.5 total; the clean 765-test result above supersedes it. Socket-bearing README, developer HTTP, and cache-wire fixtures were run outside the restricted sandbox against loopback only.

After the Gemini tool-schema projection fix, the targeted checked-in readme_live_gemini_SUITE:artifact_and_memory_tools/1 case passed 1/1 against gemini-3.1-flash-lite on 2026-07-14, exercising both model-selected memory and artifact rounds. Only the positive legacy subset remains in parameters; oneOf, additionalProperties, type unions, nested or top-level boolean schemas, and unknown keywords are preserved in parametersJsonSchema. The subsequent full live run passed this case.

The live process must inherit GEMINI_API_KEY. The checked-in readme_live_gemini_SUITE:context_cache/1 case uses a sufficiently large stable prefix and a real Runner to require resource creation, reuse it across two sessions, assert public created then hit lifecycle metadata, and prove the private resource name is absent from durable events. On the full 2026-07-14 run, its create request received HTTP 429 after the one bounded ten-second retry, so it failed as rate-limited and does not replace deterministic adapter tests.

Before that case was checked in, a sanitized manual erl -noshell probe on 2026-07-14 used a stable estimated 6,000-plus-token prefix, reached cachedContents.create, and received HTTP 429. One bounded retry after ten seconds also received 429. No resource was returned, so there was nothing to delete, and the GenerateContent step was not reached. This historical result is RATE-LIMITED (quota or billing), not a pass, skip, or deterministic regression.

Overall, the full opt-in live suite against gemini-3.1-flash-lite passed 14 of 16 cases with no skips. google_search_grounding and context_cache were the only failures; each received HTTP 429 after one bounded retry. They are recorded as quota/rate-limit failures, not implementation passes.

Explicit non-goals

• Erlang ADK will not embed a production vector database, object-store SDK, or KMS into every application; those are conformance-tested adapters.
• Raw multi-megabyte blobs will not pass through one global coordinator mailbox or be copied into session state/history.
• A context fingerprint will not be described as a cache, and context caching will not be described as model-response caching.
• Cross-service event/effect handling will not claim exactly-once external side effects. It will expose the commit boundary, idempotency key, recovery, and orphan policy.
• Python method names, zero-based artifact version numbers, and object models are not compatibility goals when the Erlang contract is clearer and safer.

Documentation rule

Public examples describe only behavior that has passed its gate. Partial features state their missing semantics next to the example. Unsupported input, overload, scope violations, timeout, cancellation, and unavailable services return explicit structural errors; none are silently accepted or counted as successful compatibility.