Skip to content

README.md

Latest commit

 

History

History
169 lines (130 loc) · 6.29 KB

README.md

File metadata and controls

169 lines (130 loc) · 6.29 KB
Raw

ExoWarrant Evidence/Receipt SDK v0.1

This SDK is the minimum cross-plugin handoff contract for scientific-tool observations. It standardizes exact evidence bytes, activity provenance, retained failures, negative results and claim references without allowing a producing plugin to authorize execution or self-assert scientific validity.

Authority boundary

Every conformant generic receipt is fixed to:

  • authority_scope: OBSERVATION_ONLY;
  • scientific_interpretation: NOT_ASSESSED;
  • attestation_scope: PRODUCER_ORIGIN_ONLY for evidence records.

A plugin, Agent, MCP server, service account or fixture may emit a record. Its presence, digest or signature does not make the issuer trusted and does not establish independence, scientific validity, laboratory performance or productivity improvement.

An SDK receipt is deliberately different from exowarrant.run-receipt.v1. The latter is accepted only after a locked study contract, profile preflight, named-human authorization, one-time authorization consumption, institution-pinned trust checks and endpoint-ledger validation. There is no automatic promotion path.

Artifact flow

upstream plugin evidence record(s)
              │
              ▼
downstream plugin operation
              │
              ├── output / log / metric evidence records
              ├── explicit negative-result records
              ├── explicit missing / redacted / not-produced records
              └── observation-only tool receipt
                              │
                              ▼
                    evidence bundle v1
                              │
             schema + digest + binding checks
                              │
                              ▼
             ExoWarrant evidence reference only
             (never automatic authorization/warrant)

The transport bundle contains all evidence records linked by one receipt. Unlinked records, duplicate evidence IDs, digest mismatches, cross-study binding, and outputs attributed to a different producing plugin fail closed.

Schemas

The normative JSON Schemas are installed with the ExoWarrant schema registry:

  • exowarrant.sdk.evidence-record.v1
  • exowarrant.sdk.tool-receipt.v1
  • exowarrant.sdk.evidence-bundle.v1

Unknown versions are refused. A schema change that alters meaning requires a new schema_version; consumers must never silently fall back to an older interpretation.

Evidence states

PRESENT requires an exact SHA-256 and media type. MISSING, REDACTED, and NOT_PRODUCED require an explicit reason and cannot carry a content digest. Only PRESENT evidence can be converted to the existing protocol evidence_ref shape.

Claims

Generic plugin receipts may reference a preregistered claim only as NOT_ASSESSED or NOT_APPLICABLE. Positive levels belong to a separate, policy-governed warrant assessment. This prevents downstream consumers that read only per-claim fields from mistaking an activity receipt for a scientific verdict.

Failure semantics

  • FAILED requires at least one severity ERROR.
  • PARTIAL requires a limitation, negative result or error.
  • STOPPED requires a limitation or error.
  • COMPLETED cannot contain severity ERROR.
  • Negative results cite retained records whose role is exactly NEGATIVE_RESULT.

Python reference

from pathlib import Path

from exowarrant import EvidenceReceiptSDK
from exowarrant.jsonutil import load_json_file

sdk = EvidenceReceiptSDK()
bundle = load_json_file(Path("evidence-bundle.v1.json"))

# Metadata conformance only. Payload bytes have not been checked.
report = sdk.validate_bundle(bundle)
assert report.status == "CONFORMANT_METADATA_ONLY"
assert report.scientific_validity == "NOT_ASSESSED"

# For exact-byte conformance, supply every PRESENT record by evidence_id.
report = sdk.validate_bundle(
    bundle,
    payloads={
        "evidence-input-001": Path("input.csv").read_bytes(),
        "evidence-output-001": Path("output.csv").read_bytes(),
    },
)
assert report.status == "CONFORMANT_WITH_PAYLOADS"

The builder requires the caller to supply IDs, timestamps, actors and evidence. It does not invent them:

bundle = sdk.build_bundle(
    bundle_id=bundle_id,
    emitted_at=emitted_at,
    evidence_records=records,
    receipt=receipt,
)

Read-only CLI validation:

exowarrant-sdk validate-bundle .\evidence-bundle.v1.json
exowarrant-sdk validate-bundle .\evidence-bundle.v1.json `
  --payload evidence-input-001=.\input.csv `
  --payload evidence-output-001=.\output.csv

TypeScript reference

The dependency-light TypeScript implementation is in sdk/typescript. It exports the artifact types, canonical JSON/SHA-256 helpers, evidence-link builder and bundle semantic validator. JSON Schema validation remains normative and should run before semantic checks.

Set-Location sdk\typescript
npm ci
npm test

Python and TypeScript must produce the same digest for the published valid bundle. The conformance test pins that cross-language vector.

Conformance fixtures

conformance-fixtures/valid/evidence-bundle.v1.json is the canonical transport vector. Its exact payloads are in conformance-fixtures/payloads. The expected bundle digest and negative mutation cases are recorded in conformance-fixtures/vectors.v1.json.

Passing these fixtures means only that an implementation conforms to the SDK contract. Synthetic actors, data and outputs in the fixtures are TEST_ONLY evidence and must not be reported as independent or scientific validation.

Plugin integration checklist

  1. Use a stable plugin_id, exact plugin version and bounded capability_id.
  2. Reuse the same binding across the receipt and every linked record.
  3. Use STUDY_BOUND only when an existing study ID and exact contract digest are known.
  4. Hash exact raw bytes; do not hash a normalized reconstruction of instrument/data files.
  5. Keep unknown container or environment digests explicitly null; never fabricate them.
  6. Retain errors, stopped operations, negative results, missing outputs and redactions.
  7. Treat signatures as unverified until an operator-pinned trust policy checks them.
  8. Hand the receipt to BioNexus or ExoWarrant as evidence input only; neither integration can bypass its own policy, authorization, trust or human-decision gates.