engineering-behavior-observatory 0.2.1

package/docs/evaluation/behavior-assertions.md

@@ -0,0 +1,45 @@
+# Behavior assertions and evidence resolution
+
+`ebo.behavior-assertion/v1` records one semantic assessment or abstention for
+one declared behavior dimension. The initial `ebo.behavior-vocabulary/v1` is a
+small data file at
+[`ontology/behavior-categories.v1.json`](../../ontology/behavior-categories.v1.json).
+Its eight entries are the categories in the canonical specification; unmapped
+observations do not force a new category.
+
+Each assertion binds the normalized-dataset schema version and canonical
+digest, run and attempt IDs, vocabulary version, one category/dimension pair,
+and evaluator/rubric identities. An assessment is constructive, adverse,
+mixed, or context-dependent and retains confidence on the explicit
+`evaluator-reported-0-to-1` scale, rationale, an alternative explanation, and
+at least one citation. Confidence is not a calibrated probability. An abstention instead retains its reason and
+may name the missing event or evidence capability; citations are optional.
+
+A citation names both a normalized event ID and that event's exact native
+source reference. `validateBehaviorAssertion` first applies the existing
+normalized-dataset integrity validator, then checks the dataset digest and
+assertion identity, declared dimension, event ownership, native reference, and
+resolver-provided run/attempt/digest. Changed datasets, foreign attempts,
+dangling events or native records, and stale digests fail closed.
+
+`ebo.behavior-review/v1` is a separate record bound to the assertion digest.
+Its states are `proposed`, `confirmed`, `disputed`, `rejected`, and
+`insufficient-evidence`. Proposed records cannot carry a reviewer; all other
+states require an explicitly identified human reviewer and rationale. The
+library derives confirmed aggregation eligibility only after revalidating the
+assertion against its dataset and native resolver, and then finding a valid
+`confirmed` review of a non-abstaining assertion. A judge assertion cannot set
+human confirmation itself.
+
+The callable validator accepts any `ebo.normalized-dataset/v1` and its
+source-specific native resolver. The current CLI rebuilds and validates the
+normalized dataset from a retained Claude Agent SDK, Codex, OpenHands, Pi, or
+DeepSeek run bundle through `validateRetainedBehaviorAssertion`:
+
+```sh
+ebo assertions validate <run-bundle-root> <assertion.json> [review.json]
+```
+
+This command validates contracts and evidence only. It does not run a judge,
+change review state, adjudicate a dispute, aggregate results, or build an
+Atlas.

package/docs/evaluation/human-calibration.md

@@ -0,0 +1,170 @@
+# Human calibration and adjudication
+
+EBO supplies a local, static workflow for people to review evidence-grounded
+behavior assertions. It does not assign reviewers, authenticate users, host a
+review service, or treat synthetic fixture decisions as research labels.
+
+## Select a reproducible sample
+
+Create a source file that points to capture-qualified Claude Agent SDK, Codex,
+OpenHands, DeepSeek, Pi, or Cursor bundles and
+their judge-produced assertions. Paths are local operator inputs; native
+evidence is revalidated through the existing assertion resolver before a
+candidate can enter a sample.
+
+```json
+{
+  "schemaVersion": "ebo.review-source-set/v1",
+  "sources": [
+    {
+      "bundleRoot": "/local/restricted/runs/run-1",
+      "assertionPath": "/local/restricted/judgments/run-1/assertion.json",
+      "taskContext": "Reviewable task prompt or bounded operator-authored task synopsis."
+    }
+  ]
+}
+```
+
+Sampling criteria use explicit, non-overlapping strata. Each stratum has its
+own requested size and may filter by task, model, harness, verifier outcome,
+terminal state, behavior category, confidence, or judge abstention. A single
+stratum with empty filters is an unstratified sample.
+
+```json
+{
+  "schemaVersion": "ebo.review-sample-criteria/v1",
+  "seed": "study-2026-09-wave-1",
+  "strata": [
+    {
+      "id": "high-confidence-verification",
+      "sampleSize": 20,
+      "filters": {
+        "categoryIds": ["verification-completion"],
+        "confidence": { "min": 0.75 },
+        "abstentions": [false]
+      }
+    },
+    {
+      "id": "judge-abstentions",
+      "sampleSize": 10,
+      "filters": { "abstentions": [true] }
+    }
+  ]
+}
+```
+
+```sh
+ebo calibration sample sources.json criteria.json selection.json
+```
+
+The saved selection retains the criteria and seed, every source root, source and
+eligible population sizes, eligible and selected assertion IDs, per-stratum requested,
+eligible, and selected counts, and any zero-candidate strata. Ordering is a
+SHA-256 function of the seed, stratum, assertion ID, and assertion digest.
+Repeated request-derived assertion IDs across runs remain distinct through
+their digest-bound identity. Where a CLI selector is ambiguous, append the
+digest as `<assertion-id>@sha256:<digest>`.
+Every command that reuses a saved selection deterministically revalidates its
+criteria, eligible population, strata, seeded ordering, and candidate bindings
+against the retained source evidence.
+Observational runs always record verifier outcome as `unavailable`; normal
+completion is never substituted for verifier success.
+
+## Generate and inspect a static packet
+
+```sh
+ebo calibration packet selection.json review-packet
+open review-packet/index.html
+ebo calibration inspect \
+  review-packet/packet.json <assertion-id> [event-id]
+```
+
+`index.html` contains the supplied task context, condition context, assertion,
+rationale, alternative explanation, and links to local pages that render the
+exact cited native records. Each evidence page also links to its source artifact
+and names the native locator. All task, assertion, and evidence content is
+HTML-escaped. Links remain relative to the packet and its declared local bundle
+root. The packet copies only cited records, keeps them `restricted-local-only`
+with mode `0600`, and keeps those heavyweight records out of `packet.json`.
+It is not a partner or public export. Moving the packet
+separately from its source bundles breaks the original-artifact links by design.
+Packet files are staged together and the completed directory is published in
+one rename, so `packet.json` never names partially rendered evidence pages.
+All selection, packet, history, and summary destinations are rejected when they
+would be written inside a source run bundle.
+
+## Import human decisions
+
+Get the exact assertion and current history bindings without manufacturing a
+decision:
+
+```sh
+ebo calibration binding selection.json <assertion-id>
+ebo calibration binding selection.json <assertion-id> history.json
+```
+
+A person supplies the reviewer identity, timestamp, decision, and rationale.
+`insufficient-evidence` is the human abstention state. The first decision uses
+`previousHistory: null`; later decisions use the binding printed for the
+current history.
+
+```json
+{
+  "schemaVersion": "ebo.human-review-decision/v1",
+  "id": "review-001",
+  "kind": "review",
+  "assertion": {
+    "id": "<assertion-id>",
+    "schemaVersion": "ebo.behavior-assertion/v1",
+    "digest": "sha256:<assertion-digest>"
+  },
+  "reviewer": { "kind": "human", "id": "<reviewer-id>" },
+  "decidedAt": "2026-09-07T12:00:00Z",
+  "state": "confirmed",
+  "rationale": "<human-authored rationale>",
+  "previousHistory": null
+}
+```
+
+```sh
+ebo calibration import selection.json history.json decision.json
+```
+
+Import appends to one history and never rewrites an earlier decision. It rejects
+unknown or changed assertions, stale history bindings, invalid adjudication
+targets, and reuse of a decision ID with different content. Reimporting the
+exact same decision is idempotent.
+Imports serialize through a per-history portable filesystem lock with a stale
+timeout and heartbeat. Interrupted imports are recovered automatically; an
+active import makes a concurrent command fail closed for an idempotent retry.
+
+An adjudication is another explicit human decision. It names at least two prior
+review decisions for the same assertion:
+
+```sh
+ebo calibration adjudicate \
+  selection.json history.json adjudication.json
+```
+
+Its JSON uses `kind: "adjudication"` and an `adjudicates` array of prior review
+decision IDs. This records lineage; it does not infer or automate adjudication.
+
+## Summarize calibration
+
+```sh
+ebo calibration summarize \
+  selection.json history.json calibration-summary.json
+```
+
+The summary reports totals and category-level counts. Judge-human agreement is
+over latest judge-human decision pairs on non-abstaining assertions.
+Human-human agreement is over distinct-reviewer pairs on the same assertion,
+excluding human abstentions. Adjudication counts use human adjudication
+decisions as their separate denominator. Every agreement result names its
+population and denominator; with no comparable reviews it is `unavailable`
+with denominator zero, never perfect agreement. Disputed, inconsistent,
+unreviewed, insufficient-evidence, and judge-abstained assertions are excluded
+from confirmed eligibility. A review appended after adjudication makes that
+adjudication non-current until the updated review population is adjudicated.
+These are calibration summaries, not comparison
+or Behavior Atlas aggregates.

package/docs/evaluation/normalization-integrity.md

@@ -0,0 +1,80 @@
+# Normalization integrity and comparison gates
+
+Normalization is accepted only when every projected event remains bound to one
+capture-qualified run and attempt. The native record stays authoritative; the
+normalized dataset retains only its source reference, native type, and digest.
+
+## Dataset validation and coverage
+
+`describeNormalizedDataset` combines a qualified capture, its normalization
+result, the adapter capability profile, and the pinned adapter version into an
+`ebo.normalized-dataset/v1` record. Source and content references retain
+separate expected digests without copying native records. It rejects input that
+is not explicitly `qualified` or `qualified-with-gaps`.
+`validateNormalizedDataset` then checks:
+
+- the dataset, event, and capability-profile schemas;
+- stable run, attempt, adapter, harness, and native-type identity;
+- resolver-provided run/attempt ownership and every source/content digest;
+- source and content references, event relations, and acyclic parentage;
+- nondecreasing order within each native order domain;
+- that every native record is mapped or explicitly retained as unmapped; and
+- that emitted families and evidence do not contradict adapter capabilities.
+
+The resolver must return `{ runId, attemptId, digest }` for every source and
+content reference. A boolean resolver remains supported by the lower-level
+uniform event validator, but it is insufficient for dataset integrity
+validation. The dataset validator rejects resolution metadata owned by another
+run or attempt.
+`createCapturedNativeEvidenceResolver` supplies the stronger metadata for an
+in-memory qualified capture and can delegate other content references to an
+adapter-specific resolver. Derived JSON Pointer locators are resolved against
+the source record; the helper never treats a containing record as proof that an
+arbitrary child locator exists.
+
+Successful validation returns an `ebo.adapter-coverage-report/v1` report. It
+counts mapped and unmapped native records by adapter version and native type.
+For each uniform family it reports both the declared capability status and the
+observed event count. Consequently, an unsupported family with zero events is
+not confused with an available family that happened to have zero observations.
+Unknown source records remain present in the native-type table and in the
+dataset's `unmapped` list.
+
+DeepSeek JSON-RPC methods and OpenHands REST/WebSocket record kinds remain
+native types in these reports. They do not create event families or imply a
+shared control protocol.
+
+## Comparison eligibility
+
+The comparison gate consumes one explicit `ebo.comparison-request/v1` or
+`ebo.comparison-request/v2` artifact. V2 additionally retains the exact measure
+and candidate manifest digests required by aggregation:
+
+```sh
+ebo comparison check <request.json>
+```
+
+The request names both candidates, their task and fixture digests, model and
+harness configuration identities, material capture/budget/tool-policy digests,
+normalization-adapter identities and pinned versions, capability profiles, required capabilities,
+and any declared model or harness difference. The command prints an
+matching versioned `ebo.comparison-report/v1` or
+`ebo.comparison-report/v2` JSON object and
+returns nonzero when its status is `unsupported`.
+
+Statuses are:
+
+- `supported`: conditions match and required capabilities are available;
+- `qualified-with-caveats`: a model/harness difference was declared or a
+  required capability is partial; and
+- `unsupported`: task, fixture, material configuration, or undeclared
+  model/harness conditions differ, or a required capability is unsupported.
+
+Declaring a model or harness difference makes that difference inspectable; it
+does not claim identical conditions or establish that the harness caused an
+observed behavioral difference.
+
+The schema is
+[`schemas/normalization-integrity.v1.json`](../../schemas/normalization-integrity.v1.json).
+Exact-match and incompatible-fixture examples live under
+`test/fixtures/comparison` in the source repository.

package/docs/evaluation/semantic-judge.md

@@ -0,0 +1,188 @@
+# Evidence-grounded semantic judge
+
+`ebo judge run` evaluates one declared behavior dimension against a bounded,
+caller-selected projection of a qualified Claude Agent SDK, Codex, OpenHands, Pi,
+Cursor, or DeepSeek retained run bundle and an
+`ebo.structural-observation-set/v1` file:
+
+```sh
+ebo judge run \
+  <run-bundle-root> <observations.json> <request.json> <output-root>
+```
+
+The output root must not exist and must be outside the immutable run bundle.
+Every rerun therefore creates a new record. Runs with the same rubric,
+selection, limits, and evidence share an input digest even when their output
+roots or judge identities differ.
+
+## Request
+
+The request is caller-owned configuration; EBO does not select a study model
+or retry a judgment:
+
+```json
+{
+  "schemaVersion": "ebo.semantic-judge-request/v1",
+  "id": "verification-run-001",
+  "behavior": {
+    "vocabularyVersion": "1.0.0",
+    "categoryId": "verification-completion",
+    "dimensionId": "verification-completion"
+  },
+  "rubric": {
+    "id": "verification-rubric",
+    "version": "1.0.0",
+    "instructions": "Assess whether retained evidence shows validation before completion."
+  },
+  "evaluator": {
+    "provider": "anthropic",
+    "model": "<existing authenticated Claude Agent SDK route>",
+    "effort": "low"
+  },
+  "selection": {
+    "eventIds": ["<normalized-event-id>"],
+    "structuralObservationIds": ["<structural-observation-id>"],
+    "includeOutcomeObservations": true
+  },
+  "limits": {
+    "maxEvidenceItems": 16,
+    "maxRecordChars": 4096,
+    "maxInputChars": 64000,
+    "maxOutputChars": 8192,
+    "maxCitations": 8,
+    "maxWallClockMs": 30000,
+    "maxTurns": 1,
+    "maxBudgetUsd": 0.1
+  },
+  "blinding": { "evaluatedModelIdentity": "redact" }
+}
+```
+
+Selection is exact. Unknown IDs fail before execution. Optional outcome
+observations are added only when requested, and the total must remain within
+`maxEvidenceItems`. Per-record truncation and whole-input omission are recorded
+in `input.json`; omitted event IDs cannot be cited. Exact evaluated-model
+strings are redacted from evidence values and keys when requested. Citation
+IDs and native references are never rewritten, and the input records the
+remaining harness, native-type, behavioral, and citation clues that may still
+reveal origin.
+
+Selected structural observations automatically include their normalized source
+events so their claims remain citable. An explicitly selected observation with
+no normalized source event, including an exact zero fact, is rejected before
+execution; the same kind of automatically included outcome is recorded as
+omitted instead of being shown to the judge as uncitable support.
+
+## Backend and trust boundary
+
+The default backend is the installed TypeScript Claude Agent SDK. The caller
+supplies model, effort, wall-clock, turn, output, citation, and optional cost
+limits. The runner passes no tools, settings sources, skills, plugins, MCP
+servers, additional directories, or persistent session. It uses an empty
+temporary working directory, strict empty MCP configuration, `dontAsk`
+permissions, and a custom system prompt that treats the delimited trajectory
+payload as untrusted data rather than instructions.
+
+The SDK subprocess inherits the parent environment for authentication and
+routing, but EBO removes ambient model and effort override variables before
+launch so the caller request remains authoritative. The retained evaluator
+metadata records that policy without retaining secret values.
+Ambient OpenTelemetry and Claude telemetry/tracing controls are also removed;
+restricted rubric and trajectory content is never sent to a parent-configured
+collector, and a console exporter cannot corrupt the SDK protocol channel.
+
+For the native Codex backend, set `evaluator.backend` to `codex-app-server`,
+`provider` to `openai`, and supply `model` and `effort`. The optional
+`executable` selects the installed `codex` executable (default: PATH). Relative
+paths resolve against the caller's working directory before isolation; its version
+must be `0.153.4`. Set `maxTurns` to `1` and omit `maxBudgetUsd`: this backend
+does not support USD budget enforcement. No automatic provider fallback occurs.
+Backend selection is independent of the evaluated harness.
+Both request and retained judgment validation enforce backend-specific provider,
+effort, limits and environment-policy combinations. A qualified partial Codex
+capture can be evaluated without a turn identity when no turn was accepted;
+missing turn events stay unavailable and the judge can abstain.
+The selected model must exist in the pinned executable's bundled catalog.
+EBO copies that exact entry into a temporary catalog with apply-patch and
+experimental tool declarations removed; its digest is retained with the raw
+runtime response. Unknown catalog models fail before a turn starts.
+
+Codex owns a fresh stdio app-server child with an empty working directory and
+temporary HOME/CODEX_HOME. Only an existing `auth.json` login is copied into it;
+personal settings, plugins, MCP, hooks, memories, shell, browser, image,
+delegation, plan, sleep, and interactive tools are disabled. Thread and turn
+environment selections are explicitly empty, and host skill discovery is
+disabled. The child environment
+allows only PATH, locale, and temporary-directory variables. Analytics and
+telemetry exporters are disabled. The thread is ephemeral with no instruction
+sources, read-only sandbox and no sandbox network access; supplied evidence
+enters only through the prompt. Unexpected tool requests fail the judgment.
+Timeouts interrupt the owned turn and reap the process group before deleting
+the temporary home. Missing cost/API timing remains unavailable.
+`runRetainedSemanticJudge` also accepts an optional `signal`; CLI SIGINT and
+SIGTERM propagate through it to either backend. Interrupted calls retain a
+failed record and bounded received output. Timeout and interruption take
+precedence over a late successful terminal message; native startup probes
+consume the same wall-clock budget as the turn.
+
+The native structured response uses `turn/start.outputSchema` and completion
+must match both owned thread and turn IDs. See the
+[official app-server contract](https://developers.openai.com/codex/app-server/).
+New assertions carry optional `evaluator.configurationDigest`, binding the
+prompt version, rubric instructions, evaluator parameters, limits and blinding.
+Evaluator defaults are made explicit before hashing: omitted and explicit
+Claude backend defaults match, as do omitted/explicit native `codex`
+executables and equivalent relative/absolute executable paths. Model or effort
+changes still produce distinct configuration digests.
+Existing v1 requests and assertions remain readable without rewriting them.
+
+The response can contain only an assessed proposal or an abstention. Assessed
+responses require confidence, rationale, an alternative explanation, and at
+least one packaged citation. Abstentions require a reason, rationale, and
+alternative explanation and may cite packaged events. Extra fields such as a
+claimed `confirmed` review state are rejected. The runner constructs trusted
+run, attempt, dataset, rubric, behavior, and evaluator bindings itself, then
+calls `validateBehaviorAssertion`; fabricated, stale, foreign, digest-mismatched,
+or ownership-invalid citations cannot produce a proposed assertion.
+
+## Retention
+
+Raw input and output files are mode `0600` and marked `restricted`. A valid
+response writes `input.json`, `raw-response.json`, `assertion.json`, and
+`judgment.json`. Malformed responses, invalid citations, provider errors, and
+timeouts instead write `failure.json` beside any bounded raw output. No failed
+record enters review, no retry occurs, and native evidence is never changed.
+Timing, cost, and usage are recorded only when the backend reports them;
+otherwise the record says they are unavailable.
+Native Codex records name the replacement environment policy and its exact
+allowlist. Model output, including partial deltas and malformed final text,
+is retained separately in restricted `raw-model-response.json` and referenced
+by optional `rawModelResponse`. It and control-frame `raw-response.json` each
+have their own `maxOutputChars` bound; startup or user-echo frames cannot
+consume the model-output retention budget.
+
+`ebo.semantic-judge-request/v1`, `ebo.semantic-judge-input/v1`, and
+`ebo.semantic-judgment/v1` are registered artifacts and can be independently
+checked with `ebo validate`.
+
+This runner does not confirm assertions, create human reviews, adjudicate,
+aggregate rates, build an Atlas, or publish evidence.
+
+The opt-in live wiring test requires an already authenticated route discovered
+by the operator; it never invents a model ID:
+
+```sh
+EBO_LIVE_SEMANTIC_JUDGE_SMOKE=1 \
+EBO_LIVE_SEMANTIC_JUDGE_MODEL='<existing-route>' \
+node --test --test-name-pattern='approved live semantic judge smoke' \
+  dist/test/semantic-judge.test.js
+```
+
+The optional installed-runtime contract test intercepts a synthetic local
+model request, uses a dummy credential, and verifies an empty tool list:
+
+```sh
+EBO_NATIVE_CODEX_CONTRACT=1 node --test dist/test/codex-judge.test.js
+EBO_LIVE_CODEX_JUDGE_SMOKE=1 EBO_LIVE_CODEX_JUDGE_MODEL='<existing-route>' \
+  node --test --test-name-pattern='approved existing-auth' dist/test/codex-judge.test.js
+```

package/docs/evaluation/structural-observations.md

@@ -0,0 +1,84 @@
+# Outcome ingestion and structural observations
+
+Retained native loading accepts the implemented source versions: OpenHands
+1.44.1/1.46.0, DeepSeek SDK 0.1.1-rc.2, and Codex 0.150.1/0.153.4. Unsupported versions
+fail explicitly rather than receiving a different adapter's provenance.
+Completed Codex bundles require exactly one matching owned native terminal to
+report completion; duplicate owned terminals reject. Qualified failed/partial
+evidence remains separate.
+Native envelopes and physical JSONL sequences are checked before dispatch;
+Codex notifications from a foreign or client-only source cannot become events.
+Codex start ownership requires unique ordered client-request/server-response
+pairs with the same JSON-RPC ID; turn requests must name the owned thread and
+completion must follow acceptance. OpenHands
+capture requires exactly one server-info record, and its version and
+conversation records must agree with the manifest; completed
+runs require one owned final conversation with `execution_status: finished`.
+DeepSeek requires the root prompt receipt and native parent/child links for
+related sessions, and runtime reap must follow root idle. A coarse related-session list alone cannot authorize foreign
+records, and the retained composition must match the pinned client version.
+Verifier task failures also require normal native completion; infrastructure
+failures and interruptions can retain qualified partial evidence instead.
+
+`ebo observations` derives versioned, deterministic facts from a
+capture-qualified retained Claude Agent SDK, Codex, OpenHands, DeepSeek, Pi, or Cursor run bundle. It runs qualification,
+normalization, native-reference integrity validation, and the registered
+extractors in that order. Source bundles are read-only; the command rejects an
+output path inside the source bundle or corpus.
+
+```sh
+ebo observations create <run-bundle-root> <output.json>
+ebo observations corpus <corpus-root> <index.jsonl> <output-root> \
+  [--run <id>] [--attempt <id>] [--task <id>] [--model <id>] [--harness <id>] \
+  [--assessment-mode <observational|verified>]
+```
+
+The corpus command first validates the supplied deterministic index, selects
+run manifests with the same exact-match filters as `ebo corpus query`, and
+writes one bounded `sha256-<run-attempt-tuple>.json` file per selection. It fails rather than skipping
+an invalid or unsupported selected bundle. `createRetainedBehaviorEvidence`
+dispatches verified native session records to each source-specific normalizer and
+resolver. `createRetainedStructuralObservationSet` is the corresponding public
+library call; the older Agent SDK-specific calls remain available. The same
+loader supplies judge input, assertion validation, calibration, and aggregation.
+Unsupported source fields remain unavailable; native schemas and identities
+are preserved. Supplemental bundle metadata is retained separately as
+`outcomeCapture`, so it cannot replace source-native session records.
+OpenHands datasets retain their captured runtime version (`1.44.1` or `1.46.0`).
+DeepSeek reapplies its native composition, capability, initialization, prompt,
+and completed receipt-to-idle/runtime-reap gate before normalization; qualified
+partial captures remain qualified-with-gaps. Physical JSONL locators stay
+unchanged, and normalization qualification cannot exceed either the structural
+bundle gate or the source-specific gate.
+
+Each `ebo.structural-observation/v1` states its extractor/version, exact
+definition, one-attempt denominator, unit, uniform event IDs, native-record
+count, and native citations. `ebo.structural-observation-set/v1` also binds the observations to
+the normalized-dataset digest and adapter coverage report.
+
+Definitions are deliberately mechanical:
+
+- logical tool operations are grouped only by explicit source-native operation
+  IDs; lifecycle records without one are counted separately;
+- repetition counts distinct operations beyond the first that share the same
+  explicit tool identity and native-input digest;
+- failure-followed-by-operation compares only explicit failures and later
+  operation starts in the same native-order domain, split into same-tool and
+  alternate-tool counts; it does not claim recovery;
+- validation-after-mutation requires explicit mutation records and validation
+  records in one native-order domain; tool names are never used to infer either;
+- model requests require model-request events and native request identities;
+  assistant messages and model reroutes are not requests;
+- cumulative resource snapshots select only the latest snapshot in one known
+  native-order domain, increments are summed only when every record declares
+  increment semantics, and a cumulative-final record is used directly;
+- native token categories stay separate, native total tokens are never rebuilt
+  from components, and cost does not imply subscription utilization;
+- compaction counts include only native records that explicitly identify a
+  compaction boundary.
+
+An observed zero is emitted only with available family coverage. Partial or
+unsupported capability, ambiguous identity, unknown order, overlapping usage,
+or missing timing remains `unavailable` with a reason. Observational runs have
+no verifier assertion records and make no task-pass claim. Verified runs retain
+each assertion outcome with its native verifier citation.