bioai-evidence-validator 0.4.1__py3-none-any.whl → 0.5.0__py3-none-any.whl

{bioai_evidence_validator-0.4.1.dist-info → bioai_evidence_validator-0.5.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: bioai-evidence-validator
-Version: 0.4.1
+Version: 0.5.0
 Summary: Standards-aligned evidence policy validation for AI-assisted biological curation
 Project-URL: Homepage, https://github.com/NingyuSUN/bioai-evidence-validator
 Project-URL: Documentation, https://github.com/NingyuSUN/bioai-evidence-validator/tree/main/docs
@@ -34,6 +34,7 @@ Description-Content-Type: text/markdown
 [![PyPI](https://img.shields.io/pypi/v/bioai-evidence-validator)](https://pypi.org/project/bioai-evidence-validator/)
 [![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue)](https://github.com/NingyuSUN/bioai-evidence-validator/blob/main/pyproject.toml)
 [![License: Apache-2.0](https://img.shields.io/badge/license-Apache--2.0-blue)](https://github.com/NingyuSUN/bioai-evidence-validator/blob/main/LICENSE)
+[![Open in Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/NingyuSUN/bioai-evidence-validator/blob/main/examples/quickstart.ipynb)
 
 **Stop AI-extracted biological claims from entering your knowledge base or
 training set before their evidence is good enough for that use.**
@@ -49,6 +50,9 @@ each requested use.
 pip install bioai-evidence-validator
 ```
 
+Or try it in the browser, nothing to install:
+[quickstart notebook on Colab](https://colab.research.google.com/github/NingyuSUN/bioai-evidence-validator/blob/main/examples/quickstart.ipynb).
+
 ## 30-second example
 
 The two records below are identical except for one field: how the supporting
@@ -105,13 +109,45 @@ injected faults; the full validator admitted **0/160**.
 
 ## Use it
 
+### Write a draft, not a full record
+
+A full record spells out identifiers, evidence lines and hashes. A draft states each fact
+once; `bioevidence build` derives the rest and hashes local source files:
+
+```yaml
+profile: literature-claim
+uses: [research_summary]
+statement:
+  subject: {id: "SYN:GENE_A", label: Synthetic gene A, type: gene}
+  predicate: associated_with
+  object: {id: "SYN:PHENOTYPE_A", label: Synthetic phenotype A, type: phenotype}
+  scope: ["taxon:synthetic"]
+sources:
+  - {id: paper, title: Synthetic paper, type: publication, version: v1,
+     retrieved_at: "2026-09-21T00:00:00Z", file: synthetic_paper.txt}
+evidence:
+  - {source: paper, locator: Table 2, type: publication_result,
+     method: llm_extraction, scope: ["taxon:synthetic"]}
+```
+
+```bash
+bioevidence build examples/drafts/llm_claim.yaml --output record.json
+bioevidence validate record.json --profile literature-claim    # exit 2: review required
+```
+
+Building never fills in scope, extraction method, retrieval time or review decisions for
+you. For LLM pipelines, `bioevidence draft-schema --profile literature-claim` prints a JSON
+Schema for structured output. See the [draft format](https://github.com/NingyuSUN/bioai-evidence-validator/blob/main/docs/DRAFTS.md).
+
 ### Command line
 
 ```bash
 bioevidence profiles                                   # list built-in profiles and their use contracts
+bioevidence build draft.yaml --output record.json       # expand a compact draft
 bioevidence validate record.json --profile literature-claim
 bioevidence validate record.json --profile my_profile.yaml --output report.json
-bioevidence generate-schema --output record.schema.json  # JSON Schema for the input format
+bioevidence draft-schema --profile literature-claim     # JSON Schema for drafts (e.g. LLM output)
+bioevidence generate-schema --output record.schema.json  # JSON Schema for full records
 ```
 
 Exit codes: **0** admitted, **1** rejected, **2** review required, **3** input or configuration error.
@@ -119,12 +155,9 @@ Exit codes: **0** admitted, **1** rejected, **2** review required, **3** input o
 ### Python
 
 ```python
-import json
-from pathlib import Path
-
-from bioevidence_validator.engine import validate_record
+from bioevidence_validator import build_record, load_draft, validate_record
 
-record = json.loads(Path("record.json").read_text(encoding="utf-8"))
+record = build_record(load_draft("draft.yaml"), base_dir=".")   # or load a full record JSON
 report = validate_record(record, profile="literature-claim")
 
 for decision in report["use_decisions"]:
@@ -133,6 +166,30 @@ for decision in report["use_decisions"]:
 
 `profile` accepts a built-in name or a path to your own YAML profile.
 
+### Check records in CI
+
+Validate every record or draft in a pull request, with a summary table and inline annotations:
+
+```yaml
+# .github/workflows/evidence.yml
+on: pull_request
+jobs:
+  evidence:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: NingyuSUN/bioai-evidence-validator@v0.5.0
+        with:
+          files: records/**/*.yaml        # whitespace-separated globs
+          format: draft                   # or: record (default)
+          profile: literature-claim       # built-in name or path to your profile YAML
+          fail-on: review                 # or: rejected
+```
+
+With `fail-on: review` (default) the job fails unless every file is admitted; with
+`fail-on: rejected` it fails only on rejected files or files that cannot be read. The
+action's outputs `admitted`, `review_required`, `rejected` and `error` hold the counts.
+
 ## How it works
 
 ```mermaid
@@ -222,7 +279,7 @@ projection. External source truth and cohort independence require upstream verif
 
 ## Versions and branches
 
-`main` is the domain-neutral framework (0.4.1). The complete canine implementation
+`main` is the domain-neutral framework (0.5.0). The complete canine implementation
 and SQLite adapter from 0.3 live on the
 [`canine-breed` branch](https://github.com/NingyuSUN/bioai-evidence-validator/tree/canine-breed);
 see the [0.4 migration guide](https://github.com/NingyuSUN/bioai-evidence-validator/blob/main/docs/MIGRATION-0.4.md) and
@@ -235,6 +292,7 @@ If you use this toolkit in research, please cite it using the metadata in
 (GitHub's "Cite this repository" button generates APA and BibTeX).
 
 [Create a profile](https://github.com/NingyuSUN/bioai-evidence-validator/blob/main/docs/PROFILES.md) ·
+[Draft format](https://github.com/NingyuSUN/bioai-evidence-validator/blob/main/docs/DRAFTS.md) ·
 [Engineering contract](https://github.com/NingyuSUN/bioai-evidence-validator/blob/main/docs/ENGINEERING.md) ·
 [Design case study](https://github.com/NingyuSUN/bioai-evidence-validator/blob/main/docs/CASE_STUDY.md) ·
 [Architecture decision](https://github.com/NingyuSUN/bioai-evidence-validator/blob/main/docs/ADR-002-domain-neutral-main.md) ·

{bioai_evidence_validator-0.4.1.dist-info → bioai_evidence_validator-0.5.0.dist-info}/RECORD

@@ -1,13 +1,14 @@
-bioevidence_validator/__init__.py,sha256=w-OLV_MserELKh9U9FrLM8ZICJqNoWNOlqMwglL1lIk,87
-bioevidence_validator/cli.py,sha256=fknYldtjN50OvguGMcp_kmAky5PxZ0i5WRUF4HEQVkA,4326
+bioevidence_validator/__init__.py,sha256=O0lprvrrJN270yZxpMRi7jF6CTawvgc-f36QbAm0HgU,312
+bioevidence_validator/cli.py,sha256=50z5Aj6y6L3L9bwI_KZLMMYvtNHpWfwWY2O_XXGNVNI,5442
 bioevidence_validator/config.py,sha256=Ahc9eRPNR_ArqnbnJkdZsPFq9yERTYied0oGwUkANYI,1110
+bioevidence_validator/draft.py,sha256=8m5Yh68advpWrDb3m6ivkWa0Cq2SEM8CCbevBqXoRec,13552
 bioevidence_validator/engine.py,sha256=fm1gIOySsLiBbI3SklbEStiMD93RrhR3lA0vqdLJJXQ,15003
 bioevidence_validator/profiles/dataset-label.yaml,sha256=4utz9YcFFF2UnaLjIb0ATb-27hF8Smw7zmv0sBTaQdM,843
 bioevidence_validator/profiles/general.yaml,sha256=i9fJCWovJZ2e2d4rbn0Bx7mrhumNb2zjS9TOarkBWZw,778
 bioevidence_validator/profiles/literature-claim.yaml,sha256=7l82gX3oGGyYFq9B29-1qGXeL4LRcMhJi8Y9fieVE0c,612
 bioevidence_validator/schema/bioevidence_core.yaml,sha256=18MMngua0jlu4VnAbpb7SfI3numnCdjO986bZP6-Xn4,6700
-bioai_evidence_validator-0.4.1.dist-info/METADATA,sha256=JkN3mmJrD-cx86fBjdrjrTaxadrM1SdzbTrtHv81uO0,12563
-bioai_evidence_validator-0.4.1.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
-bioai_evidence_validator-0.4.1.dist-info/entry_points.txt,sha256=6oufzT2x1nIhTqM5B6y4aWubExKAoFb_wXXTdz3mBQQ,63
-bioai_evidence_validator-0.4.1.dist-info/licenses/LICENSE,sha256=z8d0m5b2O9McPEK1xHG_dWgUBT6EfBDz6wA0F7xSPTA,11358
-bioai_evidence_validator-0.4.1.dist-info/RECORD,,
+bioai_evidence_validator-0.5.0.dist-info/METADATA,sha256=1gG5J1j0CxRTbQJDYGBYz7vhMMzqqy7K_uqLE6cQ9ds,15360
+bioai_evidence_validator-0.5.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+bioai_evidence_validator-0.5.0.dist-info/entry_points.txt,sha256=6oufzT2x1nIhTqM5B6y4aWubExKAoFb_wXXTdz3mBQQ,63
+bioai_evidence_validator-0.5.0.dist-info/licenses/LICENSE,sha256=z8d0m5b2O9McPEK1xHG_dWgUBT6EfBDz6wA0F7xSPTA,11358
+bioai_evidence_validator-0.5.0.dist-info/RECORD,,

bioevidence_validator/__init__.py

@@ -1,3 +1,8 @@
 """Evidence validation primitives and domain policy runners."""
 
-__version__ = "0.4.1"
+__version__ = "0.5.0"
+
+from .draft import build_record, draft_json_schema, load_draft  # noqa: E402
+from .engine import validate_record  # noqa: E402
+
+__all__ = ["__version__", "build_record", "draft_json_schema", "load_draft", "validate_record"]

bioevidence_validator/cli.py

@@ -9,6 +9,7 @@ from pathlib import Path
 
 import yaml
 
+from .draft import build_record, draft_json_schema, load_draft
 from .engine import default_schema_path, generate_json_schema, validate_record, profile_path, list_profiles
 
 
@@ -20,6 +21,12 @@ def parser() -> argparse.ArgumentParser:
     validate.add_argument("--output", type=Path)
     validate.add_argument("--schema", type=Path, default=default_schema_path())
     validate.add_argument("--profile", default="general", help="Built-in profile name or YAML file path")
+    build = commands.add_parser("build", help="Expand a compact YAML/JSON draft into a full record")
+    build.add_argument("draft", type=Path)
+    build.add_argument("--output", type=Path)
+    draft_schema = commands.add_parser("draft-schema", help="JSON Schema for drafts under one profile")
+    draft_schema.add_argument("--profile", default="general", help="Built-in profile name or YAML file path")
+    draft_schema.add_argument("--output", type=Path)
     generate = commands.add_parser("generate-schema", help="Generate JSON Schema from LinkML")
     generate.add_argument("--output", type=Path, required=True)
     generate.add_argument("--schema", type=Path, default=default_schema_path())
@@ -81,6 +88,21 @@ def _run(args) -> int:
         print(json.dumps(list_profiles(), indent=2))
         return 0
 
+    if args.command in {"build", "draft-schema"}:
+        if args.command == "build":
+            if args.output and args.output.resolve() == args.draft.resolve():
+                raise ValueError("Output must not overwrite the draft")
+            draft = load_draft(args.draft)
+            _check_depth(draft)
+            result = build_record(draft, base_dir=args.draft.parent)
+        else:
+            result = draft_json_schema(args.profile)
+        if args.output:
+            _write_json(args.output, result)
+        else:
+            print(json.dumps(result, indent=2))
+        return 0
+
     selected_profile = profile_path(args.profile)
     protected = [args.input, args.schema, selected_profile, default_schema_path()]
     if args.output and args.output.resolve() in {p.resolve() for p in protected}:

bioevidence_validator/draft.py

@@ -0,0 +1,250 @@
+"""Compact drafts: a short, strict authoring format that expands to a full evidence record.
+
+A draft names each fact once. Building it derives identifiers, groups evidence items into
+evidence lines by direction, and hashes local source files. It never fills in facts the
+caller did not state: scopes, extraction methods, retrieval times and reviewer decisions
+must be written explicitly, and the resulting record still goes through full validation.
+"""
+from __future__ import annotations
+
+import datetime as dt
+import hashlib
+import json
+from pathlib import Path
+from typing import Any
+
+from .config import load_mapping, nonblank
+from .engine import load_profile, profile_path
+
+DRAFT_KEYS = {"required": {"profile", "uses", "statement", "sources", "evidence"},
+              "optional": {"id", "status", "reviews"}}
+STATEMENT_KEYS = {"required": {"subject", "predicate", "object", "scope"}, "optional": set()}
+ENTITY_KEYS = {"required": {"id", "label", "type"}, "optional": set()}
+SOURCE_KEYS = {"required": {"id", "title", "type", "version", "retrieved_at"},
+               "optional": {"uri", "sha256", "file"}}
+EVIDENCE_KEYS = {"required": {"source", "locator", "type", "method", "scope"},
+                 "optional": {"text", "direction"}}
+REVIEW_KEYS = {"required": {"reviewer", "decision", "uses", "rationale", "decided_at"}, "optional": set()}
+REVIEWER_KEYS = {"required": {"id", "type"}, "optional": {"name"}}
+
+STATUSES = ["proposed", "accepted", "rejected", "superseded"]
+SOURCE_TYPES = ["ontology_snapshot", "registry_snapshot", "dataset_snapshot", "publication", "web_page", "local_file"]
+METHODS = ["deterministic_parser", "manual_curation", "normalized_string_match", "llm_extraction"]
+DIRECTIONS = ["supports", "contradicts", "neutral"]
+DECISIONS = ["accept", "reject", "defer"]
+AGENT_TYPES = ["human", "software", "organization"]
+
+
+def _fields(value: Any, keys: dict, path: str) -> dict:
+    if not isinstance(value, dict):
+        raise ValueError(f"{path} must be a mapping")
+    missing = keys["required"] - value.keys()
+    unknown = value.keys() - keys["required"] - keys["optional"]
+    if missing:
+        raise ValueError(f"{path} is missing: {', '.join(sorted(missing))}")
+    if unknown:
+        raise ValueError(f"{path} has unknown fields: {', '.join(sorted(map(str, unknown)))}")
+    return value
+
+
+def _text(value: Any, path: str, choices: list[str] | None = None) -> str:
+    if isinstance(value, (dt.date, dt.datetime)):
+        value = value.isoformat()  # YAML loads unquoted timestamps as datetime objects.
+    if not nonblank(value):
+        raise ValueError(f"{path} must be a nonblank string (quote numbers and versions in YAML)")
+    if choices is not None and value not in choices:
+        raise ValueError(f"{path} must be one of: {', '.join(choices)}")
+    return value
+
+
+def _texts(value: Any, path: str) -> list[str]:
+    if not isinstance(value, list) or not value:
+        raise ValueError(f"{path} must be a nonempty list")
+    items = [_text(item, f"{path}[{index}]") for index, item in enumerate(value)]
+    if len(set(items)) != len(items):
+        raise ValueError(f"{path} must not repeat values")
+    return items
+
+
+def _rows(value: Any, path: str, required: bool = True) -> list:
+    if not isinstance(value, list) or (required and not value):
+        raise ValueError(f"{path} must be a {'nonempty ' if required else ''}list")
+    return value
+
+
+def _entity(value: Any, path: str) -> dict:
+    entity = _fields(value, ENTITY_KEYS, path)
+    return {"id": _text(entity["id"], path + ".id"), "label": _text(entity["label"], path + ".label"),
+            "entity_type": _text(entity["type"], path + ".type")}
+
+
+def _source(value: Any, path: str, base_dir: Path) -> tuple[str, dict]:
+    source = _fields(value, SOURCE_KEYS, path)
+    if "sha256" not in source and "file" not in source:
+        raise ValueError(f"{path} needs sha256, file, or both")
+    artifact = {"title": _text(source["title"], path + ".title"),
+                "source_type": _text(source["type"], path + ".type", SOURCE_TYPES)}
+    if "uri" in source:
+        artifact["uri"] = _text(source["uri"], path + ".uri")
+    artifact.update({"version": _text(source["version"], path + ".version"),
+                     "retrieved_at": _text(source["retrieved_at"], path + ".retrieved_at")})
+    observed = None
+    if "file" in source:
+        file = base_dir / _text(source["file"], path + ".file")
+        if not file.is_file():
+            raise ValueError(f"{path}.file does not exist: {file}")
+        observed = hashlib.sha256(file.read_bytes()).hexdigest()
+    # A stated hash is the frozen reference; a file hash is what was observed now.
+    # With both, validation reports a mismatch (BEV002) instead of trusting either.
+    artifact["sha256"] = _text(source["sha256"], path + ".sha256").lower() if "sha256" in source else observed
+    if "sha256" in source and observed is not None:
+        artifact["observed_sha256"] = observed
+    return _text(source["id"], path + ".id"), artifact
+
+
+def load_draft(path: Path) -> dict:
+    """Read a YAML or JSON draft with duplicate-key rejection."""
+    return load_mapping(Path(path).read_bytes(), "Draft")
+
+
+def build_record(draft: dict, *, base_dir: Path | str = ".") -> dict[str, Any]:
+    """Expand a compact draft into a full record. Raises ValueError on any malformed field."""
+    draft = _fields(draft, DRAFT_KEYS, "draft")
+    base_dir = Path(base_dir)
+    profile = _text(draft["profile"], "draft.profile")
+    uses = _texts(draft["uses"], "draft.uses")
+    statement = _fields(draft["statement"], STATEMENT_KEYS, "draft.statement")
+    scope = _texts(statement["scope"], "draft.statement.scope")
+
+    record_id = _text(draft["id"], "draft.id") if "id" in draft else None
+    if record_id is None:
+        canonical = json.dumps(draft, sort_keys=True, separators=(",", ":"), default=str).encode()
+        record_id = "bioev:draft-" + hashlib.sha256(canonical).hexdigest()[:16]
+
+    sources, local_ids = [], {}
+    for index, row in enumerate(_rows(draft["sources"], "draft.sources")):
+        name, artifact = _source(row, f"draft.sources[{index}]", base_dir)
+        if name in local_ids:
+            raise ValueError(f"draft.sources[{index}].id repeats {name!r}")
+        local_ids[name] = f"{record_id}/source/{name}"
+        sources.append({"id": local_ids[name], **artifact})
+
+    items, lines = [], {}
+    for index, row in enumerate(_rows(draft["evidence"], "draft.evidence")):
+        path = f"draft.evidence[{index}]"
+        evidence = _fields(row, EVIDENCE_KEYS, path)
+        source = _text(evidence["source"], path + ".source")
+        if source not in local_ids:
+            raise ValueError(f"{path}.source {source!r} is not a declared source id")
+        item = {"id": f"{record_id}/evidence/{index + 1}", "source_artifact_id": local_ids[source],
+                "locator": _text(evidence["locator"], path + ".locator")}
+        if "text" in evidence:
+            item["extracted_text"] = _text(evidence["text"], path + ".text")
+        item.update({"evidence_type": _text(evidence["type"], path + ".type"),
+                     "extraction_method": _text(evidence["method"], path + ".method", METHODS),
+                     "scope": _texts(evidence["scope"], path + ".scope")})
+        items.append(item)
+        direction = _text(evidence.get("direction", "supports"), path + ".direction", DIRECTIONS)
+        lines.setdefault(direction, []).append(item["id"])
+
+    statement_id = f"{record_id}/statement"
+    adjudications = []
+    for index, row in enumerate(_rows(draft.get("reviews", []), "draft.reviews", required=False)):
+        path = f"draft.reviews[{index}]"
+        review = _fields(row, REVIEW_KEYS, path)
+        reviewer = _fields(review["reviewer"], REVIEWER_KEYS, path + ".reviewer")
+        agent = {"id": _text(reviewer["id"], path + ".reviewer.id")}
+        if "name" in reviewer:
+            agent["name"] = _text(reviewer["name"], path + ".reviewer.name")
+        agent["agent_type"] = _text(reviewer["type"], path + ".reviewer.type", AGENT_TYPES)
+        adjudications.append({"id": f"{record_id}/review/{index + 1}", "statement_id": statement_id,
+                              "applies_to_uses": _texts(review["uses"], path + ".uses"),
+                              "decision": _text(review["decision"], path + ".decision", DECISIONS),
+                              "reviewer": agent, "rationale": _text(review["rationale"], path + ".rationale"),
+                              "decided_at": _text(review["decided_at"], path + ".decided_at")})
+
+    return {
+        "record_id": record_id,
+        "profile_id": profile,
+        "statement": {
+            "id": statement_id,
+            "subject": _entity(statement["subject"], "draft.statement.subject"),
+            "predicate": _text(statement["predicate"], "draft.statement.predicate"),
+            "object": _entity(statement["object"], "draft.statement.object"),
+            "scope": scope,
+            "evidence_lines": [{"id": f"{record_id}/line/{direction}", "direction": direction,
+                                "evidence_item_ids": ids} for direction, ids in lines.items()],
+            "statement_status": _text(draft.get("status", "proposed"), "draft.status", STATUSES),
+        },
+        "source_artifacts": sources,
+        "evidence_items": items,
+        "adjudications": adjudications,
+        "requested_uses": uses,
+    }
+
+
+def _object(keys: dict, properties: dict, description: str | None = None) -> dict:
+    if properties.keys() != keys["required"] | keys["optional"]:
+        raise RuntimeError("Draft schema and parser fields diverged")
+    schema = {"type": "object", "additionalProperties": False,
+              "required": sorted(keys["required"]), "properties": properties}
+    return {"description": description, **schema} if description else schema
+
+
+def _choice(values: list[str], description: str | None = None) -> dict:
+    if not values:
+        return {"type": "string", "minLength": 1, **({"description": description} if description else {})}
+    return {"type": "string", "enum": list(values), **({"description": description} if description else {})}
+
+
+def draft_json_schema(profile: str | Path = "general") -> dict[str, Any]:
+    """JSON Schema for drafts under one profile, e.g. for LLM structured output.
+
+    Profile allowlists become enums. The schema guides authoring only; build_record and
+    validation remain authoritative.
+    """
+    contract = load_profile(profile_path(profile).read_bytes())
+    evidence_types = sorted({kind for use in contract["uses"].values() for kind in use["required_evidence_types"]})
+    text = {"type": "string", "minLength": 1}
+    tokens = {"type": "array", "minItems": 1, "uniqueItems": True, "items": text}
+
+    def entity(types):
+        return _object(ENTITY_KEYS, {"id": {**text, "description": "Stable identifier, e.g. a CURIE."},
+                                     "label": text, "type": _choice(types)})
+
+    return {
+        "$schema": "https://json-schema.org/draft/2020-12/schema",
+        "title": f"BioAI evidence draft ({contract['id']} profile {contract['version']})",
+        **_object(DRAFT_KEYS, {
+            "id": {**text, "description": "Optional record id; derived from the draft content when omitted."},
+            "profile": {"const": contract["id"]},
+            "uses": {"type": "array", "minItems": 1, "uniqueItems": True,
+                     "items": _choice(sorted(contract["uses"]))},
+            "status": _choice(STATUSES, "Defaults to proposed."),
+            "statement": _object(STATEMENT_KEYS, {
+                "subject": entity(contract["subject_types"]),
+                "predicate": _choice(contract["predicates"]),
+                "object": entity(contract["object_types"]),
+                "scope": {**tokens, "description": "Explicit scope tokens, e.g. taxon:9606."}}),
+            "sources": {"type": "array", "minItems": 1, "items": _object(SOURCE_KEYS, {
+                "id": {**text, "description": "Local name referenced by evidence[].source."},
+                "title": text, "type": _choice(SOURCE_TYPES), "uri": text, "version": text,
+                "retrieved_at": {"type": "string", "format": "date-time"},
+                "sha256": {"type": "string", "pattern": "^[0-9a-fA-F]{64}$",
+                           "description": "Frozen source hash."},
+                "file": {**text, "description": "Local file hashed at build time, relative to the draft."}},
+                "Provide sha256, file, or both.")},
+            "evidence": {"type": "array", "minItems": 1, "items": _object(EVIDENCE_KEYS, {
+                "source": text, "locator": {**text, "description": "Where in the source, e.g. 'Table 2'."},
+                "text": text, "type": _choice(evidence_types),
+                "method": _choice(METHODS, "Set by the pipeline that produced this item, not by a model."),
+                "scope": {**tokens, "description": "Scope the source actually supports."},
+                "direction": _choice(DIRECTIONS, "Defaults to supports.")})},
+            "reviews": {"type": "array", "items": _object(REVIEW_KEYS, {
+                "reviewer": _object(REVIEWER_KEYS, {"id": text, "name": text, "type": _choice(AGENT_TYPES)}),
+                "decision": _choice(DECISIONS),
+                "uses": {"type": "array", "minItems": 1, "uniqueItems": True,
+                         "items": _choice(sorted(contract["uses"]))},
+                "rationale": text, "decided_at": {"type": "string", "format": "date-time"}})},
+        }),
+    }