From ab7a0dd06ee982795be1b004a62b18f7b84d23f4 Mon Sep 17 00:00:00 2001 From: Andrew Altshuler Date: Wed, 1 Jul 2026 17:15:35 +0300 Subject: [PATCH] =?UTF-8?q?docs(release):=20complete=20v0.8.0=20notes=20?= =?UTF-8?q?=E2=80=94=20#314=20stricter=20validation=20+=20#316=20linux-arm?= =?UTF-8?q?64=20(#320)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * docs(release): cover #314 stricter validation + #316 linux-arm64 in v0.8.0 notes Two changes landed after the version-bump commit (#313) that wrote the v0.8.0 release notes, so they were undocumented: - #314 unified constraint validation across the loader, mutation, and merge surfaces. Its behavior changes are all stricter (enum enforced on merge, cross-version @unique rejection, precise within-batch vs across-batch dup-key semantics, per-table overwrite validation) and are user-visible, so they get a dedicated section. - #316 added linux-arm64 (aarch64) as a first-class prebuilt target + Homebrew bottle; note the new platform. Also mention the stricter validation in the release intro. Docs-only. Co-Authored-By: Claude Opus 4.8 (1M context) * docs(release): scope cross-version uniqueness to the write's visible state Greptile P2: the prior wording implied a live-head @unique guarantee, but #314's check is snapshot-scoped (probes the write's pinned base view via the @key/@unique BTREEs), so a concurrent writer committing the same value after the base was opened is not caught — matching the 'full cross-version uniqueness is still a gap' note in docs/dev/invariants.md. Qualify with 'visible to that write'. Co-Authored-By: Claude Opus 4.8 (1M context) --------- Co-authored-by: Claude Opus 4.8 (1M context) --- docs/releases/v0.8.0.md | 49 +++++++++++++++++++++++++++++++++++++++-- 1 file changed, 47 insertions(+), 2 deletions(-) diff --git a/docs/releases/v0.8.0.md b/docs/releases/v0.8.0.md index 94e9b18d..18d3dd71 100644 --- a/docs/releases/v0.8.0.md +++ b/docs/releases/v0.8.0.md @@ -1,11 +1,12 @@ # Omnigraph v0.8.0 This release moves the graph commit lineage into `__manifest` (RFC-013 Phase 7), -retires the two legacy commit-graph datasets, and surfaces the storage-format +retires the two legacy commit-graph datasets, unifies constraint validation across +every write surface (stricter in a few cases), and surfaces the storage-format version to operators. It is the first release with an internal-schema change since v0.4.0, and storage is **strict-single-version**: there is no in-place migration — a graph from an older release is rebuilt via export/import. Read the upgrade notes -before rolling it out. +and the stricter-validation notes before rolling it out. ## Graph lineage now lives in `__manifest` (internal schema v4) @@ -60,6 +61,50 @@ it through a refusal: - The server `GET /healthz` response includes `internal_schema_version` (the binary's served version). +## Stricter, unified constraint validation (#314) + +Constraint enforcement — value/range/`@check`, enum, `@unique`, edge referential +integrity, and cardinality — was previously implemented separately in the bulk +loader, the mutation executor, and the branch-merge path, and had drifted. All three +write surfaces now route through one catalog-derived evaluator, so they can no longer +diverge. The evaluator is delta-scoped (it checks only the change set) and +index-backed (it probes committed state through the `@key`/`@unique`/`src`/`dst` +BTREEs instead of scanning every catalog table), so a one-row merge opens ~3 data +tables instead of 6+ and validation cost is flat in graph size rather than O(V+E). + +The unification closes real gaps. **These behavior changes are all stricter — none +relax an existing check** — so a graph that already satisfies its schema is +unaffected, but inputs that previously slipped through are now rejected before the +commit: + +- **Enum constraints are enforced on the merge path** (previously a gap: merge + validated `@range`/`@check` but not enum). +- **Cross-version uniqueness is enforced.** A write or load whose `@unique` value + collides with an already-committed *different* row visible to that write is now + rejected. Re-upserting an existing `@key` still upserts as before. +- **Duplicate-key semantics are precise.** A `@key` that appears twice as two + distinct records *within one input batch* (e.g. a bulk load listing the same key + twice) is rejected; the *same* id reappearing *across* batches (e.g. an + insert-then-update in one mutation) is coalesced as ordered supersession of one + logical row. +- **Overwrite loads validate per touched table.** A table in the overwrite batch is + validated against its replacement image (an empty committed view); a table absent + from the batch keeps its committed rows, so an edges-only overwrite still resolves + referential integrity against the retained nodes. + +If an ingestion pipeline unknowingly relied on one of these gaps — a duplicate +`@unique` value, or an enum violation reaching a branch through merge — it will now +fail loudly at write time. Validate load inputs against the schema before upgrading +if in doubt. + +## New prebuilt platform: linux-arm64 (#316) + +Tagged releases now ship an `omnigraph-linux-arm64` (aarch64) archive alongside the +existing Linux x86_64, macOS arm64, and Windows x86_64 builds, and the Homebrew +formula carries a matching `on_linux`/`on_arm` bottle. The install script maps +Linux/aarch64 to the new asset, so aarch64 Linux is now a first-class prebuilt +target instead of build-from-source. + ## Upgrade order Upgrade every binary that touches a graph to v0.8.0 together. A mixed fleet where an