driftproof 0.3.0 → 0.4.0

package/lib/skill.js

@@ -59,7 +59,13 @@ function loadSkill(skillDir) {
   }
   const suiteRaw = JSON.parse(fs.readFileSync(suitePath, 'utf8'));
   const cases = normalizeCases(suiteRaw);
-  const suiteHash = sha256Canonical(cases);
+  // suite_hash is over the CORE case fields only ({id, prompt, rubric,
+  // pass_threshold}); optional annotations (checks, and the claim/grounding the
+  // gate reads straight from the raw suite) are excluded so adding them never
+  // disturbs a receipt's suite_hash. See spec/RECEIPT.md § suite.
+  const suiteHash = sha256Canonical(cases.map((c) => ({
+    id: c.id, prompt: c.prompt, rubric: c.rubric, pass_threshold: c.pass_threshold,
+  })));
 
   return {
     dir,
@@ -110,7 +116,11 @@ function normalizeCases(raw) {
     if (!rubric) throw new Error(`case "${id}" is missing a rubric/criteria/expected`);
     const threshold = typeof c.pass_threshold === 'number' ? c.pass_threshold
       : typeof c.threshold === 'number' ? c.threshold : 0.7;
-    return { id, prompt: String(prompt), rubric: String(rubric), pass_threshold: threshold };
+    const norm = { id, prompt: String(prompt), rubric: String(rubric), pass_threshold: threshold };
+    // Optional deterministic post-checks (v0.3.1). Carried through for the runner
+    // but EXCLUDED from suite_hash (see loadSkill) so they never disturb a receipt.
+    if (Array.isArray(c.checks) && c.checks.length) norm.checks = c.checks;
+    return norm;
   });
 }
 

package/lib/skillCost.js

@@ -0,0 +1,31 @@
+// SPDX-License-Identifier: Apache-2.0
+'use strict';
+
+// Value-per-token axis.
+//
+// A skill is not free: its SKILL.md is prepended to every generation, so a skill
+// that lifts scores by +0.10 for 400 tokens is a very different proposition from
+// one that lifts +0.10 for 6,000 tokens. Driftproof reports each skill's lift
+// (delta) BOTH raw AND normalized per 1,000 skill tokens.
+//
+// Token estimate: a coarse `ceil(chars / 4)` proxy — the standard rough rule for
+// English text, NOT a model tokenizer (no tiktoken dependency; the number is a
+// consistent proxy for comparing skills, not a billing figure). Documented on
+// docs/methodology.html.
+
+const CHARS_PER_TOKEN = 4;
+
+function estimateTokens(text) {
+  const s = String(text || '');
+  if (!s.length) return 0;
+  return Math.ceil(s.length / CHARS_PER_TOKEN);
+}
+
+// Lift per 1,000 skill tokens: delta / (skillTokens / 1000). Null when the token
+// count is unknown or zero (avoids a divide-by-zero masquerading as infinite value).
+function deltaPer1kTokens(delta, skillTokens) {
+  if (typeof delta !== 'number' || !skillTokens || skillTokens <= 0) return null;
+  return Math.round((delta / (skillTokens / 1000)) * 1e4) / 1e4;
+}
+
+module.exports = { estimateTokens, deltaPer1kTokens, CHARS_PER_TOKEN };

package/lib/verdict.js

@@ -21,6 +21,10 @@ const VERDICTS = {
   PASSED: { color: 'brightgreen', word: 'passing' },
   NO_EFFECT: { color: 'lightgrey', word: 'no effect' },
   REGRESSED: { color: 'red', word: 'regressed' },
+  // Interop (Phase 7): a receipt below TESTED (imported/DECLARED) or with no
+  // delta (a source tool with no baseline mode) never gets a pass/fail verdict
+  // — declared numbers are recorded, not verified, so the badge says so.
+  NOT_MEASURED: { color: 'lightgrey', word: 'not measured' },
 };
 
 // Strip a trailing -YYYYMMDD date stamp so the badge reads cleanly
@@ -35,8 +39,13 @@ function verdictFromReceipt(receipt) {
   const cmp = (receipt && receipt.comparison) || {};
   const delta = typeof cmp.delta === 'number' ? cmp.delta : 0;
   const model = shortModel(receipt && receipt.run && receipt.run.model_id);
+  // Below-TESTED receipts (imported/DECLARED) and null-delta receipts are never
+  // verdicted — we did not run the suite, so we do not certify the outcome.
+  const level = (receipt && receipt.verification_level) || 'TESTED';
+  const measured = level === 'TESTED' && typeof cmp.delta === 'number';
   let verdict;
-  if (delta >= EFFECT_FLOOR) verdict = 'PASSED';
+  if (!measured) verdict = 'NOT_MEASURED';
+  else if (delta >= EFFECT_FLOOR) verdict = 'PASSED';
   else if (delta <= -EFFECT_FLOOR) verdict = 'REGRESSED';
   else verdict = 'NO_EFFECT';
   const meta = VERDICTS[verdict];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "driftproof",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Continuous verification of agent skills: run a skill's eval suite with and without the skill across model versions, emit signed dated receipts, and diff receipts into drift reports.",
   "license": "Apache-2.0",
   "keywords": [

package/spec/RECEIPT.md

@@ -1,5 +1,5 @@
 <!-- SPDX-License-Identifier: Apache-2.0 -->
-# Driftproof receipt — spec v0.3
+# Driftproof receipt — spec v0.3.1
 
 A **receipt** is a signed, dated record of running one agent skill's eval suite
 **with** and **without** the skill on one model version, with the judge **sampled**
@@ -11,13 +11,74 @@ The machine-readable contract is [`receipt.schema.json`](./receipt.schema.json)
 (JSON Schema, draft 2020-12). This document is the human companion. Where they
 disagree, the schema wins.
 
-**Versioning.** The current schema is v0.3
+**Versioning.** The current schema is v0.3.1
 ([`receipt.schema.json`](./receipt.schema.json)). Prior schemas are kept as
+[`receipt.v0.3.schema.json`](./receipt.v0.3.schema.json),
 [`receipt.v0.2.schema.json`](./receipt.v0.2.schema.json) and
 [`receipt.v0.1.schema.json`](./receipt.v0.1.schema.json); the validator picks the
-schema by the receipt's own `schema_version`, so v0.1 and v0.2 receipts still load
-and validate. v0.3 is an **additive** bump — every field it adds is required in a
-fresh run, but older receipts are read unchanged against their own schema.
+schema by the receipt's own `schema_version`, so v0.1, v0.2 and v0.3 receipts still
+load and validate. v0.3.1 is an **additive** bump — `run.provider` is required in a
+fresh run and the rest is optional, but older receipts are read unchanged against
+their own schema.
+
+## Interop-additive revision (Phase 7 — receipts as an open format)
+
+The v0.3.1 schema gained an **additive interop revision** so receipts can be
+**imported** from neighboring eval tools with honest epistemics (see
+[`docs/interop.md`](../docs/interop.md) and the site's `/interop.html`):
+
+- `run.surface` and `run.judge.surface` gain **`"external"`** (the run happened
+  on another tool's harness); `run.transcripts` gains **`"none"`** (nothing
+  retained, not even hashes — only honest on an import).
+- New optional **`run.source`** — provenance of a converted receipt, e.g.
+  `"imported/agent-skills-eval"` or `"imported/skillgrade"`.
+- `skill.content_hash`, `suite.suite_hash`, and per-case `judge.rubric_hash` may
+  be **`null`**, per-case `generation_hash`/`judge_sample_hashes` may be
+  **omitted**, and `comparison.baseline_score`/`delta`/`delta_uncertainty` may be
+  **`null`** (a source tool with no baseline mode) — hashes and baselines are
+  **never fabricated**. `suite.format` may name a non-agentskills format (e.g.
+  `"skillgrade/eval.yaml"`).
+- **The TESTED tightening** (a top-level schema conditional) makes every one of
+  those relaxations available **only below `TESTED`**: a receipt claiming
+  `verification_level: "TESTED"` must still carry the full evidence chain —
+  content/suite hashes, per-case generation + judge-sample hashes, a
+  non-`external` surface, numeric comparison — exactly as before. No previously
+  issued receipt is invalidated, and `TESTED` keeps its meaning.
+- Structural consequence, enforced in code: **drift verdicts require `TESTED`
+  on both sides** — `diff` reports **NOT MEASURED** against a `DECLARED`
+  (imported) receipt, and a `DECLARED` receipt's badge reads *not measured*.
+
+## What changed from v0.3 (multi-provider — spec v0.3.1)
+
+- **`run.provider`** (required) — the two-axis provider the target model ran on:
+  `"anthropic"` or `"openai"` (from the registry `provider`, else inferred from the
+  id). Driftproof is now two-provider: the same suites and the same fixed judge,
+  run on Claude and GPT substrates.
+- **`run.surface`** gains the OpenAI lanes: the enum is now
+  `"api" | "claude-cli" | "openai-api" | "openai-cli"`. `openai-api` = a
+  Chat-Completions-compatible API (base_url configurable); `openai-cli` = the Codex
+  subscription surface (`codex exec`). `run.judge.surface` accepts the same set.
+- **`run.surface_overhead_note`** (optional) — present on the `openai-cli` surface:
+  states the fixed Codex base-instruction preamble (~12–15k input tokens per call)
+  that the harness prepends and does not control. The model id is set by us via
+  `-m` (it is not echoed in the Codex JSONL stream).
+- **Per-case `checks[]`** (optional) — deterministic post-check results, each
+  `{ name, kind, pass }` with `kind ∈ regex | contains | not_contains | min_length`.
+  Structural/regex assertions run on the model output **alongside** the judge and
+  reported as a **separate column** — **supplementary evidence only, never folded
+  into the `outcome`/band verdict.**
+- **`skill.tokens`** (optional) — the estimated token size of the skill's SKILL.md
+  (a coarse `chars/4` proxy, not a model tokenizer), used for the **value-per-token**
+  axis: `delta` per 1k skill tokens. Method documented on the methodology page.
+- **Per-case `case_status`** (optional; default `"ok"`) — `"failed_timeout"` marks a
+  case whose model/judge call persistently timed out after retries. Such a case is
+  **recorded WITHOUT fabricated samples/hashes** and is **excluded from the
+  aggregates** — a band is never invented from a case that did not complete. When
+  any case failed, the run is stamped **`run.status: "incomplete"`** (+
+  `run.failed_case_count`), and a drift/durability report **must exclude an
+  incomplete receipt from verdicts** (listing it honestly as "not measured").
+- These are additive; a v0.3 or earlier receipt reads unchanged against its own
+  frozen schema.
 
 ## Design goals
 
@@ -60,7 +121,7 @@ fresh run, but older receipts are read unchanged against their own schema.
 
 ## Fields
 
-### `schema_version` (string, required) — `"0.3"`.
+### `schema_version` (string, required) — `"0.3.1"`.
 
 ### `skill` (object, required)
 | field | type | notes |
@@ -68,6 +129,7 @@ fresh run, but older receipts are read unchanged against their own schema.
 | `name` | string | From SKILL.md front-matter or its H1. |
 | `version` | string | Skill's declared version. |
 | `content_hash` | sha256 hex | Over `SKILL.md` + every bundled file (the `evals/` dir is **excluded** — hashed separately as `suite_hash`), path + content, path-sorted. |
+| `tokens` | integer | **v0.3.1, optional.** Estimated SKILL.md token size (coarse `chars/4` proxy) for the value-per-token axis. |
 
 ### `suite` (object, required)
 | field | type | notes |
@@ -81,7 +143,9 @@ fresh run, but older receipts are read unchanged against their own schema.
 |---|---|---|
 | `model_id` | string | Canonical model id run on. |
 | `model_release_date` | ISO date or `null` | Release date **if known**, else `null`. |
-| `surface` | `"api"` \| `"claude-cli"` | `api` = Messages API; `claude-cli` = spawned `claude -p` (subscription). |
+| `provider` | `"anthropic"` \| `"openai"` | **v0.3.1.** The two-axis provider (registry `provider`, else inferred from the id). |
+| `surface` | `"api"` \| `"claude-cli"` \| `"openai-api"` \| `"openai-cli"` | `api` = Anthropic Messages API; `claude-cli` = spawned `claude -p` (subscription); `openai-api` = Chat-Completions-compatible API (base_url configurable); `openai-cli` = Codex subscription (`codex exec`). |
+| `surface_overhead_note` | string | **v0.3.1, optional.** On `openai-cli`: the fixed Codex base-instruction preamble (~12–15k input tokens/call) the harness prepends and does not control. |
 | `runner_version` | string | Runner version, for reproducibility. |
 | `date_utc` | ISO 8601 UTC | When the run finished. |
 | `registry` | `"registered"` \| `"unregistered"` | **v0.3.** Whether `model_id` resolved in the model registry (`config/models.json`). |
@@ -111,6 +175,7 @@ receipt says so.
   | `score` | number 0–1 | Alias of `mean` (kept for v0.1 readers). |
   | `threshold` | number or `null` | The case's pass threshold (or `null`). |
   | `reason` | string | One-line judge rationale (optional). |
+  | `checks` | array | **v0.3.1, optional.** Deterministic post-check results, each `{ name, kind, pass }` (`kind ∈ regex/contains/not_contains/min_length`). Run alongside the judge; a **separate column**, **not** folded into `outcome`/the band verdict. |
   | `judge` | object | `{ model_id, rubric_hash }` — who graded and a hash binding the grade to the exact rubric + judge system prompt. |
 - **`aggregates`** — `{ with_skill, baseline }`, each
   `{ case_count, pass_count, borderline_count?, mean_score, stddev }`. Here

package/spec/receipt.schema.json

@@ -2,14 +2,59 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://driftproofhq.com/spec/receipt.schema.json",
   "title": "driftproof receipt",
-  "description": "A signed, dated record of running one agent skill's eval suite with and without the skill on one model version, with sampled judge scores and confidence bands. Receipt spec v0.3 — adds transcript auditability (per-sample sha256 hashes + optional transcript retention) and registry/pricing provenance.",
+  "description": "A signed, dated record of running one agent skill's eval suite with and without the skill on one model version, with sampled judge scores and confidence bands. Receipt spec v0.3.1 — additive over v0.3: adds run.provider (two-axis provider), expands the surface enum with the OpenAI lanes (openai-api, openai-cli), adds an optional run.surface_overhead_note (fixed harness preamble on the openai/cli surface), optional per-case deterministic post-check results, and an optional skill.tokens count for the value-per-token axis. Interop-additive revision: receipts IMPORTED from external tools (surface 'external', run.source 'imported/<tool>', verification_level DECLARED) may carry null content/suite/rubric hashes and omit generation hashes — hashes are never fabricated; the TESTED tightening (see allOf) requires the full evidence chain whenever verification_level is TESTED, so no previously issued receipt is invalidated and TESTED keeps its meaning.",
   "type": "object",
   "additionalProperties": false,
   "required": ["schema_version", "skill", "suite", "run", "results", "comparison", "verification_level", "receipt_hash"],
+  "allOf": [
+    {
+      "description": "TESTED tightening — the interop relaxations (null hashes, external surface, null comparison, transcripts 'none') are ONLY available to receipts below TESTED. A TESTED receipt must carry the full evidence chain, exactly as before the interop revision.",
+      "if": { "required": ["verification_level"], "properties": { "verification_level": { "const": "TESTED" } } },
+      "then": {
+        "properties": {
+          "skill": { "properties": { "content_hash": { "type": "string" } } },
+          "suite": {
+            "properties": {
+              "format": { "const": "agentskills.io/evals" },
+              "suite_hash": { "type": "string" }
+            }
+          },
+          "run": {
+            "properties": {
+              "surface": { "enum": ["api", "claude-cli", "openai-api", "openai-cli"] },
+              "transcripts": { "enum": ["retained-local", "hashes-only"] }
+            }
+          },
+          "comparison": {
+            "properties": {
+              "baseline_score": { "type": "number" },
+              "delta": { "type": "number" },
+              "delta_uncertainty": { "type": "number" }
+            }
+          },
+          "results": {
+            "properties": {
+              "cases": {
+                "items": {
+                  "if": { "not": { "required": ["case_status"], "properties": { "case_status": { "const": "failed_timeout" } } } },
+                  "then": {
+                    "required": ["generation_hash", "judge_sample_hashes"],
+                    "properties": {
+                      "judge": { "properties": { "rubric_hash": { "type": "string" } } }
+                    }
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+  ],
   "properties": {
     "schema_version": {
       "type": "string",
-      "const": "0.3"
+      "const": "0.3.1"
     },
     "skill": {
       "type": "object",
@@ -19,9 +64,14 @@
         "name": { "type": "string", "minLength": 1 },
         "version": { "type": "string", "minLength": 1 },
         "content_hash": {
-          "type": "string",
-          "description": "sha256 (hex) over SKILL.md + all bundled files in canonical path-sorted order.",
+          "type": ["string", "null"],
+          "description": "sha256 (hex) over SKILL.md + all bundled files in canonical path-sorted order. Null ONLY on an imported (DECLARED) receipt whose skill bytes were never seen; a TESTED receipt must carry the hash (see the TESTED tightening).",
           "pattern": "^[a-f0-9]{64}$"
+        },
+        "tokens": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "v0.3.1 (optional). Estimated token size of the skill's SKILL.md (a coarse chars/4 proxy, not a model tokenizer), used for the value-per-token axis (delta per 1k skill tokens). See docs/methodology.html."
         }
       }
     },
@@ -30,10 +80,14 @@
       "additionalProperties": false,
       "required": ["format", "suite_hash", "case_count"],
       "properties": {
-        "format": { "type": "string", "const": "agentskills.io/evals" },
-        "suite_hash": {
+        "format": {
           "type": "string",
-          "description": "sha256 (hex) over the canonicalized normalized case list.",
+          "minLength": 1,
+          "description": "Suite format. Driftproof-run (TESTED) receipts are always 'agentskills.io/evals' (see the TESTED tightening); an imported receipt names the source tool's format (e.g. 'skillgrade/eval.yaml')."
+        },
+        "suite_hash": {
+          "type": ["string", "null"],
+          "description": "sha256 (hex) over the canonicalized normalized case list. Null ONLY on an imported (DECLARED) receipt whose suite bytes were never seen.",
           "pattern": "^[a-f0-9]{64}$"
         },
         "case_count": { "type": "integer", "minimum": 0 }
@@ -42,7 +96,7 @@
     "run": {
       "type": "object",
       "additionalProperties": false,
-      "required": ["model_id", "surface", "runner_version", "date_utc", "judge", "registry", "transcripts"],
+      "required": ["model_id", "provider", "surface", "runner_version", "date_utc", "judge", "registry", "transcripts"],
       "properties": {
         "model_id": { "type": "string", "minLength": 1 },
         "model_release_date": {
@@ -50,7 +104,35 @@
           "type": ["string", "null"],
           "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
         },
-        "surface": { "type": "string", "enum": ["api", "claude-cli"] },
+        "provider": {
+          "type": "string",
+          "description": "v0.3.1. The two-axis provider the target model ran on (registry `provider`, else inferred from the id).",
+          "enum": ["anthropic", "openai"]
+        },
+        "surface": {
+          "type": "string",
+          "enum": ["api", "claude-cli", "openai-api", "openai-cli", "external"],
+          "description": "'external' = the run happened on another tool's harness and was imported (never valid on a TESTED receipt)."
+        },
+        "source": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Interop-additive (optional). Provenance of a converted receipt, e.g. 'imported/agent-skills-eval' or 'imported/skillgrade'. Absent on receipts Driftproof ran itself."
+        },
+        "surface_overhead_note": {
+          "type": "string",
+          "description": "v0.3.1 (optional). Present on the openai/cli surface: states the fixed Codex base-instruction preamble (~12–15k input tokens per call) that the harness prepends and does not control."
+        },
+        "status": {
+          "type": "string",
+          "description": "v0.3.1 (optional; default 'complete'). 'incomplete' when >=1 case persistently failed (e.g. failed_timeout) and was EXCLUDED from aggregates. A drift/durability report must not compute a verdict from an incomplete receipt.",
+          "enum": ["complete", "incomplete"]
+        },
+        "failed_case_count": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "v0.3.1 (optional). Number of cases marked failed_timeout (excluded from aggregates)."
+        },
         "runner_version": { "type": "string", "minLength": 1 },
         "date_utc": {
           "type": "string",
@@ -64,8 +146,8 @@
         },
         "transcripts": {
           "type": "string",
-          "description": "Transcript retention for this run. 'hashes-only' = only the sha256 hashes in results.cases are kept (the default). 'retained-local' = the raw generations + judge outputs were also written to transcripts/<receipt-id>/ (gitignored by default).",
-          "enum": ["retained-local", "hashes-only"]
+          "description": "Transcript retention for this run. 'hashes-only' = only the sha256 hashes in results.cases are kept (the default). 'retained-local' = the raw generations + judge outputs were also written to transcripts/<receipt-id>/ (gitignored by default). 'none' = nothing retained, not even hashes — ONLY honest on an imported (DECLARED) receipt.",
+          "enum": ["retained-local", "hashes-only", "none"]
         },
         "judge": {
           "type": "object",
@@ -82,7 +164,7 @@
               "type": "string",
               "description": "How sampling params were controlled, e.g. 'api-temperature-0' or 'surface-controlled'."
             },
-            "surface": { "type": "string", "enum": ["api", "claude-cli"] }
+            "surface": { "type": "string", "enum": ["api", "claude-cli", "openai-api", "openai-cli", "external"] }
           }
         }
       }
@@ -97,10 +179,23 @@
           "items": {
             "type": "object",
             "additionalProperties": false,
-            "required": ["id", "mode", "outcome", "score", "mean", "stddev", "samples", "judge", "generation_hash", "judge_sample_hashes"],
+            "required": ["id", "mode"],
+            "allOf": [
+              {
+                "description": "A completed case carries the full sampled band + hashes; a failed_timeout case is recorded WITHOUT fabricated samples (it is excluded from aggregates).",
+                "if": { "required": ["case_status"], "properties": { "case_status": { "const": "failed_timeout" } } },
+                "then": { "required": ["id", "mode", "case_status"] },
+                "else": { "required": ["outcome", "score", "mean", "stddev", "samples", "judge"] }
+              }
+            ],
             "properties": {
               "id": { "type": "string", "minLength": 1 },
               "mode": { "type": "string", "enum": ["with_skill", "baseline"] },
+              "case_status": {
+                "type": "string",
+                "description": "v0.3.1 (optional; default 'ok'). 'failed_timeout' = the case's model/judge call persistently timed out after retries; the case is recorded but EXCLUDED from aggregates/verdicts — no samples/hashes are fabricated for it.",
+                "enum": ["ok", "failed_timeout"]
+              },
               "outcome": {
                 "type": "string",
                 "description": "borderline = the threshold lies within mean +/- stddev.",
@@ -127,13 +222,31 @@
               },
               "threshold": { "type": ["number", "null"], "minimum": 0, "maximum": 1 },
               "reason": { "type": "string" },
+              "checks": {
+                "type": "array",
+                "description": "v0.3.1 (optional). Deterministic post-check results for this (case, mode): structural/regex assertions run on the model output ALONGSIDE the judge. Supplementary evidence reported as a separate column — NOT folded into the outcome/band verdict.",
+                "items": {
+                  "type": "object",
+                  "additionalProperties": false,
+                  "required": ["name", "kind", "pass"],
+                  "properties": {
+                    "name": { "type": "string", "minLength": 1 },
+                    "kind": { "type": "string", "enum": ["regex", "contains", "not_contains", "min_length"] },
+                    "pass": { "type": "boolean" }
+                  }
+                }
+              },
               "judge": {
                 "type": "object",
                 "additionalProperties": false,
                 "required": ["model_id", "rubric_hash"],
                 "properties": {
                   "model_id": { "type": "string", "minLength": 1 },
-                  "rubric_hash": { "type": "string", "pattern": "^[a-f0-9]{64}$" }
+                  "rubric_hash": {
+                    "type": ["string", "null"],
+                    "description": "Null ONLY on an imported (DECLARED) receipt whose rubric bytes were never seen.",
+                    "pattern": "^[a-f0-9]{64}$"
+                  }
                 }
               }
             }
@@ -156,12 +269,22 @@
       "required": ["with_skill_score", "baseline_score", "delta", "delta_uncertainty"],
       "properties": {
         "with_skill_score": { "type": "number", "minimum": 0, "maximum": 1 },
-        "baseline_score": { "type": "number", "minimum": 0, "maximum": 1 },
-        "delta": { "type": "number", "minimum": -1, "maximum": 1 },
+        "baseline_score": {
+          "type": ["number", "null"],
+          "minimum": 0,
+          "maximum": 1,
+          "description": "Null ONLY on an imported (DECLARED) receipt from a tool with no baseline mode — never a fabricated 0."
+        },
+        "delta": {
+          "type": ["number", "null"],
+          "minimum": -1,
+          "maximum": 1,
+          "description": "Null when baseline_score is null (no baseline mode was run)."
+        },
         "delta_uncertainty": {
-          "type": "number",
+          "type": ["number", "null"],
           "minimum": 0,
-          "description": "Combined uncertainty of the delta (quadrature sum of the two aggregate bands)."
+          "description": "Combined uncertainty of the delta (quadrature sum of the two aggregate bands). Null when delta is null."
         }
       }
     },