Harako-RNAseq v0.3.0-beta.1

Harako-RNAseq v0.3.0-beta.1

Harako-RNAseq v0.3.0-beta.1 adds a controlled, machine-readable interface for
local automation tools such as Codex while retaining Harako as the scientific
execution engine.

Release date: 2026-08-12

Summary

The optional agent interface exposes deterministic planning, explicit
approval, execution through the existing Harako/Snakemake adapter, and
read-only run inspection. Harako does not contain an AI model, require Codex,
or delegate scientific eligibility decisions to an automation tool.

New agent commands

All commands emit one schema-versioned JSON object to stdout:

python -m app agent inspect-input --input /input --output inspection.json
python -m app agent propose-samples --inspection inspection.json --output samples.tsv --report proposal.json
python -m app agent propose-samples --inspection inspection.json --condition-map conditions.tsv --output samples.tsv --force
python -m app agent plan --samples samples.tsv --input /input --output /output --project-name study01 --species mouse --ref-preset mouse_ensembl_grcm39 --contrast-mode ref --contrast-ref control --threads 8 --plan harako-plan.yaml
python -m app agent validate-plan --plan harako-plan.yaml
python -m app agent dry-run --plan harako-plan.yaml
python -m app agent execute --plan harako-plan.yaml --approve <EXACT_APPROVAL_HASH>
python -m app agent status --run-dir /output/data_out/<run_id>
python -m app agent artifacts --run-dir /output/data_out/<run_id>
python -m app agent context --run-dir /output/data_out/<run_id> --output agent-context.json
python -m app agent post-analysis-init --run-dir /output/data_out/<run_id> --name review --question "Describe the limited read-only analysis"

Safety boundaries

• Conditions are never inferred; biological assignments require explicit user
  input.
• Ambiguous FASTQ pairing is not silently resolved.
• Execution requires the exact approval hash for the unchanged canonical plan.
• Plans reject arbitrary command fields.
• Raw FASTQ contents are not serialized into agent JSON.
• Harako embeds no OpenAI SDK, API client, API key handling, or model
  dependency, and performs no cloud upload of biological data.
• Core Run inputs and outputs remain immutable scientific evidence.
• Additional analyses are isolated under post_analysis/ and Harako does not
  execute arbitrary post-analysis code.
• QC-only output is not inferential differential-expression evidence and has
  no p-values, adjusted p-values, active contrasts, or enrichment.

Pilot evidence

A controlled local pilot used 12 paired-end samples in four explicitly
assigned conditions, with three samples per condition. The checksum-verified
mouse GRCm39 Ensembl release-113 reference and six pairwise comparisons were
approved. All 33 of 33 Snakemake jobs completed, the self-contained report and
expected typed artifacts were available, and post-analysis isolation was
confirmed without modifying selected core Run artifacts.

Compatibility

• v0.2 configuration files remain valid.
• Frozen v0.2 Run directories remain readable.
• The Streamlit GUI remains supported and is still the primary ordinary-user
  interface.
• Agent plans are optional.
• The existing differential-versus-QC-only policy, counts-based DESeq2 input,
  contrast handling, enrichment eligibility, and reference resolution are
  unchanged.

Limitations

• Operation remains local and single-user; there is no hosted multi-user
  service.
• Harako does not infer statistical designs, conditions, controls, or
  contrasts.
• Harako does not execute arbitrary post-analysis code.
• The software is not clinically validated.
• The supported image is linux/amd64; native arm64 images are not provided.
• STAR/HISAT2 alignment modes, BAM output, and MultiQC are not implemented.
• The minimum replicate gate is not a power calculation or proof of biological
  independence.

Licensing

Harako-RNAseq is source-available under the
PolyForm Noncommercial License 1.0.0. Third-party components
retain their own licenses and corresponding-source obligations as documented
in THIRD_PARTY_NOTICES.md.

Container and verification

After publication, the prerelease image references are:

• ghcr.io/do-shima/harako-rnaseq:v0.3.0-beta.1
• ghcr.io/do-shima/harako-rnaseq:beta

No latest tag is published for this prerelease.

The canonical digest is recorded in GHCR and the GitHub Release after
publication. Do not infer or substitute a digest from a local candidate image.
Attestation verification uses the final published image:

gh attestation verify \
  oci://ghcr.io/do-shima/harako-rnaseq:v0.3.0-beta.1 \
  -R do-shima/harako-rnaseq

Image availability begins only after the annotated tag triggers the
publication workflow and the GHCR build, SBOM, provenance, and attestation
steps succeed.

The final vulnerability review documents residual risk and beta dispositions;
it is not a security certification. Harako's PolyForm license does not
relicense third-party components.

Published image digest:
sha256:ede2d002117db44344f13ab738992524f304ba940bd1e2d29157555f6f0c7917

Verification:

• Anonymous pull: passed
• SBOM/provenance: published
• Attestation: verified

---

Known issue identified after release

In v0.3.0-beta.1, gene-level estimated counts from tximport were passed to
DESeq2 without the tximport-derived effective-length offset. This may affect
full-length RNA-seq analyses when average effective gene length differs across
samples, including cases involving differential isoform usage.

This does not mean that every v0.3.0-beta.1 result was incorrect, and the size
or direction of any effect cannot be determined without reanalysis.

This issue does not ordinarily apply to correctly identified 3′-tag RNA-seq
protocols, for which transcript-length correction is not recommended.

Users who analyzed full-length RNA-seq with v0.3.0-beta.1 should rerun the
analysis with v0.3.0-beta.2 or later.

Because v0.3.0-beta.1 did not record an explicit library protocol, users who
are unsure whether their data were generated using a full-length or 3′-tag
protocol should verify the library preparation before deciding whether
reanalysis is required.

Corrected release:
https://github.com/do-shima/harako-rnaseq/releases/tag/v0.3.0-beta.2