Skip to content

file-format.md

Latest commit

 

History

History
174 lines (135 loc) · 6.42 KB

file-format.md

File metadata and controls

174 lines (135 loc) · 6.42 KB
status stable
title File Format
description The .acon binary file format specification

.acon File Format

AgenticContract stores all governance data in a single .acon binary file. The format is designed for fast random access, integrity verification, and forward compatibility.

Design Goals

  • Single-file portability: One .acon file contains all policies, limits, approvals, conditions, obligations, and violations
  • Integrity: BLAKE3 checksum covers all serialized data
  • Forward compatibility: Version field in header allows readers to reject unsupported formats gracefully
  • Compactness: Binary encoding minimizes disk and network overhead
  • Simplicity: No external dependencies; the file can be read with any language that supports basic I/O

Magic Bytes

Files begin with the ASCII bytes ACON (hex 0x41 0x43 0x4F 0x4E). This magic sequence allows file-type detection without relying on file extensions.

Offset  Hex            ASCII
0x0000  41 43 4F 4E    ACON

Overall Structure

┌─────────────────────────────────────┐
│  Header (fixed size)                │
│  ┌─────────────────────────────┐    │
│  │ Magic: ACON (4 bytes)       │    │
│  │ Version: u32 (4 bytes)      │    │
│  │ Flags: u32 (4 bytes)        │    │
│  │ Entity counts (8 × u32)     │    │
│  │ Timestamps (2 × i64)        │    │
│  │ Checksum: BLAKE3 (32 bytes) │    │
│  └─────────────────────────────┘    │
├─────────────────────────────────────┤
│  Entity sections (variable size)    │
│  ┌─────────────────────────────┐    │
│  │ Policies (JSON array)       │    │
│  │ Risk Limits (JSON array)    │    │
│  │ Approval Rules (JSON array) │    │
│  │ Approval Requests           │    │
│  │ Approval Decisions          │    │
│  │ Conditions (JSON array)     │    │
│  │ Obligations (JSON array)    │    │
│  │ Violations (JSON array)     │    │
│  └─────────────────────────────┘    │
└─────────────────────────────────────┘

Header Layout

The header is a fixed-size binary block at the start of every .acon file.

Offset Size Type Field Description
0 4 [u8; 4] magic b"ACON" — file type identifier
4 4 u32 version Format version (currently 1)
8 4 u32 flags Reserved for future use (currently 0)
12 4 u32 policy_count Number of policies
16 4 u32 risk_limit_count Number of risk limits
20 4 u32 approval_rule_count Number of approval rules
24 4 u32 approval_request_count Number of approval requests
28 4 u32 condition_count Number of conditions
32 4 u32 obligation_count Number of obligations
36 4 u32 violation_count Number of violations
40 4 u32 _reserved Reserved (approval decision count)
44 8 i64 created_at File creation timestamp (Unix seconds)
52 8 i64 modified_at Last modification timestamp
60 32 [u8; 32] checksum BLAKE3 hash of all entity data

Total header size: 92 bytes.

Entity Type Discriminator

Each entity type has a u8 discriminator used internally:

Value Entity Type
1 Policy
2 RiskLimit
3 ApprovalRule
4 ApprovalRequest
5 ApprovalDecision
6 Condition
7 Obligation
8 Violation

Entity Serialization

After the header, entities are serialized as JSON arrays, one per entity type, written sequentially. Each array is length-prefixed with a u64 byte count followed by the JSON payload.

┌──────────────────────────────────┐
│ length: u64 (8 bytes)            │
│ json_data: [u8; length]          │
└──────────────────────────────────┘

This approach balances human debuggability (entities are JSON) with structure (the header provides O(1) metadata access and the checksum covers integrity).

Checksum Verification

The BLAKE3 checksum in the header covers all bytes after the header. On load, the reader:

  1. Reads the header (92 bytes)
  2. Reads all remaining bytes
  3. Computes BLAKE3 over the remaining bytes
  4. Compares against header.checksum
  5. Returns ContractError::FileFormat on mismatch

This catches corruption from partial writes, disk errors, and accidental edits.

Version Compatibility

Current version: 1

Readers must:

  • Reject files with unrecognized magic bytes
  • Reject files with version > 1 (forward-incompatible)
  • Accept files with version == 1 regardless of flags (flags are advisory)

Future versions may:

  • Add new entity sections after existing ones
  • Add new fields to existing entity JSON schemas
  • Change the serialization format (would require version bump)

Byte order: All multi-byte integers use little-endian encoding.

Size Estimates

Content Approximate Size
Empty file (header only) 92 bytes
1 policy ~512 bytes
100 entities (mixed types) ~50 KB
1,000 entities (mixed types) ~500 KB
10,000 entities (mixed types) ~5 MB

File sizes scale linearly with entity count. JSON serialization adds overhead compared to pure binary but keeps the format inspectable with standard tools.

Inspecting Files

The acon info CLI command shows file metadata:

$ acon info
Format:   ACON v1
Created:  2026-02-27T10:30:00Z
Modified: 2026-02-27T14:15:00Z
Entities: 47 total
  Policies:          12
  Risk Limits:        5
  Approval Rules:     3
  Approval Requests:  8
  Conditions:         4
  Obligations:        6
  Violations:         9
Checksum: ok (BLAKE3)

Raw hex inspection shows the magic bytes:

$ xxd -l 16 ~/.agentic/contract.acon
00000000: 4143 4f4e 0100 0000 0000 0000 0100 0000  ACON............