Qualification receipt contract — Kiln Documentation

Closed record of one local qualification run: source identity, execution envelope, selected backend and device, optional model identity, workload inputs, effective configuration, case outcomes, measurements, and hashed evidence. The Python validator enforces cross-field verdict, timestamp, platform, model, source, and artifact rules beyond this JSON Schema. A receipt is unsigned and has no self-digest; validate it and independently establish custody before treating it as trusted evidence.

Schema identity

Property	Value
Title	Kiln local qualification receipt
`$id`	`https://kiln.local/schemas/qualification-receipt-v1.json`
Dialect	`https://json-schema.org/draft/2020-12/schema`
Root type	`object`
Root object	closed

Root fields

Field	Required	Type	Constraints and default	Description
`schema_version`	yes	`any`	const 1	Qualification receipt contract version. The validator accepts only version 1.
`receipt_id`	yes	`string`	pattern ^[a-z0-9][a-z0-9._-]{2,127}$	Stable receipt label generated from time, backend, host, workload, and variant identity. It names the record but is not a content hash, signature, or uniqueness proof.
`created_at_utc`	yes	`timestamp`	-	UTC time when the receipt was created. The semantic validator requires it not to precede qualification.finished_at_utc.
`source`	yes	`object`	closed object	Identity of the source inputs and Git state observed for the run. The source-tree digest covers a defined repository subset; it does not hash this receipt, model files, result artifacts, or historical receipts.
`qualification`	yes	`object`	closed object	Runner-owned summary of the qualification category, backend family, profile, final verdict, wall-clock interval, and argv invocation.
`environment`	yes	`object`	closed object	Host, operating-system, selected-device, runtime, compiler, and optional platform-specific observations captured around the run. These observations identify the measured environment; they are not a portable device allowlist.
`model`	yes	`null \| model`	-	Model and tokenizer content identity for the measured run, or null when no model applies or a failed run could not establish it. Passed serving, performance, training, eval, and soak receipts require this object.
`workload`	yes	`null \| workload`	-	Committed workload identity, seed, and resolved parameters, or null only for environment qualification. The digest identifies the exact workload file bytes.
`effective_config`	yes	`configObject`	-	Configuration the command-produced cases proved they actually used. The local runner copies the selected variant only when every command-owned case reports an exact match; otherwise this object is empty and affected results fail.
`results`	yes	`array<result>`	minimum items 1	Runner-normalized, repetition-aggregated case outcomes in workload order. Required result status determines the receipt verdict; a passed receipt cannot contain a failed or skipped required result.
`metrics`	yes	`array<metric>`	-	Optional run-level measurements. The local workload runner currently emits case measurements under results and leaves this array empty; consumers must not silently combine the two scopes.
`artifacts`	yes	`array<artifact>`	-	Content-addressed evidence files for probes, model fingerprints, command output, normalized case results, and effective run configuration. Hash verification is opt-in for local_ignored files and is not performed for external locations.
`unsupported`	yes	`array<string>`	-	Non-empty capability or probe limitations reported by environment capture. Entries explain missing evidence; they do not automatically change the verdict.
`notes`	yes	`array<string>`	-	Non-empty runner annotations about this record, including receipt downgrades. Notes are explanatory text, not signed assertions or machine-enforced policy.

Composition and conditional rules

Show exact composition rules

{
  "allOf": [
    {
      "if": {
        "properties": {
          "qualification": {
            "properties": {
              "kind": {
                "not": {
                  "const": "environment"
                }
              }
            },
            "required": [
              "kind"
            ]
          }
        },
        "required": [
          "qualification"
        ]
      },
      "then": {
        "properties": {
          "workload": {
            "$ref": "#/$defs/workload"
          }
        }
      }
    },
    {
      "if": {
        "properties": {
          "qualification": {
            "properties": {
              "kind": {
                "enum": [
                  "serving",
                  "performance",
                  "training",
                  "eval",
                  "soak"
                ]
              },
              "verdict": {
                "const": "passed"
              }
            },
            "required": [
              "kind",
              "verdict"
            ]
          }
        },
        "required": [
          "qualification"
        ]
      },
      "then": {
        "properties": {
          "model": {
            "$ref": "#/$defs/model"
          }
        }
      }
    }
  ]
}

Definitions

capabilityStatusWhether a platform-specific probe established the named capability. For observed WSL2 and macOS capabilities, this declaration must agree with the corresponding evidence.0 fields

Type: any. Constraints: enum "available", "unavailable".

configValueOne finite JSON scalar, null, or recursively nested configuration object. List values are excluded so comparison code can address leaves with unambiguous dot paths.0 fields

Type: string | number | boolean | null | configObject.

Composition and conditional rules

The following JSON is copied exactly from this schema node.

{
  "oneOf": [
    {
      "type": [
        "string",
        "number",
        "boolean",
        "null"
      ]
    },
    {
      "$ref": "#/$defs/configObject"
    }
  ]
}

configObjectConfiguration namespace with lowercase, dot-path-compatible keys and finite scalar, null, or nested-object values.0 fields

Type: object.

Composition and conditional rules

The following JSON is copied exactly from this schema node.

{
  "propertyNames": {
    "pattern": "^[a-z][a-z0-9_-]*$"
  },
  "additionalProperties": {
    "$ref": "#/$defs/configValue"
  }
}

timestampUTC RFC 3339 timestamp ending in Z, with optional fractional seconds. The Python validator parses the value and enforces relevant ordering relationships.0 fields

Type: string. Constraints: pattern ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:.\d+)?Z$.

sha256SHA-256 digest written as sha256: followed by 64 lowercase hexadecimal characters. Syntax alone does not verify the referenced content.0 fields

Type: string. Constraints: pattern ^sha256:[0-9a-f]{64}$.

nonemptyStringMapNon-empty object of non-empty string values used for probe-reported runtime, compiler, or platform detail identities.0 fields

Type: object. Constraints: minimum properties 1.

Composition and conditional rules

The following JSON is copied exactly from this schema node.

{
  "additionalProperties": {
    "type": "string",
    "minLength": 1
  }
}

nullableSha256A SHA-256 content digest or null when the corresponding optional input does not exist.0 fields

Type: sha256 | null.

Composition and conditional rules

The following JSON is copied exactly from this schema node.

{
  "oneOf": [
    {
      "$ref": "#/$defs/sha256"
    },
    {
      "type": "null"
    }
  ]
}

weightFileOne model weight shard identified by path, byte length, and SHA-256 content digest.3 fields