The .qual format

Append-only JSONL. One record per line. VCS-native by design.

A .qual file is a UTF-8 encoded file where each line is a complete JSON object representing one record. This is JSONL (JSON Lines).

{"metabox":"1","type":"attestation","subject":"src/parser.rs","issuer":"mailto:alice@example.com","issuer_type":"human","created_at":"2026-02-24T10:00:00Z","id":"a1b2c3d4...","body":{"kind":"concern","ref":"git:3aba500","score":-30,"summary":"Panics on malformed input"}}
{"metabox":"1","type":"attestation","subject":"src/parser.rs","issuer":"mailto:bob@example.com","issuer_type":"human","created_at":"2026-02-24T11:00:00Z","id":"e5f6a7b8...","body":{"kind":"praise","score":40,"summary":"Excellent test coverage"}}

Record types

Every record has a type field that identifies its schema. Qualifier defines three record types:

When type is omitted, it defaults to "attestation". Unknown types are preserved as opaque pass-through data.

Record envelope

All record types share a common Metabox envelope — a fixed set of fields that answer "who said what about which subject, when", plus a type-specific body object. The record envelope is an instance of the Metabox envelope format.

Attestation schema

Attestations are the primary record type. Envelope fields plus body:

Body fields are in alphabetical order (MCF canonical form).

Attestation kinds

When --score is omitted from qualifier attest, the CLI uses the default score for the given kind.

Epoch schema

An epoch is a compaction snapshot — a synthetic record that replaces a set of attestations with a single scored record preserving the net score. Envelope fields plus body:

Epoch issuer is always "urn:qualifier:compact".

{
  "metabox": "1",
  "type": "epoch",
  "subject": "src/parser.rs",
  "issuer": "urn:qualifier:compact",
  "issuer_type": "tool",
  "created_at": "2026-02-25T12:00:00Z",
  "id": "f9e8d7c6...",
  "body": {
    "refs": ["a1b2...", "c3d4..."],
    "score": 10,
    "summary": "Compacted from 12 records"
  }
}

Dependency schema

A dependency record declares directed edges from one subject to others. Envelope fields plus body:

{
  "metabox": "1",
  "type": "dependency",
  "subject": "bin/server",
  "issuer": "https://build.example.com",
  "created_at": "2026-02-25T10:00:00Z",
  "id": "1a2b3c4d...",
  "body": { "depends_on": ["lib/auth", "lib/http"] }
}

Dependency records don't carry scores. They feed the propagation engine that computes effective scores.

Supersession

Attestations are immutable. To "update" a signal, write a new attestation with body.supersedes pointing to the prior ID. Only the latest in a chain contributes to scoring.

Content-addressed IDs

Record IDs are BLAKE3 hashes of the Metabox Canonical Form (MCF) — a deterministic JSON serialization with fixed envelope field order, alphabetical body field order, no whitespace, and id set to "" during hashing.

{
  "metabox": "1",
  "type": "attestation",
  "subject": "src/parser.rs",
  "issuer": "mailto:alice@example.com",
  "created_at": "2026-02-24T10:00:00Z",
  "id": "",
  "body": {
    "kind": "concern",
    "score": -30,
    "summary": "Panics on malformed input"
  }
}

Optional body fields (span, detail, suggested_fix, tags, ref, supersedes) and the optional envelope field issuer_type are omitted from the canonical form when absent — the hash changes only when a field is actually present.

This ensures identical records always produce identical IDs, regardless of implementation language.

Compaction

Append-only files grow. Compaction reclaims space:

qualifier compact src/parser.rs              # prune superseded
qualifier compact src/parser.rs --snapshot   # collapse to epoch
qualifier compact src/parser.rs --dry-run    # preview first

Compaction MUST NOT change the raw score. If it does, the implementation has a bug.

File placement

The recommended layout is one .qual file per directory. qualifier attest defaults to this.

Dependency graph

Qualifier consumes a dependency graph as qualifier.graph.jsonl:

{"subject":"bin/server","depends_on":["lib/auth","lib/http","lib/db"]}
{"subject":"lib/auth","depends_on":["lib/crypto"]}
{"subject":"lib/http","depends_on":[]}

The graph MUST be a DAG. Cycles are rejected.