# R3 Bounded Storage Execution Plan This plan executes the R3 release checklist in [`02-production-readiness.md`](./02-production-readiness.md). PostgreSQL source tables remain authoritative. Every build artifact and intermediate run is derived, checksummed, permission-restricted, disposable, and invisible to readers until the generation publication boundary accepts it. ## R3A: Coherent Source Boundary — Complete - Acquire the graph build lock, then lock pgGraph registration tables in a fixed order before reading the catalog. - Resolve registered source roots by OID, discover partitions while their roots are locked, and lock every source relation in deterministic OID order. - Reject caller-owned catalog or source write locks so an uncommitted source mutation cannot escape PostgreSQL rollback through filesystem publication. - Reconcile sync triggers, acquire the writer barrier, validate schema and caller privileges, and capture source watermark `W0` before scanning. - Immediately before persistence or backend installation, re-read the catalog, schema, caller privileges, and watermark `W1`. Require the same catalog fingerprint and `W1 = W0`. The 1.0 strategy deliberately fences writers for the transaction, so bounded catch-up contains zero rows. Cross-transaction or resumable snapshots require a durable delta coordinator and are not used by the 1.0 build path. ## R3B: Governed Build Runs — Complete - Add versioned node, relationship-outbound, relationship-inbound, filter, filter-dictionary, and resolution run records with manual little-endian codecs. Preserve duplicates and stable source identities. - Use a 128-byte checksummed run header bound to graph ID, build ID, catalog fingerprint, run kind, record count, and payload length. - Bound record size, collector bytes, read/write buffers, open readers, merge fanout, spill files, spill bytes, elapsed time, and interrupt cadence through the existing resource governor. - Merge at a fixed fanout, using one decoded record per input and a bounded heap. Validate checksums and sorted order before an input can influence an output. - Create build workspaces with mode `0700` and files with mode `0600`. Cleanup partial files on failure and abandoned workspaces only while holding the graph build lock. ## R3C: Artifact v6 And Bounded Load — Complete - Replace artifact v4/v5 with a 512-byte, 64-byte-aligned v6 header containing 26 explicitly sized sections: node metadata; forward CSR; inbound CSR; resolution; filter catalog/data/dictionaries; edge-type registry; and relationship-identity descriptors/key bytes; tenant table OIDs, dictionary, and node tokens. - Encode the header manually in little-endian form. It records the exact body length, body checksum, header checksum, forward and inbound counts and weights, and 26 `{offset, length}` descriptors. Reject nonzero padding, overlapping or unaligned ranges, reserved bits, and any exact-length mismatch before constructing typed mapped views. - Validate header/body checksums, gaps, alignments, exact cardinalities, both CSR orientations, node and resolution ranges, filter layouts, dictionary ordering, UTF-8, relationship identity, tenant metadata, and direction capability before creating mapped stores. - Map both CSR directions and graph-sized relationship/filter/dictionary data. Keep only bounded descriptors and the edge-label registry as private metadata. - Represent filters as an owned or mapped immutable base plus a sparse delta. Projection generations clone only mapping metadata and the delta, never the complete base index. - Encode filter catalog descriptors, dense or sorted-sparse values, and lexically ordered UTF-8 dictionaries without bincode. Mapped dictionary tokens remain stable; later projection values use overlay tokens after the immutable base dictionary. - Store forward and inbound relationship IDs beside each mapped CSR. Store the identity dictionary as checked fixed-width descriptors plus UTF-8 key bytes, with slot zero reserved and every referenced ID validated before install. - Continue using the governed anonymous read-only snapshot for 1.0 so another process cannot invalidate Rust references by modifying an inode. Report the snapshot as private mapped residency and report expected filesystem page-cache pressure separately. Artifact v5 and earlier versions, plus future versions, fail closed with rebuild guidance. Derived artifacts are rebuilt from PostgreSQL; bytes are never silently reinterpreted or migrated in place. ## R3D: Direct Persisted Build And Publication — Complete - Make persisted build and vacuum scan bounded source batches directly into the run collectors. The legacy owned build remains only as the nonpersisted path and equivalence oracle until the differential gate is green. - Pre-compute the checked layout from merged-run summaries, preallocate one generation-specific staging artifact, and stream each run directly into its final section. Do not construct or retain a complete owned `Engine` on the persisted path. - Stream and fsync a generation-specific v6 candidate, validate it through the production loader, repeat the R3A final checks, and publish through the R2D graph-scoped compare-and-swap pointer. - Retain the previous generation for rollback and reader pins. Failed scan, spill, merge, write, checksum, fsync, validation, catalog, watermark, or CAS steps remove only private staging state. ## Acceptance Gates - In-memory and spill builds are equivalent for node identity, both CSR directions, relationship identity/type/weight/direction, filters, dictionaries, tenants, resolution, and representative GQL. - Tiny budgets force multiple runs and at least three merge passes without exceeding configured memory, disk, file-count, row, or time limits. - Concurrent writers, catalog changes, source DDL, partition-leaf writes, and trigger bypass either appear at the declared watermark or fail before publication. - Corrupt/truncated/future runs and artifacts fail before typed mapped views are constructed. - ENOSPC, quota, interrupt, write, fsync, checksum, validation, and CAS faults preserve the prior serving generation. - Repeated build/load/sync/compact/drop and failed-build cycles show no upward RSS/PSS or staging/artifact file-count trend. - Formatting, Clippy, rustdoc, Rust/PostgreSQL tests, compatibility drift, supported-major publication checks, sanitizer/fuzz checks, playground, and the full release gate pass before R3 closes.