zrwangems/dsh-zrwang-plugin / ars/skills/sr-screener
sr-screener
Flagged系统综述文献筛选:把方案或 PROSPERO 协议转成资格规则,双盲筛选标题摘要与全文,第三人裁决冲突,输出 PRISMA 2020 计数、EndNote/Zotero RIS 分组与可交付给论文技能的 literature_corpus。Triggers: systematic review screening, screen papers, PRISMA counts, pilot screening, adjudicate conflicts | 文献筛选, 系统综述筛选, PRISMA 计数, 筛选冲突裁决。
scripts/build_cross_document_consistency_advisory.py
View on GitHub#!/usr/bin/env python3
"""Build, replay-validate, and render the hermetic #672 advisory.
The semantic observations are explicit untrusted inputs. This module performs
only closed-contract validation, exact-byte hashing/replay, deterministic
serialization, and bounded rendering. It never calls a model, network, clock,
subprocess, cache, or directory discovery surface.
"""
from __future__ import annotations
import argparse
import copy
import datetime as dt
import hashlib
import json
import os
import re
import stat
import sys
import tempfile
import unicodedata
from collections.abc import Mapping, Sequence
from pathlib import Path
from typing import Any, NoReturn
from urllib.parse import unquote
SIDECAR_SCHEMA_VERSION = "preregistration-artifact/1.0"
MANIFEST_SCHEMA_VERSION = "cross-document-source-manifest/1.0"
DRAFT_SCHEMA_VERSION = "cross-document-consistency-advisory-draft/1.0"
REPORT_SCHEMA_VERSION = "cross-document-consistency-advisory/1.0"
EVIDENCE_SCHEMA_VERSION = "evidence-row/1.2"
SURFACE = "cross_document_consistency"
LAYER = "LLM-ADVISORY"
EVALUATION_STATUS = "UNMEASURED"
MAX_DRAFT_BYTES = 16 * 1024 * 1024
MAX_MANIFEST_BYTES = 1 * 1024 * 1024
MAX_SIDECAR_BYTES = 1 * 1024 * 1024
MAX_FINAL_BYTES = 32 * 1024 * 1024
MAX_ACCEPTED_DRAFT_BYTES = 8 * 1024 * 1024
MAX_PREREGISTRATION_BYTES = 64 * 1024 * 1024
MAX_TOTAL_SOURCE_BYTES = 72 * 1024 * 1024
MAX_OBSERVATIONS = 4096
MAX_JSON_DEPTH = 100
MAX_JSON_NODES = 1_000_000
MAX_PAGE_SIZE = 25
MAX_IDENTIFIER = 200
MAX_PATH_CODEPOINTS = 1024
MAX_EXTERNAL_CODEPOINTS = 1000
MAX_EXTERNAL_WORDS = 25
MAX_ENCODED_ANCHOR = 12000
TEMPLATE_SHA256 = "40054e26c527ff3dd237a5eef3fee60b821cf8549e210d48a057005333c8e0d2"
LOCATOR_PROVENANCE = "agent_supplied_not_independently_authenticated"
SCOPE_COMPLETENESS = (
"caller_declared_complete_named_scope_not_independently_authenticated"
)
SEMANTIC_PROVENANCE = "caller_supplied_not_deterministically_verified"
PAIR_ORDER = (
"abstract_results",
"discussion_results",
"methods_reported_analyses",
"manuscript_preregistration",
)
PAIR_ROLES = {
"abstract_results": ("abstract", "results"),
"discussion_results": ("discussion", "results"),
"methods_reported_analyses": ("methods", "reported_analyses"),
"manuscript_preregistration": (
"manuscript_report",
"preregistration",
"disclosure_scope",
),
}
FINDING_TYPES = {
"abstract_results": frozenset(
{
"numeric_mismatch",
"direction_mismatch",
"significance_mismatch",
"claim_strength_rung_mismatch",
}
),
"discussion_results": frozenset(
{
"direction_mismatch",
"claim_strength_rung_mismatch",
"scope_or_population_overreach",
}
),
"methods_reported_analyses": frozenset(
{
"declared_analysis_no_reported_counterpart",
"reported_analysis_no_declared_counterpart",
"analysis_specification_conflict",
}
),
"manuscript_preregistration": frozenset({"undisclosed_preregistration_deviation"}),
}
NEGATIVE_BASES = frozenset(
{
"legitimate_compression",
"same_rung_rewording",
"disclosed_deviation",
"other_no_listed_observation",
}
)
DEVIATION_DOMAINS = frozenset(
{
"hypothesis",
"primary_outcome",
"sample_size_or_stopping",
"analysis_model",
"transformation",
"exclusion",
"inference_criterion",
"confirmatory_exploratory_designation",
}
)
EVIDENCE_STATES = frozenset(
{
"agent_extracted",
"checked_no_match",
"not_checked",
"source_missing",
"access_failed",
"retrieval_failed",
}
)
FAILURE_STATES = frozenset(
{"not_checked", "source_missing", "access_failed", "retrieval_failed"}
)
MANIFEST_STATES = frozenset(
{"present", "source_missing", "access_failed", "retrieval_failed"}
)
SIDECAR_STATES = frozenset(
{"provided", "not_provided", "access_failed", "retrieval_failed"}
)
NOT_CHECKED_REASONS = frozenset(
{
"PAIR_CHECK_NOT_PERFORMED",
"COUNTERPART_DOCUMENT_MISSING",
"COUNTERPART_SCOPE_NOT_PROVIDED",
"SOURCE_ACCESS_FAILED",
"SOURCE_RETRIEVAL_FAILED",
}
)
OUTCOMES = frozenset(
{"POTENTIAL_INCONSISTENCY_LOCATED", "NO_LISTED_INCONSISTENCY_LOCATED"}
)
DIAGNOSTIC_CODES = frozenset(
{
"NAMED_INPUT_UNREADABLE",
"DRAFT_CONTRACT_INVALID",
"SOURCE_MANIFEST_INVALID",
"SOURCE_BINDING_INVALID",
"EVIDENCE_REPLAY_INVALID",
"FINAL_ARTIFACT_INVALID",
"RESOURCE_LIMIT",
}
)
BOUNDARY = {
"semantic_observation_not_recomputed": True,
"stage_4_5_verdict_unchanged": True,
"stage_5_routing_unchanged": True,
"integrity_issue_counts_unchanged": True,
"formatter_gate_unchanged": True,
"terminal_policy_unchanged": True,
"score_not_produced": True,
"automatic_rewrite_not_performed": True,
"agreement_not_certified": True,
}
_RFC3339_RE = re.compile(
r"^[0-9]{4}-[0-9]{2}-[0-9]{2}[Tt]"
r"(?:[01][0-9]|2[0-3]):[0-5][0-9]:[0-5][0-9]"
r"(?:\.[0-9]+)?(?:[Zz]|[+-](?:[01][0-9]|2[0-3]):[0-5][0-9])$"
)
_HEX = frozenset("0123456789abcdefABCDEF")
class AdvisoryError(ValueError):
"""A closed #672 contract or replay invariant failed."""
def __init__(self, code: str, message: str) -> None:
if code not in DIAGNOSTIC_CODES:
raise ValueError(f"unknown diagnostic code: {code}")
super().__init__(message)
self.code = code
class _ClosedArgumentParser(argparse.ArgumentParser):
"""Convert malformed CLI syntax into the same bounded diagnostic channel."""
def error(self, message: str) -> NoReturn:
del message
raise AdvisoryError(
"FINAL_ARTIFACT_INVALID",
"command line: arguments do not match the closed CLI",
)
def _fail(code: str, path: str, message: str) -> NoReturn:
raise AdvisoryError(code, f"{path}: {message}")
def _sha256(value: bytes) -> str:
return hashlib.sha256(value).hexdigest()
def _canonical_bytes(value: Any) -> bytes:
try:
return json.dumps(
value,
ensure_ascii=False,
sort_keys=True,
separators=(",", ":"),
allow_nan=False,
).encode("utf-8", errors="strict")
except (TypeError, ValueError, UnicodeError, RecursionError) as exc:
_fail("FINAL_ARTIFACT_INVALID", "value", f"cannot serialize canonically: {exc}")
def _digest_without(value: Mapping[str, Any], field: str) -> str:
payload = {key: copy.deepcopy(item) for key, item in value.items() if key != field}
return _sha256(_canonical_bytes(payload))
def _closed(
value: Any,
path: str,
fields: set[str] | frozenset[str],
*,
code: str,
) -> dict[str, Any]:
if not isinstance(value, dict):
_fail(code, path, "must be an object")
missing = fields - set(value)
extra = set(value) - fields
if missing:
_fail(code, path, f"missing field(s): {', '.join(sorted(missing))}")
if extra:
_fail(code, path, f"undeclared field(s): {', '.join(sorted(extra))}")
return value
def _array(
value: Any,
path: str,
*,
code: str,
minimum: int = 0,
maximum: int = MAX_OBSERVATIONS,
) -> list[Any]:
if not isinstance(value, list):
_fail(code, path, "must be an array")
if len(value) < minimum or len(value) > maximum:
_fail(code, path, f"must contain {minimum}..{maximum} items")
return value
def _safe_text(
value: Any,
path: str,
*,
code: str,
minimum: int = 1,
maximum: int = 1000,
) -> str:
if not isinstance(value, str):
_fail(code, path, "must be a string")
if len(value) < minimum or len(value) > maximum:
_fail(code, path, f"must contain {minimum}..{maximum} code points")
for character in value:
number = ord(character)
category = unicodedata.category(character)
if (
number == 127
or (number < 32 and character not in {"\t", "\n", "\r"})
or 0xD800 <= number <= 0xDFFF
or category in {"Cf", "Zl", "Zp"}
):
_fail(code, path, f"contains forbidden character U+{number:04X}")
return value
def _identifier(value: Any, path: str, *, code: str) -> str:
text = _safe_text(value, path, code=code, maximum=MAX_IDENTIFIER)
if re.fullmatch(r"[a-z0-9][a-z0-9._-]{0,199}", text) is None:
_fail(code, path, "must be a lowercase ASCII identifier")
return text
def _sha(value: Any, path: str, *, code: str) -> str:
if not isinstance(value, str) or re.fullmatch(r"[0-9a-f]{64}", value) is None:
_fail(code, path, "must be a lowercase SHA-256 hex digest")
return value
def _integer(
value: Any,
path: str,
*,
code: str,
minimum: int = 0,
maximum: int,
) -> int:
if isinstance(value, bool) or not isinstance(value, int):
_fail(code, path, "must be an integer")
if value < minimum or value > maximum:
_fail(code, path, f"must be within {minimum}..{maximum}")
return value
def _enum(value: Any, path: str, choices: frozenset[str], *, code: str) -> str:
if not isinstance(value, str) or value not in choices:
_fail(code, path, f"must be one of {sorted(choices)}")
return value
def _timestamp(value: Any, path: str, *, code: str) -> str:
text = _safe_text(value, path, code=code, maximum=100)
if _RFC3339_RE.fullmatch(text) is None:
_fail(code, path, "must be an RFC 3339 timestamp with an offset")
normalized = text[:-1] + "+00:00" if text[-1] in {"Z", "z"} else text
try:
dt.datetime.fromisoformat(normalized)
except ValueError as exc:
_fail(code, path, f"is not a real RFC 3339 timestamp: {exc}")
return text
def _relative_path(value: Any, path: str, *, code: str) -> str:
text = _safe_text(value, path, code=code, maximum=MAX_PATH_CODEPOINTS)
if (
text.startswith("/")
or "\\" in text
or any(
unicodedata.category(character) in {"Cc", "Cf", "Zl", "Zp"}
for character in text
)
):
_fail(code, path, "must be a normalized relative POSIX path")
components = text.split("/")
if any(component in {"", ".", ".."} for component in components):
_fail(code, path, "contains an empty, dot, or parent component")
return text
def _span(value: Any, path: str, *, code: str) -> dict[str, int]:
block = _closed(value, path, {"start", "end"}, code=code)
start = _integer(
block["start"], f"{path}.start", code=code, maximum=MAX_TOTAL_SOURCE_BYTES
)
end = _integer(
block["end"],
f"{path}.end",
code=code,
minimum=1,
maximum=MAX_TOTAL_SOURCE_BYTES,
)
if end <= start:
_fail(code, path, "must be a non-empty half-open UTF-8 span")
return {"start": start, "end": end}
def strict_percent_decode(value: str) -> str:
"""Decode RFC 3986 percent escapes once; a plus remains a literal plus."""
_safe_text(
value,
"anchor_value_encoded",
code="EVIDENCE_REPLAY_INVALID",
maximum=MAX_ENCODED_ANCHOR,
)
index = 0
while index < len(value):
if value[index] == "%":
if (
index + 2 >= len(value)
or value[index + 1] not in _HEX
or value[index + 2] not in _HEX
):
_fail(
"EVIDENCE_REPLAY_INVALID",
"anchor_value_encoded",
f"malformed percent escape at character {index}",
)
index += 3
else:
index += 1
try:
return unquote(value, encoding="utf-8", errors="strict")
except UnicodeError as exc:
_fail(
"EVIDENCE_REPLAY_INVALID",
"anchor_value_encoded",
f"percent escapes are not strict UTF-8: {exc}",
)
def _precheck_depth(text: str, *, code: str, path: str) -> None:
depth = 0
in_string = False
escaped = False
for character in text:
if in_string:
if escaped:
escaped = False
elif character == "\\":
escaped = True
elif character == '"':
in_string = False
continue
if character == '"':
in_string = True
elif character in "[{":
depth += 1
if depth > MAX_JSON_DEPTH:
_fail(code, path, f"JSON nesting exceeds {MAX_JSON_DEPTH}")
elif character in "]}":
depth -= 1
def _count_nodes(value: Any, *, code: str, path: str) -> None:
count = 0
stack = [value]
while stack:
current = stack.pop()
count += 1
if count > MAX_JSON_NODES:
_fail(code, path, f"JSON aggregate nodes exceed {MAX_JSON_NODES}")
if isinstance(current, dict):
stack.extend(current.values())
elif isinstance(current, list):
stack.extend(current)
def _reject_unsafe_json_strings(value: Any, *, code: str, path: str) -> None:
stack: list[tuple[str, Any]] = [(path, value)]
while stack:
current_path, current = stack.pop()
if isinstance(current, dict):
for key, item in current.items():
_safe_text(
key, f"{current_path} key", code=code, minimum=0, maximum=1024
)
stack.append((f"{current_path}.{key}", item))
elif isinstance(current, list):
for index, item in enumerate(current):
stack.append((f"{current_path}[{index}]", item))
elif isinstance(current, str):
_safe_text(
current,
current_path,
code=code,
minimum=0,
maximum=max(len(current), 1),
)
def _read_named_bytes(
path: Path,
maximum: int,
*,
label: str,
unreadable_code: str = "NAMED_INPUT_UNREADABLE",
) -> bytes:
flags = os.O_RDONLY
if hasattr(os, "O_NOFOLLOW"):
flags |= os.O_NOFOLLOW
# A read-only open of a FIFO can otherwise wait forever before fstat has a
# chance to reject it. O_NONBLOCK is inert for ordinary regular files.
if hasattr(os, "O_NONBLOCK"):
flags |= os.O_NONBLOCK
try:
descriptor = os.open(path, flags)
try:
metadata = os.fstat(descriptor)
if not stat.S_ISREG(metadata.st_mode):
_fail(unreadable_code, label, "must be a regular file")
chunks: list[bytes] = []
remaining = maximum + 1
while remaining:
chunk = os.read(descriptor, min(1024 * 1024, remaining))
if not chunk:
break
chunks.append(chunk)
remaining -= len(chunk)
payload = b"".join(chunks)
finally:
os.close(descriptor)
except AdvisoryError:
raise
except (OSError, ValueError) as exc:
_fail(
unreadable_code,
label,
f"could not be read: {exc.__class__.__name__}",
)
if len(payload) > maximum:
_fail("RESOURCE_LIMIT", label, f"exceeds {maximum} bytes")
return payload
def _strict_json_bytes(
raw: bytes,
*,
code: str,
path: str,
) -> Any:
if raw.startswith(b"\xef\xbb\xbf"):
_fail(code, path, "must not contain a UTF-8 BOM")
try:
text = raw.decode("utf-8", errors="strict")
except UnicodeError as exc:
_fail(code, path, f"is not strict UTF-8: {exc}")
_precheck_depth(text, code=code, path=path)
def object_pairs(pairs: list[tuple[str, Any]]) -> dict[str, Any]:
result: dict[str, Any] = {}
for key, item in pairs:
if key in result:
_fail(code, path, f"contains duplicate decoded key {key!r}")
result[key] = item
return result
def reject_constant(value: str) -> NoReturn:
_fail(code, path, f"contains non-finite number {value}")
def reject_float(value: str) -> NoReturn:
_fail(code, path, f"contains unsupported non-integer number {value}")
try:
value = json.loads(
text,
object_pairs_hook=object_pairs,
parse_constant=reject_constant,
parse_float=reject_float,
)
except AdvisoryError:
raise
except (json.JSONDecodeError, RecursionError, ValueError) as exc:
_fail(code, path, f"is not strict JSON: {exc}")
_count_nodes(value, code=code, path=path)
_reject_unsafe_json_strings(value, code=code, path=path)
return value
def _load_json(
path: Path,
maximum: int,
*,
code: str,
label: str,
) -> tuple[Any, bytes]:
raw = _read_named_bytes(path, maximum, label=label)
return _strict_json_bytes(raw, code=code, path=label), raw
def _binding_bytes(
value: Any,
raw: bytes | None,
maximum: int,
*,
code: str,
path: str,
) -> bytes:
"""Bind a parsed carrier to the exact raw bytes named by its caller."""
if raw is None:
candidate = _canonical_bytes(value)
elif isinstance(raw, bytes):
candidate = raw
else:
_fail(code, path, "raw binding must be bytes")
if len(candidate) > maximum:
_fail("RESOURCE_LIMIT", path, f"exceeds {maximum} bytes")
parsed = _strict_json_bytes(candidate, code=code, path=path)
if _canonical_bytes(parsed) != _canonical_bytes(value):
_fail(code, path, "raw bytes decode to a different object")
return candidate
def _strict_source(raw: bytes, *, label: str, maximum: int) -> str:
if not isinstance(raw, bytes):
_fail("SOURCE_BINDING_INVALID", label, "must be bytes")
if len(raw) > maximum:
_fail("RESOURCE_LIMIT", label, f"exceeds {maximum} bytes")
if raw.startswith(b"\xef\xbb\xbf"):
_fail("SOURCE_BINDING_INVALID", label, "must not contain a UTF-8 BOM")
try:
text = raw.decode("utf-8", errors="strict")
if text.encode("utf-8", errors="strict") != raw:
_fail(
"SOURCE_BINDING_INVALID", label, "does not round-trip as strict UTF-8"
)
except UnicodeError as exc:
_fail("SOURCE_BINDING_INVALID", label, f"is not strict UTF-8: {exc}")
return text
def _strict_accepted_draft(raw: bytes) -> str:
text = _strict_source(
raw,
label="accepted draft",
maximum=MAX_ACCEPTED_DRAFT_BYTES,
)
if not text.strip():
_fail("SOURCE_BINDING_INVALID", "accepted draft", "must not be blank")
return text
def _atomic_write(path: Path, payload: bytes) -> None:
try:
path.parent.mkdir(parents=True, exist_ok=True)
descriptor, temporary = tempfile.mkstemp(
dir=path.parent,
prefix=f".{path.name}.",
suffix=".tmp",
)
try:
with os.fdopen(descriptor, "wb") as handle:
handle.write(payload)
handle.flush()
os.fsync(handle.fileno())
os.replace(temporary, path)
except BaseException:
try:
os.unlink(temporary)
except FileNotFoundError:
pass
raise
except AdvisoryError:
raise
except OSError as exc:
_fail(
"NAMED_INPUT_UNREADABLE",
"output",
f"atomic write failed: {exc.__class__.__name__}",
)
def _reject_output_alias(output: Path, inputs: Sequence[Path | None]) -> None:
output_absolute = os.path.abspath(output)
for candidate in inputs:
if candidate is None:
continue
if output_absolute == os.path.abspath(candidate):
_fail("NAMED_INPUT_UNREADABLE", "output", "must not alias a named input")
try:
if (
output.exists()
and candidate.exists()
and os.path.samefile(output, candidate)
):
_fail(
"NAMED_INPUT_UNREADABLE", "output", "must not alias a named input"
)
except OSError:
continue
def build_preregistration_artifact(
*,
status: str,
artifact_id: str,
declared_at: str,
companion_bytes: bytes | None = None,
relative_path: str | None = None,
artifact_provenance: str | None = None,
) -> dict[str, Any]:
"""Derive one canonical, hash-bound preregistration handoff sidecar."""
state = _enum(status, "status", SIDECAR_STATES, code="SOURCE_BINDING_INVALID")
identity = _identifier(artifact_id, "artifact_id", code="SOURCE_BINDING_INVALID")
timestamp = _timestamp(declared_at, "declared_at", code="SOURCE_BINDING_INVALID")
if state == "provided":
if companion_bytes is None:
_fail(
"SOURCE_BINDING_INVALID", "companion", "is required for provided status"
)
text = _strict_source(
companion_bytes,
label="preregistration companion",
maximum=MAX_PREREGISTRATION_BYTES,
)
if not text.strip():
_fail("SOURCE_BINDING_INVALID", "companion", "must not be blank")
digest = _sha256(companion_bytes)
if digest == TEMPLATE_SHA256:
_fail(
"SOURCE_BINDING_INVALID",
"companion",
"blank guidance template is not evidence",
)
if relative_path is None:
_fail(
"SOURCE_BINDING_INVALID",
"relative_path",
"is required for provided status",
)
normalized_path = _relative_path(
relative_path,
"relative_path",
code="SOURCE_BINDING_INVALID",
)
provenance = artifact_provenance or "author_provided_completed_preregistration"
if not isinstance(provenance, str) or provenance not in {
"author_provided_completed_preregistration",
"synthetic_fixture",
}:
_fail(
"SOURCE_BINDING_INVALID",
"artifact_provenance",
"is invalid for provided status",
)
size = len(companion_bytes)
record: dict[str, Any] = {
"schema_version": SIDECAR_SCHEMA_VERSION,
"status": state,
"artifact_id": identity,
"relative_path": normalized_path,
"artifact_provenance": provenance,
"source_artifact_sha256": digest,
"source_artifact_size_bytes": size,
"source_content_sha256": digest,
"source_content_utf8_bytes": size,
"declared_at": timestamp,
"record_digest": "",
}
else:
if companion_bytes is not None or relative_path is not None:
_fail(
"SOURCE_BINDING_INVALID",
"sidecar",
"unavailable status forbids companion/path",
)
if artifact_provenance is not None and artifact_provenance != "not_provided":
_fail(
"SOURCE_BINDING_INVALID", "artifact_provenance", "must be not_provided"
)
record = {
"schema_version": SIDECAR_SCHEMA_VERSION,
"status": state,
"artifact_id": identity,
"relative_path": None,
"artifact_provenance": "not_provided",
"source_artifact_sha256": None,
"source_artifact_size_bytes": None,
"source_content_sha256": None,
"source_content_utf8_bytes": None,
"declared_at": timestamp,
"record_digest": "",
}
record["record_digest"] = _digest_without(record, "record_digest")
if len(_canonical_bytes(record)) > MAX_SIDECAR_BYTES:
_fail("RESOURCE_LIMIT", "sidecar", "canonical output exceeds 1 MiB")
return record
def validate_preregistration_artifact(
value: Any,
*,
companion_bytes: bytes | None,
) -> dict[str, Any]:
fields = {
"schema_version",
"status",
"artifact_id",
"relative_path",
"artifact_provenance",
"source_artifact_sha256",
"source_artifact_size_bytes",
"source_content_sha256",
"source_content_utf8_bytes",
"declared_at",
"record_digest",
}
record = _closed(value, "sidecar", fields, code="SOURCE_BINDING_INVALID")
if record["schema_version"] != SIDECAR_SCHEMA_VERSION:
_fail(
"SOURCE_BINDING_INVALID", "sidecar.schema_version", "has the wrong version"
)
_sha(
record["record_digest"], "sidecar.record_digest", code="SOURCE_BINDING_INVALID"
)
expected = build_preregistration_artifact(
status=record["status"],
artifact_id=record["artifact_id"],
declared_at=record["declared_at"],
companion_bytes=companion_bytes,
relative_path=record["relative_path"],
artifact_provenance=record["artifact_provenance"],
)
if _canonical_bytes(record) != _canonical_bytes(expected):
_fail(
"SOURCE_BINDING_INVALID", "sidecar", "does not match deterministic replay"
)
return copy.deepcopy(record)
def _manifest_artifact(value: Any, path: str) -> dict[str, Any]:
fields = {
"artifact_id",
"document_kind",
"relative_path",
"artifact_state",
"artifact_provenance",
"source_artifact_sha256",
"source_artifact_size_bytes",
"source_content_sha256",
"source_content_utf8_bytes",
}
artifact = _closed(value, path, fields, code="SOURCE_MANIFEST_INVALID")
_identifier(
artifact["artifact_id"], f"{path}.artifact_id", code="SOURCE_MANIFEST_INVALID"
)
if not isinstance(artifact["document_kind"], str) or artifact[
"document_kind"
] not in {
"manuscript",
"preregistration",
}:
_fail("SOURCE_MANIFEST_INVALID", f"{path}.document_kind", "is invalid")
state = _enum(
artifact["artifact_state"],
f"{path}.artifact_state",
MANIFEST_STATES,
code="SOURCE_MANIFEST_INVALID",
)
if state == "present":
_relative_path(
artifact["relative_path"],
f"{path}.relative_path",
code="SOURCE_MANIFEST_INVALID",
)
raw_sha = _sha(
artifact["source_artifact_sha256"],
f"{path}.source_artifact_sha256",
code="SOURCE_MANIFEST_INVALID",
)
content_sha = _sha(
artifact["source_content_sha256"],
f"{path}.source_content_sha256",
code="SOURCE_MANIFEST_INVALID",
)
maximum_size = (
MAX_ACCEPTED_DRAFT_BYTES
if artifact["document_kind"] == "manuscript"
else MAX_PREREGISTRATION_BYTES
)
raw_size = _integer(
artifact["source_artifact_size_bytes"],
f"{path}.source_artifact_size_bytes",
code="SOURCE_MANIFEST_INVALID",
minimum=1,
maximum=maximum_size,
)
content_size = _integer(
artifact["source_content_utf8_bytes"],
f"{path}.source_content_utf8_bytes",
code="SOURCE_MANIFEST_INVALID",
minimum=1,
maximum=maximum_size,
)
if raw_sha != content_sha or raw_size != content_size:
_fail(
"SOURCE_MANIFEST_INVALID", path, "UTF-8 V1 raw/content bindings differ"
)
allowed_provenance = (
{"author_provided_manuscript", "synthetic_fixture"}
if artifact["document_kind"] == "manuscript"
else {"author_provided_completed_preregistration", "synthetic_fixture"}
)
if (
not isinstance(artifact["artifact_provenance"], str)
or artifact["artifact_provenance"] not in allowed_provenance
):
_fail(
"SOURCE_MANIFEST_INVALID", f"{path}.artifact_provenance", "is invalid"
)
else:
if artifact["document_kind"] != "preregistration":
_fail(
"SOURCE_MANIFEST_INVALID", path, "accepted manuscript must be present"
)
if artifact["relative_path"] is not None:
_fail("SOURCE_MANIFEST_INVALID", f"{path}.relative_path", "must be null")
for field in (
"source_artifact_sha256",
"source_artifact_size_bytes",
"source_content_sha256",
"source_content_utf8_bytes",
):
if artifact[field] is not None:
_fail("SOURCE_MANIFEST_INVALID", f"{path}.{field}", "must be null")
if artifact["artifact_provenance"] != "not_provided":
_fail(
"SOURCE_MANIFEST_INVALID",
f"{path}.artifact_provenance",
"must be not_provided",
)
return artifact
def _project_sidecar(record: Mapping[str, Any]) -> dict[str, Any]:
state = {
"provided": "present",
"not_provided": "source_missing",
"access_failed": "access_failed",
"retrieval_failed": "retrieval_failed",
}[record["status"]]
return {
"artifact_id": record["artifact_id"],
"document_kind": "preregistration",
"relative_path": record["relative_path"],
"artifact_state": state,
"artifact_provenance": record["artifact_provenance"],
"source_artifact_sha256": record["source_artifact_sha256"],
"source_artifact_size_bytes": record["source_artifact_size_bytes"],
"source_content_sha256": record["source_content_sha256"],
"source_content_utf8_bytes": record["source_content_utf8_bytes"],
}
def validate_source_manifest(
value: Any,
*,
sidecar: Mapping[str, Any],
accepted_draft_bytes: bytes,
) -> tuple[dict[str, Any], dict[str, dict[str, Any]]]:
fields = {
"schema_version",
"manifest_id",
"accepted_draft_artifact_id",
"accepted_draft_sha256",
"artifacts",
"manifest_digest",
}
manifest = _closed(value, "manifest", fields, code="SOURCE_MANIFEST_INVALID")
if manifest["schema_version"] != MANIFEST_SCHEMA_VERSION:
_fail(
"SOURCE_MANIFEST_INVALID",
"manifest.schema_version",
"has the wrong version",
)
_identifier(
manifest["manifest_id"], "manifest.manifest_id", code="SOURCE_MANIFEST_INVALID"
)
accepted_id = _identifier(
manifest["accepted_draft_artifact_id"],
"manifest.accepted_draft_artifact_id",
code="SOURCE_MANIFEST_INVALID",
)
accepted_sha = _sha(
manifest["accepted_draft_sha256"],
"manifest.accepted_draft_sha256",
code="SOURCE_MANIFEST_INVALID",
)
_sha(
manifest["manifest_digest"],
"manifest.manifest_digest",
code="SOURCE_MANIFEST_INVALID",
)
artifacts = _array(
manifest["artifacts"],
"manifest.artifacts",
code="SOURCE_MANIFEST_INVALID",
minimum=2,
maximum=2,
)
parsed = [
_manifest_artifact(item, f"manifest.artifacts[{index}]")
for index, item in enumerate(artifacts)
]
ids = [item["artifact_id"] for item in parsed]
if ids != sorted(ids) or len(set(ids)) != 2:
_fail(
"SOURCE_MANIFEST_INVALID",
"manifest.artifacts",
"must have unique ASCII-sorted IDs",
)
by_id = {item["artifact_id"]: item for item in parsed}
if accepted_id not in by_id:
_fail(
"SOURCE_MANIFEST_INVALID",
"manifest.accepted_draft_artifact_id",
"does not resolve",
)
accepted = by_id[accepted_id]
if (
accepted["document_kind"] != "manuscript"
or accepted["artifact_state"] != "present"
):
_fail(
"SOURCE_MANIFEST_INVALID",
"manifest",
"designated accepted draft is not present manuscript",
)
if sidecar["artifact_id"] == accepted_id:
_fail(
"SOURCE_MANIFEST_INVALID",
"manifest",
"preregistration/manuscript IDs must differ",
)
if set(by_id) != {accepted_id, sidecar["artifact_id"]}:
_fail(
"SOURCE_MANIFEST_INVALID",
"manifest.artifacts",
"must contain exactly accepted draft and sidecar projection",
)
if by_id[sidecar["artifact_id"]] != _project_sidecar(sidecar):
_fail(
"SOURCE_MANIFEST_INVALID",
"manifest",
"preregistration projection differs from sidecar",
)
actual_sha = _sha256(accepted_draft_bytes)
actual_size = len(accepted_draft_bytes)
if accepted_sha != actual_sha:
_fail(
"SOURCE_BINDING_INVALID",
"accepted draft",
"manifest SHA does not match named bytes",
)
for field in ("source_artifact_sha256", "source_content_sha256"):
if accepted[field] != actual_sha:
_fail(
"SOURCE_BINDING_INVALID",
f"accepted draft {field}",
"does not match named bytes",
)
for field in ("source_artifact_size_bytes", "source_content_utf8_bytes"):
if accepted[field] != actual_size:
_fail(
"SOURCE_BINDING_INVALID",
f"accepted draft {field}",
"does not match named bytes",
)
if _digest_without(manifest, "manifest_digest") != manifest["manifest_digest"]:
_fail("SOURCE_MANIFEST_INVALID", "manifest.manifest_digest", "does not replay")
return copy.deepcopy(manifest), copy.deepcopy(by_id)
def _locator(value: Any, path: str) -> dict[str, str]:
locator = _closed(
value,
path,
{"kind", "value", "provenance"},
code="DRAFT_CONTRACT_INVALID",
)
if not isinstance(locator["kind"], str) or locator["kind"] not in {
"document",
"page",
"section",
"paragraph",
"other",
}:
_fail("DRAFT_CONTRACT_INVALID", f"{path}.kind", "is invalid")
_safe_text(
locator["value"],
f"{path}.value",
code="DRAFT_CONTRACT_INVALID",
maximum=500,
)
if any(
unicodedata.category(character) in {"Cc", "Cf", "Zl", "Zp"}
for character in locator["value"]
):
_fail(
"DRAFT_CONTRACT_INVALID",
f"{path}.value",
"must be a control-free single line",
)
if locator["provenance"] != LOCATOR_PROVENANCE:
_fail("DRAFT_CONTRACT_INVALID", f"{path}.provenance", "is invalid")
return copy.deepcopy(locator)
def _rights_pair(sharing_scope: Any, rights_basis: Any, path: str) -> tuple[str, str]:
if not isinstance(sharing_scope, str) or not isinstance(rights_basis, str):
_fail(
"DRAFT_CONTRACT_INVALID",
path,
"sharing_scope/rights_basis must both be strings",
)
pair = (sharing_scope, rights_basis)
allowed = {
("session_only", "not_assessed"),
("user_confirmed_shareable", "user_declared_authorized"),
}
if pair not in allowed:
_fail(
"DRAFT_CONTRACT_INVALID",
path,
"sharing_scope/rights_basis pairing is invalid",
)
return pair # type: ignore[return-value]
def _draft_slot(
value: Any,
path: str,
*,
expected_role: str,
accepted_id: str,
preregistration_id: str,
) -> dict[str, Any]:
fields = {
"logical_role",
"artifact_id",
"document_locator",
"evidence_state",
"anchor_value_encoded",
"quote_source_span_utf8",
"checked_scope_input",
"captured_at",
"sharing_scope",
"rights_basis",
}
slot = _closed(value, path, fields, code="DRAFT_CONTRACT_INVALID")
if slot["logical_role"] != expected_role:
_fail(
"DRAFT_CONTRACT_INVALID",
f"{path}.logical_role",
f"must equal {expected_role}",
)
expected_id = (
preregistration_id if expected_role == "preregistration" else accepted_id
)
artifact_id = _identifier(
slot["artifact_id"], f"{path}.artifact_id", code="DRAFT_CONTRACT_INVALID"
)
if artifact_id != expected_id:
_fail(
"DRAFT_CONTRACT_INVALID",
f"{path}.artifact_id",
"does not bind the required artifact",
)
_locator(slot["document_locator"], f"{path}.document_locator")
state = _enum(
slot["evidence_state"],
f"{path}.evidence_state",
EVIDENCE_STATES,
code="DRAFT_CONTRACT_INVALID",
)
encoded = slot["anchor_value_encoded"]
span = slot["quote_source_span_utf8"]
scope = slot["checked_scope_input"]
captured = slot["captured_at"]
if state == "agent_extracted":
_safe_text(
encoded,
f"{path}.anchor_value_encoded",
code="DRAFT_CONTRACT_INVALID",
maximum=MAX_ENCODED_ANCHOR,
)
_span(span, f"{path}.quote_source_span_utf8", code="DRAFT_CONTRACT_INVALID")
_timestamp(captured, f"{path}.captured_at", code="DRAFT_CONTRACT_INVALID")
if scope is not None:
_fail(
"DRAFT_CONTRACT_INVALID", f"{path}.checked_scope_input", "must be null"
)
elif state == "checked_no_match":
if encoded is not None or span is not None or captured is not None:
_fail(
"DRAFT_CONTRACT_INVALID",
path,
"checked_no_match carries no quote payload",
)
block = _closed(
scope,
f"{path}.checked_scope_input",
{"source_span_utf8", "checked_at", "scope_completeness"},
code="DRAFT_CONTRACT_INVALID",
)
_span(
block["source_span_utf8"],
f"{path}.checked_scope_input.source_span_utf8",
code="DRAFT_CONTRACT_INVALID",
)
_timestamp(
block["checked_at"],
f"{path}.checked_scope_input.checked_at",
code="DRAFT_CONTRACT_INVALID",
)
if block["scope_completeness"] != SCOPE_COMPLETENESS:
_fail(
"DRAFT_CONTRACT_INVALID",
f"{path}.checked_scope_input.scope_completeness",
"is invalid",
)
else:
if (
encoded is not None
or span is not None
or scope is not None
or captured is not None
):
_fail(
"DRAFT_CONTRACT_INVALID",
path,
"failure state carries quote/scope payload",
)
sharing, rights = _rights_pair(slot["sharing_scope"], slot["rights_basis"], path)
if state != "agent_extracted" and (sharing, rights) != (
"session_only",
"not_assessed",
):
_fail(
"DRAFT_CONTRACT_INVALID",
path,
"non-quote state must use session_only/not_assessed",
)
return copy.deepcopy(slot)
def _expected_not_checked_reason(pair_kind: str, slots: list[dict[str, Any]]) -> str:
states = [slot["evidence_state"] for slot in slots]
if "source_missing" in states:
return "COUNTERPART_DOCUMENT_MISSING"
if "access_failed" in states:
return "SOURCE_ACCESS_FAILED"
if "retrieval_failed" in states:
return "SOURCE_RETRIEVAL_FAILED"
if pair_kind == "methods_reported_analyses" and sorted(states) == [
"agent_extracted",
"not_checked",
]:
return "COUNTERPART_SCOPE_NOT_PROVIDED"
if pair_kind == "manuscript_preregistration" and states == [
"agent_extracted",
"agent_extracted",
"not_checked",
]:
return "COUNTERPART_SCOPE_NOT_PROVIDED"
return "PAIR_CHECK_NOT_PERFORMED"
def _performed_combination(
observation: Mapping[str, Any], states: tuple[str, ...], path: str
) -> None:
pair = observation["pair_kind"]
outcome = observation["outcome"]
finding = observation["finding_type"]
negative = observation["negative_basis"]
expected: tuple[str, ...]
if outcome == "POTENTIAL_INCONSISTENCY_LOCATED":
if pair in {"abstract_results", "discussion_results"}:
expected = ("agent_extracted", "agent_extracted")
elif pair == "methods_reported_analyses":
expected = {
"declared_analysis_no_reported_counterpart": (
"agent_extracted",
"checked_no_match",
),
"reported_analysis_no_declared_counterpart": (
"checked_no_match",
"agent_extracted",
),
"analysis_specification_conflict": (
"agent_extracted",
"agent_extracted",
),
}[finding]
else:
expected = (
"agent_extracted",
"agent_extracted",
"checked_no_match",
)
elif negative == "disclosed_deviation":
expected = ("agent_extracted", "agent_extracted", "agent_extracted")
else:
expected = ("agent_extracted", "agent_extracted")
if states != expected:
_fail(
"DRAFT_CONTRACT_INVALID",
f"{path}.evidence_slots",
f"must use states {expected}",
)
def _preflight_draft_role_matrix(
observations: Sequence[Any],
*,
manifest: Mapping[str, Any],
artifacts: Mapping[str, Mapping[str, Any]],
sidecar: Mapping[str, Any],
fields: set[str],
) -> None:
"""Validate every identity/role/source slot before reading any outcome."""
keys: set[str] = set()
pair_counts = {pair: 0 for pair in PAIR_ORDER}
accepted_id = manifest["accepted_draft_artifact_id"]
for index, item in enumerate(observations):
path = f"draft.observations[{index}]"
observation = _closed(item, path, fields, code="DRAFT_CONTRACT_INVALID")
key = _identifier(
observation["observation_key"],
f"{path}.observation_key",
code="DRAFT_CONTRACT_INVALID",
)
if key in keys:
_fail(
"DRAFT_CONTRACT_INVALID",
f"{path}.observation_key",
"duplicates an earlier key",
)
keys.add(key)
pair = _enum(
observation["pair_kind"],
f"{path}.pair_kind",
frozenset(PAIR_ORDER),
code="DRAFT_CONTRACT_INVALID",
)
pair_counts[pair] += 1
roles = PAIR_ROLES[pair]
raw_slots = _array(
observation["evidence_slots"],
f"{path}.evidence_slots",
code="DRAFT_CONTRACT_INVALID",
minimum=len(roles),
maximum=len(roles),
)
slots = [
_draft_slot(
slot,
f"{path}.evidence_slots[{slot_index}]",
expected_role=role,
accepted_id=accepted_id,
preregistration_id=sidecar["artifact_id"],
)
for slot_index, (slot, role) in enumerate(
zip(raw_slots, roles, strict=True)
)
]
for slot_index, slot in enumerate(slots):
artifact = artifacts[slot["artifact_id"]]
state = slot["evidence_state"]
if state in {"agent_extracted", "checked_no_match", "not_checked"}:
if artifact["artifact_state"] != "present":
_fail(
"DRAFT_CONTRACT_INVALID",
f"{path}.evidence_slots[{slot_index}]",
"requires a present artifact",
)
elif artifact["artifact_state"] != state:
_fail(
"DRAFT_CONTRACT_INVALID",
f"{path}.evidence_slots[{slot_index}]",
"state differs from manifest",
)
if any(count == 0 for count in pair_counts.values()):
_fail(
"DRAFT_CONTRACT_INVALID",
"draft.observations",
"must contain all four pair kinds",
)
def validate_draft(
value: Any,
*,
manifest: Mapping[str, Any],
artifacts: Mapping[str, Mapping[str, Any]],
sidecar: Mapping[str, Any],
) -> list[dict[str, Any]]:
root = _closed(
value,
"draft",
{"schema_version", "layer", "recorded_at", "observations"},
code="DRAFT_CONTRACT_INVALID",
)
if root["schema_version"] != DRAFT_SCHEMA_VERSION or root["layer"] != LAYER:
_fail("DRAFT_CONTRACT_INVALID", "draft", "has wrong schema version or layer")
_timestamp(root["recorded_at"], "draft.recorded_at", code="DRAFT_CONTRACT_INVALID")
observations = _array(
root["observations"],
"draft.observations",
code="DRAFT_CONTRACT_INVALID",
minimum=4,
maximum=MAX_OBSERVATIONS,
)
fields = {
"observation_key",
"pair_kind",
"check_state",
"outcome",
"finding_type",
"negative_basis",
"not_checked_reason",
"deviation_id",
"deviation_domain",
"evidence_slots",
}
_preflight_draft_role_matrix(
observations,
manifest=manifest,
artifacts=artifacts,
sidecar=sidecar,
fields=fields,
)
result: list[dict[str, Any]] = []
keys: set[str] = set()
deviation_ids: set[str] = set()
pair_counts = {pair: 0 for pair in PAIR_ORDER}
accepted_id = manifest["accepted_draft_artifact_id"]
for index, item in enumerate(observations):
path = f"draft.observations[{index}]"
observation = _closed(item, path, fields, code="DRAFT_CONTRACT_INVALID")
key = _identifier(
observation["observation_key"],
f"{path}.observation_key",
code="DRAFT_CONTRACT_INVALID",
)
if key in keys:
_fail(
"DRAFT_CONTRACT_INVALID",
f"{path}.observation_key",
"duplicates an earlier key",
)
keys.add(key)
pair = _enum(
observation["pair_kind"],
f"{path}.pair_kind",
frozenset(PAIR_ORDER),
code="DRAFT_CONTRACT_INVALID",
)
pair_counts[pair] += 1
roles = PAIR_ROLES[pair]
raw_slots = _array(
observation["evidence_slots"],
f"{path}.evidence_slots",
code="DRAFT_CONTRACT_INVALID",
minimum=len(roles),
maximum=len(roles),
)
slots = [
_draft_slot(
slot,
f"{path}.evidence_slots[{slot_index}]",
expected_role=role,
accepted_id=accepted_id,
preregistration_id=sidecar["artifact_id"],
)
for slot_index, (slot, role) in enumerate(
zip(raw_slots, roles, strict=True)
)
]
for slot_index, slot in enumerate(slots):
artifact = artifacts[slot["artifact_id"]]
state = slot["evidence_state"]
if state in {"agent_extracted", "checked_no_match", "not_checked"}:
if artifact["artifact_state"] != "present":
_fail(
"DRAFT_CONTRACT_INVALID",
f"{path}.evidence_slots[{slot_index}]",
"requires a present artifact",
)
elif artifact["artifact_state"] != state:
_fail(
"DRAFT_CONTRACT_INVALID",
f"{path}.evidence_slots[{slot_index}]",
"state differs from manifest",
)
check_state = observation["check_state"]
if not isinstance(check_state, str) or check_state not in {
"performed",
"not_checked",
}:
_fail("DRAFT_CONTRACT_INVALID", f"{path}.check_state", "is invalid")
states = tuple(slot["evidence_state"] for slot in slots)
if check_state == "performed":
if (
not isinstance(observation["outcome"], str)
or observation["outcome"] not in OUTCOMES
):
_fail("DRAFT_CONTRACT_INVALID", f"{path}.outcome", "is invalid")
if observation["not_checked_reason"] is not None:
_fail(
"DRAFT_CONTRACT_INVALID",
f"{path}.not_checked_reason",
"must be null",
)
if observation["outcome"] == "POTENTIAL_INCONSISTENCY_LOCATED":
if (
not isinstance(observation["finding_type"], str)
or observation["finding_type"] not in FINDING_TYPES[pair]
or observation["negative_basis"] is not None
):
_fail(
"DRAFT_CONTRACT_INVALID",
path,
"positive outcome fields are invalid",
)
else:
if (
observation["finding_type"] is not None
or not isinstance(observation["negative_basis"], str)
or observation["negative_basis"] not in NEGATIVE_BASES
):
_fail(
"DRAFT_CONTRACT_INVALID",
path,
"no-listed outcome fields are invalid",
)
negative = observation["negative_basis"]
allowed = (
(
negative == "legitimate_compression"
and pair == "abstract_results"
)
or (
negative == "same_rung_rewording"
and pair in {"abstract_results", "discussion_results"}
)
or (
negative == "disclosed_deviation"
and pair == "manuscript_preregistration"
)
or (
negative == "other_no_listed_observation"
and pair != "manuscript_preregistration"
)
)
if not allowed:
_fail(
"DRAFT_CONTRACT_INVALID",
f"{path}.negative_basis",
"is invalid for pair",
)
_performed_combination(observation, states, path)
else:
if any(
observation[field] is not None
for field in ("outcome", "finding_type", "negative_basis")
):
_fail(
"DRAFT_CONTRACT_INVALID",
path,
"not_checked carries no semantic outcome",
)
reason = _enum(
observation["not_checked_reason"],
f"{path}.not_checked_reason",
NOT_CHECKED_REASONS,
code="DRAFT_CONTRACT_INVALID",
)
if not any(state in FAILURE_STATES for state in states):
_fail(
"DRAFT_CONTRACT_INVALID",
path,
"not_checked requires a failure slot",
)
if reason != _expected_not_checked_reason(pair, slots):
_fail(
"DRAFT_CONTRACT_INVALID",
f"{path}.not_checked_reason",
"contradicts slot-state precedence",
)
if pair == "manuscript_preregistration" and check_state == "performed":
deviation_id = _identifier(
observation["deviation_id"],
f"{path}.deviation_id",
code="DRAFT_CONTRACT_INVALID",
)
if deviation_id in deviation_ids:
_fail(
"DRAFT_CONTRACT_INVALID",
f"{path}.deviation_id",
"must be globally unique",
)
deviation_ids.add(deviation_id)
_enum(
observation["deviation_domain"],
f"{path}.deviation_domain",
DEVIATION_DOMAINS,
code="DRAFT_CONTRACT_INVALID",
)
elif (
observation["deviation_id"] is not None
or observation["deviation_domain"] is not None
):
_fail("DRAFT_CONTRACT_INVALID", path, "deviation fields must be null")
normalized = copy.deepcopy(observation)
normalized["evidence_slots"] = slots
result.append(normalized)
if any(count == 0 for count in pair_counts.values()):
_fail(
"DRAFT_CONTRACT_INVALID",
"draft.observations",
"must contain all four pair kinds",
)
return result
def _source_block(artifact: Mapping[str, Any]) -> dict[str, Any]:
return {
"artifact_id": artifact["artifact_id"],
"document_kind": artifact["document_kind"],
"relative_path": artifact["relative_path"],
"source_artifact_sha256": artifact["source_artifact_sha256"],
"source_artifact_size_bytes": artifact["source_artifact_size_bytes"],
"source_content_sha256": artifact["source_content_sha256"],
"source_content_utf8_bytes": artifact["source_content_utf8_bytes"],
}
def _slice_utf8(raw: bytes, span: Mapping[str, int], path: str) -> tuple[bytes, str]:
start = span["start"]
end = span["end"]
if end > len(raw):
_fail("EVIDENCE_REPLAY_INVALID", path, "extends beyond bound source bytes")
payload = raw[start:end]
try:
text = payload.decode("utf-8", errors="strict")
except UnicodeError as exc:
_fail("EVIDENCE_REPLAY_INVALID", path, f"splits a UTF-8 sequence: {exc}")
return payload, text
def _derive_slot(
slot: Mapping[str, Any],
*,
artifact: Mapping[str, Any],
source_bytes: bytes | None,
path: str,
) -> dict[str, Any]:
state = slot["evidence_state"]
anchor: dict[str, Any]
excerpt: dict[str, Any]
checked_scope: dict[str, Any] | None = None
if state == "agent_extracted":
if source_bytes is None:
_fail("EVIDENCE_REPLAY_INVALID", path, "quote source is unavailable")
span = _span(
slot["quote_source_span_utf8"],
f"{path}.quote_source_span_utf8",
code="EVIDENCE_REPLAY_INVALID",
)
payload, replayed = _slice_utf8(
source_bytes, span, f"{path}.quote_source_span_utf8"
)
decoded = strict_percent_decode(slot["anchor_value_encoded"])
_safe_text(
decoded,
f"{path}.anchor_value_encoded decoded",
code="EVIDENCE_REPLAY_INVALID",
maximum=MAX_EXTERNAL_CODEPOINTS,
)
word_count = len(decoded.split())
if word_count > MAX_EXTERNAL_WORDS:
_fail(
"EVIDENCE_REPLAY_INVALID",
f"{path}.anchor_value_encoded",
f"exceeds {MAX_EXTERNAL_WORDS} words by whitespace split",
)
if decoded != replayed:
_fail(
"EVIDENCE_REPLAY_INVALID",
path,
"decoded quote does not equal exact source span",
)
anchor = {
"kind": "quote",
"value_encoded": slot["anchor_value_encoded"],
"value_decoded": decoded,
}
excerpt = {
"text": decoded,
"excerpt_sha256": _sha256(payload),
"source_span_utf8": span,
"captured_at": slot["captured_at"],
}
else:
anchor = {"kind": "none", "value_encoded": "", "value_decoded": ""}
excerpt = {
"text": None,
"excerpt_sha256": None,
"source_span_utf8": None,
"captured_at": None,
}
if state == "checked_no_match":
if source_bytes is None:
_fail(
"EVIDENCE_REPLAY_INVALID",
path,
"checked scope source is unavailable",
)
block = slot["checked_scope_input"]
span = _span(
block["source_span_utf8"],
f"{path}.checked_scope_input.source_span_utf8",
code="EVIDENCE_REPLAY_INVALID",
)
payload, scope_text = _slice_utf8(
source_bytes,
span,
f"{path}.checked_scope_input.source_span_utf8",
)
if not scope_text.strip():
_fail(
"EVIDENCE_REPLAY_INVALID", path, "checked scope must not be blank"
)
checked_scope = {
"source_span_utf8": span,
"scope_sha256": _sha256(payload),
"scope_utf8_bytes": len(payload),
"checked_at": block["checked_at"],
"completeness_provenance": block["scope_completeness"],
}
sharing_scope, rights_basis = _rights_pair(
slot["sharing_scope"],
slot["rights_basis"],
path,
)
return {
"logical_role": slot["logical_role"],
"source": _source_block(artifact),
"document_locator": copy.deepcopy(slot["document_locator"]),
"evidence_state": state,
"anchor": anchor,
"excerpt": excerpt,
"checked_scope": checked_scope,
"cache": {"status": "not_used", "key_sha256": None},
"content_handling": {
"contains_external_text": state == "agent_extracted",
"sharing_scope": sharing_scope,
"rights_basis": rights_basis,
},
}
def _derive_evidence_row(
observation: Mapping[str, Any],
*,
row_id: str,
artifacts: Mapping[str, Mapping[str, Any]],
sources: Mapping[str, bytes],
) -> dict[str, Any]:
evidence_slots = [
_derive_slot(
slot,
artifact=artifacts[slot["artifact_id"]],
source_bytes=sources.get(slot["artifact_id"]),
path=f"observation.{observation['observation_key']}.evidence_slots[{index}]",
)
for index, slot in enumerate(observation["evidence_slots"])
]
row: dict[str, Any] = {
"schema_version": EVIDENCE_SCHEMA_VERSION,
"surface": SURFACE,
"row_id": row_id,
"pair_kind": observation["pair_kind"],
"observation_key": observation["observation_key"],
"deviation_id": observation["deviation_id"],
"deviation_domain": observation["deviation_domain"],
"evidence_slots": evidence_slots,
"row_sha256": "",
}
row["row_sha256"] = _digest_without(row, "row_sha256")
return row
def _source_bundle_digest(
*,
manifest_sha256: str,
sidecar_sha256: str,
sidecar: Mapping[str, Any],
manifest: Mapping[str, Any],
) -> str:
framing = {
"source_manifest_sha256": manifest_sha256,
"preregistration_record_sha256": sidecar_sha256,
"preregistration_record_digest": sidecar["record_digest"],
"accepted_draft_artifact_id": manifest["accepted_draft_artifact_id"],
"accepted_draft_sha256": manifest["accepted_draft_sha256"],
"artifacts": [copy.deepcopy(item) for item in manifest["artifacts"]],
}
return _sha256(_canonical_bytes(framing))
def _prepare_inputs(
draft: Any,
manifest: Any,
sidecar: Any,
*,
accepted_draft_bytes: bytes,
preregistration_bytes: bytes | None,
) -> tuple[
list[dict[str, Any]],
dict[str, Any],
dict[str, Any],
dict[str, dict[str, Any]],
dict[str, bytes],
]:
accepted_text = _strict_accepted_draft(accepted_draft_bytes)
del accepted_text
if preregistration_bytes is not None:
_strict_source(
preregistration_bytes,
label="preregistration companion",
maximum=MAX_PREREGISTRATION_BYTES,
)
total = len(accepted_draft_bytes) + len(preregistration_bytes or b"")
if total > MAX_TOTAL_SOURCE_BYTES:
_fail("RESOURCE_LIMIT", "sources", "exceed 72 MiB aggregate")
normalized_sidecar = validate_preregistration_artifact(
sidecar,
companion_bytes=preregistration_bytes,
)
normalized_manifest, artifacts = validate_source_manifest(
manifest,
sidecar=normalized_sidecar,
accepted_draft_bytes=accepted_draft_bytes,
)
observations = validate_draft(
draft,
manifest=normalized_manifest,
artifacts=artifacts,
sidecar=normalized_sidecar,
)
sources = {normalized_manifest["accepted_draft_artifact_id"]: accepted_draft_bytes}
if preregistration_bytes is not None:
sources[normalized_sidecar["artifact_id"]] = preregistration_bytes
return observations, normalized_manifest, normalized_sidecar, artifacts, sources
def finalize_advisory(
draft: Any,
manifest: Any,
sidecar: Any,
*,
accepted_draft_bytes: bytes,
preregistration_bytes: bytes | None,
draft_raw: bytes | None = None,
manifest_raw: bytes | None = None,
sidecar_raw: bytes | None = None,
) -> dict[str, Any]:
"""Build the canonical final carrier from all exact named inputs."""
draft_bytes = _binding_bytes(
draft,
draft_raw,
MAX_DRAFT_BYTES,
code="DRAFT_CONTRACT_INVALID",
path="advisory draft",
)
manifest_bytes = _binding_bytes(
manifest,
manifest_raw,
MAX_MANIFEST_BYTES,
code="SOURCE_MANIFEST_INVALID",
path="source manifest",
)
sidecar_bytes = _binding_bytes(
sidecar,
sidecar_raw,
MAX_SIDECAR_BYTES,
code="SOURCE_BINDING_INVALID",
path="preregistration record",
)
observations, normalized_manifest, normalized_sidecar, artifacts, sources = (
_prepare_inputs(
draft,
manifest,
sidecar,
accepted_draft_bytes=accepted_draft_bytes,
preregistration_bytes=preregistration_bytes,
)
)
draft_sha = _sha256(draft_bytes)
manifest_sha = _sha256(manifest_bytes)
sidecar_sha = _sha256(sidecar_bytes)
source_bundle_sha = _source_bundle_digest(
manifest_sha256=manifest_sha,
sidecar_sha256=sidecar_sha,
sidecar=normalized_sidecar,
manifest=normalized_manifest,
)
report_identity_payload = {
"draft_sha256": draft_sha,
"source_manifest_sha256": manifest_sha,
"preregistration_record_sha256": sidecar_sha,
"preregistration_record_digest": normalized_sidecar["record_digest"],
"accepted_draft_artifact_id": normalized_manifest["accepted_draft_artifact_id"],
"accepted_draft_sha256": normalized_manifest["accepted_draft_sha256"],
"source_bundle_sha256": source_bundle_sha,
}
report_id = "XDOC-" + _sha256(_canonical_bytes(report_identity_payload))[:24]
ordered = sorted(
observations,
key=lambda item: (PAIR_ORDER.index(item["pair_kind"]), item["observation_key"]),
)
grouped: dict[str, list[dict[str, Any]]] = {pair: [] for pair in PAIR_ORDER}
for ordinal, observation in enumerate(ordered, start=1):
advisory_id = f"ADV-XDOC-{ordinal:06d}"
row_id = f"EVR-XDOC-{ordinal:06d}"
row = _derive_evidence_row(
observation,
row_id=row_id,
artifacts=artifacts,
sources=sources,
)
grouped[observation["pair_kind"]].append(
{
"advisory_id": advisory_id,
"observation_key": observation["observation_key"],
"pair_kind": observation["pair_kind"],
"check_state": observation["check_state"],
"outcome": observation["outcome"],
"finding_type": observation["finding_type"],
"negative_basis": observation["negative_basis"],
"not_checked_reason": observation["not_checked_reason"],
"deviation_id": observation["deviation_id"],
"deviation_domain": observation["deviation_domain"],
"semantic_provenance": SEMANTIC_PROVENANCE,
"evidence_row": row,
}
)
report: dict[str, Any] = {
"schema_version": REPORT_SCHEMA_VERSION,
"layer": LAYER,
"evaluation_status": EVALUATION_STATUS,
"report_id": report_id,
"input_binding": {
"draft_schema_version": DRAFT_SCHEMA_VERSION,
"draft_sha256": draft_sha,
"source_manifest_schema_version": MANIFEST_SCHEMA_VERSION,
"source_manifest_sha256": manifest_sha,
"preregistration_record_schema_version": SIDECAR_SCHEMA_VERSION,
"preregistration_record_sha256": sidecar_sha,
"preregistration_record_digest": normalized_sidecar["record_digest"],
"accepted_draft_artifact_id": normalized_manifest[
"accepted_draft_artifact_id"
],
"accepted_draft_sha256": normalized_manifest["accepted_draft_sha256"],
"source_bundle_sha256": source_bundle_sha,
},
"pair_results": [
{"pair_kind": pair, "observations": grouped[pair]} for pair in PAIR_ORDER
],
"boundary": copy.deepcopy(BOUNDARY),
"report_digest": "",
}
report["report_digest"] = _digest_without(report, "report_digest")
if len(_canonical_bytes(report)) > MAX_FINAL_BYTES:
_fail("RESOURCE_LIMIT", "final advisory", "canonical output exceeds 32 MiB")
return report
def validate_advisory(
advisory: Any,
draft: Any,
manifest: Any,
sidecar: Any,
*,
advisory_raw: bytes,
accepted_draft_bytes: bytes,
preregistration_bytes: bytes | None,
draft_raw: bytes | None = None,
manifest_raw: bytes | None = None,
sidecar_raw: bytes | None = None,
) -> None:
expected = finalize_advisory(
draft,
manifest,
sidecar,
accepted_draft_bytes=accepted_draft_bytes,
preregistration_bytes=preregistration_bytes,
draft_raw=draft_raw,
manifest_raw=manifest_raw,
sidecar_raw=sidecar_raw,
)
_require_exact_final(advisory, advisory_raw, expected)
def _require_exact_final(advisory: Any, advisory_raw: bytes, expected: Any) -> None:
if not isinstance(advisory_raw, bytes):
_fail("FINAL_ARTIFACT_INVALID", "advisory", "raw binding must be bytes")
if len(advisory_raw) > MAX_FINAL_BYTES:
_fail("RESOURCE_LIMIT", "final advisory", "exceeds 32 MiB")
parsed = _strict_json_bytes(
advisory_raw,
code="FINAL_ARTIFACT_INVALID",
path="final advisory",
)
expected_bytes = _canonical_bytes(expected)
if (
advisory_raw != expected_bytes
or _canonical_bytes(parsed) != expected_bytes
or _canonical_bytes(advisory) != expected_bytes
):
_fail(
"FINAL_ARTIFACT_INVALID",
"advisory",
"is not the exact canonical deterministic replay",
)
def _markdown_inert(value: Any) -> str:
if value is None:
return "NOT CHECKED"
result: list[str] = []
for character in str(value):
if character.isascii() and (character.isalnum() or character == " "):
result.append(character)
else:
result.append(f"&#{ord(character)};")
return "".join(result)
def paginate(
items: Sequence[Any], *, page: int, page_size: int
) -> tuple[list[Any], int]:
if isinstance(page, bool) or not isinstance(page, int) or page < 1:
_fail("FINAL_ARTIFACT_INVALID", "page", "must be a positive integer")
if (
isinstance(page_size, bool)
or not isinstance(page_size, int)
or page_size < 1
or page_size > MAX_PAGE_SIZE
):
_fail("FINAL_ARTIFACT_INVALID", "page_size", "must be within 1..25")
total_pages = max(1, (len(items) + page_size - 1) // page_size)
if page > total_pages:
_fail("FINAL_ARTIFACT_INVALID", "page", f"must not exceed {total_pages}")
start = (page - 1) * page_size
return list(items[start : start + page_size]), total_pages
def render_advisory(
advisory: Mapping[str, Any], *, page: int = 1, page_size: int = 25
) -> str:
observations = [
observation
for pair_result in advisory["pair_results"]
for observation in pair_result["observations"]
]
visible, total_pages = paginate(observations, page=page, page_size=page_size)
report_sha = _sha256(_canonical_bytes(advisory))
lines = [
f"# Cross-document consistency advisory — Page {page}/{total_pages}",
"",
"Layer: LLM-ADVISORY",
"Evaluation status: UNMEASURED",
f"Report ID: {_markdown_inert(advisory['report_id'])}",
f"Report SHA-256: {report_sha}",
f"Rows: {len(observations)} total; {len(visible)} on this page",
"",
"NO LISTED INCONSISTENCY LOCATED — not proof of agreement, completeness, or a clean document.",
"",
"| Advisory | Pair | State | Observation | Left | Right | Disclosure | Result | Evidence |",
"|---|---|---|---|---|---|---|---|---|",
]
for observation in visible:
row = observation["evidence_row"]
slots = row["evidence_slots"]
display_slots: list[str] = []
for slot in slots:
locator = slot["document_locator"]
if slot["evidence_state"] == "agent_extracted":
evidence = slot["anchor"]["value_decoded"]
elif slot["evidence_state"] == "checked_no_match":
evidence = "CHECKED NO MATCH"
else:
evidence = "NOT CHECKED"
display_slots.append(
f"{slot['logical_role']} @ {locator['kind']}: {locator['value']} — "
f"{slot['evidence_state']} — {evidence}"
)
while len(display_slots) < 3:
display_slots.append("not applicable")
if observation["outcome"] == "NO_LISTED_INCONSISTENCY_LOCATED":
result = f"{observation['outcome']} — {observation['negative_basis']}"
else:
result = (
observation["finding_type"]
or observation["not_checked_reason"]
or observation["outcome"]
)
evidence_ref = f"{row['row_id']} / {row['row_sha256']}"
values = (
observation["advisory_id"],
observation["pair_kind"],
observation["check_state"],
observation["observation_key"],
display_slots[0],
display_slots[1],
display_slots[2],
result,
evidence_ref,
)
lines.append(
"| " + " | ".join(_markdown_inert(value) for value in values) + " |"
)
lines.append("")
if page > 1:
lines.append(f"Previous: `--page {page - 1} --page-size {page_size}`")
if page < total_pages:
lines.append(f"Next: `--page {page + 1} --page-size {page_size}`")
lines.append("")
return "\n".join(lines)
def _load_runtime_inputs(args: argparse.Namespace) -> dict[str, Any]:
sidecar, sidecar_raw = _load_json(
args.preregistration_record,
MAX_SIDECAR_BYTES,
code="SOURCE_BINDING_INVALID",
label="preregistration record",
)
companion_bytes = (
_read_named_bytes(
args.preregistration_companion,
MAX_PREREGISTRATION_BYTES,
label="preregistration companion",
unreadable_code="SOURCE_BINDING_INVALID",
)
if args.preregistration_companion is not None
else None
)
accepted_bytes = _read_named_bytes(
args.accepted_draft,
MAX_ACCEPTED_DRAFT_BYTES,
label="accepted draft",
)
manifest, manifest_raw = _load_json(
args.manifest,
MAX_MANIFEST_BYTES,
code="SOURCE_MANIFEST_INVALID",
label="source manifest",
)
# Establish all source/sidecar/manifest bindings before parsing semantic outcomes.
_strict_accepted_draft(accepted_bytes)
if companion_bytes is not None:
_strict_source(
companion_bytes,
label="preregistration companion",
maximum=MAX_PREREGISTRATION_BYTES,
)
if len(accepted_bytes) + len(companion_bytes or b"") > MAX_TOTAL_SOURCE_BYTES:
_fail("RESOURCE_LIMIT", "sources", "exceed 72 MiB aggregate")
normalized_sidecar = validate_preregistration_artifact(
sidecar,
companion_bytes=companion_bytes,
)
validate_source_manifest(
manifest,
sidecar=normalized_sidecar,
accepted_draft_bytes=accepted_bytes,
)
draft, draft_raw = _load_json(
args.draft,
MAX_DRAFT_BYTES,
code="DRAFT_CONTRACT_INVALID",
label="advisory draft",
)
return {
"sidecar": sidecar,
"sidecar_raw": sidecar_raw,
"companion_bytes": companion_bytes,
"accepted_bytes": accepted_bytes,
"manifest": manifest,
"manifest_raw": manifest_raw,
"draft": draft,
"draft_raw": draft_raw,
}
def _expected_from_loaded(loaded: Mapping[str, Any]) -> dict[str, Any]:
return finalize_advisory(
loaded["draft"],
loaded["manifest"],
loaded["sidecar"],
accepted_draft_bytes=loaded["accepted_bytes"],
preregistration_bytes=loaded["companion_bytes"],
draft_raw=loaded["draft_raw"],
manifest_raw=loaded["manifest_raw"],
sidecar_raw=loaded["sidecar_raw"],
)
def _parser() -> argparse.ArgumentParser:
parser = _ClosedArgumentParser(description=__doc__, allow_abbrev=False)
commands = parser.add_subparsers(dest="command", required=True)
sidecar = commands.add_parser("build-preregistration-artifact", allow_abbrev=False)
sidecar.add_argument("--status", required=True, choices=sorted(SIDECAR_STATES))
sidecar.add_argument("--artifact-id", required=True)
sidecar.add_argument("--declared-at", required=True)
sidecar.add_argument("--relative-path")
sidecar.add_argument("--artifact-provenance")
sidecar.add_argument("--companion", type=Path)
sidecar.add_argument("--output", type=Path, required=True)
for name in ("finalize", "validate", "render"):
command = commands.add_parser(name, allow_abbrev=False)
command.add_argument("--draft", type=Path, required=True)
command.add_argument("--manifest", type=Path, required=True)
command.add_argument("--preregistration-record", type=Path, required=True)
command.add_argument("--preregistration-companion", type=Path)
command.add_argument("--accepted-draft", type=Path, required=True)
if name in {"validate", "render"}:
command.add_argument("--advisory", type=Path, required=True)
if name in {"finalize", "render"}:
command.add_argument("--output", type=Path)
if name == "render":
command.add_argument("--page", type=int, default=1)
command.add_argument("--page-size", type=int, default=25)
return parser
def main(argv: Sequence[str] | None = None) -> int:
try:
args = _parser().parse_args(argv)
if args.command == "build-preregistration-artifact":
companion = (
_read_named_bytes(
args.companion,
MAX_PREREGISTRATION_BYTES,
label="preregistration companion",
)
if args.companion is not None
else None
)
_reject_output_alias(args.output, (args.companion,))
record = build_preregistration_artifact(
status=args.status,
artifact_id=args.artifact_id,
declared_at=args.declared_at,
companion_bytes=companion,
relative_path=args.relative_path,
artifact_provenance=args.artifact_provenance,
)
_atomic_write(args.output, _canonical_bytes(record))
return 0
loaded = _load_runtime_inputs(args)
expected = _expected_from_loaded(loaded)
if args.command == "finalize":
payload = _canonical_bytes(expected)
if args.output is None:
sys.stdout.buffer.write(payload)
else:
_reject_output_alias(
args.output,
(
args.draft,
args.manifest,
args.preregistration_record,
args.preregistration_companion,
args.accepted_draft,
),
)
_atomic_write(args.output, payload)
return 0
advisory, advisory_raw = _load_json(
args.advisory,
MAX_FINAL_BYTES,
code="FINAL_ARTIFACT_INVALID",
label="final advisory",
)
_require_exact_final(advisory, advisory_raw, expected)
if args.command == "validate":
print("Cross-document consistency advisory validation passed (#672).")
return 0
rendered = render_advisory(expected, page=args.page, page_size=args.page_size)
if args.output is None:
sys.stdout.write(rendered)
else:
_reject_output_alias(
args.output,
(
args.draft,
args.manifest,
args.preregistration_record,
args.preregistration_companion,
args.accepted_draft,
args.advisory,
),
)
_atomic_write(args.output, rendered.encode("utf-8"))
return 0
except AdvisoryError as exc:
print(f"ADVISORY_UNAVAILABLE:{exc.code}", file=sys.stderr)
return 2
except (
IndexError,
KeyError,
OSError,
RecursionError,
TypeError,
UnicodeError,
ValueError,
):
print("ADVISORY_UNAVAILABLE:FINAL_ARTIFACT_INVALID", file=sys.stderr)
return 2
__all__ = [
"AdvisoryError",
"DRAFT_SCHEMA_VERSION",
"EVIDENCE_SCHEMA_VERSION",
"EVALUATION_STATUS",
"LAYER",
"MANIFEST_SCHEMA_VERSION",
"MAX_PAGE_SIZE",
"REPORT_SCHEMA_VERSION",
"SIDECAR_SCHEMA_VERSION",
"SURFACE",
"build_preregistration_artifact",
"finalize_advisory",
"main",
"paginate",
"render_advisory",
"strict_percent_decode",
"validate_advisory",
"validate_preregistration_artifact",
"validate_source_manifest",
]
if __name__ == "__main__":
raise SystemExit(main())
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| add-product-e2e-evalpaperclipai/paperclipAdd or extend a Paperclip full-stack runner E2E workflow, fixture, matcher, or report evidence path for local or Daytona execution. | Stars: 115k | Updated | Claude CodeCodex | Verified | Install |
| add-runner-evalpaperclipai/paperclipAdd or extend a Paperclip Runner protocol evaluation definition, roster, assertion, or report fixture with provenance and narrow validation. | Stars: 115k | Updated | Claude CodeCodex | Verified | Install |
| diagnose-why-work-stoppedpaperclipai/paperclipCompatibility entry point for failed, stalled, looping, or over-recovered Paperclip work. Use fix-failed-paperclip-run for the full diagnosis, regression, repair, real verification, and green-PR workflow; honor an explicitly requested diagnosis-only scope. | Stars: 115k | Updated | Claude CodeCodex | Verified | Install |
| fix-failed-paperclip-runpaperclipai/paperclipDiagnose and fix failed, stuck, slow, or incorrectly blocked Paperclip tasks and runs. Use with a task/run URL or failure report to trace the root cause, prove a regression red then green, check second-order effects, verify the real workflow, and deliver a PR with passing checks. | Stars: 115k | Updated | Claude CodeCodex | Verified | Install |