// Package adk provides ADK-Go tool wrappers for StemeDB.
//
// This package wraps the base StemeDB SDK with tool definitions suitable
// for Google's Agent Development Kit (ADK-Go). It provides:
//
//   - QueryTool - Query with lens-based conflict resolution
//   - AssertTool - Create assertions with confidence
//   - ConstraintCheckTool - Pre-flight validation
//   - TraceTool - Audit trail queries
//   - SupersedeTool - Epoch/correction management
//
// # Tools
//
// Each tool wraps a StemeDB operation and follows ADK conventions:
//
//	tool := adk.NewQueryTool(client)
//	inputBytes, _ := json.Marshal(adk.QueryInput{
//	    Subject:   "Tesla_Inc",
//	    Predicate: "has_revenue",
//	    Lens:      "consensus",
//	})
//	outputBytes, err := tool.Execute(ctx, inputBytes)
//
// # Agent Configurations
//
// Pre-configured setups for standard agent types:
//
//	configs := adk.AllConfigs(client, 0.8, setState, log.Printf)
//	implConfig := configs["implementation"]
//	leadConfig := configs["lead"]
//	researchConfig := configs["research"]
//
// # Callbacks
//
// Callback helpers for common patterns:
//
//	// Constraint enforcement (before code generation)
//	beforeCallback := adk.ConstraintEnforcementCallback(client, codeGenTools)
//
//	// Confidence escalation (after query)
//	afterCallback := adk.ConfidenceEscalationCallback(0.8, setState)
//
//	// Audit logging (after any tool)
//	auditCallback := adk.AuditLoggingCallback(log.Printf)
//
//	// Chain multiple callbacks
//	combined := adk.ChainAfterCallbacks(
//	    adk.ConfidenceEscalationCallback(0.8, setState),
//	    adk.AuditLoggingCallback(log.Printf),
//	)
//
// # Interface-Based Design
//
// Since ADK-Go is not yet publicly released, this package uses interface-based
// design that can adapt to any ADK implementation:
//
//	type Tool interface {
//	    Name() string
//	    Description() string
//	    Execute(ctx context.Context, input []byte) ([]byte, error)
//	}
//
// This allows:
//   - Easy testing with mock clients
//   - Adaptation to any ADK implementation
//   - Standalone usage without ADK
//
// # Agent Types
//
// Implementation Agent:
//   - Writes code against approved patterns only
//   - Checks constraints before code generation
//   - Blocks forbidden patterns
//
// Lead Orchestrator:
//   - Queries with appropriate lens
//   - Confidence threshold escalation
//   - Routes to implementation or human
//
// Research Agent:
//   - Stores all sources (even conflicting)
//   - Expresses uncertainty via confidence
//   - Marks as proposed (not approved)
//
// Human Supervisor:
//   - Time-travel queries (as_of parameter)
//   - Trace queries
//   - Supersede for corrections
//
// On-Call SRE:
//   - Sub-second trace queries
//   - Fast read-only investigation
//   - Escalation to supervisor
//
// For detailed examples and integration patterns, see:
//
//   - .claude/guides/integrations/adk-go-episteme.md
//   - use-cases/agile-agent-team.md
package adk