# The .dag Format — Formal Specification v1.4

The `.dag` file format is a compiled, machine-optimized representation of a spec genome. v1.4 uses compact single-character keys to minimize token usage. Agents decode keys, humans read the verbose spec.

## Grammar (JSON Schema — v1.4 Compact)

```
dag-file ::= {
  "v": "1.4",                   // version
  "p": string,                  // project name
  "c": string,                  // compiler (dotdog version)
  "n": [node, ...],             // nodes
  "e": [edge, ...]              // edges
}

node ::= {
  "i": string,                  // id (entity name)
  "t": string,                  // type (entity, event, etc.)
  "g": string,                  // category (entity | event | prediction)
  "d": string,                  // description
  "p": {                        // properties (compact encoding)
    "<name>": "<encoding>"
  },
  "s": [string, ...],           // states
  "l": [string, ...]            // lifecycle transitions
}

edge ::= {
  "s": string,                  // source node id
  "t": string,                  // target node id
  "v": string,                  // verb (produces, contains, etc.)
  "d": string,                  // description
  "c": string,                  // cardinality (1:1, 1:N, N:1, N:M)
  "r": boolean                  // required
}

token_report ::= {
  "m": "chars/4",              // method
  "st": number,                // source tokens (all files)
  "ct": number,                // content tokens (excludes <100 byte files)
  "dt": number,                // dag tokens
  "sv": number,                // savings % (all files)
  "cs": number,                // savings % (content only)
  "saved": number              // tokens saved
}
```

## Property Schema Encoding

Properties use a compact encoding:
- `s` = string
- `n` = number
- `b` = boolean
- `e` = enum
- `j` = json
- `!` suffix = required

Example: `"email": "s!"` means "string, required"
Example: `"status": "e!"` means "enum, required"
Example: `"stock": "n"` means "number, optional"

## Token Savings

v1.4 achieves real byte savings (not estimates). Use `dotdog tokens` to verify.

| Project | Source bytes | .dag bytes | Savings |
|---------|-------------|-----------|---------|
| spec-platform (7 files) | 46,848 | 5,179 | 88.9% |
| commander (2 files) | 4,483 | 3,383 | 24.5% |

Larger specs save more. The .dag overhead (~400 bytes JSON structure) is fixed.

## Backward Compatibility

MCP server (`dotdog serve`) supports both v1.3 (verbose) and v1.4 (compact) formats. Field accessors fall back to verbose keys when compact keys are absent.

## Conformance

An implementation is conforming if it:
1. Produces valid JSON matching the v1.4 compact grammar
2. Uses compact property encoding
3. Includes token report with method field
4. Validates all MUST rules from v1.3 (node references, acyclic graph)

## History

| Version | Date | Changes |
|---------|------|---------|
| 1.0 | 2026-06-12 | Initial spec |
| 1.1 | 2026-06-12 | Validation rules, edge cases, MCP API, token efficiency |
| 1.2 | 2026-06-12 | Integrity hash, provable token savings, typed nodes |
| 1.3 | 2026-06-12 | Full property schemas, category, lifecycle, edge descriptions |
| 1.4 | 2026-06-13 | Compact single-char keys, property encoding, real byte savings, content-only calc |