Export Specification

Export Archive Format¶

FirstTry compliance exports are distributed as ZIP archives containing governance snapshots, audit ledger, and proof markers.

Archive Structure¶

export_firsttry_2026-02-26.zip
├── manifest.json              # Export metadata + proof markers
├── ledger.jsonl               # Audit trail (JSON lines)
├── snapshots/
│   ├── snapshot_1_2026-02-21.json   # Governance state snapshot
│   ├── snapshot_2_2026-02-23.json
│   └── snapshot_3_2026-02-26.json
├── hashes.txt                 # SHA256 manifest (for offline verification)
└── README.txt                 # Human-readable export guide

Manifest Structure (manifest.json)¶

{
  "export_timestamp": "2026-02-26T11:00:00Z",
  "export_version": "1.0",
  "app_version": "0.4.1",
  "audit_root_hash": "7a3b9c2d1e4f...",
  "audit_record_count": 147,
  "snapshot_count": 3,
  "build_git_sha": "abc123def456...",
  "build_ui_bundle_hash": "xyz789",
  "deterministic_zip_hash": "sha256_of_entire_zip",
  "customer_jira_site": "https://customer.atlassian.net",
  "export_scope": "complete",
  "integrity_status": "verified"
}

Snapshots (snapshot_N.json)¶

Each snapshot contains a point-in-time governance state:

{
  "snapshot_id": 1,
  "timestamp": "2026-02-21T14:30:00Z",
  "projects": [
    {
      "id": "PROJ1",
      "name": "Project One",
      "lead": "user123"
    }
  ],
  "permissions": [
    {
      "subject": "user456",
      "permission": "ADMINISTER_PROJECTS",
      "resource": "PROJ1"
    }
  ]
}

Ledger (ledger.jsonl)¶

Append-only audit trail, one JSON object per line:

{"action":"snapshot","snapshot_id":1,"hash":"abc123","nonce":"xyz","timestamp":"2026-02-21T14:30:00Z"}
{"action":"export","export_id":"exp_1","hash":"def456","nonce":"uvw","timestamp":"2026-02-26T11:00:00Z"}

Hash Manifest (hashes.txt)¶

SHA256 checksums for offline verification:

7a3b9c2d1e4f5a6b7c8d9e0f1a2b3c4d  manifest.json
8b4d0a2e1f6c7a9b3d1e5f2c0a7b4d8e  ledger.jsonl
a1c3e5f0b8d2a7c5e9f1b3d7a2c6e0f4  snapshots/snapshot_1_2026-02-21.json
...

Deterministic ZIP Ordering Rules¶

ZIP archives must be created with deterministic ordering to ensure reproducible hashes. Rules:

1. File order: Files listed in alphabetical order within the ZIP
2. Compression: All files compressed with DEFLATE (if used); no compression variation
3. Timestamps: All file timestamps set to fixed reference (e.g., 1980-01-01T00:00:00Z)
4. Permissions: All file permissions set to 0644 (standard read)
5. No extra headers: No ZIP comment, no metadata beyond standard ZIP format
6. No hidden files: No dot-files or temporary files

Determinism check:

# Create export twice; hashes must match
sha256sum export_firsttry_2026-02-26_attempt1.zip
sha256sum export_firsttry_2026-02-26_attempt2.zip
# Both SHA256 values must be identical

Verification Steps¶

Step 1: Download and Extract¶

unzip export_firsttry_2026-02-26.zip
cd export_firsttry_2026-02-26

Step 2: Verify Hashes (Offline)¶

sha256sum -c hashes.txt
# Output: manifest.json: OK
#         ledger.jsonl: OK
#         ...

Step 3: Extract Root Hash¶

grep "audit_root_hash" manifest.json
# Output: "audit_root_hash": "7a3b9c2d1e4f..."

Step 4: Verify Ledger Chain¶

Use FirstTry offline verification tool (if available):

node tools/verify_ecl_state.mjs --export-dir ./export_firsttry_2026-02-26 \
  --expected-root-hash 7a3b9c2d1e4f...
# Output: LEDGER_INTEGRITY_VERIFIED

Step 5: Manual Spot-Check (Readable)¶

head -5 ledger.jsonl  # Verify first 5 ledger entries are readable JSON
tail -5 ledger.jsonl  # Verify last 5 entries are present
cat snapshots/snapshot_1*.json | jq .timestamp  # Verify snapshot timestamps

Build Identity and Reproducibility¶

Build markers enable reproducibility checks:

Reproducibility: Given the same git SHA + app version, running forge deploy and exporting should produce an identical ZIP hash.

References¶

• LEDGER_CRYPTO_SPEC.md: Ledger hash chain formula
• SERIALIZATION_SCHEMA.md: JSON serialization rules
• ARCHITECTURE.md: Export component details