What Atlas Is¶
Atlas is a release-oriented system for genomic reference data. It accepts governed GFF3 and FASTA sources, constructs query artifacts, verifies their identity and integrity, publishes them immutably, and exposes the published state through CLI, HTTP, OpenAPI, and Rust interfaces.
The runtime may select and query a release. It may not mutate release truth.
The Product Boundary¶
flowchart LR
Source["GFF3 + FASTA + provenance"] --> Admit["format + identity + policy admission"]
Admit --> Build["normalization + indexes + database + manifest"]
Build --> Verify["structure + references + hashes + quality"]
Verify --> Publish["immutable store payload"]
Publish --> Promote["catalog identity"]
Promote --> Serve["bounded queries + provenance"]
Atlas owns the behavior of this path. It does not certify the biological truth of the upstream annotation, replace source governance, or turn an arbitrary local directory into a release.
Three Identities Explain a Result¶
| Identity | Answers | Anchored by |
|---|---|---|
| scientific source | which records and coordinate system entered the build | source hashes, metadata, species, assembly, and normalization policy |
| published dataset | which immutable bytes were selected | dataset tuple, catalog generation, manifest, and artifact hashes |
| request execution | which software and policy produced the observation | software, configuration, principal, route, query plan, request, and status |
flowchart LR
Source["scientific source"] --> Dataset["published dataset"]
Dataset --> Execution["request execution"]
Execution --> Result["structured result"]
The same dataset can be served by several compatible software releases without changing its data identity. One server can expose several named datasets without inventing an implicit “current” release.
Dataset, Software, and Target Advance Independently¶
| Identity | Changes when |
|---|---|
| dataset release | source, normalization, schema, or artifact content changes |
| software release | binaries, public contracts, chart, or packaged software changes |
| deployment qualification | target, profile, policy, dependency, selected dataset, or evidence window changes |
A software release does not republish unchanged genomic data. A new dataset does not prove every software release can serve it. Deployment qualification joins exact dataset and software identities with evidence observed in one target.
Durable Product Objects¶
| Object | Durable meaning |
|---|---|
| dataset tuple | release/species/assembly names one logical dataset |
| manifest | binds source identity, layout, statistics, and hashes |
| catalog entry | makes a published tuple discoverable |
| query contract | defines selectors, regions, ordering, limits, and cursors |
| structured result | carries typed data or a stable error envelope |
| operational receipt | binds target evidence to software and dataset identities |
Caches, logs, local SQLite handles, process memory, and mutable aliases are not release authority.
Design Commitments¶
Atlas favors:
- deterministic construction from admitted inputs and explicit configuration;
- immutable published bytes over in-place data mutation;
- narrow crate and interface ownership over a monolithic runtime;
- stable fields and error codes over message-text conventions;
- bounded rejection and observable degradation over optimistic availability;
- explicit promotion and rollback evidence over inferred success.
It refuses to:
- serve an unpublished build root as a released dataset;
- silently coerce incompatible coordinates or dataset identities;
- let a cache entry or alias redefine published identity;
- treat artifact presence as proof of completed verification; or
- infer source provenance backward from a healthy process.
Evaluate a Result¶
flowchart RL
Result["query result"] --> Dataset["dataset tuple"]
Dataset --> Catalog["catalog generation"]
Catalog --> Manifest["manifest + artifact hashes"]
Manifest --> Inputs["source hashes + provenance"]
Result --> Contract["interface contract"]
Result --> Runtime["software + configuration"]
Start with the returned dataset identity. Follow it through the catalog and manifest to the source and artifact hashes. Separately confirm the interface contract and effective runtime identity. A result missing that chain may be useful interactively, but it is insufficient for audit, release comparison, or rollback decisions.
Continue with Core Concepts, the Dataset Model, and the System Overview.