Metadata-Version: 2.4
Name: geo-design-auditor
Version: 1.0.1
Summary: A deterministic, provenance-aware foundation for reconstructing and auditing GEO experimental designs.
Author: Project Author
License-Expression: MIT
Keywords: bioinformatics,GEO,RNA-seq,metadata,experimental-design
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Requires-Python: <3.15,>=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: THIRD_PARTY_NOTICES.md
License-File: LICENSES/GPL-3.0-only.txt
License-File: LICENSES/LGPL-3.0-only.txt
Requires-Dist: defusedxml==0.7.1
Requires-Dist: et-xmlfile==2.0.0
Requires-Dist: openpyxl==3.1.5
Requires-Dist: pypdf==6.15.0
Requires-Dist: PySide6-Essentials==6.11.2
Requires-Dist: PyYAML==6.0.3
Requires-Dist: shiboken6==6.11.2
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: ruff>=0.6; extra == "dev"
Provides-Extra: release
Requires-Dist: build==1.5.0; extra == "release"
Dynamic: license-file

# 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:

```text
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:

```text
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](docs/index.md) 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:

```bash
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:

```bash
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:

```text
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](THIRD_PARTY_NOTICES.md).

```bash
python -m venv .venv

# Windows PowerShell
.venv\Scripts\Activate.ps1

# macOS/Linux
source .venv/bin/activate

pip install -e ".[dev]"
```

## Run

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

Or:

```bash
python -m geo_design_auditor GSE123456 --out results
```

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

```bash
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:

```bash
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:

```text
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:

```text
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):

```text
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:

```bash
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:

```text
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):

```bash
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:

```bash
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:

```text
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>/`:

```text
<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:

```bash
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:

```text
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:

```bash
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:

```text
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/`:

```text
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:

```powershell
.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:

```bash
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:

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

To validate another separately reviewed policy without consuming a package:

```bash
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:

```bash
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:

```text
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:

```powershell
.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:

```powershell
.\.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:

```powershell
.\.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:

```powershell
.\.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:

```powershell
.\.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:

```text
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:

```powershell
.\.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:

```powershell
.\.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:

```powershell
.\.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:

```text
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:

```powershell
.\.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:

```powershell
.\.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:

```powershell
.\.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:

```text
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:

```powershell
.\.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:

```powershell
.\.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:

```text
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:

```powershell
# 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:

```powershell
.\.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:

```powershell
.\.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:

```text
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:

```powershell
.\.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:

```powershell
.\.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:

```powershell
$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:

```text
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:

```powershell
$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:

```powershell
.\.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:

```powershell
.\.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:

```powershell
.\.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:

```powershell
.\.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:

```powershell
.\.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:

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

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

```text
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:

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

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

```bash
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:

```bash
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](https://www.ncbi.nlm.nih.gov/books/NBK25497/).

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:

```bash
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:

```bash
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`:

```bash
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:

```bash
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/`](benchmarks/README.md):

- `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:

```bash
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](benchmarks/README.md) and
[`THIRD_PARTY_NOTICES.md`](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:

```bash
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:

```bash
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:

```bash
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

```bash
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`](docs/ROADMAP.md).
