# <no value>
# Architecture Decision Records

This directory contains the Architecture Decision Records (ADRs) for this project.

## Format

Each ADR follows this structure:

```markdown
# NNNN: Title

**Status**: Proposed | Accepted | Superseded | Deprecated
**Date**: YYYY-MM-DD

## Context — What is the issue motivating this decision?

## Candidates — Options considered with trade-offs

## Decision — What we chose and why

## Consequences — What becomes easier/harder

## Constitution Compliance — Mapping to project principles
```

## Numbering Convention

ADRs are numbered sequentially: `0001`, `0002`, etc.
Numbers are never reused. If a decision is reversed, the original ADR is marked "Superseded" and a new ADR is created with a reference.

## Index

| ADR                                                           | Title                                                   | Status   |
| ------------------------------------------------------------- | ------------------------------------------------------- | -------- |
| [0001](0001-domain-hexagon-boundary.md)                       | Keep the Domain Behind Hexagonal Ports                  | Proposed |
| [0002](0002-sled-vfs-index-source.md)                         | Use Sled as the Persisted VFS Index Source              | Proposed |
| [0003](0003-cas-shadow-file-mutations.md)                     | Use CAS-Guarded Shadow-File Mutations                   | Proposed |
| [0004](0004-workspace-daemon-mcp-clients.md)                  | Use One Shared Workspace Daemon for MCP Clients         | Proposed |
| [0005](0005-native-sidecar-extensions.md)                     | Use Native Out-of-Process Sidecar Extensions            | Proposed |
| [0006](0006-extension-registry-read-paths.md)                 | Keep Extension Registry Writes Out of MCP Serving Paths | Proposed |
| [0007](0007-sidecar-multiplexed-frame-queue.md)               | Queue Inbound Sidecar Frames During HostCalls           | Proposed |
| [0008](0008-mcp-mutations-real-extension-host.md)             | Notify the Real Extension Host After MCP Mutations      | Proposed |
| [0009](0009-defer-apply-edits-extension-callbacks.md)         | Defer Extension Callbacks After Workspace Apply-Edits   | Proposed |
| [0010](0010-stage-daemon-startup-and-capability-readiness.md) | Stage Daemon Startup and Capability Readiness           | Proposed |
| [0011](0011-host-owned-agent-memory-storage.md)               | Use Host-Owned Namespaced Storage for Agent Memory      | Proposed |

<!--
  Update this table as ADRs are added. Format:
  | [0001](.template.md) | Decision Title | Accepted |
-->

## Creating a New ADR

1. Find the next number: `ls docs/ADR/ | grep -oP '^\d+' | sort -n | tail -1` + 1
2. Copy the template: `cp docs/ADR/.template.md docs/ADR/NNNN-short-name.md`
3. Fill in all sections
4. Update this index
5. Submit for review

## Pre-Merge Checklist

Before merging any new or modified ADR:

- [ ] **Cross-references**: All `[ADR-NNNN]` links resolve to existing files
- [ ] **Supersession**: If changing a prior decision, both ADRs have `Supersedes`/`Superseded by` metadata
- [ ] **Constitution**: Compliance section maps to current constitution version
- [ ] **Candidates**: At least 2 alternatives documented with trade-offs
n their own bounded preparation budget; a request timeout does not cancel daemon preparation.

Workspace, AST, and LSP readiness will be published independently by adapter-owned lifecycle state. Tool inventory and dispatch will use the same readiness snapshot. Unconfigured capability families are reported as unavailable, failures remain scoped when possible, and shutdown publishes a terminal stopping state. Domain and port contracts remain unchanged.

Committed file events from every authoritative producer will enter one ordered adapter-owned publication journal. Extension startup installs a subscriber while capturing a reconciled snapshot and watermark under the same publication ordering boundary. It replays that snapshot, drains committed events through a finite cut, and invokes a reserved host-only fence through the existing extension invocation path before atomically switching the extension to ready live delivery. Child I/O and callbacks never run while authoritative or publication locks are held.

## Consequences

**What becomes easier:**

- Clients can initialize promptly while slow workspace or extension preparation continues.
- Only one daemon generation can own Sled and workspace resources, including after client timeouts.
- Native workspace, AST, and LSP tools expose truthful, independently gated availability and failure states.
- Snapshot replay and concurrent mutations have an explicit ordering boundary with no event-loss window.
- Startup failure, cancellation, shutdown, and observability have one adapter-owned lifecycle model.

**What becomes harder:**

- The daemon must coordinate lifecycle transitions, bounded waits, worker cancellation, and owner-last shutdown.
- Every committed mutation producer must publish through the shared ordering boundary.
- Readiness-aware extensions must implement the reserved catch-up fence and preserve queue ordering.
- Compatibility requires conservative status decoding and stable structured readiness errors.
- Concurrency and recovery tests must cover ownership races, event cuts, delayed fences, and partial capability failure.

## Constitution Compliance

| Principle                 | Status    | Justification                                                                                                                    |
| ------------------------- | --------- | -------------------------------------------------------------------------------------------------------------------------------- |
| Domain purity             | Compliant | Ownership, readiness, publication, and instrumentation remain in adapters; domain and port signatures do not change.             |
| Multi-agent model         | Compliant | A lifetime workspace owner prevents concurrent daemon generations from opening the same Sled state.                              |
| Zero lock contention      | Compliant | Publication locks order in-memory commit records only; sidecar calls, disk replay, and callbacks occur after locks are released. |
| Extension fault isolation | Compliant | AST and LSP readiness and failures are isolated, bounded, and supervised per capability family.                                  |
| Index consistency         | Compliant | Snapshot watermarks, ordered committed events, and host-only fences close the startup-to-live-delivery gap.                      |
| Verification              | Compliant | The design requires process, concurrency, recovery, ordering, and full workspace completion tests.                               |
