GEO Design Auditor — 1.0.1

This repository is the first working slice of a provenance-aware tool that reconstructs and audits the experimental design of public GEO studies.

Version 1.0.1 is the privacy-hygiene patch release. It removes owner-specific local paths from the current source and artifacts without changing product or scientific behavior. The original public 1.0.0 release remains available as historical release evidence.

Start here

Use Python 3.11, 3.12, 3.13, or 3.14 in a fresh virtual environment and install the exact public patch release from PyPI:

python -m venv .venv
python -m pip install geo-design-auditor==1.0.1
python -m pip check
geo-audit --version

Run a preliminary GEO Series audit into a new output directory:

geo-audit GSE123456 --out geo_audit_output

Launch the local GUI with geo-gui. The GUI can inspect canonical artifacts and build an offline PEP/acquisition preview; it does not silently run acquisition, R, publication, or human review.

The five installed commands are geo-audit, geo-pep-import, geo-acquisition-plan, geo-workflow, and geo-gui. The first four expose COMMAND --help for their exact argument contract. The GUI accepts only normal launch, geo-gui --smoke, and geo-gui --version; it does not provide geo-gui --help. Every command supports COMMAND --version for installed identity.

Read the documentation index for the quick start, evidence/provenance model, publication boundary, PEP/acquisition workflow, statistics, GUI, limitations, privacy/security, case studies, contribution, citation, and unreleased release notes. The most important boundary is: metadata and deterministic checks do not establish biological identity, independence, pairing, replication, analysis readiness, causality, or scientific truth. Those conclusions remain unresolved unless an explicit validated human-review contract supports them.

What the release candidate does

Given a public GEO Series accession such as GSE123456, it:

1. Validates the accession.
2. Downloads the official GEO Series-family SOFT record from NCBI.
3. Preserves the complete original source document and retrieval provenance.
4. Parses Series and Sample metadata.
5. Creates a conservative normalized sample table.
6. Runs deterministic checks for:
   • missing submitted subject-identifier labels;
   • repeated submitted subject-identifier labels;
   • missing condition/group labels;
   • perfect condition–batch confounding.
7. Exports an integrated start-here Markdown report, a canonical researcher summary, an enriched researcher sample table, an output index, the legacy JSON/CSV records, and original SOFT text.

It does not claim that a study is fully analysis-ready. The default audit still uses GEO Series-family SOFT only. An opt-in repository-evidence mode can now reconcile explicit GEO, BioSample, and SRA accessions, but it does not establish biological identity, replication, independence, experimental groups, or statistical suitability. Default behavior still excludes publication and supplementary content. The opt-in publication-evidence workspace described below accepts only an already canonical evidence bundle and metadata-only discovery; it acquires no raw publication or supplement content.

The codebase now defines two standalone 1.0.0 contracts for that later publication-aware workflow: geo-design-auditor/publication-evidence and geo-design-auditor/publication-authority-policy. T-0009 composes these contracts only when geo-audit receives the explicit --publication-evidence-bundle PATH option. The evidence contract preserves source identity, hashes, exact typed locators, extraction and review state, scope, limitations, explicit unavailable/refused evidence, and the caller's bounded provision/rights-basis record. Structural validation does not prove that access or redistribution is lawful, that a named human acted, or that scientific review occurred. The generic policy states what each source class may contribute for a material field without ranking sources or selecting a winning value. Agreement remains evidence-only; biological identity, independence, pairing, repeated measures, lineage, replication, inclusion, group/contrast meaning, and design promotion remain genuine human-review decisions supplied through separate validated review contracts; the publication-evidence bundle cannot mint reviewed scientific decisions. Discovery and acquired-evidence population are separate milestones. The standalone geo-design-auditor/publication-discovery 1.0.0 contract now records metadata-only candidates and their exact GEO source occurrences from Series_pubmed_id, Series BioProject relations, and Series/Sample supplementary-file fields. Its bounded NCBI resolution surface is limited to PubMed, PMC, and BioProject identity metadata through approved ESummary, exact named pubmed_pmc ELink, and exact bounded ESearch operations. PMC linkage or open-access-filter membership does not establish a license or redistribution permission.

T-0019 ordinary PEP import

T-0019 integrates a separate explicit local-only PEP 2.1 import boundary. Its command surface is:

geo-pep-import INPUT --output OUTPUT [--amend NAME ...]

INPUT is one caller-selected project configuration YAML or CSV-only PEP. --amend is repeatable and preserves the caller's amendment order. OUTPUT is one canonical, content-addressed JSON provenance manifest. Its parent directory must already exist and must not be a link/reparse path. A missing output is installed without overwrite; exact existing canonical bytes are an idempotent success; a different, linked, non-regular, or concurrently appearing output is refused. UNC, NT-namespace and drive-relative forms, alternate-data-stream colons, and reserved Windows device names in every path component are refused before any filesystem access. Windows uses a private same-directory stage with handle-bound deletion; supported Linux uses an unnamed O_TMPFILE plus linkat(AT_EMPTY_PATH). Other POSIX platforms/filesystems fail before creating the output rather than leave a persistent stage or weaken identity safety.

The bounded importer uses pinned PyYAML 6.0.3 behind a project-owned worker protocol. It admits only the closed ordinary contract implemented by T-0019 and fails closed on unsupported or unsafe input. Before reading bytes, it binds the opened regular-file handle to the exact requested lexical path; it then double-reads and rechecks every admitted source identity before returning. It caps each source at 1,000,000 bytes, all sources at 8,000,000 bytes and 32 documents, import depth at 10, each table at 256 columns, rows/cells/decoded value bytes at 10,000/100,000/2,000,000 both per table and across all tables, transformations at 200,000, and the serialized before/after transformation evidence at 8,000,000 UTF-8 JSON bytes in aggregate, and the canonical manifest at 4,000,000 bytes. The YAML worker also caps depth at 20, nodes at 20,000, collection items at 10,000, tokens at 40,000, each scalar at 256,000 UTF-8 bytes, output at 2,000,000 bytes, elapsed time at 15 seconds, and process memory at 256 MiB. Its in-memory result retains exact YAML source bytes, raw table headers/cells, processed records, and ordered transformation detail. YAML content is recoverable byte-for-byte from the source documents; a second public parsed-YAML value graph is intentionally not exposed. The durable canonical manifest instead contains only minimized source locator/media/hash/count, table locator/header hash/count/row/column plus plaintext index-header names, processed counts/header hashes, safe transformation pointers plus hashed identifiers and attributes/presence flags, ordered import/amendment provenance, and fixed nonclaims. Index-header names are its only plaintext header facts. Non-index header names, cells, sample/processed values, raw configuration/table bytes and metadata, and before/after values are absent; non_index_header_or_cell_values_embedded is fixed false. The importer performs no automatic project discovery, environment expansion, remote resolution, GEO or NCBI request, upstream-tool execution, or biological download. It does not activate peppy, eido, GEOfetch, looper, or pipestat, and the default geo-audit command and outputs are unchanged.

The bundled JSON Schema is the closed structural interchange contract. Runtime validation is the authoritative relational layer: it additionally checks canonical content identity, ordered amendment and import lineage, transformation phase and project-target relations, table/index and processed-count relations, aggregate bounds, and source-pointer bounds that JSON Schema cannot derive from minimized cross-item content. Neither layer authenticates a rewritten manifest against source bytes that are intentionally absent; source binding is established by the importer while those bytes are present.

PEP is caller-provided project metadata, not original evidence authority. A successful import does not establish authenticity, donor/subject identity, biological units, independence, pairing, replication, groups, comparisons, review, analysis readiness, or scientific truth. Original GEO, repository, and publication evidence remains separate. T-0020 still owns deterministic standard PEP export and its separately linked audit sidecar.

This surface is integrated provisional-local and postvalidated as T-0019 at 3/3. That task alone does not satisfy any v1 requirement. Its completion snapshot brings the metadata-only benchmark corpus to exactly 4,073,661 bytes across 92 files under a narrowly raised 4,080,000-byte ceiling, leaving 6,339 bytes of headroom without adding raw PEP inputs to benchmarks/.

T-0020 audited PEP export

T-0020 provides an integrated separate library that emits deterministic PEP 2.1 configuration and tables plus a content-linked audit.sidecar.json and pep-export-index.json. Standard PEP files contain no audit or product-private fields. The initial envelope accepts only processed values it can serialize and re-import without invention: string scalars and tuple values that are the exact ordered projection of supplied processed subsample rows. Unsupported or ambiguous value shapes refuse rather than coerce.

The sidecar binds an exact validated T-0019 import and researcher audit summary at project-context level only. It does not establish biological units, identity, independence, pairing, groups, comparisons, review, readiness, or scientific truth. T-0020 adds no installed command or dependency; T-0023 retains end-to-end CLI orchestration. The output index explicitly records that no publisher or handled-failure rollback is implemented, so the bundle makes no filesystem-installation claim. The task is validated and integrated provisional-local at 3/3. It does not claim publication, requirement satisfaction, or release readiness.

T-0021 acquisition preview candidate

T-0021 adds a project-owned, side-effect-free acquisition inventory and dry-run selection plan. Callers provide already-observed raw-run or processed-file candidates with public source/evidence identity, exact/estimated/unknown size status, an optional expected SHA-256, and a safe target name. The inventory binds a validated T-0020 export; the plan binds the exact canonical inventory bytes, preserves an explicit unique selection order, and reports exact totals and missing execution policy.

The local command accepts only a canonical inventory on standard input and writes one canonical plan to standard output:

geo-acquisition-plan --select acquisition-asset:sha256:IDENTIFIER < inventory.json > plan.json

The command performs no discovery, network access, file write, download, or GEOfetch invocation. Every plan records that destination, free-space, overwrite, resume, integrity execution, and the executor itself remain T-0022 work. Neither the inventory nor the plan establishes acquisition need, evidence authority, biological identity, comparison, analysis readiness, or scientific truth. T-0021 is validated and integrated provisional-local at 3/3. It does not satisfy a v1 requirement alone or authorize execution; T-0022 retains every download and filesystem-effect gate.

T-0022 bounded acquisition execution

T-0022 adds a project-owned executor for the narrow subset of validated T-0021 plan rows that already have an exact positive byte count, expected SHA-256, safe target name, and public HTTPS locator. The caller supplies one existing local destination. The executor assesses reserved free space, writes only create-once plan-bound state and targets, resumes verified partial bytes, checks the final size and digest, and emits a minimized content-addressed acquisition-execution.json. One destination-global lock prevents different plans from publishing competing target sets.

Unknown or estimated sizes, missing integrity, FTP/null sources, raw-provider resolution, unsafe destinations, foreign targets, and overwrites refuse. The default transport disables proxy discovery and enforces same-origin HTTPS redirects and exact response/range lengths; focused tests use only tiny injected bytes and perform no live download. Completed private partials and manifest staging links are retained as plan-bound recovery evidence rather than deleted through a racy path; a digest-invalid owned single-link partial is handle-reset so an explicit retry can restart safely. No command or dependency is added here; T-0023 owns end-to-end CLI orchestration. Successful transfer does not establish acquisition need, source authority, rights, biological identity, comparison, readiness, or scientific truth. T-0022 is validated and integrated provisional-local at 4/4. It does not by itself satisfy a v1 requirement or authorize unplanned/provider-driven downloads; T-0023 owns end-to-end orchestration.

T-0023 end-to-end workflow CLI

geo-workflow composes the bounded PEP import, audited PEP export, explicit acquisition inventory, ordered selection plan, and optional T-0022 execution without changing any underlying contract. The user supplies one local PEP, one canonical researcher-audit-summary JSON document, one closed observation document, repeated exact target-name selections, and one fresh output directory. With no execution destination the complete command is offline:

geo-workflow project_config.yaml \
  --audit-summary researcher-summary.json \
  --observations acquisition-observations.json \
  --select-target processed-counts.tsv.gz \
  --output-dir audited-workflow

The observation document has exactly schema, schema_version, and a nonempty observations array. Its schema is geo-design-auditor/acquisition-observations version 1.0.0; every row uses the exact public AcquisitionObservation fields. Selected rows must already provide a public HTTPS locator, exact positive size, expected SHA-256, safe unique target name, accession, and source evidence digest/pointer. The command never discovers or guesses those values.

Add --execute-destination EXISTING_DIR only to delegate the exact selected plan to T-0022. The fixed workflow directory contains standard PEP files, separate audit sidecar and PEP index, canonical acquisition inventory/plan, optional execution provenance, and workflow-output-index.json. Publication is create-only and idempotent for an exact existing directory; handled failure never exposes a partial requested output directory, although one private deterministic staging directory may remain for inspection or manual cleanup and is never treated as authoritative output. Acquisition effects are not rolled back if later output publication fails. Stdout contains only the workflow ID, publication status, and invocation execution outcome. Neither the command nor its index establishes evidence authority, acquisition need, rights, biological identity, comparison, readiness, or scientific truth.

T-0024 bounded statistics eligibility

T-0024 adds a pure library boundary that evaluates one explicitly supplied count matrix and reviewed design against the narrow OD-0008 contract. It accepts only bulk RNA-seq, gene-level nonnegative integer counts with an exact one-to-one sample-column binding, and either two reviewed independent groups with at least three biological units per group or three or more complete reviewed two-condition pairs. Eligible decisions fix ~ group or ~ unit + condition, an explicit comparison-minus-reference contrast, DESeq2's negative-binomial GLM, standard median-ratio size factors, Wald testing with an explicit Wald-statistic semantic, unshrunken log2 fold change, raw p-value, BH-adjusted p-value, and a descriptive adjusted-p-value < 0.05 flag. The evaluator returns only eligibility and method metadata; it does not fit a model or emit any of those inferential values.

Unsupported assay or matrix semantics, malformed counts, a matrix with no gene positive in every sample (for which the approved standard median-ratio estimator is undefined), missing or duplicate bindings, unresolved biological-unit/independence/replication/pair authority, technical replicates, incomplete pairs, fewer than three units, arbitrary covariates/batches/surrogate variables/interactions, rank deficiency, non-estimable contrasts, confounding, and source/design conflict are hard refusals. The evaluator never drops a sample, imputes a value, repairs a pair, guesses independence, or turns matrix rank into scientific authority. Organism, tissue or cell type, assay, outcome, gene namespace, and biological-unit meaning are copied as caller-supplied compatibility facts for later gates.

The adjacent environment artifact originated in T-0024 as the exact R 4.6.1, Bioconductor 3.23, and DESeq2 1.52.0 reference selection. T-0025 has now matured those same bytes into a clean installed environment lock: it records the exact 74-package version/license inventory, platform identity, executable and inventory hashes, and repeated synthetic-reference identity. T-0024 itself still installed or invoked nothing and its eligibility artifact still reports no fit or result. R is recorded as GPL-2 | GPL-3 and DESeq2 as LGPL (>= 3) from their official release pages. No Python dependency, globally discoverable command, real count matrix, biological result, power conclusion, readiness claim, or scientific conclusion is added by the lock maturation.

T-0025 single-study execution boundary

T-0025's integrated library service turns only an eligible T-0024 candidate plus exact UTF-8 count-matrix bytes and explicit input authority into a deterministic private bundle: counts.csv, design.csv, fixed analysis.R, and a canonical content-addressed request manifest. The source content ID must carry the exact raw matrix SHA-256. Synthetic inputs must say synthetic-reference; real inputs require a separate real-input-authority identity. The service does not discover a matrix, infer a design, accept arbitrary R code, expose an output command, or publish files.

The generated code fixes the already reviewed formula, comparison-minus-reference contrast, standard median-ratio size factors, DESeq2 negative-binomial model, Wald test, unshrunken log2 fold change, raw p-value, BH-adjusted p-value, and descriptive FDR flag. It accepts counts only through R's exact nonnegative integer range and never drops or imputes a row, column, value, unit, or pair. Gene and sample identifiers remain exact character data even when they look numeric. Result validation requires the descriptive flag to equal adjusted_p_value < 0.05 (or NA when adjusted p-value is NA); it is not an independently supplied interpretation. The local execution boundary uses one explicitly supplied regular Rscript file, --vanilla, a private temporary directory, no shell, fixed arguments, a 1,800-second timeout, suppressed process output, an allowlisted environment, and canonical result validation. Its durable manifest contains hashes, counts, versions, method and nonclaims—not a private executable path or raw biological interpretation.

A private ignored project-scoped R 4.6.1/Bioconductor 3.23/DESeq2 1.52.0 environment now passes the product probe without PATH or registry discovery. Its exact 74-package inventory is frozen in benchmarks/statistics/r_environment.lock.json. A deterministic 100-gene synthetic reference ran twice and produced byte-identical result tables; the canonical non-interpreting result manifest is benchmarks/statistics/single_study_analysis.reference.json. This establishes software execution and reference reproducibility only. Probe and execution require the lock's exact executable and inventory identities; a merely self-consistent caller record is insufficient. It is not real biological evidence, and every real fit still requires separate exact input authority. T-0025's clean reference, review, validation and identical-tree integration are complete; they do not turn the synthetic output into evidence about a real study.

T-0026 deterministic study-effect artifact

T-0026 adds a pure offline presentation/provenance layer over one validated T-0025 request/result pair. build_study_effect_artifact(result, request_manifest_bytes=...) verifies the request/result link and input kind, exact result-table bytes, the canonical T-0025 executable/inventory hashes and counts, the fixed generated R-code binding, canonical row structure and the approved D-0022 method. It invokes no R process, network, file discovery, filesystem write, threshold chooser or new statistical calculation.

The frozen bundle contains the unchanged study-effects.csv, exact analysis.R, an accessible deterministic effect-uncertainty.svg, effect-report.md, and a content-addressed manifest. The plot uses every row having both a finite unshrunken log2 fold change and finite reported standard error; rows are never sorted, filtered, ranked or imputed. Standard error is shown directly as the approved uncertainty value. The layer does not invent a confidence interval, volcano transformation, gene selection, differential-expression verdict, cross-study compatibility, readiness, causal effect, clinical meaning or biological interpretation.

This presentation layer deliberately caps effect tables at 100,000 rows even though T-0025 admits a larger analysis input. That is a bounded presentation-specific refusal, not a change to T-0025 or a claim that every valid T-0025 result is renderable. The manifest retains the exact design/formula and contrast labels needed to regenerate and validate the Markdown report byte-for-byte; Markdown code spans are escaped without changing those labels.

The builder is an in-memory API only; T-0026 adds no command or publisher. Its tracked synthetic reference is a minimized manifest that binds the genuine repeated T-0025 reference identities and generated artifacts without tracking the result table, R code, SVG, Markdown report, private runtime, or any real fitted input/output.

T-0027 exact study compatibility gate

T-0027 adds a pure offline compatibility gate over two distinct validated T-0025 request manifests and their exactly bound T-0026 effect manifests. Distinctness is enforced across request IDs, source IDs and their exact source-byte SHA-256 values, so changing an allowed source-ID prefix cannot turn one matrix into two studies. It compares the eleven D-0022 fields—organism, tissue/cell type, assay, outcome, gene-identifier namespace, biological-unit meaning, design class, contrast direction, model, normalization and effect scale—using UTF-8 byte-exact equality only.

compatible_exact means every frozen field is identical under this narrow v1 contract. Any exact difference yields refused_field_difference and an ordered mismatch list. Neither status establishes biological equivalence or scientific incompatibility. The gate performs no normalization, ontology or synonym lookup, identifier mapping, unit conversion, batch harmonization, analysis-readiness decision or meta-analysis authorization.

build_study_compatibility(left_request, left_effect, right_request, right_effect) returns a frozen content-addressed manifest plus deterministic Markdown report. Runtime validation closes both request/effect bindings, ordered hashes/states, overall result and exact report bytes. The API performs no R invocation, network access, filesystem write, command publication or scientific inference.

For release validation, compare_study_compatibility_fields(left_fields, right_fields) exposes the same exact comparator without claiming that both profiles already have effect artifacts. T-0035 uses that narrow preflight against the genuine GSE184237 fit and the already-reviewed public GSE161357 design. It refuses five exact fields. GSE161357's submitted Gene / CPM files remain normalized, contain submitted missing rows, and are never relabeled as integer counts or fitted. A full canonical T-0027 manifest still requires two valid request/effect pairs.

T-0028 compatibility-gated meta-analysis

T-0028 adds a library-only study-level meta-analysis over two or more distinct T-0026 effect manifest/table pairs and a connected set of canonical T-0027 compatible_exact manifests. The builder closes every request, effect, source-byte and compatibility identity, requires all eleven compatibility fields to remain exact, and refuses raw-count merging, cross-study DESeq2 fitting, batch correction, unsupported configurations, aliases and disconnected or incompatible study sets. Exact compatibility permits consideration of pooling; it does not establish identical true effects or population equivalence.

For each gene, every finite unshrunken comparison-minus-reference log2 fold change with a finite strictly positive standard error contributes once. Missing and zero-SE values are recorded and not imputed; fewer than two valid studies yields pooled_effect_unavailable for that gene without stopping other genes. The primary normal-normal random-effects fit explicitly uses REML, 1/(SE^2 + tau^2) weights, and metafor's modified-HKSJ adhoc interval with k - 1 degrees of freedom. It reports tau-squared, tau, Q/df/descriptive p-value and I-squared; prediction is available only for k >= 5; leave-one-study-out is available only for k >= 3; and the three fixed sensitivity models are REML/Wald, Paule-Mandel/modified-HKSJ and common-effect/Wald.

build_meta_analysis, probe_meta_analysis_environment, and execute_meta_analysis return closed request, environment and result records. Result artifacts contain the pooled table, raw/normalized study weights, leave-one-out and sensitivity rows, explicitly requested forest data/SVG, report and environment inventory. Forest genes are never selected from results. Publication-bias diagnostics remain publication_bias_not_assessed or publication_bias_diagnostic_unsupported; no pooled p-values, BH flags, automatic study deletion, causal/biological/clinical conclusion or interval-based scientific verdict is produced.

Execution requires the exact ignored project-local R 4.6.1 overlay recorded by benchmarks/statistics/meta_analysis_environment.lock.json: metafor 5.0-1 plus its five pinned overlay dependencies. Runtime verification binds both tracked locks, the live T-0025 package inventory, exact local library search path/package origins, all overlay files, and the runtime dependency trees. The existing T-0025 site library and lock remain unchanged. The tracked statistical reference uses synthetic effects only and proves deterministic software/reference behavior, not a real-study fit or finding.

The v1 real/reference release-validation boundary is explicit: GSE184237 supplies the genuine reviewed real T-0025/T-0026 execution; source-backed GSE161357 supplies a genuine exact-field refusal; and independently constructed compatible reference effects validate the real T-0028 implementation. No evidence claims that v1 performed a real two-study Alzheimer disease meta-analysis. Real pooling requires at least two genuine study effects that independently pass the unchanged T-0027 gate.

Discovery never fetches a PDF, full text, supplement, structured file, matrix, raw sequence file, or archive. Supplementary-file links remain inventory-only; recognized raw-sequence and archive forms are explicitly refused without retrieval. Every candidate states that content acquisition was not attempted, rights and redistribution are not established, and design promotion was not applied; the manifest boundary also states that scientific review was not performed. T-0009 uses this metadata-only discovery contract only in the explicit publication-workspace mode; it does not acquire any discovered candidate content.

The separate geo-design-auditor/publication-pdf-intake 1.0.0 contract accepts already supplied PDF bytes through a bounded text-only adapter; it performs no discovery or network request. User files use a logical basename and remain not-for-redistribution. A lawful-open intake requires the caller to supply exact public HTTPS source and rights-basis locators, but the contract records that claim as not independently verified. A T-0005 candidate, HTTP availability, PMC indexing, embedded PDF metadata, or license-like document prose cannot establish lawful access or redistribution.

PDF intake hashes the exact original bytes, runs a pinned parser in an isolated worker, records parser/version and fixed limits, and retains physical 1-based page identities, derived-text hashes and counts, and explicit PDF-outline section occurrences through title hashes, ordinals and exact page-character spans. Raw page labels, outline titles, PDF/page bytes and full page text are omitted from the manifest; bounded extracted text exists only in the in-memory result for later field selection. Canonical PMID, PMCID, and DOI identifiers are the only accepted external publication IDs. The caller explicitly classifies unbound bytes as publication or supplement; an exact T-0005 GEO supplementary-file binding always forces supplement, because a .pdf suffix does not establish a publication role. Public intake and manifest-validation failures expose only fixed error codes and do not retain raw nested exception text.

The worker applies stream_decoded_byte_limit = 1,000,000 to each decoded stream touched by pypdf, page_content_decoded_byte_limit = 1,000,000 cumulatively to each page's /Contents plus recursively referenced Form XObjects, total_page_content_decoded_byte_limit = 8,000,000 across those page-content streams for the document, and a 256 MiB process-memory ceiling. The document-total 8 MB value is not a claim that every parser-decoded stream is globally totaled.

The adapter refuses encrypted, malformed, oversized, active-content, attachment, form/XFA, rich-media, external-action, and unsupported image-only inputs. It does not render pages, extract images, run OCR, follow links, execute actions, create a reviewer, classify scientific fields, or promote a design. T-0008 owns field reconciliation, while T-0009 composes only an already canonical T-0004 bundle through the opt-in CLI workspace. The default output remains unchanged.

The separate geo-design-auditor/structured-file-intake 1.0.0 contract accepts already supplied bytes only; it opens no local path and performs no network request. Its public adapters require the caller to classify each source explicitly as processed_data or supplement. A T-0005 structured- file binding never chooses that role. For lawful-open intake, its exact candidate URL must equal the source URL. For user-provided intake, the binding is metadata identity only: it does not prove that the caller's logical file is the candidate locator, format or bytes, or that either has a particular source role. Supported suffixes are .csv, .tsv, .txt, .xlsx, .csv.gz, .tsv.gz, and .txt.gz; the adapter neither sniffs a format nor accepts gzip-wrapped XLSX. User files remain not for redistribution. Lawful-open input records caller-supplied source and rights-basis locators without independently proving access, license validity, study association, or redistribution permission.

A user logical basename and lawful-open source/rights-basis URLs remain durable source identity in the manifest after bounded screening for recognizable credential, private-path, direct-identifier, contact and sensitive-demographic patterns. The caller must still minimize these values before intake: the screening is necessarily incomplete, the raw accepted locator remains durable, and neither that screening nor hashing or schema validation proves that a manifest contains no personal data, is anonymous, or received human privacy review.

Text formats decode strictly as UTF-8. One optional leading UTF-8 BOM is removed solely as an encoding marker and recorded in parser provenance; a BOM without subsequent content is empty and refused. CSV is fixed to comma, TSV to TAB, with strict standard quoting and no delimiter, header, or type inference. Multiline quoted values retain their physical start/end line locators. TXT is one value per physical line, including empty lines; the line terminator is not part of the value. Formula-looking CSV, TSV, or TXT content is inert source text. NUL and unsupported controls are refused.

The manifest hashes the exact original bytes and records file, table or worksheet, row, column and A1-style cell locators. Raw values and raw worksheet names are returned only in the bounded in-memory result. The durable manifest retains each raw cell value's hash and UTF-8 byte/character counts, but only the hash of a raw worksheet name; it does not claim a worksheet-name count. Ingest recomputes the source hash and byte count from the supplied bytes. Standalone validation of a manifest, even with matching canonical manifest bytes, checks internal coherence and cannot authenticate that source bytes not supplied to it match those recorded values. XLSX uses pinned openpyxl==3.1.5 with an explicitly selected defusedxml backend in an isolated worker. It refuses formulas, external relationships, macros, embedded objects, merged cells, unsafe XML, encrypted or malformed ZIP packages, and unsupported spreadsheet forms rather than evaluating, following, or flattening them. XLSX missing-cell versus explicitly blank-cell identity is not established.

XLSX manifests record the openpyxl parser version and the selected defusedxml XML-backend name. Exact defusedxml and et-xmlfile versions remain pinned environment and third-party-notice facts; they are not represented as separate manifest version fields. JSON Schema covers the closed schema-expressible structure. Runtime validation additionally closes content IDs, aggregate counts, references and source/binding invariants, so schema acceptance alone is not equivalent to successful runtime validation.

The closed limits are 10,000,000 input bytes; 8,000,000 gzip-decoded bytes; 256,000 UTF-8 bytes per cell; 2,000,000 UTF-8 bytes across observed cells; 64 tables or sheets; 10,000 rows per table; 1,024 columns; and 10,000 observed cells total. XLSX additionally allows at most 512 ZIP members, 8,000,000 decoded bytes per member, and 32,000,000 decoded package bytes. The worker is limited to 4,000,000 output bytes, 15 seconds, and 256 MiB. These bounds deliberately refuse large processed matrices. Intake does not interpret headers or values, select scientific fields, establish missingness, reconcile sources, create a reviewer, infer biological units or other relationships, or promote a design. T-0008 owns those bounded reconciliation decisions; T-0009 does not expose raw structured-file intake or field selection through the CLI.

Integrated T-0010: explicit GEO TSV declaration

Integrated T-0010 implements one backward-compatible structured-intake 1.1.0 path and is fully postvalidated. A caller may explicitly declare tsv only for a logical .txt or .txt.gz source. The parser does not sniff content or infer the override, and an absent declaration retains byte-identical 1.0.0 behavior. A declaration/suffix mismatch refuses rather than reinterpreting the source. All existing source, decoded, cell, row, column and worker limits remain unchanged.

The bounded real-source case is the official GSE198683 gzip-wrapped series matrix: 4,268 source bytes with SHA-256 9f0a7f0f0b5aebe90c3dd3a4c6fc227de36df4e5493772b0ef211a75735866be, and 65,477 decoded bytes with SHA-256 52abbb114ce57d97284884a40f8f8a2660d4916c62c679f9b64b0ecab8d41a5e. Strict TSV parsing reports 75 rows and 791 observed cells without assigning header, sample, field or scientific meaning. The first 503,176-byte gzip-wrapped per-sample count file expands to 1,779,046 bytes and remains a deterministic greater-than-10,000-row row_limit refusal under the explicit declaration. The unchanged suffix-only 1.0.0 path classifies both .txt.gz sources as line-oriented TXT and safely refuses their TAB bytes as control_character; caller-declared TSV is the only compatibility path. Neither source's raw bytes will be committed; only minimized canonical identities, receipts, locators, unreviewed candidates and fixed nonclaims are in scope.

The public StructuredFileIntakeError exposes a fixed code and context-free message. Its closed codes group invalid/provenance/binding and unsupported-format input; source, decoded, cell, table, row, column, archive-member and worker-output limits; encoding, control, gzip and malformed input; encrypted, unsafe, duplicate or unsupported archive structure; XML, active-content, external-link, formula and merged-cell refusals; and worker timeout, crash or protocol failures. Raw locators, values, parser exceptions and nested exception details are not public error content.

The separate geo-design-auditor/publication-reconciliation 1.0.0 contract compares a validated T-0004 publication-evidence bundle under the exact validated T-0004 non-ranking authority policy. It performs no discovery, network request, byte intake, PDF/spreadsheet parsing, or CLI/report integration. The artifact binds the input bundle and policy by canonical-byte SHA-256 and content ID; embeds their complete source inventory, field statements, unavailable evidence and field rules; and emits one result for each of the policy's 38 material fields. Every input statement retains its source, exact value and representation, four-part scope, extraction/review state and locators. No result contains a resolved, winning, preferred or canonical field value.

Automated output is deliberately limited to unavailable, single_source_only, exact_agreement, not_comparable, and unresolved_conflict. No statements yield unavailable; one distinct contributing source yields single_source_only. exact_agreement requires at least two distinct sources, byte-identical values and value representations, and complete identical entity, cohort, version and temporal scopes. Incomplete or different scope, or a different value representation, yields not_comparable. Otherwise, differing exact values remain unresolved_conflict. The engine performs no trimming, case folding, fuzzy matching, unit conversion, synonym mapping, specificity/recency ranking, majority vote or source precedence.

compatible_representation is absent because no closed versioned compatibility rule exists in this task; visual or semantic similarity is not enough. confirmed_contradiction is absent because the authority policy reserves it for genuine human review. Exact agreement corroborates only the retained source statements; it does not establish authenticity, biological/cohort/entity equivalence, study design, analysis eligibility or scientific truth.

The explicit select_pdf_field_statement and select_structured_field_statement helpers construct one unreviewed T-0004 machine-extracted candidate from already supplied bounded in-memory intake results. The caller must name the material field, exact source and redundant exact locator. PDF selection uses one half-open page-character span and retains page plus outline-section provenance; the section ID is context, not an inferred section extent. Structured selection uses an exact table/worksheet, row, column and cell coordinate. The helpers record their fixed method/version and no additional transformation. They do not infer a field from a header, prose, value, filename, co-occurrence or source kind. A separate geo-design-auditor/publication-reconciliation-review-packet 1.0.0 projection prepares neutral inspection rows from a validated reconciliation artifact. It preserves the artifact binding, sources, statements, locators, scopes, statuses and unresolved actions, while creating no reviewer identity, decision, timestamp, approval, rejection, confidence, compatible-representation rule, confirmed contradiction or design promotion. A later genuine reviewed lifecycle must supply any such authority. Exact embedded T-0004 statement review objects remain unchanged, including their null reviewer_id; packet-created objects add no reviewer field. The packet contains exactly 38 human_review_needs, one per material field; every decision_status is human_review_required. Its neutral need is respectively acquire_or_document_evidence, review_single_source_evidence, review_exact_agreement_without_promotion, review_scope_or_representation_limits, or resolve_source_scoped_conflict for the five automated statuses. These are inspection prompts, not completed decisions.

Both artifacts are canonical, content-addressed, closed and bounded. Reconciliation is limited to 4,000,000 bytes, JSON depth 32 and 100,000 items; the exact embedded-artifact packet is limited to 6,000,000 bytes, depth 40 and 150,000 items. JSON Schema covers the schema-expressible structure; runtime validation additionally recomputes identities, hashes, counts, ordering, reference closure, exact input copies and state invariants. Schema acceptance by itself does not authenticate source bytes, a person, rights, privacy review or scientific review. T-0008 remains the standalone reconciliation authority. T-0009 composes it in the opt-in publication workspace without changing its scientific boundaries; T-0010+ own real GSE198683 evidence and human-review work.

Field selection refuses through a fixed context-free PublicationFieldSelectionError code. Packet validation likewise exposes only invalid_input, artifact_invalid, packet_invalid, content_id_invalid, or bounds_exceeded. Neither public error surface retains raw selected values, locators or nested parser exceptions.

The default GEO transport is fail-closed. It accepts only the exact canonical Series-family URL, HTTP 200, an approved gzip media type, identity/no content encoding, and a matching complete Content-Length when supplied. It follows no redirect, reads at most 16 MiB of compressed data, decompresses at most 64,000,000 bytes across no more than 128 valid gzip members, and decodes UTF-8 strictly. Size, framing, encoding, content, URL, and requested-versus-parsed accession failures are sanitized and are not retried; only a closed set of transient transport/status failures receives bounded retry. The published _source.soft is the exact UTF-8 parser representation without platform newline translation. These limits deliberately refuse larger metadata documents rather than reading them without a bound.

Why no AI yet?

The initial scientific claims should come from explicit records, reproducible rules, and statistical checks. Ambiguous metadata are surfaced for manual review rather than guessed. AI can later assist with paper prose and cryptic sample names, but it should not invent counts, links, or statistical conclusions.

Install

Requires Python 3.11 or newer.

The runtime dependency pypdf==6.15.0 is pinned for deterministic text-only PDF parsing. GEO Design Auditor does not install pypdf's cryptography or image extras; encrypted and image-only documents receive controlled refusal states. See THIRD_PARTY_NOTICES.md.

python -m venv .venv

# Windows PowerShell
.venv\Scripts\Activate.ps1

# macOS/Linux
source .venv/bin/activate

pip install -e ".[dev]"

Run

geo-audit GSE123456 \
  --comparison "rheumatoid arthritis vs healthy control" \
  --out results \
  --email your.email@example.com

Or:

python -m geo_design_auditor GSE123456 --out results

For a forced-color interactive capture or an explicitly plain log:

geo-audit GSE123456 --out results --color always
geo-audit GSE123456 --out results --color never

Opt-in publication-evidence workspace

T-0009 adds one explicit composition path:

geo-audit GSE123456 \
  --out results \
  --publication-evidence-bundle evidence/GSE123456_publication_evidence.json \
  --ncbi-cache-dir results/ncbi-metadata-cache/production-v1 \
  --ncbi-offline

--publication-evidence-bundle PATH must identify a regular non-symlink file whose maximum size is exactly 2,000,000 bytes and whose bytes are already exact canonical geo-design-auditor/publication-evidence version 1.0.0 JSON. The bundle accession must equal both the requested and parsed GEO Series accession. An oversized, unsafe, or noncanonical bundle is refused before publication through a stable, context-free public error; paths, content, and nested exception text are not exposed. This mode performs only bounded T-0005 metadata discovery from the validated GEO document and existing NCBI cache/client boundary, then applies the fixed T-0004 authority policy and builds the T-0008 source-preserving reconciliation plus its neutral review packet. Discovery is metadata-only: no linked PDF, supplement, structured file, arbitrary URL, or other raw content is opened or acquired.

A successful opt-in invocation adds exactly these six current-invocation artifacts:

GSE123456_publication_discovery.json
GSE123456_publication_evidence.json
GSE123456_publication_authority_policy.json
GSE123456_publication_reconciliation.json
GSE123456_publication_review_packet.json
GSE123456_publication_review.md

The output index registers them under the closed publication_evidence source layer and never discovers stale output-directory files. The neutral Markdown has an exact maximum of 1,000,000 bytes; exceeding that limit refuses the workspace before any publication artifact is installed. The Markdown is an identity/status workspace, not a review decision. This path does not ingest raw publication files, select material fields, establish rights or source equivalence, choose a winning value, authenticate a reviewer, promote a design, or claim analysis readiness. Omitting --publication-evidence-bundle preserves the existing command behavior and output bytes; none of the six conditional artifacts is then produced.

The output folder contains:

GSE123456_source.soft
GSE123456_study.json
GSE123456_samples.csv
GSE123456_audit.json
GSE123456_report.md
GSE123456_researcher_summary.json
GSE123456_researcher_samples.csv
GSE123456_outputs.json

GSE123456_report.md is the integrated, researcher-facing start-here report. The audit JSON and legacy sample CSV retain their existing schemas and scientific behavior; the report intentionally now projects the validated layers that participated in the current invocation.

Researcher-facing audit bundle

Every normal invocation writes one validated researcher-summary model and renders the terminal, primary Markdown report, researcher sample CSV, and output index from that shared model. The output index contains only artifacts from the current invocation, identifies the start-here file, and does not discover stale files left by a prior run. The primary report presents these sections in a fixed order:

1. Study overview.
2. Comparison context.
3. Retrieval and optional-layer status.
4. Repository coverage.
5. Recovered structured fields.
6. Experimental factors.
7. Factor combinations.
8. Sample-level structure.
9. Submitted identifier groups.
10. Relationship evidence.
11. Cross-database consistency.
12. Material discrepancies.
13. Missing metadata.
14. Unresolved dimensions.
15. Human-review lifecycle.
16. Layered status and overall verdict.
17. Scope and limitations.
18. Output index.
19. Provenance summary.

Console presentation, color, and accessibility

The default terminal view is a concise, width-aware orientation to the validated run: study and comparison context, overall status, repository coverage, reviewed factors when available, material warnings, and the start-here report. Narrow terminals use compact or stacked rows instead of forcing wide tables. Deterministic preview limits and explicit truncation notices still apply. Use --verbose when the terminal should also show the detailed layer inventory, exact source selectors, complete relationship-dimension inventory, sample details, and complete current-invocation output list. Concise and verbose views consume the same validated summary and make no different scientific decision.

--color accepts auto, always, or never and defaults to auto. Automatic color is emitted only for an interactive terminal. A redirected stream or file is plain text, and the presence of the NO_COLOR environment variable disables automatic color. --color always is the explicit override for a caller that intentionally wants ANSI escapes in a pipe; --color never always produces plain terminal text. Generated Markdown, CSV, JSON, SOFT, and other output files never contain ANSI escape sequences under any color mode.

When leading, trailing, repeated, or control whitespace is required to distinguish submitted display values, the console quotes the value and makes that whitespace visible (for example, a space as \u0020). This is presentation escaping, not normalization: the structured summary and provenance retain the actual characters unchanged. Literal quote and backslash characters are escaped within this notation so they cannot collide with an escaped-whitespace display.

The supplemental semantic legend is:

Console token	Color	Boundary
GEO repository labels	Cyan	Repository presentation only.
BioSample repository labels	Magenta	Does not merge BioSample with GEO.
SRA repository labels	Blue	Does not turn Experiments or Runs into replicates.
General NCBI labels	Neutral terminal color	NCBI is the umbrella organization; it is not the BioSample namespace.
GSE/GSM, SAMN/SAME/SAMD, and SR/ER/DR P/S/X/R-family accessions	Repository color on the prefix only	The accession remains readable in plain text.
Experimental-factor names	Deterministic orange/violet/teal/rose/gold/lavender accents with a 16-color fallback	Assignment is stable and has no analytical meaning.
Literal Yes / No values	Bright green / bright red	Submitted values remain exact; color does not mean scientifically good or bad.
Completed or reconciled status	Bright green	Status text remains present.
Partial, unresolved, candidate, or manual-review status	Bright yellow	Color is not a suitability verdict.
Failed or conflicting status	Bright red	The exact status and explanation remain visible.
Not requested, not supplied, unavailable, or not applied	Gray/dim	These states are not converted into negative evidence.
Reviewed / observed / derived evidence	Bold blue / neutral emphasis / cyan-teal	Evidence category remains literal and is not an analysis-readiness scale.

Color is never the only information channel: repository names, accession prefixes, literal values, status words, warning text, and symbols remain visible without it. The plain redirected form is the accessibility and automation baseline. Color, terminal width, and --verbose affect presentation only; they do not alter the researcher-summary model, evidence categories, warnings, verdict, generated files, or output identities.

A mapped GSE198683 run therefore begins its plain at-a-glance block like this (colors supplement the same visible text on a supported interactive terminal):

2. At a glance
  [OK] 16 GEO Samples
  [OK] 2 reviewed experimental factor(s); 4 descriptive combination(s)
  [REVIEW] 4 submitted identifier presentation label(s); candidate evidence
  [OK] GEO/BioSample/SRA reconciliation completed
  [CONFLICT] 1 material conflict(s) from executed reviewed checks
  [REVIEW] Biological relationships unresolved
  [REVIEW] Overall status: manual_review_required

When --comparison is supplied, the terminal and report additionally display its exact text as Researcher-supplied context (not parsed) after the publication-safety check. Unsafe comparison text fails closed and is not written. Accepted text does not create groups, select a contrast, or establish analysis eligibility. The summary separately states whether reviewed design reconstruction or statistical assessment has been applied.

Each layer reports one closed status: completed, partial, failed, not_requested, not_supplied, unavailable, not_applied, or conflicting. A requested optional-layer failure returns a documented nonzero status, preserves the valid core and integrated outputs, marks the failed layer and any unavailable dependent layer, and omits invalid optional artifacts. A failure is never rendered as proof that metadata are absent. Core GEO retrieval or parsing failure remains fatal.

The layer rows cover the normal GEO audit, characteristic inventory, reviewed key mapping, cross-database evidence, relationship evidence, human relationship review, reviewed design input, design contract, design reconstruction, assessment specification, and comparison assessment. A normal exploratory run does not scan benchmark directories to fill any of those states.

The integrated repository-coverage table separates unique accessions found, requested, retrieved, linked, and reconciled from unavailable accessions. Missing, duplicate, and conflict counts are affected GSM mapping rows. SRA Runs are retrieved topology records and are not cross-source- reconciled. Status is reported independently for each repository object as reconciled, repository_topology, partial, conflicting, unavailable, or the applicable layer-derived not_requested/failed state; a linked accession that was not retrieved remains unavailable.

Researcher-facing statements retain the distinctions observed, derived, candidate, reviewed, inferred, unresolved, unavailable, conflicting, and not_assessed. No new biological inference is introduced. In particular:

• exact structured fields and their levels are observed;
• factor cross-tabs are derived and descriptive only, not a synthetic combined condition, reviewed group, contrast, or statistical design;
• source-scoped submitted identifier groups are candidates, not confirmed subjects, donors, specimens, biological units, or independent observations;
• equal presentation labels or memberships from GEO and BioSample are shown adjacently but are not merged or treated as equivalent; and
• GSM, SAMN, SRS, SRX, and SRR remain repository records. SRA Run counts describe repository topology, not technical replicates or independent observations.

The source-metadata portion of the integrated projection is privacy-fail-closed. It preserves field presence, coverage, and distinct-value counts. Safe exact keys may be projected without a reviewed role; exact values require an explicitly reviewed, permitted role and safety screening. Unreviewed values, sensitive demographic/contact/name content, URLs, phone-like values, local paths, unrestricted source prose, and GEO Sample titles are withheld; a sensitive key is replaced by an explicit marker. The authoritative characteristic inventory, parsed study record, and decoded SOFT provenance remain separate, and published paths inside the integrated bundle are repository- relative rather than local filesystem paths.

The console previews the first eight samples in canonical order. Markdown shows the full table through 40 samples and otherwise shows a disclosed canonical prefix; the complete output remains one GSM per row in <GSE>_researcher_samples.csv. The console shows at most 16 observed factor- combination rows. Markdown independently bounds observed and missing-theoretical combination tables at 64 rows each; its incomplete-sample and within-label tables have their own disclosed bounds. Theoretical Cartesian enumeration is not attempted above 256 combinations. CSV cells that would exceed 8,192 characters contain a deterministic summary and content hash that points to the complete researcher-summary JSON.

The default integrated bundle does not auto-load benchmark material, retrieve papers or supplements, infer physical identity, independence, pairing, repeated measures, lineage, or replication, parse the comparison into a design, calculate rank or estimability, or issue a new comparison-specific suitability verdict. Advanced inventory, graph, relationship, review, contract, reconstruction, and assessment artifacts remain the authoritative inputs for detailed provenance and expert validation when explicitly requested or supplied. Publication rolls back handled in-process failures but does not claim process-crash atomicity across the full output set. Publication also fails closed above 64 outputs, 64,000,000 bytes for one artifact, or 256,000,000 bytes for the complete in-memory output set; the current serializer may temporarily retain multiple byte copies while validating and staging a run.

Opt-in GEO–BioSample–SRA accession evidence

Add --cross-db-evidence to retrieve and reconcile explicit repository identifiers:

python -m geo_design_auditor GSE198683 \
  --out results \
  --cross-db-evidence \
  --ncbi-cache-dir results/ncbi-metadata-cache/production-v1 \
  --email your.email@example.com

The study output directory then contains three additional files:

GSE198683_evidence_graph.json
GSE198683_accession_map.csv
GSE198683_cross_db_appendix.md

New versioned JSON graphs use schema 1.1.0 and keep GEO Series, GEO Sample, BioSample, SRA Study, SRA Sample, SRA Experiment, SRA Run, and BioProject as distinct repository entities. Every observed edge points to source-located evidence and a response record containing the exact request scope, URL, retrieval timestamp, HTTP status when available, byte count, and SHA-256. Deterministic cross-source comparisons are separate derived reconciliation records. No inferred relationship is emitted.

Explicit Series-level SRP and PRJNA relations remain Series-level; they are not repeated as per-GSM mappings or treated as equivalent merely because they co-occur. Parser-visible SRA library strategy/source/selection/layout fields are retained in a separate source-scoped descriptor catalog owned by the exact SRX record. A descriptor has no repository accession or graph node and does not identify a specimen, biological unit, replicate, or independent observation. Historical graph 1.0.0 payloads remain accepted and are not rewritten; they cannot contain the new entity, edge, descriptor, or source-document forms.

The CSV is an inspection view anchored at exactly one row per Series-member GEO Sample. Multi-valued SAMN, SRS, SRX, and SRR cells use sorted |-separated accessions. Multiple runs remain in one GSM row; run counts must not be interpreted as biological sample, subject, replicate, or independent-observation counts.

The Markdown appendix is a deterministic, researcher-readable view of the validated in-memory graph. It is derived from the same ordered accession-map rows; its accession fields use the same deterministic values, while SRR accessions are summarized as a run count. It reports repository-record and mapping-status counts, explains graph issues with source-located evidence references, and summarizes source-response provenance. It performs no additional retrieval, does not reparse raw responses, and does not load benchmark fixtures.

Mapping statuses have deliberately narrow repository-identity meanings:

• consistent: the compared explicit repository accession statements agree;
• supported_one_source: an explicit mapping is supported by one source but lacks cross-source confirmation;
• incomplete: some requested or needed repository evidence could not be checked;
• ambiguous: multiple distinct identifiers or repeated qualified-identifier occurrences leave the repository evidence unresolved;
• conflicting: explicit repository accession statements disagree; and
• unavailable: a required explicit accession relation is absent, so that part of the mapping cannot be evaluated.

supported_one_source and incomplete are not labeled as conflicts. Agreement confirms repository identifiers only; disagreement is not evidence of biological mislabeling, fraud, or general study untrustworthiness. The appendix can require manual review for affected mappings, but that flag is separate from and does not change the normal GEO audit verdict.

The source-provenance table reports the repository, request type, requested and resolved accession counts, retrieval timestamp, response byte count, and SHA-256 held by the graph. Evidence-graph schemas 1.0.0 and 1.1.0 do not retain cache-versus-network origin, so the appendix identifies that field as not represented rather than reconstructing it from transport state. A response hash identifies the retrieved response bytes represented in provenance; a separate parser-input hash identifies any transformed bytes used for parsing. Neither proves that repository content is biologically correct or authentic.

This appendix evaluates repository identity and accession consistency only. It does not establish subjects, donors, specimens, biological units, pairing, repeated measures, technical or biological replication, independence, experimental groups, assay correction, statistical suitability, or general study trustworthiness. A zero-issue appendix means only that no cross-database accession discrepancy was detected within the checked repository evidence; it does not establish that the mapping is complete or that no manual review is needed.

The optional cache uses the existing immutable, hash-verified NCBI metadata-cache format. A repeat run can prohibit NCBI network access and require verified cache hits (GEO SOFT retrieval still uses the existing GEO client):

python -m geo_design_auditor GSE198683 \
  --out results \
  --cross-db-evidence \
  --ncbi-cache-dir results/ncbi-metadata-cache/production-v1 \
  --ncbi-offline

Keep full-source cache bodies under an ignored, trusted local results/ directory. They are not written into any of the three opt-in outputs. The graph retains only public repository accessions and necessary request/source provenance; it excludes BioSample owner/contact fields, titles, unrestricted prose, and unrelated Attributes. The appendix uses curated graph references such as node, edge, reconciliation, source-document, selector, and locator identifiers; it does not copy unrestricted source prose or arbitrary BioSample Attributes.

Without --cross-db-evidence, no BioSample or SRA client is constructed, no corresponding network request is made. The legacy audit JSON and sample CSV retain their existing semantics and the GEO warning/verdict rules are unchanged. The integrated report and researcher outputs instead record that cross-database evidence was not_requested; when the option is used, they summarize the validated reconciliation and link to the three specialized artifacts.

Opt-in biological-relationship evidence

Add --relationship-evidence together with --cross-db-evidence to construct the first provenance-backed biological-relationship evidence layer from the metadata already retrieved for the repository graph:

python -m geo_design_auditor GSE198683 \
  --out results \
  --cross-db-evidence \
  --relationship-evidence \
  --ncbi-cache-dir results/ncbi-metadata-cache/production-v1 \
  --email your.email@example.com

--relationship-evidence requires --cross-db-evidence. Supplying it alone is a usage error; it does not silently enable BioSample or SRA retrieval. Relationship construction reuses the validated GEO, BioSample, SRA, and evidence-graph inputs from the same execution and makes no additional metadata request.

The study output directory then contains two more files:

GSE198683_relationship_evidence.json
GSE198683_relationship_map.csv

The JSON follows geo-design-auditor/relationship-evidence schema version 1.0.0. It pins the input evidence-graph identity and SHA-256 and keeps repository records separate from submitted labels and candidate biological entities. The CSV has exactly one row per Series-member GEO Sample, with separate exact-label columns for submitted subject, donor, specimen, culture, pair, repeated-measure, replicate, and timepoint evidence; multiple SRA Runs, candidate groups, and claims never multiply rows.

The versioned semantic-role rules are deliberately narrow. A rule enumerates an explicit key and records whether the comparison was exact or case-insensitive. Recognized relationship keys may include explicit individual, subject, donor, specimen, culture or cell-line, pair, replicate, and timepoint identifiers. Aliases are enumerated separately; punctuation, whitespace, and underscore variants are not silently merged. Generic keys such as sample, sample id, name, id, group, and source are ambiguous and cannot construct relationships. Roles are never inferred from values.

GEO observations preserve the exact characteristic key and value at the existing parser boundary: the parser strips whitespace surrounding the complete SOFT metadata value, after which key/value substrings remain unchanged. BioSample observations preserve exact parser-visible XML text and complete Attribute qualifiers, not lexical XML spelling. Values remain source-scoped and are never trimmed, case-normalized, ontology-normalized, merged across sources, or resolved by majority vote or source preference. Similar-looking values that are not exactly equal remain separate evidence and may require manual review.

Relationship statements have explicit boundaries:

• Observed statements reproduce a structured submitted label with its source locator and provenance.
• Derived statements apply only deterministic operations, such as identifying distinct GSMs that contain the same exact submitted label.
• Candidate entities and claims describe exact-label groupings, not accepted subject, specimen, pairing, replicate, or biological-unit truth.
• Inferred biological conclusions are absent from automated output or remain explicitly unresolved with human review required.

The layer does not infer relationships from titles, sample or accession order, equal group sizes, numeric proximity, shared organism, tissue, treatment, source name, repository-identifier similarity, XML shape, or SRA Run or Experiment counts. In particular, multiple Runs do not establish technical replication, and different submitted labels do not prove different physical subjects or specimens.

Only relationship-relevant structured values are eligible for these outputs. Owner and contact data, names and emails, unrestricted titles or BioSample Attributes, exact ages, ancestry, complete quasi-identifying combinations, arbitrary prose or URLs, raw response bodies, and sequence or download metadata are excluded. A coded value is published only when an approved closed key rule matches and the fail-closed publication-safety check accepts the exact value and, for BioSample, its complete qualifier tuple. Empty, prose-like, contact-like, unsupported, or otherwise unsafe values are withheld, form no candidate entity, and leave the affected relationship unavailable or requiring manual review. Published coded study labels still carry documented study-scoped contextual-linkage risk and must not be used to reconstruct identifiable people.

The five-study benchmark defines a strict automation boundary. A full cross-database GSE198683 execution produces eight source-scoped candidate entities representing four unique GSM membership sets: four GEO entities retain the separator-adjacent leading whitespace in their exact values, and four BioSample entities retain the corresponding XML text without that whitespace. They are not normalized or merged; the exact-value disagreement remains ambiguous and requires manual review. The four unique membership sets reproduce the narrow membership evidence in the human-reviewed oracle, but automated candidates do not import reviewer acceptance. The GSE51518 title-derived E/L pair proposals are not reproduced, and GSE52202 Run sets are not classified as replicates. Relationship evidence remains unavailable for GSE161357 and GSE184237; no placeholder claim is fabricated, and the known GSE184237 assay discrepancy is not corrected.

Identical submitted labels support shared labeling only, not physical identity. Missing labels do not prove independence, candidate groups must not replace GEO Sample counts automatically, and ambiguous or conflicting evidence requires manual review. These files do not change the legacy audit JSON, warnings, severity, verdict, or statistical-suitability conclusion. When supplied in the same invocation, the integrated Markdown report accurately projects their validated status and bounded findings. They are not a determination of biological independence.

Human relationship-review lifecycle

The production review workflow is a separate offline overlay on an already-published canonical evidence pair. Before either review command can run, these files must already exist under <out>/<GSE>/:

<GSE>_evidence_graph.json
<GSE>_relationship_evidence.json

Create that pair first with the normal --cross-db-evidence --relationship-evidence retrieval workflow. Later, generate a deterministic review template with:

python -m geo_design_auditor GSE198683 \
  --out results \
  --cross-db-evidence \
  --relationship-evidence \
  --relationship-review-template

Although the two evidence flags remain required as explicit mode dependencies, template generation loads the saved pair and returns before constructing a GEO or NCBI client. It performs no GEO, BioSample, or SRA retrieval and never regenerates or rewrites either evidence file. It publishes only:

GSE198683_relationship_review.template.json

The template is a draft: it leaves the reviewer identity and date null, assigns no approval, and initializes every reviewable candidate, claim, conflict, and unresolved relationship without making a human decision. Template publication fails if that filename already exists, so the tool never rewrites or overwrites an in-progress review.

After a reviewer edits the template or a separate copy, validate it with:

python -m geo_design_auditor GSE198683 \
  --out results \
  --cross-db-evidence \
  --relationship-evidence \
  --relationship-review path/to/completed_relationship_review.json

--relationship-review-template and --relationship-review PATH are mutually exclusive, and both require --cross-db-evidence plus --relationship-evidence. Validation is also offline: it loads the same saved canonical pair, makes no GEO or NCBI request, and never rewrites those files. It reads the supplied review without modifying or copying it and publishes only:

GSE198683_relationship_review_validation.json

Review schema geo-design-auditor/relationship-review version 1.0.0 supports lifecycle states draft, pending_review, approved, rejected, and superseded. Individual decisions are accepted, rejected, unresolved, needs_additional_evidence, or not_applicable. Generated templates never fill reviewer fields or dates and never auto-approve a decision. Completed states require reviewer identity human-reviewer:<provider>:<public-account-handle>, a real ISO YYYY-MM-DD review date, and the exact closed rationale pair for every decision. This validates a public-account-shaped identifier syntactically; it does not authenticate the account or prove that the person controlling it performed the review. Provider and handle segments start with an ASCII letter or digit, then use only letters, digits, ., _, or -; their maximum lengths are 32 and 64 characters respectively. The derived summary uses geo-design-auditor/relationship-review-validation version 1.0.0.

draft requires null reviewer identity and date. pending_review permits either a null or valid reviewer identity but still requires a null date. approved, rejected, and superseded require both completed reviewer fields. The generated draft's placeholder unresolved decisions retain a null rationale code and empty review text. Once a reviewer acts on an item—and for every item in a completed lifecycle state—the decision-to-rationale mapping is fixed and accepts no free-form substitution:

Decision	Required rationale code	Required fixed review text
accepted	limited_interpretation_supported	The exact evidence references support only the permitted bounded interpretation.
rejected	interpretation_not_supported	The exact evidence references do not support the permitted bounded interpretation.
unresolved	evidence_remains_unresolved	The exact evidence references remain unresolved within this review scope.
needs_additional_evidence	additional_evidence_required	Additional structured evidence is required before a bounded disposition.
not_applicable	not_applicable_to_review_scope	This item is not applicable to the stated review scope.

Every review binds to the saved relationship-evidence bytes, SHA-256, byte count, schema, and version and to the saved evidence-graph bytes, SHA-256, schema, and provenance identified by that relationship artifact. Every decision also retains its exact item and evidence references. Any saved-byte or provenance drift, or a changed item inventory, membership, status, or evidence reference, makes the review stale. Validation fails rather than silently rebasing it.

Reviewer rationale is therefore closed and privacy-safe rather than unrestricted prose. Reviewer metadata also fails closed on automated-review labels, email addresses, URLs, phone numbers, direct identifiers, honorific names, exact ages, and ancestry. Use only a public provider and public account handle; never place private identity or study-participant information in reviewer metadata.

An accepted decision for a conflict or unavailable relationship means only that the reviewed record should retain that bounded unresolved disposition. It does not create or confirm a positive subject, specimen, pairing, repeated-measure, replicate, or independence relationship.

The deterministic validation summary omits reviewer rationales. It reports lifecycle, reviewer, review-artifact identity, binding validity, decision counts, and completeness only; it does not apply accepted decisions to the audit, sample counts, biological-unit reconstruction, statistical independence, design matrices, warnings, severity, report, or verdict.

Each offline command stages and publishes its one output independently. Handled in-process template failures leave no new template, while handled summary failures restore the prior summary when one existed. Neither single-file path claims process-crash atomicity.

This production review schema is separate from the benchmark-only relationship_ground_truth.reviewed.json oracle. Production runtime still does not load benchmark review decisions.

Frozen reviewed GSE198683 relationship package

The benchmark corpus freezes one complete four-file production review package under benchmarks/studies/GSE198683/:

GSE198683_evidence_graph.json
GSE198683_relationship_evidence.json
relationship_review.reviewed.json
GSE198683_relationship_review_validation.json

The graph and relationship-evidence files are the exact canonical inputs reviewed by human-reviewer:github:Microlyzer on 2026-07-31. The approved review accepts all eight source-scoped candidate entities and all eight deterministic exact-label claims. Its four unresolved-relationship decisions remain unresolved: pairing and repeated measures, physical identity and biological independence, specimen and culture lineage, and technical and biological replication are not established.

Acceptance means only that the referenced GSMs share the exact submitted individual label in that source. GEO values retain their separator-adjacent leading space while BioSample values do not. The eight source-scoped candidates remain separate and cover four GSM membership sets, each represented once per source; they are not four proven people, donors, specimens, independent observations, or biological units. The validation summary therefore records downstream_application: "not_applied"; no reviewed decision changes the audit, sample counts, design matrices, warnings, report, severity, verdict, or statistical-suitability result.

Check the frozen package entirely offline with:

.venv\Scripts\python.exe -B scripts/validate_relationship_review_package.py --check

The validator performs no network access and never creates, rewrites, or overwrites the human-authored relationship_review.reviewed.json. Check mode writes nothing and fails on drift in any pinned artifact, evidence binding, decision inventory, lifecycle field, or deterministic validation summary.

The package retains public repository accessions, official source/request provenance, exact coded DonorID 1 through DonorID 4 observations, and the GSM memberships needed to review the claim. It excludes owner/contact data, names and emails, unrestricted titles, source-name values, unrelated or unrestricted BioSample Attributes, exact ages, ancestry, complete quasi-identifying combinations, arbitrary source prose, raw response bodies, and sequence/download metadata. The coded labels still carry study-scoped contextual-linkage risk. NCBI attribution, submitter-rights caveats, and the repository's non-relicensing boundary are documented in THIRD_PARTY_NOTICES.md.

Reviewed relationship-consumption policy

Relationship review and downstream consumption are separate human-owned decisions. A completed relationship review says which bounded evidence statements a reviewer accepted; it does not grant the software permission to turn those statements into design inputs. Policy schema geo-design-auditor/relationship-consumption-policy version 1.0.0 supplies that second gate.

Generate a generic policy template entirely offline with:

python -m geo_design_auditor GSE198683 \
  --out results \
  --relationship-consumption-policy-template

This writes <GSE>_relationship_consumption_policy.template.json. Its bytes do not depend on the accession: the accession is used only for the output directory and filename. The template is a draft, has null reviewer identity and date, and leaves both v1 rule choices unresolved. Publication is fail-if-present. Automation never approves the policy or expands its choices.

The generic, package-independent v1 policy is now tracked at benchmarks/policies/relationship_consumption_policy.reviewed.json. It was approved by human-reviewer:github:Microlyzer on 2026-07-31, with both ordered transformations set to allow_bounded. Its stable rule-inventory identity is relationship-consumption-policy:sha256:bcbe37d15c3e2d84e56341634532b5700779eb374d37ec60859420554baa187b; that ID is shared with the draft because the schema version and ordered rule inventory did not change. The canonical approved file is separately bound by SHA-256 78983aa41432935994246d8b36decb0df63fdcd09fb95454e53dfe0674360d25.

Validate the tracked reviewed policy entirely offline and without writes:

.venv\Scripts\python.exe -B scripts/validate_relationship_consumption_policy.py --check

To validate another separately reviewed policy without consuming a package:

python -m geo_design_auditor GSE198683 \
  --relationship-consumption-policy path/to/reviewed_policy.json

To apply that policy to an explicitly supplied four-file reviewed package, run:

python -m geo_design_auditor GSE198683 \
  --out results \
  --relationship-consumption-policy path/to/reviewed_policy.json \
  --relationship-review-package benchmarks/studies/GSE198683 \
  --build-reviewed-design-input

The build mode validates the canonical evidence graph, relationship evidence, approved review, and deterministic validation summary before it evaluates the approved policy. It is offline, returns before GEO or NCBI clients are constructed, does not search benchmark directories, and does not mutate the package or policy. It transactionally publishes this immutable pair:

GSE198683_reviewed_design_input.json
GSE198683_relationship_policy_application_log.json

V1 has only two closed transformation choices: an accepted submitted_subject_label candidate may become a reviewed_submitted_identifier_group, and its accepted samples_share_exact_submitted_identifier claim may become a reviewed supporting statement. Both remain source scoped. Exact raw keys, coded labels, whitespace, capitalization, repository, and GSM memberships are preserved; GEO and BioSample groups are never merged or normalized. Equal labels or memberships never authorize cross-source equivalence. Unresolved relationship gates remain mandatory and non-waivable.

For the frozen GSE198683 package this permits eight source-scoped reviewed groups when both rules are approved: four GEO representations and four BioSample representations. It does not mean four physical donors, biological units, independent observations, pairs, repeated measures, specimens, cultures, technical replicates, or biological replicates. The four unresolved relationship dimensions are copied forward as explicit blocking gates. The design-input artifact remains design_reconstruction_status: "not_applied", and the application log records one disposition for every review decision plus explicit zero-normalization and zero-source-merge confirmations.

The tracked benchmark publication now includes benchmarks/studies/GSE198683/GSE198683_reviewed_design_input.json (112,980 bytes; SHA-256 c7516d67d6c26bea00d999448fa5076f83382e54c01488bd7acc18104f5ca0a4; artifact ID reviewed-design-input:sha256:5a692460638cd6dd8b07707213593151e586009f3d0fa96e69686b1f02970e7f) and benchmarks/studies/GSE198683/GSE198683_relationship_policy_application_log.json (27,547 bytes; SHA-256 124dfb4a41f221fd09286e5da68e78437db2a7ab07a2ac4d0f331ced54d48932; artifact ID relationship-policy-application-log:sha256:60a41ebc88b1dffec0d6abb504429c6ca645a5d4649d460d4fc037624e97a851). The input contains eight reviewed source-scoped groups, eight bounded supporting claims, and four preserved unresolved gates. The log evaluates all 20 human-review decisions exactly once: eight accepted candidate decisions and eight accepted claim decisions emit bounded outputs, four unresolved decisions emit preserved gates, and no decision is skipped or rejected. No normalization operation or source-scope merge occurs.

Validate the complete publication offline and read-only with:

.venv\Scripts\python.exe -B scripts/validate_relationship_consumption_application.py --check

Policies support draft, pending_review, approved, rejected, and superseded lifecycle states. Only a complete approved policy with valid human reviewer metadata is consumable. Rejected, superseded, incomplete, stale, normalized, source-merging, gate-waiving, or privacy- violating inputs fail closed. Existing exact output pairs are accepted only when byte-identical; partial or different outputs are never overwritten. Handled publication failures remove newly created partial files, without claiming process-crash atomicity.

These artifacts are inputs to the separately reviewed comparison-specific contract and later design-reconstruction layers described below. They do not themselves reconstruct a design and do not change the normal audit, Markdown report, warnings, severity, verdict, sample or biological-unit counts, independence conclusions, comparison structure, or statistical suitability.

The earlier reviewed-policy publication did not itself apply the policy. This separately reviewed publication applies that exact tracked policy only to the frozen GSE198683 review package and publishes the non-applying design-input/application-log pair. Design reconstruction remains not_applied.

Comparison-specific design-reconstruction contract

Schema geo-design-auditor/design-reconstruction-contract defines the next human-owned boundary between the published reviewed-design input and any future reconstruction. Version 1.0.0 remains supported without reinterpretation; version 1.1.0 adds explicit human-reviewed mapping and evidence structures needed to represent positive relationships safely. It is comparison specific: changing the scientific question, included GSMs, group assignments, contrast, unit of analysis, independence model, pairing or repeated-measures structure, replicate handling, blocking factors, covariates, or batch treatment requires a different reviewed contract. An approved relationship review, approved consumption policy, and published reviewed-design input do not answer those comparison-specific questions.

The contract uses the repository lifecycle states draft, pending_review, approved, rejected, and superseded. Review lifecycle, review completeness, and downstream application are separate. Individual decisions use the closed states unresolved, reviewed_supported, reviewed_not_supported, and reviewed_not_applicable. In particular, a completely reviewed contract may preserve an unsupported scientific dimension as unresolved and prohibit reconstruction that depends on it. Lifecycle approval never means that a design has been reconstructed or that an analysis is statistically safe. Design reconstruction, audit application, and statistical application remain separately recorded as not_applied in this slice.

The closed v1 inventory contains exactly these 18 decisions in this order:

1. comparison definition;
2. analysis population;
3. group-assignment definition;
4. contrast definition;
5. candidate biological-unit definition;
6. physical-identity basis;
7. independence basis;
8. pairing structure;
9. repeated-measures structure;
10. specimen and culture lineage;
11. technical-replicate handling;
12. biological-replicate handling;
13. blocking factors;
14. covariates;
15. batch variables;
16. missing-data handling;
17. cross-source equivalence policy; and
18. unresolved-gate disposition.

Decision 18 binds, without waiving, all four inherited dimensions: pairing/repeated measures, physical identity/biological independence, specimen/culture lineage, and technical/biological replication. Every decision is represented exactly once and in canonical order. A completed non-unresolved decision requires human provenance, bounded rationale, evidence references, explicit study-wide or GSM scope, and limitations. An explicitly unresolved reviewed decision must retain the downstream uses it blocks; reviewers are never required to invent an unsupported conclusion merely to complete review.

Version 1.1.0 retains the same 18 decisions and lifecycle, but separates a reviewed decision state from an explicit reviewed mapping. Its closed reviewed_application_mappings section can carry exact GSM-scoped biological units, physical identity, independence assertions, pairs, repeated-measures sets, specimen or culture lineage, technical- and biological-replicate sets, blocking factors, covariates, batch variables, and bounded cross-source equivalence assertions. Each positive mapping is bound to its source decision, exact scope, admissible category-specific human-reviewed evidence, bounded interpretation, limitations, and provenance. A positive state without its required mapping fails, and a mapping cannot cite an unresolved, not-supported, or not-applicable decision. Evidence based only on matching labels, repository co-occurrence, accession order, Run multiplicity, or shared group membership is not admissible relationship evidence.

The v1.1 variable mappings preserve exact source fields and per-GSM value strings, including whitespace, and require every included GSM to have either one reviewed value or explicit reviewed missingness. They do not trim, normalize, recode, convert, standardize, impute, or select reference levels. V1.1 also adds a separately preserved bounded contrast interpretation and permits an optional bounded cross-source-equivalence assertion only with its own reviewed evidence. Even then, GEO and BioSample objects and submitted labels remain separate: no source is preferred, normalized, merged, or rewritten. One positive mapping never resolves a different relationship dimension, and all four inherited gates remain present and explicitly bounded.

The anonymous draft builder may create v1.1 structure only when that version is requested explicitly. Such a draft contains empty mapping collections, no generated relationship evidence, and 18 unresolved decisions. Automation never constructs positive mappings or their supporting human review. Bounded interpretations and exact approved values remain subject to deterministic privacy screening, which does not replace human privacy review.

Generate the deterministic anonymous GSE198683 draft entirely offline with:

.\.venv\Scripts\python.exe -B scripts/build_design_reconstruction_contract.py `
  --study GSE198683 `
  --reviewed-design-input benchmarks/studies/GSE198683/GSE198683_reviewed_design_input.json `
  --application-log benchmarks/studies/GSE198683/GSE198683_relationship_policy_application_log.json `
  --output results/design-reconstruction-contract-review/GSE198683/GSE198683_design_reconstruction_contract.template.json

The generated file is under the ignored results/ tree. It is an incomplete draft with null reviewer identity, review date, and approval authority; all 18 human decisions are unresolved; and all downstream statuses are not_applied. Immutable upstream and unresolved-gate references are prefilled only to prevent drift or omission. The generator does not infer an analysis population, groups, contrast, donors, subjects, biological units, independence, pairing, repeated measures, lineage, or replicate status. It validates both inputs before writing, requires an explicit output path, and rejects destinations under the tracked benchmark corpus. An exact existing deterministic draft is accepted idempotently; different existing content is not overwritten, and handled write failures leave no partial template.

Validate this anonymous GSE198683 draft offline and without writes with:

.\.venv\Scripts\python.exe -B scripts/validate_design_reconstruction_contract.py `
  --contract results/design-reconstruction-contract-review/GSE198683/GSE198683_design_reconstruction_contract.template.json `
  --reviewed-design-input benchmarks/studies/GSE198683/GSE198683_reviewed_design_input.json `
  --application-log benchmarks/studies/GSE198683/GSE198683_relationship_policy_application_log.json `
  --check

Validation fails on upstream or contract-identity drift, noncanonical JSON, missing, duplicate, or reordered decisions, invalid human provenance, omitted gates, unsupported biological promotion, cross-source merging, submitted-label normalization, local paths, privacy weakening, or downstream application. The contract carries stable references instead of copying unrestricted upstream evidence bodies. It permits only the public accessions, exact approved coded labels and source-scoped memberships needed for review, hashes and artifact identities, controlled values, and bounded reviewer text. Owner/contact data, names, email or phone-like values, exact ages, ancestry, unrestricted titles or BioSample attributes, raw responses, complete quasi-identifying combinations, sequence/download metadata, and unrelated URLs remain excluded.

The reviewed-design input contains eight source-scoped submitted-identifier representations, not four proven donors or subjects. Equal GSM memberships and similar DonorID labels do not establish GEO/BioSample equivalence or physical identity, and absence of documented relationships does not establish independence. This earlier neutral slice itself published no approved contract. The later owner-reviewed v1.1 publication described below retains those boundaries and still changes no legacy audit warning, severity, verdict, sample count, design matrix, or statistical-suitability behavior.

Anonymous design-contract review packet

The anonymous draft has a separate explanatory companion with schema geo-design-auditor/design-reconstruction-review-packet version 1.0.0. The packet and its Markdown guide help a human inspect the exact bounded evidence, the 18 questions that still require decisions, and the downstream uses blocked by each unresolved item. They contain no scientific answer, sample selection, group assignment, contrast, reviewer identity, review date, approval, or reviewed contract. Codex generates deterministic review assistance; it cannot serve as the human reviewer.

For an explicitly requested synthetic v1.1 draft, review assistance additionally explains which mapping fields and category-specific evidence a human would have to supply. It remains neutral: it does not propose a mapping, convert generic metadata into relationship evidence, or select a decision. The GSE198683 v1.0 packet and guide remain byte-identical.

Generate both ignored outputs offline with:

.\.venv\Scripts\python.exe -B scripts/build_design_reconstruction_review_packet.py `
  --study GSE198683 `
  --contract results/design-reconstruction-contract-review/GSE198683/GSE198683_design_reconstruction_contract.template.json `
  --reviewed-design-input benchmarks/studies/GSE198683/GSE198683_reviewed_design_input.json `
  --application-log benchmarks/studies/GSE198683/GSE198683_relationship_policy_application_log.json `
  --packet-output results/design-reconstruction-contract-review/GSE198683/GSE198683_design_reconstruction_review_packet.json `
  --guide-output results/design-reconstruction-contract-review/GSE198683/GSE198683_design_reconstruction_review_guide.md

Validate the complete pair without writes with:

.\.venv\Scripts\python.exe -B scripts/validate_design_reconstruction_review_packet.py `
  --contract results/design-reconstruction-contract-review/GSE198683/GSE198683_design_reconstruction_contract.template.json `
  --reviewed-design-input benchmarks/studies/GSE198683/GSE198683_reviewed_design_input.json `
  --application-log benchmarks/studies/GSE198683/GSE198683_relationship_policy_application_log.json `
  --packet results/design-reconstruction-contract-review/GSE198683/GSE198683_design_reconstruction_review_packet.json `
  --guide results/design-reconstruction-contract-review/GSE198683/GSE198683_design_reconstruction_review_guide.md `
  --check

The packet preserves the 22 minimized references as two upstream artifacts, eight distinct source-scoped groups, eight exact-label claims, and four unresolved gates. GEO values retain their submitted leading spaces, BioSample values remain separate, and identical memberships do not merge the two repositories. The four submitted DonorID values are coded labels, not automatic evidence of four physical donors or four biological units. Unavailable relationship dimensions remain unresolved rather than becoming independence, pairing, lineage, or replicate conclusions.

For manual review, first validate the draft and packet, then make a separate backup of the ignored draft. Edit only its designated human-review fields; do not change schemas, upstream bindings, evidence, ordering, gates, privacy boundaries, or prohibited uses. Record decisions and rationales only where evidence supports them, preserving unsupported dimensions as unresolved or reviewed_not_supported. The generic publication workflow described below recanonicalizes a separate human-edited source, refreshes only its derived publication identities, and validates actual human approval. Do not move a draft or candidate into benchmarks/ manually or claim approval before the publisher and read-only validator accept it.

Parallel anonymous GSE198683 v1.1 review workflow

The GSE198683 version 1.0.0 draft, packet, and guide above remain frozen and reproducible at their existing byte identities. A separate, explicitly requested version 1.1.0 workflow creates these three ignored and untracked artifacts in a versioned subdirectory:

results/design-reconstruction-contract-review/GSE198683/v1.1/GSE198683_design_reconstruction_contract_v1_1.template.json
results/design-reconstruction-contract-review/GSE198683/v1.1/GSE198683_design_reconstruction_review_packet_v1_1.json
results/design-reconstruction-contract-review/GSE198683/v1.1/GSE198683_design_reconstruction_review_guide_v1_1.md

The v1.1 packet binds the exact anonymous v1.0 contract as its predecessor review artifact. That binding records continuity and identity only: no human decision is migrated. The new contract has the same 18 ordered unresolved decisions and 12 closed, empty reviewed-mapping collections. The packet and 32-section guide expose 20 ordered mapping-review topics, the exact 16-GSM universe, the eight source-scoped groups, eight exact-label claims, four unresolved gates, and the evidence and human-authority boundaries a reviewer must consider. Exact labels are preserved as submitted evidence, including leading whitespace, but they are not biological-relationship evidence.

First generate or reproduce the v1.0 predecessor with the existing command above. Then build the parallel v1.1 anonymous contract offline:

.\.venv\Scripts\python.exe -B scripts/build_gse198683_design_reconstruction_contract_v1_1.py `
  --study GSE198683 `
  --reviewed-design-input benchmarks/studies/GSE198683/GSE198683_reviewed_design_input.json `
  --application-log benchmarks/studies/GSE198683/GSE198683_relationship_policy_application_log.json `
  --v1-predecessor-contract results/design-reconstruction-contract-review/GSE198683/GSE198683_design_reconstruction_contract.template.json `
  --output results/design-reconstruction-contract-review/GSE198683/v1.1/GSE198683_design_reconstruction_contract_v1_1.template.json

Build the packet and guide as one deterministic pair:

.\.venv\Scripts\python.exe -B scripts/build_gse198683_design_reconstruction_review_packet_v1_1.py `
  --study GSE198683 `
  --contract results/design-reconstruction-contract-review/GSE198683/v1.1/GSE198683_design_reconstruction_contract_v1_1.template.json `
  --reviewed-design-input benchmarks/studies/GSE198683/GSE198683_reviewed_design_input.json `
  --application-log benchmarks/studies/GSE198683/GSE198683_relationship_policy_application_log.json `
  --v1-predecessor-contract results/design-reconstruction-contract-review/GSE198683/GSE198683_design_reconstruction_contract.template.json `
  --packet-output results/design-reconstruction-contract-review/GSE198683/v1.1/GSE198683_design_reconstruction_review_packet_v1_1.json `
  --guide-output results/design-reconstruction-contract-review/GSE198683/v1.1/GSE198683_design_reconstruction_review_guide_v1_1.md

Validate all six bound files offline and without writes:

.\.venv\Scripts\python.exe -B scripts/validate_gse198683_design_reconstruction_review_v1_1.py `
  --contract results/design-reconstruction-contract-review/GSE198683/v1.1/GSE198683_design_reconstruction_contract_v1_1.template.json `
  --packet results/design-reconstruction-contract-review/GSE198683/v1.1/GSE198683_design_reconstruction_review_packet_v1_1.json `
  --guide results/design-reconstruction-contract-review/GSE198683/v1.1/GSE198683_design_reconstruction_review_guide_v1_1.md `
  --reviewed-design-input benchmarks/studies/GSE198683/GSE198683_reviewed_design_input.json `
  --application-log benchmarks/studies/GSE198683/GSE198683_relationship_policy_application_log.json `
  --v1-predecessor-contract results/design-reconstruction-contract-review/GSE198683/GSE198683_design_reconstruction_contract.template.json `
  --check

These commands create review assistance, not review results. They do not turn DonorID labels into donors, subjects, or biological units; treat missing relationship evidence as independence; treat multiple Runs as technical replication; or treat shared group membership as biological replication. They create no reviewed contract, reconstructed design, assessment specification or assessment, reviewer identity, approval, selected mapping, or resolved gate. They also do not alter legacy audit artifacts, warnings, severity, verdict, or statistical behavior. These standalone commands do not construct the integrated runtime report.

Guided GSE198683 v1.1 owner-review workspace

The focused workspace removes the need to edit the 42 KB contract JSON by hand. It validates the exact six-file frozen review graph, then creates one ignored, untracked workspace triple:

results/design-reconstruction-contract-review/GSE198683/v1.1/workspace/GSE198683_design_reconstruction_review_form_v1_1.toml
results/design-reconstruction-contract-review/GSE198683/v1.1/workspace/GSE198683_design_reconstruction_review_workspace_v1_1.json
results/design-reconstruction-contract-review/GSE198683/v1.1/workspace/GSE198683_design_reconstruction_review_workspace_v1_1.md

Only the TOML form is human editable. The JSON is an immutable structured index and the Markdown combines instructions, the exact 18-decision checklist, the 12-category mapping checklist, four inherited gates, the unchanged 22-reference bounded evidence browser, and neutral structural schemas and TOML skeletons for every decision, reviewed-evidence row, and mapping category. Contract decision 10 continues to cover both specimen and culture lineage; decisions 17 and 18 remain separate cross-source-equivalence and unresolved-gate decisions. The workspace does not reshape v1.1 semantics to match presentation headings.

Create the initial neutral workspace offline:

.\.venv\Scripts\python.exe -B scripts/build_gse198683_design_reconstruction_review_workspace_v1_1.py `
  GSE198683 --create-workspace

Edit the TOML form, not the anonymous contract, generated JSON, or generated Markdown. The form contains only the closed human-authorized lifecycle, decision, reviewed-evidence, and mapping fields. TOML inline table { __json_null__ = true } represents a required JSON null. A human must supply every scientific value, rationale, evidence choice, limitation, evidence ID, mapping ID, reviewer field, and lifecycle state; the workspace supplies none. For pending_review, omit review_date and approval_authority from the lifecycle table; materialized JSON represents them as null.

Check current progress read-only through the existing preflight engine:

.\.venv\Scripts\python.exe -B scripts/build_gse198683_design_reconstruction_review_workspace_v1_1.py `
  GSE198683 --check --reference-date 2026-08-03

The summary reports exact completed, incomplete, and invalid decision IDs; complete, incomplete, and invalid mapping categories; resolved, unresolved, and invalid inherited gate IDs; reviewer- field validation, privacy, scientific-boundary, and semantic-contract status; controlled blocked next steps; privacy-safe preflight findings; remaining human actions; owner-source conflict state; and validation state. Invalid gates remain counted as unresolved. Its states are incomplete, draft_review, ready_for_validation, or invalid; it never grants or reports lifecycle approval from the unmaterialized form. Invalid content returns a nonzero command status. The explicit date is a deterministic preflight cutoff, not generated reviewer metadata. Checking writes nothing and does not persist a status file that could become stale.

After --check reports ready_for_validation and the human has inspected the form, explicitly materialize its literal values into the established direct-child preflight source:

.\.venv\Scripts\python.exe -B scripts/build_gse198683_design_reconstruction_review_workspace_v1_1.py `
  GSE198683 --materialize-owner-source --reference-date 2026-08-03

Materialization sets only the infrastructure-owned source path and deterministically reflects decision completeness/comparison specificity. It deliberately retains the stale anonymous contract ID for the existing canonicalizer and never calculates a reviewer, approval, reviewed- evidence ID, or mapping ID. Exclusive creation refuses to replace a differing owner source. It does not create incomplete or invalid owner sources, preflight reports, a canonical candidate, a published contract, an application, a reconstruction, or an assessment.

Integrated T-0010: inspection-only publication attachment

Integrated T-0010 implements the separate canonical geo-design-auditor/design-reconstruction-publication-evidence-attachment version 1.0.0 contract at benchmarks/studies/GSE198683/GSE198683_design_reconstruction_publication_evidence_attachment.json for the ignored GSE198683 v1.1 workspace. The artifact is frozen, integrated provisional-local and postvalidated. Final contract/security and science/privacy/provenance reviews returned CLEAR, the guarded live ignored-workspace migration completed, broad compatibility passed, and complete preintegration and postintegration validation passed. The canonical attachment is capped at exactly 16,000,000 bytes and refuses above that boundary before workspace use. The immutable workspace JSON projection is separately capped at 24,000,000 bytes so every contract-valid attachment has bounded fixed-overhead headroom. The frozen artifact preserves the official full-SOFT identity (81,852 decoded LF bytes; SHA-256 3e7a4a51b241c6727d4200f9c3d5ddc8a664f1ff4520503e5afbff313513625c), PMID 35773318, PMCID PMC9247091, DOI 10.1038/s41598-022-15393-2, and PRJNA816452. The recorded NCBI OA CC BY metadata is source/rights metadata, not scientific validation or proof that NCBI transferred submitter redistribution rights. The generic attachment contract preserves receipt structure and provider response hashes while declaring receipt_values_authenticated_by_schema=false and requiring a source-specific adapter. Generic schema/runtime acceptance therefore does not authenticate the receipt values or establish lawfulness or redistribution permission. The frozen GSE198683 adapter separately verifies its exact minimized PMID/PMCID/DOI/license/retraction fields and the fixed 900-byte bibliographic-response and 444-byte OA-response hashes and byte counts. Before parsing, it also pins the whole canonical attachment at exactly 632,971 bytes and SHA-256 04afe54c16a040afd9c13c6fb6b77e159f85d4a67681439ed4e46cf2c9dfc390, so recomputing an internal attachment ID cannot substitute different frozen bytes.

The exact 5,780,944-byte publisher PDF has SHA-256 c23c39bce2d40428be0f4e3ecd62f507e9bb62655bb39b7a45b0cec157714f12. It remains below the current 10,000,000-byte PDF input limit but refuses at the unchanged 1,000,000-byte decoded-stream limit with decoded_stream_limit; T-0010 does not raise that limit. The attachment therefore records an unavailable paper-content state without a page, text span, section, extracted value or false absence. This is safe refusal evidence, not admissible paper page content; broader M1 lawful paper/supplement-content proof therefore remains incomplete. The PDF, abstract, full text, matrix and count-file bytes are not committed.

The attachment stays outside the v1.1 contract's human-reviewed extended_evidence catalog. With no attachment, the existing workspace JSON/Markdown and version 1.0.0 remain byte-identical. With a validated attachment, only the immutable JSON and Markdown assistance become 1.1.0; the human-editable TOML remains byte-identical. Every projected row is inspection-only, not reviewed and not applied. All 18 decisions remain unresolved, all 12 mapping collections remain empty, all four inherited gates remain unresolved, extended_evidence=[], and reviewer, approval, owner-source and downstream-output state remain absent. Guarded migration retained the exact TOML SHA-256 692e24670fe73eb7c63075c833894402cb9dfe06fef70563dab6e5ab4501e33a and installed workspace JSON SHA-256 1efb0ea8828a665cfbfe174e09a15d494b0058504affd66e38cc5817b4f0d197 plus Markdown SHA-256 3ced368c9ed7bfc5190399065fb54895535440664dd62332d7da6f1cc2f5d759. The existing preflight change-manifest/JSON/Markdown hashes remained 8dbb1b8995f13d0d5ce49727148e31fc05876de779ad73e70d92f2ed4242bb0d, 4e6ece99ea7fce7283116d8a197b6b856e3fb449a04cf7f25c584293a05d3894, and 0dea709245802b2777bfd8ee3e8db4127e1c0dedc15e01715db8b1d0ad73fd71. The post-write read-only check exited zero with the same 18 unresolved decisions, 12 empty mappings, four unresolved gates and no owner source.

Final science/privacy/provenance review returned CLEAR with 22 and seven focused tests passing. Final contract/security review returned CLEAR across 54 targeted tests after the adapter, rollback and bounds repairs; real symlink creation was unavailable on Windows. The combined relevant selection passed 541 tests with two skips in 209.05 seconds, and the final attachment module passed 28 tests in 4.65 seconds. The corrected postintegration full run passed 2,506 tests with eight skips in 1,200.56 seconds and exited zero; an earlier harness timeout had no pytest summary and is non-evidence. T-0011, not T-0010, is the genuine owner/domain-review gate.

Owner-authored v1.1 review preflight

Preflight is a read-only scientific-content check before canonicalization. It compares two contract roles and binds five supporting inputs, but it never edits either contract. Keep these four roles separate:

1. The anonymous baseline is the protected v1.1 template under results/.../v1.1/; do not edit it.
2. The owner-edited source is a separately materialized, ignored direct child of the GSE198683 review directory, for example results/design-reconstruction-contract-review/GSE198683/GSE198683_design_reconstruction_contract_v1_1.human-edited.json. Only the owner supplies its review content through the form. For canonicalizer handoff, its embedded artifact_path must equal that exact direct-child source path; retaining the anonymous path is reported as an outstanding handoff requirement, never silently repaired.
3. A future canonical candidate is a separate ignored file created only by the existing canonicalizer after preflight and owner inspection. Preflight does not create it.
4. A future tracked reviewed contract is created only by the separate approved-only publisher. Preflight neither creates nor approves it.

The workflow emits exactly three ignored, untracked outputs:

results/design-reconstruction-contract-review/GSE198683/v1.1/preflight/GSE198683_design_reconstruction_review_change_manifest.json
results/design-reconstruction-contract-review/GSE198683/v1.1/preflight/GSE198683_design_reconstruction_review_preflight.json
results/design-reconstruction-contract-review/GSE198683/v1.1/preflight/GSE198683_design_reconstruction_review_preflight.md

The closed change-manifest schema geo-design-auditor/design-reconstruction-review-change-manifest version 1.0.0 records hashes, controlled classifications, and bounded display decisions for every changed field. The closed preflight schema geo-design-auditor/design-reconstruction-review-preflight version 1.0.0 reports all 18 decision rows, all 12 mapping collections, the four inherited gates, evidence and GSM consistency, reviewer/lifecycle structure, privacy screening, scientific-boundary screening, and canonicalization requirements. The Markdown guide is rendered only from the validated report; it does not expose unrestricted rationale text or suggest a scientific answer.

After the owner has explicitly materialized and inspected the direct-child source, generate the three reports offline with:

.\.venv\Scripts\python.exe -B scripts/preflight_gse198683_design_reconstruction_review_v1_1.py `
  --anonymous-baseline-contract results/design-reconstruction-contract-review/GSE198683/v1.1/GSE198683_design_reconstruction_contract_v1_1.template.json `
  --owner-edited-source-contract results/design-reconstruction-contract-review/GSE198683/GSE198683_design_reconstruction_contract_v1_1.human-edited.json `
  --reviewed-design-input benchmarks/studies/GSE198683/GSE198683_reviewed_design_input.json `
  --application-log benchmarks/studies/GSE198683/GSE198683_relationship_policy_application_log.json `
  --v1-predecessor-contract results/design-reconstruction-contract-review/GSE198683/GSE198683_design_reconstruction_contract.template.json `
  --v1-1-review-packet results/design-reconstruction-contract-review/GSE198683/v1.1/GSE198683_design_reconstruction_review_packet_v1_1.json `
  --v1-1-review-guide results/design-reconstruction-contract-review/GSE198683/v1.1/GSE198683_design_reconstruction_review_guide_v1_1.md `
  --change-manifest-output results/design-reconstruction-contract-review/GSE198683/v1.1/preflight/GSE198683_design_reconstruction_review_change_manifest.json `
  --preflight-json-output results/design-reconstruction-contract-review/GSE198683/v1.1/preflight/GSE198683_design_reconstruction_review_preflight.json `
  --preflight-markdown-output results/design-reconstruction-contract-review/GSE198683/v1.1/preflight/GSE198683_design_reconstruction_review_preflight.md `
  --reference-date 2026-08-03

Validate the same ten-file graph without writes:

.\.venv\Scripts\python.exe -B scripts/validate_gse198683_design_reconstruction_review_preflight_v1_1.py `
  --check `
  --anonymous-baseline-contract results/design-reconstruction-contract-review/GSE198683/v1.1/GSE198683_design_reconstruction_contract_v1_1.template.json `
  --owner-edited-source-contract results/design-reconstruction-contract-review/GSE198683/GSE198683_design_reconstruction_contract_v1_1.human-edited.json `
  --reviewed-design-input benchmarks/studies/GSE198683/GSE198683_reviewed_design_input.json `
  --application-log benchmarks/studies/GSE198683/GSE198683_relationship_policy_application_log.json `
  --v1-predecessor-contract results/design-reconstruction-contract-review/GSE198683/GSE198683_design_reconstruction_contract.template.json `
  --v1-1-review-packet results/design-reconstruction-contract-review/GSE198683/v1.1/GSE198683_design_reconstruction_review_packet_v1_1.json `
  --v1-1-review-guide results/design-reconstruction-contract-review/GSE198683/v1.1/GSE198683_design_reconstruction_review_guide_v1_1.md `
  --change-manifest-output results/design-reconstruction-contract-review/GSE198683/v1.1/preflight/GSE198683_design_reconstruction_review_change_manifest.json `
  --preflight-json-output results/design-reconstruction-contract-review/GSE198683/v1.1/preflight/GSE198683_design_reconstruction_review_preflight.json `
  --preflight-markdown-output results/design-reconstruction-contract-review/GSE198683/v1.1/preflight/GSE198683_design_reconstruction_review_preflight.md `
  --reference-date 2026-08-03

--reference-date is a required deterministic cutoff for future-date validation, not a review date and not generated reviewer metadata. Reuse the same value when validating previously generated outputs. The unchanged anonymous draft, when supplied as a byte-identical separate working copy, produces lifecycle draft, preflight incomplete, and both readiness flags false: all 18 decisions remain unresolved and all 12 mapping collections remain empty.

Preflight distinguishes permitted human edits, stale derived identity, protected or unknown field changes, incomplete or inconsistent review, privacy failures, and prohibited scientific promotion. It checks that exact-label evidence does not become biological-unit or identity evidence, absence does not become independence, Run multiplicity does not become technical replication, and shared groups do not become biological replication. It never repairs a field, refreshes an identity, canonicalizes JSON, grants approval, publishes or applies a contract, or creates a reconstructed design or assessment. The 2026-08-20 owner review completed this preflight separately; preflight itself still does not mutate runtime outputs, legacy audit warnings, severity, verdict, or statistical behavior.

Reviewed-contract canonicalization and publication infrastructure

Human editing, serialization canonicalization, publication, and downstream application are four different operations. A human is the sole authority for reviewer metadata, lifecycle approval, the 18 decision states and values, rationales, evidence citations, limitations, GSM inclusion and exclusion, groups, contrast, biological-unit interpretation, and relationship interpretation. Automation never chooses, proposes, repairs, infers, completes, or approves those fields.

The standalone canonicalizer accepts a human-edited source contract and an explicit candidate output under the repository's ignored results/ tree, outside benchmarks/. The source and both upstream artifacts must be regular, non-symlinked files inside the repository; their exact parsed bytes are pinned through candidate installation. The source may use noncanonical JSON serialization. Canonicalization preserves every non-identity value exactly—including whitespace inside submitted labels and human rationales, decision order, GSM order, memberships, evidence references, contrast direction, and limitations—while applying deterministic key order and indentation, UTF-8 encoding, and one final newline. It deterministically migrates the non-scientific artifact_path to the conventional future tracked reviewed-contract path and then refreshes the content-derived contract ID, recording each field whose value changed. No other field may change. Serialization and identity refresh are not human review, approval, publication, or application.

The separate publisher accepts only a canonical, complete, human-approved candidate bound to the exact reviewed-design input and application log. The first four comparison decisions must define the scientific question or estimand, complete included/excluded GSM accounting, source-supported groups, and a directed contrast. A valid approved contract may retain a safely bounded unresolved dimension when its reason, evidence, limitations, and blocked downstream uses are explicit. It may not claim an applied reconstruction or analysis: design reconstruction, audit application, and statistical application must all remain not_applied.

Publication installs the reviewed contract and a deterministic, version-matched geo-design-auditor/design-reconstruction-contract-validation summary as a tracked pair. A v1.0 contract retains its exact v1.0 summary behavior. A v1.1 summary additionally records counts for each reviewed mapping and extended evidence category, inherited-gate accounting, and explicit zero-normalization and zero-cross-source-merge validation. The summary otherwise records identities, exact upstream bindings, lifecycle and reviewer metadata, completeness and decision counts, privacy and scientific-boundary checks, canonical-byte status, and non-applying downstream statuses. It uses stable references and counts rather than copying unrestricted mapping interpretations, rationales, or evidence bodies. An exact existing pair is an idempotent no-write result; a partial or different pair fails unchanged; handled installation failures roll back newly installed files and clean staging. This is not a process-crash atomicity guarantee.

The read-only validator requires --check, reconstructs the expected validation summary, compares canonical bytes and identities, revalidates both upstream artifacts, and rereads every input for drift. Reviewer IDs use the repository's human-reviewer:<provider>:<public-account-handle> syntax and completed reviews require a valid, non-future ISO date. These checks reject automated or placeholder identities but do not cryptographically authenticate the named reviewer.

The following paths illustrate roles only; replace angle-bracketed values after a genuine human review. Do not use the anonymous GSE198683 draft as an approved input:

results/design-reconstruction-contract-review/<GSE_ACCESSION>/<GSE_ACCESSION>_design_reconstruction_contract.human-edited.json
results/design-reconstruction-contract-review/<GSE_ACCESSION>/<GSE_ACCESSION>_design_reconstruction_contract.candidate.json
benchmarks/studies/<GSE_ACCESSION>/<GSE_ACCESSION>_design_reconstruction_contract.reviewed.json
benchmarks/studies/<GSE_ACCESSION>/<GSE_ACCESSION>_design_reconstruction_contract_validation.json

Canonicalize a future genuinely human-edited source with explicit upstream and candidate paths:

# Replace every angle-bracketed placeholder before use.
.\.venv\Scripts\python.exe -B scripts/canonicalize_reviewed_design_reconstruction_contract.py `
  --input-contract results/design-reconstruction-contract-review/<GSE_ACCESSION>/<GSE_ACCESSION>_design_reconstruction_contract.human-edited.json `
  --reviewed-design-input benchmarks/studies/<GSE_ACCESSION>/<GSE_ACCESSION>_reviewed_design_input.json `
  --application-log benchmarks/studies/<GSE_ACCESSION>/<GSE_ACCESSION>_relationship_policy_application_log.json `
  --output results/design-reconstruction-contract-review/<GSE_ACCESSION>/<GSE_ACCESSION>_design_reconstruction_contract.candidate.json

After genuine human approval, publish that canonical candidate and its validation summary as one tracked pair:

.\.venv\Scripts\python.exe -B scripts/publish_reviewed_design_reconstruction_contract.py `
  --candidate results/design-reconstruction-contract-review/<GSE_ACCESSION>/<GSE_ACCESSION>_design_reconstruction_contract.candidate.json `
  --reviewed-design-input benchmarks/studies/<GSE_ACCESSION>/<GSE_ACCESSION>_reviewed_design_input.json `
  --application-log benchmarks/studies/<GSE_ACCESSION>/<GSE_ACCESSION>_relationship_policy_application_log.json `
  --reviewed-contract-output benchmarks/studies/<GSE_ACCESSION>/<GSE_ACCESSION>_design_reconstruction_contract.reviewed.json `
  --validation-summary-output benchmarks/studies/<GSE_ACCESSION>/<GSE_ACCESSION>_design_reconstruction_contract_validation.json

Validate a published pair offline without writes:

.\.venv\Scripts\python.exe -B scripts/validate_reviewed_design_reconstruction_contract.py `
  --reviewed-contract benchmarks/studies/<GSE_ACCESSION>/<GSE_ACCESSION>_design_reconstruction_contract.reviewed.json `
  --validation-summary benchmarks/studies/<GSE_ACCESSION>/<GSE_ACCESSION>_design_reconstruction_contract_validation.json `
  --reviewed-design-input benchmarks/studies/<GSE_ACCESSION>/<GSE_ACCESSION>_reviewed_design_input.json `
  --application-log benchmarks/studies/<GSE_ACCESSION>/<GSE_ACCESSION>_relationship_policy_application_log.json `
  --check

The existing GSE198683 v1.0 contract remains the byte-identical version 1.0.0 anonymous draft: unresolved, unapproved, ignored, and unpublished. It was not silently upgraded. The separate v1.1 owner review is tracked as GSE198683_design_reconstruction_contract.reviewed.json plus its validation summary. It approves only the eight-GSM IL17_DEX-minus-IL17 comparison: five decisions are supported, ten are reviewed-not-supported, three are not applicable, all 12 mapping collections are empty, and all four inherited gates are reviewed-not-supported. That status means the evidence does not establish the relationship, not that the relationship is proven absent. An ordinary researcher run still does not consume this publication and reports downstream design states as not_supplied or not_applied.

Applying an approved v1.1 contract

The generic offline application workflow is a separate operation after publication. For this slice it accepts only a canonical, human-approved design-reconstruction contract at version 1.1.0, its exact validation summary, and the exact reviewed-design input and relationship-policy application log bound by that contract. Version 1.0.0 remains valid for review and publication but is deliberately not application eligible because it cannot represent every required explicit mapping. The reviewed GSE198683 v1.1 publication is now application eligible through that same four-input gate; its reconstructed-design and application-log outputs remain ignored under results/, not benchmark evidence.

Application deterministically reproduces reviewed values in a geo-design-auditor/reconstructed-design version 1.0.0 artifact and records every decision and mapping evaluation in a geo-design-auditor/design-reconstruction-application-log version 1.0.0 artifact. The reconstructed design has the closed role contract_derived_design_representation. Identity dependencies are one way:

reviewed contract + validation summary + reviewed design input + relationship-policy log
  -> reconstructed design
  -> design-reconstruction application log

Both outputs record contract_validation_status: passed, contract_application_status: applied, and design_reconstruction_status: applied, while audit_application_status, statistical_application_status, and suitability_assessment_status remain not_applied.

The workflow makes no new scientific decision. It does not infer sample inclusion, groups, contrasts, biological units, independence, pairing, repeated measures, lineage, or replication; normalize or impute values; resolve inherited gates; construct a design matrix or model formula; assess statistical suitability; or enter the normal audit publication and verdict path. The current researcher-facing summary does not consume this standalone application and keeps design and assessment states not_applied. Reviewed unsupported, not-applicable, and unresolved dimensions remain distinct. In particular, it creates no independent-observation count without explicit reviewed support.

Apply a genuinely approved synthetic v1.1 publication to an ignored output pair with explicit paths:

.\.venv\Scripts\python.exe -B scripts/apply_reviewed_design_reconstruction_contract.py `
  --repository-root . `
  --reviewed-contract benchmarks/studies/<GSE_ACCESSION>/<GSE_ACCESSION>_design_reconstruction_contract.reviewed.json `
  --validation-summary benchmarks/studies/<GSE_ACCESSION>/<GSE_ACCESSION>_design_reconstruction_contract_validation.json `
  --reviewed-design-input benchmarks/studies/<GSE_ACCESSION>/<GSE_ACCESSION>_reviewed_design_input.json `
  --relationship-policy-application-log benchmarks/studies/<GSE_ACCESSION>/<GSE_ACCESSION>_relationship_policy_application_log.json `
  --reconstructed-design-output results/design-reconstruction-application/<GSE_ACCESSION>/<GSE_ACCESSION>_reconstructed_design.json `
  --design-reconstruction-application-log-output results/design-reconstruction-application/<GSE_ACCESSION>/<GSE_ACCESSION>_design_reconstruction_application_log.json

Validate all four inputs and both outputs offline without writes:

.\.venv\Scripts\python.exe -B scripts/validate_design_reconstruction_application.py `
  --repository-root . `
  --reviewed-contract benchmarks/studies/<GSE_ACCESSION>/<GSE_ACCESSION>_design_reconstruction_contract.reviewed.json `
  --validation-summary benchmarks/studies/<GSE_ACCESSION>/<GSE_ACCESSION>_design_reconstruction_contract_validation.json `
  --reviewed-design-input benchmarks/studies/<GSE_ACCESSION>/<GSE_ACCESSION>_reviewed_design_input.json `
  --relationship-policy-application-log benchmarks/studies/<GSE_ACCESSION>/<GSE_ACCESSION>_relationship_policy_application_log.json `
  --reconstructed-design results/design-reconstruction-application/<GSE_ACCESSION>/<GSE_ACCESSION>_reconstructed_design.json `
  --design-reconstruction-application-log results/design-reconstruction-application/<GSE_ACCESSION>/<GSE_ACCESSION>_design_reconstruction_application_log.json `
  --check

Exact existing output pairs are idempotent; partial or different pairs fail unchanged, and handled installation failures roll back files owned by the current transaction. The anonymous GSE198683 v1.0 predecessor remains unchanged and ineligible; only the separately reviewed v1.1 publication may be supplied for GSE198683.

Comparison-specific design assessment

Design reconstruction and design assessment are separate human-authority boundaries. A reconstructed design says what the approved comparison, rows, groups, variables, and relationship limitations are. It does not choose a statistical model. The assessment workflow therefore also requires a separate, canonical, human-approved geo-design-auditor/comparison-design-assessment-specification version 1.0.0 and its exact validation summary. That specification alone declares the matrix rows, intercept, model terms, categorical coding and reference levels, interactions, deterministic coefficient order, missingness policy, and one coefficient-level contrast. No term, row, coding rule, reference level, interaction, or contrast is selected automatically.

The framework remains comparison specific. Synthetic tests create approved GSE900001 inputs in temporary repositories, while the benchmark corpus now also contains the genuine owner-approved GSE198683 assessment specification and validation summary. That real specification declares only the exact eight-row, group-only algebraic question. T-0014 now applies it through the same deterministic engine and persists the ignored assessment/application-log pair under results/. That output reports an 8-by-2 matrix, exact rank 2, empty nullspace basis and an algebraically estimable [0, 1] contrast. It also keeps independent-observation count unavailable and every model-fit, effect, p-value, differential-expression, power, audit, suitability and readiness operation blocked or not applied. A real application always requires the reviewed v1.1 reconstruction pair, the separate human-approved assessment specification, and exact input binding.

Anonymous assessment-specification review assistance

A separate non-executable geo-design-auditor/comparison-design-assessment-specification-draft version 1.0.0 makes the next human review manageable without pretending that a model has already been chosen. The draft binds one exact reconstructed-design/application-log pair and leaves the assessment question, matrix rows and omissions, intercept, terms, categorical coding and reference levels, interactions, coefficient inventory and order, coefficient contrast, missingness policy, complete-case subset, blockers, limitations, and approval metadata unresolved or unselected. It has no reviewer identity, review date, or approval authority and cannot be supplied to the assessment application command.

The draft's explanatory companions use geo-design-auditor/comparison-design-assessment-review-packet version 1.0.0 with role human_review_assistance_only and a deterministic Markdown guide. They bind the exact draft, reconstructed design, reconstruction log, study, comparison, and source reviewed-contract authority. They display only bounded GSM, group, contrast, variable, exact-value, missingness, and relationship inventories needed for review. Every assessment choice remains human controlled. The packet does not select or recommend a row, omission, term, intercept policy, coding policy, reference level, interaction, covariate, blocking factor, batch variable, coefficient, contrast, complete-case subset, or missingness policy. It does not construct a matrix or calculate rank, null space, or estimability.

For a privacy-safe synthetic review target whose reconstructed-design pair already exists, create and validate the three ignored outputs with:

$study = "GSE900001"
$designRoot = "results/design-reconstruction-application/$study"
$reconstructedDesign = "$designRoot/${study}_reconstructed_design.json"
$reconstructionLog = "$designRoot/${study}_design_reconstruction_application_log.json"
$reviewRoot = "results/comparison-design-assessment-review/$study"
$anonymousDraft = "$reviewRoot/${study}_comparison_design_assessment_specification.template.json"
$reviewPacket = "$reviewRoot/${study}_comparison_design_assessment_review_packet.json"
$reviewGuide = "$reviewRoot/${study}_comparison_design_assessment_review_guide.md"

.\.venv\Scripts\python.exe -B scripts\build_comparison_design_assessment_specification_draft.py `
  --reconstructed-design $reconstructedDesign `
  --reconstruction-application-log $reconstructionLog `
  --output $anonymousDraft `
  --repository-root .

.\.venv\Scripts\python.exe -B scripts\build_comparison_design_assessment_review_packet.py `
  --anonymous-specification $anonymousDraft `
  --reconstructed-design $reconstructedDesign `
  --reconstruction-application-log $reconstructionLog `
  --packet-output $reviewPacket `
  --guide-output $reviewGuide `
  --repository-root .

.\.venv\Scripts\python.exe -B scripts\validate_comparison_design_assessment_review_packet.py `
  --anonymous-specification $anonymousDraft `
  --reconstructed-design $reconstructedDesign `
  --reconstruction-application-log $reconstructionLog `
  --packet $reviewPacket `
  --guide $reviewGuide `
  --repository-root . `
  --check

These commands are offline and standalone. The draft, packet, and guide stay under ignored results/; they are not benchmark fixtures and must not be force-added to Git. A human reviewer may use them to author a separate executable assessment specification, but the assistance cannot approve that specification or act as the statistical reviewer. The reviewed specification still must pass the existing canonicalization, publication, and approved-only validation gates before assessment application.

The guide explains deterministic consequences without recommending a choice. In particular, no missing value causes automatic complete-case selection, no reconstructed group automatically becomes a model term, and no coding, reference level, interaction, coefficient order, or contrast is supplied as a default. Exact matrix rank would describe algebraic column dependence only; it would not establish biological independence. Exact contrast estimability would establish only row-space membership for the declared matrix; it would not establish power, study validity, effective sample size, or suitability.

Candidate matrices use exact reviewed per-GSM values. Numeric strings must satisfy the closed decimal contract; they are not trimmed, imputed, centered, scaled, normalized, transformed, or unit-converted. Matrix entries, contrast coefficients, rank, row-space membership, and null-space dependencies use exact reduced rational arithmetic rather than binary floating point or numerical tolerances. Exact rank answers whether the declared columns are algebraically independent under this matrix. Exact contrast estimability answers whether the declared coefficient contrast lies in the matrix row space. Neither result establishes adequate power, low bias, causal validity, or the scientific validity of treating GEO rows as independent observations.

Treatment-reference and full-indicator coding are supported only when explicitly declared. Full-indicator coding does not silently drop a level. Rank deficiency produces deterministic exact dependency vectors and controlled structural-alias findings; the workflow does not delete a column, switch coding, remove a term, or turn algebraic aliasing into a causal-confounding claim. Group counts, categorical cross-tabs and cell occupancy, exact numeric ranges, and declared-value missingness are descriptive only. No p-values, fitted coefficients, effects, power calculations, severity labels, recommendations, differential-expression results, or suitability verdicts are produced.

Missing model values never trigger an implicit complete-case analysis. require_complete_declared_rows blocks matrix construction when a required value is missing; use_explicit_reviewed_complete_case_subset uses only the exact retained and omitted rows already approved in the specification; and matrix_construction_blocked records the reviewed blocker without constructing a matrix. Pairing, repeated-measures, replicate, biological-unit, physical- identity, and independence limitations are carried forward from the reconstructed design. Algebra may still be assessed when the approved specification permits it, but an independent-observation count is never derived from matrix rank.

The two deterministic application outputs use geo-design-auditor/comparison-design-assessment and geo-design-auditor/comparison-design-assessment-application-log, both version 1.0.0. Their identity dependency is acyclic:

reconstructed design + reconstruction application log
  + approved assessment specification + specification validation summary
  -> comparison-specific design assessment
  -> design-assessment application log

Canonicalization may change JSON serialization and permitted identity/path fields only; human- authored question text, row membership and order, term order, coding choices, reference levels, interaction declarations, contrast, interpretation, limitations, and reviewer metadata remain unchanged. The canonical review candidate and assessment outputs use explicit paths under ignored results/; an intentionally published approved specification/validation pair uses its conventional tracked benchmark path. Both publication paths reject unsafe aliases and partial or differing pairs, treat exact pairs as idempotent no-write results, verify installed bytes, and roll back handled installation failures. The read-only validators reconstruct the complete expected artifacts, recalculate the exact algebra, compare canonical bytes, and reread every input for drift without networking or writes.

The standalone workflow is intentionally not part of geo-audit. Use it only after the reconstructed-design pair exists and a human has completed and approved the assessment specification. The publication command validates that approval; it never supplies reviewer metadata or changes lifecycle state. In the following PowerShell example, replace GSE123456 only with an accession already bound to a genuinely reviewed synthetic or owner-authorized package; GSE198683 is now the integrated real example:

$study = "GSE123456"
$designRoot = "results/design-reconstruction-application/$study"
$reconstructedDesign = "$designRoot/${study}_reconstructed_design.json"
$reconstructionLog = "$designRoot/${study}_design_reconstruction_application_log.json"
$reviewRoot = "results/comparison-design-assessment-specification-review/$study"
$humanSpecification = "$reviewRoot/${study}_comparison_design_assessment_specification.human-edited.json"
$candidate = "$reviewRoot/${study}_comparison_design_assessment_specification.template.json"
$benchmarkRoot = "benchmarks/studies/$study"
$reviewedSpecification = "$benchmarkRoot/${study}_comparison_design_assessment_specification.reviewed.json"
$specificationValidation = "$benchmarkRoot/${study}_comparison_design_assessment_specification_validation.json"
$assessmentRoot = "results/comparison-design-assessment/$study"
$assessment = "$assessmentRoot/${study}_comparison_design_assessment.json"
$assessmentLog = "$assessmentRoot/${study}_comparison_design_assessment_application_log.json"

Canonicalize the human-edited specification into an ignored candidate. This refreshes only the permitted path and content-identity fields:

.\.venv\Scripts\python.exe -B scripts\canonicalize_comparison_design_assessment_specification.py `
  --input-specification $humanSpecification `
  --reconstructed-design $reconstructedDesign `
  --reconstruction-application-log $reconstructionLog `
  --output $candidate

Publish the already human-approved candidate and its deterministic validation summary as one transactional pair:

.\.venv\Scripts\python.exe -B scripts\publish_reviewed_comparison_design_assessment_specification.py `
  --candidate $candidate `
  --reconstructed-design $reconstructedDesign `
  --reconstruction-application-log $reconstructionLog `
  --reviewed-specification-output $reviewedSpecification `
  --validation-summary-output $specificationValidation

Validate that reviewed pair offline and without writes before application:

.\.venv\Scripts\python.exe -B scripts\validate_reviewed_comparison_design_assessment_specification.py `
  --reviewed-specification $reviewedSpecification `
  --validation-summary $specificationValidation `
  --reconstructed-design $reconstructedDesign `
  --reconstruction-application-log $reconstructionLog `
  --check

Apply the exact approved choices to create the ignored assessment/application-log pair:

.\.venv\Scripts\python.exe -B scripts\apply_comparison_design_assessment.py `
  --reconstructed-design $reconstructedDesign `
  --reconstruction-application-log $reconstructionLog `
  --assessment-specification $reviewedSpecification `
  --specification-validation-summary $specificationValidation `
  --design-assessment-output $assessment `
  --assessment-application-log-output $assessmentLog `
  --repository-root .

Finally, validate all six files offline, read-only, and by complete deterministic reconstruction:

.\.venv\Scripts\python.exe -B scripts\validate_comparison_design_assessment.py `
  --reconstructed-design $reconstructedDesign `
  --reconstruction-application-log $reconstructionLog `
  --assessment-specification $reviewedSpecification `
  --specification-validation-summary $specificationValidation `
  --design-assessment $assessment `
  --assessment-application-log $assessmentLog `
  --repository-root . `
  --check

These offline assessment commands do not alter normal GEO retrieval, parsing, normalization, audit JSON, legacy sample CSV, warning, severity, or verdict semantics. The primary researcher report is intentionally integrated by geo-audit, as documented above. For GSE198683, they compute only the owner-approved algebraic matrix/rank/nullspace/estimability result and preserve every relationship and noninferential limitation; they do not fit a model or establish scientific suitability or analysis readiness.

Inventory raw sample-characteristic keys

Developers can add an uninterpreted inventory of the study-specific keys and values retained from GEO sample-characteristic fields:

geo-audit GSE339369 \
  --inventory-keys \
  --out results \
  --email your.email@example.com

With --inventory-keys, the accession output folder also contains:

GSE339369_characteristic_keys.csv
GSE339369_characteristic_keys.json

The inventory scans every parsed Sample_characteristics_ch* field. Its exactness boundary is the existing SOFT parser: that parser strips whitespace surrounding the complete SOFT metadata value before inventory construction. After that boundary, the inventory performs no additional stripping or normalization. Parser-retained case, punctuation, channel, interior whitespace, repeated occurrences, empty values, empty explicit keys, unkeyed characteristics, and additional colons are preserved. This does not claim byte-for-byte or character-for-character identity with the downloaded source. The decoded source document is saved separately as <GSE>_source.soft as the provenance record.

Each key summary reports the number of GEO samples containing the key, the number of exact parser-retained distinct values, and up to five first-seen representative values. The JSON export retains every occurrence and its GSM accession. The inventory does not interpret, merge, or infer meanings.

The CSV starts with one inventory_metadata row containing study-level accession and provenance, followed by zero or more key_summary rows. Thus a study with no characteristic keys still retains its source URL, retrieval timestamp, total sample count, and representative-value limit. The row type also distinguishes no key summaries from an explicit empty-string key.

For complete provenance the CSV JSON-encodes sample-accession and occurrence lists inside cells. Those cells can be large for studies with many samples; this is a known developer-export limitation for the current milestone. The JSON export is easier to consume when occurrence-level records are needed.

This command retrieves GEO Series-family SOFT metadata only. It does not download FASTQ, BAM, CRAM, or other sequencing files.

Explicit reviewed key mapping

--key-mapping-package requires --inventory-keys and accepts only an explicitly supplied package directory. Runtime never discovers a package by accession or auto-loads a benchmark. The loader verifies the tracked frozen inventory bytes against the exact SHA-256 pinned by the reviewed mapping. It separately compares the inventory produced from the current retrieved study with that frozen inventory at the parser-retained scientific-content boundary. Current retrieval provenance and JSON serialization are excluded from that comparison, so the live inventory bytes and hash may differ without weakening the frozen package identity. Scientific-content or reviewed-package drift fails closed. Reviewed discrepancy observations are then located and rebound to the current parsed SOFT Series/Sample source; the frozen review does not substitute stale source provenance or values.

Without a supplied reviewed package, the console may list detected characteristic keys and their coverage, but it reports their semantic roles as unreviewed and does not promote a two-level field to an experimental factor merely because its cardinality is binary. It gives this generic next step exactly:

Review the detected characteristic keys or rerun with --key-mapping-package <directory>.

Because that option requires the inventory, the complete valid generic command is:

geo-audit <GSE> --inventory-keys --key-mapping-package <directory>

When the explicitly supplied package validates, the mapped view may show its accepted reviewed roles, safe values, descriptive factor combinations, and bounded reviewed discrepancies. Mapping does not create groups, infer a design, or change source metadata. Both mapped and unmapped views retain the same repository and biological-identity boundaries.

For the frozen GSE198683 acceptance case, a metadata-only mapping run is:

geo-audit GSE198683 \
  --out results \
  --inventory-keys \
  --key-mapping-package benchmarks/studies/GSE198683

To include repository and relationship evidence in the same researcher-facing report, add --cross-db-evidence --relationship-evidence and the required NCBI cache/contact options described above. The reviewed GSE198683 package recognizes the exact dexamethasone and il-17 keys as two separate experimental factors. The integrated report derives their four descriptive combinations without creating a combined condition. It also retains the reviewed material discrepancy between the Series-level 100 nM dexamethasone description and excluded Sample growth-protocol evidence of 10 nM; neither dose is selected and manual review remains required.

Dexamethasone	IL-17	GEO Sample count
No	No	4
No	Yes	4
Yes	No	4
Yes	Yes	4

Those counts are derived from the current parser-retained sample-level inventory after its scientific content is validated against the frozen reviewed inventory, rather than from hard-coded accession logic. The same reviewed mapping reports cell type at 16/16 coverage with display level primary human airway epithelial cells (hAECs); the exact parser-retained value and its explicit outer-whitespace presentation transform remain in the machine summary and inventory. With cross- database evidence, the report shows 16 GEO Samples, 16 linked and reconciled BioSamples, 16 SRA Samples, 16 SRA Experiments, and 30 SRA Run records while keeping each repository record type distinct. Run count remains repository topology, not replicate evidence.

For this study, the recovered source-scoped individual labels may be displayed as four distinct submitted identifier labels—DonorID 1, DonorID 2, DonorID 3, and DonorID 4—with four GSMs per label and complete descriptive 2-by-2 factor coverage within each label. That adjacency does not establish four physical donors, biological units, independent blocks, pairing, repeated measures, lineage, or replication. GEO and BioSample label evidence remains separate even where presentation values and memberships align.

The layered status for this invocation reports metadata structure substantially recovered, recovered fields recovered, explicit factors recovered, factor combinations recovered descriptively, repository reconciliation completed, and source- scoped label groups recovered as candidates. Physical identity, biological-unit identity, and independence remain unresolved; the other relationship dimensions remain unavailable. Design reconstruction and comparison assessment are not applied, and the conservative overall verdict remains manual_review_required.

Missing-metadata rows distinguish observed structured-field absence, incomplete or ambiguous coverage, conflicts, unrequested or failed retrieval/processing, unreviewed or unsupported roles, structure-only inapplicability, and privacy-withheld values. These statuses do not assert that a biological property is absent. The human-review lifecycle also reports the relationship- consumption policy explicitly as not supplied and not applied; a normal run does not discover or apply the tracked benchmark policy.

Developer NCBI metadata transport

Sprint 1 includes an internal, transport-only E-utilities client and deterministic metadata cache in geo_design_auditor.ncbi_client. The default command never constructs it. The opt-in --cross-db-evidence path uses it for exact BioSample and SRA metadata requests. GEO SOFT retrieval and the legacy audit JSON, sample CSV, scientific warning rules, and verdict semantics remain unchanged; the integrated terminal, report, summary, sample table, and output index intentionally reflect whether this optional layer ran.

The client accepts explicit settings for the NCBI tool name, optional contact email and API key, timeout, retry count and backoff, minimum request interval, optional cache directory, offline mode, printable-ASCII User-Agent, and maximum response size. Direct NcbiClientConfig(...) construction never reads the environment. NcbiClientConfig.from_environment(...) may read NCBI_EMAIL and NCBI_API_KEY; an explicitly supplied value takes precedence, and explicit None disables the corresponding environment fallback. Both values may be absent.

The client accepts only a fixed operation matrix: legacy BioSample/SRA esearch and efetch, PubMed/PMC/BioProject esummary, exact PMC and BioProject discovery esearch, and the exact named PubMed-to-PMC pubmed_pmc elink. It builds every URL beneath https://eutils.ncbi.nlm.nih.gov/entrez/eutils/; arbitrary endpoint/database combinations remain invalid. It does not accept caller-supplied hosts or URLs, follow redirects or metadata links, or download referenced files. The default 0.34-second per-client request interval is conservative relative to NCBI's published three-requests-per-second guidance; callers remain responsible for current NCBI requirements, and the client does not claim to guarantee policy or legal compliance. See the official E-utilities guidance.

When a cache directory is configured, a response is stored as an immutable body.bin plus a secret-free JSON manifest under a SHA-256 request key. The authoritative exactness boundary is the HTTP response-body byte sequence after HTTP framing has been removed and before character decoding, newline conversion, or Unicode normalization. The body hash and byte count cover those bytes; decode_text() is strict and never replaces invalid input. Every cache hit rechecks the manifest, semantic request identity, byte count, and SHA-256. Cache entries are not created by default because cache_directory defaults to None. These checks detect incomplete or incoherently changed entries; they are not signatures and do not establish authenticity, so the configured cache directory must be treated as trusted local storage.

API keys, full contact-email values, User-Agent values, authorization headers, and cookies are not placed in request identities, cache keys, manifests, provenance dictionaries, logs, or public exceptions. Provenance records the tool name and only whether a contact email was supplied. For a cache hit it exposes both the current cache-read request and the original network-request identity retained in the manifest. Operation-specific query values are intentionally retained because they define the request; callers must not put credentials in those fields. Exact opaque NCBI response bodies may themselves contain submitter-provided values and are not redacted or interpreted.

Offline mode performs verified cache reads only. A missing entry raises an explicit offline cache miss, a corrupt entry raises a corruption error, and neither condition falls back to network access. The transport itself remains metadata-opaque. Separate production parsers extract only qualified BioSample GEO/SRA identifiers and explicit SRS/SRX/SRR structures for the opt-in graph; they do not normalize biological values or count biological units.

BioSample capture review and approved fixtures

Sprint 1 includes a separate developer-only BioSample evidence component. Human-reviewed selector policies and minimized, deterministic fixture sets are published for 66 public SAMN accessions across all five frozen benchmark studies, with 888 deterministic observed statements.

The final publication adds the 22 accessions linked from GSE161357 and GSE184237, using only the approved 20260730-task4-remaining-pilot-01 capture and reviewed policies. GSE161357 retains exact treatment observations. GSE184237 retains exact Sex and case-or-control observations while excluding BioSample age, ancestry, source names, and coded-title prose. Neither study publishes relationship_observations.json; each manifest records relationship evidence as explicitly unavailable. The exact GEO/BioSample Sex disagreement and the documented RNA-Seq versus genomic/genomic-DNA discrepancy remain unresolved rather than normalized or corrected, with the assay discrepancy still manual_review_required.

Normal fixture-builder operation is fully offline and performs no BioSample request. A real metadata-only capture requires both the explicit review flag and this new ignored directory:

python scripts/build_biosample_fixtures.py \
  --capture-review \
  --cache-dir results/ncbi-biosample-cache/20260730-task4-remaining-pilot-01 \
  --email your.email@example.com

This capture retrieves only the four fixed E-utilities metadata responses for the second cohort studies. It does not follow metadata links or retrieve sequence files. Complete response bodies remain under the ignored results/ directory and may contain sensitive submitter-provided metadata, so they remain in trusted local storage and are not redistributed. The capture produces only local review evidence and never publishes or changes tracked files by itself.

All five reviewed policies can be validated against the two explicitly approved captures without writing fixtures:

python scripts/build_biosample_fixtures.py --validate-reviewed-policies

This offline mode pins each cohort's completion marker, review report, exact response hashes, and expected study membership. It rejects arbitrary capture identities and never generates, rewrites, or publishes policies or fixtures.

Publication is a separate, explicit, offline operation. The original three-study command remains bound to 20260730-task4-pilot-02; the final two-study command is bound to 20260730-task4-remaining-pilot-01:

python scripts/build_biosample_fixtures.py --publish-reviewed
python scripts/build_biosample_fixtures.py --publish-remaining-reviewed

The builder validates but never generates or overwrites biosample_selector_policy.reviewed.json. Each command validates its complete approved cohort before atomically publishing canonical reduced XML, a provenance manifest, and observed-value JSON. Repeated publication is byte-identical. Normal mode and explicit check remain fully offline, cover all five committed fixture sets, and do not read either ignored authoritative capture:

python scripts/build_biosample_fixtures.py --check

The snapshot-manifest contract distinguishes real relationship evidence, which still requires its artifact path and hash, from explicitly unavailable evidence, which records a reason, confirms that no artifact was fabricated, and states the scientific consequence. GSE161357 and GSE184237 use that strict unavailable state in their published manifests; no placeholder relationship file exists. This does not imply that relationship review occurred and supplies no subject, pairing, replicate, biological-unit, or independence evidence. Each second-cohort manifest also pins the approved capture identity, response hashes and byte counts, accession/UID trace, reviewed policy, serialized fixture, privacy review, and redistribution review.

The parser preserves exact HTTP response bytes only in the local cache. Parsed values are exact at the XML parser boundary; XML attribute ordering, quote and entity spelling, namespace-prefix spelling, CDATA presentation, empty-element spelling, source line endings, indentation, and other lexical markup details are not preserved after parsing. No benchmark BioSample semantic mapping, subject or specimen inference, audit rule, or report field is active. Strict production source parsing still requires the numeric BioSample UID; minimized fixture parsing does not, because the UID remains in manifest provenance rather than reduced XML. The opt-in CLI retrieves current or cached production responses and extracts repository identity evidence directly; it never loads these benchmark fixtures or selector policies at runtime.

Offline Sprint 1 benchmark corpus

The repository includes a frozen developer corpus of five reduced public GEO Series-family metadata extracts under benchmarks/:

• GSE161357
• GSE51518
• GSE52202
• GSE184237
• GSE198683

Each study keeps observed reduced SOFT metadata, a deterministic inventory built with the production parser/inventory code, and a separate human-reviewed study-scoped key mapping. Cross-study JSON and CSV catalogs aggregate exact keys without merging variants. GSE339369 is documented separately as an inventory stress case rather than a qualifying benchmark study.

Rebuild and verify all generated benchmark artifacts without network access:

python scripts/build_benchmark_fixtures.py
python scripts/build_benchmark_fixtures.py --check

An explicit --refresh fetches five official Series-family SOFT archives and filters them locally. It never follows links to FASTQ, BAM, CRAM, standalone expression matrices, or supplementary files; embedded Platform and data-table content is discarded rather than committed. Refresh stops if upstream decoded content differs from the reviewed source hashes. See the benchmark documentation and THIRD_PARTY_NOTICES.md before refreshing or redistributing snapshots.

Benchmark-only relationship oracle

Three pilot studies (GSE198683, GSE51518, and GSE52202) also have a developer relationship oracle. Its deterministic observed layer preserves source-pinned GSE, GSM, SAMN, SRS, SRX, and SRR accession edges and exact submitted-label occurrences. A separate reviewed layer records study-scoped relationship assertions and their explicit lifecycle. A .reviewed.json filename means that the artifact is intended for human review; it does not automatically mean that every assertion is accepted. reviewer_status is authoritative: pending assertions use not_assessed confidence and null reviewer fields, while accepted assertions require an assessed confidence, a non-null human reviewer ID, and a review date. The current three-study oracle contains 22 narrowly accepted assertions while retaining its explicit unknowns.

Build or verify the observed fixtures entirely offline:

python scripts/build_relationship_fixtures.py
python scripts/build_relationship_fixtures.py --check

The only network-enabled path is an explicit, fixed-allowlist SRA metadata refresh for the eight reviewed GSE52202 SRX accessions:

python scripts/build_relationship_fixtures.py \
  --refresh-sra \
  --email your.email@example.com

That refresh retrieves official RunInfo metadata, retains 13 accession and library/platform columns, and rejects source-hash, accession, or cardinality drift before writing. It excludes sequence-download paths, hashes, sizes, spot counts, base counts, and participant fields. The relationship builder never creates or overwrites relationship_ground_truth.reviewed.json, and it does not change the production geo-audit command or its outputs.

Human-reviewed representative-study contracts

The M3 representative-study package uses the same reviewed-design input, relationship-policy log, v1.1 reviewed contract, and validation-summary machinery as the GSE198683 workflow. GSE184237 records the owner-approved twelve-subject AD-minus-healthy independent-group design. GSE161357 records the exact five donor-level PLUS/MINUS pairs and donor block. GSE51518 preserves ten project-local E/L title-stem blocks while explicitly refusing to promote them into subject identity, physical identity, independence, biological replication, or statistical pairing.

Build or verify those canonical artifacts offline:

python scripts/build_representative_study_contracts.py
python scripts/build_representative_study_contracts.py --check

The focused validation computes the approved independent ~ group matrix at exact rank two and the paired ~ unit + condition matrix at exact rank six; both directed contrasts are algebraically estimable. Those deterministic algebra facts do not prove stochastic independence, model fitness, power, effect, significance, suitability, or analysis readiness. No paper/supplement content is invented for GSE184237, and the visible GEO/BioSample assay discrepancy remains source-separated. These benchmark contracts are never selected merely from a runtime accession.

Test

pytest -q
ruff check src tests scripts

Scientific interpretation policy

Every integrated statement carries its applicable evidence category or state:

• Observed: directly stated by a source record.
• Derived: calculated deterministically from observed records.
• Candidate: a bounded interpretation not accepted as biological truth.
• Reviewed: supported only within the scope of an explicitly supplied validated human review.
• Inferred: permitted interpretation from incomplete evidence with confidence and limitations; this milestone introduces none.
• Unresolved, unavailable, conflicting, or not assessed: the reason a conclusion cannot be reported is explicit rather than converted into a negative finding.

Categories are not silently promoted. A descriptive derived cross-tab is not an observed combined condition, a candidate is not reviewed, and unavailable evidence is not evidence of absence.

Current researcher-integration and design-reconstruction boundary

The backward-compatible v1.1 contract extension makes explicit positive human-reviewed relationship and variable mappings structurally representable without weakening v1.0. The generic deterministic application framework can now reproduce an exact approved v1.1 publication as a reconstructed design and immutable application log without choosing, repairing, normalizing, merging, or inferring design facts. Its approved inputs and outputs remain synthetic and temporary in this slice.

The default GSE198683 path remains its byte-identical anonymous v1.0 workflow. The parallel anonymous v1.1 contract, packet, and guide are review assistance only. Owner review and any later v1.1 publication or application for that study are separate human actions; no GSE198683 decision, reviewed contract, reconstructed design, or application log is created here. The inserted researcher-facing integration milestone now reports the evidence and lifecycle state actually supplied to a normal invocation, but it does not promote those states or auto-load a reviewed package. Genuine GSE198683 v1.1 review, publication and application, real-study assessment, and final evidence-backed verdict semantics remain separate human-reviewed work even though the generic synthetic matrix checks already exist.

See docs/ROADMAP.md.