# Specification

> Specification draft v0.2 defines five cumulative conformance levels, from L0 Files to L4 Sync. Each level corresponds to a set of concepts and a set of executable acceptance tests; a claim of “compatible” without a `conformance.json` is not accepted.

> **Draft.** There is no reference implementation and no runnable conformance suite yet. The acceptance tests below are part of the specification: their job is to make the word “compatible” checkable.

## Components of the specification

| Component | Contents | Target version |
| --- | --- | --- |
| Core | The six nouns, the Store contract, branches and protected trees, merges, soft delete. | v0.3 draft |
| Lease & Record | The lease format (an `authorization_details` profile), the format of records and read manifests, `explain`. | v0.3 draft |
| Interfaces | Mount semantics, the Git and S3 projections, the HTTP API, the MCP tool surface. | v0.4 draft |
| Memory | Note conventions, derivatives and recipes, budgeted reads, evidence pointers. | v0.4 draft |
| Guard | Labels, session taint, the policy profile, Gate Cards, the forget report. | v0.5 draft |
| Sync | Handoff bundles, label thresholds, tombstones. | Later |
| Conformance Suite | Executable acceptance tests for each level. | In step with each version |

## Conformance levels

Levels are cumulative: to claim L2, you must also satisfy L0 and L1.

| Level | Name | Concepts covered | In one line |
| --- | --- | --- | --- |
| L0 | Files | Agent Home, Agent Branch | A directory with history. |
| L1 | Authority | Flight Recorder, Capability Lease, Human Gate | Who, on what authority, did what. |
| L2 | Memory | Agent Memory, Budgeted Reads | Memory you can read and move. |
| L3 | Guard | Trust Labels, Cascade Forget | Limiting consequences. |
| L4 | Sync | None (optional) | Multiple nodes. |

## L0 Files: a directory with history

1. Changing files in a run branch leaves the protected main line unchanged.
2. A direct write to a protected tree is refused, even with valid credentials.
3. After a file in a protected tree is deleted, it can be restored from the recycle area.
4. Export followed by import yields a byte-identical tree and history.
5. At least two standard views are offered: mount and Git, or one of them plus S3.

## L1 Authority: who, on what authority, did what

1. A request without a lease is refused, and the refusal is recorded.
2. A request for a child lease wider than its parent is refused.
3. After a lease expires the mount becomes read-only; revocation takes effect within the time limit the implementation declares.
4. No lease can delete a snapshot.
5. Any commit can be `explain`ed back to a run, a lease and a read manifest.
6. Verification of the record chain passes; after one record is tampered with, verification fails.
7. When merging into a protected tree, the Gate Card shows a diff computed by the NAS, and the approval is bound to a digest: change the diff and the approval is void.

## L2 Memory: memory you can read and move

1. After all indexes are deleted and rebuilt, the golden recall tests pass.
2. Notes can be read without the Memory layer.
3. Every derivative carries a recipe and its inputs.
4. A budgeted read degrades when the budget is too small, and declares the view it actually returned.
5. Evidence pointers can be verified: after commits change, a pointer still points to the original content.

## L3 Guard: limiting consequences

1. Under a lease with B and C, when a session that read `external` content triggers a C-class action, it is refused or handed to a gate.
2. A derivative inherits the union of its inputs’ labels.
3. Notes written by a tainted session are not autoloaded.
4. A forget request produces a report that includes “what is not covered”; a legal hold can block forgetting.
5. Policy evaluation does not call an LLM: the policy engine makes no outbound calls to a model, so it can be audited.

## L4 Sync: multiple nodes

1. After two nodes synchronize, the trees are identical.
2. Highly sensitive objects are not sent to a node with a lower clearance.
3. Tombstones for forgetting propagate to the peer.
4. A handoff bundle can be executed on the peer, and leases only get narrower.

## The declaration format

An implementation must publish a `conformance.json` stating the level it conforms to, the result of each test and any known deviations. A claim of “compatible” without this file is not accepted.

*conformance.json*

```json
{
  "implementation": "example-nas",
  "version": "0.1.0",
  "spec": "0.2",
  "level": "L1",
  "tests": { "L0.1": "pass", "L0.2": "pass", "L0.3": "pass", "L0.4": "pass", "L0.5": "pass",
             "L1.1": "pass", "L1.2": "pass", "L1.3": "pass", "L1.4": "pass",
             "L1.5": "pass", "L1.6": "pass", "L1.7": "pass" },
  "deviations": ["L1.3: revocation takes effect within 60 seconds"]
}
```

## Versions and compatibility

- Semantic versioning. No compatibility is guaranteed during 0.x.
- New fields are backward compatible.
- A deprecated field keeps a warning period of at least one version.

## What the specification does not cover yet

Version details of transport protocols, a specific policy language, the signing algorithm for tokens, specific storage engines, and user interfaces.

---

Canonical URL: https://agentnas.com/spec/
Updated: 2026-11-11 · Draft specification v0.2 · CC BY 4.0