Tiffany ADR Index

This document tracks relevant Architectural Decision Records (ADRs) for the Tiffany agentic runtime project. ADRs are numbered sequentially and grouped by functional domain.

🗂️ Summary of Additional ADR Recommendations:

Choice of Rust Version

• ADR-0001: Choice of Rust Version
  Decision to use the latest stable Rust version for performance, safety, and ecosystem benefits.

Doc book Policy

• ADR-0002: Doc book Policy
  Documentation standards, structure, and tooling for maintaining high-quality project documentation.

🧠 Agent Architecture

• ADR-0003: Task Scheduler Model
  Coroutine-first, cooperative scheduling with stateful yield and resume semantics.

• ADR-0004: Agent Loop and ReAct Design
  Lifecycle of an agent: reasoning, acting, yielding, and interacting with tools.

• ADR-0005: Virtual Canvas Git Strategy
  Strategy for code change tracking, patch application, and micro-commits.

📦 Storage & Durability

• ADR-0006: WAL Schema and Replay Policy
  Format of write-ahead log, recovery semantics, and log compaction strategy.

• ADR-0007: Process Activity Log (PAL)
  Real-time activity tracking for agent tasks, complementing the WAL.

• ADR-0008: Persistent Agent Memory Strategy
  Design of Neo4j semantic memory, graph structure, and retrieval policies. Emphasize goals, prompts, plan recall, continuity between sessions.

• ADR-0009: Code Structure Graph and Symbol Analysis graph-based code indexing and semantic AST analysis into Neo4j, enabling precise symbol tracking and refactoring intelligence.

• ADR-0010: Task Plan Timeline and Execution Metadata Structure for task execution metadata, including plan history and decision lineage.

🧩 Modularity & Extensibility

• ADR-0011: Plugin and MCP Tooling Architecture
  How Tiffany integrates internal and external tools securely and generically.

• ADR-0012-: Agent Skill System (Future Plan)
  Representation of agent capabilities as composable skills.

🔐 Runtime & Execution

• ADR-0013: Firecracker MicroVM Integration
  VM lifecycle, execution isolation, resource constraints.

• ADR-0014: Command Execution and Safety Policy
  Shell execution flow, trust boundaries, and --yolo mode considerations.

📡 Interfacing & I/O

• ADR-0015: REST/gRPC API Design
  Interface contract for external task submission, result retrieval, and metadata queries.

• ADR-0016: Filesystem Socket Protocol for CLI
  Local interaction protocol for invoking agent actions via socket.

• ADR-0017: Kubernetes Operator and CRD Design Custom resource definitions for managing agent lifecycle and task orchestration.

🧪 Observability

• ADR-0018: Metrics Policy and Instrumentation Plan
  Prometheus metrics structure, naming conventions, and dashboard philosophy.

• ADR-0019: Logging Strategy and Span Hierarchy
  Use of tracing, span lifecycles, log level defaults.

🧭 Governance & Open Source

• ADR-0020: Versioning and Release Policy
  Semantic versioning, LTS channels, changelog protocol.

• ADR-0021: Contributor Roles and Governance
  Roles, responsibilities, PR review flow, escalation path.

22. Backup, Disaster Recovery, and Failover Strategy

• Policies around data recovery, backups, and failover mechanisms.
• Clearly defines how agent memory, logs, and metadata are backed up.
• Explicit recovery process, RTO (Recovery Time Objective), and RPO (Recovery Point Objective).

23. Secrets and Credentials Management

• Explicit handling of secrets, keys, tokens, and credentials.
• Integration with secure vaults (e.g., HashiCorp Vault, AWS Secrets Manager, Kubernetes Secrets).
• Auditing access and rotation policies.

24. Authentication and Authorization

• How FAR agents, developers, and other components authenticate securely.
• Role-Based Access Control (RBAC), OAuth/OIDC integration, or mTLS approaches.
• Explicitly defined trust boundaries and security contexts.

25. Dependency Management and Update Policy

• Management and update processes for third-party libraries, Rust crates, Kubernetes components, and container images.
• Vulnerability scanning and patching procedures.
• Policies around dependency updates, deprecations, and removals.

26. Performance and Scalability Strategy

• Detailed performance benchmarks, scalability tests, and capacity planning.
• Horizontal vs. vertical scaling policies.
• Strategies for proactive performance optimization and reactive capacity adjustments.

27. Localization and Internationalization (i18n) Policy

• How the system will handle internationalization, localization, and multilingual capabilities.
• Consideration of Unicode support, locale-aware formatting, and error handling.

28. Compliance, Auditing, and Regulatory Considerations

• Compliance with privacy regulations (GDPR, CCPA), standards (SOC 2, ISO 27001).
• Auditing policies, log retention strategies, and compliance reporting mechanisms.

29. Data Retention and Privacy

• Explicit data retention policies, data lifecycle management, and privacy guarantees.
• Handling and protection of personally identifiable information (PII), if relevant.

30. Cost Management and Budgeting

• Explicit policies around cost monitoring, cloud usage, and resource budgeting.
• Alerting on cost overruns, proactive cost management strategies, and cost optimization.

31. Accessibility and Usability Guidelines

• Ensuring the interfaces (CLI, UI, documentation) are accessible and usable.
• Compliance with WCAG accessibility standards.