1# Atlas authoring23Atlas creation has one public input and one public operation:45```text6sample-region.atlas-project7 │8 ▼9atlas build ── plan ── capture ── observe ── assemble ── compile ── install10 │ shared content cache │11 └────────────────────────────────────────────────────────┘12 immutable native .atlas13```1415The manifest is configuration, not a project directory. Source bytes are held16once in a shared content-addressed cache; successful outputs are held once in17the Atlas library. Moving the manifest preserves request identity because18remote locators remain authored and local locators resolve relative to the19manifest.2021## Commands2223```sh24# Inspect the exact source requests and output without fetching or writing.25go run ./cmd/atlas build -plan-json examples/sample-region.atlas-project2627# Build and atomically install a native vNext volume.28go run ./cmd/atlas build examples/sample-region.atlas-project2930# Rebuild only from already captured evidence.31go run ./cmd/atlas build -offline examples/sample-region.atlas-project3233# Rebuild from the exact evidence selected by an earlier Atlas or receipt.34go run ./cmd/atlas build -replay previous-build.atlas examples/sample-region.atlas-project3536# Edit, inspect, build, and hand the result to Atlas from the workbench.37go run ./cmd/atlas workbench examples/sample-region.atlas-project38```3940`-cache` selects the evidence cache and `-bundles` selects the Atlas library.41Their defaults are the application-owned cache and library.4243## Contract4445- `atlas-project/v2` is an intentional hard break. Top-level `feature-sets`46 declare stable semantic membership, one homogeneous `point`, `path`, or47 `area` geometry family, typed property contracts, and relationship contracts.48 Semantic types remain domain language rather than geometry labels.49- Feature adapters acquire evidence; source mappings only bind identity, title,50 geometry transforms, property paths, and relationship paths to a declared51 FeatureSet. An adapter cannot redefine a set's title, semantic type, geometry,52 field types, or relationship meaning.53- The YAML decoder is strict. Unknown keys, duplicate identities, incomplete54 mappings, broken presentation references, and invalid raster plans fail.55- Adapters describe acquisition; declarative mappings describe meaning.56 Built-ins are `geojson`, `arcgis-feature-service`, `ogc-api-features`,57 `raster-file`, explicit-window `xyz`, and REST-template `wmts`.58- Planning performs no network or filesystem writes. Every request has a stable59 binding identity plus a source-independent acquisition identity that includes60 adapter version, portable locator, media type, and tile coordinates. The plan61 reports validated cache presence, estimated bytes, and obligations; identical62 acquisitions may be shared across projects without merging their semantics.63- Every plan resolves stable refusal budgets for request bytes, total evidence,64 request count, raster tile count, raster pixel count, emitted feature count,65 and emitted geometry positions. The `features` default is 2,000,000 fused66 features and the `geometry-positions` default is 50,000,000 positions; the67 manifest may state smaller or deliberately larger positive limits. Planning68 rejects tile explosions before enumeration; capture rejects at `limit + 1`;69 semantic assembly counts the70 final fused output with checked arithmetic before native compilation. Online,71 offline, and exact replay apply the same limits. Atlas never truncates to fit72 a budget.73- Capture envelopes retain request identity, body hash, media type, timestamp,74 licence, and attribution. Changed bodies append history instead of replacing75 evidence. Cache reads verify the envelope, body length, and body SHA-256;76 repeated or concurrent bytes retain one first-seen timestamp.77- Observations retain source-native identity and evidence. Assembly begins from78 the declared contracts, so empty sets and optional fields remain explicit in79 the native result. It merges only canonical identities declared by the80 manifest; earlier sources win conflicts and every contributor remains in81 provenance. Required properties and relationships are checked after fusion,82 allowing one source to complete another. Property contracts retain bool,83 int64, float64, string, bytes, and stable-ID kinds; relationships name their84 target FeatureSet and canonical feature identity.85- A local raster image is deterministically expanded into the declared native86 pyramid. Explicit XYZ sources retain authored windows. Authored supporting87 assets are captured, packed, and may be referenced directly by styles.88- Presentation is compiled directly into native styles and layers. There is no89 legacy JSON document or enrichment projection between authored intent and the90 packed schema.91- Publishing writes from the already validated file handle, syncs the staged92 file, commits without replacement, syncs the library directory, and fully93 validates the installed result. An existing stamp-named file must itself be94 valid and byte-identical. Rebuilding the same project from the same evidence95 produces the same bytes and returns the existing file; corrupt or colliding96 targets fail loudly.97- Every build embeds an executable v3 evidence receipt. Each selected capture98 carries the adapter and version, exact hashes and media metadata, and its99 licence/attribution obligation. `-replay` selects those100 exact immutable capture hashes even when newer evidence exists. Mapping and101 presentation changes may deliberately replay the same acquisitions, while a102 changed locator, query, media type, or adapter version is refused as drift.103104## Workbench105106The desktop application now provides the default creation path directly on107its included Earth: telescope anywhere, use the current view or draw a108rectangle, choose the U.S.-coverage USGS/TIGER source pack and presentation,109then mint. The selection is geographic, not fenced to the current sources;110new source packs can reuse the same surface. Atlas writes the same single111manifest documented here into its app-owned `recipes/` directory, uses its112shared cache, installs the native result, and opens it. No separate site or113Workbench process is required.114115Workbench is the advanced surface for someone who wants to inspect or edit the116full manifest, capture graph, receipts, compiled schema, or physical artifact.117118The workbench receives one manifest path at startup. Browser requests cannot119choose another file, cache, command, or output directory.120121The Project page shows the resolved build graph, cache readiness, estimated122input, licence/attribution obligations, manifest editor, and the build log. A123build belongs to the workbench process rather than the POST request, so reloads124do not cancel it. When it completes, **Open in Atlas** performs a native file125handoff; the artifact card also supports dragging the `.atlas` onto an Atlas126window.127128The compiled inspector is derived only from the validated `.atlas`, never from129the manifest. It shows the carried/runtime schema boundary, worlds, coordinate130space, explicit FeatureSet contracts (including empty sets), paged feature131facts, geometry, relationships, provenance, raster/presentation semantics,132assets, and the integrity-protected evidence/legal receipt.133134## Production envelope135136The current native container is intentionally bounded: a strict entry/reference137budget, exact ZIP-entry role bijection, Store-only table/blob references,138bounded bootstrap/schema/table/blob reads, deterministic validation order, and139streamed opaque-blob hashing. These are refusal boundaries, not claims that the140current single feature pack and per-tile ZIP layout scale without limit. The141next storage-generation break for genuinely massive worlds is partitioned142feature blocks plus deterministic raster shard packs and range/page APIs.143144Release publication runs correctness and browser acceptance first, then builds145native desktop delivery on each target OS. macOS exports the Atlas UTI from a146signed/notarizable application bundle, Linux installs a desktop entry and147shared MIME declaration from a `.deb`, and Windows installs and immediately148smokes its per-user `.atlas` association. Signing steps are inert when their149CI credentials are absent; adding the documented release secrets activates150the same package path rather than a second release recipe.151152The release job checks the exact eight-asset allowlist, validates every package153payload, and drives the packaged CLI through online and cache-only Sample154Region builds. Those two `.atlas` files must be byte-identical and readable by155the packaged measurement command. Only then does it generate and verify156`SHA256SUMS`, upload all nine files to a draft, compare the complete local and157remote asset sets, verify each remote asset's GitHub SHA-256 digest, and make158the release public. Both CLI and desktop binaries answer `--version` from the159release tag.160161The former `crawl`, `tiles`, `compose`, `enrich`, and `translate` commands and162the Sources/Operations workbench pages are no longer public interfaces. Their163code remains only as migration and corpus-test material while existing fixtures164are retired.