docs(release): complete v0.8.0 notes — #314 stricter validation + #316 linux-arm64 (#320)

* 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) <noreply@anthropic.com>

* 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) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
Andrew Altshuler 2026-07-01 17:15:35 +03:00 committed by GitHub
parent b73cf1a92e
commit ab7a0dd06e
No known key found for this signature in database
GPG key ID: B5690EEEBB952194

View file

@ -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