New human-friendly directory sync format (RFC)

A new format for directory and Git sync is planned, replacing the current database-shaped YAML files with a versioned, human-oriented document format.

Goals

• Files that are understandable and safely editable without knowing anything about Yaak’s internals
• A one field edit produces a one field diff, so Git diffs describe intent instead of database noise
• No internal timestamps, parent IDs, or machine paths written to files
• Conflicts resolved against a common base, never by wall clock timestamps
• Stable IDs so renames and moves preserve history and references
• Malformed input or an ambiguous conflict never causes silent data loss
• Comments and unknown x- extensions in files survive edits made by Yaak

What it looks like

acme-api/
├── yaak.yaml
├── environments/
│   ├── development.yaml
│   └── production.yaml
├── users/
│   ├── _folder.yaml
│   ├── list-users.http.yaml
│   └── create-user.http.yaml
└── fixtures/
    └── user.proto

A request file reads like something a person would write:

id: rq_create_user
name: Create user
method: POST
url: ${[ base_url ]}/users

headers:
  - name: Content-Type
    value: application/json

body:
  type: json
  text: |-
    {
      "name": "Ada Lovelace",
      "email": "ada@example.com"
    }

Migration

Both the current format and the new one will be supported.