[dimetron]

Part of #3674 (split of #3673).

Scope

Library-only first slice of go/adk/pkg/declarative: an experimental document format (apiVersion: adk.declarative/v0alpha1, no compatibility promise) that builds ADK Go agents from YAML/JSON.

• Agent classes: Workflow, LlmAgent.
• Node types: function, join, tool (registered tools only), agent, llm (inline, single_turn), workflow (nested, max depth 8).
• Edges with START, string routes and DEFAULT, entry sugar; per-node retry (max_attempts, delays, backoff, jitter) and timeout; node input_schema/output_schema and LLM output_schema.
• Validation aggregates every issue with its field path (agents[1].nodes[2].tool: ...); decoding is strict, so unknown or not-yet-supported fields are rejected.
• Models: one model per workflow. NewRegistry(model) takes it via the constructor; documents omit model (or use stub, the offline test model). Any other model name is rejected. Documented in doc.go.
• Prompts: inline instruction/global_instruction only.

No CRD, proto, translator, controller, UI, Makefile, or image changes. No new dependencies (go mod tidy is clean).

Intentionally excluded (later PRs per #3674)

Feature	Lands with
cel nodes, CEL when / retry.when (cel-go dependency)	CEL PR
MCP tools (mcp_servers, server: on tool nodes)	MCP PR, via template tool bindings
callbacks / hooks	hooks PR
parallel_worker, dynamic, max_concurrency	fan-out PR
AgentTemplate/BYO wiring, ConfigMap instruction_from, config proto loading	API PR
agent_tools, toolsets, custom node types, model resolver	deferred pending the design discussion in #3674
SequentialAgent / ParallelAgent / LoopAgent	dropped (Workflow covers them)
HITL	deferred entirely

Testing

cd go
go test ./adk/pkg/declarative/...          # ok
go vet ./adk/pkg/declarative/...           # clean
make lint LINT_ARGS=./adk/pkg/declarative/...   # 0 issues
go mod tidy && git diff --exit-code go.mod go.sum   # no diff

Tests use Given/When/AssertThat scenarios. They cover a showcase document that runs every branch end-to-end with the stub model, the validation issue matrix, strict decoding of excluded fields, registry model resolution, retry/timeout, engine build failures, and runtime schema enforcement. About 2.2k lines including tests.