Generated assets v12 on Berkeley S3

Release runbook · v20260807 release notes · Cahill–Keyes generated snapshot

The public S3 release exposes the complete generated tree for direct web use without checking assets.generated/ into Git. It mirrors the immutable assets.generated.v12.tar.xz package attached to GitHub release v20260807. The package remains the byte-for-byte recovery artifact; the S3 tree/ is the browser-delivery form.

Identity and layout

cartofreako/v12/
├── tree/
│   ├── svg/
│   ├── pdf/
│   ├── png/
│   └── thumbnail/cahill-keyes/
├── package/assets.generated.v12.tar.xz
├── README.md
├── viewer.html
├── SHA256SUMS
└── release.json

The archive remains unchanged and contains 673 files below assets.generated/. The browser-delivery tree contains 589 files because its 187 source SVGs become 187 explicit gzip objects: the 84 supplied .svg.gz members are retained and the other 103 are generated deterministically. README.md describes the object release, viewer.html renders the compressed SVGs, SHA256SUMS covers the stored bytes of all 592 payload objects, and release.json records the destination, source identity, inventory, and delivery contract. The complete release has 594 objects. The completion marker is uploaded last; its absence means the prefix must be treated as incomplete.

Browser delivery and compression

The S3 tree publishes all 187 full SVGs only as tree/svg/*.svg.gz, plus 187 PDFs, 187 full-size PNGs, and 28 existing 480-by-240 PNG thumbnails. Large uncompressed .svg objects are deliberately absent:

The documentation grid embeds the small PNG previews rather than downloading full SVGs. A preview link opens the S3-hosted viewer with the gzip filename in its query string. The viewer validates that filename, fetches the adjacent tree/svg/*.svg.gz object with a relative URL, pipes the response body through DecompressionStream("gzip"), and displays the resulting SVG from a local blob URL. It also offers direct compressed and decompressed downloads. Hosting both files at the same S3 origin avoids cross-origin fetch requirements. Browsers without DecompressionStream retain the compressed-download fallback.

The public base URL is:

https://s3-ewh.ist.berkeley.edu/adekosnik-bucket01/cartofreako/v12/

For example, the CK geometry preview, compressed SVG, and viewer are:

• tree/thumbnail/cahill-keyes/geometry-ck-44-22.png
• tree/svg/geometry-ck-44-22.svg.gz
• viewer.html?asset=geometry-ck-44-22.svg.gz

Build, validate, and publish

The implementation follows the alpha60 cluster-operations upload boundary. It uses an empty temporary rclone configuration, asks for S3 credentials silently on /dev/tty, exports them only to the uploader process, unsets them on exit, and writes a sanitized log under /tmp/cartofreako-upload-logs/. Credentials must not be pasted into documentation, command arguments, chat, or a committed rclone configuration.

Build the S3 form only from the release archive, not from a potentially mixed live assets.generated/ directory:

scripts/build-generated-assets-s3-release.sh
scripts/upload-generated-assets-s3-release.sh --validate-only

The builder writes the ignored staging tree at build/s3-release-v12/. It checks the package digest and archive structure, extracts into a temporary directory, validates fixed inventories and the explicit gzip pairs, creates the other deterministic SVG gzip files, round-trips all 187 against the archive’s source SVGs, removes raw SVGs only from the temporary publication tree, installs the viewer, and constructs the sorted manifest and completion marker.

Run an authenticated remote inventory check and dry run:

scripts/upload-generated-assets-s3-release.sh

Publish only after reviewing that plan:

scripts/upload-generated-assets-s3-release.sh --apply --verify-download

Applied publication requires typing the exact destination adekosnik-bucket01/cartofreako/v12/. The uploader rejects remote objects not present in the release, uses checksum comparison plus rclone’s immutable mode, and never invokes sync or move. It first uploads one explicit SVG-gzip and one PNG pilot, verifies their S3 metadata and stored bytes through anonymous HTTPS, then verifies the same-origin viewer. The remaining payload is uploaded in MIME-specific phases, checked against the local stored bytes, and release.json is uploaded last. --verify-download performs an additional full remote read.

Uploader 2 stopped after creating two pilots and before creating release.json. Its obsolete tree/svg/geometry-ck-44-22.svg key is not part of the final explicit-gzip layout. Uploader 4 recognizes only that exact unexpected key on an incomplete prefix and requires a second exact-object confirmation before calling rclone deletefile for that object alone. It then refreshes the retained PNG pilot’s missing cache metadata. Any other unexpected object, or any cleanup attempt after a completion marker exists, is rejected.

The rclone remote root intentionally ends in /. Without that delimiter, rclone probes the root as a possible object with HeadObject; Berkeley’s Cloudian service has returned HTTP 500 rather than the expected not-found response for a brand-new prefix. Pilot and completion-marker uploads therefore use root-relative include filters instead of addressing a nonexistent object as the rclone remote root. This preserves normal HEAD-based integrity checks after each object exists.

HTTP system metadata is supplied with rclone’s direct upload-header mechanism. In rclone 1.74, --metadata-set is gated by --metadata; using it alone leaves Content-Encoding and Cache-Control unset, while enabling all metadata would also copy local UID, GID, mode, and timestamp fields. Direct upload headers set only the intended HTTP values. SVG gzip objects intentionally receive no Content-Encoding; the viewer, not the HTTP stack, performs decompression. If a retained pilot from an incomplete attempt has the right bytes but lacks its headers, the uploader may refresh that pilot after exact-destination confirmation. It never performs that repair after a release.json completion marker exists.

Active Archive report and delivery

The completed deposit has a Devastation Pacific Summer 2026 v1.1 report titled cartofreako v12 checked in to UCB Active Archive Object Storage. It uses the canonical archival palette, hard grid, evidence labels, and Atkinson Hyperlegible Next/Mono typography established by the Alpha60 year/2025 report. The recurring-notification randoma11y-style option is intentionally not used for this one-off release record.

Uploader 5 adds report production as stage 9 of a successful applied run. It unsets the S3 credential environment first, then calls scripts/build-generated-assets-s3-report.sh with the uploader run ID, Pacific verification time, and full-download status. The builder validates the local release evidence, renders tagged HTML-to-PDF output with Chrome, checks metadata, page size, page count, embedded/subset fonts, Unicode mappings, and text extraction, then renders all pages into a temporary QA directory for mandatory visual inspection. Its tracked source template is docs/releases/v12-active-archive-report.html.in; generated files are written to:

reports/cartofreako-v12-ucb-active-archive-check-in.html
reports/cartofreako-v12-ucb-active-archive-check-in.pdf

The actual v12 upload completed with uploader 4 run 20260807T091154Z; after the report integration was added, the builder was run against that exact release and its recorded full-readback completion time, 2026-08-07 02:22:51 PT. Final QA confirmed three US Letter pages, a tagged structure, coherent text extraction, embedded/subset Atkinson fonts with Unicode mappings, and visual inspection of every rendered page. The 132,115-byte PDF has SHA-256:

670a370ff6e3388fba0df5473ee05091f176347ca747e9f8b30243e2be4624ce

At 2026-08-07 03:00:48 PT, Gmail sent one message with that PDF attached to b.dekosnik@gmail.com and abigail.dekosnik@gmail.com. The subject was the exact report title above, and the mail service reported successful completion. The generated HTML, PDF, and QA renders remain ignored delivery artifacts; post-publication reports do not mutate the immutable S3 prefix.

The delivery artifact is specifically the three-page cartofreako-v12-ucb-active-archive-check-in.pdf. The separate two-page cartofreako-v12-deposit-report.pdf is a generic deposit-verification layout, not the Active Archive check-in style, and must not be selected by the uploader or attached to the completion notice. The report builder gates the canonical document-kind marker, exact title, three-page Letter structure, Active Archive kicker, and embedded Atkinson Next/Mono fonts; it also rejects the generic deposit report’s Liberation Sans and DejaVu Sans Mono fonts.

Immutability and later versions

Do not repair or replace bytes under cartofreako/v12/. If a published object, metadata value, source render, or manifest needs correction, build a new versioned prefix such as cartofreako/v13/ and update documentation to point to it. Mutable catalogs or post-publication reports belong outside the immutable release root.