From aa7853743af07445c38bbd8c3ea58db7769ed864 Mon Sep 17 00:00:00 2001 From: tamnd <1218621+tamnd@users.noreply.github.com> Date: Sat, 8 Aug 2026 17:51:35 +0700 Subject: [PATCH] Migrate graph research corpus --- README.md | 7 + docs/00-index.md | 89 ++ docs/01-current-state-audit.md | 169 ++++ docs/02-architecture-flaws.md | 122 +++ docs/03-product-contract.md | 135 +++ docs/04-target-architecture.md | 179 ++++ docs/05-storage-query-contract.md | 210 +++++ docs/06-identity-and-data-model.md | 144 +++ docs/07-query-engine.md | 131 +++ docs/08-transactions-and-recovery.md | 132 +++ docs/09-zu1-format-and-io.md | 130 +++ docs/10-sqlite-backend.md | 89 ++ docs/11-object-storage.md | 133 +++ docs/12-runtime-and-resources.md | 149 +++ docs/13-qualification-and-operations.md | 151 +++ docs/14-roadmap-and-verification.md | 211 +++++ docs/15-research-sources.md | 169 ++++ docs/README.md | 6 + docs/research/000-index.md | 520 ++++++++++ docs/research/engine-aerospike_graph.md | 885 +++++++++++++++++ docs/research/engine-agensgraph.md | 884 +++++++++++++++++ docs/research/engine-allegrograph.md | 884 +++++++++++++++++ docs/research/engine-amazon_neptune.md | 885 +++++++++++++++++ .../engine-amazon_neptune_analytics.md | 884 +++++++++++++++++ docs/research/engine-apache_age.md | 885 +++++++++++++++++ docs/research/engine-apache_hugegraph.md | 886 +++++++++++++++++ docs/research/engine-apache_jena_tdb2.md | 886 +++++++++++++++++ docs/research/engine-arangodb.md | 885 +++++++++++++++++ docs/research/engine-arcadedb.md | 885 +++++++++++++++++ .../research/engine-azure_cosmosdb_gremlin.md | 884 +++++++++++++++++ docs/research/engine-blazegraph.md | 884 +++++++++++++++++ docs/research/engine-cozodb.md | 884 +++++++++++++++++ .../engine-datastax_enterprise_graph.md | 884 +++++++++++++++++ docs/research/engine-dgraph.md | 884 +++++++++++++++++ docs/research/engine-duckpgq.md | 886 +++++++++++++++++ docs/research/engine-falkordb.md | 885 +++++++++++++++++ docs/research/engine-google_spanner_graph.md | 884 +++++++++++++++++ docs/research/engine-graphscope_flex.md | 886 +++++++++++++++++ docs/research/engine-helixdb.md | 886 +++++++++++++++++ docs/research/engine-huawei_ges.md | 886 +++++++++++++++++ docs/research/engine-ibm_db2_graph.md | 883 +++++++++++++++++ docs/research/engine-janusgraph.md | 886 +++++++++++++++++ docs/research/engine-kuzu.md | 885 +++++++++++++++++ docs/research/engine-ladybugdb.md | 885 +++++++++++++++++ docs/research/engine-memgraph.md | 886 +++++++++++++++++ .../research/engine-microsoft_fabric_graph.md | 885 +++++++++++++++++ docs/research/engine-millenniumdb.md | 884 +++++++++++++++++ docs/research/engine-nebulagraph.md | 885 +++++++++++++++++ docs/research/engine-neo4j.md | 885 +++++++++++++++++ docs/research/engine-ontotext_graphdb.md | 885 +++++++++++++++++ docs/research/engine-openlink_virtuoso.md | 885 +++++++++++++++++ docs/research/engine-oracle_property_graph.md | 884 +++++++++++++++++ docs/research/engine-orientdb.md | 885 +++++++++++++++++ docs/research/engine-oxigraph.md | 884 +++++++++++++++++ docs/research/engine-puppygraph.md | 885 +++++++++++++++++ docs/research/engine-redisgraph.md | 884 +++++++++++++++++ docs/research/engine-sap_hana_graph.md | 883 +++++++++++++++++ docs/research/engine-stardog.md | 885 +++++++++++++++++ docs/research/engine-surrealdb.md | 886 +++++++++++++++++ docs/research/engine-terminusdb.md | 886 +++++++++++++++++ docs/research/engine-tigergraph.md | 886 +++++++++++++++++ docs/research/engine-tugraph.md | 885 +++++++++++++++++ docs/research/engine-typedb.md | 886 +++++++++++++++++ docs/research/engine-ultipa.md | 885 +++++++++++++++++ .../system-benchmark-and-10x-claim.md | 520 ++++++++++ docs/research/system-landscape-scorecard.md | 520 ++++++++++ docs/research/system-target-architecture.md | 520 ++++++++++ src/generate_research.py | 890 ++++++++++++++++++ 68 files changed, 45146 insertions(+) create mode 100644 docs/00-index.md create mode 100644 docs/01-current-state-audit.md create mode 100644 docs/02-architecture-flaws.md create mode 100644 docs/03-product-contract.md create mode 100644 docs/04-target-architecture.md create mode 100644 docs/05-storage-query-contract.md create mode 100644 docs/06-identity-and-data-model.md create mode 100644 docs/07-query-engine.md create mode 100644 docs/08-transactions-and-recovery.md create mode 100644 docs/09-zu1-format-and-io.md create mode 100644 docs/10-sqlite-backend.md create mode 100644 docs/11-object-storage.md create mode 100644 docs/12-runtime-and-resources.md create mode 100644 docs/13-qualification-and-operations.md create mode 100644 docs/14-roadmap-and-verification.md create mode 100644 docs/15-research-sources.md create mode 100644 docs/research/000-index.md create mode 100644 docs/research/engine-aerospike_graph.md create mode 100644 docs/research/engine-agensgraph.md create mode 100644 docs/research/engine-allegrograph.md create mode 100644 docs/research/engine-amazon_neptune.md create mode 100644 docs/research/engine-amazon_neptune_analytics.md create mode 100644 docs/research/engine-apache_age.md create mode 100644 docs/research/engine-apache_hugegraph.md create mode 100644 docs/research/engine-apache_jena_tdb2.md create mode 100644 docs/research/engine-arangodb.md create mode 100644 docs/research/engine-arcadedb.md create mode 100644 docs/research/engine-azure_cosmosdb_gremlin.md create mode 100644 docs/research/engine-blazegraph.md create mode 100644 docs/research/engine-cozodb.md create mode 100644 docs/research/engine-datastax_enterprise_graph.md create mode 100644 docs/research/engine-dgraph.md create mode 100644 docs/research/engine-duckpgq.md create mode 100644 docs/research/engine-falkordb.md create mode 100644 docs/research/engine-google_spanner_graph.md create mode 100644 docs/research/engine-graphscope_flex.md create mode 100644 docs/research/engine-helixdb.md create mode 100644 docs/research/engine-huawei_ges.md create mode 100644 docs/research/engine-ibm_db2_graph.md create mode 100644 docs/research/engine-janusgraph.md create mode 100644 docs/research/engine-kuzu.md create mode 100644 docs/research/engine-ladybugdb.md create mode 100644 docs/research/engine-memgraph.md create mode 100644 docs/research/engine-microsoft_fabric_graph.md create mode 100644 docs/research/engine-millenniumdb.md create mode 100644 docs/research/engine-nebulagraph.md create mode 100644 docs/research/engine-neo4j.md create mode 100644 docs/research/engine-ontotext_graphdb.md create mode 100644 docs/research/engine-openlink_virtuoso.md create mode 100644 docs/research/engine-oracle_property_graph.md create mode 100644 docs/research/engine-orientdb.md create mode 100644 docs/research/engine-oxigraph.md create mode 100644 docs/research/engine-puppygraph.md create mode 100644 docs/research/engine-redisgraph.md create mode 100644 docs/research/engine-sap_hana_graph.md create mode 100644 docs/research/engine-stardog.md create mode 100644 docs/research/engine-surrealdb.md create mode 100644 docs/research/engine-terminusdb.md create mode 100644 docs/research/engine-tigergraph.md create mode 100644 docs/research/engine-tugraph.md create mode 100644 docs/research/engine-typedb.md create mode 100644 docs/research/engine-ultipa.md create mode 100644 docs/research/system-benchmark-and-10x-claim.md create mode 100644 docs/research/system-landscape-scorecard.md create mode 100644 docs/research/system-target-architecture.md create mode 100644 src/generate_research.py diff --git a/README.md b/README.md index 855ba20..7f918b1 100644 --- a/README.md +++ b/README.md @@ -35,6 +35,13 @@ Research is current to the date recorded in each specification. Database releases, pricing, source heads, issues, and managed-service behavior change; revalidate decision-critical claims before adopting them. +Start with: + +- [Research corpus index](./docs/research/000-index.md) +- [Cross-engine landscape](./docs/research/system-landscape-scorecard.md) +- [Target architecture](./docs/research/system-target-architecture.md) +- [Reproducible benchmark and 10x protocol](./docs/research/system-benchmark-and-10x-claim.md) + ## License The repository's original text and scripts are available under the diff --git a/docs/00-index.md b/docs/00-index.md new file mode 100644 index 0000000..34c54d9 --- /dev/null +++ b/docs/00-index.md @@ -0,0 +1,89 @@ +# zu architecture correction and v1 technical specification + +Status: proposed replacement architecture +Research cut: 2026-08-08 +Repository baseline: `tamnd/zu` commit `1f2c7834a3069fe458ee056c0478efc206f87454` +Audit scope: tracked source, tests, benchmarks, CI, Git history, and `docs/00` through `docs/13` + +## Purpose + +This set turns zu's promising prototypes into one coherent database architecture. It preserves the parts that are already strong—defensive decoders, a compact single-file skeleton, vector/factorized query experiments, deterministic tests, and object-store CAS experiments—while replacing the boundary that currently prevents them from becoming one product. + +The decisive correction is: + +> zu has one semantic transaction and query model, one canonical immutable segment model, and backend-specific persistence protocols. The query engine consumes typed vector streams and adjacency batches from a snapshot; it does not consume engine-specific files, raw object-store calls, or a per-node virtual API. + +The current `GraphStore` cannot be incrementally “filled in.” It is unused by every engine, its payload types are empty, and it cannot express batched asynchronous reads, pushdown, resource ownership, transaction validation, or backend capabilities. Meanwhile the working query engine uses a second `Graph` trait and a direct `zu1` adapter. The new design replaces both with a snapshot-oriented storage service interface and makes `zu1`, SQLite, and object storage conform through adapters. + +## Normative language and evidence labels + +`MUST`, `MUST NOT`, `SHOULD`, and `MAY` are normative. Each important statement belongs to one of these categories: + +- **Observed**: verified in baseline source or a command run on that baseline. +- **Qualification target**: a measurable release gate, not a current performance claim. +- **Proposal**: a design requirement to implement and validate. +- **Research inference**: a conclusion drawn from cited primary literature or official system documentation; it is not represented as a fact about zu. + +## Documents + +1. [Current-state audit](./01-current-state-audit.md) — what exists, what is tested, and where documentation and code diverge. +2. [Architecture flaw register](./02-architecture-flaws.md) — severity-ranked flaws, failure modes, and required decisions. +3. [Product contract and invariants](./03-product-contract.md) — supported profiles, consistency, durability, failure model, and non-goals. +4. [Target architecture and crates](./04-target-architecture.md) — control/data planes, ownership, dependency direction, and component responsibilities. +5. [Storage/query service interface](./05-storage-query-contract.md) — the replacement SPI, capabilities, batching, pushdown, streams, and cancellation. +6. [Identity, schema, and graph semantics](./06-identity-and-data-model.md) — stable node/edge identity, multi-edges, labels, constraints, and path semantics. +7. [Query compiler and execution](./07-query-engine.md) — language conformance, IRs, factorization, joins, recursion, scheduling, and spilling. +8. [Transactions, MVCC, WAL, and recovery](./08-transactions-and-recovery.md) — one semantic layer with backend-specific durability adapters. +9. [`zu1` format, buffer manager, and integrity](./09-zu1-format-and-io.md) — byte ownership, chunk integrity, bounded open, CoW publication, and compatibility. +10. [SQLite engine](./10-sqlite-backend.md) — oracle scope, read/write pools, native plans, semantic parity, and interop limits. +11. [Object-storage engine](./11-object-storage.md) — fencing, ambiguity, WAL publication, cache-aware planning, partitions, GC, and cost admission. +12. [Memory, I/O, scheduling, and observability](./12-runtime-and-resources.md) — budget hierarchy, backpressure, I/O futures, cache admission, and metrics. +13. [Performance, cost, security, and operations](./13-qualification-and-operations.md) — honest SLO classes, equations, overload policy, and threat model. +14. [Migration and verification roadmap](./14-roadmap-and-verification.md) — dependency-ordered delivery, compatibility, deterministic simulation, and release gates. +15. [2026 research and system evidence](./15-research-sources.md) — primary sources and the exact constraints they impose. +16. [2026 graph-engine research corpus](./research/000-index.md) — one 500+ line audit per engine, cross-engine scorecard, S3/PB target architecture, and a defensible tenfold benchmark protocol. + +## Product profiles + +| Profile | Purpose | Authority | Concurrency | Durability acknowledgement | +|---|---|---|---|---| +| `zu1-local` | embedded analytics and traversal | one `.zu1` plus sidecar WAL | one process writer broker, snapshot readers | WAL commit record plus qualified sync chain | +| `sqlite-local` | interop, small OLTP, differential oracle | SQLite database/WAL | SQLite single writer, read connection pool | selected SQLite synchronous mode, reported exactly | +| `object-single` | large read-mostly namespace | immutable packs + fenced root/WAL protocol | one externally arbitrated writer, many readers | committed WAL object and published log/root metadata | +| `object-partitioned` | independent graph partitions | root directory + partition roots | one writer per partition; cross-partition semantics restricted | per-partition only; no atomic cross-partition claim | + +`object-partitioned` is not a distributed ACID graph. Cross-partition mutations MUST be rejected in strict mode or exposed as an explicitly asynchronous workflow. A future distributed-transaction profile requires a transactional control plane and is outside v1. + +## Irreducible invariants + +1. Every query reads one immutable `SnapshotToken` that binds data root, catalog root, stats generation, and transaction epoch. +2. Every returned node or relationship has a stable logical element ID. Physical row, group, CSR slot, and object range are locators, never identity. +3. Parallel edges remain distinct through storage, traversal, equality, `DIFFERENT EDGES`, properties, checkpoint, reorder, and export. +4. An acknowledged commit has a single documented recovery point. `Memory`, `Local`, `RemoteLog`, and `Published` are distinct acknowledgement levels even when a backend maps two levels to the same physical transition. +5. A stale writer cannot produce an acknowledged commit after fencing. CAS of one manifest key alone is not sufficient proof of this property. +6. A snapshot pins every byte and schema object it can reach until its final consumer releases it; eviction and GC cannot invalidate borrowed data. +7. Query operators request batches/splits. No executor loop is allowed to issue one object-store request per node, edge, or row. +8. All variable-size allocations are charged before allocation to a query, transaction, cache, or maintenance budget. +9. Point reads verify the exact bytes they consume. A checksum that only full scans validate is not end-to-end integrity. +10. Recovery after a clean shutdown is independent of database size. Crash recovery has explicit WAL byte/object/count bounds. +11. Cost control is enforced by admission and request/byte budgets. Cache hit rate is an observation, not a bound. +12. Backend differences are surfaced as capabilities and plan choices; they never silently alter graph semantics. + +## Decision ledger + +| Question | Decision | +|---|---| +| Keep the current `GraphStore` and fill placeholders? | No; replace before more engines integrate. | +| Let the executor use raw encoded segments? | Only behind stable typed `Batch`/`AdjacencyBatch` views whose owners pin bytes and expose encoding capabilities. | +| Share one physical layout across all engines? | No. Share canonical segment envelopes and semantic objects; SQLite remains relational internally. | +| Put MVCC “above all engines”? | Share transaction semantics and validation; persistence/visibility adapters remain backend-specific. | +| Store relationship identity as CSR slot or `(type,src,dst)`? | No; use stable `EdgeId`, with CSR slot as a versioned locator. | +| Promise multi-label nodes via a fixed 256-bit column? | No fixed global cap in semantics; use label membership tables/bitmaps selected per table and versioned in schema. | +| Call S3 request cost flat because writes batch? | No; enforce per-namespace budgets and report compute, cache, storage, request, retrieval, and egress separately. | +| Allow automatic writer takeover with no lease/arbitration? | No; explicit fencing authority or manual force token is required. | +| Claim PB scale through independent manifests? | Only as partitioned, non-atomic datasets until a control plane exists. | +| Freeze `zu1` version 1 now? | No; current bytes are experimental. Introduce a pre-freeze format epoch and golden-reader gate first. | + +## Definition of v1-ready + +v1 is ready only when one public `Database`/`Connection` API can execute the conformance corpus against `zu1` and SQLite, all updates are visible through snapshot reads before checkpoint, edge identity and multi-edge semantics survive every storage transformation, recovery passes deterministic fault injection, memory and request budgets apply under overload, and the supported format/API compatibility matrix is frozen. Passing unit tests for isolated crates is necessary but not sufficient. diff --git a/docs/01-current-state-audit.md b/docs/01-current-state-audit.md new file mode 100644 index 0000000..0709564 --- /dev/null +++ b/docs/01-current-state-audit.md @@ -0,0 +1,169 @@ +# Current-state audit + +## Baseline and method + +The audit used commit `1f2c7834a3069fe458ee056c0478efc206f87454` from 2026-08-07. The worktree was clean. `cargo test --workspace --all-features` passed: 321 tests across the workspace, including 108 `zu1`, 106 query, 68 encoding, 18 S3-manifest, 12 SQLite, and 9 facade/common tests. This is strong evidence for the implemented slices, not evidence that the documented end-state exists. + +Tracked production source is roughly 22 K lines. The largest modules are `zu-query/src/exec.rs` (~4.3 K), `zu-query` as a crate (~9.8 K), and `zu-zu1` (~7.7 K). `zu-storage`, nominally the architectural center, is 62 lines and has no tests. + +## Baseline evidence map + +Line anchors below refer to the audited commit and are intended to make each major finding independently checkable. + +| Finding | Baseline source evidence | +|---|---| +| storage SPI is declarations/placeholders | `crates/zu-storage/src/lib.rs:29–60` (`Catalog`, `CommitBatch`, `SealedNodeGroup`, `SegmentRef`, `CsrRef`, `Snapshot`, `GraphStore`) | +| executor has a second storage trait | `crates/zu-query/src/exec.rs:72–137` (`Value`, `Graph`) | +| relationship value lacks edge identity | `crates/zu-query/src/exec.rs:79`; trail equality at `:1670`; pair expansion at `:2115–2132` | +| zu1 is wired directly into the query facade | `crates/zu/src/query.rs:132–280`; worker fork reopens at `:260` | +| packed IDs validate only in debug | `crates/zu-common/src/id.rs:40–50`; unused physical `RelId` begins at `:92` | +| MVCC/WAL/fold are zu1-local | `crates/zu-zu1/src/txn.rs:61–190`, `wal.rs`, and `fold.rs:105–180` | +| fold retains a 32-bit relationship row ceiling | `crates/zu-zu1/src/fold.rs:315–336` | +| open eagerly materializes the free list | `crates/zu-zu1/src/file.rs:219–263`; it is decoded again in `lib.rs:183–186` | +| point/range path skips the whole payload CRC | `crates/zu-zu1/src/segment.rs:29–30`, full validation at `:211–235`, partial paths at `:284` and `:358` | +| object layer is a manifest-only CAS prototype | `crates/zu-s3/src/manifest.rs:4–30`, `store.rs:1–18`, takeover at `store.rs:107–129` | +| facade engines are unconditional dependencies | `crates/zu/Cargo.toml:15–19`; only `arrow` is feature-gated at `:28–29` | +| DML clauses are deliberately rejected | `crates/zu-query/src/parser.rs:25–28`, test at `:914` | + +The principal design claims being compared are in `README.md`, `docs/00-overview.md`, `docs/02-architecture.md`, `docs/04-storage-zu1-format.md`, `docs/06-storage-s3.md`, `docs/08-transactions-mvcc.md`, and `docs/10-api-and-tooling.md`. + +## What is genuinely strong + +### Encoding and defensive parsing + +- Stable numeric encoding IDs exist for Plain, Constant, RLE, Dict, FOR, Delta, ALP, ALP-RD, FSST, Bool, Frequency, Zstd, and DeltaPatch. +- Integer MiniBlock chunks select one encoding from sampled candidates and fall back to Plain if the full encoding expands. +- Decoders take caller ceilings, reject hostile counts, and have extensive unit/fuzz coverage. +- FullZip, float, FSST, Zstd, validity, point-range, fence, and zone-map slices are separately implemented and tested. +- Miri covers the encoding roundtrip sweep; CI fuzzes a useful subset of decoders and file verification. + +The implementation is more honest than the prose in one respect: `bench/budgets.toml` records that LiveJournal adjacency is currently about 21–22 bits/edge, not the 4–8 bits/edge headline. + +### `zu1` file mechanics + +- A 4 KiB file header and two alternating 4 KiB database headers are implemented. +- Data is placed in 256 KiB blocks; metadata chains, a delayed free list, catalog, table index, props, CSR directions, key index, and whole-file verifier exist. +- Publication writes data, syncs, flips the alternate database header, and syncs again. +- Open validates the two headers and chooses the highest valid epoch. +- Segment point reads access only required chunk spans, while full reads validate CRC, fences, counts, and zones. +- WAL frames are length/CRC protected; replay recognizes committed prefixes and ignores torn tails. +- The latest slices implement in-memory epoch-stamped overlays and checkpoint folding into new roots. + +### Query prototype + +- Lexer, recursive-descent parser, binder, logical plan, join ordering, optimizer, factorized pull executor, profiling, and a work-stealing morsel path exist. +- Supported query slices include `MATCH`, `OPTIONAL MATCH`, `WHERE`, `WITH`, `UNWIND`, `RETURN`, expressions, ordering, pagination, fixed expansions, variable-length trail enumeration, aggregations, and an ASP-style edge-set closure. +- Flat execution is used as a differential oracle for factorized execution in tests. +- Queries run end-to-end against actual `zu1` catalogs and properties. + +### SQLite and object-storage prototypes + +- SQLite opens/claims a database, sets WAL/NORMAL, creates safe identifiers and adjacency indexes, inserts rows, and serves neighbor/count reads. +- The S3 crate serializes a CRC-protected manifest and exercises conditional create/update against the in-memory `object_store` backend. +- Tests correctly record that `object_store::local::LocalFileSystem` does not implement conditional update; the current S3 test is therefore not a real-provider conformance test. + +## The architecture described in docs does not exist + +### Two incompatible storage interfaces + +`zu-storage` declares: + +```rust +pub trait Snapshot { + fn scan_column(...) -> Result; + fn csr(...) -> Result; + fn lookup_pk(...) -> Result>; +} +``` + +Every payload (`Catalog`, `CommitBatch`, `SealedNodeGroup`, `SegmentRef`, `CsrRef`) is empty. No engine implements `GraphStore` or `Snapshot`; repository search finds only declarations, re-exports, and comments promising future implementation. + +The working executor instead declares a second trait: + +```rust +pub trait Graph { + fn neighbors(&mut self, rel, node, reversed, out) -> Result<()>; + fn has_edge(&mut self, rel, src, dst) -> Result; + fn degree_sum(...); + fn lookup_key(...); + fn property(...); + fn fork(&self) -> Option>; +} +``` + +`zu/src/query.rs` implements that trait directly for `Zu1File`, imports the `zu1` catalog/props/CSR types, and loads a fresh catalog on every preparation. SQLite and S3 cannot execute a query. Therefore the central README claim—three storage engines sharing one query processor—is not currently true. + +### Dependency direction contradicts the design + +The docs say `zu-storage` owns node groups, segments, buffer management, WAL abstraction, and depends on `zu-encoding`; `zu-zu1` should depend on it. In code, `zu-zu1` depends only on common/encoding, owns its own segment, catalog, graph, WAL, and MVCC types, and does not reference `zu-storage`. The facade unconditionally depends on `zu1`, SQLite, S3, query, storage, Parquet-related optional paths, and bundled SQLite; advertised engine feature isolation does not exist. + +### Public API does not exist + +The documented `Database`, `Config`, `Connection`, prepared statement, transaction, Arrow iterator, timeout, and engine selection APIs do not exist. `zu/src/lib.rs` is a re-export plus `query`; the actual API requires callers to own a mutable `Zu1File`. The CLI has useful copy/stat/query commands but is not proof of the documented embedded contract. + +## Semantic gaps + +### Relationship identity is lost + +The data model permits multi-edges and says an internal relationship offset distinguishes them. The executor represents a relationship as only `{ table, src, dst }`. Trail detection calls `path.contains(rel_value)`, so two parallel edges are the same logical edge. `ExpandInto` returns at most one relationship for a pair. Edge properties cannot select a specific parallel edge. A physical `RelId` type exists but is unused by storage/query and its CSR slot would move during rebuild. + +This is a correctness blocker for GQL `DIFFERENT EDGES`, relationship equality, relationship properties, deletes, exports, and checkpoint/reorder. + +### Current capacity and identity differ from docs + +- `NodeId` has the documented 14/22/17/11-bit layout, but `NodeId::new` uses `debug_assert!`; invalid public inputs silently truncate in release. +- The implemented graph loader and edges use `u32` rows. Checkpoint fold explicitly rejects a relationship table beyond the `u32` row domain. The 2^39 rows/table design limit is therefore not implemented. +- Query `Value::Node` uses `(table: u32, offset: u64)` rather than the packed `NodeId`. +- Primary keys are `u64` only in the working adapter, despite docs specifying general typed primary keys. +- Secondary labels, nulls in property storage, edge properties, multiple endpoint pairs, and declared cardinalities are not implemented. + +### MVCC is isolated from queries and API + +`Mvcc`, `WriteTxn`, recovery, and checkpoint fold are used only inside `zu-zu1` modules/tests. `zu::query::run` reads the sealed file through `GraphReader`; it has no overlay reference or snapshot epoch. Consequently a committed overlay is not query-visible through the public query facade until a fold. There is no connection-owned snapshot, epoch pin registry, or old-segment retention tied to active readers. + +The docs say MVCC is shared above the engine trait. The code puts it in `zu-zu1` and SQLite delegates to independent SQLite transactions. Sharing semantic rules is desirable; pretending their physical MVCC is common is not. + +### DML and constraints are absent + +The parser explicitly rejects `CREATE`, `SET`, `DELETE`, `DETACH`, `MERGE`, `CALL`, `FILTER`, `LET`, and `NEXT`. Transaction operations accept numeric table/column/row values directly and do not perform catalog type checks, primary-key uniqueness, endpoint existence, detach rules, or write-write validation. WAL replay rejects DDL and ingest reference records as unsupported. + +## Storage and integrity gaps + +### Open is not strictly O(1) + +`Zu1File::open` reads the 12 KiB headers, then eagerly reads and decodes the complete free-list metadata chain and walks it again for block IDs. Open cost is O(free blocks / metadata capacity), not O(1). The 10 GB benchmark can still pass because it does not imply a highly fragmented free list. + +### Point reads can return silent corruption + +Full segment reads verify the segment CRC. Point/range/probe paths intentionally skip it to avoid reading the whole payload. They validate bounds and structure but cannot detect a bit flip that remains structurally valid. A corrupt neighbor or property can therefore be returned without error. Per-chunk checksums or authenticated content IDs are required for the claimed integrity posture. + +### I/O and buffer manager are not implemented + +`Zu1File` uses `seek` plus `read_exact`/`write_all`, allocates a 256 KiB `Vec` for every full block read, and has no `IoBackend`, buffer manager, page state machine, budget accounting, prefetch, direct I/O, async interface, or cache. Query workers reopen the file read-write and maintain private decoded-group caches. This is functional prototyping, not the documented vmcache-style design. + +### Format description and bytes have drifted + +Docs describe a recursive `EncodingNode` cascade depth ≤3, while integer chunk payloads store one encoding ID; “cascade” is currently a name, not an encoding tree. Docs describe group-local CSR slack, continuation chains, tombstone validity, relationship columns, and 16-byte generic zones; current CSR is dense offsets/neighbors, fold rebuilds an entire relationship table, and segment zones are `u64` only. + +The current format version is already `1`, but these incompatible fundamentals remain open. It MUST be treated as experimental, not frozen v1. + +## S3 and cost gaps + +- The implemented manifest contains only epoch, writer ID, and segment key strings. There are no packs, byte ranges, catalog, WAL interval, checksums/content IDs, checkpoints, GC boundary, partition root, or cost metadata. +- `CURRENT` stores the full manifest, unlike the documented small pointer object. +- `take_over()` lets any caller that can write immediately replace the current writer. No lease, external election, manual force token, or grace/failure detector exists. +- A CAS on `CURRENT` fences root publication but does not by itself prevent an old writer from uploading WAL/segments or acknowledging a WAL-only commit. SlateDB's own fencing design is more involved and fences WAL positions, not merely a manifest field. +- The cost table assumes a 95% hit rate; it does not bound misses. A 10× scan over new data raises GETs and bytes. The claim “flat ±10%” requires admission control or request shedding. +- “Total bill” excludes compute, NVMe, cache replication, retrieval, egress, observability, and operations. It is only a modeled object-storage subtotal. +- Independent partition manifests make the two adjacency directions of a cross-partition edge non-atomic. Readers can see different graphs depending on traversal direction. + +## Build and release gaps + +- `Cargo.lock` is ignored even though the workspace builds an application binary and database format; identical commits can resolve different transitive versions. +- Advertised default feature isolation is absent; all engines are unconditional facade dependencies. +- CI does not run deterministic crash injection, Loom, real object-store CAS conformance, differential zu1/SQLite queries, format golden files, backward compatibility, sanitizer jobs, or benchmark gates on normal pull requests. +- README says “nothing is usable” and “specification complete,” while substantial slices are implemented and the spec has material contradictions. Status needs generated feature/conformance tables. + +## Conclusion + +The repository is not an empty prototype. It contains valuable, well-tested algorithms. Its main risk is that continued vertical slices will harden the wrong seams: engine-specific query access, physical identity leaking into semantics, and separate transaction paths. The next milestone should be an architecture correction, not another feature. diff --git a/docs/02-architecture-flaws.md b/docs/02-architecture-flaws.md new file mode 100644 index 0000000..6dd6641 --- /dev/null +++ b/docs/02-architecture-flaws.md @@ -0,0 +1,122 @@ +# Architecture flaw register + +## Severity model + +- **P0**: makes documented semantics impossible or risks acknowledged-data loss/corruption. +- **P1**: forces a rewrite, invalidates a headline property, or prevents one product/API. +- **P2**: important production gap with a contained migration path. +- **P3**: documentation, ergonomics, or later optimization. + +## P0: relationship identity is not represented end to end + +**Evidence:** query values use `(table, src, dst)`; trail visited checks compare that tuple; storage neighbor arrays contain only destinations; `has_edge` is boolean; checkpoint rebuild sorts edges; physical `RelId` is unused. + +**Failure:** parallel relationships collapse for equality and path restrictions. Relationship property lookup and delete cannot name the intended edge. Reordering or rebuilding can change a slot-based ID. + +**Decision:** introduce logical `EdgeId(u128)` (serializable as two `u64` words where an ABI requires it), allocated at insert/bulk load. Every adjacency entry carries `(neighbor, edge_id)` in parallel compressed streams. Edge properties are keyed/densely located by `edge_id` through a versioned locator index. All query `Rel` values contain `edge_id`; `(src,dst)` is metadata. + +**Gate:** generated multigraph corpus with parallel self-loops must match a reference evaluator for equality, trail, simple path, delete-one, update-property, checkpoint, reorder, export/import, and both directions. + +## P0: commits and queries use disconnected state + +**Evidence:** `Mvcc` exists in `zu-zu1`; the only query facade receives `&mut Zu1File`; it never receives `Mvcc` or an epoch. + +**Failure:** a successful commit may not be visible to a new query until checkpoint. There is no API-level read-your-writes, repeatable read, or pinned historical snapshot. + +**Decision:** `DatabaseInner` owns engine, transaction manager, catalog registry, epoch pins, and maintenance. `Connection` begins a `ReadTxn` with a `SnapshotToken`; `WriteTxn` exposes an overlay view and commits through one coordinator. Storage adapters merge base and overlay into snapshot batches or provide native snapshot reads. + +**Gate:** API-level tests, not module tests, prove read-your-writes, old-reader stability across commit/checkpoint, rollback, recovery, and concurrent readers. + +## P0: S3 fencing is insufficient for acknowledgement semantics + +**Evidence:** `take_over()` unconditionally advances writer ID via manifest CAS. Current code has no WAL, but docs plan to acknowledge after WAL PUT. CAS-fencing only `CURRENT` does not stop a stale writer from successfully PUTting a WAL object or reporting success. + +**Failure:** two writers can each acknowledge transactions, while only one lineage becomes reachable; automatic takeover can oscillate under a partition; ambiguous timeouts can duplicate or lose logical commits. + +**Decision:** separate writer arbitration, log-position fencing, and root publication. A writer obtains a monotonically increasing `WriterEpoch` from a fencing authority; each WAL position is create-only and names that epoch; a commit is acknowledged only after the WAL batch is durably recorded and an authoritative log-tail CAS includes its digest. Takeover requires lease expiry/external election or an explicit operator force token. Every uncertain response is reconciled by `(txn_id, epoch, log_seq, digest)`. + +**Gate:** deterministic state-machine tests and real-provider tests cover delayed/duplicated requests, timeouts after success, zombie writers, takeover, stale credentials, and GC. + +## P0: partitioning breaks graph consistency + +**Evidence:** docs allow an edge spanning independently committed partitions and call it eventually visible. Forward CSR belongs naturally to source partition; backward CSR belongs to destination partition. + +**Failure:** an edge may exist forward but not backward. The answer changes with query direction, violating one property graph snapshot. Node deletion/constraints cannot be atomic. + +**Decision for v1:** strict ownership. A partition owns nodes and canonical edge records by source. Reverse adjacency for remote destinations is an asynchronous derived index and MUST NOT be used for strict snapshot queries. Strict queries either route through canonical source ownership or reject plans requiring stale reverse indexes. Cross-partition writes are rejected in ACID transactions. A future global snapshot/control plane is a separate profile. + +## P1: the architectural SPI is dead code and has the wrong shape + +**Failure:** implementing SQLite/S3 against it would force decompression/copies, serialize remote reads, and omit pushdown/cancellation. Keeping the executor's `Graph` trait would create object-store pointer chasing. + +**Decision:** replace both traits with `CatalogService`, `SnapshotReader`, `MutationSink`, and `MaintenanceService`. Read requests are vector/batch-oriented and return owned/pinned views or streams. Capabilities are explicit. See [05](./05-storage-query-contract.md). + +## P1: physical location is confused with logical identity + +**Evidence:** dense row offsets double as default user ID; packed NodeId encodes group/row; reorder relies on a partial key index; `RelId` encodes CSR slot. + +**Failure:** vacuum/reorder/schema migration conflict with stable identity; keyed tables without a relationship can return any requested key as if it existed; invalid packed values can truncate in release. + +**Decision:** `NodeId` and `EdgeId` are immutable logical IDs. A snapshot-specific locator maps them to table/row/group/slot. User primary key is a separately typed unique key. Packed physical locators never cross the public API or WAL semantic layer. + +## P1: the persistence model cannot be shared exactly as documented + +**Failure:** SQLite native MVCC/locking and object-store immutable roots do not use zu1's in-memory version chains. Forcing one physical MVCC either defeats SQLite or leaks engine behavior. + +**Decision:** share isolation contract, logical mutations, validation rules, transaction IDs, and conformance tests. Each backend implements `begin_snapshot`, durable commit, and recovery using its native mechanism. The coordinator owns public transaction lifecycle and single-writer policy. + +## P1: format version 1 is premature + +**Failure:** adding edge IDs, chunk checksums, typed zones, group-local directories, labels, nullability, and a real encoding tree changes bytes and metadata. Pretending compatibility now creates permanent baggage. + +**Decision:** mark existing files `experimental_epoch=0`; the next writer emits format epoch 1 but still declares `stability=experimental`. Freeze only after independent reader, golden corpus, mutation/recovery, and compatibility gates. Public v1 software version is independent from on-disk format number. + +## P1: synchronous point API conflicts with remote and parallel I/O + +**Failure:** `neighbors(node)` encourages one call/read per node; `block_on` creates hidden runtime nesting; private reader caches duplicate memory; no cancellation or deadlines reach I/O. + +**Decision:** requests describe many adjacency lists, projections, row selections, and an I/O budget. They return futures/streams of splits. Local adapters may complete immediately. The pipeline uses bounded async-source operators feeding CPU workers with backpressure; no Tokio requirement leaks into public core. + +## P1: performance goals are inconsistent with evidence + +**Evidence:** G5 says ≤8 bits/edge, current budget permits 22; G1 says p99 <100 µs but gates mostly p50; SQLite and S3 targets are mixed with zu1; cold and warm definitions vary. + +**Decision:** publish profile-specific SLOs with dataset, cache state, concurrency, durability mode, hardware, percentile, and correctness checksum. Current numbers remain engineering observations. Aspirational goals remain qualification targets until a reproducible artifact passes. + +## P2: checksum granularity is wrong for point access + +**Decision:** every independently fetched/decoded chunk has CRC32C; immutable object/pack descriptors also carry BLAKE3-256 content digests. Metadata binds chunk range, logical type, count, encoding, and digest. Point reads validate chunk checksum before decode; full verification additionally validates object digest and graph invariants. + +## P2: open and recovery bounds are unspecified in actual structures + +**Decision:** headers point to a bounded root page containing allocator summary and root directory. Free space is a persistent bitmap/radix tree loaded lazily; startup reads a fixed maximum (target ≤64 KiB local). WAL recovery is capped by bytes and transactions; exceeding the cap switches to explicit recovery progress, not an “open <10 ms” claim. + +## P2: fixed group size is overloaded + +The same 131,072-row group is called compression, zone-map, MVCC, rewrite, cache, and S3 packing unit. These concerns have different optimal sizes. High-degree adjacency and wide strings make group bytes unbounded. + +**Decision:** separate logical row group (ID/visibility), column page/chunk (encoding and checksum), adjacency tile (source range and edge budget), and pack object (remote request economics). Directories map between them. Targets are byte-bounded, not only row-bounded. + +## P2: catalog and plan lifetime are under-specified + +**Decision:** catalog is immutable and versioned; every snapshot token names a catalog digest. Plans bind stable object IDs and carry a compatibility predicate. DDL invalidates only plans whose dependency set changed. Catalog fetch, stats, and data root are atomic from the reader's perspective. + +## P2: memory accounting and cancellation are absent + +**Decision:** hierarchical reservations cover decoded batches, factorized lists, hash tables, PMRs, overlays, cache entries, inflight I/O, and maintenance. Operators acquire before allocating and spill/yield/error deterministically. Cancellation propagates to queued morsels, object reads, SQLite statements, and maintenance waiters. + +## P2: cost model is an estimate without enforcement + +**Decision:** the optimizer produces an estimated remote request/byte envelope; runtime charges actual operations. Namespace token buckets bound GET, PUT, bytes, and concurrency. Policies choose wait, reject, degrade-to-stale, or require explicit override. Reports separate object-storage, compute, NVMe, network, and operational cost. + +## P2: reproducibility and compatibility controls are missing + +**Decision:** track `Cargo.lock` for workspace binaries, pin toolchain and external fixtures, record benchmark dataset digests, generate an SBOM, test previous released readers/writers, and require format corpus review for byte changes. + +## P3 corrections + +- Replace “Kùzu is dead and the lane is open” with current competition: Ladybug is actively maintained in July 2026 and offers the same embedded columnar/CSR/factorized baseline. +- Do not call vector/FTS/MCP “table stakes” in architecture requirements; make them product features with measured demand and isolated indexes. +- Do not promise “no fsck”; promise automatic recovery for supported failure classes and a verifier/repair tool for corruption. +- Do not say a general graph query is GQL-conformant until a clause-by-clause conformance declaration and tests exist. +- Generate README status from a capability manifest so implementation milestones cannot drift from prose. diff --git a/docs/03-product-contract.md b/docs/03-product-contract.md new file mode 100644 index 0000000..39a18af --- /dev/null +++ b/docs/03-product-contract.md @@ -0,0 +1,135 @@ +# Product contract and system invariants + +## Product thesis + +zu is an embedded property-graph query engine with portable local storage and an optional object-native read-mostly profile. Its differentiator is not merely “three engines”; it is predictable semantics and query plans across storage with deliberate capability specialization. + +The local `zu1` profile competes on mixed traversal/analytics latency and small deployment footprint. SQLite competes on interop and trusted small-write durability, not analytical parity. Object storage competes on capacity and stateless read scale, not local latency or unrestricted transactions. + +## Supported consistency contract + +### Local profiles + +- One write transaction at a time per `Database` instance. +- Read-only transactions use snapshot isolation and may span statements. +- Write transactions are serialized by begin/commit order and read their own staged writes. +- DDL and DML are atomic within the same write transaction unless an operation is explicitly documented as offline bulk build. +- Connections in the same process share one transaction manager. Opening the same local file through two independent `Database` objects in write mode MUST fail through an OS-level exclusive writer lock. +- Read-only independent processes MAY open a committed root. They do not see in-process uncheckpointed overlay commits unless the WAL-tail reader protocol is explicitly enabled and qualified. + +“Serializable” MUST be used only after tests/model prove the actual isolation contract. A single writer removes write/write anomalies but does not alone make an arbitrary read-then-write API serializable if read snapshots or predicate validation are wrong. + +### Object-single profile + +- One fenced writer per namespace; many readers. +- A strong read names a published log-tail/root generation and includes all commits through it. +- A bounded-stale read names its observed generation and maximum polling interval. +- Read-your-writes is provided by a commit receipt containing `txn_id`, `writer_epoch`, `log_seq`, and digest; a subsequent read waits until its snapshot covers that receipt. +- The system does not promise low-latency strong reads during object-store unavailability. + +### Partitioned profile + +- A query returns a `SnapshotVector` of `(partition_id, generation)`. +- It is not a globally atomic time unless a future coordinator certifies it. +- Strict queries MUST reject cross-partition reverse-index reads that are behind their canonical edge generation. +- Cross-partition write transactions are unsupported in v1. + +## Durability levels + +Every commit API accepts or inherits one level and returns it in the receipt: + +| Level | `zu1` | SQLite | Object storage | +|---|---|---|---| +| `Memory` | overlay only; process loss loses it | transaction not committed | memory batch only | +| `Local` | WAL commit synced to qualified local device | SQLite commit at configured sync | local spill synced; node loss may lose it | +| `RemoteLog` | not applicable | not applicable | WAL object and authoritative tail committed | +| `Published` | same as Local; overlay visible in process | same as SQLite commit | root/manifest generation includes transaction | + +Default is `Local` for local profiles and `RemoteLog` for object-single. `Memory` and object `Local` require an explicit unsafe/relaxed configuration name; they must never be described as durable. + +## Failure model + +Supported failures: + +- process crash or kill at any instrumented syscall boundary; +- torn/short local file or WAL write within the qualified filesystem/device assumptions; +- reordered completion of independent object-store requests; +- object request retry, duplicate, timeout-after-success, 412 conflict, and bounded unavailability; +- stale writer continuing after takeover; +- cache loss at any point; +- corruption detected by checksum/digest; +- cancellation, memory exhaustion, disk-full, and budget exhaustion. + +Not automatically tolerated in v1: + +- malicious storage rewriting both data and digests without encryption/authentication; +- loss of the only local device; +- object store violating documented single-key atomicity/conditional-write semantics; +- atomic mutation spanning object partitions; +- arbitrary filesystem/network filesystems not in the qualification matrix; +- Byzantine writer credentials. + +## Data correctness invariants + +1. `NodeId` and `EdgeId` are never reused within a database UUID. +2. User primary keys are unique among visible nodes in a table at a snapshot. +3. An edge's source, destination, type, and `EdgeId` are immutable; changing endpoints is delete+insert. +4. A visible edge has visible endpoints unless the query explicitly opens a relaxed/import-repair snapshot. +5. Forward and backward local adjacency indexes contain the same visible `EdgeId` set. +6. Relationship properties resolve by `EdgeId`, never solely by endpoints or CSR slot. +7. Every operator obeys bag semantics unless the language requests set semantics. Storage must not deduplicate parallel edges. +8. Null, absent property, and type error are distinct according to the language rules. +9. A snapshot's catalog and values are from the same commit lineage. +10. Export/import preserves logical IDs when requested, or emits an explicit old→new ID mapping. + +## Operational invariants + +- Maintenance is cancellable and budgeted. +- Checkpoint/compaction never blocks readers on data I/O; publication may briefly serialize with commit. +- Disk/object GC is reachability-based with snapshot/checkpoint pins and a grace period. Time alone is never proof of safety. +- A health endpoint distinguishes ready, read-only degraded, recovery required, fenced, budget-throttled, and corrupt. +- Metrics are bounded-cardinality. Query text/keys/properties are not logged by default. +- Secrets never enter manifests, WAL payload diagnostics, tracing fields, or error strings. + +## Non-goals for v1 + +- multi-writer distributed transactions or Raft; +- a globally consistent PB graph; +- arbitrary schema-less values; +- online stable-ID-preserving physical repartition across object partitions; +- graph-shaped vector indexes traversed directly from cold object storage; +- every optional GQL feature; +- automatic repair of undetected corruption; +- general server product, authentication system, or tenant control plane. + +## Capacity policy + +Format bit widths are not supported capacities. Each profile has qualification ceilings: + +| Dimension | v1 default policy | +|---|---:| +| tables/database | 16,384 format maximum; 4,096 qualified | +| labels/database | semantic `u32`; 65,536 qualified | +| nodes/table local | 2^39 format target; qualify at tested dataset sizes | +| edges/table local | `u64`; no `usize`-dependent on-disk count | +| value/chunk | 16 MiB default maximum; continuation required above | +| transaction | 256 MiB logical default and 1 M mutations, whichever first | +| query path enumeration | explicit result/visited/PMR budgets | +| object pack | 8–64 MiB target, ≤128 MiB hard v1 limit | + +Every conversion from on-disk `u64` to `usize` MUST check platform and budget before allocation. + +## API-level contract + +The primary API is synchronous at the call boundary for embedded users, but internally supports asynchronous I/O sources. Blocking methods accept a deadline/cancellation token through options; convenience methods use configured defaults. + +```rust +let db = Database::open(uri, OpenOptions::default())?; +let conn = db.connect()?; +let read = conn.begin_read(ReadOptions::latest())?; +let stmt = read.prepare("MATCH ...")?; +let mut rows = stmt.query(params, QueryOptions::default())?; +while let Some(batch) = rows.next_batch()? { /* borrowed until next call */ } +``` + +`Database` is `Send + Sync`; `Connection` is `Send` but not concurrently used; `ReadTxn` and `WriteTxn` are neither implicitly cloned nor detached. Result buffers have explicit ownership lifetimes and may be copied into Arrow. diff --git a/docs/04-target-architecture.md b/docs/04-target-architecture.md new file mode 100644 index 0000000..0322e40 --- /dev/null +++ b/docs/04-target-architecture.md @@ -0,0 +1,179 @@ +# Target architecture and crate boundaries + +## Architecture overview + +```text +Public API / CLI / bindings + | +Session + transaction coordinator + |--- CatalogService (immutable catalog per snapshot) + |--- Compiler (parse -> semantic IR -> logical IR -> physical IR) + |--- Runtime (pipelines, tasks, budgets, spill, cancellation) + | +SnapshotReader + MutationSink + MaintenanceService + | + +----+-------------------+--------------------+ + | | | +zu1 adapter SQLite adapter object adapter + | | | +page/chunk I/O SQL/read pool range I/O/cache +local WAL/CoW root SQLite WAL fenced WAL/roots +``` + +The query engine never imports `zu_zu1`, `rusqlite`, or `object_store`. Engine crates never import parser/optimizer/executor. `zu-core` is the composition root. + +## Control plane versus data plane + +### In-process control plane + +`DatabaseInner` owns: + +- engine instance and immutable capability descriptor; +- transaction coordinator and writer queue; +- current catalog/root generation registry; +- snapshot pin registry and safe-reclamation watermark; +- plan cache keyed by semantic dependencies; +- global memory/I/O/request budgets; +- maintenance scheduler; +- metrics and lifecycle state. + +It does not own query-local vectors, hash tables, path state, or a global async runtime. + +### Query data plane + +Each query owns: + +- one immutable snapshot token; +- one `QueryBudget` child reservation; +- physical pipelines and bounded channels; +- a cancellation token/deadline; +- per-worker arenas and spill files; +- source cursors created from the snapshot reader; +- profile counters and remote-cost ledger. + +No mutable catalog or engine global is accessed from hot operators. + +## Proposed workspace + +| Crate | Responsibility | Allowed dependencies | +|---|---|---| +| `zu-types` | IDs, types, scalar/vector ABI, errors, limits | std only by default | +| `zu-format` | canonical segment envelopes, encoding trees, checksums, compatibility | `zu-types`, `zu-encoding` | +| `zu-encoding` | pure codecs and compute-on-encoded kernels | `zu-types` | +| `zu-catalog` | immutable schema, names, constraints, stats descriptors | `zu-types` | +| `zu-storage` | SPI request/response types and capability model | types/format/catalog | +| `zu-txn` | public transaction state machine, logical mutations, validation orchestration | types/catalog/storage | +| `zu-query` | syntax, semantic IR, logical/physical planning | types/catalog/storage interfaces | +| `zu-runtime` | vector/factorized execution, scheduling, budgets, spill | query/storage/format | +| `zu-zu1` | local persistence adapter, WAL, allocator, buffer manager | storage/format/txn protocol | +| `zu-sqlite` | relational persistence adapter and native pushdown | storage/catalog/txn protocol/rusqlite | +| `zu-object` | object packs, cache, fenced log/root, provider adapter | storage/format/object_store | +| `zu-core` | `Database`, `Connection`, feature-gated composition | selected engines + compiler/runtime | +| `zu-cli` | CLI only | `zu-core` | + +Names may be consolidated to avoid premature crate explosion, but dependency direction is normative. In particular, `zu-zu1` MUST implement `zu-storage`; `zu-query` MUST NOT depend on `zu-zu1`; and `zu-storage` MUST contain real contract types with conformance tests. + +## Canonical objects, not one physical format + +The shared unit is a `SegmentEnvelope`: + +```text +SegmentEnvelope { + format_epoch, logical_type, encoding_tree, + value_count, null_count, uncompressed_bytes, + stats, chunk_directory, content_digest, + chunk payloads... +} +``` + +`zu1` stores envelopes in local extents. Object storage stores them in immutable packs. SQLite MAY synthesize canonical batches without persisting envelope bytes; forcing SQLite to store opaque compressed blobs would sacrifice interop and native index benefits. Export/conversion materializes envelopes through the read SPI. + +## Ownership and lifetime model + +### Snapshot token + +```rust +pub struct SnapshotToken { + pub database: DatabaseId, + pub data_generation: Generation, + pub catalog_generation: Generation, + pub stats_generation: Generation, + pub visible_epoch: Epoch, + pub durability_floor: CommitPosition, + pin: Arc, +} +``` + +The token is unforgeable outside storage/core. Dropping the last clone advances possible reclamation. A backend validates that all locators used with a token belong to its generation. + +### Pinned bytes + +`PinnedBuffer` owns an `Arc` to a cache/page/object slice and a budget charge. `EncodedArray` references only a `PinnedBuffer` or owned bytes. An eviction removes lookup reachability but cannot free bytes until pins drop. Raw borrowed slices never escape without an owner. + +### Immutable metadata + +Catalogs, group directories, manifests, and stats are immutable content-addressed values. Publication swaps one root. Mutable caches point to immutable values and may be rebuilt. + +## Threading model + +- CPU worker pool: fixed, database-wide by default, work-stealing with per-query fairness. +- I/O driver: a small backend-specific service produces completions; local synchronous reads may run on dedicated blocking I/O threads; object reads use the provider's async API. +- Writer broker: exactly one task serializes local logical commits; it does not perform expensive encoding while holding publication locks. +- Maintenance: low-priority tasks with explicit CPU/I/O/memory quotas. +- Result consumer: backpressure stops upstream pipelines when result buffers reach the configured bound. + +The existing “fork a graph by reopening the file” mechanism is transitional. Target workers share snapshot directories and buffer cache; they do not independently duplicate catalog and decoded-group state. + +## Compilation boundaries + +1. Parser produces lossless syntax AST and diagnostics. +2. Semantic binder resolves names/labels/types against `CatalogSnapshot` and produces stable IDs. +3. Graph-normalization IR makes edge identity, path mode, match mode, null extension, and bag semantics explicit. +4. Logical optimizer performs equivalence-preserving rewrites. +5. Physical optimizer consults `StorageCapabilities`, stats, budgets, and remote-cost model. +6. Runtime executes `PhysicalPlan` with a fixed snapshot token. + +Physical plans may contain backend leaf operators (`SqliteIndexRange`, `EncodedGroupScan`, `RemoteAdjacencyGather`) selected from declared capabilities. Backend-specific leaves terminate at typed batch outputs; engine details do not leak upward. + +## Capability negotiation + +Capabilities are immutable for an open engine except transient health/cost availability: + +```rust +pub struct StorageCapabilities { + pub snapshot: SnapshotCapabilities, + pub scan: ScanCapabilities, + pub adjacency: AdjacencyCapabilities, + pub mutation: MutationCapabilities, + pub io: IoCapabilities, + pub limits: StorageLimits, +} +``` + +Examples: exact filter pushdown, ordered adjacency, edge-ID projection, typed PK lookup, batch ranges, SQL aggregation pushdown, remote request estimates, historical snapshots, DDL, and bulk atomicity. Unsupported operations are rejected during planning or lowered to a correct generic path. There is no optimistic call-and-fallback after partial query execution. + +## State machines + +Database lifecycle: + +```text +Opening -> Recovering -> Ready + -> ReadOnlyDegraded + -> RecoveryRequired +Ready -> Fenced | BudgetThrottled | Closing -> Closed +Ready -> Corrupt (sticky; writes disabled) +``` + +Write transaction: + +```text +Active -> Validating -> Prepared -> Durable -> Published -> Committed + | | | | | + +----------+------------+----------+-----------+-> Aborted/Unknown +``` + +`Unknown` is required for ambiguous remote outcomes. The client reconciles by transaction ID; it never blindly reapplies mutations. + +## Extension points + +Extensions register functions, logical rewrite rules, table/index providers, or file readers through versioned interfaces. They cannot allocate outside budgets, bypass snapshot tokens, introduce unversioned on-disk bytes, or call engine internals. Native extensions are disabled by default for untrusted databases; WASM or process isolation is future work. diff --git a/docs/05-storage-query-contract.md b/docs/05-storage-query-contract.md new file mode 100644 index 0000000..ac4a246 --- /dev/null +++ b/docs/05-storage-query-contract.md @@ -0,0 +1,210 @@ +# Storage/query service interface + +## Why a service interface + +The storage boundary must preserve graph semantics while allowing radically different access costs. A local encoded group can be read in microseconds; SQLite may answer best with a native indexed SQL query; object storage needs batched ranges and async completion. A trait returning one `SegmentRef` or neighbor list cannot express these choices. + +The SPI is split by responsibility so reads, mutations, and maintenance cannot accidentally share locks or acknowledgement semantics. + +## Core interfaces + +```rust +pub trait StorageEngine: Send + Sync + 'static { + fn capabilities(&self) -> &StorageCapabilities; + fn catalog_service(&self) -> &dyn CatalogService; + fn snapshots(&self) -> &dyn SnapshotService; + fn mutations(&self) -> &dyn MutationService; + fn maintenance(&self) -> &dyn MaintenanceService; +} + +pub trait SnapshotService: Send + Sync { + fn latest(&self, opts: SnapshotOptions) -> BoxFuture>; + fn at(&self, selector: SnapshotSelector) -> BoxFuture>; +} + +pub trait SnapshotReader: Send + Sync { + fn token(&self) -> &SnapshotToken; + fn plan_scan(&self, request: ScanRequest) -> Result>; + fn plan_adjacency(&self, request: AdjacencyRequest) + -> Result>; + fn lookup(&self, request: LookupRequest) -> BoxFuture>; +} +``` + +`SnapshotHandle` contains an `Arc`, the exact `CatalogSnapshot`, and backend accounting context. It is acquired once per read transaction/query, not once per operator. + +## Batch source contract + +```rust +pub trait BatchSource: Send { + fn schema(&self) -> &BatchSchema; + fn next(&mut self, cx: &mut SourceContext) + -> Poll>>; + fn cancel(&mut self); +} +``` + +The poll-shaped internal interface avoids selecting a public async runtime. `SourceContext` contains deadline, cancellation, memory reservation, I/O submitter, request/byte budget, and profile sink. A synchronous local source may return `Ready` immediately; a remote source schedules vectored reads and returns `Pending`. + +`DataBatch` is 1–8192 rows (default target 2048) and owns/pins: + +- schema and row selection; +- canonical arrays (`Flat`, `Constant`, `Dictionary`, `FOR`, `List`, etc.); +- optional row/element IDs; +- nullability bitmap; +- ordering and factorization metadata; +- budget reservation released on drop. + +The runtime may compute directly on supported compressed arrays. Canonicalization to flat vectors is explicit and budgeted. + +## Scan request + +```rust +pub struct ScanRequest { + pub table: TableId, + pub snapshot: SnapshotToken, + pub projection: Vec, + pub filter: StorageExpr, + pub order: RequiredOrder, + pub row_id: RowIdProjection, + pub partitioning: SplitPreference, + pub limit_hint: Option, + pub budget: ReadEnvelope, +} +``` + +Rules: + +- `StorageExpr` is a small typed, versioned expression language; it does not embed query-engine AST nodes. +- The engine returns a `PushdownReport` marking each conjunct `Exact`, `PruningOnly`, or `Unsupported`. +- `PruningOnly` never authorizes dropping the runtime filter. +- Projection includes filter-only fields but allows the source to discard them before output. +- Splits are independently executable and carry deterministic IDs for replay/profiling. +- `limit_hint` is not semantically binding unless the engine proves order/filter equivalence. + +This follows the useful N×M separation in Vortex's evolving scan API: a request describes filter/projection, a source returns independent splits, and pruning is distinguished from exact evaluation. + +## Adjacency request + +```rust +pub struct AdjacencyRequest { + pub edge_types: SmallVec<[RelTableId; 4]>, + pub direction: Direction, + pub sources: IdBatch, + pub neighbor_labels: LabelPredicate, + pub edge_filter: StorageExpr, + pub projection: AdjacencyProjection, + pub order: AdjacencyOrder, + pub mode: AdjacencyMode, + pub budget: ReadEnvelope, +} + +pub struct AdjacencyProjection { + pub neighbor_id: bool, + pub edge_id: bool, + pub edge_columns: Vec, + pub neighbor_columns: Vec, +} +``` + +An `AdjacencyBatch` is list-structured: source IDs, offsets, neighbor IDs, edge IDs, and projected property arrays. Sources may be reordered internally only if a source-position map is returned. Empty lists are represented, not dropped. + +Modes: + +- `Enumerate`: exact edges with identity; required for relationship binding and path semantics. +- `DegreeOnly`: exact visible degree after filters; no neighbor values. +- `ExistencePairs`: many `(src,dst)` probes returning count or edge IDs, not only boolean. +- `Intersect`: optional backend WCOJ primitive over ordered lists, with exact identity/multiplicity rules. +- `Prefetch`: materialize/pin predicted tiles without returning rows. + +The minimum useful batch is many source nodes. The physical planner MUST NOT lower a remote expansion to repeated single-source requests. + +## Lookup request + +Lookup supports typed keys and IDs: + +```rust +pub enum LookupKeyBatch { + Primary { table: TableId, values: Array }, + NodeIds(IdBatch), + EdgeIds(IdBatch), +} +``` + +Results preserve input order and include an explicit found bitmap. Dense fallback MUST range-check against visibility; it cannot return `Some(key)` merely because no index exists. + +## Mutation interface + +```rust +pub trait MutationService: Send + Sync { + fn prepare(&self, base: &SnapshotToken, txn: TxnId, + mutations: LogicalMutationBatch, + ctx: &CommitContext) -> BoxFuture>; + fn make_durable(&self, prepared: PreparedCommit, + level: DurabilityLevel, + ctx: &CommitContext) -> BoxFuture>; + fn publish(&self, durable: DurableCommit, + ctx: &CommitContext) -> BoxFuture>; + fn reconcile(&self, key: CommitKey) -> BoxFuture>; +} +``` + +The split phases make remote ambiguity and local publication explicit. Backends may fuse phases but must emit the same state transitions. `PreparedCommit` is single-use and carries base generation, mutation digest, reserved IDs, and validation proof. Retrying uses `TxnId` and digest; changing payload under the same ID is conflict/corruption. + +Logical mutations include typed node/edge insert, property update, label membership change, delete, and DDL. They contain logical IDs and primary keys, never block pointers or CSR slots. + +## Maintenance interface + +Checkpoint, compaction, analyze, verify, vacuum, GC, and export are jobs: + +```rust +pub trait MaintenanceService { + fn submit(&self, job: MaintenanceJob, + budget: MaintenanceBudget) -> Result; +} +``` + +Jobs have progress, cancellation, resumability, generated artifacts, and publication phase. `verify` is read-only. `repair` is a distinct, explicit operation that writes a new root and preserves evidence. + +## Capability examples + +| Capability | zu1 | SQLite | object-single | +|---|---:|---:|---:| +| ordered exact adjacency with edge IDs | required | via indexed SQL | required when canonical tile cached/fetched | +| exact scalar predicate pushdown | selected encoded kernels | broad SQL subset | selected encoded kernels | +| async vectored ranges | local gather | no; statement source | required | +| historical snapshot by generation | pinned local epochs, bounded | optional SQLite snapshot support | immutable roots | +| native aggregate pushdown | limited metadata counts | selected safe SQL | limited metadata counts | +| DDL | yes | yes | single-partition only | +| cross-partition transaction | n/a | n/a | false | + +## Error contract + +Errors are structured and stable: + +- `Corrupt { object, range, expected, actual }` +- `Unsupported { capability, backend, alternative }` +- `Conflict { kind, current_generation }` +- `Fenced { expected_epoch, current_epoch }` +- `AmbiguousCommit { key }` +- `BudgetExceeded { resource, requested, remaining }` +- `Cancelled`, `DeadlineExceeded` +- `SnapshotExpired`, `SnapshotMismatch` +- `ConstraintViolation { constraint, element }` +- `Io { class, retryability, source }` + +No backend error string is the semantic API. Provider/SQLite/OS errors are retained as sources and mapped deterministically. + +## Conformance kit + +Every engine implementation runs the same suite for: + +- empty and multi-table catalogs; +- typed PK hits/misses and duplicates; +- multi-edge/self-loop adjacency both directions; +- filters/nulls/projections and order; +- snapshot stability across commits; +- cancellation and budget exhaustion; +- idempotent commit/reconcile; +- constraint failure atomicity; +- export to canonical batches and reimport parity. diff --git a/docs/06-identity-and-data-model.md b/docs/06-identity-and-data-model.md new file mode 100644 index 0000000..2b0b4bc --- /dev/null +++ b/docs/06-identity-and-data-model.md @@ -0,0 +1,144 @@ +# Identity and data model + +## Decision + +Element identity is logical, immutable, snapshot-independent, and distinct from physical position. A CSR offset, row number, SQLite `rowid`, object key, or encoded-array slot is never a public node or edge identity. + +This corrects the current executor, which represents a relationship as `(table, src, dst)`. That representation cannot distinguish parallel edges and therefore gives incorrect trail semantics, deletes, property lookup, and cardinality whenever two edges share endpoints. + +## Identifier layout + +The portable logical forms are: + +```rust +#[repr(transparent)] +pub struct NodeId(u64); + +#[repr(transparent)] +pub struct EdgeId(u128); + +pub struct ElementRef { + pub kind: ElementKind, + pub table: TableId, + pub id: ElementId, +} +``` + +`NodeId` is a 64-bit database-lineage-local value in v1. `EdgeId` is 128-bit because object-store partitions must allocate concurrently without coordinating every insert. Neither exposes bit fields through the public API. A backend may internally use a compact 64-bit edge ID only when import/export and uniqueness are lossless. + +Recommended allocation: + +- local zu1 and SQLite: monotonic 64-bit sequence persisted in commit metadata; widen edge IDs to 128 bits at the boundary; +- object store: `writer_epoch:32 | writer_id:32 | counter:64`, encoded big-endian for stable ordering; +- imported user IDs remain properties or primary keys unless an explicit preserve-ID import validates the namespace; +- IDs are never reused, including after abort, deletion, vacuum, or restore. + +Constructors are checked in every build. `try_from_raw`, `try_from_parts`, and deserialization reject reserved values and overflow. `new_unchecked` is crate-private and documents its proof obligation. Debug assertions are not validation. + +## Table and schema identity + +Names are mutable catalog attributes; IDs are immutable: + +```text +CatalogId u128, unique database lineage +SchemaVersion u64, monotonically published +TableId u32, never reused within lineage +ColumnId u32, never reused within table +ConstraintId u64 +IndexId u64 +``` + +A rename changes only the name mapping. Dropping and recreating `Person` creates a new `TableId`. Plans embed catalog lineage, schema version, and stable IDs, then revalidate name-dependent assumptions before execution. + +## Edge semantics + +An edge record contains: + +```rust +pub struct EdgeHeader { + pub id: EdgeId, + pub table: RelTableId, + pub src: NodeId, + pub dst: NodeId, + pub begin: CommitTs, + pub end: CommitTs, // infinity until deleted +} +``` + +For undirected syntax, storage still chooses a canonical endpoint ordering and preserves the logical edge once. Directional expansion produces the appropriate orientation without duplicating identity. Self-loops appear once per logical expansion unless the language construct explicitly has two endpoint roles. + +Parallel edges are first-class. Existence probes return a count or IDs; boolean results are only valid when the consumer explicitly requests existential semantics. Trail uniqueness uses `EdgeId`; simple-path uniqueness uses `NodeId`; walk semantics use neither visited set. + +## Physical locators + +Physical locators are hints scoped to one immutable root: + +```rust +pub struct PhysicalLocator { + pub root: RootId, + pub object: ObjectId, + pub group: u32, + pub ordinal: u32, +} +``` + +They may be cached beside an ID, but lookup must fall back through an ID index when the root changes. Compaction is free to rewrite every locator. No WAL entry, query value, foreign key, or client-visible token may rely on one after its root is unpinned. + +## Logical schema + +Node tables define a primary key and zero or more labels. Relationship tables define allowed source/destination table sets, directionality, and property columns. The minimum portable type system is: + +- `Bool`, signed/unsigned integers, `Float32/64`, `Decimal128(scale)`; +- UTF-8 string and binary; +- date, time, timestamp with explicit unit and timezone semantics, duration; +- list and struct with bounded nesting; +- `NodeId` and `EdgeId` as non-arithmetic internal types. + +Null and absent are distinct in schema evolution. A nullable column has a validity bitmap. A column absent from an older segment evaluates to its schema-version default; a stored null remains null. Defaults must be deterministic and side-effect-free to support replay. + +## Constraints + +The catalog represents, and commit validation enforces: + +- node primary-key uniqueness; +- optional unique and non-null constraints; +- relationship endpoint existence in the same commit snapshot plus the transaction's writes; +- source/destination table admissibility; +- optional relationship uniqueness on declared endpoint/property keys; +- delete policy: `RESTRICT`, `CASCADE`, or `DETACH`. + +Validation operates over the complete write set. It cannot publish the forward edge without the reverse edge, or a relationship without both visible endpoints. Constraint indexes are part of the commit unit; asynchronous index maintenance is allowed only for non-constraint indexes. + +## Snapshot visibility + +For snapshot timestamp `S`, an element version is visible iff `begin <= S < end`. A transaction sees its own writes over that snapshot. Update creates a new version; delete closes the old interval. Physical encodings may replace intervals with base-plus-delta structures, but must produce identical results. + +Every `DataBatch` that can bind graph elements carries logical IDs. Property lookup uses those IDs at the same `SnapshotToken`; mixing batches or tokens is a `SnapshotMismatch`, never a best-effort lookup. + +## Adjacency invariants + +For every committed directed edge `e=(id, table, src, dst)`: + +1. Enumerating `OUT(src, table)` yields exactly one entry with `(dst, id)`. +2. Enumerating `IN(dst, table)` yields exactly one entry with `(src, id)`. +3. Both entries resolve to the same property version. +4. The two entries become visible and invisible in the same published commit. +5. Sorting is deterministic by `(neighbor_id, edge_id)` unless the request states another order. + +These invariants are checked at prepare time for deltas and by offline verification for sealed structures. + +## Evolution and interchange + +Schema changes publish a new immutable schema version. Readers bind by stable column ID and use adapters for widening conversions. Destructive or narrowing conversions require a rewrite job and cannot reinterpret bytes in place. + +Canonical export includes catalog lineage, stable schema IDs, logical element IDs, commit timestamp, and format version. A backup restore preserves IDs and lineage; a logical copy intentionally creates new lineage and records an ID mapping. + +## Required tests + +- two, ten, and 100 parallel edges between identical endpoints retain distinct bindings; +- self-loop expansion has specified multiplicity in inbound, outbound, and both modes; +- compaction changes all physical positions without changing IDs or query results; +- abort burns allocated IDs and retry with the same transaction remains idempotent; +- rename/drop/recreate cannot bind a stale plan to the new table; +- boundary values and malformed binary IDs fail identically in debug and release; +- forward/reverse/property indexes agree after crash recovery at every injected write point. diff --git a/docs/07-query-engine.md b/docs/07-query-engine.md new file mode 100644 index 0000000..8d4542e --- /dev/null +++ b/docs/07-query-engine.md @@ -0,0 +1,131 @@ +# Query engine specification + +## Scope + +The query layer owns parsing, semantic analysis, logical planning, optimization, physical lowering, vectorized execution, and result streaming. It does not open zu1 files, issue SQLite statements, or construct object keys. All data access goes through the storage/query SPI. + +The v1 language is the documented read subset plus explicit transactional DML only when its storage path is complete. Unsupported syntax fails during analysis with a stable feature code. It must never parse successfully and then silently weaken graph semantics. + +## Pipeline + +```text +text -> CST -> typed AST -> bound logical graph plan + -> normalized IR -> memo/optimizer -> backend-aware physical plan + -> bounded batch pipeline -> result stream + profile +``` + +Each boundary is serializable for tests. The bound plan records catalog lineage/version, table and column IDs, parameter types, nullability, uniqueness, and ordering. Cached plans rebind or fail on incompatible schema change. + +## Logical algebra + +Required operators include: + +- `NodeScan`, `EdgeScan`, `Expand`, `ExpandInto`, `PathExpand`; +- `Filter`, `Project`, `Unwind`, `Distinct`, `Sort`, `TopK`, `Limit`; +- `HashJoin`, `MergeJoin`, `IndexJoin`, `IntersectJoin`, `OptionalJoin`; +- `Aggregate`, `Window` when supported by grammar; +- `Create`, `Update`, `Delete`, `Merge` only behind completed mutation capabilities. + +Logical `Expand` carries direction, edge types, endpoint predicates, path mode (`walk`, `trail`, `simple`), length bounds, and whether edge identity is bound. Multiplicity is part of the operator contract, not an optimizer accident. + +## Cardinality and cost model + +Statistics are versioned catalog objects: + +- exact row/edge counts per table and group; +- degree count, mean, variance, max, and equi-depth/log histograms; +- heavy hitters and joint endpoint-label counts; +- null fraction, min/max, distinct estimates and selected multi-column sketches; +- storage locality: bytes, groups, object ranges, compression, cache residency class; +- confidence, sample rate, generation, and staleness. + +The estimator returns `(low, expected, high, confidence)`, not a misleading scalar. Pessimistic bounds and degree-sequence bounds guide memory admission and catastrophic-plan avoidance; expected cost selects among acceptable plans. Feedback is keyed by normalized plan and snapshot/statistics generation, bounded in influence, and never changes semantics. + +Cost has separate dimensions: + +```text +cpu_units, decoded_bytes, peak_memory, +local_io_bytes + seeks, +remote_requests + remote_bytes, +spill_bytes, startup_latency +``` + +Profiles calibrate weights. A single number may rank candidates within one profile, but EXPLAIN exposes the vector and estimates. Object-store request cost cannot be hidden inside a nominal byte count. + +## Join and traversal strategy + +The optimizer must consider both binary and multiway plans: + +- adjacency expansion for selective bound endpoints; +- scan/hash join for broad edge access; +- ordered intersection or worst-case-optimal join for cyclic motifs; +- semijoin/bitmap reduction before expensive fact scans; +- factorized intermediate batches where repeated prefixes would explode; +- robust recursive scheduling for variable-length paths. + +The recent research direction is convergence, not one universal algorithm: worst-case-optimal and binary joins can share infrastructure; robust recursive execution reduces dependence on perfect path cardinalities; factorization should be adaptive. These features enter behind plan-rule flags and differential tests. + +## Physical operators + +Operators consume and produce `DataBatch`. They implement: + +```rust +trait Operator { + fn open(&mut self, cx: &mut ExecContext) -> Result<()>; + fn poll_next(&mut self, cx: &mut ExecContext) + -> Poll>>; + fn close(&mut self, cx: &mut ExecContext); +} +``` + +Every operator declares its memory behavior (`streaming`, `bounded_state`, `blocking`, `spillable`), preserved ordering, multiplicity, and cancellation granularity. Blocking operators reserve memory before building. Failure to reserve triggers an alternative/spill or `BudgetExceeded`; it never relies on allocator OOM. + +Expression kernels accept flat, constant, dictionary, FOR/bit-packed, and selected structural encodings. Unsupported combinations explicitly materialize through a budgeted adapter. Selection vectors are preferred over copying. Null semantics are defined once in the typed expression layer. + +## Backpressure and cancellation + +The result consumer drives demand. At most the configured number of batches may be queued per pipeline edge. Remote sources have request and byte semaphores; cancellation stops new work, attempts provider cancellation, discards late results, and releases all reservations/pins. + +The executor checks deadline/cancellation at least once per batch and inside long graph loops. A client that stops reading cannot leave a producer, SQLite statement, range request, spill file, or pinned snapshot live indefinitely. + +## Variable-length paths + +Path execution has explicit guards: + +- length bounds are mandatory for object-store profiles unless an administrator enables bounded-runtime search; +- maximum frontier entries, path states, result rows, bytes, and wall time are enforced; +- visited edge/node state uses stable IDs; +- breadth/depth/bidirectional strategy is costed from degree bounds and endpoint selectivity; +- frontier expansion is batched and deduplicated only where path semantics permit; +- optional recursive morsel stealing may rebalance skew without changing deterministic results. + +Spilled frontier state is checksummed and query-scoped. Unbounded enumeration is rejected at admission when no safe envelope is available. + +## SQLite lowering + +The SQLite backend may return a native statement source for scans, joins, filters, or aggregates it can exactly implement. Lowering uses bound identifiers and parameters, never string substitution. A pushed fragment returns its exact output schema, ordering, null/multiplicity proof, and residual predicate. + +Graph-specific lowering batches source IDs into a temporary/virtual table and joins an indexed edge table once. Per-source SQL queries are prohibited in a physical plan except for a proven tiny cardinality under a configured threshold. + +## Object-store lowering + +Plans group adjacency sources by tile/object, coalesce allowed byte ranges, and schedule bounded concurrent reads. A cold-plan estimate includes metadata fetches and range request count. If projected requests or bytes exceed the read envelope, optimization must choose a scan/coarser tile or reject before execution. + +## DML execution + +DML produces a logical mutation batch. The executor performs expression evaluation and eager local validation; the storage mutation service performs authoritative validation and publication. `RETURNING` rows are released only at the promised durability/publication point. A failed multi-row statement has no partial effect. + +## Determinism and observability + +Without `ORDER BY`, row order is unspecified but multiplicity is exact. With order, ties follow documented expressions and a stable ID tie-breaker when pagination tokens require repeatability. + +`EXPLAIN` reports logical/physical plans, pushdown classification, capability assumptions, estimated ranges, remote request/byte estimates, and admission decision. `PROFILE` adds actual rows, batches, time, CPU, waits, peak memory, decoded/read bytes, cache tiers, spills, and source requests. Secrets and property values are redacted by default. + +## Correctness gates + +- differential query generation compares zu1, SQLite, and an in-memory reference at the same logical snapshot; +- parallel edges, nulls, empty adjacency, self-loops, cycles, disconnected patterns, and skew are mandatory corpora; +- every rewrite has equivalence/property tests including bag semantics; +- fault injection proves cancellation releases memory, pins, statements, and I/O; +- optimizer fuzzing validates every chosen plan against the interpreter; +- cold and warm object-store request counts are regression metrics, not anecdotes. diff --git a/docs/08-transactions-and-recovery.md b/docs/08-transactions-and-recovery.md new file mode 100644 index 0000000..3c59f5d --- /dev/null +++ b/docs/08-transactions-and-recovery.md @@ -0,0 +1,132 @@ +# Transactions, durability, and recovery + +## Public contract + +The default isolation level is snapshot isolation with explicit write-write conflict detection. A transaction reads one immutable `SnapshotToken` plus its own writes. Serializable isolation is future work unless predicate/range conflicts are implemented and tested; documentation must not imply it. + +```rust +pub trait Transaction { + fn snapshot(&self) -> &SnapshotToken; + fn query(&mut self, query: BoundQuery) -> Result; + fn mutate(&mut self, batch: LogicalMutationBatch) -> Result<()>; + fn commit(self, level: DurabilityLevel) -> Result; + fn rollback(self) -> Result<()>; +} +``` + +A connection may own only one active write transaction. Read transactions are independent snapshot handles. Dropping an uncommitted write transaction rolls it back; it never commits implicitly. + +## Commit timestamps and conflicts + +`CommitTs` is a monotonically published 64-bit sequence within one database lineage. It is not wall-clock time. The commit coordinator assigns it after validating the base snapshot and before writing the durable commit record. + +Conflict detection covers: + +- the same logical element version written after the base snapshot; +- uniqueness/index keys introduced or removed after the base snapshot; +- schema objects changed since binding; +- endpoint deletes conflicting with new edges; +- compare-and-set catalog/root generation. + +Snapshot isolation permits write skew across disjoint keys. APIs label this behavior. Operations requiring stronger invariants use a catalog-defined validation key or wait for serializable support. + +## Durability levels + +| Level | Acknowledgement condition | Crash expectation | +|---|---|---| +| `Memory` | transaction published in process | may be lost on process failure | +| `Local` | WAL and commit marker synced to configured local device | survives process/OS restart subject to device contract | +| `RemoteLog` | immutable WAL exists and fenced authoritative metadata commits its digest/high-water mark | survives loss of local cache; readers may merge committed log | +| `Published` | selected data/root representation covers the commit | readable without an uncovered transaction-log tail | +| `Replicated(n)` | durable receipt from a separately qualified quorum/service | depends on its declared failure model; post-v1 unless implemented | + +The receipt states the achieved level, commit timestamp, root generation, transaction ID, mutation digest, writer epoch, and backend evidence. The API never returns a stronger enum than actually achieved. + +## Local WAL format + +The WAL is a sequence of framed records: + +```text +magic | version | type | flags | header_len | payload_len +txn_id | sequence | base_ts | payload_digest | header_crc +payload | payload_crc | frame_len_copy +``` + +Record types include `Begin`, logical/physical mutation chunks, `Prepare`, `Commit`, `Abort`, `Checkpoint`, and `RootPublish`. Maximum sizes are bounded before allocation. Unknown required versions fail closed; optional fields use a length-delimited extension area. + +One transaction's payload may span frames. `Commit` contains the digest of the ordered mutation frames, assigned commit timestamp, and resulting catalog/root digest. A torn or corrupt tail is truncated only after the last fully verified frame. Corruption in an acknowledged committed prefix is a hard error, not treated as an ordinary tail. + +## Local commit protocol + +For `Local` durability: + +1. Freeze the logical write set and compute its digest. +2. Under commit serialization, validate conflicts and constraints against current published state. +3. Reserve IDs and assign `CommitTs`. +4. Append mutation and `Commit` frames. +5. Sync WAL according to the configured device policy. +6. Apply/publish the in-memory delta root with a release barrier. +7. Return a receipt. + +Readers acquiring a snapshot after step 6 see the commit; earlier snapshots do not. If step 5 succeeds and the process dies before step 6, recovery publishes the committed record. If step 5 fails, no success is returned. + +Group commit may combine steps 4–5, but each receipt remains tied to its own verified commit record. An explicit maximum delay and byte threshold bound latency. + +## Overlay and checkpoint + +Committed WAL-backed deltas are immediately queryable. The canonical reader merges: + +```text +immutable checkpoint root + committed delta layers <= snapshot + txn-local writes +``` + +The query facade cannot bypass the overlay by opening a sealed `Zu1File` directly. Delta indexes cover ID/PK lookup, property versions, tombstones, and both adjacency directions including edge IDs. + +Checkpoint builds a new immutable root without blocking readers, verifies it, then publishes a small atomic root record. Only after the root is durable and no pinned snapshot needs older state may WAL prefixes and old roots be reclaimed. + +## Recovery state machine + +On open: + +1. Select the newest valid root record by generation and checksum; never just the newest bytes. +2. Load bounded root metadata and catalog. +3. Scan WAL from the root's replay position, validating every frame and transaction digest. +4. Redo committed transactions not incorporated in the root; discard incomplete/aborted transactions. +5. Reconstruct indexes, next-ID counters, commit clock, and delta root. +6. Run invariant checks before accepting writers. + +Recovery is idempotent. Reopening after a crash during recovery produces the same state. Normal open time is proportional to post-checkpoint WAL, with a configured threshold that can force read-only open or recovery checkpoint rather than unbounded surprise. + +## Ambiguous commits + +Timeout or transport failure after durable submission yields `AmbiguousCommit { key }`. The client calls `reconcile(key)`; blindly retrying with a new transaction can duplicate effects. Retrying the same `(TxnId, mutation_digest)` returns the original result. The same `TxnId` with another digest is rejected. + +## Object-store transaction protocol + +Single-partition object commits use immutable objects plus a fenced manifest. Updating that manifest with an advanced committed WAL high-water mark achieves `RemoteLog`; advancing its materialized-through position after validated packs achieves `Published`: + +1. Acquire/renew a writer lease and monotonically increasing writer epoch from the configured coordinator. +2. Write immutable WAL/data objects under content-addressed or transaction-scoped keys. +3. Verify object length/checksum through provider response or read-back policy. +4. Conditional-write the partition manifest from generation `g` to `g+1`, including writer epoch, commit digest, immutable object references, and WAL high-water mark. +5. Re-read or otherwise verify the winning manifest before acknowledging `RemoteLog` or `Published`, as applicable. + +Every publication checks the writer epoch. A stale writer cannot acknowledge merely because it uploaded an object. S3 conditional writes serialize one manifest key but do not create a cross-key transaction; the protocol derives atomic visibility solely from the final manifest reference. + +Multi-partition atomic transactions are out of scope for v1. A cross-partition operation must be rejected, explicitly executed as a saga with visible partial-state semantics, or delegated to an external transactional coordinator. Forward and reverse adjacency for one edge therefore live in the same atomic partition unit or are published by a protocol that proves their joint visibility. + +## Backup and restore + +A backup captures one pinned immutable root, all referenced objects, catalog lineage, and a manifest with sizes and cryptographic digests. Completion means every referenced object has been verified. Restore writes a new unpublished root, verifies it, then atomically installs it. Point-in-time restore replays only complete commits through a specified `CommitTs`. + +## Fault-injection matrix + +Tests terminate or fail I/O: + +- before/after every WAL append, sync, root write, rename/manifest CAS, and acknowledgement; +- on short writes, torn sectors, stale reads, duplicate delivery, timeout, throttling, and checksum mismatch; +- with concurrent checkpoint, compaction, readers, and writers; +- while allocating IDs and updating uniqueness/adjacency indexes; +- during lease expiry and stale-writer continuation. + +For each point, the allowed outcome is precisely old state or new committed state; never half an edge, orphan properties, duplicate commit, a visible uncommitted row, or acknowledgement followed by loss under the selected durability model. diff --git a/docs/09-zu1-format-and-io.md b/docs/09-zu1-format-and-io.md new file mode 100644 index 0000000..84ce556 --- /dev/null +++ b/docs/09-zu1-format-and-io.md @@ -0,0 +1,130 @@ +# zu1 format, encoding, and local I/O + +## Format posture + +zu1 is an immutable, checksummed local checkpoint format with append-only publication metadata. It is not itself the database transaction layer. WAL/delta state is composed through the storage engine and becomes a new zu1 root during checkpoint. + +The format is explicitly versioned and has a compatibility policy. Readers accept the current major version and documented older versions; writers emit one configured version. A major bump is required for a semantic reinterpretation. Minor extensions are length-delimited and ignorable only when marked optional. + +## File layout + +```text +superblock A (4 KiB) +superblock B (4 KiB) +root journal / bounded anchor area +immutable metadata pages +immutable data extents +optional append-only free-space/checkpoint records +``` + +Each superblock contains magic, format version, page-size log2, database lineage, root generation, root pointer/length, WAL replay position, feature flags, and checksum. Publication writes an inactive root/superblock, syncs required bytes, then advances the chosen superblock. Open selects the highest generation whose full dependency graph verifies. + +The root contains a bounded directory of catalogs, table manifests, indexes, statistics, and extent maps. Opening a healthy file reads `O(1)` anchor pages plus requested metadata—not the complete free-list chain and not every segment. Free-space summaries are checkpoint artifacts with a bounded top-level index; rebuilding them is maintenance, not a prerequisite for read-only open. + +## Page and object integrity + +Every independently addressed unit has: + +- type, version, logical object ID, generation, encoded and decoded lengths; +- codec/encoding ID and required feature flags; +- CRC32C for accidental corruption; +- parent manifests with a cryptographic digest (BLAKE3-256 or a specified equivalent) for identity and end-to-end validation. + +A point lookup or range scan validates every chunk it consumes. Whole-segment checksums alone are insufficient because a fast path can skip untouched bytes and otherwise return silently corrupted values. Chunk size is selected so validation amplification remains bounded, initially 16–64 KiB. + +Lengths, offsets, counts, bit widths, nesting, and allocation products are checked before pointer arithmetic or allocation. Decoding untrusted/corrupt files never invokes unchecked slicing. The verifier reports object and range; repair never silently edits the only copy. + +## Row groups and arrays + +The unit of pruning, fetching, and parallel scan is a row group. The initial target is 64K–1M logical rows depending on width, with a byte-size cap. Each group manifest records row range, column chunk locations, min/max/null/distinct metadata, encoding tree, checksums, and optional learned/selectivity metadata. + +An array is a typed encoding tree, not one enum choice: + +```text +ArrayNode := Flat + | Constant + | BitPacked(bit_width, child/domain) + | FOR(base, deltas) + | Delta(base, deltas) + | RLE(values, runs) + | Dictionary(dictionary, codes) + | Sparse(present, values, default) + | List(offsets, child) + | Struct(children) + | Validity(bitmap, child) +``` + +Nesting depth, child count, and decoded expansion are bounded. Each node declares supported kernels (`filter`, `compare`, `gather`, `sum`, `minmax`) so execution can operate compressed or request materialization. The encoder samples candidates and minimizes a calibrated objective over bytes, decode CPU, point access, and filter kernels. The current `encode_auto` single-choice behavior is retained only as a baseline. + +Structural encodings should borrow the separable layout/scan ideas demonstrated by Lance and Vortex, while FastLanes motivates portable vector-sized primitives. Adoption requires zu-specific benchmarks and fuzzed round trips; a paper result is not a format guarantee. + +## Adjacency layout + +Each relationship table stores edge records by stable `EdgeId` plus two adjacency projections: + +```text +out: src -> [(dst, edge_id, optional inline columns)] +in: dst -> [(src, edge_id, optional inline columns)] +``` + +Lists are ordered by `(neighbor_id, edge_id)`, and high-degree lists are split into continuation tiles with explicit first/last keys. A two-level degree/offset index locates a node without decoding unrelated groups. Empty nodes remain representable through the node-domain index. + +The sealed base is dense. Update slack is not placed inside immutable CSR; changes live in WAL-backed delta adjacency and are merged during reads. Checkpoint compacts selected relationship partitions/groups, not necessarily the entire table. A partition map and change heat determine rebuild scope. Claiming group-local rebuild is prohibited until this machinery exists. + +## Indexes + +Mandatory indexes: + +- logical ID to group/ordinal for node and edge records; +- node primary key to `NodeId` with uniqueness metadata; +- source and destination adjacency directory; +- edge property locator by `EdgeId`; +- group-level zone maps/statistics. + +Optional indexes are cataloged with build root, covered columns, state (`building`, `ready`, `stale`, `failed`), and checksum. Plans can use only `ready` indexes whose root/schema compatibility is proved. + +## I/O backend + +```rust +trait IoBackend: Send + Sync { + fn read_many(&self, reqs: &[ReadRange], cx: &IoContext) + -> BoxFuture>>; + fn write_extent(&self, req: WriteExtent, cx: &IoContext) + -> BoxFuture>; + fn sync(&self, scope: SyncScope) -> BoxFuture>; +} +``` + +Implementations include positioned buffered I/O first, optional mmap for immutable verified regions, and an experimental direct/async backend. Reads are positioned (`pread`-style), not shared seek state. Runtime capability detection and benchmarks choose the backend; unsupported kernels/filesystems fall back safely. + +`GraphReader::fork` becomes a cheap clone of immutable metadata and shared cache handles. It must not reopen the file read-write, duplicate catalog walks, or create isolated caches. Write handles are separately typed and never required for a query. + +## Buffer and decoded cache + +The buffer manager has global budgets and two accounting domains: + +- compressed page/chunk cache keyed by `(file identity, root, object, range)`; +- decoded/vector cache keyed by encoding node and selection/projection. + +Entries carry checksum status, byte charge, pin count, and admission class. Scans use low-retention admission; point/metadata reuse is protected. SIEVE is a candidate low-overhead eviction policy, but it is not inherently scan-resistant, so scan admission/bypass is a separate rule. No per-reader unbounded cache is allowed. + +All reads reserve bytes before issuance. Oversized results are rejected before allocation. Prefetch is cancellable and subordinate to demand. Metrics distinguish requested, fetched, validated, decoded, pinned, evicted, and wasted-prefetch bytes. + +## Compaction and free space + +Checkpoint/compaction writes new immutable extents, validates them, then publishes a new root. Readers pinned to old roots keep their extents live. Reclamation uses the minimum pinned root plus retained backup/history policy. A crash between extent creation and root publication leaves unreachable garbage discoverable by verify/GC, never visible partial data. + +The allocator cannot trust an unverified free-list entry. Extent reuse occurs only after the root that last referenced it is unpinned and a durable reclamation record exists. + +## Tooling and acceptance + +`zu inspect` prints version/root/catalog without scanning data. `zu verify` supports anchor, metadata, selected table, and full modes. `zu salvage` writes a new file and emits an evidence report; it never mutates the source. + +Format acceptance requires: + +- golden files for every supported version and endian-independent scalar tests; +- property/fuzz tests over every encoding tree and corrupted length/offset; +- point, range, and predicate reads that detect a bit flip in every consumed chunk; +- crash tests around root publication and extent reuse; +- cold/warm open complexity measurements proving bounded anchor work; +- scan, lookup, adjacency, and high-degree benchmarks against the current baseline. diff --git a/docs/10-sqlite-backend.md b/docs/10-sqlite-backend.md new file mode 100644 index 0000000..cbadea1 --- /dev/null +++ b/docs/10-sqlite-backend.md @@ -0,0 +1,89 @@ +# SQLite backend + +## Role + +SQLite is a complete storage-engine implementation for portability and transactional embedding, not an import/export shim. It implements the common catalog, snapshot, scan, adjacency, lookup, mutation, and maintenance contracts while exploiting SQLite's native transactions and planner where semantics match. + +The backend has no dependency on zu1. The query crate has no dependency on SQLite. All backend-specific lowering is selected through capabilities and a typed pushdown compiler. + +## Physical schema + +One database contains metadata tables plus user table families. Illustrative layout: + +```sql +CREATE TABLE _zu_meta(key TEXT PRIMARY KEY, value BLOB NOT NULL) WITHOUT ROWID; +CREATE TABLE _zu_schema(version INTEGER NOT NULL, catalog BLOB NOT NULL, digest BLOB NOT NULL); + +CREATE TABLE n_( + node_id INTEGER PRIMARY KEY, + pk NOT NULL UNIQUE, + begin_ts INTEGER NOT NULL, + end_ts INTEGER NOT NULL, + ... properties ... +); + +CREATE TABLE e_( + edge_hi INTEGER NOT NULL, + edge_lo INTEGER NOT NULL, + src INTEGER NOT NULL, + dst INTEGER NOT NULL, + begin_ts INTEGER NOT NULL, + end_ts INTEGER NOT NULL, + ... properties ..., + PRIMARY KEY(edge_hi, edge_lo) +) WITHOUT ROWID; +CREATE INDEX e__out ON e_(src, dst, edge_hi, edge_lo); +CREATE INDEX e__in ON e_(dst, src, edge_hi, edge_lo); +``` + +Production DDL quotes generated identifiers defensively and derives them only from numeric stable IDs. Type mapping and collation are fixed in catalog metadata. User-provided names or expressions are never interpolated into SQL. + +If historical MVCC is not enabled, tables may store only current versions and the capability matrix says so. If enabled, version history is represented explicitly or by history tables; SQLite's WAL snapshot alone is not advertised as arbitrary historical snapshot support. + +## Connection model + +Each database owns a bounded connection pool. A read snapshot pins one connection/read transaction for its lifetime. A write transaction owns a dedicated connection and uses `BEGIN IMMEDIATE` by default to make writer contention explicit. Busy handling respects query deadline/cancellation; it is not an unbounded sleep loop. + +Pragmas are configured and reported, including journal mode, synchronous level, foreign keys, cache size, temp store, mmap policy, and busy timeout. Durability receipts reflect `synchronous` and filesystem assumptions. The backend never claims `Local` if configured in a mode that cannot meet it. + +## Adjacency + +For a batch of source IDs, the engine uses a temporary input table or an equivalent bounded set mechanism and executes one indexed join per relationship-table/direction group. Results return source position, neighbor ID, and full edge ID, ordered as requested. + +Large batches are chunked below parameter/temporary-space budgets. The backend reports actual statements, rows, page-cache activity where observable, and temporary bytes. A loop issuing one query per source is a guarded tiny-input fallback and visible in the profile. + +## Typed pushdown + +The pushdown compiler accepts only the storage expression IR. It returns SQL plus bound parameters and a proof classification: + +- exact: SQLite comparison, null, collation, overflow, and function behavior match the logical language; +- pruning-only: safe necessary condition; runtime evaluates the original predicate; +- unsupported: no pushdown. + +Floating NaN, decimal scaling, timestamps/timezones, Unicode collation, integer overflow, pattern matching, and user functions require explicit conformance tests. Backend truthiness or implicit type coercion is not allowed to redefine query semantics. + +Whole safe subplans may lower to SQL: scans, joins, projection, filters, grouping, ordering, and limit. The lowering boundary returns canonical batches and preserves bag semantics. `EXPLAIN` includes sanitized generated SQL and SQLite's plan in verbose mode. + +## Mutations and IDs + +Logical mutations execute inside one SQLite transaction. ID counters, node/edge rows, both adjacency indexes, property values, constraints, catalog version, and commit metadata commit atomically. Transaction ID and mutation digest are recorded in `_zu_commits` so retries reconcile to the original receipt. + +User primary keys are independent of logical IDs. Deletes follow the catalog's edge policy. Native foreign keys may reinforce invariants, but portable pre-commit validation and conformance remain authoritative. + +## Backup and migration + +Online backup uses SQLite's supported backup mechanism or a documented consistent file procedure; copying the main file while WAL writes continue is prohibited. Import/export streams canonical batches with logical IDs and schema metadata. Migration is versioned, transactional where SQLite allows it, resumable for table rewrites, and leaves a recovery record. + +## Limits and security + +The backend sets and tests limits for SQL length, variables, expression depth, attached databases, result size, and temp storage. It disables extension loading unless explicitly enabled. Paths, URI parameters, and pragmas are validated. Cancellation interrupts the active statement and cleans temporary tables before returning the pooled connection. + +## Conformance and performance gates + +- all common storage conformance tests run against file and memory databases; +- parallel edge identity and self-loop multiplicity match the reference engine; +- randomized logical plans compare native pushdown on/off; +- kill/reopen tests cover every mutation and migration phase; +- busy, disk-full, corrupt, read-only, and cancelled cases map to stable errors; +- batched adjacency demonstrates bounded statement count as source cardinality rises; +- durable configurations document and measure commit latency without weakening defaults invisibly. diff --git a/docs/11-object-storage.md b/docs/11-object-storage.md new file mode 100644 index 0000000..13151f7 --- /dev/null +++ b/docs/11-object-storage.md @@ -0,0 +1,133 @@ +# Object-storage architecture + +## Supported profile and consistency boundary + +The first remote profile is `object-single`: one writer for one partition epoch, many readers, immutable data objects, and one atomically replaced manifest per partition. It does not promise multi-partition atomicity, linearizable arbitrary object updates, or local-device latency. + +An S3-compatible provider must offer read-after-write for new objects and conditional update on the manifest key with a stable entity tag/version. The implementation probes required capabilities and refuses writable mode when semantics are unknown. Provider-specific behavior is isolated behind the `object_store`-style async abstraction. + +## Namespace + +```text +db//catalog/ +db//part//manifest/- +db//part//CURRENT +db//wal/// +db//data/ +db//index/ +db//leases/... +db//gc/... +``` + +Immutable names are content-addressed where practical. `CURRENT` is the only mutable partition publication pointer and contains generation, manifest digest, writer epoch, prior generation, and checksum. Its immutable manifest separately records the committed WAL high-water mark and the materialized-through position. Readers never infer committed state by listing a prefix. + +## Manifest + +The immutable manifest contains: + +- database lineage, partition ID, generation, parent digest, writer epoch; +- schema/catalog digest and commit timestamp range; +- committed WAL high-water mark, materialized-through position, and transaction digest set/index; +- data/index object references with exact length, cryptographic digest, format and key ID; +- partition mapping version, statistics and deletion/tombstone references; +- minimum reader/runtime version and feature requirements. + +The complete manifest is checked before a root becomes readable. Metadata is sharded into immutable submanifests when necessary, but opening fetches a small bounded root and only demanded subtrees. + +## Writer fencing + +Conditional `PUT CURRENT if-match=` prevents two updates from winning that one key, but is not a lease and does not by itself fence a stale writer's WAL acknowledgements. A writable deployment therefore supplies a fencing service with monotonically increasing epochs (for example, an external transactional metadata service). Every prepared commit, immutable WAL object, manifest, and receipt carries the epoch. + +A writer must renew before a safety margin. Once renewal is uncertain or expired, it stops acknowledgement immediately. A later writer publishes a greater epoch; readers reject manifests that violate epoch/generation lineage. “Take over now” without lease expiry/election is not a supported operation. + +If no fencing service is configured, the backend runs in one of two honest modes: read-only, or administratively single-writer with no automatic failover guarantee. + +## Commit protocol + +The remote protocol follows [transactions and recovery](08-transactions-and-recovery.md). Key additional rules: + +1. Uploaded objects are immutable and retryable by exact key/digest. +2. A manifest references only successfully verified objects. +3. The conditional `CURRENT` update is the linearization point for partition visibility. A generation may advance only the committed WAL tail (`RemoteLog`) or also advance materialized data coverage (`Published`); readers merge the uncovered committed tail. +4. A lost response creates an ambiguous commit; reconcile reads `CURRENT` ancestry/commit index. +5. An orphan upload is invisible and later GC-eligible. +6. Publication never requires atomic rename, directory listing consistency, or in-place append. + +AWS documents strong consistency for individual S3 object reads/writes and conditional requests, but object-store atomicity remains key-scoped. The architecture must not extrapolate that into a transaction spanning WAL, data, and catalog keys. SlateDB's manifest evolution is a useful warning: safe fencing includes WAL positions and compactor/writer coordination, not merely a last-writer-wins root string. + +## Data layout for graphs + +Remote layout minimizes request count, not just bytes. A partition manifest maps node/edge ID ranges and hashed/high-degree exceptions to packs. Each pack contains independently checksummed aligned tiles: + +- adjacency directory tile for many source nodes; +- adjacency data tiles containing neighbor and edge IDs; +- projected hot edge properties when configured; +- column data tiles and group metadata; +- optional coarse endpoint/bloom/zone indexes. + +Small metadata/chunks are packed to avoid tiny GETs. Large high-degree lists have range-addressable continuation tiles. Forward/reverse views and edge records for one atomic partition commit are referenced by the same manifest generation. + +Partitioning begins with a declared strategy (source range/hash, table, or tenant). The v1 rule is source ownership: the canonical edge record and outbound projection commit in the source partition; a remote-destination reverse projection is an explicitly asynchronous derived index. Strict queries route through canonical source ownership or reject a stale reverse-index plan. A `SnapshotVector` reports each partition generation. Independent forward/reverse publication must never be presented as one atomic property-graph snapshot. + +## Read path + +Cold query execution is: + +```text +resolve/pin CURRENT -> fetch root/submanifest -> plan tile ranges +-> memory cache -> disk cache -> coalesced ranged GETs +-> checksum/decode -> bounded batches +``` + +The reader keys caches by immutable digest, so stale bytes cannot alias a new generation. It coalesces only ranges whose excess bytes are cheaper than another request under current provider/pricing weights. Concurrency, in-flight bytes, retries, and decoded memory are separately bounded. + +Remote adjacency is always batched by source IDs and tile. The optimizer sees projected GET count, bytes, cold/warm class, and cache certainty. A “95% hit rate” is an observation, never a latency or cost bound. Cold latency includes manifest and data requests; total latency includes queue, fetch, checksum, decode, compute, spill, and result backpressure. + +## Cache + +The disk cache is an optional content-addressed store with an atomic local index, byte quota, checksum on fill/use policy, and cross-process locking. A partial download is written under a temporary unique name, verified, then installed. Eviction never affects correctness. + +Admission distinguishes metadata, reused point tiles, and one-pass scans. Scan resistance is implemented via admission/bypass and protected metadata quotas; an eviction policy alone is insufficient. Prefetch uses lower priority and is dropped first under pressure. + +## Retry and error policy + +Only idempotent object operations retry automatically. Retry classification uses provider status, honors server hints, applies jittered exponential backoff, and consumes a deadline/attempt budget. Authentication, conditional failure, checksum mismatch, and semantic not-found are not blindly retried. Metrics record attempts, throttling, bytes repeated, and ambiguity. + +## Encryption and credentials + +TLS is required in transit. Server-side encryption settings are explicit; optional client-side envelope encryption records key ID and authenticated metadata in each object header. Nonces are unique per object/chunk. Credentials use the provider chain and are never stored in manifests, logs, plans, or cache metadata. + +Key rotation rewrites references by publishing a new immutable generation. Deleting old keys waits until retention, backups, and pinned readers no longer depend on them. + +## Garbage collection + +GC is mark-and-sweep over a consistent set of retained roots: current roots, manifest ancestry within retention, backups, pins/leases, and in-progress jobs. It writes a mark epoch, observes a quarantine interval longer than maximum publication/clock uncertainty, then deletes only unreferenced immutable objects older than the epoch. + +Listing is discovery, never proof of liveness. Delete batches are idempotent and audited. Dry-run reports exact keys, sizes, roots considered, and earliest deletion time. By default, GC is disabled until pin/retention accounting passes crash and race tests. + +## SLO and cost contract + +Performance is reported by workload and state: + +- cold/warm/hot latency percentiles; +- queries admitted/rejected/throttled; +- requests and provider bytes per query; +- cache hit bytes by tier, not only hit operations; +- compute/decoded bytes, spill and peak memory; +- commit upload bytes, requests, CAS conflicts and ambiguous outcomes; +- estimated provider cost under a named price table and date. + +There is no universal “flat query cost.” Admission enforces `max_remote_requests`, `max_remote_bytes`, time, and result limits. Public targets name graph size, selectivity, degree distribution, projection, cache state, region, concurrency, and hardware. + +## Qualification + +- provider contract tests against supported S3 implementations and fault proxies; +- stale-writer/lease-expiry tests proving no acknowledgement after fencing; +- crash and response-loss tests at every commit step; +- corrupt/truncated/range-shifted object detection; +- no-listing read correctness and GC races with publication/pins; +- high-degree, random-source, full-scan, and cross-partition workloads; +- request-bound assertions in CI for canonical query plans; +- restore from remote-only state with empty caches. + +Turbopuffer is a useful systems comparator for object-storage economics: it batches WAL persistence and uses an object-friendly coarse index rather than assuming a pointer-heavy local index transfers directly. Its published cold/warm latency gap also reinforces that remote performance must be specified by cache state, not one headline number. diff --git a/docs/12-runtime-and-resources.md b/docs/12-runtime-and-resources.md new file mode 100644 index 0000000..e8bb752 --- /dev/null +++ b/docs/12-runtime-and-resources.md @@ -0,0 +1,149 @@ +# Runtime, resources, and observability + +## Runtime contract + +The runtime turns a physical plan into bounded work. Correctness includes predictable ownership under overload: no query, writer, scan, prefetcher, or maintenance job can allocate or issue I/O without a reservation. + +The runtime is internal and poll-based. Public APIs may expose synchronous iterators and opt-in async streams without committing storage traits to Tokio or another runtime. Backend adapters bridge their completion mechanisms into the common scheduler. + +## Resource hierarchy + +```text +process +└── database + ├── foreground pool + │ ├── connection/session + │ └── query or transaction + │ ├── operator + │ └── source/task + ├── caches + └── maintenance pool +``` + +Budgets cover at least: + +- resident and decoded memory bytes; +- pinned cache bytes; +- temporary/spill bytes; +- CPU time/work units; +- local read/write bytes and concurrent operations; +- remote requests, bytes, concurrent operations, retries, and estimated charge; +- output rows/bytes; +- wall-clock deadline. + +Child reservations debit parents. Reserved-but-unused capacity is reclaimable; committed allocations are released by RAII guards. Counters use checked arithmetic. A request exceeding a hard limit fails before allocation or I/O. + +## Memory protocol + +```rust +pub trait MemoryPool: Send + Sync { + fn try_reserve(&self, bytes: usize, class: MemoryClass) + -> Result; +} +``` + +Operators estimate minimum and preferred reservations during admission. Execution grants memory incrementally. Hash tables and frontiers grow only after acquiring the next reservation. Variable-length decoders validate decoded size and reserve it before allocation. + +Memory classes distinguish operator state, input/output batches, pinned encoded bytes, decoded cache, metadata, writer/WAL buffers, and maintenance. A fixed emergency reserve remains available for error reporting, cancellation, and cleanup; normal work cannot consume it. + +Global pressure proceeds in this order: + +1. stop speculative prefetch and low-value cache admission; +2. evict unpinned cache entries; +3. ask spillable foreground operators to spill at safe points; +4. throttle new work and maintenance; +5. reject admission with a structured limit error. + +The runtime never depends on the operating-system OOM killer as policy. + +## Scheduling + +CPU work is split into morsels with a target execution time, initially 0.25–2 ms after calibration. Tasks carry database/query identity, priority class, cancellation token, and resource reservation. Work stealing is allowed within fairness constraints. + +Weighted deficit scheduling prevents one broad scan or recursive traversal from monopolizing workers. Interactive, batch, ingestion, and maintenance weights are configurable. Aging prevents starvation. A per-query runnable-task cap controls fan-out even when many graph partitions exist. + +Long kernels and recursive expansions yield at batch/morsel boundaries. Blocking OS/SQLite calls run on a bounded blocking pool. An exhausted blocking pool backpressures submitters rather than spawning threads. + +## I/O scheduling + +I/O requests declare ranges, priority, deadline, expected bytes, checksum scope, and coalescing key. The scheduler: + +- merges compatible adjacent reads within a bounded amplification ratio; +- limits per-backend/per-query operations and bytes in flight; +- schedules metadata ahead of speculative data but behind demanded foreground data; +- supports cancellation before dispatch and discards late completion safely; +- accounts actual bytes, retries, and provider requests to the originating query/job. + +Local and remote I/O share accounting, not identical policies. Local seek/queue depth, object-store GET count, and SQLite statement concurrency remain distinct metrics and cost dimensions. + +## Backpressure + +Pipeline channels are bounded by batches and bytes. A producer may not retain an unbounded batch while waiting for output capacity. Source polling stops when downstream has no demand, except for a strictly bounded read-ahead window. + +Result streams own the query until exhausted, cancelled, or dropped. Drop triggers cancellation and bounded cleanup. If cleanup requires asynchronous completion, the database lifecycle retains the cleanup task and its charges; resources do not leak merely because the client abandoned a future. + +## Spill + +Spill files live in a database-configured directory, never an implicit current directory. Each query has a unique subdirectory with restrictive permissions and a manifest. Blocks are length-delimited and checksummed; optional authenticated encryption is required where temp storage is not trusted. + +Spill algorithms include partitioned hash join/aggregate, external sort, distinct, and recursive frontier state. Operators reserve spill quota before writing. Disk-full becomes `BudgetExceeded`/I/O error with cleanup. Startup scavenging removes abandoned query directories only after validating ownership and age; active instances use locks/leases. + +Spill bytes are not durable database state and are never replayed after crash. + +## Cache policy + +Cache capacity is a database-level resource with protected metadata quota. Entries are immutable and keyed by database lineage, root/content digest, object/range, representation, and schema/codec version. No key may alias bytes across generations. + +Admission uses reuse evidence and scan classification. Sequential one-pass input may bypass the cache. Eviction policy is independently replaceable and measured against skew, scans, and mixed workloads. Pinned entries may lose cache membership but remain alive and charged to their pin owner until release. + +Negative cache entries have short explicit TTLs and are invalidated by root generation. Authorization or transient provider errors are never negative-cached as absence. + +## Admission + +Before execution, the planner supplies low/expected/high estimates and minimum viable resources. Admission checks: + +```text +hard semantic limits +available memory and spill +CPU/runnable capacity +local I/O envelope +remote request/byte/cost envelope +deadline feasibility +``` + +Uncertain estimates use the high bound for hard remote/cost limits and a configured confidence policy for elastic resources. During execution, approaching an envelope can select a preplanned fallback at a checkpoint; otherwise execution stops cleanly. Semantics never change to stay under budget. + +## Observability schema + +Every operation has trace ID, database/partition ID, snapshot/root generation, query fingerprint, backend, and outcome. Raw query text, parameter/property values, credentials, object authorization tokens, and filesystem secrets are excluded by default. + +Minimum counters/histograms: + +- parse/bind/optimize/admission/queue/execute/result durations; +- rows and batches at each operator, estimated versus actual; +- current/peak reserved memory, pins, cache and spill bytes; +- local reads/writes/seeks/sync latency; +- object requests by operation/status/retry, requested/fetched bytes, cache tier; +- SQLite statement count, time, busy time, rows and temp use; +- WAL append/sync/group size, commit phase latency, conflicts and ambiguity; +- snapshot age/pins, root generations, checkpoint/compaction/GC debt; +- cancellation latency and cleanup failures. + +Cardinality labels are bounded: table/column names, query text, node IDs, object keys, and transaction IDs do not become metric labels. Detailed identifiers belong in sampled/redacted traces. + +## Profiles and reproducibility + +`EXPLAIN ANALYZE` records engine/version, format/root, schema/stats version, optimizer flags, hardware/profile ID, memory/request envelopes, cache state declaration, and per-operator measurements. Benchmark artifacts capture these fields plus dataset digest and random seed. + +Timing instrumentation is sampled or batched so profiling overhead is measured. A no-profile baseline and counter-only mode quantify observer effects. + +## Runtime qualification + +- adversarial allocation sizes never exceed configured resident memory beyond a small measured allocator allowance; +- dropping results at every operator releases pins, tasks, statements, and requests; +- slow consumers keep bounded queued bytes; +- concurrent high-degree traversals respect fairness and runnable caps; +- maintenance cannot starve foreground commits or consume emergency reserve; +- disk-full, cache corruption, delayed I/O, retry storms, and provider throttling stay bounded; +- ThreadSanitizer/Loom-style state tests cover publication, cancellation, pins, and queues where practical; +- profiles reconcile operator totals with backend requests/bytes and global resource counters. diff --git a/docs/13-qualification-and-operations.md b/docs/13-qualification-and-operations.md new file mode 100644 index 0000000..160270e --- /dev/null +++ b/docs/13-qualification-and-operations.md @@ -0,0 +1,151 @@ +# Qualification, security, and operations + +## No benchmark is a contract without a workload + +Every performance statement names: + +- commit/build version and feature flags; +- dataset generator/source and digest; +- node/edge/property counts, degree distribution, labels and skew; +- query corpus, parameters, selectivity, result size and concurrency; +- backend/profile, storage/device/provider/region and machine; +- cold/warm/hot cache procedure; +- memory, spill, CPU, request and byte budgets; +- repetitions, warmup, percentile/confidence method, failures and timeouts. + +Results report throughput and latency distributions, not only the best or mean. Regressions compare like-for-like artifacts. An estimate derived from cache-hit assumptions or provider price tables is labeled a model, not a measurement. + +## Release SLO classes + +Initial SLOs are qualification templates; numeric thresholds are set only after representative baselines: + +| Class | Required measures | +|---|---| +| local point/adjacency | p50/p95/p99 latency, bytes/pages decoded, cache state | +| local analytical scan | rows/s, compressed/decoded bytes/s, CPU, peak memory | +| write/commit | p50/p99 by durability level, group size, WAL bytes, sync time | +| recovery/open | clean open fixed work; crash replay versus WAL bytes/transactions | +| SQLite | latency/throughput, statement count, busy time, native pushdown fraction | +| object cold/warm | p50/p95/p99, GET/HEAD count, provider/cache bytes and total cost | +| path/skew | explored states, peak frontier, spills, deadline/cap termination | + +Qualification includes overload. A service meets its SLO only if admitted requests do; rejection/throttling rates and queue time are reported alongside latency. + +## Cost model + +Remote estimated cost for an operation is: + +```text +request_count_by_class × request_price ++ storage_byte_time × storage_price ++ retrieved_bytes × retrieval_price ++ egress_bytes × egress_price ++ cache_volume/IO cost ++ compute_time × compute price +``` + +Price tables are versioned by provider, region, storage class, and effective date. The model includes retries and compaction/GC write amplification. “Storage cost” and “total query cost” are not interchangeable. + +Local cost reports device bytes, write amplification, CPU, peak resident memory, and spill. The optimizer's cost units need not be monetary but must be calibratable to measured components. + +## Correctness qualification + +Release gates include: + +- parser/binder golden diagnostics and language conformance corpus; +- randomized differential results across reference, zu1, and SQLite; +- bag multiplicity, stable edge IDs, parallel edges, self-loops, nulls, and path modes; +- snapshot/MVCC histories generated against a small executable state-machine model; +- deterministic crash/fault simulation at every persistence transition; +- encoding, file, WAL, manifest and network-input fuzzing; +- full verification after randomized update/checkpoint/compaction/reopen cycles; +- upgrade/downgrade golden artifacts for each supported format/API version; +- sanitizer and concurrency-model checks for unsafe/lifetime/publication code. + +A correctness failure blocks performance release. Expected files and known issues are versioned, narrow, and expire; a blanket flaky-test retry is not acceptance. + +## Availability and degradation + +Health reports components separately: read path, writer lease, WAL, root publication, cache, maintenance debt, and provider access. Modes are explicit: + +- `Ready`: full advertised capabilities; +- `ReadOnlyDegraded`: snapshots readable, new commits disabled; +- `Fenced`: this process cannot write; reads may continue; +- `RecoveryRequired`: operator action or full recovery needed; +- `Corrupt`: integrity failure; writes disabled and evidence preserved; +- `BudgetThrottled`: healthy but admission-limited. + +The system does not turn a checksum failure into a cache miss unless the corrupt object is an independently disposable cache copy and a verified authoritative refetch succeeds. Authoritative corruption is sticky and surfaced. + +## Threat model + +Consider: + +- malicious query text/parameters and oversized values; +- malformed or adversarial database, WAL, manifest and encoded bytes; +- compromised/incorrect object provider responses and stale data; +- credential leakage through errors, logs, profiles or paths; +- untrusted extensions/functions; +- tenant resource exhaustion; +- local attacker able to read temp/cache files where deployment does not isolate them. + +Not initially defended: an attacker with arbitrary code execution as the database OS user; denial of service through unlimited authorized result data when administrators disable budgets; cryptographic authenticity of local files unless signing/encryption is enabled. + +## Security requirements + +- all byte decoders are bounded, checked, fuzzed, and avoid allocation before validation; +- unsafe code is isolated, justified by invariants, and covered by Miri/sanitizers where applicable; +- SQL lowering is parameterized and generated identifiers derive from checked stable IDs; +- object credentials/tokens are resolved at runtime, redacted, and never persisted in catalog/plan; +- cache/spill directories use restrictive permissions; symlink/path traversal is rejected; +- remote transport verifies TLS by default; insecure modes are explicit test-only flags; +- encryption metadata is authenticated; checksum is not presented as authentication; +- plugins/native extensions are off by default for untrusted inputs; +- dependency advisories, licenses, lockfile integrity and supply-chain provenance are CI gates. + +Because `zu-cli` is an application and file compatibility depends on exact codecs, the repository should track `Cargo.lock`. Reproducible release builds pin the Rust toolchain and emit an SBOM and checksums. + +## Operator workflows + +### Open and inspect + +`zu inspect ` performs bounded, read-only anchor/catalog validation. It reports format/runtime requirements, lineage/root, clean/dirty state, WAL replay work, encryption key IDs, and detected capabilities. It does not mutate recovery state unless `--recover` is explicit. + +### Verify and repair + +Verification levels are anchor, metadata, index/table, full content, and cross-index semantic invariants. Output is machine-readable and identifies roots/objects/ranges and whether a verified redundant copy exists. + +Repair always creates a new root/database and a report. Destructive salvage requires an explicit destination and never overwrites the sole evidence. Object-store repair does not delete old objects. + +### Backup/restore + +Backups are pinned-snapshot manifests with end-to-end digests. Restore is tested regularly, not inferred from upload success. Operational targets include recovery point/time objectives with workload and data size. + +### Maintenance + +Checkpoint, compaction, analyze, index build, re-encoding, backup, verify, and GC expose progress and resource usage. They are cancellable before publication; after publication begins, cancellation completes or safely reconciles that transition. Jobs resume from verified artifacts after restart. + +## Compatibility policy + +Three versions are independent: + +- public API/CLI behavior; +- logical catalog and query semantics; +- physical file/WAL/object format. + +The compatibility matrix states readable/writable ranges and migration path. Readers never silently write upgrades. Unknown required features fail with a diagnostic naming the minimum runtime. Once a stable format is declared, at least one previous major reader and export path remain available under the published support window. + +## Operational game days + +Before GA and periodically afterward, exercise: + +- process/host loss during commits and checkpoint; +- device full/read-only/short I/O and WAL corruption; +- object-store throttling, stale/failed reads, lost CAS response and regional outage; +- lease-service loss, expiry, clock skew and stale writer; +- cache loss/corruption with remote-only restore; +- accidental schema change, bad rollout and binary downgrade; +- runaway scan/path query and spill exhaustion; +- GC racing a reader, backup and publication. + +Each drill records detection time, allowed state, operator commands, evidence retained, recovery time, data-loss result, and follow-up test. Runbooks link to exact error codes and do not depend on tribal knowledge. diff --git a/docs/14-roadmap-and-verification.md b/docs/14-roadmap-and-verification.md new file mode 100644 index 0000000..0543cf8 --- /dev/null +++ b/docs/14-roadmap-and-verification.md @@ -0,0 +1,211 @@ +# Migration and verification roadmap + +## Delivery principle + +Build a vertical, semantically complete local slice before expanding remote scale. The current prototypes remain valuable as test inputs, but no new backend feature should deepen the direct `zu-query -> zu-zu1` dependency or the empty `zu-storage` abstraction. + +Each phase ends in an executable gate. Feature flags mark incomplete work as experimental; documentation never describes later phases as current behavior. + +## Phase 0 — freeze claims and preserve evidence + +Deliverables: + +- classify existing docs and benchmarks as implemented, experimental, target, or model; +- capture golden zu1 files, queries, and current benchmark artifacts at baseline commit; +- add CI for all workspace features, release-mode tests, formatting/lints, dependency audit, and tracked lockfile; +- make current unchecked ID constructors checked and add release-boundary tests; +- document that DML, unified transactions, true S3 persistence, and multi-edge trail correctness are not released. + +Exit gate: baseline behavior is reproducible; misleading claims are removed; known format inputs can be read or deliberately rejected by future work. + +## Phase 1 — semantic foundation and real SPI + +Deliverables: + +- stable `NodeId`, `EdgeId`, table/column/catalog IDs and versioned types; +- immutable `CatalogSnapshot`, capability descriptors, `SnapshotToken` and pin registry; +- `StorageEngine`/reader/source/mutation interfaces from document 05; +- canonical `DataBatch`/`AdjacencyBatch` ownership and budget guards; +- in-memory reference engine implementing the whole semantic contract; +- common storage conformance suite. + +Exit gate: the query interpreter runs only through the new SPI and passes generated multi-edge/snapshot tests. Empty placeholder types and the executor's legacy `Graph` trait have a dated removal plan. + +## Phase 2 — query migration + +Deliverables: + +- separate bound logical and physical IRs; +- stable edge identity in values, equality, property lookup, and path visited state; +- batch source/adjacency operators, backpressure, cancellation and memory accounting; +- typed pushdown classification and capability validation; +- reference differential harness and optimizer rewrite tests; +- public `Database`, `Connection`, read transaction, prepared query, and result-stream APIs. + +Exit gate: all supported read queries match the reference engine on deterministic generated corpora; no query crate imports an engine crate; cancellation leaks zero pins/reservations in fault tests. + +## Phase 3 — local transaction vertical slice + +Deliverables: + +- logical mutation batches and write transaction API; +- node/edge insert/update/delete plus constraints and both adjacency directions; +- framed WAL, commit state machine, immediately visible committed overlay; +- deterministic recovery simulator and fault injection; +- checkpoint to an immutable root and safe snapshot-based reclamation. + +Exit gate: acknowledged local commits survive every injected crash; unacknowledged commits resolve only to documented old/new outcomes; queries see committed deltas before checkpoint; parallel edges survive recovery and checkpoint. + +## Phase 4 — zu1 pre-freeze redesign + +Deliverables: + +- bounded anchor/open and copy-on-write root publication; +- per-consumed-chunk integrity and full verifier; +- stable-ID indexes and tiled bidirectional adjacency; +- encoding trees and compute capability metadata; +- shared buffer manager/positioned I/O and cheap reader cloning; +- partial partition/group checkpoint and measured reclamation. + +Exit gate: format fuzz/crash/golden tests pass, corrupt point-read chunks fail closed, clean open performs bounded I/O, and benchmark artifacts demonstrate no unacceptable regression. Only then assign a stable format epoch. + +## Phase 5 — SQLite parity + +Deliverables: + +- full SPI implementation with bounded connection pool; +- schema/ID/edge model and transactional DML; +- snapshot capability stated exactly; +- batched adjacency and typed native pushdown; +- backup/migration/reconcile and error mapping. + +Exit gate: common conformance plus randomized cross-engine differential tests pass; native pushdown on/off produces identical results; configured durability has crash-test evidence. + +## Phase 6 — runtime hardening and optimizer + +Deliverables: + +- global/query/operator resource hierarchy, spill and fair scheduler; +- vector kernels over selected encodings and explicit materialization; +- robust degree/statistics ranges and backend-aware multi-dimensional costing; +- binary/multiway join choices, bitmap/semijoin reduction, adaptive factorization; +- bounded variable-length path execution and full observability. + +Exit gate: adversarial overload remains within memory/I/O bounds, plan differential tests pass, estimated versus actual telemetry is recorded, and representative local/SQLite SLO templates have thresholds. + +## Phase 7 — object-single + +Deliverables: + +- provider capability qualification and immutable pack/range reader; +- content-addressed disk/memory cache with scan admission; +- externally fenced writer epochs and manifest/WAL commit/reconcile; +- request/byte/cost-aware planning and admission; +- backup/restore, retention pins and quarantined mark/sweep GC. + +Exit gate: stale writers cannot acknowledge, ambiguous commits reconcile, GC never removes live data under deterministic races, empty-cache restore succeeds, and cold/warm request-count/SLO gates pass. Until then `zu-s3` remains a manifest experiment, not a remote database engine. + +## Phase 8 — partitioned datasets + +Deliverables: + +- stable partition map/version and routing; +- explicit edge co-location/projection rule preserving directional consistency; +- partition-local transactions and query fan-out budgets; +- resharding job with dual-read/publication state machine; +- clear rejection or saga semantics for cross-partition mutation. + +Exit gate: partition movement, stale maps, partial outage, and high-degree exceptions pass model/fault tests. No distributed ACID claim is permitted without a separate transactional control-plane project. + +## Dependency graph + +```text +identity/catalog -> storage SPI -> query migration + | | + v v + local txn/WAL -> runtime/optimizer + | | + v +--> SQLite parity + zu1 pre-freeze | + +--------------+--> object-single -> partitioned +``` + +Object-store work may prototype packs in parallel, but cannot become the authoritative write path before transaction identity, fencing, snapshot pins, and budgets exist. + +## Compatibility and rollout + +Use side-by-side readers and explicit conversion: + +1. retain the baseline reader as `zu1-experimental-0`; +2. implement new semantic exports from old readable files; +3. write new-format output to a separate destination; +4. verify counts, IDs where representable, properties and query corpus; +5. atomically select the new database only after validation; +6. retain source according to rollback policy. + +The old relationship representation cannot always reconstruct distinct edge identity if input already collapsed parallel edges. Migration reports this as data loss/ambiguity and requires user policy; it must not invent equivalence silently. + +## Verification pyramid + +### Per change + +- unit/property tests and parser/format golden cases; +- common conformance subset; +- format/lint and unsafe review; +- deterministic seed recorded on failure. + +### Per merge + +- all features in debug and release; +- randomized differential engine/query histories; +- crash points touched by persistence changes; +- resource leak/bound tests touched by runtime changes; +- benchmark smoke tests with request-count assertions. + +### Nightly + +- long fuzz campaigns for parsers, codecs, file/WAL/manifest readers; +- thousands of model-based MVCC/recovery histories; +- optimizer query generation and cross-engine differential runs; +- concurrency sanitizers/model checking subsets; +- provider fault proxy and GC/publication races. + +### Release + +- supported-version golden matrix and upgrade/restore rehearsal; +- full integrity scan after stress/update/compaction; +- security/advisory/license/SBOM gates; +- workload-specific SLO and cost report, including overload and cold cache; +- signed artifacts/checksums and operator runbooks. + +## Traceability matrix + +Every normative requirement gets an ID in implementation issues and tests: + +| Prefix | Area | Example evidence | +|---|---|---| +| `ID-*` | element/schema identity | parallel-edge compaction test | +| `SNAP-*` | MVCC/snapshots | generated history model | +| `DUR-*` | WAL/commit/recovery | crash-point matrix | +| `FMT-*` | format/integrity | corrupt point-read corpus | +| `QRY-*` | language/optimizer | reference differential seed | +| `RES-*` | resources/runtime | peak reservation assertion | +| `OBJ-*` | remote/fencing/GC | stale writer simulator | +| `OPS-*` | backup/security/upgrade | restore/game-day artifact | + +A release checklist links requirement, code, test, and evidence artifact. A test count alone is not traceability. + +## First ten implementation changes + +1. Add checked stable `EdgeId` and use it in executor relationship values/visited sets. +2. Define canonical catalog/snapshot/batch types in dependency-leaf crates. +3. Replace empty `zu-storage` payloads with the read-only SPI and in-memory adapter. +4. Move the current zu1 query adapter behind `SnapshotReader`. +5. Add common multi-edge/self-loop/snapshot tests and a reference interpreter. +6. Introduce public database/connection/read-transaction APIs with engine features. +7. Route current zu1 WAL overlay through snapshot reads. +8. Specify/implement framed WAL and deterministic crash harness before more DML. +9. Add per-chunk checksums and bounded root/open metadata in a pre-freeze format epoch. +10. Implement SQLite through the same SPI and use it as a differential oracle. + +These are ordered to remove semantic and dependency risk before optimizing storage or promising remote scale. diff --git a/docs/15-research-sources.md b/docs/15-research-sources.md new file mode 100644 index 0000000..60db874 --- /dev/null +++ b/docs/15-research-sources.md @@ -0,0 +1,169 @@ +# 2026 research and system evidence + +Research cut: 2026-08-08. Sources are primary papers or official project/provider documentation. They motivate design choices; they do not prove zu implements a result or will reproduce another system's performance. + +## Graph storage and execution + +### Kùzu / factorized graph processing + +- Source: [Kùzu Graph Database Management System, CIDR 2023](https://www.vldb.org/cidrdb/2023/kuzu-graph-database-management-system.html) +- Evidence: a modern embedded graph DBMS combines columnar storage, CSR-style adjacency, factorized/vectorized processing, and graph-aware optimization rather than treating graph access as only repeated key/value neighbor calls. +- Constraint on zu: preserve adjacency structure and factorization metadata across the storage/runtime boundary; do not expose only per-node iterators. +- Caveat: Kùzu/Ladybug's implementation and workload results are not zu targets without equivalent experiments. + +### Current Ladybug baseline + +- Sources: [Ladybug documentation](https://docs.ladybugdb.com/), [database internals](https://docs.ladybugdb.com/developer-guide/database-internal), [relationship table DDL](https://docs.ladybugdb.com/cypher/data-definition/create-table/), [Icebug import](https://docs.ladybugdb.com/import/icebug/) +- Evidence as observed by the research cut: the actively documented successor to Kùzu presents embedded columnar/CSR and vectorized/factorized execution; relationship rows have identifiers supporting multiple relationships between endpoints; Icebug describes graph-aware access over remote Parquet-style data. +- Constraint on zu: claims that competitors lack these capabilities are stale. Stable relationship identity and graph-aware remote layout are baseline design concerns, not optional polish. +- Caveat: official product documentation is evidence of documented behavior, not an independent benchmark. + +### Robust recursive execution + +- Source: [Robust Recursive Query Parallelism, PVLDB 2025](https://www.vldb.org/pvldb/vol18/p4465-chakraborty.pdf) +- Evidence: recursive graph workloads are skewed and difficult to estimate; scheduling can be designed to remain robust when the initial recursive plan or partitioning is imperfect. +- Constraint on zu: variable-length traversal needs resumable morsels, frontier budgets and adaptive work redistribution. Correctness and resource limits cannot depend on a precise single cardinality estimate. + +### Relational graph representations + +- Source: [Raqlet, CIDR 2026](https://www.vldb.org/cidrdb/papers/2026/p7-shaikhha.pdf) +- Evidence: recent work continues exploring graph representations and graph operations through relational/array abstractions rather than a hard separation between a graph runtime and columnar execution. +- Constraint on zu: retain typed batch algebra and permit graph operations to lower into general vector/relational machinery; do not bake zu1 pointers into graph values. + +### Graph analytics over relational systems + +- Source: [GraphAlg, 2026 preprint](https://arxiv.org/abs/2601.06705) +- Evidence: graph-algorithm integration with relational processing remains an active 2026 topic. +- Constraint on zu: treat future algorithms as bounded physical operators over snapshots/batches with explicit frontier state, not as a second storage API. The preprint status means it is directional evidence, not a release dependency. + +### Dynamic graph storage + +- Sources: [LSMGraph, 2024 preprint](https://arxiv.org/abs/2411.06392), [An Experimental Study of Dynamic Graph Storage, 2025 preprint](https://arxiv.org/abs/2502.10959) +- Evidence: dynamic graph layout is a multidimensional trade-off across updates, locality, amplification, degree skew, and concurrency; there is no basis for assuming fixed CSR slack alone solves update behavior. +- Constraint on zu: keep sealed dense adjacency plus visible deltas, measure amplification, and make checkpoint scope explicit. Evaluate alternatives on zu workloads before selecting a more complex dynamic structure. + +## Encodings and columnar layout + +### Structural encodings + +- Source: [Lance: Efficient Random Access in Columnar Storage through Adaptive Structural Encodings, 2025](https://arxiv.org/abs/2504.15247) +- Evidence: encoding can be modeled compositionally and selected for both compression and access behavior, rather than as a single terminal codec per column. +- Constraint on zu: represent arrays as bounded encoding trees with kernel capabilities, and include point/gather/filter cost in selection. The exact Lance layout is not copied automatically. + +### FastLanes + +- Sources: [The FastLanes Compression Layout, PVLDB 2023](https://www.vldb.org/pvldb/vol16/p2132-afroozeh.pdf), [FastLanes File Format, PVLDB 2025](https://vldb.org/pvldb/vol18/p4629-afroozeh.pdf) +- Evidence: vector-sized, layout-aware compression primitives can improve portability and decode/compute behavior; the later file-format work illustrates composing those ideas into self-describing storage. +- Constraint on zu: benchmark portable vector primitives, preserve an explicit format version, and qualify decode-on-query kernels. Hardware-specific fast paths need a correct scalar fallback. + +### Vortex + +- Sources: [Vortex layouts](https://docs.vortex.dev/concepts/layouts), [scan API](https://docs.vortex.dev/concepts/scanning), [architecture](https://docs.vortex.dev/developer-guide/internals/architecture) +- Evidence: current official design separates logical arrays/encodings, physical layouts, and scan orchestration; scan requests support projection/filter while layouts produce executable splits and pruning. +- Constraint on zu: use a typed scan request, independent splits and an exact/pruning-only pushdown report. Separate canonical semantic batches from backend layout. +- Caveat: these pages describe an evolving project. zu must pin any dependency/API version and maintain its own compatibility layer. + +## Joins, factorization, and cardinality + +### Binary and worst-case-optimal convergence + +- Source: [Unifying Binary and Worst-Case Optimal Joins, 2025 preprint](https://arxiv.org/abs/2505.19918) +- Evidence: current research explores a continuum/shared execution mechanisms rather than an absolute choice between binary and worst-case-optimal joins. +- Constraint on zu: optimizer IR should express ordered intersections/multiway plans without requiring a separate executor universe; choose per subproblem and measured distribution. + +### Conservative cardinality bounds + +- Sources: [Pessimistic Cardinality Estimation, 2024 preprint](https://arxiv.org/abs/2412.00642), [LpBound, 2025 preprint](https://arxiv.org/abs/2502.05912), [Degree-Based Cardinality Estimation: An Ambidextrous Perspective, 2025 preprint](https://arxiv.org/abs/2510.04249) +- Evidence: pessimistic and degree-based bounds can protect against severe underestimation for joins/graph patterns, complementing expected-value estimates. +- Constraint on zu: return estimate ranges/confidence; use conservative bounds for admission and catastrophic memory/request decisions. Do not market a bound technique as universally tight. + +### Learned/feedback estimation + +- Source: [COLOR: a Learned Cardinality Estimator, PVLDB 2025](https://www.vldb.org/pvldb/vol18/p130-deeds.pdf) +- Evidence: learned/representation-based estimation continues to improve, but introduces model lifecycle, training and generalization concerns. +- Constraint on zu: retain a pluggable estimator interface and runtime feedback. A learned estimator is post-v1 and may never be the sole guard for hard resource limits. + +### Adaptive factorization and semijoin filtering + +- Sources: [Adaptive Factorization Using Linear Chained Hash Tables, CIDR 2025](https://www.vldb.org/cidrdb/2025/adaptive-factorization-using-linear-chained-hash-tables.html), [I Can't Believe It's Not Yannakakis: Pragmatic Bitmap Filters in Microsoft SQL Server, CIDR 2026](https://www.vldb.org/cidrdb/2026/i-cant-believe-its-not-yannakakis-pragmatic-bitmap-filters-in-microsoft-sql-server.html) +- Evidence: factorization choices can adapt at runtime, and practical bitmap/semijoin reductions can bring classic acyclic-join ideas into production engines. +- Constraint on zu: carry factorization metadata, allow adaptive materialization at safe boundaries, and cost bitmap reduction before broad edge/property scans. + +## Buffer management and execution plumbing + +### SIEVE cache policy + +- Sources: [SIEVE project page, NSDI 2024](https://www.usenix.org/conference/nsdi24/presentation/zhang-yazhuo), [paper PDF](https://www.usenix.org/system/files/nsdi24-zhang-yazhuo.pdf) +- Evidence: SIEVE offers a simple, scalable eviction approach with strong reported results, but the paper explicitly does not make it inherently scan-resistant. +- Constraint on zu: SIEVE is a candidate eviction policy only. Protect metadata and handle one-pass scans with admission/bypass; never infer scan resistance from the algorithm name. + +### SSD-conscious buffer managers + +- Sources: [How to Write to SSDs, or ZLeanStore, PVLDB 2026](https://www.vldb.org/pvldb/vol19/p1469-lee.pdf), [Predictive Translation, 2026](https://db.in.tum.de/~zinsmeister/papers/predictive-translation.pdf) +- Evidence: storage-device behavior, translation, and asynchronous/batched access continue to affect buffer-manager design on modern SSDs. +- Constraint on zu: keep I/O backend and cache policy pluggable, record physical I/O amplification, and qualify direct/async paths. Do not hard-wire a research algorithm before representative hardware tests. + +### DuckDB execution and storage comparison + +- Sources: [DuckDB storage internals](https://duckdb.org/docs/stable/internals/storage), [analytics-optimized concurrent transactions](https://duckdb.org/2024/10/30/analytics-optimized-concurrent-transactions), [test-driving Lance, 2026](https://duckdb.org/2026/05/21/test-driving-lance) +- Evidence: an embedded analytical system can combine compressed columnar storage and MVCC with explicit concurrency trade-offs; the 2026 Lance work is further evidence that external columnar formats require workload-driven integration testing. +- Constraint on zu: distinguish transactional deltas from immutable analytical layout and test format/kernel integration end-to-end. DuckDB's concurrency/format details are comparators, not drop-in semantics. + +### Acero + +- Source: [Apache Arrow Acero user guide](https://arrow.apache.org/docs/cpp/acero/user_guide.html) +- Evidence: production vector execution exposes push-based/backpressured execution concerns, schemas, batches, and bounded pipelines. +- Constraint on zu: make demand, cancellation and batch ownership first-class. zu need not adopt Arrow as its internal ABI, but interoperability should preserve typed batch semantics. + +## Object storage and remote durability + +### Rust object_store abstraction + +- Sources: [`object_store` crate documentation](https://docs.rs/object_store/latest/object_store/), [`ObjectStore` trait](https://docs.rs/object_store/latest/object_store/trait.ObjectStore.html) +- Evidence: the Rust ecosystem exposes an asynchronous multi-provider object API including range operations and conditional/multipart capabilities. +- Constraint on zu: isolate provider details behind an adapter, pin tested versions/features, and negotiate actual conditional semantics. A common trait does not make provider guarantees identical. + +### S3 consistency and conditional operations + +- Sources: [Amazon S3 user guide](https://docs.aws.amazon.com/AmazonS3/latest/userguide/Welcome.html), [conditional requests](https://docs.aws.amazon.com/AmazonS3/latest/userguide/conditional-requests.html) +- Evidence: S3 documents strong read-after-write consistency for individual object operations and supports conditional requests. Those guarantees are object/key scoped; they do not provide a multi-object database transaction or writer lease. +- Constraint on zu: publish one partition through one conditional root pointer after immutable uploads, and supply separate fencing. Do not derive cross-key atomicity from strong consistency. + +### SlateDB + +- Sources: [SlateDB file design](https://slatedb.io/docs/design/files/), [manifest fencing RFC](https://slatedb.io/rfcs/0001-manifest/) +- Evidence: a serious object-store database separates immutable WAL/SST/manifest objects, and its manifest design must coordinate writer/compactor epochs and WAL positions. +- Constraint on zu: a manifest containing only `epoch`, `writer_id`, and segment strings is insufficient. Publication/recovery need WAL high-water marks, epoch lineage, immutable references, reconcile, and GC roots. + +### Turbopuffer + +- Source: [Turbopuffer architecture](https://turbopuffer.com/docs/architecture) +- Evidence: the official architecture describes object storage as authoritative, WAL batching, caching, and an object-friendly coarse vector index; its published example shows a large cold-versus-warm latency difference (874 ms versus 14 ms p50 at the time observed). +- Constraint on zu: batch durable writes, design request-efficient coarse/tiled structures, and publish separate cold/warm results. The values are that system's documented example, not zu targets and not guaranteed current beyond the research cut. + +## Standards and product landscape + +### ISO GQL + +- Source: [ISO/IEC 39075:2024 — GQL](https://www.iso.org/standard/76120.html?browse=tc) +- Evidence: graph query language now has an international standard baseline. +- Constraint on zu: document its language as a precise subset/dialect, keep semantic IR concepts such as graph element identity and path modes explicit, and use stable unsupported-feature diagnostics. Full GQL conformance is not a v1 assumption. + +### Spanner Graph + +- Source: [Google Cloud Spanner Graph](https://cloud.google.com/products/spanner/graph?e=48754805) +- Evidence: current managed systems combine graph and relational models over transactional infrastructure. +- Constraint on zu: avoid claiming that one physical graph layout is necessary for every backend; share graph semantics while allowing relational lowering. This does not change zu's embedded/read-mostly scope. + +## Synthesis: what this evidence changes + +The sources support six architectural conclusions: + +1. **Identity and semantics first.** Current graph systems and the GQL landscape make distinct edge identity, path semantics, and typed catalogs non-negotiable. +2. **Batched structural interfaces.** Graph-native adjacency, columnar batches, factorization and multiway joins all require more structure than `neighbors(node) -> Vec`. +3. **Immutable base plus explicit transactional delta.** Analytical encodings and update/recovery concerns have different optimal forms; the API must merge them at one snapshot. +4. **Encoding is a tree with compute capabilities.** Recent format work argues against representing compression as a single opaque codec chosen only by byte size. +5. **Bounds matter more remotely.** Cardinality ranges, request-aware planning, backpressure and admission are correctness/operability mechanisms, not later tuning. +6. **Object CAS is publication, not a database protocol.** Immutable objects and a conditional root are useful primitives, but fencing, WAL position, ambiguity, pins and GC complete the protocol. + +None of these sources justifies a zu performance claim without the qualification framework in document 13. Research features enter the roadmap only with a correctness fallback, reproducible workload, resource envelope, and evidence artifact. diff --git a/docs/README.md b/docs/README.md index 6c8a434..cd49530 100644 --- a/docs/README.md +++ b/docs/README.md @@ -3,3 +3,9 @@ This directory contains the source-audited graph database specifications. Cross-engine architecture and benchmark documents live at this level; engine research and dedicated deep-audit dossiers live under `research/`. + +- [Architecture and product specification](./00-index.md) +- [Graph database research corpus](./research/000-index.md) +- [Target graph architecture](./research/system-target-architecture.md) +- [Benchmark and 10x claim protocol](./research/system-benchmark-and-10x-claim.md) +- [Landscape scorecard](./research/system-landscape-scorecard.md) diff --git a/docs/research/000-index.md b/docs/research/000-index.md new file mode 100644 index 0000000..bab5820 --- /dev/null +++ b/docs/research/000-index.md @@ -0,0 +1,520 @@ +# 2026 graph database research corpus + +Research cut: `2026-08-08` +Minimum generated length: 520 lines per Markdown file +Purpose: evidence base for zu's low-latency, low-resource, distributed, S3-authoritative, fixed-cost, PB-scale design. + +## Scope rule + +The word `all` is operationalized as all engines with material 2026 adoption, benchmark relevance, architectural novelty, standards relevance, or historical baseline value found during the survey. It is not a claim that every private, abandoned, academic prototype, or graph API over a general database is included. + +Every engine receives one file. Kuzu and RedisGraph remain separate historical files because benchmark reports still cite them, while LadybugDB and FalkorDB receive active successor files. Managed analytical services that are separate engines, such as Neptune Analytics, receive separate files. + +## Reading order + +1. Read `system-target-architecture.md` for the proposed design. +2. Read `system-benchmark-and-10x-claim.md` before using any performance statement. +3. Read `system-landscape-scorecard.md` for cross-engine classification. +4. Use the engine files for evidence, risks, and exact qualification work. + +## Engine files + +- [Neo4j](./engine-neo4j.md) — native property graph; active; calendar-versioned 2026 line. +- [FalkorDB](./engine-falkordb.md) — matrix property graph; active; Rust transition and Redis-module lineage. +- [LadybugDB](./engine-ladybugdb.md) — embedded analytical property graph; active successor fork in 2026. +- [Kuzu (archived)](./engine-kuzu.md) — embedded analytical property graph; archived 2025-10-10; historical baseline. +- [PuppyGraph](./engine-puppygraph.md) — lakehouse graph query engine; active commercial product. +- [Memgraph](./engine-memgraph.md) — in-memory operational property graph; active. +- [NebulaGraph](./engine-nebulagraph.md) — distributed property graph; active; Enterprise 5.2 was current in the 2025 review. +- [TigerGraph](./engine-tigergraph.md) — distributed native property graph; active; 4.2.4 released 2026-07-20. +- [GraphScope Flex Interactive](./engine-graphscope_flex.md) — distributed interactive graph system; active Apache-2.0 project. +- [JanusGraph](./engine-janusgraph.md) — storage-agnostic distributed graph layer; active 1.x. +- [Apache HugeGraph](./engine-apache_hugegraph.md) — pluggable OLTP plus OLAP graph platform; active Apache top-level project. +- [TuGraph](./engine-tugraph.md) — HTAP native property graph; active. +- [Ultipa Powerhouse](./engine-ultipa.md) — hybrid distributed and high-density graph system; active v5 line. +- [ArangoDB](./engine-arangodb.md) — native multi-model database; active. +- [Dgraph](./engine-dgraph.md) — distributed predicate-sharded graph database; active. +- [OrientDB](./engine-orientdb.md) — multi-model graph/document database; active 4.0 line but legacy architecture remains relevant. +- [ArcadeDB](./engine-arcadedb.md) — multi-model native graph database; active 26.x. +- [TypeDB](./engine-typedb.md) — typed polymorphic database; active 3.x; clustering was experimental/alpha in current docs. +- [TerminusDB](./engine-terminusdb.md) — version-controlled document graph database; active. +- [CozoDB](./engine-cozodb.md) — embedded relational-graph-vector database; maintenance activity appears limited after late 2024; verify before adoption. +- [SurrealDB](./engine-surrealdb.md) — distributed multi-model database; active 3.x. +- [HelixDB](./engine-helixdb.md) — Rust graph-vector database; active and fast-moving; 3.0.2 listed in May 2026. +- [MillenniumDB](./engine-millenniumdb.md) — research persistent graph database; active research project with small community. +- [DuckPGQ](./engine-duckpgq.md) — analytical SQL/PGQ extension; active CWI project. +- [Apache AGE](./engine-apache_age.md) — PostgreSQL graph extension; active Apache project. +- [AgensGraph](./engine-agensgraph.md) — PostgreSQL-derived multi-model graph database; active 2.17 documentation line. +- [Amazon Neptune Database](./engine-amazon_neptune.md) — managed cloud graph database; active AWS service. +- [Amazon Neptune Analytics](./engine-amazon_neptune_analytics.md) — managed in-memory graph analytics; active AWS service. +- [Google Cloud Spanner Graph](./engine-google_spanner_graph.md) — managed relational-property-graph database; active Enterprise/Enterprise Plus feature; docs updated 2026-07-22. +- [Azure Cosmos DB for Apache Gremlin](./engine-azure_cosmosdb_gremlin.md) — managed partitioned multi-model graph API; active. +- [Graph in Microsoft Fabric](./engine-microsoft_fabric_graph.md) — lakehouse graph analytics; active 2026 feature. +- [Oracle Database Property Graph](./engine-oracle_property_graph.md) — relational-integrated graph platform; active Oracle Database 26ai line. +- [SAP HANA Cloud Property Graph Engine](./engine-sap_hana_graph.md) — in-memory relational-integrated graph engine; active QRC 1/2026. +- [Stardog](./engine-stardog.md) — enterprise RDF knowledge graph platform; active 12.x-era platform. +- [Ontotext GraphDB](./engine-ontotext_graphdb.md) — RDF store and reasoner; active 11.x. +- [Apache Jena TDB2](./engine-apache_jena_tdb2.md) — embedded RDF store; active Apache project. +- [OpenLink Virtuoso](./engine-openlink_virtuoso.md) — multi-model SQL/RDF server; active commercial/open-source lineage. +- [Oxigraph](./engine-oxigraph.md) — embedded Rust RDF store; active and explicitly still optimizing. +- [AllegroGraph](./engine-allegrograph.md) — commercial RDF/knowledge graph database; active 9.x line. +- [Blazegraph (legacy)](./engine-blazegraph.md) — RDF graph database; archived repository; historical benchmark baseline. +- [RedisGraph (legacy)](./engine-redisgraph.md) — matrix property graph; end-of-life lineage continued by FalkorDB. +- [Aerospike Graph](./engine-aerospike_graph.md) — stateless Gremlin compute over distributed KV storage; active commercial product. +- [Huawei Cloud Graph Engine Service (GES)](./engine-huawei_ges.md) — managed distributed graph engine; active; GQL added in 2025 and docs refreshed in 2026. +- [DataStax Enterprise Graph](./engine-datastax_enterprise_graph.md) — Cassandra-integrated distributed graph; maintained DSE 6.9 documentation; legacy strategic baseline rather than a modern standalone graph focus. +- [IBM Db2 Graph](./engine-ibm_db2_graph.md) — Gremlin layer over Db2 relational data; legacy/limited: current IBM page says standalone support is tied to Db2 11.5.6–11.5.8. + +## Coverage classes + +### Native and embedded property graph + +Neo4j, FalkorDB, LadybugDB, Kuzu, Memgraph, TuGraph, and emerging HelixDB cover direct adjacency, low-latency serving, analytical factorization, sparse matrices, and Rust-native designs. + +### Distributed property graph + +NebulaGraph, TigerGraph, GraphScope Flex, JanusGraph, Apache HugeGraph, Ultipa, Dgraph, ArangoDB, and managed Neptune cover shared-nothing, replicated, predicate-sharded, locality-sharded, and shared-storage patterns. + +### Lakehouse and relational graph + +PuppyGraph, DuckPGQ, Apache AGE, AgensGraph, Spanner Graph, Fabric Graph, Oracle Property Graph, SAP HANA Graph, and Cosmos DB Gremlin cover graph-over-tables, materialized traversal projections, SQL/PGQ, and source-partition-aware APIs. + +### Semantic and RDF + +Stardog, GraphDB, Jena TDB2, Virtuoso, Oxigraph, AllegroGraph, Blazegraph, TerminusDB, TypeDB, and MillenniumDB cover RDF permutations, reasoning, Datalog, strong schemas, versioning, and path-query research. + +## Evidence hierarchy + +- Level 1: reproducible local source inspection and a pinned benchmark artifact. +- Level 2: official versioned documentation or a standards conformance declaration. +- Level 3: audited benchmark full-disclosure report. +- Level 4: peer-reviewed paper tied to a specific version/configuration. +- Level 5: vendor benchmark or capacity claim, explicitly labeled. +- Level 6: inference that creates a hypothesis, never a fact. + +## Global conclusions + +- No surveyed engine simultaneously proves local-class hot latency, tiny resource footprint, distributed transactional writes, S3-only authority, predictable fixed cost, PB capacity, and a tenfold win on every graph workload. +- The attainable product is a set of honest profiles sharing semantics: embedded/local, remote single-writer, and partitioned read-scale. A universal profile would conceal contradictions. +- S3 can be the durable authority, but low latency then comes from immutable IDs, coarse range-addressable tiles, batched frontier reads, and RAM/NVMe caches—not from remote pointer chasing. +- Fixed cost is an admission-control contract backed by bounded compute and remote I/O, not an emergent property of S3 pricing. +- PB scale is mostly a metadata, partitioning, compaction, GC, and skew problem after the per-edge byte budget is solved. +- A tenfold advantage must be a matrix of qualified wins. Some cells will target parity, lower memory, lower dollars, or unique capability instead of latency. + +## Known exclusions and why + +Graph processing frameworks without an online database contract, visualization products, pure vector databases, generic SQL databases without a maintained graph surface, and private internal engines without enough public evidence are not assigned engine files. They can still appear as architectural sources or benchmark references. + +## Maintenance protocol + +At every quarterly refresh: recheck product lifecycle, latest stable release, license, distribution capability, object-storage claims, GQL/SQL-PGQ support, audited results, and any public scale limit. A changed fact updates the engine file and the scorecard in one commit. + +## Appendix A. Release-gate assertions + +- RG-001: For the research inventory, release is blocked until the raw samples and aggregated chart agree. +- RG-002: For the research inventory, release is blocked until the query result matches the canonical oracle. +- RG-003: For the research inventory, release is blocked until the engine version and artifact digest are recorded. +- RG-004: For the research inventory, release is blocked until the selected durability level matches the comparison class. +- RG-005: For the research inventory, release is blocked until cache state is explicit and reproducible. +- RG-006: For the research inventory, release is blocked until peak memory includes engine and required sidecars. +- RG-007: For the research inventory, release is blocked until storage size includes indexes, logs, replicas, and temporary space. +- RG-008: For the research inventory, release is blocked until timeouts and rejected operations remain in the result set. +- RG-009: For the research inventory, release is blocked until remote requests and bytes are measured rather than estimated. +- RG-010: For the research inventory, release is blocked until background maintenance is either quiesced or reported. +- RG-011: For the research inventory, release is blocked until thread, NUMA, and CPU-affinity settings are captured. +- RG-012: For the research inventory, release is blocked until the dataset and update-stream digests are immutable. +- RG-013: For the research inventory, release is blocked until the query plan/profile is archived. +- RG-014: For the research inventory, release is blocked until unsupported features are not replaced by weaker semantics. +- RG-015: For the research inventory, release is blocked until a second operator can reproduce the run from a clean host. +- RG-016: For the research inventory, release is blocked until the raw samples and aggregated chart agree. +- RG-017: For the research inventory, release is blocked until the query result matches the canonical oracle. +- RG-018: For the research inventory, release is blocked until the engine version and artifact digest are recorded. +- RG-019: For the research inventory, release is blocked until the selected durability level matches the comparison class. +- RG-020: For the research inventory, release is blocked until cache state is explicit and reproducible. +- RG-021: For the research inventory, release is blocked until peak memory includes engine and required sidecars. +- RG-022: For the research inventory, release is blocked until storage size includes indexes, logs, replicas, and temporary space. +- RG-023: For the research inventory, release is blocked until timeouts and rejected operations remain in the result set. +- RG-024: For the research inventory, release is blocked until remote requests and bytes are measured rather than estimated. +- RG-025: For the research inventory, release is blocked until background maintenance is either quiesced or reported. +- RG-026: For the research inventory, release is blocked until thread, NUMA, and CPU-affinity settings are captured. +- RG-027: For the research inventory, release is blocked until the dataset and update-stream digests are immutable. +- RG-028: For the research inventory, release is blocked until the query plan/profile is archived. +- RG-029: For the research inventory, release is blocked until unsupported features are not replaced by weaker semantics. +- RG-030: For the research inventory, release is blocked until a second operator can reproduce the run from a clean host. +- RG-031: For the research inventory, release is blocked until the raw samples and aggregated chart agree. +- RG-032: For the research inventory, release is blocked until the query result matches the canonical oracle. +- RG-033: For the research inventory, release is blocked until the engine version and artifact digest are recorded. +- RG-034: For the research inventory, release is blocked until the selected durability level matches the comparison class. +- RG-035: For the research inventory, release is blocked until cache state is explicit and reproducible. +- RG-036: For the research inventory, release is blocked until peak memory includes engine and required sidecars. +- RG-037: For the research inventory, release is blocked until storage size includes indexes, logs, replicas, and temporary space. +- RG-038: For the research inventory, release is blocked until timeouts and rejected operations remain in the result set. +- RG-039: For the research inventory, release is blocked until remote requests and bytes are measured rather than estimated. +- RG-040: For the research inventory, release is blocked until background maintenance is either quiesced or reported. +- RG-041: For the research inventory, release is blocked until thread, NUMA, and CPU-affinity settings are captured. +- RG-042: For the research inventory, release is blocked until the dataset and update-stream digests are immutable. +- RG-043: For the research inventory, release is blocked until the query plan/profile is archived. +- RG-044: For the research inventory, release is blocked until unsupported features are not replaced by weaker semantics. +- RG-045: For the research inventory, release is blocked until a second operator can reproduce the run from a clean host. +- RG-046: For the research inventory, release is blocked until the raw samples and aggregated chart agree. +- RG-047: For the research inventory, release is blocked until the query result matches the canonical oracle. +- RG-048: For the research inventory, release is blocked until the engine version and artifact digest are recorded. +- RG-049: For the research inventory, release is blocked until the selected durability level matches the comparison class. +- RG-050: For the research inventory, release is blocked until cache state is explicit and reproducible. +- RG-051: For the research inventory, release is blocked until peak memory includes engine and required sidecars. +- RG-052: For the research inventory, release is blocked until storage size includes indexes, logs, replicas, and temporary space. +- RG-053: For the research inventory, release is blocked until timeouts and rejected operations remain in the result set. +- RG-054: For the research inventory, release is blocked until remote requests and bytes are measured rather than estimated. +- RG-055: For the research inventory, release is blocked until background maintenance is either quiesced or reported. +- RG-056: For the research inventory, release is blocked until thread, NUMA, and CPU-affinity settings are captured. +- RG-057: For the research inventory, release is blocked until the dataset and update-stream digests are immutable. +- RG-058: For the research inventory, release is blocked until the query plan/profile is archived. +- RG-059: For the research inventory, release is blocked until unsupported features are not replaced by weaker semantics. +- RG-060: For the research inventory, release is blocked until a second operator can reproduce the run from a clean host. +- RG-061: For the research inventory, release is blocked until the raw samples and aggregated chart agree. +- RG-062: For the research inventory, release is blocked until the query result matches the canonical oracle. +- RG-063: For the research inventory, release is blocked until the engine version and artifact digest are recorded. +- RG-064: For the research inventory, release is blocked until the selected durability level matches the comparison class. +- RG-065: For the research inventory, release is blocked until cache state is explicit and reproducible. +- RG-066: For the research inventory, release is blocked until peak memory includes engine and required sidecars. +- RG-067: For the research inventory, release is blocked until storage size includes indexes, logs, replicas, and temporary space. +- RG-068: For the research inventory, release is blocked until timeouts and rejected operations remain in the result set. +- RG-069: For the research inventory, release is blocked until remote requests and bytes are measured rather than estimated. +- RG-070: For the research inventory, release is blocked until background maintenance is either quiesced or reported. +- RG-071: For the research inventory, release is blocked until thread, NUMA, and CPU-affinity settings are captured. +- RG-072: For the research inventory, release is blocked until the dataset and update-stream digests are immutable. +- RG-073: For the research inventory, release is blocked until the query plan/profile is archived. +- RG-074: For the research inventory, release is blocked until unsupported features are not replaced by weaker semantics. +- RG-075: For the research inventory, release is blocked until a second operator can reproduce the run from a clean host. +- RG-076: For the research inventory, release is blocked until the raw samples and aggregated chart agree. +- RG-077: For the research inventory, release is blocked until the query result matches the canonical oracle. +- RG-078: For the research inventory, release is blocked until the engine version and artifact digest are recorded. +- RG-079: For the research inventory, release is blocked until the selected durability level matches the comparison class. +- RG-080: For the research inventory, release is blocked until cache state is explicit and reproducible. +- RG-081: For the research inventory, release is blocked until peak memory includes engine and required sidecars. +- RG-082: For the research inventory, release is blocked until storage size includes indexes, logs, replicas, and temporary space. +- RG-083: For the research inventory, release is blocked until timeouts and rejected operations remain in the result set. +- RG-084: For the research inventory, release is blocked until remote requests and bytes are measured rather than estimated. +- RG-085: For the research inventory, release is blocked until background maintenance is either quiesced or reported. +- RG-086: For the research inventory, release is blocked until thread, NUMA, and CPU-affinity settings are captured. +- RG-087: For the research inventory, release is blocked until the dataset and update-stream digests are immutable. +- RG-088: For the research inventory, release is blocked until the query plan/profile is archived. +- RG-089: For the research inventory, release is blocked until unsupported features are not replaced by weaker semantics. +- RG-090: For the research inventory, release is blocked until a second operator can reproduce the run from a clean host. +- RG-091: For the research inventory, release is blocked until the raw samples and aggregated chart agree. +- RG-092: For the research inventory, release is blocked until the query result matches the canonical oracle. +- RG-093: For the research inventory, release is blocked until the engine version and artifact digest are recorded. +- RG-094: For the research inventory, release is blocked until the selected durability level matches the comparison class. +- RG-095: For the research inventory, release is blocked until cache state is explicit and reproducible. +- RG-096: For the research inventory, release is blocked until peak memory includes engine and required sidecars. +- RG-097: For the research inventory, release is blocked until storage size includes indexes, logs, replicas, and temporary space. +- RG-098: For the research inventory, release is blocked until timeouts and rejected operations remain in the result set. +- RG-099: For the research inventory, release is blocked until remote requests and bytes are measured rather than estimated. +- RG-100: For the research inventory, release is blocked until background maintenance is either quiesced or reported. +- RG-101: For the research inventory, release is blocked until thread, NUMA, and CPU-affinity settings are captured. +- RG-102: For the research inventory, release is blocked until the dataset and update-stream digests are immutable. +- RG-103: For the research inventory, release is blocked until the query plan/profile is archived. +- RG-104: For the research inventory, release is blocked until unsupported features are not replaced by weaker semantics. +- RG-105: For the research inventory, release is blocked until a second operator can reproduce the run from a clean host. +- RG-106: For the research inventory, release is blocked until the raw samples and aggregated chart agree. +- RG-107: For the research inventory, release is blocked until the query result matches the canonical oracle. +- RG-108: For the research inventory, release is blocked until the engine version and artifact digest are recorded. +- RG-109: For the research inventory, release is blocked until the selected durability level matches the comparison class. +- RG-110: For the research inventory, release is blocked until cache state is explicit and reproducible. +- RG-111: For the research inventory, release is blocked until peak memory includes engine and required sidecars. +- RG-112: For the research inventory, release is blocked until storage size includes indexes, logs, replicas, and temporary space. +- RG-113: For the research inventory, release is blocked until timeouts and rejected operations remain in the result set. +- RG-114: For the research inventory, release is blocked until remote requests and bytes are measured rather than estimated. +- RG-115: For the research inventory, release is blocked until background maintenance is either quiesced or reported. +- RG-116: For the research inventory, release is blocked until thread, NUMA, and CPU-affinity settings are captured. +- RG-117: For the research inventory, release is blocked until the dataset and update-stream digests are immutable. +- RG-118: For the research inventory, release is blocked until the query plan/profile is archived. +- RG-119: For the research inventory, release is blocked until unsupported features are not replaced by weaker semantics. +- RG-120: For the research inventory, release is blocked until a second operator can reproduce the run from a clean host. +- RG-121: For the research inventory, release is blocked until the raw samples and aggregated chart agree. +- RG-122: For the research inventory, release is blocked until the query result matches the canonical oracle. +- RG-123: For the research inventory, release is blocked until the engine version and artifact digest are recorded. +- RG-124: For the research inventory, release is blocked until the selected durability level matches the comparison class. +- RG-125: For the research inventory, release is blocked until cache state is explicit and reproducible. +- RG-126: For the research inventory, release is blocked until peak memory includes engine and required sidecars. +- RG-127: For the research inventory, release is blocked until storage size includes indexes, logs, replicas, and temporary space. +- RG-128: For the research inventory, release is blocked until timeouts and rejected operations remain in the result set. +- RG-129: For the research inventory, release is blocked until remote requests and bytes are measured rather than estimated. +- RG-130: For the research inventory, release is blocked until background maintenance is either quiesced or reported. +- RG-131: For the research inventory, release is blocked until thread, NUMA, and CPU-affinity settings are captured. +- RG-132: For the research inventory, release is blocked until the dataset and update-stream digests are immutable. +- RG-133: For the research inventory, release is blocked until the query plan/profile is archived. +- RG-134: For the research inventory, release is blocked until unsupported features are not replaced by weaker semantics. +- RG-135: For the research inventory, release is blocked until a second operator can reproduce the run from a clean host. +- RG-136: For the research inventory, release is blocked until the raw samples and aggregated chart agree. +- RG-137: For the research inventory, release is blocked until the query result matches the canonical oracle. +- RG-138: For the research inventory, release is blocked until the engine version and artifact digest are recorded. +- RG-139: For the research inventory, release is blocked until the selected durability level matches the comparison class. +- RG-140: For the research inventory, release is blocked until cache state is explicit and reproducible. +- RG-141: For the research inventory, release is blocked until peak memory includes engine and required sidecars. +- RG-142: For the research inventory, release is blocked until storage size includes indexes, logs, replicas, and temporary space. +- RG-143: For the research inventory, release is blocked until timeouts and rejected operations remain in the result set. +- RG-144: For the research inventory, release is blocked until remote requests and bytes are measured rather than estimated. +- RG-145: For the research inventory, release is blocked until background maintenance is either quiesced or reported. +- RG-146: For the research inventory, release is blocked until thread, NUMA, and CPU-affinity settings are captured. +- RG-147: For the research inventory, release is blocked until the dataset and update-stream digests are immutable. +- RG-148: For the research inventory, release is blocked until the query plan/profile is archived. +- RG-149: For the research inventory, release is blocked until unsupported features are not replaced by weaker semantics. +- RG-150: For the research inventory, release is blocked until a second operator can reproduce the run from a clean host. +- RG-151: For the research inventory, release is blocked until the raw samples and aggregated chart agree. +- RG-152: For the research inventory, release is blocked until the query result matches the canonical oracle. +- RG-153: For the research inventory, release is blocked until the engine version and artifact digest are recorded. +- RG-154: For the research inventory, release is blocked until the selected durability level matches the comparison class. +- RG-155: For the research inventory, release is blocked until cache state is explicit and reproducible. +- RG-156: For the research inventory, release is blocked until peak memory includes engine and required sidecars. +- RG-157: For the research inventory, release is blocked until storage size includes indexes, logs, replicas, and temporary space. +- RG-158: For the research inventory, release is blocked until timeouts and rejected operations remain in the result set. +- RG-159: For the research inventory, release is blocked until remote requests and bytes are measured rather than estimated. +- RG-160: For the research inventory, release is blocked until background maintenance is either quiesced or reported. +- RG-161: For the research inventory, release is blocked until thread, NUMA, and CPU-affinity settings are captured. +- RG-162: For the research inventory, release is blocked until the dataset and update-stream digests are immutable. +- RG-163: For the research inventory, release is blocked until the query plan/profile is archived. +- RG-164: For the research inventory, release is blocked until unsupported features are not replaced by weaker semantics. +- RG-165: For the research inventory, release is blocked until a second operator can reproduce the run from a clean host. +- RG-166: For the research inventory, release is blocked until the raw samples and aggregated chart agree. +- RG-167: For the research inventory, release is blocked until the query result matches the canonical oracle. +- RG-168: For the research inventory, release is blocked until the engine version and artifact digest are recorded. +- RG-169: For the research inventory, release is blocked until the selected durability level matches the comparison class. +- RG-170: For the research inventory, release is blocked until cache state is explicit and reproducible. +- RG-171: For the research inventory, release is blocked until peak memory includes engine and required sidecars. +- RG-172: For the research inventory, release is blocked until storage size includes indexes, logs, replicas, and temporary space. +- RG-173: For the research inventory, release is blocked until timeouts and rejected operations remain in the result set. +- RG-174: For the research inventory, release is blocked until remote requests and bytes are measured rather than estimated. +- RG-175: For the research inventory, release is blocked until background maintenance is either quiesced or reported. +- RG-176: For the research inventory, release is blocked until thread, NUMA, and CPU-affinity settings are captured. +- RG-177: For the research inventory, release is blocked until the dataset and update-stream digests are immutable. +- RG-178: For the research inventory, release is blocked until the query plan/profile is archived. +- RG-179: For the research inventory, release is blocked until unsupported features are not replaced by weaker semantics. +- RG-180: For the research inventory, release is blocked until a second operator can reproduce the run from a clean host. +- RG-181: For the research inventory, release is blocked until the raw samples and aggregated chart agree. +- RG-182: For the research inventory, release is blocked until the query result matches the canonical oracle. +- RG-183: For the research inventory, release is blocked until the engine version and artifact digest are recorded. +- RG-184: For the research inventory, release is blocked until the selected durability level matches the comparison class. +- RG-185: For the research inventory, release is blocked until cache state is explicit and reproducible. +- RG-186: For the research inventory, release is blocked until peak memory includes engine and required sidecars. +- RG-187: For the research inventory, release is blocked until storage size includes indexes, logs, replicas, and temporary space. +- RG-188: For the research inventory, release is blocked until timeouts and rejected operations remain in the result set. +- RG-189: For the research inventory, release is blocked until remote requests and bytes are measured rather than estimated. +- RG-190: For the research inventory, release is blocked until background maintenance is either quiesced or reported. +- RG-191: For the research inventory, release is blocked until thread, NUMA, and CPU-affinity settings are captured. +- RG-192: For the research inventory, release is blocked until the dataset and update-stream digests are immutable. +- RG-193: For the research inventory, release is blocked until the query plan/profile is archived. +- RG-194: For the research inventory, release is blocked until unsupported features are not replaced by weaker semantics. +- RG-195: For the research inventory, release is blocked until a second operator can reproduce the run from a clean host. +- RG-196: For the research inventory, release is blocked until the raw samples and aggregated chart agree. +- RG-197: For the research inventory, release is blocked until the query result matches the canonical oracle. +- RG-198: For the research inventory, release is blocked until the engine version and artifact digest are recorded. +- RG-199: For the research inventory, release is blocked until the selected durability level matches the comparison class. +- RG-200: For the research inventory, release is blocked until cache state is explicit and reproducible. +- RG-201: For the research inventory, release is blocked until peak memory includes engine and required sidecars. +- RG-202: For the research inventory, release is blocked until storage size includes indexes, logs, replicas, and temporary space. +- RG-203: For the research inventory, release is blocked until timeouts and rejected operations remain in the result set. +- RG-204: For the research inventory, release is blocked until remote requests and bytes are measured rather than estimated. +- RG-205: For the research inventory, release is blocked until background maintenance is either quiesced or reported. +- RG-206: For the research inventory, release is blocked until thread, NUMA, and CPU-affinity settings are captured. +- RG-207: For the research inventory, release is blocked until the dataset and update-stream digests are immutable. +- RG-208: For the research inventory, release is blocked until the query plan/profile is archived. +- RG-209: For the research inventory, release is blocked until unsupported features are not replaced by weaker semantics. +- RG-210: For the research inventory, release is blocked until a second operator can reproduce the run from a clean host. +- RG-211: For the research inventory, release is blocked until the raw samples and aggregated chart agree. +- RG-212: For the research inventory, release is blocked until the query result matches the canonical oracle. +- RG-213: For the research inventory, release is blocked until the engine version and artifact digest are recorded. +- RG-214: For the research inventory, release is blocked until the selected durability level matches the comparison class. +- RG-215: For the research inventory, release is blocked until cache state is explicit and reproducible. +- RG-216: For the research inventory, release is blocked until peak memory includes engine and required sidecars. +- RG-217: For the research inventory, release is blocked until storage size includes indexes, logs, replicas, and temporary space. +- RG-218: For the research inventory, release is blocked until timeouts and rejected operations remain in the result set. +- RG-219: For the research inventory, release is blocked until remote requests and bytes are measured rather than estimated. +- RG-220: For the research inventory, release is blocked until background maintenance is either quiesced or reported. +- RG-221: For the research inventory, release is blocked until thread, NUMA, and CPU-affinity settings are captured. +- RG-222: For the research inventory, release is blocked until the dataset and update-stream digests are immutable. +- RG-223: For the research inventory, release is blocked until the query plan/profile is archived. +- RG-224: For the research inventory, release is blocked until unsupported features are not replaced by weaker semantics. +- RG-225: For the research inventory, release is blocked until a second operator can reproduce the run from a clean host. +- RG-226: For the research inventory, release is blocked until the raw samples and aggregated chart agree. +- RG-227: For the research inventory, release is blocked until the query result matches the canonical oracle. +- RG-228: For the research inventory, release is blocked until the engine version and artifact digest are recorded. +- RG-229: For the research inventory, release is blocked until the selected durability level matches the comparison class. +- RG-230: For the research inventory, release is blocked until cache state is explicit and reproducible. +- RG-231: For the research inventory, release is blocked until peak memory includes engine and required sidecars. +- RG-232: For the research inventory, release is blocked until storage size includes indexes, logs, replicas, and temporary space. +- RG-233: For the research inventory, release is blocked until timeouts and rejected operations remain in the result set. +- RG-234: For the research inventory, release is blocked until remote requests and bytes are measured rather than estimated. +- RG-235: For the research inventory, release is blocked until background maintenance is either quiesced or reported. +- RG-236: For the research inventory, release is blocked until thread, NUMA, and CPU-affinity settings are captured. +- RG-237: For the research inventory, release is blocked until the dataset and update-stream digests are immutable. +- RG-238: For the research inventory, release is blocked until the query plan/profile is archived. +- RG-239: For the research inventory, release is blocked until unsupported features are not replaced by weaker semantics. +- RG-240: For the research inventory, release is blocked until a second operator can reproduce the run from a clean host. +- RG-241: For the research inventory, release is blocked until the raw samples and aggregated chart agree. +- RG-242: For the research inventory, release is blocked until the query result matches the canonical oracle. +- RG-243: For the research inventory, release is blocked until the engine version and artifact digest are recorded. +- RG-244: For the research inventory, release is blocked until the selected durability level matches the comparison class. +- RG-245: For the research inventory, release is blocked until cache state is explicit and reproducible. +- RG-246: For the research inventory, release is blocked until peak memory includes engine and required sidecars. +- RG-247: For the research inventory, release is blocked until storage size includes indexes, logs, replicas, and temporary space. +- RG-248: For the research inventory, release is blocked until timeouts and rejected operations remain in the result set. +- RG-249: For the research inventory, release is blocked until remote requests and bytes are measured rather than estimated. +- RG-250: For the research inventory, release is blocked until background maintenance is either quiesced or reported. +- RG-251: For the research inventory, release is blocked until thread, NUMA, and CPU-affinity settings are captured. +- RG-252: For the research inventory, release is blocked until the dataset and update-stream digests are immutable. +- RG-253: For the research inventory, release is blocked until the query plan/profile is archived. +- RG-254: For the research inventory, release is blocked until unsupported features are not replaced by weaker semantics. +- RG-255: For the research inventory, release is blocked until a second operator can reproduce the run from a clean host. +- RG-256: For the research inventory, release is blocked until the raw samples and aggregated chart agree. +- RG-257: For the research inventory, release is blocked until the query result matches the canonical oracle. +- RG-258: For the research inventory, release is blocked until the engine version and artifact digest are recorded. +- RG-259: For the research inventory, release is blocked until the selected durability level matches the comparison class. +- RG-260: For the research inventory, release is blocked until cache state is explicit and reproducible. +- RG-261: For the research inventory, release is blocked until peak memory includes engine and required sidecars. +- RG-262: For the research inventory, release is blocked until storage size includes indexes, logs, replicas, and temporary space. +- RG-263: For the research inventory, release is blocked until timeouts and rejected operations remain in the result set. +- RG-264: For the research inventory, release is blocked until remote requests and bytes are measured rather than estimated. +- RG-265: For the research inventory, release is blocked until background maintenance is either quiesced or reported. +- RG-266: For the research inventory, release is blocked until thread, NUMA, and CPU-affinity settings are captured. +- RG-267: For the research inventory, release is blocked until the dataset and update-stream digests are immutable. +- RG-268: For the research inventory, release is blocked until the query plan/profile is archived. +- RG-269: For the research inventory, release is blocked until unsupported features are not replaced by weaker semantics. +- RG-270: For the research inventory, release is blocked until a second operator can reproduce the run from a clean host. +- RG-271: For the research inventory, release is blocked until the raw samples and aggregated chart agree. +- RG-272: For the research inventory, release is blocked until the query result matches the canonical oracle. +- RG-273: For the research inventory, release is blocked until the engine version and artifact digest are recorded. +- RG-274: For the research inventory, release is blocked until the selected durability level matches the comparison class. +- RG-275: For the research inventory, release is blocked until cache state is explicit and reproducible. +- RG-276: For the research inventory, release is blocked until peak memory includes engine and required sidecars. +- RG-277: For the research inventory, release is blocked until storage size includes indexes, logs, replicas, and temporary space. +- RG-278: For the research inventory, release is blocked until timeouts and rejected operations remain in the result set. +- RG-279: For the research inventory, release is blocked until remote requests and bytes are measured rather than estimated. +- RG-280: For the research inventory, release is blocked until background maintenance is either quiesced or reported. +- RG-281: For the research inventory, release is blocked until thread, NUMA, and CPU-affinity settings are captured. +- RG-282: For the research inventory, release is blocked until the dataset and update-stream digests are immutable. +- RG-283: For the research inventory, release is blocked until the query plan/profile is archived. +- RG-284: For the research inventory, release is blocked until unsupported features are not replaced by weaker semantics. +- RG-285: For the research inventory, release is blocked until a second operator can reproduce the run from a clean host. +- RG-286: For the research inventory, release is blocked until the raw samples and aggregated chart agree. +- RG-287: For the research inventory, release is blocked until the query result matches the canonical oracle. +- RG-288: For the research inventory, release is blocked until the engine version and artifact digest are recorded. +- RG-289: For the research inventory, release is blocked until the selected durability level matches the comparison class. +- RG-290: For the research inventory, release is blocked until cache state is explicit and reproducible. +- RG-291: For the research inventory, release is blocked until peak memory includes engine and required sidecars. +- RG-292: For the research inventory, release is blocked until storage size includes indexes, logs, replicas, and temporary space. +- RG-293: For the research inventory, release is blocked until timeouts and rejected operations remain in the result set. +- RG-294: For the research inventory, release is blocked until remote requests and bytes are measured rather than estimated. +- RG-295: For the research inventory, release is blocked until background maintenance is either quiesced or reported. +- RG-296: For the research inventory, release is blocked until thread, NUMA, and CPU-affinity settings are captured. +- RG-297: For the research inventory, release is blocked until the dataset and update-stream digests are immutable. +- RG-298: For the research inventory, release is blocked until the query plan/profile is archived. +- RG-299: For the research inventory, release is blocked until unsupported features are not replaced by weaker semantics. +- RG-300: For the research inventory, release is blocked until a second operator can reproduce the run from a clean host. +- RG-301: For the research inventory, release is blocked until the raw samples and aggregated chart agree. +- RG-302: For the research inventory, release is blocked until the query result matches the canonical oracle. +- RG-303: For the research inventory, release is blocked until the engine version and artifact digest are recorded. +- RG-304: For the research inventory, release is blocked until the selected durability level matches the comparison class. +- RG-305: For the research inventory, release is blocked until cache state is explicit and reproducible. +- RG-306: For the research inventory, release is blocked until peak memory includes engine and required sidecars. +- RG-307: For the research inventory, release is blocked until storage size includes indexes, logs, replicas, and temporary space. +- RG-308: For the research inventory, release is blocked until timeouts and rejected operations remain in the result set. +- RG-309: For the research inventory, release is blocked until remote requests and bytes are measured rather than estimated. +- RG-310: For the research inventory, release is blocked until background maintenance is either quiesced or reported. +- RG-311: For the research inventory, release is blocked until thread, NUMA, and CPU-affinity settings are captured. +- RG-312: For the research inventory, release is blocked until the dataset and update-stream digests are immutable. +- RG-313: For the research inventory, release is blocked until the query plan/profile is archived. +- RG-314: For the research inventory, release is blocked until unsupported features are not replaced by weaker semantics. +- RG-315: For the research inventory, release is blocked until a second operator can reproduce the run from a clean host. +- RG-316: For the research inventory, release is blocked until the raw samples and aggregated chart agree. +- RG-317: For the research inventory, release is blocked until the query result matches the canonical oracle. +- RG-318: For the research inventory, release is blocked until the engine version and artifact digest are recorded. +- RG-319: For the research inventory, release is blocked until the selected durability level matches the comparison class. +- RG-320: For the research inventory, release is blocked until cache state is explicit and reproducible. +- RG-321: For the research inventory, release is blocked until peak memory includes engine and required sidecars. +- RG-322: For the research inventory, release is blocked until storage size includes indexes, logs, replicas, and temporary space. +- RG-323: For the research inventory, release is blocked until timeouts and rejected operations remain in the result set. +- RG-324: For the research inventory, release is blocked until remote requests and bytes are measured rather than estimated. +- RG-325: For the research inventory, release is blocked until background maintenance is either quiesced or reported. +- RG-326: For the research inventory, release is blocked until thread, NUMA, and CPU-affinity settings are captured. +- RG-327: For the research inventory, release is blocked until the dataset and update-stream digests are immutable. +- RG-328: For the research inventory, release is blocked until the query plan/profile is archived. +- RG-329: For the research inventory, release is blocked until unsupported features are not replaced by weaker semantics. +- RG-330: For the research inventory, release is blocked until a second operator can reproduce the run from a clean host. +- RG-331: For the research inventory, release is blocked until the raw samples and aggregated chart agree. +- RG-332: For the research inventory, release is blocked until the query result matches the canonical oracle. +- RG-333: For the research inventory, release is blocked until the engine version and artifact digest are recorded. +- RG-334: For the research inventory, release is blocked until the selected durability level matches the comparison class. +- RG-335: For the research inventory, release is blocked until cache state is explicit and reproducible. +- RG-336: For the research inventory, release is blocked until peak memory includes engine and required sidecars. +- RG-337: For the research inventory, release is blocked until storage size includes indexes, logs, replicas, and temporary space. +- RG-338: For the research inventory, release is blocked until timeouts and rejected operations remain in the result set. +- RG-339: For the research inventory, release is blocked until remote requests and bytes are measured rather than estimated. +- RG-340: For the research inventory, release is blocked until background maintenance is either quiesced or reported. +- RG-341: For the research inventory, release is blocked until thread, NUMA, and CPU-affinity settings are captured. +- RG-342: For the research inventory, release is blocked until the dataset and update-stream digests are immutable. +- RG-343: For the research inventory, release is blocked until the query plan/profile is archived. +- RG-344: For the research inventory, release is blocked until unsupported features are not replaced by weaker semantics. +- RG-345: For the research inventory, release is blocked until a second operator can reproduce the run from a clean host. +- RG-346: For the research inventory, release is blocked until the raw samples and aggregated chart agree. +- RG-347: For the research inventory, release is blocked until the query result matches the canonical oracle. +- RG-348: For the research inventory, release is blocked until the engine version and artifact digest are recorded. +- RG-349: For the research inventory, release is blocked until the selected durability level matches the comparison class. +- RG-350: For the research inventory, release is blocked until cache state is explicit and reproducible. +- RG-351: For the research inventory, release is blocked until peak memory includes engine and required sidecars. +- RG-352: For the research inventory, release is blocked until storage size includes indexes, logs, replicas, and temporary space. +- RG-353: For the research inventory, release is blocked until timeouts and rejected operations remain in the result set. +- RG-354: For the research inventory, release is blocked until remote requests and bytes are measured rather than estimated. +- RG-355: For the research inventory, release is blocked until background maintenance is either quiesced or reported. +- RG-356: For the research inventory, release is blocked until thread, NUMA, and CPU-affinity settings are captured. +- RG-357: For the research inventory, release is blocked until the dataset and update-stream digests are immutable. +- RG-358: For the research inventory, release is blocked until the query plan/profile is archived. +- RG-359: For the research inventory, release is blocked until unsupported features are not replaced by weaker semantics. +- RG-360: For the research inventory, release is blocked until a second operator can reproduce the run from a clean host. +- RG-361: For the research inventory, release is blocked until the raw samples and aggregated chart agree. +- RG-362: For the research inventory, release is blocked until the query result matches the canonical oracle. +- RG-363: For the research inventory, release is blocked until the engine version and artifact digest are recorded. +- RG-364: For the research inventory, release is blocked until the selected durability level matches the comparison class. +- RG-365: For the research inventory, release is blocked until cache state is explicit and reproducible. +- RG-366: For the research inventory, release is blocked until peak memory includes engine and required sidecars. +- RG-367: For the research inventory, release is blocked until storage size includes indexes, logs, replicas, and temporary space. +- RG-368: For the research inventory, release is blocked until timeouts and rejected operations remain in the result set. +- RG-369: For the research inventory, release is blocked until remote requests and bytes are measured rather than estimated. +- RG-370: For the research inventory, release is blocked until background maintenance is either quiesced or reported. +- RG-371: For the research inventory, release is blocked until thread, NUMA, and CPU-affinity settings are captured. +- RG-372: For the research inventory, release is blocked until the dataset and update-stream digests are immutable. +- RG-373: For the research inventory, release is blocked until the query plan/profile is archived. +- RG-374: For the research inventory, release is blocked until unsupported features are not replaced by weaker semantics. +- RG-375: For the research inventory, release is blocked until a second operator can reproduce the run from a clean host. +- RG-376: For the research inventory, release is blocked until the raw samples and aggregated chart agree. +- RG-377: For the research inventory, release is blocked until the query result matches the canonical oracle. +- RG-378: For the research inventory, release is blocked until the engine version and artifact digest are recorded. +- RG-379: For the research inventory, release is blocked until the selected durability level matches the comparison class. +- RG-380: For the research inventory, release is blocked until cache state is explicit and reproducible. +- RG-381: For the research inventory, release is blocked until peak memory includes engine and required sidecars. +- RG-382: For the research inventory, release is blocked until storage size includes indexes, logs, replicas, and temporary space. +- RG-383: For the research inventory, release is blocked until timeouts and rejected operations remain in the result set. +- RG-384: For the research inventory, release is blocked until remote requests and bytes are measured rather than estimated. +- RG-385: For the research inventory, release is blocked until background maintenance is either quiesced or reported. +- RG-386: For the research inventory, release is blocked until thread, NUMA, and CPU-affinity settings are captured. +- RG-387: For the research inventory, release is blocked until the dataset and update-stream digests are immutable. +- RG-388: For the research inventory, release is blocked until the query plan/profile is archived. +- RG-389: For the research inventory, release is blocked until unsupported features are not replaced by weaker semantics. +- RG-390: For the research inventory, release is blocked until a second operator can reproduce the run from a clean host. +- RG-391: For the research inventory, release is blocked until the raw samples and aggregated chart agree. +- RG-392: For the research inventory, release is blocked until the query result matches the canonical oracle. +- RG-393: For the research inventory, release is blocked until the engine version and artifact digest are recorded. +- RG-394: For the research inventory, release is blocked until the selected durability level matches the comparison class. +- RG-395: For the research inventory, release is blocked until cache state is explicit and reproducible. +- RG-396: For the research inventory, release is blocked until peak memory includes engine and required sidecars. +- RG-397: For the research inventory, release is blocked until storage size includes indexes, logs, replicas, and temporary space. +- RG-398: For the research inventory, release is blocked until timeouts and rejected operations remain in the result set. +- RG-399: For the research inventory, release is blocked until remote requests and bytes are measured rather than estimated. +- RG-400: For the research inventory, release is blocked until background maintenance is either quiesced or reported. +- RG-401: For the research inventory, release is blocked until thread, NUMA, and CPU-affinity settings are captured. +- RG-402: For the research inventory, release is blocked until the dataset and update-stream digests are immutable. +- RG-403: For the research inventory, release is blocked until the query plan/profile is archived. +- RG-404: For the research inventory, release is blocked until unsupported features are not replaced by weaker semantics. +- RG-405: For the research inventory, release is blocked until a second operator can reproduce the run from a clean host. +- RG-406: For the research inventory, release is blocked until the raw samples and aggregated chart agree. +- RG-407: For the research inventory, release is blocked until the query result matches the canonical oracle. diff --git a/docs/research/engine-aerospike_graph.md b/docs/research/engine-aerospike_graph.md new file mode 100644 index 0000000..8763fd7 --- /dev/null +++ b/docs/research/engine-aerospike_graph.md @@ -0,0 +1,885 @@ +# Aerospike Graph: 2026 deep technical and competitive specification + +Research cut: `2026-08-08` +Status: evidence-backed competitor audit; not a vendor endorsement +Family: `stateless Gremlin compute over distributed KV storage` +Evidence convention: **Observed/official**, **Vendor claim**, **Research inference**, **Unknown**, **Qualification target**. + +## 1. Decision summary + +Aerospike Graph is a major low-latency distributed Gremlin comparator and a close analogue to stateless graph compute over a non-graph storage service. + +This document answers two questions: what this engine actually proves in 2026, and what zu must build or measure to earn a defensible advantage. A missing public detail remains unknown; it is never silently filled with a favorable assumption. + +### Snapshot card + +- Lifecycle: active commercial product. +- Data model: property graph. +- Query surface: Apache TinkerPop Gremlin. +- Persistent layout: vertices, edges, and properties encoded in Aerospike Database records. +- Execution: stateless Aerospike Graph Service with step reordering, server-side filtering, and parallel execution. +- Transactions: Aerospike strong-consistency and AGS transaction boundaries; verify multi-record graph mutation behavior. +- Distribution: independently scalable stateless AGS compute over automatically sharded Aerospike Database. +- Object-storage posture: not S3-native; Aerospike's flash/storage engine remains authoritative. +- License/commercial boundary: commercial proprietary. +- Scale evidence: official docs target billions of graph elements; no public PB proof. +- Benchmark posture: measure graph-service fanout and underlying Aerospike record operations, not only client latency. + +### Facts that materially affect comparison + +- F01 — Applications send Gremlin over WebSocket to Aerospike Graph Service. +- F02 — AGS instances are stateless and any instance can serve a request. +- F03 — Graph records live in an automatically sharded Aerospike Database cluster. +- F04 — The compute and storage layers scale independently. +- F05 — A traversal can translate into multiple storage operations, so record-operation count and fanout are mandatory metrics. + +### Bottom-line fit against zu's target + +- Very-low latency: compare hot point and bounded traversal paths; never extrapolate from scans or algorithms. +- Very-low resources: charge resident set, page cache, remote cache, background services, and replicas. +- Distributed: distinguish read replication, partitioned capacity, distributed transactions, and elastic stateless compute. +- Fixed cost: no engine has fixed marginal cost by declaration; admission, batching, and capacity reservations create the bound. +- S3 authority: backups, imports, lake scans, and S3-native demand paging are four different architectures. +- PB / trillion-edge scale: require a capacity derivation plus a run at the largest affordable scale; marketing adjectives do not qualify. +- Tenfold win: can be a per-cell qualification result, never a universal statement across incomparable workloads. + +## 2. Product and ecosystem boundary + +The audited unit is **Aerospike Graph** in the exact release, edition, deployment, and durability mode recorded by the harness. The family classification is **stateless Gremlin compute over distributed KV storage**. The current lifecycle statement is: active commercial product. + +The harness must record binary/container digest, source commit when available, build flags, plugins, license/edition, language mode, storage mode, cluster topology, replication factor, durability settings, cache sizes, thread counts, NUMA policy, kernel, filesystem, cloud region, and all environment variables that affect execution. + +A managed service is not placed in a same-hardware chart. It receives a service-level result with provisioned units, region, public price, and observed provider metrics. A historical engine remains useful for regression but cannot support a claim about beating all current competitors. + +## 3. Architecture reconstruction + +### 3.1 Logical model + +Aerospike Graph exposes property graph. The conformance corpus must test nulls, missing properties, labels/types, direction, self-loops, parallel edges, element equality, path equality, bag semantics, ordering, numeric overflow, string collation, temporal values, and schema evolution. + +### 3.2 Language and compiler + +The public query surface is Apache TinkerPop Gremlin. Syntax similarity is not semantic equivalence. Every supported construct needs a result oracle and an unsupported-feature declaration. + +### 3.3 Storage + +The best supported storage summary is: vertices, edges, and properties encoded in Aerospike Database records. This statement must be refined from code, format documentation, or provider counters before using it in a performance explanation. + +### 3.4 Execution + +The best supported execution summary is: stateless Aerospike Graph Service with step reordering, server-side filtering, and parallel execution. The benchmark profiler must confirm which runtime and operators actually executed. + +### 3.5 Transactions and recovery + +The public contract is: Aerospike strong-consistency and AGS transaction boundaries; verify multi-record graph mutation behavior. Exact acknowledgement, isolation anomalies, recovery bounds, and failover behavior remain separate qualification items. + +### 3.6 Distribution + +The deployment shape is: independently scalable stateless AGS compute over automatically sharded Aerospike Database. Replication is not capacity sharding; sharding is not distributed ACID; stateless readers are not stateless storage. + +### 3.7 Object storage and cost + +The 2026 posture is: not S3-native; Aerospike's flash/storage engine remains authoritative. The audit distinguishes authoritative live bytes, derived acceleration, backup, import/export, and spill. + +## 4. Forty-control deep audit + +### 4.1 `product_boundary` + +Audit question: What exact executable, edition, and storage mode is the system under test? + +Current assessment: Pin Aerospike Graph, lifecycle `active commercial product`, and its edition/mode. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.2 `authority` + +Audit question: Which durable component is the source of truth after every acknowledged write? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.3 `identity` + +Audit question: Are node and edge identities stable across compaction, export, replication, and restore? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.4 `parallel_edges` + +Audit question: Can distinct parallel edges retain properties and trail identity end to end? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.5 `schema` + +Audit question: Is the schema open, closed, optional, inferred, or externally mapped? + +Current assessment: Start from `property graph` and test actual constraints. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.6 `labels` + +Audit question: How are multiple labels represented and indexed? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.7 `adjacency_out` + +Audit question: How is outgoing adjacency located, encoded, split, cached, and updated? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.8 `adjacency_in` + +Audit question: Is incoming adjacency first-class, derived, replicated, or a fan-out operation? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.9 `supernodes` + +Audit question: How are million-to-billion-degree vertices represented and scheduled? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.10 `properties` + +Audit question: Are properties co-located, columnar, row-oriented, document-encoded, or remote? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.11 `compression` + +Audit question: Which topology, integer, string, null, and floating encodings are implemented? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.12 `checksums` + +Audit question: What integrity unit is verified on point reads and range reads? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.13 `snapshot` + +Audit question: What exact token pins graph data, schema, statistics, and indexes? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.14 `isolation` + +Audit question: Which anomalies are forbidden at the documented isolation level? + +Current assessment: Published summary: Aerospike strong-consistency and AGS transaction boundaries; verify multi-record graph mutation behavior. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.15 `durability` + +Audit question: What device/service acknowledgement is required before commit returns? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.16 `recovery` + +Audit question: What bounds restart work after a clean stop and a crash? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.17 `writer_fencing` + +Audit question: Can a stale writer acknowledge after failover or lease expiry? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.18 `partitioning` + +Audit question: What key determines placement and what happens to cross-partition edges? + +Current assessment: Published distribution summary: independently scalable stateless AGS compute over automatically sharded Aerospike Database. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.19 `rebalancing` + +Audit question: Can placement change online without changing logical identity? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.20 `replication` + +Audit question: Are replicas full, sharded, synchronous, asynchronous, or shared-storage readers? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.21 `optimizer` + +Audit question: Does the optimizer cost graph expansion, joins, network, cache, and remote requests? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.22 `statistics` + +Audit question: Which degree, correlation, path, and property statistics are persistent? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.23 `execution` + +Audit question: Is execution tuple-at-a-time, vectorized, factorized, compiled, matrix, or actor based? + +Current assessment: Expected family: stateless Aerospike Graph Service with step reordering, server-side filtering, and parallel execution. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.24 `recursion` + +Audit question: How are BFS, shortest paths, trails, simple paths, and arbitrary reachability executed? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.25 `parallelism` + +Audit question: How does the engine avoid skew and nested parallelism under mixed queries? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.26 `memory` + +Audit question: Are all variable allocations charged to bounded query and system budgets? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.27 `spill` + +Audit question: Which operators spill, in what format, and with what admission controls? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.28 `cancellation` + +Audit question: Can cancellation stop CPU, local I/O, remote I/O, retries, and prefetch? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.29 `cache` + +Audit question: What is cached, how is it keyed, admitted, pinned, and evicted? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.30 `cold_start` + +Audit question: What metadata and data round trips are required with empty caches? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.31 `object_requests` + +Audit question: Can a query issue one remote request per node, edge, or result row? + +Current assessment: Published object-store posture: not S3-native; Aerospike's flash/storage engine remains authoritative. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.32 `cost_admission` + +Audit question: Are request, byte, CPU, spill, and result limits enforced before work? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.33 `observability` + +Audit question: Can operators report rows, edges, bytes, requests, stalls, memory, and spill? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.34 `language` + +Audit question: Which GQL/Cypher/SQL-PGQ/Gremlin/SPARQL semantics are declared and tested? + +Current assessment: Declared surface: Apache TinkerPop Gremlin. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.35 `updates` + +Audit question: Are DDL, insert, merge, update, detach delete, and constraints complete? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.36 `bulk_load` + +Audit question: Does bulk load preserve transactional and index invariants? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.37 `backup` + +Audit question: Is backup consistent, incremental, immutable, and restore-tested? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.38 `gc` + +Audit question: How are old snapshots, orphan objects, tombstones, and indexes reclaimed safely? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.39 `security` + +Audit question: Are authentication, authorization, encryption, audit, and tenant isolation in scope? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.40 `operations` + +Audit question: What compaction, upgrade, repair, verification, and capacity procedures exist? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +## 5. Benchmark contract for this engine + +Every case runs correctness first, then isolated latency, then closed-loop concurrency, then open-loop overload. Report median, p95, p99, p99.9, timeout/rejection rate, throughput, CPU-seconds, peak RSS, cache bytes, disk bytes, network bytes, remote requests, write amplification, and estimated monthly cost. + +Warm means all intended engine caches are populated without changing the query parameters. Hot means the exact working set is resident. Cold means process-local, engine, OS, NVMe, and remote cache state are explicitly reset or a fresh namespace is used. Those words are never inferred from repetition count. + +### 5.1 `point_pk` — primary-key node lookup with one projected property + +- Applicability to Aerospike Graph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.2 `point_edge` — stable edge-ID lookup including endpoints and one property + +- Applicability to Aerospike Graph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.3 `degree_1` — degree-one outgoing expansion + +- Applicability to Aerospike Graph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.4 `degree_32` — small adjacency expansion around degree 32 + +- Applicability to Aerospike Graph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.5 `degree_1k` — medium adjacency expansion around degree 1,024 + +- Applicability to Aerospike Graph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.6 `supernode` — range-limited expansion of a ten-million-degree supernode + +- Applicability to Aerospike Graph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.7 `expand_2` — selective two-hop expansion + +- Applicability to Aerospike Graph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.8 `expand_3` — three-hop frontier expansion with duplicate control + +- Applicability to Aerospike Graph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.9 `expand_into` — edge-existence/expand-into between already-bound endpoints + +- Applicability to Aerospike Graph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.10 `multi_edge` — parallel-edge identity and property projection + +- Applicability to Aerospike Graph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.11 `shortest` — bidirectional point-to-point unweighted shortest path + +- Applicability to Aerospike Graph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.12 `weighted` — weighted shortest path with property access + +- Applicability to Aerospike Graph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.13 `var_walk` — bounded variable-length walk + +- Applicability to Aerospike Graph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.14 `trail` — DIFFERENT EDGES trail enumeration + +- Applicability to Aerospike Graph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.15 `simple` — simple-path enumeration with explicit bound + +- Applicability to Aerospike Graph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.16 `triangle` — triangle pattern with worst-case-sensitive join + +- Applicability to Aerospike Graph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.17 `cycle4` — four-cycle pattern + +- Applicability to Aerospike Graph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.18 `star_join` — high-fanout star pattern with property filters + +- Applicability to Aerospike Graph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.19 `optional` — optional match preserving null/bag semantics + +- Applicability to Aerospike Graph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.20 `aggregate` — grouped aggregate after traversal + +- Applicability to Aerospike Graph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.21 `topk` — ordered top-k with late property materialization + +- Applicability to Aerospike Graph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.22 `scan` — full projected property scan + +- Applicability to Aerospike Graph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.23 `selective_scan` — zone/index-pruned selective property scan + +- Applicability to Aerospike Graph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.24 `mixed` — concurrent short reads, complex reads, and updates + +- Applicability to Aerospike Graph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.25 `ingest` — sustained transactional ingest with indexes enabled + +- Applicability to Aerospike Graph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.26 `bulk` — initial bulk load including index/CSR build + +- Applicability to Aerospike Graph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.27 `checkpoint` — checkpoint or compaction while readers remain active + +- Applicability to Aerospike Graph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.28 `recovery` — crash recovery at bounded dirty-log size + +- Applicability to Aerospike Graph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.29 `cold` — same query after clearing engine and OS/cache tiers + +- Applicability to Aerospike Graph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.30 `remote` — same query with authoritative bytes only in object storage + +- Applicability to Aerospike Graph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +## 6. Fairness controls + +- Same logical dataset and update stream; engine-native physical layouts are allowed and disclosed. +- Same result semantics; unsupported queries remain unsupported rather than rewritten into easier questions. +- Same durable acknowledgement class for write comparisons. +- Same number of physical cores and memory limit for self-hosted single-node tests. +- Same aggregate resources and replication fault tolerance for distributed tests. +- Officially recommended tuning may be applied before the freeze and is committed with rationale. +- Query-specific hints are allowed only when equivalent hints are offered to every engine and separately charted. +- Load/build/index time and bytes are first-class results. +- Cold, warm, and hot results are separate charts. +- Managed services use public configurations and cannot borrow hidden same-machine resource claims. +- Failed runs, OOMs, correctness mismatches, and timeouts stay in the dataset. +- Every chart links raw samples and the exact reproduction command. + +## 7. Likely advantages and limits + +The strongest known reason to choose this engine is tied to its family `stateless Gremlin compute over distributed KV storage`, its execution path `stateless Aerospike Graph Service with step reordering, server-side filtering, and parallel execution`, and its existing ecosystem. The strongest reason to reject it for zu's target is the gap between `not S3-native; Aerospike's flash/storage engine remains authoritative` and an S3-authoritative, request-budgeted, PB-scale graph service. + +Capacity statement: official docs target billions of graph elements; no public PB proof. This is not converted into an edge-count claim without a physical byte model including IDs, both adjacency directions, properties, indexes, MVCC, WAL, replicas, and free space. + +Commercial statement: commercial proprietary. License cost, support cost, and unavailable enterprise capabilities remain visible in TCO and feature tables. + +## 8. Concrete lessons for zu + +1. Keep stable logical node and edge identity independent of row group, CSR slot, shard, and object range. +2. Store forward and reverse adjacency as immutable range-addressable tiles carrying edge IDs. +3. Feed queries adjacency batches and typed vectors; prohibit one storage call per logical element. +4. Use vectorized/factorized execution for property-heavy patterns and dedicated frontier operators for recursion. +5. Cost topology, properties, network, cache certainty, remote requests, and result materialization together. +6. Separate the local embedded profile from the object-authoritative distributed read profile. +7. Fence writers with monotonic epochs and make ambiguous commits reconcilable by transaction ID. +8. Pack small graph tiles into large immutable objects while retaining independent checksums and range offsets. +9. Keep the hot topology working set in RAM/NVMe; batch cold frontier misses into few remote rounds. +10. Admission-control remote requests and bytes so fixed-price plans have an enforceable upper bound. +11. Partition by workload-aware graph locality, and expose cross-partition semantics rather than hiding them. +12. Publish qualified wins per workload cell; never promise a universal tenfold advantage. + +## 9. Evidence gaps to close before publication + +- Exact current version and release date. +- Exact license text for the benchmarked artifact. +- Storage bytes per node/edge/property on all standard datasets. +- Stable-edge-ID and parallel-edge semantics. +- Isolation litmus results and commit acknowledgement point. +- Crash recovery time versus dirty WAL size. +- Supernode behavior and maximum tested degree. +- Cold-start metadata and request count. +- Distributed cross-partition query amplification. +- Peak memory under skew, cancellation, and overload. +- Background compaction/GC effect on tail latency. +- Full load/index/checkpoint/backup resource cost. +- Reproducible largest-scale result. +- Independent or audited benchmark evidence. + +## 10. Primary and official sources + +- [Architecture](https://aerospike.com/docs/graph/overview/architecture/) +- [Graph documentation](https://aerospike.com/docs/graph/) +- [Transaction guidance](https://aerospike.com/docs/graph/querying/transactions) +- [LDBC SNB Interactive and audited disclosures](https://ldbcouncil.org/benchmarks/snb/interactive/) +- [LDBC Graphalytics](https://ldbcouncil.org/benchmarks/graphalytics/) +- [SoK: The Faults in our Graph Benchmarks](https://arxiv.org/abs/2404.00766) + +## 11. Source-handling rules + +- Official documentation and source are evidence for implemented or declared behavior, not independent performance. +- A vendor benchmark is labeled vendor claim until the harness reproduces it. +- A peer-reviewed paper establishes only the version, configuration, and workload it evaluated. +- Search snippets, comparison sites, and unsourced blogs are discovery aids, not final evidence. +- Unknown is a valid result and creates a concrete experiment or source-inspection task. +- All web facts are rechecked at benchmark freeze because this corpus is current only through the research date. + +## 12. Reproduction record template + +- engine: `Aerospike Graph` +- version: `TBD at benchmark freeze` +- artifact digest: `TBD` +- source commit: `TBD or managed-service N/A` +- edition/license: `TBD` +- query language/version: `TBD` +- storage and durability mode: `TBD` +- cluster and replication: `TBD` +- CPU/RAM/NVMe/network: `TBD` +- OS/kernel/filesystem: `TBD` +- dataset URI and digest: `TBD` +- loader command and duration: `TBD` +- physical bytes by category: `TBD` +- tuning file: `TBD` +- query corpus commit: `TBD` +- raw result URI/digest: `TBD` +- profiler/trace URI: `TBD` +- correctness status: `TBD` +- reviewer and rerun date: `TBD` diff --git a/docs/research/engine-agensgraph.md b/docs/research/engine-agensgraph.md new file mode 100644 index 0000000..8bc04dc --- /dev/null +++ b/docs/research/engine-agensgraph.md @@ -0,0 +1,884 @@ +# AgensGraph: 2026 deep technical and competitive specification + +Research cut: `2026-08-08` +Status: evidence-backed competitor audit; not a vendor endorsement +Family: `PostgreSQL-derived multi-model graph database` +Evidence convention: **Observed/official**, **Vendor claim**, **Research inference**, **Unknown**, **Qualification target**. + +## 1. Decision summary + +AgensGraph provides a mature SQL/Cypher hybrid baseline but is not a PB or object-storage competitor. + +This document answers two questions: what this engine actually proves in 2026, and what zu must build or measure to earn a defensible advantage. A missing public detail remains unknown; it is never silently filled with a favorable assumption. + +### Snapshot card + +- Lifecycle: active 2.17 documentation line. +- Data model: graph, relational, JSON document. +- Query surface: SQL and Cypher, composable in one query. +- Persistent layout: PostgreSQL-derived storage, WAL, and indexes with graph extensions. +- Execution: hybrid relational/graph planner and graph indexes. +- Transactions: ACID inherited from PostgreSQL. +- Distribution: active-standby HA; no native horizontally sharded property graph in public docs. +- Object-storage posture: not S3-native. +- License/commercial boundary: open-source/community plus commercial ecosystem; verify package license. +- Scale evidence: single-primary scale. +- Benchmark posture: hybrid-query correctness and optimizer quality are the main comparisons. + +### Facts that materially affect comparison + +- F01 — Graphs are first-class database objects rather than only a function wrapper. +- F02 — Graph and relational expressions can appear in one query. +- F03 — Vertex and edge indexes accelerate graph access. +- F04 — PostgreSQL operational tooling is a major adoption advantage. +- F05 — The active-standby model improves availability but not write or capacity scale. + +### Bottom-line fit against zu's target + +- Very-low latency: compare hot point and bounded traversal paths; never extrapolate from scans or algorithms. +- Very-low resources: charge resident set, page cache, remote cache, background services, and replicas. +- Distributed: distinguish read replication, partitioned capacity, distributed transactions, and elastic stateless compute. +- Fixed cost: no engine has fixed marginal cost by declaration; admission, batching, and capacity reservations create the bound. +- S3 authority: backups, imports, lake scans, and S3-native demand paging are four different architectures. +- PB / trillion-edge scale: require a capacity derivation plus a run at the largest affordable scale; marketing adjectives do not qualify. +- Tenfold win: can be a per-cell qualification result, never a universal statement across incomparable workloads. + +## 2. Product and ecosystem boundary + +The audited unit is **AgensGraph** in the exact release, edition, deployment, and durability mode recorded by the harness. The family classification is **PostgreSQL-derived multi-model graph database**. The current lifecycle statement is: active 2.17 documentation line. + +The harness must record binary/container digest, source commit when available, build flags, plugins, license/edition, language mode, storage mode, cluster topology, replication factor, durability settings, cache sizes, thread counts, NUMA policy, kernel, filesystem, cloud region, and all environment variables that affect execution. + +A managed service is not placed in a same-hardware chart. It receives a service-level result with provisioned units, region, public price, and observed provider metrics. A historical engine remains useful for regression but cannot support a claim about beating all current competitors. + +## 3. Architecture reconstruction + +### 3.1 Logical model + +AgensGraph exposes graph, relational, JSON document. The conformance corpus must test nulls, missing properties, labels/types, direction, self-loops, parallel edges, element equality, path equality, bag semantics, ordering, numeric overflow, string collation, temporal values, and schema evolution. + +### 3.2 Language and compiler + +The public query surface is SQL and Cypher, composable in one query. Syntax similarity is not semantic equivalence. Every supported construct needs a result oracle and an unsupported-feature declaration. + +### 3.3 Storage + +The best supported storage summary is: PostgreSQL-derived storage, WAL, and indexes with graph extensions. This statement must be refined from code, format documentation, or provider counters before using it in a performance explanation. + +### 3.4 Execution + +The best supported execution summary is: hybrid relational/graph planner and graph indexes. The benchmark profiler must confirm which runtime and operators actually executed. + +### 3.5 Transactions and recovery + +The public contract is: ACID inherited from PostgreSQL. Exact acknowledgement, isolation anomalies, recovery bounds, and failover behavior remain separate qualification items. + +### 3.6 Distribution + +The deployment shape is: active-standby HA; no native horizontally sharded property graph in public docs. Replication is not capacity sharding; sharding is not distributed ACID; stateless readers are not stateless storage. + +### 3.7 Object storage and cost + +The 2026 posture is: not S3-native. The audit distinguishes authoritative live bytes, derived acceleration, backup, import/export, and spill. + +## 4. Forty-control deep audit + +### 4.1 `product_boundary` + +Audit question: What exact executable, edition, and storage mode is the system under test? + +Current assessment: Pin AgensGraph, lifecycle `active 2.17 documentation line`, and its edition/mode. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.2 `authority` + +Audit question: Which durable component is the source of truth after every acknowledged write? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.3 `identity` + +Audit question: Are node and edge identities stable across compaction, export, replication, and restore? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.4 `parallel_edges` + +Audit question: Can distinct parallel edges retain properties and trail identity end to end? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.5 `schema` + +Audit question: Is the schema open, closed, optional, inferred, or externally mapped? + +Current assessment: Start from `graph, relational, JSON document` and test actual constraints. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.6 `labels` + +Audit question: How are multiple labels represented and indexed? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.7 `adjacency_out` + +Audit question: How is outgoing adjacency located, encoded, split, cached, and updated? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.8 `adjacency_in` + +Audit question: Is incoming adjacency first-class, derived, replicated, or a fan-out operation? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.9 `supernodes` + +Audit question: How are million-to-billion-degree vertices represented and scheduled? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.10 `properties` + +Audit question: Are properties co-located, columnar, row-oriented, document-encoded, or remote? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.11 `compression` + +Audit question: Which topology, integer, string, null, and floating encodings are implemented? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.12 `checksums` + +Audit question: What integrity unit is verified on point reads and range reads? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.13 `snapshot` + +Audit question: What exact token pins graph data, schema, statistics, and indexes? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.14 `isolation` + +Audit question: Which anomalies are forbidden at the documented isolation level? + +Current assessment: Published summary: ACID inherited from PostgreSQL. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.15 `durability` + +Audit question: What device/service acknowledgement is required before commit returns? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.16 `recovery` + +Audit question: What bounds restart work after a clean stop and a crash? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.17 `writer_fencing` + +Audit question: Can a stale writer acknowledge after failover or lease expiry? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.18 `partitioning` + +Audit question: What key determines placement and what happens to cross-partition edges? + +Current assessment: Published distribution summary: active-standby HA; no native horizontally sharded property graph in public docs. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.19 `rebalancing` + +Audit question: Can placement change online without changing logical identity? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.20 `replication` + +Audit question: Are replicas full, sharded, synchronous, asynchronous, or shared-storage readers? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.21 `optimizer` + +Audit question: Does the optimizer cost graph expansion, joins, network, cache, and remote requests? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.22 `statistics` + +Audit question: Which degree, correlation, path, and property statistics are persistent? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.23 `execution` + +Audit question: Is execution tuple-at-a-time, vectorized, factorized, compiled, matrix, or actor based? + +Current assessment: Expected family: hybrid relational/graph planner and graph indexes. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.24 `recursion` + +Audit question: How are BFS, shortest paths, trails, simple paths, and arbitrary reachability executed? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.25 `parallelism` + +Audit question: How does the engine avoid skew and nested parallelism under mixed queries? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.26 `memory` + +Audit question: Are all variable allocations charged to bounded query and system budgets? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.27 `spill` + +Audit question: Which operators spill, in what format, and with what admission controls? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.28 `cancellation` + +Audit question: Can cancellation stop CPU, local I/O, remote I/O, retries, and prefetch? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.29 `cache` + +Audit question: What is cached, how is it keyed, admitted, pinned, and evicted? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.30 `cold_start` + +Audit question: What metadata and data round trips are required with empty caches? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.31 `object_requests` + +Audit question: Can a query issue one remote request per node, edge, or result row? + +Current assessment: Published object-store posture: not S3-native. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.32 `cost_admission` + +Audit question: Are request, byte, CPU, spill, and result limits enforced before work? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.33 `observability` + +Audit question: Can operators report rows, edges, bytes, requests, stalls, memory, and spill? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.34 `language` + +Audit question: Which GQL/Cypher/SQL-PGQ/Gremlin/SPARQL semantics are declared and tested? + +Current assessment: Declared surface: SQL and Cypher, composable in one query. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.35 `updates` + +Audit question: Are DDL, insert, merge, update, detach delete, and constraints complete? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.36 `bulk_load` + +Audit question: Does bulk load preserve transactional and index invariants? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.37 `backup` + +Audit question: Is backup consistent, incremental, immutable, and restore-tested? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.38 `gc` + +Audit question: How are old snapshots, orphan objects, tombstones, and indexes reclaimed safely? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.39 `security` + +Audit question: Are authentication, authorization, encryption, audit, and tenant isolation in scope? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.40 `operations` + +Audit question: What compaction, upgrade, repair, verification, and capacity procedures exist? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +## 5. Benchmark contract for this engine + +Every case runs correctness first, then isolated latency, then closed-loop concurrency, then open-loop overload. Report median, p95, p99, p99.9, timeout/rejection rate, throughput, CPU-seconds, peak RSS, cache bytes, disk bytes, network bytes, remote requests, write amplification, and estimated monthly cost. + +Warm means all intended engine caches are populated without changing the query parameters. Hot means the exact working set is resident. Cold means process-local, engine, OS, NVMe, and remote cache state are explicitly reset or a fresh namespace is used. Those words are never inferred from repetition count. + +### 5.1 `point_pk` — primary-key node lookup with one projected property + +- Applicability to AgensGraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.2 `point_edge` — stable edge-ID lookup including endpoints and one property + +- Applicability to AgensGraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.3 `degree_1` — degree-one outgoing expansion + +- Applicability to AgensGraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.4 `degree_32` — small adjacency expansion around degree 32 + +- Applicability to AgensGraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.5 `degree_1k` — medium adjacency expansion around degree 1,024 + +- Applicability to AgensGraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.6 `supernode` — range-limited expansion of a ten-million-degree supernode + +- Applicability to AgensGraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.7 `expand_2` — selective two-hop expansion + +- Applicability to AgensGraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.8 `expand_3` — three-hop frontier expansion with duplicate control + +- Applicability to AgensGraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.9 `expand_into` — edge-existence/expand-into between already-bound endpoints + +- Applicability to AgensGraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.10 `multi_edge` — parallel-edge identity and property projection + +- Applicability to AgensGraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.11 `shortest` — bidirectional point-to-point unweighted shortest path + +- Applicability to AgensGraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.12 `weighted` — weighted shortest path with property access + +- Applicability to AgensGraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.13 `var_walk` — bounded variable-length walk + +- Applicability to AgensGraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.14 `trail` — DIFFERENT EDGES trail enumeration + +- Applicability to AgensGraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.15 `simple` — simple-path enumeration with explicit bound + +- Applicability to AgensGraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.16 `triangle` — triangle pattern with worst-case-sensitive join + +- Applicability to AgensGraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.17 `cycle4` — four-cycle pattern + +- Applicability to AgensGraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.18 `star_join` — high-fanout star pattern with property filters + +- Applicability to AgensGraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.19 `optional` — optional match preserving null/bag semantics + +- Applicability to AgensGraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.20 `aggregate` — grouped aggregate after traversal + +- Applicability to AgensGraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.21 `topk` — ordered top-k with late property materialization + +- Applicability to AgensGraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.22 `scan` — full projected property scan + +- Applicability to AgensGraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.23 `selective_scan` — zone/index-pruned selective property scan + +- Applicability to AgensGraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.24 `mixed` — concurrent short reads, complex reads, and updates + +- Applicability to AgensGraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.25 `ingest` — sustained transactional ingest with indexes enabled + +- Applicability to AgensGraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.26 `bulk` — initial bulk load including index/CSR build + +- Applicability to AgensGraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.27 `checkpoint` — checkpoint or compaction while readers remain active + +- Applicability to AgensGraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.28 `recovery` — crash recovery at bounded dirty-log size + +- Applicability to AgensGraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.29 `cold` — same query after clearing engine and OS/cache tiers + +- Applicability to AgensGraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.30 `remote` — same query with authoritative bytes only in object storage + +- Applicability to AgensGraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +## 6. Fairness controls + +- Same logical dataset and update stream; engine-native physical layouts are allowed and disclosed. +- Same result semantics; unsupported queries remain unsupported rather than rewritten into easier questions. +- Same durable acknowledgement class for write comparisons. +- Same number of physical cores and memory limit for self-hosted single-node tests. +- Same aggregate resources and replication fault tolerance for distributed tests. +- Officially recommended tuning may be applied before the freeze and is committed with rationale. +- Query-specific hints are allowed only when equivalent hints are offered to every engine and separately charted. +- Load/build/index time and bytes are first-class results. +- Cold, warm, and hot results are separate charts. +- Managed services use public configurations and cannot borrow hidden same-machine resource claims. +- Failed runs, OOMs, correctness mismatches, and timeouts stay in the dataset. +- Every chart links raw samples and the exact reproduction command. + +## 7. Likely advantages and limits + +The strongest known reason to choose this engine is tied to its family `PostgreSQL-derived multi-model graph database`, its execution path `hybrid relational/graph planner and graph indexes`, and its existing ecosystem. The strongest reason to reject it for zu's target is the gap between `not S3-native` and an S3-authoritative, request-budgeted, PB-scale graph service. + +Capacity statement: single-primary scale. This is not converted into an edge-count claim without a physical byte model including IDs, both adjacency directions, properties, indexes, MVCC, WAL, replicas, and free space. + +Commercial statement: open-source/community plus commercial ecosystem; verify package license. License cost, support cost, and unavailable enterprise capabilities remain visible in TCO and feature tables. + +## 8. Concrete lessons for zu + +1. Keep stable logical node and edge identity independent of row group, CSR slot, shard, and object range. +2. Store forward and reverse adjacency as immutable range-addressable tiles carrying edge IDs. +3. Feed queries adjacency batches and typed vectors; prohibit one storage call per logical element. +4. Use vectorized/factorized execution for property-heavy patterns and dedicated frontier operators for recursion. +5. Cost topology, properties, network, cache certainty, remote requests, and result materialization together. +6. Separate the local embedded profile from the object-authoritative distributed read profile. +7. Fence writers with monotonic epochs and make ambiguous commits reconcilable by transaction ID. +8. Pack small graph tiles into large immutable objects while retaining independent checksums and range offsets. +9. Keep the hot topology working set in RAM/NVMe; batch cold frontier misses into few remote rounds. +10. Admission-control remote requests and bytes so fixed-price plans have an enforceable upper bound. +11. Partition by workload-aware graph locality, and expose cross-partition semantics rather than hiding them. +12. Publish qualified wins per workload cell; never promise a universal tenfold advantage. + +## 9. Evidence gaps to close before publication + +- Exact current version and release date. +- Exact license text for the benchmarked artifact. +- Storage bytes per node/edge/property on all standard datasets. +- Stable-edge-ID and parallel-edge semantics. +- Isolation litmus results and commit acknowledgement point. +- Crash recovery time versus dirty WAL size. +- Supernode behavior and maximum tested degree. +- Cold-start metadata and request count. +- Distributed cross-partition query amplification. +- Peak memory under skew, cancellation, and overload. +- Background compaction/GC effect on tail latency. +- Full load/index/checkpoint/backup resource cost. +- Reproducible largest-scale result. +- Independent or audited benchmark evidence. + +## 10. Primary and official sources + +- [Source repository](https://github.com/skaiworldwide-oss/agensgraph) +- [Project lineage repository](https://github.com/bitnine-oss/agensgraph) +- [LDBC SNB Interactive and audited disclosures](https://ldbcouncil.org/benchmarks/snb/interactive/) +- [LDBC Graphalytics](https://ldbcouncil.org/benchmarks/graphalytics/) +- [SoK: The Faults in our Graph Benchmarks](https://arxiv.org/abs/2404.00766) + +## 11. Source-handling rules + +- Official documentation and source are evidence for implemented or declared behavior, not independent performance. +- A vendor benchmark is labeled vendor claim until the harness reproduces it. +- A peer-reviewed paper establishes only the version, configuration, and workload it evaluated. +- Search snippets, comparison sites, and unsourced blogs are discovery aids, not final evidence. +- Unknown is a valid result and creates a concrete experiment or source-inspection task. +- All web facts are rechecked at benchmark freeze because this corpus is current only through the research date. + +## 12. Reproduction record template + +- engine: `AgensGraph` +- version: `TBD at benchmark freeze` +- artifact digest: `TBD` +- source commit: `TBD or managed-service N/A` +- edition/license: `TBD` +- query language/version: `TBD` +- storage and durability mode: `TBD` +- cluster and replication: `TBD` +- CPU/RAM/NVMe/network: `TBD` +- OS/kernel/filesystem: `TBD` +- dataset URI and digest: `TBD` +- loader command and duration: `TBD` +- physical bytes by category: `TBD` +- tuning file: `TBD` +- query corpus commit: `TBD` +- raw result URI/digest: `TBD` +- profiler/trace URI: `TBD` +- correctness status: `TBD` +- reviewer and rerun date: `TBD` diff --git a/docs/research/engine-allegrograph.md b/docs/research/engine-allegrograph.md new file mode 100644 index 0000000..e4d46ee --- /dev/null +++ b/docs/research/engine-allegrograph.md @@ -0,0 +1,884 @@ +# AllegroGraph: 2026 deep technical and competitive specification + +Research cut: `2026-08-08` +Status: evidence-backed competitor audit; not a vendor endorsement +Family: `commercial RDF/knowledge graph database` +Evidence convention: **Observed/official**, **Vendor claim**, **Research inference**, **Unknown**, **Qualification target**. + +## 1. Decision summary + +AllegroGraph matters for semantic workloads and mature operational features, not as the primary LPG latency target. + +This document answers two questions: what this engine actually proves in 2026, and what zu must build or measure to earn a defensible advantage. A missing public detail remains unknown; it is never silently filled with a favorable assumption. + +### Snapshot card + +- Lifecycle: active 9.x line. +- Data model: RDF quads, JSON-LD documents, vector/geospatial extensions. +- Query surface: SPARQL, Prolog, APIs. +- Persistent layout: native persistent triple/quad store. +- Execution: SPARQL plus reasoning, federation, and graph analytics. +- Transactions: transactional commits. +- Distribution: warm-standby replication and distributed/federated features. +- Object-storage posture: not S3-native live serving. +- License/commercial boundary: commercial proprietary with free-tier terms. +- Scale evidence: large knowledge graphs; current PB evidence unavailable. +- Benchmark posture: benchmark RDF semantics, reasoning, vector, and replication independently. + +### Facts that materially affect comparison + +- F01 — Replication is transactionally consistent from primary to replicas. +- F02 — Transaction log archives support recovery and synchronization. +- F03 — The engine integrates Common Lisp and Prolog-era reasoning strengths. +- F04 — JSON-LD document access broadens the data model. +- F05 — Current performance claims require reproducible datasets and licensed configuration disclosure. + +### Bottom-line fit against zu's target + +- Very-low latency: compare hot point and bounded traversal paths; never extrapolate from scans or algorithms. +- Very-low resources: charge resident set, page cache, remote cache, background services, and replicas. +- Distributed: distinguish read replication, partitioned capacity, distributed transactions, and elastic stateless compute. +- Fixed cost: no engine has fixed marginal cost by declaration; admission, batching, and capacity reservations create the bound. +- S3 authority: backups, imports, lake scans, and S3-native demand paging are four different architectures. +- PB / trillion-edge scale: require a capacity derivation plus a run at the largest affordable scale; marketing adjectives do not qualify. +- Tenfold win: can be a per-cell qualification result, never a universal statement across incomparable workloads. + +## 2. Product and ecosystem boundary + +The audited unit is **AllegroGraph** in the exact release, edition, deployment, and durability mode recorded by the harness. The family classification is **commercial RDF/knowledge graph database**. The current lifecycle statement is: active 9.x line. + +The harness must record binary/container digest, source commit when available, build flags, plugins, license/edition, language mode, storage mode, cluster topology, replication factor, durability settings, cache sizes, thread counts, NUMA policy, kernel, filesystem, cloud region, and all environment variables that affect execution. + +A managed service is not placed in a same-hardware chart. It receives a service-level result with provisioned units, region, public price, and observed provider metrics. A historical engine remains useful for regression but cannot support a claim about beating all current competitors. + +## 3. Architecture reconstruction + +### 3.1 Logical model + +AllegroGraph exposes RDF quads, JSON-LD documents, vector/geospatial extensions. The conformance corpus must test nulls, missing properties, labels/types, direction, self-loops, parallel edges, element equality, path equality, bag semantics, ordering, numeric overflow, string collation, temporal values, and schema evolution. + +### 3.2 Language and compiler + +The public query surface is SPARQL, Prolog, APIs. Syntax similarity is not semantic equivalence. Every supported construct needs a result oracle and an unsupported-feature declaration. + +### 3.3 Storage + +The best supported storage summary is: native persistent triple/quad store. This statement must be refined from code, format documentation, or provider counters before using it in a performance explanation. + +### 3.4 Execution + +The best supported execution summary is: SPARQL plus reasoning, federation, and graph analytics. The benchmark profiler must confirm which runtime and operators actually executed. + +### 3.5 Transactions and recovery + +The public contract is: transactional commits. Exact acknowledgement, isolation anomalies, recovery bounds, and failover behavior remain separate qualification items. + +### 3.6 Distribution + +The deployment shape is: warm-standby replication and distributed/federated features. Replication is not capacity sharding; sharding is not distributed ACID; stateless readers are not stateless storage. + +### 3.7 Object storage and cost + +The 2026 posture is: not S3-native live serving. The audit distinguishes authoritative live bytes, derived acceleration, backup, import/export, and spill. + +## 4. Forty-control deep audit + +### 4.1 `product_boundary` + +Audit question: What exact executable, edition, and storage mode is the system under test? + +Current assessment: Pin AllegroGraph, lifecycle `active 9.x line`, and its edition/mode. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.2 `authority` + +Audit question: Which durable component is the source of truth after every acknowledged write? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.3 `identity` + +Audit question: Are node and edge identities stable across compaction, export, replication, and restore? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.4 `parallel_edges` + +Audit question: Can distinct parallel edges retain properties and trail identity end to end? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.5 `schema` + +Audit question: Is the schema open, closed, optional, inferred, or externally mapped? + +Current assessment: Start from `RDF quads, JSON-LD documents, vector/geospatial extensions` and test actual constraints. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.6 `labels` + +Audit question: How are multiple labels represented and indexed? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.7 `adjacency_out` + +Audit question: How is outgoing adjacency located, encoded, split, cached, and updated? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.8 `adjacency_in` + +Audit question: Is incoming adjacency first-class, derived, replicated, or a fan-out operation? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.9 `supernodes` + +Audit question: How are million-to-billion-degree vertices represented and scheduled? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.10 `properties` + +Audit question: Are properties co-located, columnar, row-oriented, document-encoded, or remote? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.11 `compression` + +Audit question: Which topology, integer, string, null, and floating encodings are implemented? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.12 `checksums` + +Audit question: What integrity unit is verified on point reads and range reads? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.13 `snapshot` + +Audit question: What exact token pins graph data, schema, statistics, and indexes? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.14 `isolation` + +Audit question: Which anomalies are forbidden at the documented isolation level? + +Current assessment: Published summary: transactional commits. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.15 `durability` + +Audit question: What device/service acknowledgement is required before commit returns? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.16 `recovery` + +Audit question: What bounds restart work after a clean stop and a crash? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.17 `writer_fencing` + +Audit question: Can a stale writer acknowledge after failover or lease expiry? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.18 `partitioning` + +Audit question: What key determines placement and what happens to cross-partition edges? + +Current assessment: Published distribution summary: warm-standby replication and distributed/federated features. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.19 `rebalancing` + +Audit question: Can placement change online without changing logical identity? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.20 `replication` + +Audit question: Are replicas full, sharded, synchronous, asynchronous, or shared-storage readers? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.21 `optimizer` + +Audit question: Does the optimizer cost graph expansion, joins, network, cache, and remote requests? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.22 `statistics` + +Audit question: Which degree, correlation, path, and property statistics are persistent? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.23 `execution` + +Audit question: Is execution tuple-at-a-time, vectorized, factorized, compiled, matrix, or actor based? + +Current assessment: Expected family: SPARQL plus reasoning, federation, and graph analytics. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.24 `recursion` + +Audit question: How are BFS, shortest paths, trails, simple paths, and arbitrary reachability executed? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.25 `parallelism` + +Audit question: How does the engine avoid skew and nested parallelism under mixed queries? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.26 `memory` + +Audit question: Are all variable allocations charged to bounded query and system budgets? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.27 `spill` + +Audit question: Which operators spill, in what format, and with what admission controls? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.28 `cancellation` + +Audit question: Can cancellation stop CPU, local I/O, remote I/O, retries, and prefetch? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.29 `cache` + +Audit question: What is cached, how is it keyed, admitted, pinned, and evicted? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.30 `cold_start` + +Audit question: What metadata and data round trips are required with empty caches? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.31 `object_requests` + +Audit question: Can a query issue one remote request per node, edge, or result row? + +Current assessment: Published object-store posture: not S3-native live serving. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.32 `cost_admission` + +Audit question: Are request, byte, CPU, spill, and result limits enforced before work? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.33 `observability` + +Audit question: Can operators report rows, edges, bytes, requests, stalls, memory, and spill? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.34 `language` + +Audit question: Which GQL/Cypher/SQL-PGQ/Gremlin/SPARQL semantics are declared and tested? + +Current assessment: Declared surface: SPARQL, Prolog, APIs. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.35 `updates` + +Audit question: Are DDL, insert, merge, update, detach delete, and constraints complete? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.36 `bulk_load` + +Audit question: Does bulk load preserve transactional and index invariants? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.37 `backup` + +Audit question: Is backup consistent, incremental, immutable, and restore-tested? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.38 `gc` + +Audit question: How are old snapshots, orphan objects, tombstones, and indexes reclaimed safely? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.39 `security` + +Audit question: Are authentication, authorization, encryption, audit, and tenant isolation in scope? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.40 `operations` + +Audit question: What compaction, upgrade, repair, verification, and capacity procedures exist? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +## 5. Benchmark contract for this engine + +Every case runs correctness first, then isolated latency, then closed-loop concurrency, then open-loop overload. Report median, p95, p99, p99.9, timeout/rejection rate, throughput, CPU-seconds, peak RSS, cache bytes, disk bytes, network bytes, remote requests, write amplification, and estimated monthly cost. + +Warm means all intended engine caches are populated without changing the query parameters. Hot means the exact working set is resident. Cold means process-local, engine, OS, NVMe, and remote cache state are explicitly reset or a fresh namespace is used. Those words are never inferred from repetition count. + +### 5.1 `point_pk` — primary-key node lookup with one projected property + +- Applicability to AllegroGraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.2 `point_edge` — stable edge-ID lookup including endpoints and one property + +- Applicability to AllegroGraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.3 `degree_1` — degree-one outgoing expansion + +- Applicability to AllegroGraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.4 `degree_32` — small adjacency expansion around degree 32 + +- Applicability to AllegroGraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.5 `degree_1k` — medium adjacency expansion around degree 1,024 + +- Applicability to AllegroGraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.6 `supernode` — range-limited expansion of a ten-million-degree supernode + +- Applicability to AllegroGraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.7 `expand_2` — selective two-hop expansion + +- Applicability to AllegroGraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.8 `expand_3` — three-hop frontier expansion with duplicate control + +- Applicability to AllegroGraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.9 `expand_into` — edge-existence/expand-into between already-bound endpoints + +- Applicability to AllegroGraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.10 `multi_edge` — parallel-edge identity and property projection + +- Applicability to AllegroGraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.11 `shortest` — bidirectional point-to-point unweighted shortest path + +- Applicability to AllegroGraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.12 `weighted` — weighted shortest path with property access + +- Applicability to AllegroGraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.13 `var_walk` — bounded variable-length walk + +- Applicability to AllegroGraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.14 `trail` — DIFFERENT EDGES trail enumeration + +- Applicability to AllegroGraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.15 `simple` — simple-path enumeration with explicit bound + +- Applicability to AllegroGraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.16 `triangle` — triangle pattern with worst-case-sensitive join + +- Applicability to AllegroGraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.17 `cycle4` — four-cycle pattern + +- Applicability to AllegroGraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.18 `star_join` — high-fanout star pattern with property filters + +- Applicability to AllegroGraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.19 `optional` — optional match preserving null/bag semantics + +- Applicability to AllegroGraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.20 `aggregate` — grouped aggregate after traversal + +- Applicability to AllegroGraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.21 `topk` — ordered top-k with late property materialization + +- Applicability to AllegroGraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.22 `scan` — full projected property scan + +- Applicability to AllegroGraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.23 `selective_scan` — zone/index-pruned selective property scan + +- Applicability to AllegroGraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.24 `mixed` — concurrent short reads, complex reads, and updates + +- Applicability to AllegroGraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.25 `ingest` — sustained transactional ingest with indexes enabled + +- Applicability to AllegroGraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.26 `bulk` — initial bulk load including index/CSR build + +- Applicability to AllegroGraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.27 `checkpoint` — checkpoint or compaction while readers remain active + +- Applicability to AllegroGraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.28 `recovery` — crash recovery at bounded dirty-log size + +- Applicability to AllegroGraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.29 `cold` — same query after clearing engine and OS/cache tiers + +- Applicability to AllegroGraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.30 `remote` — same query with authoritative bytes only in object storage + +- Applicability to AllegroGraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +## 6. Fairness controls + +- Same logical dataset and update stream; engine-native physical layouts are allowed and disclosed. +- Same result semantics; unsupported queries remain unsupported rather than rewritten into easier questions. +- Same durable acknowledgement class for write comparisons. +- Same number of physical cores and memory limit for self-hosted single-node tests. +- Same aggregate resources and replication fault tolerance for distributed tests. +- Officially recommended tuning may be applied before the freeze and is committed with rationale. +- Query-specific hints are allowed only when equivalent hints are offered to every engine and separately charted. +- Load/build/index time and bytes are first-class results. +- Cold, warm, and hot results are separate charts. +- Managed services use public configurations and cannot borrow hidden same-machine resource claims. +- Failed runs, OOMs, correctness mismatches, and timeouts stay in the dataset. +- Every chart links raw samples and the exact reproduction command. + +## 7. Likely advantages and limits + +The strongest known reason to choose this engine is tied to its family `commercial RDF/knowledge graph database`, its execution path `SPARQL plus reasoning, federation, and graph analytics`, and its existing ecosystem. The strongest reason to reject it for zu's target is the gap between `not S3-native live serving` and an S3-authoritative, request-budgeted, PB-scale graph service. + +Capacity statement: large knowledge graphs; current PB evidence unavailable. This is not converted into an edge-count claim without a physical byte model including IDs, both adjacency directions, properties, indexes, MVCC, WAL, replicas, and free space. + +Commercial statement: commercial proprietary with free-tier terms. License cost, support cost, and unavailable enterprise capabilities remain visible in TCO and feature tables. + +## 8. Concrete lessons for zu + +1. Keep stable logical node and edge identity independent of row group, CSR slot, shard, and object range. +2. Store forward and reverse adjacency as immutable range-addressable tiles carrying edge IDs. +3. Feed queries adjacency batches and typed vectors; prohibit one storage call per logical element. +4. Use vectorized/factorized execution for property-heavy patterns and dedicated frontier operators for recursion. +5. Cost topology, properties, network, cache certainty, remote requests, and result materialization together. +6. Separate the local embedded profile from the object-authoritative distributed read profile. +7. Fence writers with monotonic epochs and make ambiguous commits reconcilable by transaction ID. +8. Pack small graph tiles into large immutable objects while retaining independent checksums and range offsets. +9. Keep the hot topology working set in RAM/NVMe; batch cold frontier misses into few remote rounds. +10. Admission-control remote requests and bytes so fixed-price plans have an enforceable upper bound. +11. Partition by workload-aware graph locality, and expose cross-partition semantics rather than hiding them. +12. Publish qualified wins per workload cell; never promise a universal tenfold advantage. + +## 9. Evidence gaps to close before publication + +- Exact current version and release date. +- Exact license text for the benchmarked artifact. +- Storage bytes per node/edge/property on all standard datasets. +- Stable-edge-ID and parallel-edge semantics. +- Isolation litmus results and commit acknowledgement point. +- Crash recovery time versus dirty WAL size. +- Supernode behavior and maximum tested degree. +- Cold-start metadata and request count. +- Distributed cross-partition query amplification. +- Peak memory under skew, cancellation, and overload. +- Background compaction/GC effect on tail latency. +- Full load/index/checkpoint/backup resource cost. +- Reproducible largest-scale result. +- Independent or audited benchmark evidence. + +## 10. Primary and official sources + +- [Current replication](https://franz.com/agraph/support/documentation/replication.html) +- [Documentation](https://franz.com/agraph/support/documentation/) +- [LDBC SNB Interactive and audited disclosures](https://ldbcouncil.org/benchmarks/snb/interactive/) +- [LDBC Graphalytics](https://ldbcouncil.org/benchmarks/graphalytics/) +- [SoK: The Faults in our Graph Benchmarks](https://arxiv.org/abs/2404.00766) + +## 11. Source-handling rules + +- Official documentation and source are evidence for implemented or declared behavior, not independent performance. +- A vendor benchmark is labeled vendor claim until the harness reproduces it. +- A peer-reviewed paper establishes only the version, configuration, and workload it evaluated. +- Search snippets, comparison sites, and unsourced blogs are discovery aids, not final evidence. +- Unknown is a valid result and creates a concrete experiment or source-inspection task. +- All web facts are rechecked at benchmark freeze because this corpus is current only through the research date. + +## 12. Reproduction record template + +- engine: `AllegroGraph` +- version: `TBD at benchmark freeze` +- artifact digest: `TBD` +- source commit: `TBD or managed-service N/A` +- edition/license: `TBD` +- query language/version: `TBD` +- storage and durability mode: `TBD` +- cluster and replication: `TBD` +- CPU/RAM/NVMe/network: `TBD` +- OS/kernel/filesystem: `TBD` +- dataset URI and digest: `TBD` +- loader command and duration: `TBD` +- physical bytes by category: `TBD` +- tuning file: `TBD` +- query corpus commit: `TBD` +- raw result URI/digest: `TBD` +- profiler/trace URI: `TBD` +- correctness status: `TBD` +- reviewer and rerun date: `TBD` diff --git a/docs/research/engine-amazon_neptune.md b/docs/research/engine-amazon_neptune.md new file mode 100644 index 0000000..dec46d8 --- /dev/null +++ b/docs/research/engine-amazon_neptune.md @@ -0,0 +1,885 @@ +# Amazon Neptune Database: 2026 deep technical and competitive specification + +Research cut: `2026-08-08` +Status: evidence-backed competitor audit; not a vendor endorsement +Family: `managed cloud graph database` +Evidence convention: **Observed/official**, **Vendor claim**, **Research inference**, **Unknown**, **Qualification target**. + +## 1. Decision summary + +Neptune is a production durability/availability baseline but cannot satisfy a 1-PB single-graph target today. + +This document answers two questions: what this engine actually proves in 2026, and what zu must build or measure to earn a defensible advantage. A missing public detail remains unknown; it is never silently filled with a favorable assumption. + +### Snapshot card + +- Lifecycle: active AWS service. +- Data model: property graph and RDF. +- Query surface: Gremlin, openCypher, SPARQL. +- Persistent layout: distributed shared SSD-backed cluster volume, six copies across three AZs. +- Execution: managed DFE query engine and language-specific execution. +- Transactions: ACID with documented language-specific isolation/locking semantics. +- Distribution: one writer, up to fifteen read replicas sharing storage; automatic 10-GiB segment growth. +- Object-storage posture: backups are on S3, but live database storage is a managed shared block service, not user-priced S3 objects. +- License/commercial boundary: proprietary managed service. +- Scale evidence: 128-TiB cluster-volume maximum in most regions. +- Benchmark posture: managed-service comparison must include instance, I/O/storage mode, replicas, and network. + +### Facts that materially affect comparison + +- F01 — Cluster storage grows in 10-GiB segments. +- F02 — Each storage segment has six copies across three availability zones. +- F03 — A cluster has one write primary and as many as fifteen read replicas. +- F04 — I/O-Optimized pricing removes per-I/O charges in exchange for higher storage price. +- F05 — Deleting data does not reduce the billed storage high-water mark. + +### Bottom-line fit against zu's target + +- Very-low latency: compare hot point and bounded traversal paths; never extrapolate from scans or algorithms. +- Very-low resources: charge resident set, page cache, remote cache, background services, and replicas. +- Distributed: distinguish read replication, partitioned capacity, distributed transactions, and elastic stateless compute. +- Fixed cost: no engine has fixed marginal cost by declaration; admission, batching, and capacity reservations create the bound. +- S3 authority: backups, imports, lake scans, and S3-native demand paging are four different architectures. +- PB / trillion-edge scale: require a capacity derivation plus a run at the largest affordable scale; marketing adjectives do not qualify. +- Tenfold win: can be a per-cell qualification result, never a universal statement across incomparable workloads. + +## 2. Product and ecosystem boundary + +The audited unit is **Amazon Neptune Database** in the exact release, edition, deployment, and durability mode recorded by the harness. The family classification is **managed cloud graph database**. The current lifecycle statement is: active AWS service. + +The harness must record binary/container digest, source commit when available, build flags, plugins, license/edition, language mode, storage mode, cluster topology, replication factor, durability settings, cache sizes, thread counts, NUMA policy, kernel, filesystem, cloud region, and all environment variables that affect execution. + +A managed service is not placed in a same-hardware chart. It receives a service-level result with provisioned units, region, public price, and observed provider metrics. A historical engine remains useful for regression but cannot support a claim about beating all current competitors. + +## 3. Architecture reconstruction + +### 3.1 Logical model + +Amazon Neptune Database exposes property graph and RDF. The conformance corpus must test nulls, missing properties, labels/types, direction, self-loops, parallel edges, element equality, path equality, bag semantics, ordering, numeric overflow, string collation, temporal values, and schema evolution. + +### 3.2 Language and compiler + +The public query surface is Gremlin, openCypher, SPARQL. Syntax similarity is not semantic equivalence. Every supported construct needs a result oracle and an unsupported-feature declaration. + +### 3.3 Storage + +The best supported storage summary is: distributed shared SSD-backed cluster volume, six copies across three AZs. This statement must be refined from code, format documentation, or provider counters before using it in a performance explanation. + +### 3.4 Execution + +The best supported execution summary is: managed DFE query engine and language-specific execution. The benchmark profiler must confirm which runtime and operators actually executed. + +### 3.5 Transactions and recovery + +The public contract is: ACID with documented language-specific isolation/locking semantics. Exact acknowledgement, isolation anomalies, recovery bounds, and failover behavior remain separate qualification items. + +### 3.6 Distribution + +The deployment shape is: one writer, up to fifteen read replicas sharing storage; automatic 10-GiB segment growth. Replication is not capacity sharding; sharding is not distributed ACID; stateless readers are not stateless storage. + +### 3.7 Object storage and cost + +The 2026 posture is: backups are on S3, but live database storage is a managed shared block service, not user-priced S3 objects. The audit distinguishes authoritative live bytes, derived acceleration, backup, import/export, and spill. + +## 4. Forty-control deep audit + +### 4.1 `product_boundary` + +Audit question: What exact executable, edition, and storage mode is the system under test? + +Current assessment: Pin Amazon Neptune Database, lifecycle `active AWS service`, and its edition/mode. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.2 `authority` + +Audit question: Which durable component is the source of truth after every acknowledged write? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.3 `identity` + +Audit question: Are node and edge identities stable across compaction, export, replication, and restore? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.4 `parallel_edges` + +Audit question: Can distinct parallel edges retain properties and trail identity end to end? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.5 `schema` + +Audit question: Is the schema open, closed, optional, inferred, or externally mapped? + +Current assessment: Start from `property graph and RDF` and test actual constraints. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.6 `labels` + +Audit question: How are multiple labels represented and indexed? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.7 `adjacency_out` + +Audit question: How is outgoing adjacency located, encoded, split, cached, and updated? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.8 `adjacency_in` + +Audit question: Is incoming adjacency first-class, derived, replicated, or a fan-out operation? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.9 `supernodes` + +Audit question: How are million-to-billion-degree vertices represented and scheduled? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.10 `properties` + +Audit question: Are properties co-located, columnar, row-oriented, document-encoded, or remote? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.11 `compression` + +Audit question: Which topology, integer, string, null, and floating encodings are implemented? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.12 `checksums` + +Audit question: What integrity unit is verified on point reads and range reads? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.13 `snapshot` + +Audit question: What exact token pins graph data, schema, statistics, and indexes? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.14 `isolation` + +Audit question: Which anomalies are forbidden at the documented isolation level? + +Current assessment: Published summary: ACID with documented language-specific isolation/locking semantics. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.15 `durability` + +Audit question: What device/service acknowledgement is required before commit returns? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.16 `recovery` + +Audit question: What bounds restart work after a clean stop and a crash? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.17 `writer_fencing` + +Audit question: Can a stale writer acknowledge after failover or lease expiry? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.18 `partitioning` + +Audit question: What key determines placement and what happens to cross-partition edges? + +Current assessment: Published distribution summary: one writer, up to fifteen read replicas sharing storage; automatic 10-GiB segment growth. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.19 `rebalancing` + +Audit question: Can placement change online without changing logical identity? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.20 `replication` + +Audit question: Are replicas full, sharded, synchronous, asynchronous, or shared-storage readers? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.21 `optimizer` + +Audit question: Does the optimizer cost graph expansion, joins, network, cache, and remote requests? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.22 `statistics` + +Audit question: Which degree, correlation, path, and property statistics are persistent? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.23 `execution` + +Audit question: Is execution tuple-at-a-time, vectorized, factorized, compiled, matrix, or actor based? + +Current assessment: Expected family: managed DFE query engine and language-specific execution. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.24 `recursion` + +Audit question: How are BFS, shortest paths, trails, simple paths, and arbitrary reachability executed? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.25 `parallelism` + +Audit question: How does the engine avoid skew and nested parallelism under mixed queries? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.26 `memory` + +Audit question: Are all variable allocations charged to bounded query and system budgets? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.27 `spill` + +Audit question: Which operators spill, in what format, and with what admission controls? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.28 `cancellation` + +Audit question: Can cancellation stop CPU, local I/O, remote I/O, retries, and prefetch? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.29 `cache` + +Audit question: What is cached, how is it keyed, admitted, pinned, and evicted? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.30 `cold_start` + +Audit question: What metadata and data round trips are required with empty caches? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.31 `object_requests` + +Audit question: Can a query issue one remote request per node, edge, or result row? + +Current assessment: Published object-store posture: backups are on S3, but live database storage is a managed shared block service, not user-priced S3 objects. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.32 `cost_admission` + +Audit question: Are request, byte, CPU, spill, and result limits enforced before work? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.33 `observability` + +Audit question: Can operators report rows, edges, bytes, requests, stalls, memory, and spill? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.34 `language` + +Audit question: Which GQL/Cypher/SQL-PGQ/Gremlin/SPARQL semantics are declared and tested? + +Current assessment: Declared surface: Gremlin, openCypher, SPARQL. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.35 `updates` + +Audit question: Are DDL, insert, merge, update, detach delete, and constraints complete? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.36 `bulk_load` + +Audit question: Does bulk load preserve transactional and index invariants? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.37 `backup` + +Audit question: Is backup consistent, incremental, immutable, and restore-tested? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.38 `gc` + +Audit question: How are old snapshots, orphan objects, tombstones, and indexes reclaimed safely? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.39 `security` + +Audit question: Are authentication, authorization, encryption, audit, and tenant isolation in scope? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.40 `operations` + +Audit question: What compaction, upgrade, repair, verification, and capacity procedures exist? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +## 5. Benchmark contract for this engine + +Every case runs correctness first, then isolated latency, then closed-loop concurrency, then open-loop overload. Report median, p95, p99, p99.9, timeout/rejection rate, throughput, CPU-seconds, peak RSS, cache bytes, disk bytes, network bytes, remote requests, write amplification, and estimated monthly cost. + +Warm means all intended engine caches are populated without changing the query parameters. Hot means the exact working set is resident. Cold means process-local, engine, OS, NVMe, and remote cache state are explicitly reset or a fresh namespace is used. Those words are never inferred from repetition count. + +### 5.1 `point_pk` — primary-key node lookup with one projected property + +- Applicability to Amazon Neptune Database: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.2 `point_edge` — stable edge-ID lookup including endpoints and one property + +- Applicability to Amazon Neptune Database: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.3 `degree_1` — degree-one outgoing expansion + +- Applicability to Amazon Neptune Database: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.4 `degree_32` — small adjacency expansion around degree 32 + +- Applicability to Amazon Neptune Database: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.5 `degree_1k` — medium adjacency expansion around degree 1,024 + +- Applicability to Amazon Neptune Database: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.6 `supernode` — range-limited expansion of a ten-million-degree supernode + +- Applicability to Amazon Neptune Database: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.7 `expand_2` — selective two-hop expansion + +- Applicability to Amazon Neptune Database: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.8 `expand_3` — three-hop frontier expansion with duplicate control + +- Applicability to Amazon Neptune Database: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.9 `expand_into` — edge-existence/expand-into between already-bound endpoints + +- Applicability to Amazon Neptune Database: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.10 `multi_edge` — parallel-edge identity and property projection + +- Applicability to Amazon Neptune Database: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.11 `shortest` — bidirectional point-to-point unweighted shortest path + +- Applicability to Amazon Neptune Database: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.12 `weighted` — weighted shortest path with property access + +- Applicability to Amazon Neptune Database: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.13 `var_walk` — bounded variable-length walk + +- Applicability to Amazon Neptune Database: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.14 `trail` — DIFFERENT EDGES trail enumeration + +- Applicability to Amazon Neptune Database: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.15 `simple` — simple-path enumeration with explicit bound + +- Applicability to Amazon Neptune Database: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.16 `triangle` — triangle pattern with worst-case-sensitive join + +- Applicability to Amazon Neptune Database: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.17 `cycle4` — four-cycle pattern + +- Applicability to Amazon Neptune Database: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.18 `star_join` — high-fanout star pattern with property filters + +- Applicability to Amazon Neptune Database: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.19 `optional` — optional match preserving null/bag semantics + +- Applicability to Amazon Neptune Database: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.20 `aggregate` — grouped aggregate after traversal + +- Applicability to Amazon Neptune Database: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.21 `topk` — ordered top-k with late property materialization + +- Applicability to Amazon Neptune Database: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.22 `scan` — full projected property scan + +- Applicability to Amazon Neptune Database: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.23 `selective_scan` — zone/index-pruned selective property scan + +- Applicability to Amazon Neptune Database: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.24 `mixed` — concurrent short reads, complex reads, and updates + +- Applicability to Amazon Neptune Database: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.25 `ingest` — sustained transactional ingest with indexes enabled + +- Applicability to Amazon Neptune Database: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.26 `bulk` — initial bulk load including index/CSR build + +- Applicability to Amazon Neptune Database: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.27 `checkpoint` — checkpoint or compaction while readers remain active + +- Applicability to Amazon Neptune Database: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.28 `recovery` — crash recovery at bounded dirty-log size + +- Applicability to Amazon Neptune Database: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.29 `cold` — same query after clearing engine and OS/cache tiers + +- Applicability to Amazon Neptune Database: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.30 `remote` — same query with authoritative bytes only in object storage + +- Applicability to Amazon Neptune Database: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +## 6. Fairness controls + +- Same logical dataset and update stream; engine-native physical layouts are allowed and disclosed. +- Same result semantics; unsupported queries remain unsupported rather than rewritten into easier questions. +- Same durable acknowledgement class for write comparisons. +- Same number of physical cores and memory limit for self-hosted single-node tests. +- Same aggregate resources and replication fault tolerance for distributed tests. +- Officially recommended tuning may be applied before the freeze and is committed with rationale. +- Query-specific hints are allowed only when equivalent hints are offered to every engine and separately charted. +- Load/build/index time and bytes are first-class results. +- Cold, warm, and hot results are separate charts. +- Managed services use public configurations and cannot borrow hidden same-machine resource claims. +- Failed runs, OOMs, correctness mismatches, and timeouts stay in the dataset. +- Every chart links raw samples and the exact reproduction command. + +## 7. Likely advantages and limits + +The strongest known reason to choose this engine is tied to its family `managed cloud graph database`, its execution path `managed DFE query engine and language-specific execution`, and its existing ecosystem. The strongest reason to reject it for zu's target is the gap between `backups are on S3, but live database storage is a managed shared block service, not user-priced S3 objects` and an S3-authoritative, request-budgeted, PB-scale graph service. + +Capacity statement: 128-TiB cluster-volume maximum in most regions. This is not converted into an edge-count claim without a physical byte model including IDs, both adjacency directions, properties, indexes, MVCC, WAL, replicas, and free space. + +Commercial statement: proprietary managed service. License cost, support cost, and unavailable enterprise capabilities remain visible in TCO and feature tables. + +## 8. Concrete lessons for zu + +1. Keep stable logical node and edge identity independent of row group, CSR slot, shard, and object range. +2. Store forward and reverse adjacency as immutable range-addressable tiles carrying edge IDs. +3. Feed queries adjacency batches and typed vectors; prohibit one storage call per logical element. +4. Use vectorized/factorized execution for property-heavy patterns and dedicated frontier operators for recursion. +5. Cost topology, properties, network, cache certainty, remote requests, and result materialization together. +6. Separate the local embedded profile from the object-authoritative distributed read profile. +7. Fence writers with monotonic epochs and make ambiguous commits reconcilable by transaction ID. +8. Pack small graph tiles into large immutable objects while retaining independent checksums and range offsets. +9. Keep the hot topology working set in RAM/NVMe; batch cold frontier misses into few remote rounds. +10. Admission-control remote requests and bytes so fixed-price plans have an enforceable upper bound. +11. Partition by workload-aware graph locality, and expose cross-partition semantics rather than hiding them. +12. Publish qualified wins per workload cell; never promise a universal tenfold advantage. + +## 9. Evidence gaps to close before publication + +- Exact current version and release date. +- Exact license text for the benchmarked artifact. +- Storage bytes per node/edge/property on all standard datasets. +- Stable-edge-ID and parallel-edge semantics. +- Isolation litmus results and commit acknowledgement point. +- Crash recovery time versus dirty WAL size. +- Supernode behavior and maximum tested degree. +- Cold-start metadata and request count. +- Distributed cross-partition query amplification. +- Peak memory under skew, cancellation, and overload. +- Background compaction/GC effect on tail latency. +- Full load/index/checkpoint/backup resource cost. +- Reproducible largest-scale result. +- Independent or audited benchmark evidence. + +## 10. Primary and official sources + +- [Service overview](https://docs.aws.amazon.com/neptune/latest/userguide/intro.html) +- [Storage architecture](https://docs.aws.amazon.com/neptune/latest/userguide/feature-overview-storage.html) +- [Transactions](https://docs.aws.amazon.com/neptune/latest/userguide/transactions.html) +- [LDBC SNB Interactive and audited disclosures](https://ldbcouncil.org/benchmarks/snb/interactive/) +- [LDBC Graphalytics](https://ldbcouncil.org/benchmarks/graphalytics/) +- [SoK: The Faults in our Graph Benchmarks](https://arxiv.org/abs/2404.00766) + +## 11. Source-handling rules + +- Official documentation and source are evidence for implemented or declared behavior, not independent performance. +- A vendor benchmark is labeled vendor claim until the harness reproduces it. +- A peer-reviewed paper establishes only the version, configuration, and workload it evaluated. +- Search snippets, comparison sites, and unsourced blogs are discovery aids, not final evidence. +- Unknown is a valid result and creates a concrete experiment or source-inspection task. +- All web facts are rechecked at benchmark freeze because this corpus is current only through the research date. + +## 12. Reproduction record template + +- engine: `Amazon Neptune Database` +- version: `TBD at benchmark freeze` +- artifact digest: `TBD` +- source commit: `TBD or managed-service N/A` +- edition/license: `TBD` +- query language/version: `TBD` +- storage and durability mode: `TBD` +- cluster and replication: `TBD` +- CPU/RAM/NVMe/network: `TBD` +- OS/kernel/filesystem: `TBD` +- dataset URI and digest: `TBD` +- loader command and duration: `TBD` +- physical bytes by category: `TBD` +- tuning file: `TBD` +- query corpus commit: `TBD` +- raw result URI/digest: `TBD` +- profiler/trace URI: `TBD` +- correctness status: `TBD` +- reviewer and rerun date: `TBD` diff --git a/docs/research/engine-amazon_neptune_analytics.md b/docs/research/engine-amazon_neptune_analytics.md new file mode 100644 index 0000000..864d202 --- /dev/null +++ b/docs/research/engine-amazon_neptune_analytics.md @@ -0,0 +1,884 @@ +# Amazon Neptune Analytics: 2026 deep technical and competitive specification + +Research cut: `2026-08-08` +Status: evidence-backed competitor audit; not a vendor endorsement +Family: `managed in-memory graph analytics` +Evidence convention: **Observed/official**, **Vendor claim**, **Research inference**, **Unknown**, **Qualification target**. + +## 1. Decision summary + +Neptune Analytics is a strong hot analytical baseline but its economics fundamentally differ from S3-authoritative cold data. + +This document answers two questions: what this engine actually proves in 2026, and what zu must build or measure to earn a defensible advantage. A missing public detail remains unknown; it is never silently filled with a favorable assumption. + +### Snapshot card + +- Lifecycle: active AWS service. +- Data model: property graph analytics. +- Query surface: openCypher procedures and queries. +- Persistent layout: provisioned memory-optimized graph loaded from Neptune or S3. +- Execution: in-memory algorithms, low-latency analytical queries, vector search. +- Transactions: analytics service rather than primary OLTP authority. +- Distribution: managed provisioned graph endpoint. +- Object-storage posture: S3 is an import/source path, not demand-paged live graph storage. +- License/commercial boundary: proprietary managed service. +- Scale evidence: capacity bound by provisioned analytics graph sizes; not PB resident. +- Benchmark posture: charge load time, provisioned capacity, and algorithm duration. + +### Facts that materially affect comparison + +- F01 — The service loads graph data into memory. +- F02 — It complements rather than replaces Neptune Database. +- F03 — More than twenty-five algorithm variants are exposed as procedures. +- F04 — Vector search can participate in graph traversals. +- F05 — Public/private endpoint and IAM overhead belong in end-to-end latency. + +### Bottom-line fit against zu's target + +- Very-low latency: compare hot point and bounded traversal paths; never extrapolate from scans or algorithms. +- Very-low resources: charge resident set, page cache, remote cache, background services, and replicas. +- Distributed: distinguish read replication, partitioned capacity, distributed transactions, and elastic stateless compute. +- Fixed cost: no engine has fixed marginal cost by declaration; admission, batching, and capacity reservations create the bound. +- S3 authority: backups, imports, lake scans, and S3-native demand paging are four different architectures. +- PB / trillion-edge scale: require a capacity derivation plus a run at the largest affordable scale; marketing adjectives do not qualify. +- Tenfold win: can be a per-cell qualification result, never a universal statement across incomparable workloads. + +## 2. Product and ecosystem boundary + +The audited unit is **Amazon Neptune Analytics** in the exact release, edition, deployment, and durability mode recorded by the harness. The family classification is **managed in-memory graph analytics**. The current lifecycle statement is: active AWS service. + +The harness must record binary/container digest, source commit when available, build flags, plugins, license/edition, language mode, storage mode, cluster topology, replication factor, durability settings, cache sizes, thread counts, NUMA policy, kernel, filesystem, cloud region, and all environment variables that affect execution. + +A managed service is not placed in a same-hardware chart. It receives a service-level result with provisioned units, region, public price, and observed provider metrics. A historical engine remains useful for regression but cannot support a claim about beating all current competitors. + +## 3. Architecture reconstruction + +### 3.1 Logical model + +Amazon Neptune Analytics exposes property graph analytics. The conformance corpus must test nulls, missing properties, labels/types, direction, self-loops, parallel edges, element equality, path equality, bag semantics, ordering, numeric overflow, string collation, temporal values, and schema evolution. + +### 3.2 Language and compiler + +The public query surface is openCypher procedures and queries. Syntax similarity is not semantic equivalence. Every supported construct needs a result oracle and an unsupported-feature declaration. + +### 3.3 Storage + +The best supported storage summary is: provisioned memory-optimized graph loaded from Neptune or S3. This statement must be refined from code, format documentation, or provider counters before using it in a performance explanation. + +### 3.4 Execution + +The best supported execution summary is: in-memory algorithms, low-latency analytical queries, vector search. The benchmark profiler must confirm which runtime and operators actually executed. + +### 3.5 Transactions and recovery + +The public contract is: analytics service rather than primary OLTP authority. Exact acknowledgement, isolation anomalies, recovery bounds, and failover behavior remain separate qualification items. + +### 3.6 Distribution + +The deployment shape is: managed provisioned graph endpoint. Replication is not capacity sharding; sharding is not distributed ACID; stateless readers are not stateless storage. + +### 3.7 Object storage and cost + +The 2026 posture is: S3 is an import/source path, not demand-paged live graph storage. The audit distinguishes authoritative live bytes, derived acceleration, backup, import/export, and spill. + +## 4. Forty-control deep audit + +### 4.1 `product_boundary` + +Audit question: What exact executable, edition, and storage mode is the system under test? + +Current assessment: Pin Amazon Neptune Analytics, lifecycle `active AWS service`, and its edition/mode. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.2 `authority` + +Audit question: Which durable component is the source of truth after every acknowledged write? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.3 `identity` + +Audit question: Are node and edge identities stable across compaction, export, replication, and restore? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.4 `parallel_edges` + +Audit question: Can distinct parallel edges retain properties and trail identity end to end? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.5 `schema` + +Audit question: Is the schema open, closed, optional, inferred, or externally mapped? + +Current assessment: Start from `property graph analytics` and test actual constraints. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.6 `labels` + +Audit question: How are multiple labels represented and indexed? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.7 `adjacency_out` + +Audit question: How is outgoing adjacency located, encoded, split, cached, and updated? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.8 `adjacency_in` + +Audit question: Is incoming adjacency first-class, derived, replicated, or a fan-out operation? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.9 `supernodes` + +Audit question: How are million-to-billion-degree vertices represented and scheduled? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.10 `properties` + +Audit question: Are properties co-located, columnar, row-oriented, document-encoded, or remote? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.11 `compression` + +Audit question: Which topology, integer, string, null, and floating encodings are implemented? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.12 `checksums` + +Audit question: What integrity unit is verified on point reads and range reads? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.13 `snapshot` + +Audit question: What exact token pins graph data, schema, statistics, and indexes? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.14 `isolation` + +Audit question: Which anomalies are forbidden at the documented isolation level? + +Current assessment: Published summary: analytics service rather than primary OLTP authority. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.15 `durability` + +Audit question: What device/service acknowledgement is required before commit returns? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.16 `recovery` + +Audit question: What bounds restart work after a clean stop and a crash? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.17 `writer_fencing` + +Audit question: Can a stale writer acknowledge after failover or lease expiry? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.18 `partitioning` + +Audit question: What key determines placement and what happens to cross-partition edges? + +Current assessment: Published distribution summary: managed provisioned graph endpoint. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.19 `rebalancing` + +Audit question: Can placement change online without changing logical identity? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.20 `replication` + +Audit question: Are replicas full, sharded, synchronous, asynchronous, or shared-storage readers? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.21 `optimizer` + +Audit question: Does the optimizer cost graph expansion, joins, network, cache, and remote requests? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.22 `statistics` + +Audit question: Which degree, correlation, path, and property statistics are persistent? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.23 `execution` + +Audit question: Is execution tuple-at-a-time, vectorized, factorized, compiled, matrix, or actor based? + +Current assessment: Expected family: in-memory algorithms, low-latency analytical queries, vector search. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.24 `recursion` + +Audit question: How are BFS, shortest paths, trails, simple paths, and arbitrary reachability executed? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.25 `parallelism` + +Audit question: How does the engine avoid skew and nested parallelism under mixed queries? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.26 `memory` + +Audit question: Are all variable allocations charged to bounded query and system budgets? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.27 `spill` + +Audit question: Which operators spill, in what format, and with what admission controls? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.28 `cancellation` + +Audit question: Can cancellation stop CPU, local I/O, remote I/O, retries, and prefetch? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.29 `cache` + +Audit question: What is cached, how is it keyed, admitted, pinned, and evicted? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.30 `cold_start` + +Audit question: What metadata and data round trips are required with empty caches? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.31 `object_requests` + +Audit question: Can a query issue one remote request per node, edge, or result row? + +Current assessment: Published object-store posture: S3 is an import/source path, not demand-paged live graph storage. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.32 `cost_admission` + +Audit question: Are request, byte, CPU, spill, and result limits enforced before work? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.33 `observability` + +Audit question: Can operators report rows, edges, bytes, requests, stalls, memory, and spill? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.34 `language` + +Audit question: Which GQL/Cypher/SQL-PGQ/Gremlin/SPARQL semantics are declared and tested? + +Current assessment: Declared surface: openCypher procedures and queries. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.35 `updates` + +Audit question: Are DDL, insert, merge, update, detach delete, and constraints complete? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.36 `bulk_load` + +Audit question: Does bulk load preserve transactional and index invariants? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.37 `backup` + +Audit question: Is backup consistent, incremental, immutable, and restore-tested? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.38 `gc` + +Audit question: How are old snapshots, orphan objects, tombstones, and indexes reclaimed safely? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.39 `security` + +Audit question: Are authentication, authorization, encryption, audit, and tenant isolation in scope? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.40 `operations` + +Audit question: What compaction, upgrade, repair, verification, and capacity procedures exist? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +## 5. Benchmark contract for this engine + +Every case runs correctness first, then isolated latency, then closed-loop concurrency, then open-loop overload. Report median, p95, p99, p99.9, timeout/rejection rate, throughput, CPU-seconds, peak RSS, cache bytes, disk bytes, network bytes, remote requests, write amplification, and estimated monthly cost. + +Warm means all intended engine caches are populated without changing the query parameters. Hot means the exact working set is resident. Cold means process-local, engine, OS, NVMe, and remote cache state are explicitly reset or a fresh namespace is used. Those words are never inferred from repetition count. + +### 5.1 `point_pk` — primary-key node lookup with one projected property + +- Applicability to Amazon Neptune Analytics: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.2 `point_edge` — stable edge-ID lookup including endpoints and one property + +- Applicability to Amazon Neptune Analytics: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.3 `degree_1` — degree-one outgoing expansion + +- Applicability to Amazon Neptune Analytics: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.4 `degree_32` — small adjacency expansion around degree 32 + +- Applicability to Amazon Neptune Analytics: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.5 `degree_1k` — medium adjacency expansion around degree 1,024 + +- Applicability to Amazon Neptune Analytics: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.6 `supernode` — range-limited expansion of a ten-million-degree supernode + +- Applicability to Amazon Neptune Analytics: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.7 `expand_2` — selective two-hop expansion + +- Applicability to Amazon Neptune Analytics: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.8 `expand_3` — three-hop frontier expansion with duplicate control + +- Applicability to Amazon Neptune Analytics: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.9 `expand_into` — edge-existence/expand-into between already-bound endpoints + +- Applicability to Amazon Neptune Analytics: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.10 `multi_edge` — parallel-edge identity and property projection + +- Applicability to Amazon Neptune Analytics: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.11 `shortest` — bidirectional point-to-point unweighted shortest path + +- Applicability to Amazon Neptune Analytics: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.12 `weighted` — weighted shortest path with property access + +- Applicability to Amazon Neptune Analytics: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.13 `var_walk` — bounded variable-length walk + +- Applicability to Amazon Neptune Analytics: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.14 `trail` — DIFFERENT EDGES trail enumeration + +- Applicability to Amazon Neptune Analytics: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.15 `simple` — simple-path enumeration with explicit bound + +- Applicability to Amazon Neptune Analytics: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.16 `triangle` — triangle pattern with worst-case-sensitive join + +- Applicability to Amazon Neptune Analytics: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.17 `cycle4` — four-cycle pattern + +- Applicability to Amazon Neptune Analytics: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.18 `star_join` — high-fanout star pattern with property filters + +- Applicability to Amazon Neptune Analytics: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.19 `optional` — optional match preserving null/bag semantics + +- Applicability to Amazon Neptune Analytics: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.20 `aggregate` — grouped aggregate after traversal + +- Applicability to Amazon Neptune Analytics: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.21 `topk` — ordered top-k with late property materialization + +- Applicability to Amazon Neptune Analytics: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.22 `scan` — full projected property scan + +- Applicability to Amazon Neptune Analytics: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.23 `selective_scan` — zone/index-pruned selective property scan + +- Applicability to Amazon Neptune Analytics: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.24 `mixed` — concurrent short reads, complex reads, and updates + +- Applicability to Amazon Neptune Analytics: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.25 `ingest` — sustained transactional ingest with indexes enabled + +- Applicability to Amazon Neptune Analytics: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.26 `bulk` — initial bulk load including index/CSR build + +- Applicability to Amazon Neptune Analytics: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.27 `checkpoint` — checkpoint or compaction while readers remain active + +- Applicability to Amazon Neptune Analytics: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.28 `recovery` — crash recovery at bounded dirty-log size + +- Applicability to Amazon Neptune Analytics: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.29 `cold` — same query after clearing engine and OS/cache tiers + +- Applicability to Amazon Neptune Analytics: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.30 `remote` — same query with authoritative bytes only in object storage + +- Applicability to Amazon Neptune Analytics: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +## 6. Fairness controls + +- Same logical dataset and update stream; engine-native physical layouts are allowed and disclosed. +- Same result semantics; unsupported queries remain unsupported rather than rewritten into easier questions. +- Same durable acknowledgement class for write comparisons. +- Same number of physical cores and memory limit for self-hosted single-node tests. +- Same aggregate resources and replication fault tolerance for distributed tests. +- Officially recommended tuning may be applied before the freeze and is committed with rationale. +- Query-specific hints are allowed only when equivalent hints are offered to every engine and separately charted. +- Load/build/index time and bytes are first-class results. +- Cold, warm, and hot results are separate charts. +- Managed services use public configurations and cannot borrow hidden same-machine resource claims. +- Failed runs, OOMs, correctness mismatches, and timeouts stay in the dataset. +- Every chart links raw samples and the exact reproduction command. + +## 7. Likely advantages and limits + +The strongest known reason to choose this engine is tied to its family `managed in-memory graph analytics`, its execution path `in-memory algorithms, low-latency analytical queries, vector search`, and its existing ecosystem. The strongest reason to reject it for zu's target is the gap between `S3 is an import/source path, not demand-paged live graph storage` and an S3-authoritative, request-budgeted, PB-scale graph service. + +Capacity statement: capacity bound by provisioned analytics graph sizes; not PB resident. This is not converted into an edge-count claim without a physical byte model including IDs, both adjacency directions, properties, indexes, MVCC, WAL, replicas, and free space. + +Commercial statement: proprietary managed service. License cost, support cost, and unavailable enterprise capabilities remain visible in TCO and feature tables. + +## 8. Concrete lessons for zu + +1. Keep stable logical node and edge identity independent of row group, CSR slot, shard, and object range. +2. Store forward and reverse adjacency as immutable range-addressable tiles carrying edge IDs. +3. Feed queries adjacency batches and typed vectors; prohibit one storage call per logical element. +4. Use vectorized/factorized execution for property-heavy patterns and dedicated frontier operators for recursion. +5. Cost topology, properties, network, cache certainty, remote requests, and result materialization together. +6. Separate the local embedded profile from the object-authoritative distributed read profile. +7. Fence writers with monotonic epochs and make ambiguous commits reconcilable by transaction ID. +8. Pack small graph tiles into large immutable objects while retaining independent checksums and range offsets. +9. Keep the hot topology working set in RAM/NVMe; batch cold frontier misses into few remote rounds. +10. Admission-control remote requests and bytes so fixed-price plans have an enforceable upper bound. +11. Partition by workload-aware graph locality, and expose cross-partition semantics rather than hiding them. +12. Publish qualified wins per workload cell; never promise a universal tenfold advantage. + +## 9. Evidence gaps to close before publication + +- Exact current version and release date. +- Exact license text for the benchmarked artifact. +- Storage bytes per node/edge/property on all standard datasets. +- Stable-edge-ID and parallel-edge semantics. +- Isolation litmus results and commit acknowledgement point. +- Crash recovery time versus dirty WAL size. +- Supernode behavior and maximum tested degree. +- Cold-start metadata and request count. +- Distributed cross-partition query amplification. +- Peak memory under skew, cancellation, and overload. +- Background compaction/GC effect on tail latency. +- Full load/index/checkpoint/backup resource cost. +- Reproducible largest-scale result. +- Independent or audited benchmark evidence. + +## 10. Primary and official sources + +- [Service overview](https://docs.aws.amazon.com/neptune-analytics/latest/userguide/what-is-neptune-analytics.html) +- [Algorithms](https://docs.aws.amazon.com/neptune-analytics/latest/userguide/algorithms.html) +- [LDBC SNB Interactive and audited disclosures](https://ldbcouncil.org/benchmarks/snb/interactive/) +- [LDBC Graphalytics](https://ldbcouncil.org/benchmarks/graphalytics/) +- [SoK: The Faults in our Graph Benchmarks](https://arxiv.org/abs/2404.00766) + +## 11. Source-handling rules + +- Official documentation and source are evidence for implemented or declared behavior, not independent performance. +- A vendor benchmark is labeled vendor claim until the harness reproduces it. +- A peer-reviewed paper establishes only the version, configuration, and workload it evaluated. +- Search snippets, comparison sites, and unsourced blogs are discovery aids, not final evidence. +- Unknown is a valid result and creates a concrete experiment or source-inspection task. +- All web facts are rechecked at benchmark freeze because this corpus is current only through the research date. + +## 12. Reproduction record template + +- engine: `Amazon Neptune Analytics` +- version: `TBD at benchmark freeze` +- artifact digest: `TBD` +- source commit: `TBD or managed-service N/A` +- edition/license: `TBD` +- query language/version: `TBD` +- storage and durability mode: `TBD` +- cluster and replication: `TBD` +- CPU/RAM/NVMe/network: `TBD` +- OS/kernel/filesystem: `TBD` +- dataset URI and digest: `TBD` +- loader command and duration: `TBD` +- physical bytes by category: `TBD` +- tuning file: `TBD` +- query corpus commit: `TBD` +- raw result URI/digest: `TBD` +- profiler/trace URI: `TBD` +- correctness status: `TBD` +- reviewer and rerun date: `TBD` diff --git a/docs/research/engine-apache_age.md b/docs/research/engine-apache_age.md new file mode 100644 index 0000000..fd59d88 --- /dev/null +++ b/docs/research/engine-apache_age.md @@ -0,0 +1,885 @@ +# Apache AGE: 2026 deep technical and competitive specification + +Research cut: `2026-08-08` +Status: evidence-backed competitor audit; not a vendor endorsement +Family: `PostgreSQL graph extension` +Evidence convention: **Observed/official**, **Vendor claim**, **Research inference**, **Unknown**, **Qualification target**. + +## 1. Decision summary + +AGE is the strongest open PostgreSQL extension baseline; zu should win deep traversal and storage density while conceding ecosystem maturity. + +This document answers two questions: what this engine actually proves in 2026, and what zu must build or measure to earn a defensible advantage. A missing public detail remains unknown; it is never silently filled with a favorable assumption. + +### Snapshot card + +- Lifecycle: active Apache project. +- Data model: labeled property graph in PostgreSQL. +- Query surface: openCypher embedded in SQL function calls. +- Persistent layout: PostgreSQL heap/index/WAL storage with agtype properties and graph tables. +- Execution: Cypher parser/transformer/planner/executor integrated into PostgreSQL. +- Transactions: inherits PostgreSQL ACID transactions. +- Distribution: PostgreSQL HA options; AGE tables are not currently transparently distributed by Citus. +- Object-storage posture: not S3-native live serving. +- License/commercial boundary: Apache-2.0. +- Scale evidence: PostgreSQL-node scale; no native PB graph sharding. +- Benchmark posture: compare both graph-only and hybrid SQL/Cypher, including join and JSON-property costs. + +### Facts that materially affect comparison + +- F01 — Cypher is transformed into PostgreSQL query trees and graph plan nodes. +- F02 — Every component uses PostgreSQL's transaction and cache layers. +- F03 — Properties use a JSON-like agtype representation. +- F04 — The official FAQ acknowledges relational join limitations for graph workloads. +- F05 — Citus compatibility does not currently make AGE graph tables distributed. + +### Bottom-line fit against zu's target + +- Very-low latency: compare hot point and bounded traversal paths; never extrapolate from scans or algorithms. +- Very-low resources: charge resident set, page cache, remote cache, background services, and replicas. +- Distributed: distinguish read replication, partitioned capacity, distributed transactions, and elastic stateless compute. +- Fixed cost: no engine has fixed marginal cost by declaration; admission, batching, and capacity reservations create the bound. +- S3 authority: backups, imports, lake scans, and S3-native demand paging are four different architectures. +- PB / trillion-edge scale: require a capacity derivation plus a run at the largest affordable scale; marketing adjectives do not qualify. +- Tenfold win: can be a per-cell qualification result, never a universal statement across incomparable workloads. + +## 2. Product and ecosystem boundary + +The audited unit is **Apache AGE** in the exact release, edition, deployment, and durability mode recorded by the harness. The family classification is **PostgreSQL graph extension**. The current lifecycle statement is: active Apache project. + +The harness must record binary/container digest, source commit when available, build flags, plugins, license/edition, language mode, storage mode, cluster topology, replication factor, durability settings, cache sizes, thread counts, NUMA policy, kernel, filesystem, cloud region, and all environment variables that affect execution. + +A managed service is not placed in a same-hardware chart. It receives a service-level result with provisioned units, region, public price, and observed provider metrics. A historical engine remains useful for regression but cannot support a claim about beating all current competitors. + +## 3. Architecture reconstruction + +### 3.1 Logical model + +Apache AGE exposes labeled property graph in PostgreSQL. The conformance corpus must test nulls, missing properties, labels/types, direction, self-loops, parallel edges, element equality, path equality, bag semantics, ordering, numeric overflow, string collation, temporal values, and schema evolution. + +### 3.2 Language and compiler + +The public query surface is openCypher embedded in SQL function calls. Syntax similarity is not semantic equivalence. Every supported construct needs a result oracle and an unsupported-feature declaration. + +### 3.3 Storage + +The best supported storage summary is: PostgreSQL heap/index/WAL storage with agtype properties and graph tables. This statement must be refined from code, format documentation, or provider counters before using it in a performance explanation. + +### 3.4 Execution + +The best supported execution summary is: Cypher parser/transformer/planner/executor integrated into PostgreSQL. The benchmark profiler must confirm which runtime and operators actually executed. + +### 3.5 Transactions and recovery + +The public contract is: inherits PostgreSQL ACID transactions. Exact acknowledgement, isolation anomalies, recovery bounds, and failover behavior remain separate qualification items. + +### 3.6 Distribution + +The deployment shape is: PostgreSQL HA options; AGE tables are not currently transparently distributed by Citus. Replication is not capacity sharding; sharding is not distributed ACID; stateless readers are not stateless storage. + +### 3.7 Object storage and cost + +The 2026 posture is: not S3-native live serving. The audit distinguishes authoritative live bytes, derived acceleration, backup, import/export, and spill. + +## 4. Forty-control deep audit + +### 4.1 `product_boundary` + +Audit question: What exact executable, edition, and storage mode is the system under test? + +Current assessment: Pin Apache AGE, lifecycle `active Apache project`, and its edition/mode. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.2 `authority` + +Audit question: Which durable component is the source of truth after every acknowledged write? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.3 `identity` + +Audit question: Are node and edge identities stable across compaction, export, replication, and restore? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.4 `parallel_edges` + +Audit question: Can distinct parallel edges retain properties and trail identity end to end? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.5 `schema` + +Audit question: Is the schema open, closed, optional, inferred, or externally mapped? + +Current assessment: Start from `labeled property graph in PostgreSQL` and test actual constraints. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.6 `labels` + +Audit question: How are multiple labels represented and indexed? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.7 `adjacency_out` + +Audit question: How is outgoing adjacency located, encoded, split, cached, and updated? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.8 `adjacency_in` + +Audit question: Is incoming adjacency first-class, derived, replicated, or a fan-out operation? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.9 `supernodes` + +Audit question: How are million-to-billion-degree vertices represented and scheduled? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.10 `properties` + +Audit question: Are properties co-located, columnar, row-oriented, document-encoded, or remote? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.11 `compression` + +Audit question: Which topology, integer, string, null, and floating encodings are implemented? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.12 `checksums` + +Audit question: What integrity unit is verified on point reads and range reads? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.13 `snapshot` + +Audit question: What exact token pins graph data, schema, statistics, and indexes? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.14 `isolation` + +Audit question: Which anomalies are forbidden at the documented isolation level? + +Current assessment: Published summary: inherits PostgreSQL ACID transactions. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.15 `durability` + +Audit question: What device/service acknowledgement is required before commit returns? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.16 `recovery` + +Audit question: What bounds restart work after a clean stop and a crash? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.17 `writer_fencing` + +Audit question: Can a stale writer acknowledge after failover or lease expiry? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.18 `partitioning` + +Audit question: What key determines placement and what happens to cross-partition edges? + +Current assessment: Published distribution summary: PostgreSQL HA options; AGE tables are not currently transparently distributed by Citus. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.19 `rebalancing` + +Audit question: Can placement change online without changing logical identity? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.20 `replication` + +Audit question: Are replicas full, sharded, synchronous, asynchronous, or shared-storage readers? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.21 `optimizer` + +Audit question: Does the optimizer cost graph expansion, joins, network, cache, and remote requests? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.22 `statistics` + +Audit question: Which degree, correlation, path, and property statistics are persistent? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.23 `execution` + +Audit question: Is execution tuple-at-a-time, vectorized, factorized, compiled, matrix, or actor based? + +Current assessment: Expected family: Cypher parser/transformer/planner/executor integrated into PostgreSQL. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.24 `recursion` + +Audit question: How are BFS, shortest paths, trails, simple paths, and arbitrary reachability executed? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.25 `parallelism` + +Audit question: How does the engine avoid skew and nested parallelism under mixed queries? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.26 `memory` + +Audit question: Are all variable allocations charged to bounded query and system budgets? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.27 `spill` + +Audit question: Which operators spill, in what format, and with what admission controls? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.28 `cancellation` + +Audit question: Can cancellation stop CPU, local I/O, remote I/O, retries, and prefetch? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.29 `cache` + +Audit question: What is cached, how is it keyed, admitted, pinned, and evicted? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.30 `cold_start` + +Audit question: What metadata and data round trips are required with empty caches? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.31 `object_requests` + +Audit question: Can a query issue one remote request per node, edge, or result row? + +Current assessment: Published object-store posture: not S3-native live serving. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.32 `cost_admission` + +Audit question: Are request, byte, CPU, spill, and result limits enforced before work? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.33 `observability` + +Audit question: Can operators report rows, edges, bytes, requests, stalls, memory, and spill? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.34 `language` + +Audit question: Which GQL/Cypher/SQL-PGQ/Gremlin/SPARQL semantics are declared and tested? + +Current assessment: Declared surface: openCypher embedded in SQL function calls. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.35 `updates` + +Audit question: Are DDL, insert, merge, update, detach delete, and constraints complete? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.36 `bulk_load` + +Audit question: Does bulk load preserve transactional and index invariants? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.37 `backup` + +Audit question: Is backup consistent, incremental, immutable, and restore-tested? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.38 `gc` + +Audit question: How are old snapshots, orphan objects, tombstones, and indexes reclaimed safely? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.39 `security` + +Audit question: Are authentication, authorization, encryption, audit, and tenant isolation in scope? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.40 `operations` + +Audit question: What compaction, upgrade, repair, verification, and capacity procedures exist? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +## 5. Benchmark contract for this engine + +Every case runs correctness first, then isolated latency, then closed-loop concurrency, then open-loop overload. Report median, p95, p99, p99.9, timeout/rejection rate, throughput, CPU-seconds, peak RSS, cache bytes, disk bytes, network bytes, remote requests, write amplification, and estimated monthly cost. + +Warm means all intended engine caches are populated without changing the query parameters. Hot means the exact working set is resident. Cold means process-local, engine, OS, NVMe, and remote cache state are explicitly reset or a fresh namespace is used. Those words are never inferred from repetition count. + +### 5.1 `point_pk` — primary-key node lookup with one projected property + +- Applicability to Apache AGE: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.2 `point_edge` — stable edge-ID lookup including endpoints and one property + +- Applicability to Apache AGE: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.3 `degree_1` — degree-one outgoing expansion + +- Applicability to Apache AGE: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.4 `degree_32` — small adjacency expansion around degree 32 + +- Applicability to Apache AGE: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.5 `degree_1k` — medium adjacency expansion around degree 1,024 + +- Applicability to Apache AGE: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.6 `supernode` — range-limited expansion of a ten-million-degree supernode + +- Applicability to Apache AGE: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.7 `expand_2` — selective two-hop expansion + +- Applicability to Apache AGE: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.8 `expand_3` — three-hop frontier expansion with duplicate control + +- Applicability to Apache AGE: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.9 `expand_into` — edge-existence/expand-into between already-bound endpoints + +- Applicability to Apache AGE: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.10 `multi_edge` — parallel-edge identity and property projection + +- Applicability to Apache AGE: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.11 `shortest` — bidirectional point-to-point unweighted shortest path + +- Applicability to Apache AGE: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.12 `weighted` — weighted shortest path with property access + +- Applicability to Apache AGE: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.13 `var_walk` — bounded variable-length walk + +- Applicability to Apache AGE: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.14 `trail` — DIFFERENT EDGES trail enumeration + +- Applicability to Apache AGE: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.15 `simple` — simple-path enumeration with explicit bound + +- Applicability to Apache AGE: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.16 `triangle` — triangle pattern with worst-case-sensitive join + +- Applicability to Apache AGE: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.17 `cycle4` — four-cycle pattern + +- Applicability to Apache AGE: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.18 `star_join` — high-fanout star pattern with property filters + +- Applicability to Apache AGE: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.19 `optional` — optional match preserving null/bag semantics + +- Applicability to Apache AGE: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.20 `aggregate` — grouped aggregate after traversal + +- Applicability to Apache AGE: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.21 `topk` — ordered top-k with late property materialization + +- Applicability to Apache AGE: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.22 `scan` — full projected property scan + +- Applicability to Apache AGE: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.23 `selective_scan` — zone/index-pruned selective property scan + +- Applicability to Apache AGE: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.24 `mixed` — concurrent short reads, complex reads, and updates + +- Applicability to Apache AGE: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.25 `ingest` — sustained transactional ingest with indexes enabled + +- Applicability to Apache AGE: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.26 `bulk` — initial bulk load including index/CSR build + +- Applicability to Apache AGE: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.27 `checkpoint` — checkpoint or compaction while readers remain active + +- Applicability to Apache AGE: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.28 `recovery` — crash recovery at bounded dirty-log size + +- Applicability to Apache AGE: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.29 `cold` — same query after clearing engine and OS/cache tiers + +- Applicability to Apache AGE: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.30 `remote` — same query with authoritative bytes only in object storage + +- Applicability to Apache AGE: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +## 6. Fairness controls + +- Same logical dataset and update stream; engine-native physical layouts are allowed and disclosed. +- Same result semantics; unsupported queries remain unsupported rather than rewritten into easier questions. +- Same durable acknowledgement class for write comparisons. +- Same number of physical cores and memory limit for self-hosted single-node tests. +- Same aggregate resources and replication fault tolerance for distributed tests. +- Officially recommended tuning may be applied before the freeze and is committed with rationale. +- Query-specific hints are allowed only when equivalent hints are offered to every engine and separately charted. +- Load/build/index time and bytes are first-class results. +- Cold, warm, and hot results are separate charts. +- Managed services use public configurations and cannot borrow hidden same-machine resource claims. +- Failed runs, OOMs, correctness mismatches, and timeouts stay in the dataset. +- Every chart links raw samples and the exact reproduction command. + +## 7. Likely advantages and limits + +The strongest known reason to choose this engine is tied to its family `PostgreSQL graph extension`, its execution path `Cypher parser/transformer/planner/executor integrated into PostgreSQL`, and its existing ecosystem. The strongest reason to reject it for zu's target is the gap between `not S3-native live serving` and an S3-authoritative, request-budgeted, PB-scale graph service. + +Capacity statement: PostgreSQL-node scale; no native PB graph sharding. This is not converted into an edge-count claim without a physical byte model including IDs, both adjacency directions, properties, indexes, MVCC, WAL, replicas, and free space. + +Commercial statement: Apache-2.0. License cost, support cost, and unavailable enterprise capabilities remain visible in TCO and feature tables. + +## 8. Concrete lessons for zu + +1. Keep stable logical node and edge identity independent of row group, CSR slot, shard, and object range. +2. Store forward and reverse adjacency as immutable range-addressable tiles carrying edge IDs. +3. Feed queries adjacency batches and typed vectors; prohibit one storage call per logical element. +4. Use vectorized/factorized execution for property-heavy patterns and dedicated frontier operators for recursion. +5. Cost topology, properties, network, cache certainty, remote requests, and result materialization together. +6. Separate the local embedded profile from the object-authoritative distributed read profile. +7. Fence writers with monotonic epochs and make ambiguous commits reconcilable by transaction ID. +8. Pack small graph tiles into large immutable objects while retaining independent checksums and range offsets. +9. Keep the hot topology working set in RAM/NVMe; batch cold frontier misses into few remote rounds. +10. Admission-control remote requests and bytes so fixed-price plans have an enforceable upper bound. +11. Partition by workload-aware graph locality, and expose cross-partition semantics rather than hiding them. +12. Publish qualified wins per workload cell; never promise a universal tenfold advantage. + +## 9. Evidence gaps to close before publication + +- Exact current version and release date. +- Exact license text for the benchmarked artifact. +- Storage bytes per node/edge/property on all standard datasets. +- Stable-edge-ID and parallel-edge semantics. +- Isolation litmus results and commit acknowledgement point. +- Crash recovery time versus dirty WAL size. +- Supernode behavior and maximum tested degree. +- Cold-start metadata and request count. +- Distributed cross-partition query amplification. +- Peak memory under skew, cancellation, and overload. +- Background compaction/GC effect on tail latency. +- Full load/index/checkpoint/backup resource cost. +- Reproducible largest-scale result. +- Independent or audited benchmark evidence. + +## 10. Primary and official sources + +- [Architecture overview](https://age.apache.org/overview/) +- [FAQ and limitations](https://age.apache.org/faq/) +- [Source repository](https://github.com/apache/age) +- [LDBC SNB Interactive and audited disclosures](https://ldbcouncil.org/benchmarks/snb/interactive/) +- [LDBC Graphalytics](https://ldbcouncil.org/benchmarks/graphalytics/) +- [SoK: The Faults in our Graph Benchmarks](https://arxiv.org/abs/2404.00766) + +## 11. Source-handling rules + +- Official documentation and source are evidence for implemented or declared behavior, not independent performance. +- A vendor benchmark is labeled vendor claim until the harness reproduces it. +- A peer-reviewed paper establishes only the version, configuration, and workload it evaluated. +- Search snippets, comparison sites, and unsourced blogs are discovery aids, not final evidence. +- Unknown is a valid result and creates a concrete experiment or source-inspection task. +- All web facts are rechecked at benchmark freeze because this corpus is current only through the research date. + +## 12. Reproduction record template + +- engine: `Apache AGE` +- version: `TBD at benchmark freeze` +- artifact digest: `TBD` +- source commit: `TBD or managed-service N/A` +- edition/license: `TBD` +- query language/version: `TBD` +- storage and durability mode: `TBD` +- cluster and replication: `TBD` +- CPU/RAM/NVMe/network: `TBD` +- OS/kernel/filesystem: `TBD` +- dataset URI and digest: `TBD` +- loader command and duration: `TBD` +- physical bytes by category: `TBD` +- tuning file: `TBD` +- query corpus commit: `TBD` +- raw result URI/digest: `TBD` +- profiler/trace URI: `TBD` +- correctness status: `TBD` +- reviewer and rerun date: `TBD` diff --git a/docs/research/engine-apache_hugegraph.md b/docs/research/engine-apache_hugegraph.md new file mode 100644 index 0000000..71ba04b --- /dev/null +++ b/docs/research/engine-apache_hugegraph.md @@ -0,0 +1,886 @@ +# Apache HugeGraph: 2026 deep technical and competitive specification + +Research cut: `2026-08-08` +Status: evidence-backed competitor audit; not a vendor endorsement +Family: `pluggable OLTP plus OLAP graph platform` +Evidence convention: **Observed/official**, **Vendor claim**, **Research inference**, **Unknown**, **Qualification target**. + +## 1. Decision summary + +HugeGraph's explicit 1000-TB envelope is highly relevant, but it reaches it with a distributed store rather than cheap object-only serving. + +This document answers two questions: what this engine actually proves in 2026, and what zu must build or measure to earn a defensible advantage. A missing public detail remains unknown; it is never silently filled with a favorable assumption. + +### Snapshot card + +- Lifecycle: active Apache top-level project. +- Data model: schema-full property graph. +- Query surface: Gremlin and openCypher. +- Persistent layout: RocksDB standalone; HStore distributed in current line; older backend matrix is no longer maintained. +- Execution: TinkerPop-compatible OLTP engine plus Vermeer and Pregel-style distributed analytics. +- Transactions: backend- and mode-dependent; HStore uses distributed control/storage services. +- Distribution: PD plus HStore horizontal mode with HA. +- Object-storage posture: not S3-native live serving; external storage is an ingest/analytics concern. +- License/commercial boundary: Apache-2.0. +- Scale evidence: official 2026 docs scope standalone below 4 TB and distributed below 1000 TB. +- Benchmark posture: run server/HStore and analytics components as separate systems. + +### Facts that materially affect comparison + +- F01 — Current 1.7-era docs removed legacy MySQL/PostgreSQL/Cassandra adapters from the maintained path. +- F02 — HugeGraph Server separates core, backend, and REST API layers. +- F03 — HStore requires PD and Store deployments. +- F04 — The platform distinguishes OLTP database, in-memory Vermeer, and distributed HugeGraph-Computer. +- F05 — A 1000-TB advertised boundary is close to PB but not proof at trillion-edge workload shape. + +### Bottom-line fit against zu's target + +- Very-low latency: compare hot point and bounded traversal paths; never extrapolate from scans or algorithms. +- Very-low resources: charge resident set, page cache, remote cache, background services, and replicas. +- Distributed: distinguish read replication, partitioned capacity, distributed transactions, and elastic stateless compute. +- Fixed cost: no engine has fixed marginal cost by declaration; admission, batching, and capacity reservations create the bound. +- S3 authority: backups, imports, lake scans, and S3-native demand paging are four different architectures. +- PB / trillion-edge scale: require a capacity derivation plus a run at the largest affordable scale; marketing adjectives do not qualify. +- Tenfold win: can be a per-cell qualification result, never a universal statement across incomparable workloads. + +## 2. Product and ecosystem boundary + +The audited unit is **Apache HugeGraph** in the exact release, edition, deployment, and durability mode recorded by the harness. The family classification is **pluggable OLTP plus OLAP graph platform**. The current lifecycle statement is: active Apache top-level project. + +The harness must record binary/container digest, source commit when available, build flags, plugins, license/edition, language mode, storage mode, cluster topology, replication factor, durability settings, cache sizes, thread counts, NUMA policy, kernel, filesystem, cloud region, and all environment variables that affect execution. + +A managed service is not placed in a same-hardware chart. It receives a service-level result with provisioned units, region, public price, and observed provider metrics. A historical engine remains useful for regression but cannot support a claim about beating all current competitors. + +## 3. Architecture reconstruction + +### 3.1 Logical model + +Apache HugeGraph exposes schema-full property graph. The conformance corpus must test nulls, missing properties, labels/types, direction, self-loops, parallel edges, element equality, path equality, bag semantics, ordering, numeric overflow, string collation, temporal values, and schema evolution. + +### 3.2 Language and compiler + +The public query surface is Gremlin and openCypher. Syntax similarity is not semantic equivalence. Every supported construct needs a result oracle and an unsupported-feature declaration. + +### 3.3 Storage + +The best supported storage summary is: RocksDB standalone; HStore distributed in current line; older backend matrix is no longer maintained. This statement must be refined from code, format documentation, or provider counters before using it in a performance explanation. + +### 3.4 Execution + +The best supported execution summary is: TinkerPop-compatible OLTP engine plus Vermeer and Pregel-style distributed analytics. The benchmark profiler must confirm which runtime and operators actually executed. + +### 3.5 Transactions and recovery + +The public contract is: backend- and mode-dependent; HStore uses distributed control/storage services. Exact acknowledgement, isolation anomalies, recovery bounds, and failover behavior remain separate qualification items. + +### 3.6 Distribution + +The deployment shape is: PD plus HStore horizontal mode with HA. Replication is not capacity sharding; sharding is not distributed ACID; stateless readers are not stateless storage. + +### 3.7 Object storage and cost + +The 2026 posture is: not S3-native live serving; external storage is an ingest/analytics concern. The audit distinguishes authoritative live bytes, derived acceleration, backup, import/export, and spill. + +## 4. Forty-control deep audit + +### 4.1 `product_boundary` + +Audit question: What exact executable, edition, and storage mode is the system under test? + +Current assessment: Pin Apache HugeGraph, lifecycle `active Apache top-level project`, and its edition/mode. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.2 `authority` + +Audit question: Which durable component is the source of truth after every acknowledged write? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.3 `identity` + +Audit question: Are node and edge identities stable across compaction, export, replication, and restore? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.4 `parallel_edges` + +Audit question: Can distinct parallel edges retain properties and trail identity end to end? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.5 `schema` + +Audit question: Is the schema open, closed, optional, inferred, or externally mapped? + +Current assessment: Start from `schema-full property graph` and test actual constraints. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.6 `labels` + +Audit question: How are multiple labels represented and indexed? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.7 `adjacency_out` + +Audit question: How is outgoing adjacency located, encoded, split, cached, and updated? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.8 `adjacency_in` + +Audit question: Is incoming adjacency first-class, derived, replicated, or a fan-out operation? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.9 `supernodes` + +Audit question: How are million-to-billion-degree vertices represented and scheduled? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.10 `properties` + +Audit question: Are properties co-located, columnar, row-oriented, document-encoded, or remote? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.11 `compression` + +Audit question: Which topology, integer, string, null, and floating encodings are implemented? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.12 `checksums` + +Audit question: What integrity unit is verified on point reads and range reads? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.13 `snapshot` + +Audit question: What exact token pins graph data, schema, statistics, and indexes? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.14 `isolation` + +Audit question: Which anomalies are forbidden at the documented isolation level? + +Current assessment: Published summary: backend- and mode-dependent; HStore uses distributed control/storage services. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.15 `durability` + +Audit question: What device/service acknowledgement is required before commit returns? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.16 `recovery` + +Audit question: What bounds restart work after a clean stop and a crash? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.17 `writer_fencing` + +Audit question: Can a stale writer acknowledge after failover or lease expiry? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.18 `partitioning` + +Audit question: What key determines placement and what happens to cross-partition edges? + +Current assessment: Published distribution summary: PD plus HStore horizontal mode with HA. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.19 `rebalancing` + +Audit question: Can placement change online without changing logical identity? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.20 `replication` + +Audit question: Are replicas full, sharded, synchronous, asynchronous, or shared-storage readers? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.21 `optimizer` + +Audit question: Does the optimizer cost graph expansion, joins, network, cache, and remote requests? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.22 `statistics` + +Audit question: Which degree, correlation, path, and property statistics are persistent? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.23 `execution` + +Audit question: Is execution tuple-at-a-time, vectorized, factorized, compiled, matrix, or actor based? + +Current assessment: Expected family: TinkerPop-compatible OLTP engine plus Vermeer and Pregel-style distributed analytics. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.24 `recursion` + +Audit question: How are BFS, shortest paths, trails, simple paths, and arbitrary reachability executed? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.25 `parallelism` + +Audit question: How does the engine avoid skew and nested parallelism under mixed queries? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.26 `memory` + +Audit question: Are all variable allocations charged to bounded query and system budgets? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.27 `spill` + +Audit question: Which operators spill, in what format, and with what admission controls? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.28 `cancellation` + +Audit question: Can cancellation stop CPU, local I/O, remote I/O, retries, and prefetch? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.29 `cache` + +Audit question: What is cached, how is it keyed, admitted, pinned, and evicted? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.30 `cold_start` + +Audit question: What metadata and data round trips are required with empty caches? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.31 `object_requests` + +Audit question: Can a query issue one remote request per node, edge, or result row? + +Current assessment: Published object-store posture: not S3-native live serving; external storage is an ingest/analytics concern. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.32 `cost_admission` + +Audit question: Are request, byte, CPU, spill, and result limits enforced before work? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.33 `observability` + +Audit question: Can operators report rows, edges, bytes, requests, stalls, memory, and spill? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.34 `language` + +Audit question: Which GQL/Cypher/SQL-PGQ/Gremlin/SPARQL semantics are declared and tested? + +Current assessment: Declared surface: Gremlin and openCypher. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.35 `updates` + +Audit question: Are DDL, insert, merge, update, detach delete, and constraints complete? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.36 `bulk_load` + +Audit question: Does bulk load preserve transactional and index invariants? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.37 `backup` + +Audit question: Is backup consistent, incremental, immutable, and restore-tested? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.38 `gc` + +Audit question: How are old snapshots, orphan objects, tombstones, and indexes reclaimed safely? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.39 `security` + +Audit question: Are authentication, authorization, encryption, audit, and tenant isolation in scope? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.40 `operations` + +Audit question: What compaction, upgrade, repair, verification, and capacity procedures exist? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +## 5. Benchmark contract for this engine + +Every case runs correctness first, then isolated latency, then closed-loop concurrency, then open-loop overload. Report median, p95, p99, p99.9, timeout/rejection rate, throughput, CPU-seconds, peak RSS, cache bytes, disk bytes, network bytes, remote requests, write amplification, and estimated monthly cost. + +Warm means all intended engine caches are populated without changing the query parameters. Hot means the exact working set is resident. Cold means process-local, engine, OS, NVMe, and remote cache state are explicitly reset or a fresh namespace is used. Those words are never inferred from repetition count. + +### 5.1 `point_pk` — primary-key node lookup with one projected property + +- Applicability to Apache HugeGraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.2 `point_edge` — stable edge-ID lookup including endpoints and one property + +- Applicability to Apache HugeGraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.3 `degree_1` — degree-one outgoing expansion + +- Applicability to Apache HugeGraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.4 `degree_32` — small adjacency expansion around degree 32 + +- Applicability to Apache HugeGraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.5 `degree_1k` — medium adjacency expansion around degree 1,024 + +- Applicability to Apache HugeGraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.6 `supernode` — range-limited expansion of a ten-million-degree supernode + +- Applicability to Apache HugeGraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.7 `expand_2` — selective two-hop expansion + +- Applicability to Apache HugeGraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.8 `expand_3` — three-hop frontier expansion with duplicate control + +- Applicability to Apache HugeGraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.9 `expand_into` — edge-existence/expand-into between already-bound endpoints + +- Applicability to Apache HugeGraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.10 `multi_edge` — parallel-edge identity and property projection + +- Applicability to Apache HugeGraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.11 `shortest` — bidirectional point-to-point unweighted shortest path + +- Applicability to Apache HugeGraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.12 `weighted` — weighted shortest path with property access + +- Applicability to Apache HugeGraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.13 `var_walk` — bounded variable-length walk + +- Applicability to Apache HugeGraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.14 `trail` — DIFFERENT EDGES trail enumeration + +- Applicability to Apache HugeGraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.15 `simple` — simple-path enumeration with explicit bound + +- Applicability to Apache HugeGraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.16 `triangle` — triangle pattern with worst-case-sensitive join + +- Applicability to Apache HugeGraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.17 `cycle4` — four-cycle pattern + +- Applicability to Apache HugeGraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.18 `star_join` — high-fanout star pattern with property filters + +- Applicability to Apache HugeGraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.19 `optional` — optional match preserving null/bag semantics + +- Applicability to Apache HugeGraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.20 `aggregate` — grouped aggregate after traversal + +- Applicability to Apache HugeGraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.21 `topk` — ordered top-k with late property materialization + +- Applicability to Apache HugeGraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.22 `scan` — full projected property scan + +- Applicability to Apache HugeGraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.23 `selective_scan` — zone/index-pruned selective property scan + +- Applicability to Apache HugeGraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.24 `mixed` — concurrent short reads, complex reads, and updates + +- Applicability to Apache HugeGraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.25 `ingest` — sustained transactional ingest with indexes enabled + +- Applicability to Apache HugeGraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.26 `bulk` — initial bulk load including index/CSR build + +- Applicability to Apache HugeGraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.27 `checkpoint` — checkpoint or compaction while readers remain active + +- Applicability to Apache HugeGraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.28 `recovery` — crash recovery at bounded dirty-log size + +- Applicability to Apache HugeGraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.29 `cold` — same query after clearing engine and OS/cache tiers + +- Applicability to Apache HugeGraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.30 `remote` — same query with authoritative bytes only in object storage + +- Applicability to Apache HugeGraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +## 6. Fairness controls + +- Same logical dataset and update stream; engine-native physical layouts are allowed and disclosed. +- Same result semantics; unsupported queries remain unsupported rather than rewritten into easier questions. +- Same durable acknowledgement class for write comparisons. +- Same number of physical cores and memory limit for self-hosted single-node tests. +- Same aggregate resources and replication fault tolerance for distributed tests. +- Officially recommended tuning may be applied before the freeze and is committed with rationale. +- Query-specific hints are allowed only when equivalent hints are offered to every engine and separately charted. +- Load/build/index time and bytes are first-class results. +- Cold, warm, and hot results are separate charts. +- Managed services use public configurations and cannot borrow hidden same-machine resource claims. +- Failed runs, OOMs, correctness mismatches, and timeouts stay in the dataset. +- Every chart links raw samples and the exact reproduction command. + +## 7. Likely advantages and limits + +The strongest known reason to choose this engine is tied to its family `pluggable OLTP plus OLAP graph platform`, its execution path `TinkerPop-compatible OLTP engine plus Vermeer and Pregel-style distributed analytics`, and its existing ecosystem. The strongest reason to reject it for zu's target is the gap between `not S3-native live serving; external storage is an ingest/analytics concern` and an S3-authoritative, request-budgeted, PB-scale graph service. + +Capacity statement: official 2026 docs scope standalone below 4 TB and distributed below 1000 TB. This is not converted into an edge-count claim without a physical byte model including IDs, both adjacency directions, properties, indexes, MVCC, WAL, replicas, and free space. + +Commercial statement: Apache-2.0. License cost, support cost, and unavailable enterprise capabilities remain visible in TCO and feature tables. + +## 8. Concrete lessons for zu + +1. Keep stable logical node and edge identity independent of row group, CSR slot, shard, and object range. +2. Store forward and reverse adjacency as immutable range-addressable tiles carrying edge IDs. +3. Feed queries adjacency batches and typed vectors; prohibit one storage call per logical element. +4. Use vectorized/factorized execution for property-heavy patterns and dedicated frontier operators for recursion. +5. Cost topology, properties, network, cache certainty, remote requests, and result materialization together. +6. Separate the local embedded profile from the object-authoritative distributed read profile. +7. Fence writers with monotonic epochs and make ambiguous commits reconcilable by transaction ID. +8. Pack small graph tiles into large immutable objects while retaining independent checksums and range offsets. +9. Keep the hot topology working set in RAM/NVMe; batch cold frontier misses into few remote rounds. +10. Admission-control remote requests and bytes so fixed-price plans have an enforceable upper bound. +11. Partition by workload-aware graph locality, and expose cross-partition semantics rather than hiding them. +12. Publish qualified wins per workload cell; never promise a universal tenfold advantage. + +## 9. Evidence gaps to close before publication + +- Exact current version and release date. +- Exact license text for the benchmarked artifact. +- Storage bytes per node/edge/property on all standard datasets. +- Stable-edge-ID and parallel-edge semantics. +- Isolation litmus results and commit acknowledgement point. +- Crash recovery time versus dirty WAL size. +- Supernode behavior and maximum tested degree. +- Cold-start metadata and request count. +- Distributed cross-partition query amplification. +- Peak memory under skew, cancellation, and overload. +- Background compaction/GC effect on tail latency. +- Full load/index/checkpoint/backup resource cost. +- Reproducible largest-scale result. +- Independent or audited benchmark evidence. + +## 10. Primary and official sources + +- [2026 introduction](https://hugegraph.apache.org/docs/introduction/) +- [Architecture](https://hugegraph.apache.org/docs/guides/architectural/) +- [FAQ and scale guidance](https://hugegraph.apache.org/docs/guides/faq/) +- [Source repository](https://github.com/apache/hugegraph) +- [LDBC SNB Interactive and audited disclosures](https://ldbcouncil.org/benchmarks/snb/interactive/) +- [LDBC Graphalytics](https://ldbcouncil.org/benchmarks/graphalytics/) +- [SoK: The Faults in our Graph Benchmarks](https://arxiv.org/abs/2404.00766) + +## 11. Source-handling rules + +- Official documentation and source are evidence for implemented or declared behavior, not independent performance. +- A vendor benchmark is labeled vendor claim until the harness reproduces it. +- A peer-reviewed paper establishes only the version, configuration, and workload it evaluated. +- Search snippets, comparison sites, and unsourced blogs are discovery aids, not final evidence. +- Unknown is a valid result and creates a concrete experiment or source-inspection task. +- All web facts are rechecked at benchmark freeze because this corpus is current only through the research date. + +## 12. Reproduction record template + +- engine: `Apache HugeGraph` +- version: `TBD at benchmark freeze` +- artifact digest: `TBD` +- source commit: `TBD or managed-service N/A` +- edition/license: `TBD` +- query language/version: `TBD` +- storage and durability mode: `TBD` +- cluster and replication: `TBD` +- CPU/RAM/NVMe/network: `TBD` +- OS/kernel/filesystem: `TBD` +- dataset URI and digest: `TBD` +- loader command and duration: `TBD` +- physical bytes by category: `TBD` +- tuning file: `TBD` +- query corpus commit: `TBD` +- raw result URI/digest: `TBD` +- profiler/trace URI: `TBD` +- correctness status: `TBD` +- reviewer and rerun date: `TBD` diff --git a/docs/research/engine-apache_jena_tdb2.md b/docs/research/engine-apache_jena_tdb2.md new file mode 100644 index 0000000..53b7412 --- /dev/null +++ b/docs/research/engine-apache_jena_tdb2.md @@ -0,0 +1,886 @@ +# Apache Jena TDB2: 2026 deep technical and competitive specification + +Research cut: `2026-08-08` +Status: evidence-backed competitor audit; not a vendor endorsement +Family: `embedded RDF store` +Evidence convention: **Observed/official**, **Vendor claim**, **Research inference**, **Unknown**, **Qualification target**. + +## 1. Decision summary + +TDB2 is a valuable compact local-store reference for CoW MVCC, dictionary IDs, and tuple permutations. + +This document answers two questions: what this engine actually proves in 2026, and what zu must build or measure to earn a defensible advantage. A missing public detail remains unknown; it is never silently filled with a favorable assumption. + +### Snapshot card + +- Lifecycle: active Apache project. +- Data model: RDF triples and quads. +- Query surface: SPARQL 1.1 and Jena APIs. +- Persistent layout: custom node table plus multiple B+tree tuple indexes; memory-mapped files. +- Execution: statistics-based basic-graph-pattern optimization. +- Transactions: serializable ACID; copy-on-write MVCC; multiple readers and one writer. +- Distribution: single JVM; Fuseki provides network access, not distributed storage. +- Object-storage posture: not S3-native. +- License/commercial boundary: Apache-2.0. +- Scale evidence: single-node and filesystem-bound. +- Benchmark posture: strong correctness/reference baseline for RDF, not PB latency competitor. + +### Facts that materially affect comparison + +- F01 — RDF terms map to eight-byte NodeIds with selected scalar values inlined. +- F02 — Triples and quads are stored as full tuple indexes rather than a heap plus secondary indexes. +- F03 — TDB2 only permits transactional operation. +- F04 — One JVM owns a database directory to avoid corruption. +- F05 — Compaction creates numbered complete generations. + +### Bottom-line fit against zu's target + +- Very-low latency: compare hot point and bounded traversal paths; never extrapolate from scans or algorithms. +- Very-low resources: charge resident set, page cache, remote cache, background services, and replicas. +- Distributed: distinguish read replication, partitioned capacity, distributed transactions, and elastic stateless compute. +- Fixed cost: no engine has fixed marginal cost by declaration; admission, batching, and capacity reservations create the bound. +- S3 authority: backups, imports, lake scans, and S3-native demand paging are four different architectures. +- PB / trillion-edge scale: require a capacity derivation plus a run at the largest affordable scale; marketing adjectives do not qualify. +- Tenfold win: can be a per-cell qualification result, never a universal statement across incomparable workloads. + +## 2. Product and ecosystem boundary + +The audited unit is **Apache Jena TDB2** in the exact release, edition, deployment, and durability mode recorded by the harness. The family classification is **embedded RDF store**. The current lifecycle statement is: active Apache project. + +The harness must record binary/container digest, source commit when available, build flags, plugins, license/edition, language mode, storage mode, cluster topology, replication factor, durability settings, cache sizes, thread counts, NUMA policy, kernel, filesystem, cloud region, and all environment variables that affect execution. + +A managed service is not placed in a same-hardware chart. It receives a service-level result with provisioned units, region, public price, and observed provider metrics. A historical engine remains useful for regression but cannot support a claim about beating all current competitors. + +## 3. Architecture reconstruction + +### 3.1 Logical model + +Apache Jena TDB2 exposes RDF triples and quads. The conformance corpus must test nulls, missing properties, labels/types, direction, self-loops, parallel edges, element equality, path equality, bag semantics, ordering, numeric overflow, string collation, temporal values, and schema evolution. + +### 3.2 Language and compiler + +The public query surface is SPARQL 1.1 and Jena APIs. Syntax similarity is not semantic equivalence. Every supported construct needs a result oracle and an unsupported-feature declaration. + +### 3.3 Storage + +The best supported storage summary is: custom node table plus multiple B+tree tuple indexes; memory-mapped files. This statement must be refined from code, format documentation, or provider counters before using it in a performance explanation. + +### 3.4 Execution + +The best supported execution summary is: statistics-based basic-graph-pattern optimization. The benchmark profiler must confirm which runtime and operators actually executed. + +### 3.5 Transactions and recovery + +The public contract is: serializable ACID; copy-on-write MVCC; multiple readers and one writer. Exact acknowledgement, isolation anomalies, recovery bounds, and failover behavior remain separate qualification items. + +### 3.6 Distribution + +The deployment shape is: single JVM; Fuseki provides network access, not distributed storage. Replication is not capacity sharding; sharding is not distributed ACID; stateless readers are not stateless storage. + +### 3.7 Object storage and cost + +The 2026 posture is: not S3-native. The audit distinguishes authoritative live bytes, derived acceleration, backup, import/export, and spill. + +## 4. Forty-control deep audit + +### 4.1 `product_boundary` + +Audit question: What exact executable, edition, and storage mode is the system under test? + +Current assessment: Pin Apache Jena TDB2, lifecycle `active Apache project`, and its edition/mode. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.2 `authority` + +Audit question: Which durable component is the source of truth after every acknowledged write? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.3 `identity` + +Audit question: Are node and edge identities stable across compaction, export, replication, and restore? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.4 `parallel_edges` + +Audit question: Can distinct parallel edges retain properties and trail identity end to end? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.5 `schema` + +Audit question: Is the schema open, closed, optional, inferred, or externally mapped? + +Current assessment: Start from `RDF triples and quads` and test actual constraints. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.6 `labels` + +Audit question: How are multiple labels represented and indexed? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.7 `adjacency_out` + +Audit question: How is outgoing adjacency located, encoded, split, cached, and updated? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.8 `adjacency_in` + +Audit question: Is incoming adjacency first-class, derived, replicated, or a fan-out operation? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.9 `supernodes` + +Audit question: How are million-to-billion-degree vertices represented and scheduled? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.10 `properties` + +Audit question: Are properties co-located, columnar, row-oriented, document-encoded, or remote? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.11 `compression` + +Audit question: Which topology, integer, string, null, and floating encodings are implemented? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.12 `checksums` + +Audit question: What integrity unit is verified on point reads and range reads? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.13 `snapshot` + +Audit question: What exact token pins graph data, schema, statistics, and indexes? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.14 `isolation` + +Audit question: Which anomalies are forbidden at the documented isolation level? + +Current assessment: Published summary: serializable ACID; copy-on-write MVCC; multiple readers and one writer. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.15 `durability` + +Audit question: What device/service acknowledgement is required before commit returns? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.16 `recovery` + +Audit question: What bounds restart work after a clean stop and a crash? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.17 `writer_fencing` + +Audit question: Can a stale writer acknowledge after failover or lease expiry? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.18 `partitioning` + +Audit question: What key determines placement and what happens to cross-partition edges? + +Current assessment: Published distribution summary: single JVM; Fuseki provides network access, not distributed storage. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.19 `rebalancing` + +Audit question: Can placement change online without changing logical identity? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.20 `replication` + +Audit question: Are replicas full, sharded, synchronous, asynchronous, or shared-storage readers? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.21 `optimizer` + +Audit question: Does the optimizer cost graph expansion, joins, network, cache, and remote requests? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.22 `statistics` + +Audit question: Which degree, correlation, path, and property statistics are persistent? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.23 `execution` + +Audit question: Is execution tuple-at-a-time, vectorized, factorized, compiled, matrix, or actor based? + +Current assessment: Expected family: statistics-based basic-graph-pattern optimization. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.24 `recursion` + +Audit question: How are BFS, shortest paths, trails, simple paths, and arbitrary reachability executed? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.25 `parallelism` + +Audit question: How does the engine avoid skew and nested parallelism under mixed queries? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.26 `memory` + +Audit question: Are all variable allocations charged to bounded query and system budgets? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.27 `spill` + +Audit question: Which operators spill, in what format, and with what admission controls? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.28 `cancellation` + +Audit question: Can cancellation stop CPU, local I/O, remote I/O, retries, and prefetch? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.29 `cache` + +Audit question: What is cached, how is it keyed, admitted, pinned, and evicted? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.30 `cold_start` + +Audit question: What metadata and data round trips are required with empty caches? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.31 `object_requests` + +Audit question: Can a query issue one remote request per node, edge, or result row? + +Current assessment: Published object-store posture: not S3-native. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.32 `cost_admission` + +Audit question: Are request, byte, CPU, spill, and result limits enforced before work? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.33 `observability` + +Audit question: Can operators report rows, edges, bytes, requests, stalls, memory, and spill? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.34 `language` + +Audit question: Which GQL/Cypher/SQL-PGQ/Gremlin/SPARQL semantics are declared and tested? + +Current assessment: Declared surface: SPARQL 1.1 and Jena APIs. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.35 `updates` + +Audit question: Are DDL, insert, merge, update, detach delete, and constraints complete? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.36 `bulk_load` + +Audit question: Does bulk load preserve transactional and index invariants? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.37 `backup` + +Audit question: Is backup consistent, incremental, immutable, and restore-tested? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.38 `gc` + +Audit question: How are old snapshots, orphan objects, tombstones, and indexes reclaimed safely? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.39 `security` + +Audit question: Are authentication, authorization, encryption, audit, and tenant isolation in scope? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.40 `operations` + +Audit question: What compaction, upgrade, repair, verification, and capacity procedures exist? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +## 5. Benchmark contract for this engine + +Every case runs correctness first, then isolated latency, then closed-loop concurrency, then open-loop overload. Report median, p95, p99, p99.9, timeout/rejection rate, throughput, CPU-seconds, peak RSS, cache bytes, disk bytes, network bytes, remote requests, write amplification, and estimated monthly cost. + +Warm means all intended engine caches are populated without changing the query parameters. Hot means the exact working set is resident. Cold means process-local, engine, OS, NVMe, and remote cache state are explicitly reset or a fresh namespace is used. Those words are never inferred from repetition count. + +### 5.1 `point_pk` — primary-key node lookup with one projected property + +- Applicability to Apache Jena TDB2: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.2 `point_edge` — stable edge-ID lookup including endpoints and one property + +- Applicability to Apache Jena TDB2: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.3 `degree_1` — degree-one outgoing expansion + +- Applicability to Apache Jena TDB2: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.4 `degree_32` — small adjacency expansion around degree 32 + +- Applicability to Apache Jena TDB2: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.5 `degree_1k` — medium adjacency expansion around degree 1,024 + +- Applicability to Apache Jena TDB2: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.6 `supernode` — range-limited expansion of a ten-million-degree supernode + +- Applicability to Apache Jena TDB2: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.7 `expand_2` — selective two-hop expansion + +- Applicability to Apache Jena TDB2: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.8 `expand_3` — three-hop frontier expansion with duplicate control + +- Applicability to Apache Jena TDB2: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.9 `expand_into` — edge-existence/expand-into between already-bound endpoints + +- Applicability to Apache Jena TDB2: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.10 `multi_edge` — parallel-edge identity and property projection + +- Applicability to Apache Jena TDB2: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.11 `shortest` — bidirectional point-to-point unweighted shortest path + +- Applicability to Apache Jena TDB2: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.12 `weighted` — weighted shortest path with property access + +- Applicability to Apache Jena TDB2: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.13 `var_walk` — bounded variable-length walk + +- Applicability to Apache Jena TDB2: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.14 `trail` — DIFFERENT EDGES trail enumeration + +- Applicability to Apache Jena TDB2: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.15 `simple` — simple-path enumeration with explicit bound + +- Applicability to Apache Jena TDB2: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.16 `triangle` — triangle pattern with worst-case-sensitive join + +- Applicability to Apache Jena TDB2: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.17 `cycle4` — four-cycle pattern + +- Applicability to Apache Jena TDB2: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.18 `star_join` — high-fanout star pattern with property filters + +- Applicability to Apache Jena TDB2: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.19 `optional` — optional match preserving null/bag semantics + +- Applicability to Apache Jena TDB2: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.20 `aggregate` — grouped aggregate after traversal + +- Applicability to Apache Jena TDB2: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.21 `topk` — ordered top-k with late property materialization + +- Applicability to Apache Jena TDB2: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.22 `scan` — full projected property scan + +- Applicability to Apache Jena TDB2: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.23 `selective_scan` — zone/index-pruned selective property scan + +- Applicability to Apache Jena TDB2: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.24 `mixed` — concurrent short reads, complex reads, and updates + +- Applicability to Apache Jena TDB2: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.25 `ingest` — sustained transactional ingest with indexes enabled + +- Applicability to Apache Jena TDB2: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.26 `bulk` — initial bulk load including index/CSR build + +- Applicability to Apache Jena TDB2: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.27 `checkpoint` — checkpoint or compaction while readers remain active + +- Applicability to Apache Jena TDB2: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.28 `recovery` — crash recovery at bounded dirty-log size + +- Applicability to Apache Jena TDB2: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.29 `cold` — same query after clearing engine and OS/cache tiers + +- Applicability to Apache Jena TDB2: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.30 `remote` — same query with authoritative bytes only in object storage + +- Applicability to Apache Jena TDB2: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +## 6. Fairness controls + +- Same logical dataset and update stream; engine-native physical layouts are allowed and disclosed. +- Same result semantics; unsupported queries remain unsupported rather than rewritten into easier questions. +- Same durable acknowledgement class for write comparisons. +- Same number of physical cores and memory limit for self-hosted single-node tests. +- Same aggregate resources and replication fault tolerance for distributed tests. +- Officially recommended tuning may be applied before the freeze and is committed with rationale. +- Query-specific hints are allowed only when equivalent hints are offered to every engine and separately charted. +- Load/build/index time and bytes are first-class results. +- Cold, warm, and hot results are separate charts. +- Managed services use public configurations and cannot borrow hidden same-machine resource claims. +- Failed runs, OOMs, correctness mismatches, and timeouts stay in the dataset. +- Every chart links raw samples and the exact reproduction command. + +## 7. Likely advantages and limits + +The strongest known reason to choose this engine is tied to its family `embedded RDF store`, its execution path `statistics-based basic-graph-pattern optimization`, and its existing ecosystem. The strongest reason to reject it for zu's target is the gap between `not S3-native` and an S3-authoritative, request-budgeted, PB-scale graph service. + +Capacity statement: single-node and filesystem-bound. This is not converted into an edge-count claim without a physical byte model including IDs, both adjacency directions, properties, indexes, MVCC, WAL, replicas, and free space. + +Commercial statement: Apache-2.0. License cost, support cost, and unavailable enterprise capabilities remain visible in TCO and feature tables. + +## 8. Concrete lessons for zu + +1. Keep stable logical node and edge identity independent of row group, CSR slot, shard, and object range. +2. Store forward and reverse adjacency as immutable range-addressable tiles carrying edge IDs. +3. Feed queries adjacency batches and typed vectors; prohibit one storage call per logical element. +4. Use vectorized/factorized execution for property-heavy patterns and dedicated frontier operators for recursion. +5. Cost topology, properties, network, cache certainty, remote requests, and result materialization together. +6. Separate the local embedded profile from the object-authoritative distributed read profile. +7. Fence writers with monotonic epochs and make ambiguous commits reconcilable by transaction ID. +8. Pack small graph tiles into large immutable objects while retaining independent checksums and range offsets. +9. Keep the hot topology working set in RAM/NVMe; batch cold frontier misses into few remote rounds. +10. Admission-control remote requests and bytes so fixed-price plans have an enforceable upper bound. +11. Partition by workload-aware graph locality, and expose cross-partition semantics rather than hiding them. +12. Publish qualified wins per workload cell; never promise a universal tenfold advantage. + +## 9. Evidence gaps to close before publication + +- Exact current version and release date. +- Exact license text for the benchmarked artifact. +- Storage bytes per node/edge/property on all standard datasets. +- Stable-edge-ID and parallel-edge semantics. +- Isolation litmus results and commit acknowledgement point. +- Crash recovery time versus dirty WAL size. +- Supernode behavior and maximum tested degree. +- Cold-start metadata and request count. +- Distributed cross-partition query amplification. +- Peak memory under skew, cancellation, and overload. +- Background compaction/GC effect on tail latency. +- Full load/index/checkpoint/backup resource cost. +- Reproducible largest-scale result. +- Independent or audited benchmark evidence. + +## 10. Primary and official sources + +- [Architecture](https://jena.apache.org/documentation/tdb/architecture.html) +- [Transactions](https://jena.apache.org/documentation/tdb/tdb_transactions.html) +- [Administration](https://jena.apache.org/documentation/tdb2/tdb2_admin.html) +- [Source repository](https://github.com/apache/jena) +- [LDBC SNB Interactive and audited disclosures](https://ldbcouncil.org/benchmarks/snb/interactive/) +- [LDBC Graphalytics](https://ldbcouncil.org/benchmarks/graphalytics/) +- [SoK: The Faults in our Graph Benchmarks](https://arxiv.org/abs/2404.00766) + +## 11. Source-handling rules + +- Official documentation and source are evidence for implemented or declared behavior, not independent performance. +- A vendor benchmark is labeled vendor claim until the harness reproduces it. +- A peer-reviewed paper establishes only the version, configuration, and workload it evaluated. +- Search snippets, comparison sites, and unsourced blogs are discovery aids, not final evidence. +- Unknown is a valid result and creates a concrete experiment or source-inspection task. +- All web facts are rechecked at benchmark freeze because this corpus is current only through the research date. + +## 12. Reproduction record template + +- engine: `Apache Jena TDB2` +- version: `TBD at benchmark freeze` +- artifact digest: `TBD` +- source commit: `TBD or managed-service N/A` +- edition/license: `TBD` +- query language/version: `TBD` +- storage and durability mode: `TBD` +- cluster and replication: `TBD` +- CPU/RAM/NVMe/network: `TBD` +- OS/kernel/filesystem: `TBD` +- dataset URI and digest: `TBD` +- loader command and duration: `TBD` +- physical bytes by category: `TBD` +- tuning file: `TBD` +- query corpus commit: `TBD` +- raw result URI/digest: `TBD` +- profiler/trace URI: `TBD` +- correctness status: `TBD` +- reviewer and rerun date: `TBD` diff --git a/docs/research/engine-arangodb.md b/docs/research/engine-arangodb.md new file mode 100644 index 0000000..0dcb0da --- /dev/null +++ b/docs/research/engine-arangodb.md @@ -0,0 +1,885 @@ +# ArangoDB: 2026 deep technical and competitive specification + +Research cut: `2026-08-08` +Status: evidence-backed competitor audit; not a vendor endorsement +Family: `native multi-model database` +Evidence convention: **Observed/official**, **Vendor claim**, **Research inference**, **Unknown**, **Qualification target**. + +## 1. Decision summary + +ArangoDB shows the benefit and cost of multi-model integration; SmartGraph locality is a mandatory partitioning comparison. + +This document answers two questions: what this engine actually proves in 2026, and what zu must build or measure to earn a defensible advantage. A missing public detail remains unknown; it is never silently filled with a favorable assumption. + +### Snapshot card + +- Lifecycle: active. +- Data model: document, key/value, graph, vector. +- Query surface: AQL. +- Persistent layout: RocksDB-backed collections with edge documents and indexes. +- Execution: AQL optimizer and cluster execution for traversal, joins, search, and documents. +- Transactions: ACID with scope/cluster caveats defined by edition and transaction pattern. +- Distribution: CP master/master cluster with coordinators, DB-Servers, agency; SmartGraphs optimize locality. +- Object-storage posture: not S3-native live serving. +- License/commercial boundary: source-available/community and commercial Enterprise terms; pin version. +- Scale evidence: horizontal document/graph scale; efficient graph scale depends on sharding locality. +- Benchmark posture: Community General Graph and Enterprise SmartGraph are distinct baselines. + +### Facts that materially affect comparison + +- F01 — SmartGraphs co-locate vertices and intra-partition edges by a chosen attribute. +- F02 — Satellite collections replicate small shared data to DB-Servers. +- F03 — Disjoint SmartGraphs prohibit cross-partition edges for fully local traversal. +- F04 — The smart sharding attribute and shard count are effectively model commitments. +- F05 — A graph benchmark that ignores cross-shard edge ratio hides the central design tradeoff. + +### Bottom-line fit against zu's target + +- Very-low latency: compare hot point and bounded traversal paths; never extrapolate from scans or algorithms. +- Very-low resources: charge resident set, page cache, remote cache, background services, and replicas. +- Distributed: distinguish read replication, partitioned capacity, distributed transactions, and elastic stateless compute. +- Fixed cost: no engine has fixed marginal cost by declaration; admission, batching, and capacity reservations create the bound. +- S3 authority: backups, imports, lake scans, and S3-native demand paging are four different architectures. +- PB / trillion-edge scale: require a capacity derivation plus a run at the largest affordable scale; marketing adjectives do not qualify. +- Tenfold win: can be a per-cell qualification result, never a universal statement across incomparable workloads. + +## 2. Product and ecosystem boundary + +The audited unit is **ArangoDB** in the exact release, edition, deployment, and durability mode recorded by the harness. The family classification is **native multi-model database**. The current lifecycle statement is: active. + +The harness must record binary/container digest, source commit when available, build flags, plugins, license/edition, language mode, storage mode, cluster topology, replication factor, durability settings, cache sizes, thread counts, NUMA policy, kernel, filesystem, cloud region, and all environment variables that affect execution. + +A managed service is not placed in a same-hardware chart. It receives a service-level result with provisioned units, region, public price, and observed provider metrics. A historical engine remains useful for regression but cannot support a claim about beating all current competitors. + +## 3. Architecture reconstruction + +### 3.1 Logical model + +ArangoDB exposes document, key/value, graph, vector. The conformance corpus must test nulls, missing properties, labels/types, direction, self-loops, parallel edges, element equality, path equality, bag semantics, ordering, numeric overflow, string collation, temporal values, and schema evolution. + +### 3.2 Language and compiler + +The public query surface is AQL. Syntax similarity is not semantic equivalence. Every supported construct needs a result oracle and an unsupported-feature declaration. + +### 3.3 Storage + +The best supported storage summary is: RocksDB-backed collections with edge documents and indexes. This statement must be refined from code, format documentation, or provider counters before using it in a performance explanation. + +### 3.4 Execution + +The best supported execution summary is: AQL optimizer and cluster execution for traversal, joins, search, and documents. The benchmark profiler must confirm which runtime and operators actually executed. + +### 3.5 Transactions and recovery + +The public contract is: ACID with scope/cluster caveats defined by edition and transaction pattern. Exact acknowledgement, isolation anomalies, recovery bounds, and failover behavior remain separate qualification items. + +### 3.6 Distribution + +The deployment shape is: CP master/master cluster with coordinators, DB-Servers, agency; SmartGraphs optimize locality. Replication is not capacity sharding; sharding is not distributed ACID; stateless readers are not stateless storage. + +### 3.7 Object storage and cost + +The 2026 posture is: not S3-native live serving. The audit distinguishes authoritative live bytes, derived acceleration, backup, import/export, and spill. + +## 4. Forty-control deep audit + +### 4.1 `product_boundary` + +Audit question: What exact executable, edition, and storage mode is the system under test? + +Current assessment: Pin ArangoDB, lifecycle `active`, and its edition/mode. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.2 `authority` + +Audit question: Which durable component is the source of truth after every acknowledged write? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.3 `identity` + +Audit question: Are node and edge identities stable across compaction, export, replication, and restore? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.4 `parallel_edges` + +Audit question: Can distinct parallel edges retain properties and trail identity end to end? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.5 `schema` + +Audit question: Is the schema open, closed, optional, inferred, or externally mapped? + +Current assessment: Start from `document, key/value, graph, vector` and test actual constraints. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.6 `labels` + +Audit question: How are multiple labels represented and indexed? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.7 `adjacency_out` + +Audit question: How is outgoing adjacency located, encoded, split, cached, and updated? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.8 `adjacency_in` + +Audit question: Is incoming adjacency first-class, derived, replicated, or a fan-out operation? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.9 `supernodes` + +Audit question: How are million-to-billion-degree vertices represented and scheduled? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.10 `properties` + +Audit question: Are properties co-located, columnar, row-oriented, document-encoded, or remote? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.11 `compression` + +Audit question: Which topology, integer, string, null, and floating encodings are implemented? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.12 `checksums` + +Audit question: What integrity unit is verified on point reads and range reads? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.13 `snapshot` + +Audit question: What exact token pins graph data, schema, statistics, and indexes? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.14 `isolation` + +Audit question: Which anomalies are forbidden at the documented isolation level? + +Current assessment: Published summary: ACID with scope/cluster caveats defined by edition and transaction pattern. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.15 `durability` + +Audit question: What device/service acknowledgement is required before commit returns? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.16 `recovery` + +Audit question: What bounds restart work after a clean stop and a crash? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.17 `writer_fencing` + +Audit question: Can a stale writer acknowledge after failover or lease expiry? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.18 `partitioning` + +Audit question: What key determines placement and what happens to cross-partition edges? + +Current assessment: Published distribution summary: CP master/master cluster with coordinators, DB-Servers, agency; SmartGraphs optimize locality. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.19 `rebalancing` + +Audit question: Can placement change online without changing logical identity? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.20 `replication` + +Audit question: Are replicas full, sharded, synchronous, asynchronous, or shared-storage readers? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.21 `optimizer` + +Audit question: Does the optimizer cost graph expansion, joins, network, cache, and remote requests? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.22 `statistics` + +Audit question: Which degree, correlation, path, and property statistics are persistent? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.23 `execution` + +Audit question: Is execution tuple-at-a-time, vectorized, factorized, compiled, matrix, or actor based? + +Current assessment: Expected family: AQL optimizer and cluster execution for traversal, joins, search, and documents. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.24 `recursion` + +Audit question: How are BFS, shortest paths, trails, simple paths, and arbitrary reachability executed? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.25 `parallelism` + +Audit question: How does the engine avoid skew and nested parallelism under mixed queries? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.26 `memory` + +Audit question: Are all variable allocations charged to bounded query and system budgets? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.27 `spill` + +Audit question: Which operators spill, in what format, and with what admission controls? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.28 `cancellation` + +Audit question: Can cancellation stop CPU, local I/O, remote I/O, retries, and prefetch? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.29 `cache` + +Audit question: What is cached, how is it keyed, admitted, pinned, and evicted? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.30 `cold_start` + +Audit question: What metadata and data round trips are required with empty caches? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.31 `object_requests` + +Audit question: Can a query issue one remote request per node, edge, or result row? + +Current assessment: Published object-store posture: not S3-native live serving. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.32 `cost_admission` + +Audit question: Are request, byte, CPU, spill, and result limits enforced before work? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.33 `observability` + +Audit question: Can operators report rows, edges, bytes, requests, stalls, memory, and spill? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.34 `language` + +Audit question: Which GQL/Cypher/SQL-PGQ/Gremlin/SPARQL semantics are declared and tested? + +Current assessment: Declared surface: AQL. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.35 `updates` + +Audit question: Are DDL, insert, merge, update, detach delete, and constraints complete? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.36 `bulk_load` + +Audit question: Does bulk load preserve transactional and index invariants? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.37 `backup` + +Audit question: Is backup consistent, incremental, immutable, and restore-tested? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.38 `gc` + +Audit question: How are old snapshots, orphan objects, tombstones, and indexes reclaimed safely? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.39 `security` + +Audit question: Are authentication, authorization, encryption, audit, and tenant isolation in scope? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.40 `operations` + +Audit question: What compaction, upgrade, repair, verification, and capacity procedures exist? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +## 5. Benchmark contract for this engine + +Every case runs correctness first, then isolated latency, then closed-loop concurrency, then open-loop overload. Report median, p95, p99, p99.9, timeout/rejection rate, throughput, CPU-seconds, peak RSS, cache bytes, disk bytes, network bytes, remote requests, write amplification, and estimated monthly cost. + +Warm means all intended engine caches are populated without changing the query parameters. Hot means the exact working set is resident. Cold means process-local, engine, OS, NVMe, and remote cache state are explicitly reset or a fresh namespace is used. Those words are never inferred from repetition count. + +### 5.1 `point_pk` — primary-key node lookup with one projected property + +- Applicability to ArangoDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.2 `point_edge` — stable edge-ID lookup including endpoints and one property + +- Applicability to ArangoDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.3 `degree_1` — degree-one outgoing expansion + +- Applicability to ArangoDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.4 `degree_32` — small adjacency expansion around degree 32 + +- Applicability to ArangoDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.5 `degree_1k` — medium adjacency expansion around degree 1,024 + +- Applicability to ArangoDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.6 `supernode` — range-limited expansion of a ten-million-degree supernode + +- Applicability to ArangoDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.7 `expand_2` — selective two-hop expansion + +- Applicability to ArangoDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.8 `expand_3` — three-hop frontier expansion with duplicate control + +- Applicability to ArangoDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.9 `expand_into` — edge-existence/expand-into between already-bound endpoints + +- Applicability to ArangoDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.10 `multi_edge` — parallel-edge identity and property projection + +- Applicability to ArangoDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.11 `shortest` — bidirectional point-to-point unweighted shortest path + +- Applicability to ArangoDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.12 `weighted` — weighted shortest path with property access + +- Applicability to ArangoDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.13 `var_walk` — bounded variable-length walk + +- Applicability to ArangoDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.14 `trail` — DIFFERENT EDGES trail enumeration + +- Applicability to ArangoDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.15 `simple` — simple-path enumeration with explicit bound + +- Applicability to ArangoDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.16 `triangle` — triangle pattern with worst-case-sensitive join + +- Applicability to ArangoDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.17 `cycle4` — four-cycle pattern + +- Applicability to ArangoDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.18 `star_join` — high-fanout star pattern with property filters + +- Applicability to ArangoDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.19 `optional` — optional match preserving null/bag semantics + +- Applicability to ArangoDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.20 `aggregate` — grouped aggregate after traversal + +- Applicability to ArangoDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.21 `topk` — ordered top-k with late property materialization + +- Applicability to ArangoDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.22 `scan` — full projected property scan + +- Applicability to ArangoDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.23 `selective_scan` — zone/index-pruned selective property scan + +- Applicability to ArangoDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.24 `mixed` — concurrent short reads, complex reads, and updates + +- Applicability to ArangoDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.25 `ingest` — sustained transactional ingest with indexes enabled + +- Applicability to ArangoDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.26 `bulk` — initial bulk load including index/CSR build + +- Applicability to ArangoDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.27 `checkpoint` — checkpoint or compaction while readers remain active + +- Applicability to ArangoDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.28 `recovery` — crash recovery at bounded dirty-log size + +- Applicability to ArangoDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.29 `cold` — same query after clearing engine and OS/cache tiers + +- Applicability to ArangoDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.30 `remote` — same query with authoritative bytes only in object storage + +- Applicability to ArangoDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +## 6. Fairness controls + +- Same logical dataset and update stream; engine-native physical layouts are allowed and disclosed. +- Same result semantics; unsupported queries remain unsupported rather than rewritten into easier questions. +- Same durable acknowledgement class for write comparisons. +- Same number of physical cores and memory limit for self-hosted single-node tests. +- Same aggregate resources and replication fault tolerance for distributed tests. +- Officially recommended tuning may be applied before the freeze and is committed with rationale. +- Query-specific hints are allowed only when equivalent hints are offered to every engine and separately charted. +- Load/build/index time and bytes are first-class results. +- Cold, warm, and hot results are separate charts. +- Managed services use public configurations and cannot borrow hidden same-machine resource claims. +- Failed runs, OOMs, correctness mismatches, and timeouts stay in the dataset. +- Every chart links raw samples and the exact reproduction command. + +## 7. Likely advantages and limits + +The strongest known reason to choose this engine is tied to its family `native multi-model database`, its execution path `AQL optimizer and cluster execution for traversal, joins, search, and documents`, and its existing ecosystem. The strongest reason to reject it for zu's target is the gap between `not S3-native live serving` and an S3-authoritative, request-budgeted, PB-scale graph service. + +Capacity statement: horizontal document/graph scale; efficient graph scale depends on sharding locality. This is not converted into an edge-count claim without a physical byte model including IDs, both adjacency directions, properties, indexes, MVCC, WAL, replicas, and free space. + +Commercial statement: source-available/community and commercial Enterprise terms; pin version. License cost, support cost, and unavailable enterprise capabilities remain visible in TCO and feature tables. + +## 8. Concrete lessons for zu + +1. Keep stable logical node and edge identity independent of row group, CSR slot, shard, and object range. +2. Store forward and reverse adjacency as immutable range-addressable tiles carrying edge IDs. +3. Feed queries adjacency batches and typed vectors; prohibit one storage call per logical element. +4. Use vectorized/factorized execution for property-heavy patterns and dedicated frontier operators for recursion. +5. Cost topology, properties, network, cache certainty, remote requests, and result materialization together. +6. Separate the local embedded profile from the object-authoritative distributed read profile. +7. Fence writers with monotonic epochs and make ambiguous commits reconcilable by transaction ID. +8. Pack small graph tiles into large immutable objects while retaining independent checksums and range offsets. +9. Keep the hot topology working set in RAM/NVMe; batch cold frontier misses into few remote rounds. +10. Admission-control remote requests and bytes so fixed-price plans have an enforceable upper bound. +11. Partition by workload-aware graph locality, and expose cross-partition semantics rather than hiding them. +12. Publish qualified wins per workload cell; never promise a universal tenfold advantage. + +## 9. Evidence gaps to close before publication + +- Exact current version and release date. +- Exact license text for the benchmarked artifact. +- Storage bytes per node/edge/property on all standard datasets. +- Stable-edge-ID and parallel-edge semantics. +- Isolation litmus results and commit acknowledgement point. +- Crash recovery time versus dirty WAL size. +- Supernode behavior and maximum tested degree. +- Cold-start metadata and request count. +- Distributed cross-partition query amplification. +- Peak memory under skew, cancellation, and overload. +- Background compaction/GC effect on tail latency. +- Full load/index/checkpoint/backup resource cost. +- Reproducible largest-scale result. +- Independent or audited benchmark evidence. + +## 10. Primary and official sources + +- [Cluster architecture](https://docs.arango.ai/arangodb/stable/deploy/cluster/) +- [SmartGraphs](https://docs.arango.ai/arangodb/stable/graphs/smartgraphs/) +- [Source repository](https://github.com/arangodb/arangodb) +- [LDBC SNB Interactive and audited disclosures](https://ldbcouncil.org/benchmarks/snb/interactive/) +- [LDBC Graphalytics](https://ldbcouncil.org/benchmarks/graphalytics/) +- [SoK: The Faults in our Graph Benchmarks](https://arxiv.org/abs/2404.00766) + +## 11. Source-handling rules + +- Official documentation and source are evidence for implemented or declared behavior, not independent performance. +- A vendor benchmark is labeled vendor claim until the harness reproduces it. +- A peer-reviewed paper establishes only the version, configuration, and workload it evaluated. +- Search snippets, comparison sites, and unsourced blogs are discovery aids, not final evidence. +- Unknown is a valid result and creates a concrete experiment or source-inspection task. +- All web facts are rechecked at benchmark freeze because this corpus is current only through the research date. + +## 12. Reproduction record template + +- engine: `ArangoDB` +- version: `TBD at benchmark freeze` +- artifact digest: `TBD` +- source commit: `TBD or managed-service N/A` +- edition/license: `TBD` +- query language/version: `TBD` +- storage and durability mode: `TBD` +- cluster and replication: `TBD` +- CPU/RAM/NVMe/network: `TBD` +- OS/kernel/filesystem: `TBD` +- dataset URI and digest: `TBD` +- loader command and duration: `TBD` +- physical bytes by category: `TBD` +- tuning file: `TBD` +- query corpus commit: `TBD` +- raw result URI/digest: `TBD` +- profiler/trace URI: `TBD` +- correctness status: `TBD` +- reviewer and rerun date: `TBD` diff --git a/docs/research/engine-arcadedb.md b/docs/research/engine-arcadedb.md new file mode 100644 index 0000000..dc1baf4 --- /dev/null +++ b/docs/research/engine-arcadedb.md @@ -0,0 +1,885 @@ +# ArcadeDB: 2026 deep technical and competitive specification + +Research cut: `2026-08-08` +Status: evidence-backed competitor audit; not a vendor endorsement +Family: `multi-model native graph database` +Evidence convention: **Observed/official**, **Vendor claim**, **Research inference**, **Unknown**, **Qualification target**. + +## 1. Decision summary + +ArcadeDB is a strong low-resource JVM/multi-model comparison and a fast-moving 2026 target. + +This document answers two questions: what this engine actually proves in 2026, and what zu must build or measure to earn a defensible advantage. A missing public detail remains unknown; it is never silently filled with a favorable assumption. + +### Snapshot card + +- Lifecycle: active 26.x. +- Data model: graph, document, key/value, vector, time-series, geospatial. +- Query surface: SQL, Cypher, Gremlin, GraphQL and wire-protocol compatibility subsets. +- Persistent layout: custom low-level Java storage with physical graph links and transactional indexes. +- Execution: parallel SQL plus native traversal and multi-model operators. +- Transactions: ACID local; Raft HA from 26.4.1. +- Distribution: leader/replica Raft HA scales reads and availability, not sharded capacity. +- Object-storage posture: not S3-native. +- License/commercial boundary: Apache-2.0. +- Scale evidence: single-database capacity plus replicated copies; no PB claim. +- Benchmark posture: benchmark embedded and server modes; disclose protocol translation. + +### Facts that materially affect comparison + +- F01 — ArcadeDB is a conceptual successor/fork lineage from OrientDB but uses a new engine. +- F02 — Official docs describe graph edges as physical links enabling constant-hop lookup. +- F03 — All models share one transaction and one storage engine. +- F04 — Apache Ratis replaced the previous HA protocol in 26.4.1. +- F05 — Six query/protocol surfaces vary in completeness and require conformance, not checkbox parity. + +### Bottom-line fit against zu's target + +- Very-low latency: compare hot point and bounded traversal paths; never extrapolate from scans or algorithms. +- Very-low resources: charge resident set, page cache, remote cache, background services, and replicas. +- Distributed: distinguish read replication, partitioned capacity, distributed transactions, and elastic stateless compute. +- Fixed cost: no engine has fixed marginal cost by declaration; admission, batching, and capacity reservations create the bound. +- S3 authority: backups, imports, lake scans, and S3-native demand paging are four different architectures. +- PB / trillion-edge scale: require a capacity derivation plus a run at the largest affordable scale; marketing adjectives do not qualify. +- Tenfold win: can be a per-cell qualification result, never a universal statement across incomparable workloads. + +## 2. Product and ecosystem boundary + +The audited unit is **ArcadeDB** in the exact release, edition, deployment, and durability mode recorded by the harness. The family classification is **multi-model native graph database**. The current lifecycle statement is: active 26.x. + +The harness must record binary/container digest, source commit when available, build flags, plugins, license/edition, language mode, storage mode, cluster topology, replication factor, durability settings, cache sizes, thread counts, NUMA policy, kernel, filesystem, cloud region, and all environment variables that affect execution. + +A managed service is not placed in a same-hardware chart. It receives a service-level result with provisioned units, region, public price, and observed provider metrics. A historical engine remains useful for regression but cannot support a claim about beating all current competitors. + +## 3. Architecture reconstruction + +### 3.1 Logical model + +ArcadeDB exposes graph, document, key/value, vector, time-series, geospatial. The conformance corpus must test nulls, missing properties, labels/types, direction, self-loops, parallel edges, element equality, path equality, bag semantics, ordering, numeric overflow, string collation, temporal values, and schema evolution. + +### 3.2 Language and compiler + +The public query surface is SQL, Cypher, Gremlin, GraphQL and wire-protocol compatibility subsets. Syntax similarity is not semantic equivalence. Every supported construct needs a result oracle and an unsupported-feature declaration. + +### 3.3 Storage + +The best supported storage summary is: custom low-level Java storage with physical graph links and transactional indexes. This statement must be refined from code, format documentation, or provider counters before using it in a performance explanation. + +### 3.4 Execution + +The best supported execution summary is: parallel SQL plus native traversal and multi-model operators. The benchmark profiler must confirm which runtime and operators actually executed. + +### 3.5 Transactions and recovery + +The public contract is: ACID local; Raft HA from 26.4.1. Exact acknowledgement, isolation anomalies, recovery bounds, and failover behavior remain separate qualification items. + +### 3.6 Distribution + +The deployment shape is: leader/replica Raft HA scales reads and availability, not sharded capacity. Replication is not capacity sharding; sharding is not distributed ACID; stateless readers are not stateless storage. + +### 3.7 Object storage and cost + +The 2026 posture is: not S3-native. The audit distinguishes authoritative live bytes, derived acceleration, backup, import/export, and spill. + +## 4. Forty-control deep audit + +### 4.1 `product_boundary` + +Audit question: What exact executable, edition, and storage mode is the system under test? + +Current assessment: Pin ArcadeDB, lifecycle `active 26.x`, and its edition/mode. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.2 `authority` + +Audit question: Which durable component is the source of truth after every acknowledged write? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.3 `identity` + +Audit question: Are node and edge identities stable across compaction, export, replication, and restore? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.4 `parallel_edges` + +Audit question: Can distinct parallel edges retain properties and trail identity end to end? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.5 `schema` + +Audit question: Is the schema open, closed, optional, inferred, or externally mapped? + +Current assessment: Start from `graph, document, key/value, vector, time-series, geospatial` and test actual constraints. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.6 `labels` + +Audit question: How are multiple labels represented and indexed? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.7 `adjacency_out` + +Audit question: How is outgoing adjacency located, encoded, split, cached, and updated? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.8 `adjacency_in` + +Audit question: Is incoming adjacency first-class, derived, replicated, or a fan-out operation? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.9 `supernodes` + +Audit question: How are million-to-billion-degree vertices represented and scheduled? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.10 `properties` + +Audit question: Are properties co-located, columnar, row-oriented, document-encoded, or remote? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.11 `compression` + +Audit question: Which topology, integer, string, null, and floating encodings are implemented? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.12 `checksums` + +Audit question: What integrity unit is verified on point reads and range reads? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.13 `snapshot` + +Audit question: What exact token pins graph data, schema, statistics, and indexes? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.14 `isolation` + +Audit question: Which anomalies are forbidden at the documented isolation level? + +Current assessment: Published summary: ACID local; Raft HA from 26.4.1. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.15 `durability` + +Audit question: What device/service acknowledgement is required before commit returns? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.16 `recovery` + +Audit question: What bounds restart work after a clean stop and a crash? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.17 `writer_fencing` + +Audit question: Can a stale writer acknowledge after failover or lease expiry? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.18 `partitioning` + +Audit question: What key determines placement and what happens to cross-partition edges? + +Current assessment: Published distribution summary: leader/replica Raft HA scales reads and availability, not sharded capacity. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.19 `rebalancing` + +Audit question: Can placement change online without changing logical identity? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.20 `replication` + +Audit question: Are replicas full, sharded, synchronous, asynchronous, or shared-storage readers? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.21 `optimizer` + +Audit question: Does the optimizer cost graph expansion, joins, network, cache, and remote requests? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.22 `statistics` + +Audit question: Which degree, correlation, path, and property statistics are persistent? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.23 `execution` + +Audit question: Is execution tuple-at-a-time, vectorized, factorized, compiled, matrix, or actor based? + +Current assessment: Expected family: parallel SQL plus native traversal and multi-model operators. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.24 `recursion` + +Audit question: How are BFS, shortest paths, trails, simple paths, and arbitrary reachability executed? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.25 `parallelism` + +Audit question: How does the engine avoid skew and nested parallelism under mixed queries? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.26 `memory` + +Audit question: Are all variable allocations charged to bounded query and system budgets? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.27 `spill` + +Audit question: Which operators spill, in what format, and with what admission controls? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.28 `cancellation` + +Audit question: Can cancellation stop CPU, local I/O, remote I/O, retries, and prefetch? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.29 `cache` + +Audit question: What is cached, how is it keyed, admitted, pinned, and evicted? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.30 `cold_start` + +Audit question: What metadata and data round trips are required with empty caches? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.31 `object_requests` + +Audit question: Can a query issue one remote request per node, edge, or result row? + +Current assessment: Published object-store posture: not S3-native. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.32 `cost_admission` + +Audit question: Are request, byte, CPU, spill, and result limits enforced before work? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.33 `observability` + +Audit question: Can operators report rows, edges, bytes, requests, stalls, memory, and spill? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.34 `language` + +Audit question: Which GQL/Cypher/SQL-PGQ/Gremlin/SPARQL semantics are declared and tested? + +Current assessment: Declared surface: SQL, Cypher, Gremlin, GraphQL and wire-protocol compatibility subsets. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.35 `updates` + +Audit question: Are DDL, insert, merge, update, detach delete, and constraints complete? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.36 `bulk_load` + +Audit question: Does bulk load preserve transactional and index invariants? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.37 `backup` + +Audit question: Is backup consistent, incremental, immutable, and restore-tested? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.38 `gc` + +Audit question: How are old snapshots, orphan objects, tombstones, and indexes reclaimed safely? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.39 `security` + +Audit question: Are authentication, authorization, encryption, audit, and tenant isolation in scope? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.40 `operations` + +Audit question: What compaction, upgrade, repair, verification, and capacity procedures exist? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +## 5. Benchmark contract for this engine + +Every case runs correctness first, then isolated latency, then closed-loop concurrency, then open-loop overload. Report median, p95, p99, p99.9, timeout/rejection rate, throughput, CPU-seconds, peak RSS, cache bytes, disk bytes, network bytes, remote requests, write amplification, and estimated monthly cost. + +Warm means all intended engine caches are populated without changing the query parameters. Hot means the exact working set is resident. Cold means process-local, engine, OS, NVMe, and remote cache state are explicitly reset or a fresh namespace is used. Those words are never inferred from repetition count. + +### 5.1 `point_pk` — primary-key node lookup with one projected property + +- Applicability to ArcadeDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.2 `point_edge` — stable edge-ID lookup including endpoints and one property + +- Applicability to ArcadeDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.3 `degree_1` — degree-one outgoing expansion + +- Applicability to ArcadeDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.4 `degree_32` — small adjacency expansion around degree 32 + +- Applicability to ArcadeDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.5 `degree_1k` — medium adjacency expansion around degree 1,024 + +- Applicability to ArcadeDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.6 `supernode` — range-limited expansion of a ten-million-degree supernode + +- Applicability to ArcadeDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.7 `expand_2` — selective two-hop expansion + +- Applicability to ArcadeDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.8 `expand_3` — three-hop frontier expansion with duplicate control + +- Applicability to ArcadeDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.9 `expand_into` — edge-existence/expand-into between already-bound endpoints + +- Applicability to ArcadeDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.10 `multi_edge` — parallel-edge identity and property projection + +- Applicability to ArcadeDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.11 `shortest` — bidirectional point-to-point unweighted shortest path + +- Applicability to ArcadeDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.12 `weighted` — weighted shortest path with property access + +- Applicability to ArcadeDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.13 `var_walk` — bounded variable-length walk + +- Applicability to ArcadeDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.14 `trail` — DIFFERENT EDGES trail enumeration + +- Applicability to ArcadeDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.15 `simple` — simple-path enumeration with explicit bound + +- Applicability to ArcadeDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.16 `triangle` — triangle pattern with worst-case-sensitive join + +- Applicability to ArcadeDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.17 `cycle4` — four-cycle pattern + +- Applicability to ArcadeDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.18 `star_join` — high-fanout star pattern with property filters + +- Applicability to ArcadeDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.19 `optional` — optional match preserving null/bag semantics + +- Applicability to ArcadeDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.20 `aggregate` — grouped aggregate after traversal + +- Applicability to ArcadeDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.21 `topk` — ordered top-k with late property materialization + +- Applicability to ArcadeDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.22 `scan` — full projected property scan + +- Applicability to ArcadeDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.23 `selective_scan` — zone/index-pruned selective property scan + +- Applicability to ArcadeDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.24 `mixed` — concurrent short reads, complex reads, and updates + +- Applicability to ArcadeDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.25 `ingest` — sustained transactional ingest with indexes enabled + +- Applicability to ArcadeDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.26 `bulk` — initial bulk load including index/CSR build + +- Applicability to ArcadeDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.27 `checkpoint` — checkpoint or compaction while readers remain active + +- Applicability to ArcadeDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.28 `recovery` — crash recovery at bounded dirty-log size + +- Applicability to ArcadeDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.29 `cold` — same query after clearing engine and OS/cache tiers + +- Applicability to ArcadeDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.30 `remote` — same query with authoritative bytes only in object storage + +- Applicability to ArcadeDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +## 6. Fairness controls + +- Same logical dataset and update stream; engine-native physical layouts are allowed and disclosed. +- Same result semantics; unsupported queries remain unsupported rather than rewritten into easier questions. +- Same durable acknowledgement class for write comparisons. +- Same number of physical cores and memory limit for self-hosted single-node tests. +- Same aggregate resources and replication fault tolerance for distributed tests. +- Officially recommended tuning may be applied before the freeze and is committed with rationale. +- Query-specific hints are allowed only when equivalent hints are offered to every engine and separately charted. +- Load/build/index time and bytes are first-class results. +- Cold, warm, and hot results are separate charts. +- Managed services use public configurations and cannot borrow hidden same-machine resource claims. +- Failed runs, OOMs, correctness mismatches, and timeouts stay in the dataset. +- Every chart links raw samples and the exact reproduction command. + +## 7. Likely advantages and limits + +The strongest known reason to choose this engine is tied to its family `multi-model native graph database`, its execution path `parallel SQL plus native traversal and multi-model operators`, and its existing ecosystem. The strongest reason to reject it for zu's target is the gap between `not S3-native` and an S3-authoritative, request-budgeted, PB-scale graph service. + +Capacity statement: single-database capacity plus replicated copies; no PB claim. This is not converted into an edge-count claim without a physical byte model including IDs, both adjacency directions, properties, indexes, MVCC, WAL, replicas, and free space. + +Commercial statement: Apache-2.0. License cost, support cost, and unavailable enterprise capabilities remain visible in TCO and feature tables. + +## 8. Concrete lessons for zu + +1. Keep stable logical node and edge identity independent of row group, CSR slot, shard, and object range. +2. Store forward and reverse adjacency as immutable range-addressable tiles carrying edge IDs. +3. Feed queries adjacency batches and typed vectors; prohibit one storage call per logical element. +4. Use vectorized/factorized execution for property-heavy patterns and dedicated frontier operators for recursion. +5. Cost topology, properties, network, cache certainty, remote requests, and result materialization together. +6. Separate the local embedded profile from the object-authoritative distributed read profile. +7. Fence writers with monotonic epochs and make ambiguous commits reconcilable by transaction ID. +8. Pack small graph tiles into large immutable objects while retaining independent checksums and range offsets. +9. Keep the hot topology working set in RAM/NVMe; batch cold frontier misses into few remote rounds. +10. Admission-control remote requests and bytes so fixed-price plans have an enforceable upper bound. +11. Partition by workload-aware graph locality, and expose cross-partition semantics rather than hiding them. +12. Publish qualified wins per workload cell; never promise a universal tenfold advantage. + +## 9. Evidence gaps to close before publication + +- Exact current version and release date. +- Exact license text for the benchmarked artifact. +- Storage bytes per node/edge/property on all standard datasets. +- Stable-edge-ID and parallel-edge semantics. +- Isolation litmus results and commit acknowledgement point. +- Crash recovery time versus dirty WAL size. +- Supernode behavior and maximum tested degree. +- Cold-start metadata and request count. +- Distributed cross-partition query amplification. +- Peak memory under skew, cancellation, and overload. +- Background compaction/GC effect on tail latency. +- Full load/index/checkpoint/backup resource cost. +- Reproducible largest-scale result. +- Independent or audited benchmark evidence. + +## 10. Primary and official sources + +- [What is ArcadeDB](https://docs.arcadedb.com/arcadedb/tutorials/what-is-arcadedb) +- [HA concepts](https://docs.arcadedb.com/arcadedb/concepts/high-availability) +- [Source repository](https://github.com/ArcadeData/arcadedb) +- [LDBC SNB Interactive and audited disclosures](https://ldbcouncil.org/benchmarks/snb/interactive/) +- [LDBC Graphalytics](https://ldbcouncil.org/benchmarks/graphalytics/) +- [SoK: The Faults in our Graph Benchmarks](https://arxiv.org/abs/2404.00766) + +## 11. Source-handling rules + +- Official documentation and source are evidence for implemented or declared behavior, not independent performance. +- A vendor benchmark is labeled vendor claim until the harness reproduces it. +- A peer-reviewed paper establishes only the version, configuration, and workload it evaluated. +- Search snippets, comparison sites, and unsourced blogs are discovery aids, not final evidence. +- Unknown is a valid result and creates a concrete experiment or source-inspection task. +- All web facts are rechecked at benchmark freeze because this corpus is current only through the research date. + +## 12. Reproduction record template + +- engine: `ArcadeDB` +- version: `TBD at benchmark freeze` +- artifact digest: `TBD` +- source commit: `TBD or managed-service N/A` +- edition/license: `TBD` +- query language/version: `TBD` +- storage and durability mode: `TBD` +- cluster and replication: `TBD` +- CPU/RAM/NVMe/network: `TBD` +- OS/kernel/filesystem: `TBD` +- dataset URI and digest: `TBD` +- loader command and duration: `TBD` +- physical bytes by category: `TBD` +- tuning file: `TBD` +- query corpus commit: `TBD` +- raw result URI/digest: `TBD` +- profiler/trace URI: `TBD` +- correctness status: `TBD` +- reviewer and rerun date: `TBD` diff --git a/docs/research/engine-azure_cosmosdb_gremlin.md b/docs/research/engine-azure_cosmosdb_gremlin.md new file mode 100644 index 0000000..c187a92 --- /dev/null +++ b/docs/research/engine-azure_cosmosdb_gremlin.md @@ -0,0 +1,884 @@ +# Azure Cosmos DB for Apache Gremlin: 2026 deep technical and competitive specification + +Research cut: `2026-08-08` +Status: evidence-backed competitor audit; not a vendor endorsement +Family: `managed partitioned multi-model graph API` +Evidence convention: **Observed/official**, **Vendor claim**, **Research inference**, **Unknown**, **Qualification target**. + +## 1. Decision summary + +Cosmos is the clearest counterexample showing why edge direction and partition-key-aware planning are mandatory. + +This document answers two questions: what this engine actually proves in 2026, and what zu must build or measure to earn a defensible advantage. A missing public detail remains unknown; it is never silently filled with a favorable assumption. + +### Snapshot card + +- Lifecycle: active. +- Data model: property graph stored as JSON documents. +- Query surface: Gremlin subset. +- Persistent layout: Cosmos DB hash-partitioned document store; outgoing edges co-located with source. +- Execution: Gremlin translation over partitioned document operations. +- Transactions: Cosmos consistency levels and transactional-batch boundaries; graph-wide ACID is not implied. +- Distribution: automatic partitioning by user-chosen key. +- Object-storage posture: managed cloud storage, not an S3-native portable engine. +- License/commercial boundary: proprietary managed service. +- Scale evidence: large horizontal capacity; graph latency is sensitive to partition key and direction. +- Benchmark posture: report request units, partitions touched, throttling, and retry latency. + +### Facts that materially affect comparison + +- F01 — Vertices and edges are JSON documents. +- F02 — Outgoing edges are stored with their source vertex. +- F03 — Incoming traversal can fan out across partitions and be expensive. +- F04 — Supplying vertex ID without partition key loses routing precision. +- F05 — RU cost is an essential benchmark metric, not ancillary billing detail. + +### Bottom-line fit against zu's target + +- Very-low latency: compare hot point and bounded traversal paths; never extrapolate from scans or algorithms. +- Very-low resources: charge resident set, page cache, remote cache, background services, and replicas. +- Distributed: distinguish read replication, partitioned capacity, distributed transactions, and elastic stateless compute. +- Fixed cost: no engine has fixed marginal cost by declaration; admission, batching, and capacity reservations create the bound. +- S3 authority: backups, imports, lake scans, and S3-native demand paging are four different architectures. +- PB / trillion-edge scale: require a capacity derivation plus a run at the largest affordable scale; marketing adjectives do not qualify. +- Tenfold win: can be a per-cell qualification result, never a universal statement across incomparable workloads. + +## 2. Product and ecosystem boundary + +The audited unit is **Azure Cosmos DB for Apache Gremlin** in the exact release, edition, deployment, and durability mode recorded by the harness. The family classification is **managed partitioned multi-model graph API**. The current lifecycle statement is: active. + +The harness must record binary/container digest, source commit when available, build flags, plugins, license/edition, language mode, storage mode, cluster topology, replication factor, durability settings, cache sizes, thread counts, NUMA policy, kernel, filesystem, cloud region, and all environment variables that affect execution. + +A managed service is not placed in a same-hardware chart. It receives a service-level result with provisioned units, region, public price, and observed provider metrics. A historical engine remains useful for regression but cannot support a claim about beating all current competitors. + +## 3. Architecture reconstruction + +### 3.1 Logical model + +Azure Cosmos DB for Apache Gremlin exposes property graph stored as JSON documents. The conformance corpus must test nulls, missing properties, labels/types, direction, self-loops, parallel edges, element equality, path equality, bag semantics, ordering, numeric overflow, string collation, temporal values, and schema evolution. + +### 3.2 Language and compiler + +The public query surface is Gremlin subset. Syntax similarity is not semantic equivalence. Every supported construct needs a result oracle and an unsupported-feature declaration. + +### 3.3 Storage + +The best supported storage summary is: Cosmos DB hash-partitioned document store; outgoing edges co-located with source. This statement must be refined from code, format documentation, or provider counters before using it in a performance explanation. + +### 3.4 Execution + +The best supported execution summary is: Gremlin translation over partitioned document operations. The benchmark profiler must confirm which runtime and operators actually executed. + +### 3.5 Transactions and recovery + +The public contract is: Cosmos consistency levels and transactional-batch boundaries; graph-wide ACID is not implied. Exact acknowledgement, isolation anomalies, recovery bounds, and failover behavior remain separate qualification items. + +### 3.6 Distribution + +The deployment shape is: automatic partitioning by user-chosen key. Replication is not capacity sharding; sharding is not distributed ACID; stateless readers are not stateless storage. + +### 3.7 Object storage and cost + +The 2026 posture is: managed cloud storage, not an S3-native portable engine. The audit distinguishes authoritative live bytes, derived acceleration, backup, import/export, and spill. + +## 4. Forty-control deep audit + +### 4.1 `product_boundary` + +Audit question: What exact executable, edition, and storage mode is the system under test? + +Current assessment: Pin Azure Cosmos DB for Apache Gremlin, lifecycle `active`, and its edition/mode. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.2 `authority` + +Audit question: Which durable component is the source of truth after every acknowledged write? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.3 `identity` + +Audit question: Are node and edge identities stable across compaction, export, replication, and restore? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.4 `parallel_edges` + +Audit question: Can distinct parallel edges retain properties and trail identity end to end? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.5 `schema` + +Audit question: Is the schema open, closed, optional, inferred, or externally mapped? + +Current assessment: Start from `property graph stored as JSON documents` and test actual constraints. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.6 `labels` + +Audit question: How are multiple labels represented and indexed? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.7 `adjacency_out` + +Audit question: How is outgoing adjacency located, encoded, split, cached, and updated? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.8 `adjacency_in` + +Audit question: Is incoming adjacency first-class, derived, replicated, or a fan-out operation? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.9 `supernodes` + +Audit question: How are million-to-billion-degree vertices represented and scheduled? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.10 `properties` + +Audit question: Are properties co-located, columnar, row-oriented, document-encoded, or remote? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.11 `compression` + +Audit question: Which topology, integer, string, null, and floating encodings are implemented? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.12 `checksums` + +Audit question: What integrity unit is verified on point reads and range reads? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.13 `snapshot` + +Audit question: What exact token pins graph data, schema, statistics, and indexes? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.14 `isolation` + +Audit question: Which anomalies are forbidden at the documented isolation level? + +Current assessment: Published summary: Cosmos consistency levels and transactional-batch boundaries; graph-wide ACID is not implied. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.15 `durability` + +Audit question: What device/service acknowledgement is required before commit returns? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.16 `recovery` + +Audit question: What bounds restart work after a clean stop and a crash? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.17 `writer_fencing` + +Audit question: Can a stale writer acknowledge after failover or lease expiry? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.18 `partitioning` + +Audit question: What key determines placement and what happens to cross-partition edges? + +Current assessment: Published distribution summary: automatic partitioning by user-chosen key. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.19 `rebalancing` + +Audit question: Can placement change online without changing logical identity? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.20 `replication` + +Audit question: Are replicas full, sharded, synchronous, asynchronous, or shared-storage readers? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.21 `optimizer` + +Audit question: Does the optimizer cost graph expansion, joins, network, cache, and remote requests? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.22 `statistics` + +Audit question: Which degree, correlation, path, and property statistics are persistent? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.23 `execution` + +Audit question: Is execution tuple-at-a-time, vectorized, factorized, compiled, matrix, or actor based? + +Current assessment: Expected family: Gremlin translation over partitioned document operations. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.24 `recursion` + +Audit question: How are BFS, shortest paths, trails, simple paths, and arbitrary reachability executed? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.25 `parallelism` + +Audit question: How does the engine avoid skew and nested parallelism under mixed queries? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.26 `memory` + +Audit question: Are all variable allocations charged to bounded query and system budgets? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.27 `spill` + +Audit question: Which operators spill, in what format, and with what admission controls? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.28 `cancellation` + +Audit question: Can cancellation stop CPU, local I/O, remote I/O, retries, and prefetch? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.29 `cache` + +Audit question: What is cached, how is it keyed, admitted, pinned, and evicted? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.30 `cold_start` + +Audit question: What metadata and data round trips are required with empty caches? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.31 `object_requests` + +Audit question: Can a query issue one remote request per node, edge, or result row? + +Current assessment: Published object-store posture: managed cloud storage, not an S3-native portable engine. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.32 `cost_admission` + +Audit question: Are request, byte, CPU, spill, and result limits enforced before work? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.33 `observability` + +Audit question: Can operators report rows, edges, bytes, requests, stalls, memory, and spill? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.34 `language` + +Audit question: Which GQL/Cypher/SQL-PGQ/Gremlin/SPARQL semantics are declared and tested? + +Current assessment: Declared surface: Gremlin subset. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.35 `updates` + +Audit question: Are DDL, insert, merge, update, detach delete, and constraints complete? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.36 `bulk_load` + +Audit question: Does bulk load preserve transactional and index invariants? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.37 `backup` + +Audit question: Is backup consistent, incremental, immutable, and restore-tested? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.38 `gc` + +Audit question: How are old snapshots, orphan objects, tombstones, and indexes reclaimed safely? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.39 `security` + +Audit question: Are authentication, authorization, encryption, audit, and tenant isolation in scope? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.40 `operations` + +Audit question: What compaction, upgrade, repair, verification, and capacity procedures exist? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +## 5. Benchmark contract for this engine + +Every case runs correctness first, then isolated latency, then closed-loop concurrency, then open-loop overload. Report median, p95, p99, p99.9, timeout/rejection rate, throughput, CPU-seconds, peak RSS, cache bytes, disk bytes, network bytes, remote requests, write amplification, and estimated monthly cost. + +Warm means all intended engine caches are populated without changing the query parameters. Hot means the exact working set is resident. Cold means process-local, engine, OS, NVMe, and remote cache state are explicitly reset or a fresh namespace is used. Those words are never inferred from repetition count. + +### 5.1 `point_pk` — primary-key node lookup with one projected property + +- Applicability to Azure Cosmos DB for Apache Gremlin: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.2 `point_edge` — stable edge-ID lookup including endpoints and one property + +- Applicability to Azure Cosmos DB for Apache Gremlin: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.3 `degree_1` — degree-one outgoing expansion + +- Applicability to Azure Cosmos DB for Apache Gremlin: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.4 `degree_32` — small adjacency expansion around degree 32 + +- Applicability to Azure Cosmos DB for Apache Gremlin: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.5 `degree_1k` — medium adjacency expansion around degree 1,024 + +- Applicability to Azure Cosmos DB for Apache Gremlin: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.6 `supernode` — range-limited expansion of a ten-million-degree supernode + +- Applicability to Azure Cosmos DB for Apache Gremlin: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.7 `expand_2` — selective two-hop expansion + +- Applicability to Azure Cosmos DB for Apache Gremlin: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.8 `expand_3` — three-hop frontier expansion with duplicate control + +- Applicability to Azure Cosmos DB for Apache Gremlin: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.9 `expand_into` — edge-existence/expand-into between already-bound endpoints + +- Applicability to Azure Cosmos DB for Apache Gremlin: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.10 `multi_edge` — parallel-edge identity and property projection + +- Applicability to Azure Cosmos DB for Apache Gremlin: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.11 `shortest` — bidirectional point-to-point unweighted shortest path + +- Applicability to Azure Cosmos DB for Apache Gremlin: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.12 `weighted` — weighted shortest path with property access + +- Applicability to Azure Cosmos DB for Apache Gremlin: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.13 `var_walk` — bounded variable-length walk + +- Applicability to Azure Cosmos DB for Apache Gremlin: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.14 `trail` — DIFFERENT EDGES trail enumeration + +- Applicability to Azure Cosmos DB for Apache Gremlin: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.15 `simple` — simple-path enumeration with explicit bound + +- Applicability to Azure Cosmos DB for Apache Gremlin: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.16 `triangle` — triangle pattern with worst-case-sensitive join + +- Applicability to Azure Cosmos DB for Apache Gremlin: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.17 `cycle4` — four-cycle pattern + +- Applicability to Azure Cosmos DB for Apache Gremlin: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.18 `star_join` — high-fanout star pattern with property filters + +- Applicability to Azure Cosmos DB for Apache Gremlin: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.19 `optional` — optional match preserving null/bag semantics + +- Applicability to Azure Cosmos DB for Apache Gremlin: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.20 `aggregate` — grouped aggregate after traversal + +- Applicability to Azure Cosmos DB for Apache Gremlin: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.21 `topk` — ordered top-k with late property materialization + +- Applicability to Azure Cosmos DB for Apache Gremlin: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.22 `scan` — full projected property scan + +- Applicability to Azure Cosmos DB for Apache Gremlin: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.23 `selective_scan` — zone/index-pruned selective property scan + +- Applicability to Azure Cosmos DB for Apache Gremlin: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.24 `mixed` — concurrent short reads, complex reads, and updates + +- Applicability to Azure Cosmos DB for Apache Gremlin: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.25 `ingest` — sustained transactional ingest with indexes enabled + +- Applicability to Azure Cosmos DB for Apache Gremlin: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.26 `bulk` — initial bulk load including index/CSR build + +- Applicability to Azure Cosmos DB for Apache Gremlin: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.27 `checkpoint` — checkpoint or compaction while readers remain active + +- Applicability to Azure Cosmos DB for Apache Gremlin: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.28 `recovery` — crash recovery at bounded dirty-log size + +- Applicability to Azure Cosmos DB for Apache Gremlin: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.29 `cold` — same query after clearing engine and OS/cache tiers + +- Applicability to Azure Cosmos DB for Apache Gremlin: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.30 `remote` — same query with authoritative bytes only in object storage + +- Applicability to Azure Cosmos DB for Apache Gremlin: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +## 6. Fairness controls + +- Same logical dataset and update stream; engine-native physical layouts are allowed and disclosed. +- Same result semantics; unsupported queries remain unsupported rather than rewritten into easier questions. +- Same durable acknowledgement class for write comparisons. +- Same number of physical cores and memory limit for self-hosted single-node tests. +- Same aggregate resources and replication fault tolerance for distributed tests. +- Officially recommended tuning may be applied before the freeze and is committed with rationale. +- Query-specific hints are allowed only when equivalent hints are offered to every engine and separately charted. +- Load/build/index time and bytes are first-class results. +- Cold, warm, and hot results are separate charts. +- Managed services use public configurations and cannot borrow hidden same-machine resource claims. +- Failed runs, OOMs, correctness mismatches, and timeouts stay in the dataset. +- Every chart links raw samples and the exact reproduction command. + +## 7. Likely advantages and limits + +The strongest known reason to choose this engine is tied to its family `managed partitioned multi-model graph API`, its execution path `Gremlin translation over partitioned document operations`, and its existing ecosystem. The strongest reason to reject it for zu's target is the gap between `managed cloud storage, not an S3-native portable engine` and an S3-authoritative, request-budgeted, PB-scale graph service. + +Capacity statement: large horizontal capacity; graph latency is sensitive to partition key and direction. This is not converted into an edge-count claim without a physical byte model including IDs, both adjacency directions, properties, indexes, MVCC, WAL, replicas, and free space. + +Commercial statement: proprietary managed service. License cost, support cost, and unavailable enterprise capabilities remain visible in TCO and feature tables. + +## 8. Concrete lessons for zu + +1. Keep stable logical node and edge identity independent of row group, CSR slot, shard, and object range. +2. Store forward and reverse adjacency as immutable range-addressable tiles carrying edge IDs. +3. Feed queries adjacency batches and typed vectors; prohibit one storage call per logical element. +4. Use vectorized/factorized execution for property-heavy patterns and dedicated frontier operators for recursion. +5. Cost topology, properties, network, cache certainty, remote requests, and result materialization together. +6. Separate the local embedded profile from the object-authoritative distributed read profile. +7. Fence writers with monotonic epochs and make ambiguous commits reconcilable by transaction ID. +8. Pack small graph tiles into large immutable objects while retaining independent checksums and range offsets. +9. Keep the hot topology working set in RAM/NVMe; batch cold frontier misses into few remote rounds. +10. Admission-control remote requests and bytes so fixed-price plans have an enforceable upper bound. +11. Partition by workload-aware graph locality, and expose cross-partition semantics rather than hiding them. +12. Publish qualified wins per workload cell; never promise a universal tenfold advantage. + +## 9. Evidence gaps to close before publication + +- Exact current version and release date. +- Exact license text for the benchmarked artifact. +- Storage bytes per node/edge/property on all standard datasets. +- Stable-edge-ID and parallel-edge semantics. +- Isolation litmus results and commit acknowledgement point. +- Crash recovery time versus dirty WAL size. +- Supernode behavior and maximum tested degree. +- Cold-start metadata and request count. +- Distributed cross-partition query amplification. +- Peak memory under skew, cancellation, and overload. +- Background compaction/GC effect on tail latency. +- Full load/index/checkpoint/backup resource cost. +- Reproducible largest-scale result. +- Independent or audited benchmark evidence. + +## 10. Primary and official sources + +- [Partitioning](https://learn.microsoft.com/en-us/azure/cosmos-db/gremlin/partitioning) +- [Gremlin support](https://learn.microsoft.com/en-us/azure/cosmos-db/gremlin/support) +- [LDBC SNB Interactive and audited disclosures](https://ldbcouncil.org/benchmarks/snb/interactive/) +- [LDBC Graphalytics](https://ldbcouncil.org/benchmarks/graphalytics/) +- [SoK: The Faults in our Graph Benchmarks](https://arxiv.org/abs/2404.00766) + +## 11. Source-handling rules + +- Official documentation and source are evidence for implemented or declared behavior, not independent performance. +- A vendor benchmark is labeled vendor claim until the harness reproduces it. +- A peer-reviewed paper establishes only the version, configuration, and workload it evaluated. +- Search snippets, comparison sites, and unsourced blogs are discovery aids, not final evidence. +- Unknown is a valid result and creates a concrete experiment or source-inspection task. +- All web facts are rechecked at benchmark freeze because this corpus is current only through the research date. + +## 12. Reproduction record template + +- engine: `Azure Cosmos DB for Apache Gremlin` +- version: `TBD at benchmark freeze` +- artifact digest: `TBD` +- source commit: `TBD or managed-service N/A` +- edition/license: `TBD` +- query language/version: `TBD` +- storage and durability mode: `TBD` +- cluster and replication: `TBD` +- CPU/RAM/NVMe/network: `TBD` +- OS/kernel/filesystem: `TBD` +- dataset URI and digest: `TBD` +- loader command and duration: `TBD` +- physical bytes by category: `TBD` +- tuning file: `TBD` +- query corpus commit: `TBD` +- raw result URI/digest: `TBD` +- profiler/trace URI: `TBD` +- correctness status: `TBD` +- reviewer and rerun date: `TBD` diff --git a/docs/research/engine-blazegraph.md b/docs/research/engine-blazegraph.md new file mode 100644 index 0000000..0df9d40 --- /dev/null +++ b/docs/research/engine-blazegraph.md @@ -0,0 +1,884 @@ +# Blazegraph (legacy): 2026 deep technical and competitive specification + +Research cut: `2026-08-08` +Status: evidence-backed competitor audit; not a vendor endorsement +Family: `RDF graph database` +Evidence convention: **Observed/official**, **Vendor claim**, **Research inference**, **Unknown**, **Qualification target**. + +## 1. Decision summary + +Blazegraph is historically important but must be labeled legacy to avoid a misleading 2026 comparison. + +This document answers two questions: what this engine actually proves in 2026, and what zu must build or measure to earn a defensible advantage. A missing public detail remains unknown; it is never silently filled with a favorable assumption. + +### Snapshot card + +- Lifecycle: archived repository; historical benchmark baseline. +- Data model: RDF triples/quads and property-graph integrations. +- Query surface: SPARQL; historical Blueprints/Gremlin integrations. +- Persistent layout: B+tree-oriented journal storage. +- Execution: SPARQL optimizer and optional GPU/cluster research lineage. +- Transactions: transactional journal. +- Distribution: historical HA/scale-out commercial features. +- Object-storage posture: not S3-native. +- License/commercial boundary: GPL-2.0 repository. +- Scale evidence: historically large Wikidata deployments; active-product status is unsuitable. +- Benchmark posture: retain for RDF regression only. + +### Facts that materially affect comparison + +- F01 — The public repository is archived. +- F02 — Blazegraph powered major public knowledge-graph deployments historically. +- F03 — Its journal and B+tree design remain useful reference material. +- F04 — Operational security and dependency posture are legacy risks. +- F05 — No new zu claim should rely on beating an unmaintained version alone. + +### Bottom-line fit against zu's target + +- Very-low latency: compare hot point and bounded traversal paths; never extrapolate from scans or algorithms. +- Very-low resources: charge resident set, page cache, remote cache, background services, and replicas. +- Distributed: distinguish read replication, partitioned capacity, distributed transactions, and elastic stateless compute. +- Fixed cost: no engine has fixed marginal cost by declaration; admission, batching, and capacity reservations create the bound. +- S3 authority: backups, imports, lake scans, and S3-native demand paging are four different architectures. +- PB / trillion-edge scale: require a capacity derivation plus a run at the largest affordable scale; marketing adjectives do not qualify. +- Tenfold win: can be a per-cell qualification result, never a universal statement across incomparable workloads. + +## 2. Product and ecosystem boundary + +The audited unit is **Blazegraph (legacy)** in the exact release, edition, deployment, and durability mode recorded by the harness. The family classification is **RDF graph database**. The current lifecycle statement is: archived repository; historical benchmark baseline. + +The harness must record binary/container digest, source commit when available, build flags, plugins, license/edition, language mode, storage mode, cluster topology, replication factor, durability settings, cache sizes, thread counts, NUMA policy, kernel, filesystem, cloud region, and all environment variables that affect execution. + +A managed service is not placed in a same-hardware chart. It receives a service-level result with provisioned units, region, public price, and observed provider metrics. A historical engine remains useful for regression but cannot support a claim about beating all current competitors. + +## 3. Architecture reconstruction + +### 3.1 Logical model + +Blazegraph (legacy) exposes RDF triples/quads and property-graph integrations. The conformance corpus must test nulls, missing properties, labels/types, direction, self-loops, parallel edges, element equality, path equality, bag semantics, ordering, numeric overflow, string collation, temporal values, and schema evolution. + +### 3.2 Language and compiler + +The public query surface is SPARQL; historical Blueprints/Gremlin integrations. Syntax similarity is not semantic equivalence. Every supported construct needs a result oracle and an unsupported-feature declaration. + +### 3.3 Storage + +The best supported storage summary is: B+tree-oriented journal storage. This statement must be refined from code, format documentation, or provider counters before using it in a performance explanation. + +### 3.4 Execution + +The best supported execution summary is: SPARQL optimizer and optional GPU/cluster research lineage. The benchmark profiler must confirm which runtime and operators actually executed. + +### 3.5 Transactions and recovery + +The public contract is: transactional journal. Exact acknowledgement, isolation anomalies, recovery bounds, and failover behavior remain separate qualification items. + +### 3.6 Distribution + +The deployment shape is: historical HA/scale-out commercial features. Replication is not capacity sharding; sharding is not distributed ACID; stateless readers are not stateless storage. + +### 3.7 Object storage and cost + +The 2026 posture is: not S3-native. The audit distinguishes authoritative live bytes, derived acceleration, backup, import/export, and spill. + +## 4. Forty-control deep audit + +### 4.1 `product_boundary` + +Audit question: What exact executable, edition, and storage mode is the system under test? + +Current assessment: Pin Blazegraph (legacy), lifecycle `archived repository; historical benchmark baseline`, and its edition/mode. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.2 `authority` + +Audit question: Which durable component is the source of truth after every acknowledged write? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.3 `identity` + +Audit question: Are node and edge identities stable across compaction, export, replication, and restore? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.4 `parallel_edges` + +Audit question: Can distinct parallel edges retain properties and trail identity end to end? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.5 `schema` + +Audit question: Is the schema open, closed, optional, inferred, or externally mapped? + +Current assessment: Start from `RDF triples/quads and property-graph integrations` and test actual constraints. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.6 `labels` + +Audit question: How are multiple labels represented and indexed? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.7 `adjacency_out` + +Audit question: How is outgoing adjacency located, encoded, split, cached, and updated? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.8 `adjacency_in` + +Audit question: Is incoming adjacency first-class, derived, replicated, or a fan-out operation? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.9 `supernodes` + +Audit question: How are million-to-billion-degree vertices represented and scheduled? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.10 `properties` + +Audit question: Are properties co-located, columnar, row-oriented, document-encoded, or remote? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.11 `compression` + +Audit question: Which topology, integer, string, null, and floating encodings are implemented? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.12 `checksums` + +Audit question: What integrity unit is verified on point reads and range reads? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.13 `snapshot` + +Audit question: What exact token pins graph data, schema, statistics, and indexes? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.14 `isolation` + +Audit question: Which anomalies are forbidden at the documented isolation level? + +Current assessment: Published summary: transactional journal. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.15 `durability` + +Audit question: What device/service acknowledgement is required before commit returns? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.16 `recovery` + +Audit question: What bounds restart work after a clean stop and a crash? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.17 `writer_fencing` + +Audit question: Can a stale writer acknowledge after failover or lease expiry? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.18 `partitioning` + +Audit question: What key determines placement and what happens to cross-partition edges? + +Current assessment: Published distribution summary: historical HA/scale-out commercial features. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.19 `rebalancing` + +Audit question: Can placement change online without changing logical identity? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.20 `replication` + +Audit question: Are replicas full, sharded, synchronous, asynchronous, or shared-storage readers? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.21 `optimizer` + +Audit question: Does the optimizer cost graph expansion, joins, network, cache, and remote requests? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.22 `statistics` + +Audit question: Which degree, correlation, path, and property statistics are persistent? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.23 `execution` + +Audit question: Is execution tuple-at-a-time, vectorized, factorized, compiled, matrix, or actor based? + +Current assessment: Expected family: SPARQL optimizer and optional GPU/cluster research lineage. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.24 `recursion` + +Audit question: How are BFS, shortest paths, trails, simple paths, and arbitrary reachability executed? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.25 `parallelism` + +Audit question: How does the engine avoid skew and nested parallelism under mixed queries? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.26 `memory` + +Audit question: Are all variable allocations charged to bounded query and system budgets? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.27 `spill` + +Audit question: Which operators spill, in what format, and with what admission controls? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.28 `cancellation` + +Audit question: Can cancellation stop CPU, local I/O, remote I/O, retries, and prefetch? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.29 `cache` + +Audit question: What is cached, how is it keyed, admitted, pinned, and evicted? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.30 `cold_start` + +Audit question: What metadata and data round trips are required with empty caches? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.31 `object_requests` + +Audit question: Can a query issue one remote request per node, edge, or result row? + +Current assessment: Published object-store posture: not S3-native. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.32 `cost_admission` + +Audit question: Are request, byte, CPU, spill, and result limits enforced before work? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.33 `observability` + +Audit question: Can operators report rows, edges, bytes, requests, stalls, memory, and spill? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.34 `language` + +Audit question: Which GQL/Cypher/SQL-PGQ/Gremlin/SPARQL semantics are declared and tested? + +Current assessment: Declared surface: SPARQL; historical Blueprints/Gremlin integrations. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.35 `updates` + +Audit question: Are DDL, insert, merge, update, detach delete, and constraints complete? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.36 `bulk_load` + +Audit question: Does bulk load preserve transactional and index invariants? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.37 `backup` + +Audit question: Is backup consistent, incremental, immutable, and restore-tested? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.38 `gc` + +Audit question: How are old snapshots, orphan objects, tombstones, and indexes reclaimed safely? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.39 `security` + +Audit question: Are authentication, authorization, encryption, audit, and tenant isolation in scope? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.40 `operations` + +Audit question: What compaction, upgrade, repair, verification, and capacity procedures exist? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +## 5. Benchmark contract for this engine + +Every case runs correctness first, then isolated latency, then closed-loop concurrency, then open-loop overload. Report median, p95, p99, p99.9, timeout/rejection rate, throughput, CPU-seconds, peak RSS, cache bytes, disk bytes, network bytes, remote requests, write amplification, and estimated monthly cost. + +Warm means all intended engine caches are populated without changing the query parameters. Hot means the exact working set is resident. Cold means process-local, engine, OS, NVMe, and remote cache state are explicitly reset or a fresh namespace is used. Those words are never inferred from repetition count. + +### 5.1 `point_pk` — primary-key node lookup with one projected property + +- Applicability to Blazegraph (legacy): required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.2 `point_edge` — stable edge-ID lookup including endpoints and one property + +- Applicability to Blazegraph (legacy): required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.3 `degree_1` — degree-one outgoing expansion + +- Applicability to Blazegraph (legacy): required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.4 `degree_32` — small adjacency expansion around degree 32 + +- Applicability to Blazegraph (legacy): required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.5 `degree_1k` — medium adjacency expansion around degree 1,024 + +- Applicability to Blazegraph (legacy): required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.6 `supernode` — range-limited expansion of a ten-million-degree supernode + +- Applicability to Blazegraph (legacy): required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.7 `expand_2` — selective two-hop expansion + +- Applicability to Blazegraph (legacy): required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.8 `expand_3` — three-hop frontier expansion with duplicate control + +- Applicability to Blazegraph (legacy): required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.9 `expand_into` — edge-existence/expand-into between already-bound endpoints + +- Applicability to Blazegraph (legacy): required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.10 `multi_edge` — parallel-edge identity and property projection + +- Applicability to Blazegraph (legacy): required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.11 `shortest` — bidirectional point-to-point unweighted shortest path + +- Applicability to Blazegraph (legacy): required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.12 `weighted` — weighted shortest path with property access + +- Applicability to Blazegraph (legacy): required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.13 `var_walk` — bounded variable-length walk + +- Applicability to Blazegraph (legacy): required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.14 `trail` — DIFFERENT EDGES trail enumeration + +- Applicability to Blazegraph (legacy): required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.15 `simple` — simple-path enumeration with explicit bound + +- Applicability to Blazegraph (legacy): required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.16 `triangle` — triangle pattern with worst-case-sensitive join + +- Applicability to Blazegraph (legacy): required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.17 `cycle4` — four-cycle pattern + +- Applicability to Blazegraph (legacy): required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.18 `star_join` — high-fanout star pattern with property filters + +- Applicability to Blazegraph (legacy): required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.19 `optional` — optional match preserving null/bag semantics + +- Applicability to Blazegraph (legacy): required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.20 `aggregate` — grouped aggregate after traversal + +- Applicability to Blazegraph (legacy): required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.21 `topk` — ordered top-k with late property materialization + +- Applicability to Blazegraph (legacy): required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.22 `scan` — full projected property scan + +- Applicability to Blazegraph (legacy): required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.23 `selective_scan` — zone/index-pruned selective property scan + +- Applicability to Blazegraph (legacy): required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.24 `mixed` — concurrent short reads, complex reads, and updates + +- Applicability to Blazegraph (legacy): required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.25 `ingest` — sustained transactional ingest with indexes enabled + +- Applicability to Blazegraph (legacy): required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.26 `bulk` — initial bulk load including index/CSR build + +- Applicability to Blazegraph (legacy): required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.27 `checkpoint` — checkpoint or compaction while readers remain active + +- Applicability to Blazegraph (legacy): required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.28 `recovery` — crash recovery at bounded dirty-log size + +- Applicability to Blazegraph (legacy): required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.29 `cold` — same query after clearing engine and OS/cache tiers + +- Applicability to Blazegraph (legacy): required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.30 `remote` — same query with authoritative bytes only in object storage + +- Applicability to Blazegraph (legacy): required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +## 6. Fairness controls + +- Same logical dataset and update stream; engine-native physical layouts are allowed and disclosed. +- Same result semantics; unsupported queries remain unsupported rather than rewritten into easier questions. +- Same durable acknowledgement class for write comparisons. +- Same number of physical cores and memory limit for self-hosted single-node tests. +- Same aggregate resources and replication fault tolerance for distributed tests. +- Officially recommended tuning may be applied before the freeze and is committed with rationale. +- Query-specific hints are allowed only when equivalent hints are offered to every engine and separately charted. +- Load/build/index time and bytes are first-class results. +- Cold, warm, and hot results are separate charts. +- Managed services use public configurations and cannot borrow hidden same-machine resource claims. +- Failed runs, OOMs, correctness mismatches, and timeouts stay in the dataset. +- Every chart links raw samples and the exact reproduction command. + +## 7. Likely advantages and limits + +The strongest known reason to choose this engine is tied to its family `RDF graph database`, its execution path `SPARQL optimizer and optional GPU/cluster research lineage`, and its existing ecosystem. The strongest reason to reject it for zu's target is the gap between `not S3-native` and an S3-authoritative, request-budgeted, PB-scale graph service. + +Capacity statement: historically large Wikidata deployments; active-product status is unsuitable. This is not converted into an edge-count claim without a physical byte model including IDs, both adjacency directions, properties, indexes, MVCC, WAL, replicas, and free space. + +Commercial statement: GPL-2.0 repository. License cost, support cost, and unavailable enterprise capabilities remain visible in TCO and feature tables. + +## 8. Concrete lessons for zu + +1. Keep stable logical node and edge identity independent of row group, CSR slot, shard, and object range. +2. Store forward and reverse adjacency as immutable range-addressable tiles carrying edge IDs. +3. Feed queries adjacency batches and typed vectors; prohibit one storage call per logical element. +4. Use vectorized/factorized execution for property-heavy patterns and dedicated frontier operators for recursion. +5. Cost topology, properties, network, cache certainty, remote requests, and result materialization together. +6. Separate the local embedded profile from the object-authoritative distributed read profile. +7. Fence writers with monotonic epochs and make ambiguous commits reconcilable by transaction ID. +8. Pack small graph tiles into large immutable objects while retaining independent checksums and range offsets. +9. Keep the hot topology working set in RAM/NVMe; batch cold frontier misses into few remote rounds. +10. Admission-control remote requests and bytes so fixed-price plans have an enforceable upper bound. +11. Partition by workload-aware graph locality, and expose cross-partition semantics rather than hiding them. +12. Publish qualified wins per workload cell; never promise a universal tenfold advantage. + +## 9. Evidence gaps to close before publication + +- Exact current version and release date. +- Exact license text for the benchmarked artifact. +- Storage bytes per node/edge/property on all standard datasets. +- Stable-edge-ID and parallel-edge semantics. +- Isolation litmus results and commit acknowledgement point. +- Crash recovery time versus dirty WAL size. +- Supernode behavior and maximum tested degree. +- Cold-start metadata and request count. +- Distributed cross-partition query amplification. +- Peak memory under skew, cancellation, and overload. +- Background compaction/GC effect on tail latency. +- Full load/index/checkpoint/backup resource cost. +- Reproducible largest-scale result. +- Independent or audited benchmark evidence. + +## 10. Primary and official sources + +- [Archived repository](https://github.com/blazegraph/database) +- [Legacy documentation](https://blazegraph.com/database/apidocs/) +- [LDBC SNB Interactive and audited disclosures](https://ldbcouncil.org/benchmarks/snb/interactive/) +- [LDBC Graphalytics](https://ldbcouncil.org/benchmarks/graphalytics/) +- [SoK: The Faults in our Graph Benchmarks](https://arxiv.org/abs/2404.00766) + +## 11. Source-handling rules + +- Official documentation and source are evidence for implemented or declared behavior, not independent performance. +- A vendor benchmark is labeled vendor claim until the harness reproduces it. +- A peer-reviewed paper establishes only the version, configuration, and workload it evaluated. +- Search snippets, comparison sites, and unsourced blogs are discovery aids, not final evidence. +- Unknown is a valid result and creates a concrete experiment or source-inspection task. +- All web facts are rechecked at benchmark freeze because this corpus is current only through the research date. + +## 12. Reproduction record template + +- engine: `Blazegraph (legacy)` +- version: `TBD at benchmark freeze` +- artifact digest: `TBD` +- source commit: `TBD or managed-service N/A` +- edition/license: `TBD` +- query language/version: `TBD` +- storage and durability mode: `TBD` +- cluster and replication: `TBD` +- CPU/RAM/NVMe/network: `TBD` +- OS/kernel/filesystem: `TBD` +- dataset URI and digest: `TBD` +- loader command and duration: `TBD` +- physical bytes by category: `TBD` +- tuning file: `TBD` +- query corpus commit: `TBD` +- raw result URI/digest: `TBD` +- profiler/trace URI: `TBD` +- correctness status: `TBD` +- reviewer and rerun date: `TBD` diff --git a/docs/research/engine-cozodb.md b/docs/research/engine-cozodb.md new file mode 100644 index 0000000..ccc7f59 --- /dev/null +++ b/docs/research/engine-cozodb.md @@ -0,0 +1,884 @@ +# CozoDB: 2026 deep technical and competitive specification + +Research cut: `2026-08-08` +Status: evidence-backed competitor audit; not a vendor endorsement +Family: `embedded relational-graph-vector database` +Evidence convention: **Observed/official**, **Vendor claim**, **Research inference**, **Unknown**, **Qualification target**. + +## 1. Decision summary + +CozoDB is a compact Datalog design reference; limited recent activity weakens it as a production comparator. + +This document answers two questions: what this engine actually proves in 2026, and what zu must build or measure to earn a defensible advantage. A missing public detail remains unknown; it is never silently filled with a favorable assumption. + +### Snapshot card + +- Lifecycle: maintenance activity appears limited after late 2024; verify before adoption. +- Data model: relations queried recursively as graphs. +- Query surface: Datalog. +- Persistent layout: pluggable RocksDB, SQLite, in-memory, and other KV backends by build. +- Execution: compiled Datalog with joins, recursion, algorithms, and vector indices. +- Transactions: backend-dependent transactions with a unified embedded API. +- Distribution: single-process/embedded; TiKV-era distributed options are not a simple turnkey cluster. +- Object-storage posture: not S3-native. +- License/commercial boundary: MPL-2.0. +- Scale evidence: local and backend-dependent; no PB evidence. +- Benchmark posture: include recursive-query and algorithm microbenchmarks, but flag lifecycle risk. + +### Facts that materially affect comparison + +- F01 — Datalog makes recursion and joins first-class rather than special traversal syntax. +- F02 — Multiple storage engines complicate universal performance and durability statements. +- F03 — The product combines relational, graph, and vector operations in one embedded interface. +- F04 — Repository recency is an adoption risk and should be rechecked at benchmark freeze. +- F05 — Its concise query/runtime design is relevant to zu's fixed-point operator work. + +### Bottom-line fit against zu's target + +- Very-low latency: compare hot point and bounded traversal paths; never extrapolate from scans or algorithms. +- Very-low resources: charge resident set, page cache, remote cache, background services, and replicas. +- Distributed: distinguish read replication, partitioned capacity, distributed transactions, and elastic stateless compute. +- Fixed cost: no engine has fixed marginal cost by declaration; admission, batching, and capacity reservations create the bound. +- S3 authority: backups, imports, lake scans, and S3-native demand paging are four different architectures. +- PB / trillion-edge scale: require a capacity derivation plus a run at the largest affordable scale; marketing adjectives do not qualify. +- Tenfold win: can be a per-cell qualification result, never a universal statement across incomparable workloads. + +## 2. Product and ecosystem boundary + +The audited unit is **CozoDB** in the exact release, edition, deployment, and durability mode recorded by the harness. The family classification is **embedded relational-graph-vector database**. The current lifecycle statement is: maintenance activity appears limited after late 2024; verify before adoption. + +The harness must record binary/container digest, source commit when available, build flags, plugins, license/edition, language mode, storage mode, cluster topology, replication factor, durability settings, cache sizes, thread counts, NUMA policy, kernel, filesystem, cloud region, and all environment variables that affect execution. + +A managed service is not placed in a same-hardware chart. It receives a service-level result with provisioned units, region, public price, and observed provider metrics. A historical engine remains useful for regression but cannot support a claim about beating all current competitors. + +## 3. Architecture reconstruction + +### 3.1 Logical model + +CozoDB exposes relations queried recursively as graphs. The conformance corpus must test nulls, missing properties, labels/types, direction, self-loops, parallel edges, element equality, path equality, bag semantics, ordering, numeric overflow, string collation, temporal values, and schema evolution. + +### 3.2 Language and compiler + +The public query surface is Datalog. Syntax similarity is not semantic equivalence. Every supported construct needs a result oracle and an unsupported-feature declaration. + +### 3.3 Storage + +The best supported storage summary is: pluggable RocksDB, SQLite, in-memory, and other KV backends by build. This statement must be refined from code, format documentation, or provider counters before using it in a performance explanation. + +### 3.4 Execution + +The best supported execution summary is: compiled Datalog with joins, recursion, algorithms, and vector indices. The benchmark profiler must confirm which runtime and operators actually executed. + +### 3.5 Transactions and recovery + +The public contract is: backend-dependent transactions with a unified embedded API. Exact acknowledgement, isolation anomalies, recovery bounds, and failover behavior remain separate qualification items. + +### 3.6 Distribution + +The deployment shape is: single-process/embedded; TiKV-era distributed options are not a simple turnkey cluster. Replication is not capacity sharding; sharding is not distributed ACID; stateless readers are not stateless storage. + +### 3.7 Object storage and cost + +The 2026 posture is: not S3-native. The audit distinguishes authoritative live bytes, derived acceleration, backup, import/export, and spill. + +## 4. Forty-control deep audit + +### 4.1 `product_boundary` + +Audit question: What exact executable, edition, and storage mode is the system under test? + +Current assessment: Pin CozoDB, lifecycle `maintenance activity appears limited after late 2024; verify before adoption`, and its edition/mode. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.2 `authority` + +Audit question: Which durable component is the source of truth after every acknowledged write? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.3 `identity` + +Audit question: Are node and edge identities stable across compaction, export, replication, and restore? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.4 `parallel_edges` + +Audit question: Can distinct parallel edges retain properties and trail identity end to end? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.5 `schema` + +Audit question: Is the schema open, closed, optional, inferred, or externally mapped? + +Current assessment: Start from `relations queried recursively as graphs` and test actual constraints. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.6 `labels` + +Audit question: How are multiple labels represented and indexed? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.7 `adjacency_out` + +Audit question: How is outgoing adjacency located, encoded, split, cached, and updated? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.8 `adjacency_in` + +Audit question: Is incoming adjacency first-class, derived, replicated, or a fan-out operation? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.9 `supernodes` + +Audit question: How are million-to-billion-degree vertices represented and scheduled? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.10 `properties` + +Audit question: Are properties co-located, columnar, row-oriented, document-encoded, or remote? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.11 `compression` + +Audit question: Which topology, integer, string, null, and floating encodings are implemented? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.12 `checksums` + +Audit question: What integrity unit is verified on point reads and range reads? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.13 `snapshot` + +Audit question: What exact token pins graph data, schema, statistics, and indexes? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.14 `isolation` + +Audit question: Which anomalies are forbidden at the documented isolation level? + +Current assessment: Published summary: backend-dependent transactions with a unified embedded API. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.15 `durability` + +Audit question: What device/service acknowledgement is required before commit returns? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.16 `recovery` + +Audit question: What bounds restart work after a clean stop and a crash? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.17 `writer_fencing` + +Audit question: Can a stale writer acknowledge after failover or lease expiry? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.18 `partitioning` + +Audit question: What key determines placement and what happens to cross-partition edges? + +Current assessment: Published distribution summary: single-process/embedded; TiKV-era distributed options are not a simple turnkey cluster. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.19 `rebalancing` + +Audit question: Can placement change online without changing logical identity? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.20 `replication` + +Audit question: Are replicas full, sharded, synchronous, asynchronous, or shared-storage readers? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.21 `optimizer` + +Audit question: Does the optimizer cost graph expansion, joins, network, cache, and remote requests? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.22 `statistics` + +Audit question: Which degree, correlation, path, and property statistics are persistent? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.23 `execution` + +Audit question: Is execution tuple-at-a-time, vectorized, factorized, compiled, matrix, or actor based? + +Current assessment: Expected family: compiled Datalog with joins, recursion, algorithms, and vector indices. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.24 `recursion` + +Audit question: How are BFS, shortest paths, trails, simple paths, and arbitrary reachability executed? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.25 `parallelism` + +Audit question: How does the engine avoid skew and nested parallelism under mixed queries? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.26 `memory` + +Audit question: Are all variable allocations charged to bounded query and system budgets? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.27 `spill` + +Audit question: Which operators spill, in what format, and with what admission controls? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.28 `cancellation` + +Audit question: Can cancellation stop CPU, local I/O, remote I/O, retries, and prefetch? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.29 `cache` + +Audit question: What is cached, how is it keyed, admitted, pinned, and evicted? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.30 `cold_start` + +Audit question: What metadata and data round trips are required with empty caches? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.31 `object_requests` + +Audit question: Can a query issue one remote request per node, edge, or result row? + +Current assessment: Published object-store posture: not S3-native. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.32 `cost_admission` + +Audit question: Are request, byte, CPU, spill, and result limits enforced before work? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.33 `observability` + +Audit question: Can operators report rows, edges, bytes, requests, stalls, memory, and spill? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.34 `language` + +Audit question: Which GQL/Cypher/SQL-PGQ/Gremlin/SPARQL semantics are declared and tested? + +Current assessment: Declared surface: Datalog. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.35 `updates` + +Audit question: Are DDL, insert, merge, update, detach delete, and constraints complete? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.36 `bulk_load` + +Audit question: Does bulk load preserve transactional and index invariants? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.37 `backup` + +Audit question: Is backup consistent, incremental, immutable, and restore-tested? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.38 `gc` + +Audit question: How are old snapshots, orphan objects, tombstones, and indexes reclaimed safely? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.39 `security` + +Audit question: Are authentication, authorization, encryption, audit, and tenant isolation in scope? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.40 `operations` + +Audit question: What compaction, upgrade, repair, verification, and capacity procedures exist? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +## 5. Benchmark contract for this engine + +Every case runs correctness first, then isolated latency, then closed-loop concurrency, then open-loop overload. Report median, p95, p99, p99.9, timeout/rejection rate, throughput, CPU-seconds, peak RSS, cache bytes, disk bytes, network bytes, remote requests, write amplification, and estimated monthly cost. + +Warm means all intended engine caches are populated without changing the query parameters. Hot means the exact working set is resident. Cold means process-local, engine, OS, NVMe, and remote cache state are explicitly reset or a fresh namespace is used. Those words are never inferred from repetition count. + +### 5.1 `point_pk` — primary-key node lookup with one projected property + +- Applicability to CozoDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.2 `point_edge` — stable edge-ID lookup including endpoints and one property + +- Applicability to CozoDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.3 `degree_1` — degree-one outgoing expansion + +- Applicability to CozoDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.4 `degree_32` — small adjacency expansion around degree 32 + +- Applicability to CozoDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.5 `degree_1k` — medium adjacency expansion around degree 1,024 + +- Applicability to CozoDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.6 `supernode` — range-limited expansion of a ten-million-degree supernode + +- Applicability to CozoDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.7 `expand_2` — selective two-hop expansion + +- Applicability to CozoDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.8 `expand_3` — three-hop frontier expansion with duplicate control + +- Applicability to CozoDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.9 `expand_into` — edge-existence/expand-into between already-bound endpoints + +- Applicability to CozoDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.10 `multi_edge` — parallel-edge identity and property projection + +- Applicability to CozoDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.11 `shortest` — bidirectional point-to-point unweighted shortest path + +- Applicability to CozoDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.12 `weighted` — weighted shortest path with property access + +- Applicability to CozoDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.13 `var_walk` — bounded variable-length walk + +- Applicability to CozoDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.14 `trail` — DIFFERENT EDGES trail enumeration + +- Applicability to CozoDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.15 `simple` — simple-path enumeration with explicit bound + +- Applicability to CozoDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.16 `triangle` — triangle pattern with worst-case-sensitive join + +- Applicability to CozoDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.17 `cycle4` — four-cycle pattern + +- Applicability to CozoDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.18 `star_join` — high-fanout star pattern with property filters + +- Applicability to CozoDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.19 `optional` — optional match preserving null/bag semantics + +- Applicability to CozoDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.20 `aggregate` — grouped aggregate after traversal + +- Applicability to CozoDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.21 `topk` — ordered top-k with late property materialization + +- Applicability to CozoDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.22 `scan` — full projected property scan + +- Applicability to CozoDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.23 `selective_scan` — zone/index-pruned selective property scan + +- Applicability to CozoDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.24 `mixed` — concurrent short reads, complex reads, and updates + +- Applicability to CozoDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.25 `ingest` — sustained transactional ingest with indexes enabled + +- Applicability to CozoDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.26 `bulk` — initial bulk load including index/CSR build + +- Applicability to CozoDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.27 `checkpoint` — checkpoint or compaction while readers remain active + +- Applicability to CozoDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.28 `recovery` — crash recovery at bounded dirty-log size + +- Applicability to CozoDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.29 `cold` — same query after clearing engine and OS/cache tiers + +- Applicability to CozoDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.30 `remote` — same query with authoritative bytes only in object storage + +- Applicability to CozoDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +## 6. Fairness controls + +- Same logical dataset and update stream; engine-native physical layouts are allowed and disclosed. +- Same result semantics; unsupported queries remain unsupported rather than rewritten into easier questions. +- Same durable acknowledgement class for write comparisons. +- Same number of physical cores and memory limit for self-hosted single-node tests. +- Same aggregate resources and replication fault tolerance for distributed tests. +- Officially recommended tuning may be applied before the freeze and is committed with rationale. +- Query-specific hints are allowed only when equivalent hints are offered to every engine and separately charted. +- Load/build/index time and bytes are first-class results. +- Cold, warm, and hot results are separate charts. +- Managed services use public configurations and cannot borrow hidden same-machine resource claims. +- Failed runs, OOMs, correctness mismatches, and timeouts stay in the dataset. +- Every chart links raw samples and the exact reproduction command. + +## 7. Likely advantages and limits + +The strongest known reason to choose this engine is tied to its family `embedded relational-graph-vector database`, its execution path `compiled Datalog with joins, recursion, algorithms, and vector indices`, and its existing ecosystem. The strongest reason to reject it for zu's target is the gap between `not S3-native` and an S3-authoritative, request-budgeted, PB-scale graph service. + +Capacity statement: local and backend-dependent; no PB evidence. This is not converted into an edge-count claim without a physical byte model including IDs, both adjacency directions, properties, indexes, MVCC, WAL, replicas, and free space. + +Commercial statement: MPL-2.0. License cost, support cost, and unavailable enterprise capabilities remain visible in TCO and feature tables. + +## 8. Concrete lessons for zu + +1. Keep stable logical node and edge identity independent of row group, CSR slot, shard, and object range. +2. Store forward and reverse adjacency as immutable range-addressable tiles carrying edge IDs. +3. Feed queries adjacency batches and typed vectors; prohibit one storage call per logical element. +4. Use vectorized/factorized execution for property-heavy patterns and dedicated frontier operators for recursion. +5. Cost topology, properties, network, cache certainty, remote requests, and result materialization together. +6. Separate the local embedded profile from the object-authoritative distributed read profile. +7. Fence writers with monotonic epochs and make ambiguous commits reconcilable by transaction ID. +8. Pack small graph tiles into large immutable objects while retaining independent checksums and range offsets. +9. Keep the hot topology working set in RAM/NVMe; batch cold frontier misses into few remote rounds. +10. Admission-control remote requests and bytes so fixed-price plans have an enforceable upper bound. +11. Partition by workload-aware graph locality, and expose cross-partition semantics rather than hiding them. +12. Publish qualified wins per workload cell; never promise a universal tenfold advantage. + +## 9. Evidence gaps to close before publication + +- Exact current version and release date. +- Exact license text for the benchmarked artifact. +- Storage bytes per node/edge/property on all standard datasets. +- Stable-edge-ID and parallel-edge semantics. +- Isolation litmus results and commit acknowledgement point. +- Crash recovery time versus dirty WAL size. +- Supernode behavior and maximum tested degree. +- Cold-start metadata and request count. +- Distributed cross-partition query amplification. +- Peak memory under skew, cancellation, and overload. +- Background compaction/GC effect on tail latency. +- Full load/index/checkpoint/backup resource cost. +- Reproducible largest-scale result. +- Independent or audited benchmark evidence. + +## 10. Primary and official sources + +- [Manual](https://docs.cozodb.org/) +- [Source repository](https://github.com/cozodb/cozo) +- [LDBC SNB Interactive and audited disclosures](https://ldbcouncil.org/benchmarks/snb/interactive/) +- [LDBC Graphalytics](https://ldbcouncil.org/benchmarks/graphalytics/) +- [SoK: The Faults in our Graph Benchmarks](https://arxiv.org/abs/2404.00766) + +## 11. Source-handling rules + +- Official documentation and source are evidence for implemented or declared behavior, not independent performance. +- A vendor benchmark is labeled vendor claim until the harness reproduces it. +- A peer-reviewed paper establishes only the version, configuration, and workload it evaluated. +- Search snippets, comparison sites, and unsourced blogs are discovery aids, not final evidence. +- Unknown is a valid result and creates a concrete experiment or source-inspection task. +- All web facts are rechecked at benchmark freeze because this corpus is current only through the research date. + +## 12. Reproduction record template + +- engine: `CozoDB` +- version: `TBD at benchmark freeze` +- artifact digest: `TBD` +- source commit: `TBD or managed-service N/A` +- edition/license: `TBD` +- query language/version: `TBD` +- storage and durability mode: `TBD` +- cluster and replication: `TBD` +- CPU/RAM/NVMe/network: `TBD` +- OS/kernel/filesystem: `TBD` +- dataset URI and digest: `TBD` +- loader command and duration: `TBD` +- physical bytes by category: `TBD` +- tuning file: `TBD` +- query corpus commit: `TBD` +- raw result URI/digest: `TBD` +- profiler/trace URI: `TBD` +- correctness status: `TBD` +- reviewer and rerun date: `TBD` diff --git a/docs/research/engine-datastax_enterprise_graph.md b/docs/research/engine-datastax_enterprise_graph.md new file mode 100644 index 0000000..bde3921 --- /dev/null +++ b/docs/research/engine-datastax_enterprise_graph.md @@ -0,0 +1,884 @@ +# DataStax Enterprise Graph: 2026 deep technical and competitive specification + +Research cut: `2026-08-08` +Status: evidence-backed competitor audit; not a vendor endorsement +Family: `Cassandra-integrated distributed graph` +Evidence convention: **Observed/official**, **Vendor claim**, **Research inference**, **Unknown**, **Qualification target**. + +## 1. Decision summary + +DSE Graph is a historical PB-distributed reference and exposes the latency cost of building graph semantics on Cassandra-scale storage. + +This document answers two questions: what this engine actually proves in 2026, and what zu must build or measure to earn a defensible advantage. A missing public detail remains unknown; it is never silently filled with a favorable assumption. + +### Snapshot card + +- Lifecycle: maintained DSE 6.9 documentation; legacy strategic baseline rather than a modern standalone graph focus. +- Data model: property graph. +- Query surface: Gremlin/TinkerPop. +- Persistent layout: graph records and indexes integrated with DataStax Enterprise/Cassandra, Search, and Analytics. +- Execution: Gremlin traversal with DSE Search and Spark analytics integrations. +- Transactions: Cassandra/DSE consistency and graph transaction behavior; not universal serializable graph ACID. +- Distribution: shared-nothing Cassandra distribution and replication. +- Object-storage posture: not S3-native. +- License/commercial boundary: commercial proprietary. +- Scale evidence: DSE platform advertises petabyte data and graph billions, but graph-specific interactive proof must be separated. +- Benchmark posture: include Cassandra replication, consistency, Solr/Search, and Spark sidecars in resources. + +### Facts that materially affect comparison + +- F01 — DSE Graph is tightly integrated with Apache Cassandra lineage. +- F02 — It uses the TinkerPop/Gremlin programming model. +- F03 — Search and analytics are separate integrated subsystems that add resources and consistency considerations. +- F04 — Petabyte platform capacity is not automatically petabyte low-latency graph capacity. +- F05 — JanusGraph is the more relevant open modular Cassandra comparator, but DSE Graph remains a commercial deployment baseline. + +### Bottom-line fit against zu's target + +- Very-low latency: compare hot point and bounded traversal paths; never extrapolate from scans or algorithms. +- Very-low resources: charge resident set, page cache, remote cache, background services, and replicas. +- Distributed: distinguish read replication, partitioned capacity, distributed transactions, and elastic stateless compute. +- Fixed cost: no engine has fixed marginal cost by declaration; admission, batching, and capacity reservations create the bound. +- S3 authority: backups, imports, lake scans, and S3-native demand paging are four different architectures. +- PB / trillion-edge scale: require a capacity derivation plus a run at the largest affordable scale; marketing adjectives do not qualify. +- Tenfold win: can be a per-cell qualification result, never a universal statement across incomparable workloads. + +## 2. Product and ecosystem boundary + +The audited unit is **DataStax Enterprise Graph** in the exact release, edition, deployment, and durability mode recorded by the harness. The family classification is **Cassandra-integrated distributed graph**. The current lifecycle statement is: maintained DSE 6.9 documentation; legacy strategic baseline rather than a modern standalone graph focus. + +The harness must record binary/container digest, source commit when available, build flags, plugins, license/edition, language mode, storage mode, cluster topology, replication factor, durability settings, cache sizes, thread counts, NUMA policy, kernel, filesystem, cloud region, and all environment variables that affect execution. + +A managed service is not placed in a same-hardware chart. It receives a service-level result with provisioned units, region, public price, and observed provider metrics. A historical engine remains useful for regression but cannot support a claim about beating all current competitors. + +## 3. Architecture reconstruction + +### 3.1 Logical model + +DataStax Enterprise Graph exposes property graph. The conformance corpus must test nulls, missing properties, labels/types, direction, self-loops, parallel edges, element equality, path equality, bag semantics, ordering, numeric overflow, string collation, temporal values, and schema evolution. + +### 3.2 Language and compiler + +The public query surface is Gremlin/TinkerPop. Syntax similarity is not semantic equivalence. Every supported construct needs a result oracle and an unsupported-feature declaration. + +### 3.3 Storage + +The best supported storage summary is: graph records and indexes integrated with DataStax Enterprise/Cassandra, Search, and Analytics. This statement must be refined from code, format documentation, or provider counters before using it in a performance explanation. + +### 3.4 Execution + +The best supported execution summary is: Gremlin traversal with DSE Search and Spark analytics integrations. The benchmark profiler must confirm which runtime and operators actually executed. + +### 3.5 Transactions and recovery + +The public contract is: Cassandra/DSE consistency and graph transaction behavior; not universal serializable graph ACID. Exact acknowledgement, isolation anomalies, recovery bounds, and failover behavior remain separate qualification items. + +### 3.6 Distribution + +The deployment shape is: shared-nothing Cassandra distribution and replication. Replication is not capacity sharding; sharding is not distributed ACID; stateless readers are not stateless storage. + +### 3.7 Object storage and cost + +The 2026 posture is: not S3-native. The audit distinguishes authoritative live bytes, derived acceleration, backup, import/export, and spill. + +## 4. Forty-control deep audit + +### 4.1 `product_boundary` + +Audit question: What exact executable, edition, and storage mode is the system under test? + +Current assessment: Pin DataStax Enterprise Graph, lifecycle `maintained DSE 6.9 documentation; legacy strategic baseline rather than a modern standalone graph focus`, and its edition/mode. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.2 `authority` + +Audit question: Which durable component is the source of truth after every acknowledged write? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.3 `identity` + +Audit question: Are node and edge identities stable across compaction, export, replication, and restore? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.4 `parallel_edges` + +Audit question: Can distinct parallel edges retain properties and trail identity end to end? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.5 `schema` + +Audit question: Is the schema open, closed, optional, inferred, or externally mapped? + +Current assessment: Start from `property graph` and test actual constraints. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.6 `labels` + +Audit question: How are multiple labels represented and indexed? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.7 `adjacency_out` + +Audit question: How is outgoing adjacency located, encoded, split, cached, and updated? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.8 `adjacency_in` + +Audit question: Is incoming adjacency first-class, derived, replicated, or a fan-out operation? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.9 `supernodes` + +Audit question: How are million-to-billion-degree vertices represented and scheduled? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.10 `properties` + +Audit question: Are properties co-located, columnar, row-oriented, document-encoded, or remote? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.11 `compression` + +Audit question: Which topology, integer, string, null, and floating encodings are implemented? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.12 `checksums` + +Audit question: What integrity unit is verified on point reads and range reads? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.13 `snapshot` + +Audit question: What exact token pins graph data, schema, statistics, and indexes? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.14 `isolation` + +Audit question: Which anomalies are forbidden at the documented isolation level? + +Current assessment: Published summary: Cassandra/DSE consistency and graph transaction behavior; not universal serializable graph ACID. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.15 `durability` + +Audit question: What device/service acknowledgement is required before commit returns? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.16 `recovery` + +Audit question: What bounds restart work after a clean stop and a crash? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.17 `writer_fencing` + +Audit question: Can a stale writer acknowledge after failover or lease expiry? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.18 `partitioning` + +Audit question: What key determines placement and what happens to cross-partition edges? + +Current assessment: Published distribution summary: shared-nothing Cassandra distribution and replication. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.19 `rebalancing` + +Audit question: Can placement change online without changing logical identity? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.20 `replication` + +Audit question: Are replicas full, sharded, synchronous, asynchronous, or shared-storage readers? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.21 `optimizer` + +Audit question: Does the optimizer cost graph expansion, joins, network, cache, and remote requests? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.22 `statistics` + +Audit question: Which degree, correlation, path, and property statistics are persistent? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.23 `execution` + +Audit question: Is execution tuple-at-a-time, vectorized, factorized, compiled, matrix, or actor based? + +Current assessment: Expected family: Gremlin traversal with DSE Search and Spark analytics integrations. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.24 `recursion` + +Audit question: How are BFS, shortest paths, trails, simple paths, and arbitrary reachability executed? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.25 `parallelism` + +Audit question: How does the engine avoid skew and nested parallelism under mixed queries? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.26 `memory` + +Audit question: Are all variable allocations charged to bounded query and system budgets? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.27 `spill` + +Audit question: Which operators spill, in what format, and with what admission controls? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.28 `cancellation` + +Audit question: Can cancellation stop CPU, local I/O, remote I/O, retries, and prefetch? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.29 `cache` + +Audit question: What is cached, how is it keyed, admitted, pinned, and evicted? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.30 `cold_start` + +Audit question: What metadata and data round trips are required with empty caches? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.31 `object_requests` + +Audit question: Can a query issue one remote request per node, edge, or result row? + +Current assessment: Published object-store posture: not S3-native. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.32 `cost_admission` + +Audit question: Are request, byte, CPU, spill, and result limits enforced before work? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.33 `observability` + +Audit question: Can operators report rows, edges, bytes, requests, stalls, memory, and spill? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.34 `language` + +Audit question: Which GQL/Cypher/SQL-PGQ/Gremlin/SPARQL semantics are declared and tested? + +Current assessment: Declared surface: Gremlin/TinkerPop. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.35 `updates` + +Audit question: Are DDL, insert, merge, update, detach delete, and constraints complete? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.36 `bulk_load` + +Audit question: Does bulk load preserve transactional and index invariants? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.37 `backup` + +Audit question: Is backup consistent, incremental, immutable, and restore-tested? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.38 `gc` + +Audit question: How are old snapshots, orphan objects, tombstones, and indexes reclaimed safely? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.39 `security` + +Audit question: Are authentication, authorization, encryption, audit, and tenant isolation in scope? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.40 `operations` + +Audit question: What compaction, upgrade, repair, verification, and capacity procedures exist? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +## 5. Benchmark contract for this engine + +Every case runs correctness first, then isolated latency, then closed-loop concurrency, then open-loop overload. Report median, p95, p99, p99.9, timeout/rejection rate, throughput, CPU-seconds, peak RSS, cache bytes, disk bytes, network bytes, remote requests, write amplification, and estimated monthly cost. + +Warm means all intended engine caches are populated without changing the query parameters. Hot means the exact working set is resident. Cold means process-local, engine, OS, NVMe, and remote cache state are explicitly reset or a fresh namespace is used. Those words are never inferred from repetition count. + +### 5.1 `point_pk` — primary-key node lookup with one projected property + +- Applicability to DataStax Enterprise Graph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.2 `point_edge` — stable edge-ID lookup including endpoints and one property + +- Applicability to DataStax Enterprise Graph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.3 `degree_1` — degree-one outgoing expansion + +- Applicability to DataStax Enterprise Graph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.4 `degree_32` — small adjacency expansion around degree 32 + +- Applicability to DataStax Enterprise Graph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.5 `degree_1k` — medium adjacency expansion around degree 1,024 + +- Applicability to DataStax Enterprise Graph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.6 `supernode` — range-limited expansion of a ten-million-degree supernode + +- Applicability to DataStax Enterprise Graph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.7 `expand_2` — selective two-hop expansion + +- Applicability to DataStax Enterprise Graph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.8 `expand_3` — three-hop frontier expansion with duplicate control + +- Applicability to DataStax Enterprise Graph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.9 `expand_into` — edge-existence/expand-into between already-bound endpoints + +- Applicability to DataStax Enterprise Graph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.10 `multi_edge` — parallel-edge identity and property projection + +- Applicability to DataStax Enterprise Graph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.11 `shortest` — bidirectional point-to-point unweighted shortest path + +- Applicability to DataStax Enterprise Graph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.12 `weighted` — weighted shortest path with property access + +- Applicability to DataStax Enterprise Graph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.13 `var_walk` — bounded variable-length walk + +- Applicability to DataStax Enterprise Graph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.14 `trail` — DIFFERENT EDGES trail enumeration + +- Applicability to DataStax Enterprise Graph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.15 `simple` — simple-path enumeration with explicit bound + +- Applicability to DataStax Enterprise Graph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.16 `triangle` — triangle pattern with worst-case-sensitive join + +- Applicability to DataStax Enterprise Graph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.17 `cycle4` — four-cycle pattern + +- Applicability to DataStax Enterprise Graph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.18 `star_join` — high-fanout star pattern with property filters + +- Applicability to DataStax Enterprise Graph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.19 `optional` — optional match preserving null/bag semantics + +- Applicability to DataStax Enterprise Graph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.20 `aggregate` — grouped aggregate after traversal + +- Applicability to DataStax Enterprise Graph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.21 `topk` — ordered top-k with late property materialization + +- Applicability to DataStax Enterprise Graph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.22 `scan` — full projected property scan + +- Applicability to DataStax Enterprise Graph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.23 `selective_scan` — zone/index-pruned selective property scan + +- Applicability to DataStax Enterprise Graph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.24 `mixed` — concurrent short reads, complex reads, and updates + +- Applicability to DataStax Enterprise Graph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.25 `ingest` — sustained transactional ingest with indexes enabled + +- Applicability to DataStax Enterprise Graph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.26 `bulk` — initial bulk load including index/CSR build + +- Applicability to DataStax Enterprise Graph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.27 `checkpoint` — checkpoint or compaction while readers remain active + +- Applicability to DataStax Enterprise Graph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.28 `recovery` — crash recovery at bounded dirty-log size + +- Applicability to DataStax Enterprise Graph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.29 `cold` — same query after clearing engine and OS/cache tiers + +- Applicability to DataStax Enterprise Graph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.30 `remote` — same query with authoritative bytes only in object storage + +- Applicability to DataStax Enterprise Graph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +## 6. Fairness controls + +- Same logical dataset and update stream; engine-native physical layouts are allowed and disclosed. +- Same result semantics; unsupported queries remain unsupported rather than rewritten into easier questions. +- Same durable acknowledgement class for write comparisons. +- Same number of physical cores and memory limit for self-hosted single-node tests. +- Same aggregate resources and replication fault tolerance for distributed tests. +- Officially recommended tuning may be applied before the freeze and is committed with rationale. +- Query-specific hints are allowed only when equivalent hints are offered to every engine and separately charted. +- Load/build/index time and bytes are first-class results. +- Cold, warm, and hot results are separate charts. +- Managed services use public configurations and cannot borrow hidden same-machine resource claims. +- Failed runs, OOMs, correctness mismatches, and timeouts stay in the dataset. +- Every chart links raw samples and the exact reproduction command. + +## 7. Likely advantages and limits + +The strongest known reason to choose this engine is tied to its family `Cassandra-integrated distributed graph`, its execution path `Gremlin traversal with DSE Search and Spark analytics integrations`, and its existing ecosystem. The strongest reason to reject it for zu's target is the gap between `not S3-native` and an S3-authoritative, request-budgeted, PB-scale graph service. + +Capacity statement: DSE platform advertises petabyte data and graph billions, but graph-specific interactive proof must be separated. This is not converted into an edge-count claim without a physical byte model including IDs, both adjacency directions, properties, indexes, MVCC, WAL, replicas, and free space. + +Commercial statement: commercial proprietary. License cost, support cost, and unavailable enterprise capabilities remain visible in TCO and feature tables. + +## 8. Concrete lessons for zu + +1. Keep stable logical node and edge identity independent of row group, CSR slot, shard, and object range. +2. Store forward and reverse adjacency as immutable range-addressable tiles carrying edge IDs. +3. Feed queries adjacency batches and typed vectors; prohibit one storage call per logical element. +4. Use vectorized/factorized execution for property-heavy patterns and dedicated frontier operators for recursion. +5. Cost topology, properties, network, cache certainty, remote requests, and result materialization together. +6. Separate the local embedded profile from the object-authoritative distributed read profile. +7. Fence writers with monotonic epochs and make ambiguous commits reconcilable by transaction ID. +8. Pack small graph tiles into large immutable objects while retaining independent checksums and range offsets. +9. Keep the hot topology working set in RAM/NVMe; batch cold frontier misses into few remote rounds. +10. Admission-control remote requests and bytes so fixed-price plans have an enforceable upper bound. +11. Partition by workload-aware graph locality, and expose cross-partition semantics rather than hiding them. +12. Publish qualified wins per workload cell; never promise a universal tenfold advantage. + +## 9. Evidence gaps to close before publication + +- Exact current version and release date. +- Exact license text for the benchmarked artifact. +- Storage bytes per node/edge/property on all standard datasets. +- Stable-edge-ID and parallel-edge semantics. +- Isolation litmus results and commit acknowledgement point. +- Crash recovery time versus dirty WAL size. +- Supernode behavior and maximum tested degree. +- Cold-start metadata and request count. +- Distributed cross-partition query amplification. +- Peak memory under skew, cancellation, and overload. +- Background compaction/GC effect on tail latency. +- Full load/index/checkpoint/backup resource cost. +- Reproducible largest-scale result. +- Independent or audited benchmark evidence. + +## 10. Primary and official sources + +- [DSE 6.9 Graph overview](https://docs.datastax.com/en/dse/6.9/graph/about-graph.html) +- [Product overview](https://www.datastax.com/products/datastax-graph) +- [LDBC SNB Interactive and audited disclosures](https://ldbcouncil.org/benchmarks/snb/interactive/) +- [LDBC Graphalytics](https://ldbcouncil.org/benchmarks/graphalytics/) +- [SoK: The Faults in our Graph Benchmarks](https://arxiv.org/abs/2404.00766) + +## 11. Source-handling rules + +- Official documentation and source are evidence for implemented or declared behavior, not independent performance. +- A vendor benchmark is labeled vendor claim until the harness reproduces it. +- A peer-reviewed paper establishes only the version, configuration, and workload it evaluated. +- Search snippets, comparison sites, and unsourced blogs are discovery aids, not final evidence. +- Unknown is a valid result and creates a concrete experiment or source-inspection task. +- All web facts are rechecked at benchmark freeze because this corpus is current only through the research date. + +## 12. Reproduction record template + +- engine: `DataStax Enterprise Graph` +- version: `TBD at benchmark freeze` +- artifact digest: `TBD` +- source commit: `TBD or managed-service N/A` +- edition/license: `TBD` +- query language/version: `TBD` +- storage and durability mode: `TBD` +- cluster and replication: `TBD` +- CPU/RAM/NVMe/network: `TBD` +- OS/kernel/filesystem: `TBD` +- dataset URI and digest: `TBD` +- loader command and duration: `TBD` +- physical bytes by category: `TBD` +- tuning file: `TBD` +- query corpus commit: `TBD` +- raw result URI/digest: `TBD` +- profiler/trace URI: `TBD` +- correctness status: `TBD` +- reviewer and rerun date: `TBD` diff --git a/docs/research/engine-dgraph.md b/docs/research/engine-dgraph.md new file mode 100644 index 0000000..9836202 --- /dev/null +++ b/docs/research/engine-dgraph.md @@ -0,0 +1,884 @@ +# Dgraph: 2026 deep technical and competitive specification + +Research cut: `2026-08-08` +Status: evidence-backed competitor audit; not a vendor endorsement +Family: `distributed predicate-sharded graph database` +Evidence convention: **Observed/official**, **Vendor claim**, **Research inference**, **Unknown**, **Qualification target**. + +## 1. Decision summary + +Dgraph is the canonical predicate-sharding counterpoint to source-range adjacency partitioning. + +This document answers two questions: what this engine actually proves in 2026, and what zu must build or measure to earn a defensible advantage. A missing public detail remains unknown; it is never silently filled with a favorable assumption. + +### Snapshot card + +- Lifecycle: active. +- Data model: RDF-like directed graph exposed through DQL and GraphQL. +- Query surface: DQL, GraphQL, admin APIs. +- Persistent layout: Badger-derived LSM KV storage; predicates assigned to Alpha Raft groups. +- Execution: distributed query execution across predicate owners. +- Transactions: ACID with snapshot isolation and conflict detection; linearizable operations described. +- Distribution: Zero control plane plus Alpha Raft groups; predicate sharding and rebalancing. +- Object-storage posture: not S3-native; backups may use object storage. +- License/commercial boundary: Apache-2.0 core. +- Scale evidence: horizontal scale, but hot predicates and cross-group queries are key constraints. +- Benchmark posture: measure predicate skew, network fanout, Raft durability, and GraphQL translation separately. + +### Facts that materially affect comparison + +- F01 — Zero allocates timestamps, UIDs, membership, and predicate placement. +- F02 — Each Alpha group owns predicates and is independently replicated through Raft. +- F03 — Predicate sharding can create hot groups when relationship types are skewed. +- F04 — Queries crossing predicates become distributed even when vertex neighborhoods are otherwise local. +- F05 — GraphQL convenience must not be confused with native graph query expressiveness. + +### Bottom-line fit against zu's target + +- Very-low latency: compare hot point and bounded traversal paths; never extrapolate from scans or algorithms. +- Very-low resources: charge resident set, page cache, remote cache, background services, and replicas. +- Distributed: distinguish read replication, partitioned capacity, distributed transactions, and elastic stateless compute. +- Fixed cost: no engine has fixed marginal cost by declaration; admission, batching, and capacity reservations create the bound. +- S3 authority: backups, imports, lake scans, and S3-native demand paging are four different architectures. +- PB / trillion-edge scale: require a capacity derivation plus a run at the largest affordable scale; marketing adjectives do not qualify. +- Tenfold win: can be a per-cell qualification result, never a universal statement across incomparable workloads. + +## 2. Product and ecosystem boundary + +The audited unit is **Dgraph** in the exact release, edition, deployment, and durability mode recorded by the harness. The family classification is **distributed predicate-sharded graph database**. The current lifecycle statement is: active. + +The harness must record binary/container digest, source commit when available, build flags, plugins, license/edition, language mode, storage mode, cluster topology, replication factor, durability settings, cache sizes, thread counts, NUMA policy, kernel, filesystem, cloud region, and all environment variables that affect execution. + +A managed service is not placed in a same-hardware chart. It receives a service-level result with provisioned units, region, public price, and observed provider metrics. A historical engine remains useful for regression but cannot support a claim about beating all current competitors. + +## 3. Architecture reconstruction + +### 3.1 Logical model + +Dgraph exposes RDF-like directed graph exposed through DQL and GraphQL. The conformance corpus must test nulls, missing properties, labels/types, direction, self-loops, parallel edges, element equality, path equality, bag semantics, ordering, numeric overflow, string collation, temporal values, and schema evolution. + +### 3.2 Language and compiler + +The public query surface is DQL, GraphQL, admin APIs. Syntax similarity is not semantic equivalence. Every supported construct needs a result oracle and an unsupported-feature declaration. + +### 3.3 Storage + +The best supported storage summary is: Badger-derived LSM KV storage; predicates assigned to Alpha Raft groups. This statement must be refined from code, format documentation, or provider counters before using it in a performance explanation. + +### 3.4 Execution + +The best supported execution summary is: distributed query execution across predicate owners. The benchmark profiler must confirm which runtime and operators actually executed. + +### 3.5 Transactions and recovery + +The public contract is: ACID with snapshot isolation and conflict detection; linearizable operations described. Exact acknowledgement, isolation anomalies, recovery bounds, and failover behavior remain separate qualification items. + +### 3.6 Distribution + +The deployment shape is: Zero control plane plus Alpha Raft groups; predicate sharding and rebalancing. Replication is not capacity sharding; sharding is not distributed ACID; stateless readers are not stateless storage. + +### 3.7 Object storage and cost + +The 2026 posture is: not S3-native; backups may use object storage. The audit distinguishes authoritative live bytes, derived acceleration, backup, import/export, and spill. + +## 4. Forty-control deep audit + +### 4.1 `product_boundary` + +Audit question: What exact executable, edition, and storage mode is the system under test? + +Current assessment: Pin Dgraph, lifecycle `active`, and its edition/mode. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.2 `authority` + +Audit question: Which durable component is the source of truth after every acknowledged write? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.3 `identity` + +Audit question: Are node and edge identities stable across compaction, export, replication, and restore? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.4 `parallel_edges` + +Audit question: Can distinct parallel edges retain properties and trail identity end to end? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.5 `schema` + +Audit question: Is the schema open, closed, optional, inferred, or externally mapped? + +Current assessment: Start from `RDF-like directed graph exposed through DQL and GraphQL` and test actual constraints. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.6 `labels` + +Audit question: How are multiple labels represented and indexed? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.7 `adjacency_out` + +Audit question: How is outgoing adjacency located, encoded, split, cached, and updated? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.8 `adjacency_in` + +Audit question: Is incoming adjacency first-class, derived, replicated, or a fan-out operation? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.9 `supernodes` + +Audit question: How are million-to-billion-degree vertices represented and scheduled? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.10 `properties` + +Audit question: Are properties co-located, columnar, row-oriented, document-encoded, or remote? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.11 `compression` + +Audit question: Which topology, integer, string, null, and floating encodings are implemented? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.12 `checksums` + +Audit question: What integrity unit is verified on point reads and range reads? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.13 `snapshot` + +Audit question: What exact token pins graph data, schema, statistics, and indexes? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.14 `isolation` + +Audit question: Which anomalies are forbidden at the documented isolation level? + +Current assessment: Published summary: ACID with snapshot isolation and conflict detection; linearizable operations described. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.15 `durability` + +Audit question: What device/service acknowledgement is required before commit returns? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.16 `recovery` + +Audit question: What bounds restart work after a clean stop and a crash? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.17 `writer_fencing` + +Audit question: Can a stale writer acknowledge after failover or lease expiry? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.18 `partitioning` + +Audit question: What key determines placement and what happens to cross-partition edges? + +Current assessment: Published distribution summary: Zero control plane plus Alpha Raft groups; predicate sharding and rebalancing. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.19 `rebalancing` + +Audit question: Can placement change online without changing logical identity? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.20 `replication` + +Audit question: Are replicas full, sharded, synchronous, asynchronous, or shared-storage readers? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.21 `optimizer` + +Audit question: Does the optimizer cost graph expansion, joins, network, cache, and remote requests? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.22 `statistics` + +Audit question: Which degree, correlation, path, and property statistics are persistent? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.23 `execution` + +Audit question: Is execution tuple-at-a-time, vectorized, factorized, compiled, matrix, or actor based? + +Current assessment: Expected family: distributed query execution across predicate owners. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.24 `recursion` + +Audit question: How are BFS, shortest paths, trails, simple paths, and arbitrary reachability executed? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.25 `parallelism` + +Audit question: How does the engine avoid skew and nested parallelism under mixed queries? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.26 `memory` + +Audit question: Are all variable allocations charged to bounded query and system budgets? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.27 `spill` + +Audit question: Which operators spill, in what format, and with what admission controls? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.28 `cancellation` + +Audit question: Can cancellation stop CPU, local I/O, remote I/O, retries, and prefetch? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.29 `cache` + +Audit question: What is cached, how is it keyed, admitted, pinned, and evicted? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.30 `cold_start` + +Audit question: What metadata and data round trips are required with empty caches? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.31 `object_requests` + +Audit question: Can a query issue one remote request per node, edge, or result row? + +Current assessment: Published object-store posture: not S3-native; backups may use object storage. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.32 `cost_admission` + +Audit question: Are request, byte, CPU, spill, and result limits enforced before work? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.33 `observability` + +Audit question: Can operators report rows, edges, bytes, requests, stalls, memory, and spill? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.34 `language` + +Audit question: Which GQL/Cypher/SQL-PGQ/Gremlin/SPARQL semantics are declared and tested? + +Current assessment: Declared surface: DQL, GraphQL, admin APIs. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.35 `updates` + +Audit question: Are DDL, insert, merge, update, detach delete, and constraints complete? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.36 `bulk_load` + +Audit question: Does bulk load preserve transactional and index invariants? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.37 `backup` + +Audit question: Is backup consistent, incremental, immutable, and restore-tested? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.38 `gc` + +Audit question: How are old snapshots, orphan objects, tombstones, and indexes reclaimed safely? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.39 `security` + +Audit question: Are authentication, authorization, encryption, audit, and tenant isolation in scope? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.40 `operations` + +Audit question: What compaction, upgrade, repair, verification, and capacity procedures exist? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +## 5. Benchmark contract for this engine + +Every case runs correctness first, then isolated latency, then closed-loop concurrency, then open-loop overload. Report median, p95, p99, p99.9, timeout/rejection rate, throughput, CPU-seconds, peak RSS, cache bytes, disk bytes, network bytes, remote requests, write amplification, and estimated monthly cost. + +Warm means all intended engine caches are populated without changing the query parameters. Hot means the exact working set is resident. Cold means process-local, engine, OS, NVMe, and remote cache state are explicitly reset or a fresh namespace is used. Those words are never inferred from repetition count. + +### 5.1 `point_pk` — primary-key node lookup with one projected property + +- Applicability to Dgraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.2 `point_edge` — stable edge-ID lookup including endpoints and one property + +- Applicability to Dgraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.3 `degree_1` — degree-one outgoing expansion + +- Applicability to Dgraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.4 `degree_32` — small adjacency expansion around degree 32 + +- Applicability to Dgraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.5 `degree_1k` — medium adjacency expansion around degree 1,024 + +- Applicability to Dgraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.6 `supernode` — range-limited expansion of a ten-million-degree supernode + +- Applicability to Dgraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.7 `expand_2` — selective two-hop expansion + +- Applicability to Dgraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.8 `expand_3` — three-hop frontier expansion with duplicate control + +- Applicability to Dgraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.9 `expand_into` — edge-existence/expand-into between already-bound endpoints + +- Applicability to Dgraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.10 `multi_edge` — parallel-edge identity and property projection + +- Applicability to Dgraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.11 `shortest` — bidirectional point-to-point unweighted shortest path + +- Applicability to Dgraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.12 `weighted` — weighted shortest path with property access + +- Applicability to Dgraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.13 `var_walk` — bounded variable-length walk + +- Applicability to Dgraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.14 `trail` — DIFFERENT EDGES trail enumeration + +- Applicability to Dgraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.15 `simple` — simple-path enumeration with explicit bound + +- Applicability to Dgraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.16 `triangle` — triangle pattern with worst-case-sensitive join + +- Applicability to Dgraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.17 `cycle4` — four-cycle pattern + +- Applicability to Dgraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.18 `star_join` — high-fanout star pattern with property filters + +- Applicability to Dgraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.19 `optional` — optional match preserving null/bag semantics + +- Applicability to Dgraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.20 `aggregate` — grouped aggregate after traversal + +- Applicability to Dgraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.21 `topk` — ordered top-k with late property materialization + +- Applicability to Dgraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.22 `scan` — full projected property scan + +- Applicability to Dgraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.23 `selective_scan` — zone/index-pruned selective property scan + +- Applicability to Dgraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.24 `mixed` — concurrent short reads, complex reads, and updates + +- Applicability to Dgraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.25 `ingest` — sustained transactional ingest with indexes enabled + +- Applicability to Dgraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.26 `bulk` — initial bulk load including index/CSR build + +- Applicability to Dgraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.27 `checkpoint` — checkpoint or compaction while readers remain active + +- Applicability to Dgraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.28 `recovery` — crash recovery at bounded dirty-log size + +- Applicability to Dgraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.29 `cold` — same query after clearing engine and OS/cache tiers + +- Applicability to Dgraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.30 `remote` — same query with authoritative bytes only in object storage + +- Applicability to Dgraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +## 6. Fairness controls + +- Same logical dataset and update stream; engine-native physical layouts are allowed and disclosed. +- Same result semantics; unsupported queries remain unsupported rather than rewritten into easier questions. +- Same durable acknowledgement class for write comparisons. +- Same number of physical cores and memory limit for self-hosted single-node tests. +- Same aggregate resources and replication fault tolerance for distributed tests. +- Officially recommended tuning may be applied before the freeze and is committed with rationale. +- Query-specific hints are allowed only when equivalent hints are offered to every engine and separately charted. +- Load/build/index time and bytes are first-class results. +- Cold, warm, and hot results are separate charts. +- Managed services use public configurations and cannot borrow hidden same-machine resource claims. +- Failed runs, OOMs, correctness mismatches, and timeouts stay in the dataset. +- Every chart links raw samples and the exact reproduction command. + +## 7. Likely advantages and limits + +The strongest known reason to choose this engine is tied to its family `distributed predicate-sharded graph database`, its execution path `distributed query execution across predicate owners`, and its existing ecosystem. The strongest reason to reject it for zu's target is the gap between `not S3-native; backups may use object storage` and an S3-authoritative, request-budgeted, PB-scale graph service. + +Capacity statement: horizontal scale, but hot predicates and cross-group queries are key constraints. This is not converted into an edge-count claim without a physical byte model including IDs, both adjacency directions, properties, indexes, MVCC, WAL, replicas, and free space. + +Commercial statement: Apache-2.0 core. License cost, support cost, and unavailable enterprise capabilities remain visible in TCO and feature tables. + +## 8. Concrete lessons for zu + +1. Keep stable logical node and edge identity independent of row group, CSR slot, shard, and object range. +2. Store forward and reverse adjacency as immutable range-addressable tiles carrying edge IDs. +3. Feed queries adjacency batches and typed vectors; prohibit one storage call per logical element. +4. Use vectorized/factorized execution for property-heavy patterns and dedicated frontier operators for recursion. +5. Cost topology, properties, network, cache certainty, remote requests, and result materialization together. +6. Separate the local embedded profile from the object-authoritative distributed read profile. +7. Fence writers with monotonic epochs and make ambiguous commits reconcilable by transaction ID. +8. Pack small graph tiles into large immutable objects while retaining independent checksums and range offsets. +9. Keep the hot topology working set in RAM/NVMe; batch cold frontier misses into few remote rounds. +10. Admission-control remote requests and bytes so fixed-price plans have an enforceable upper bound. +11. Partition by workload-aware graph locality, and expose cross-partition semantics rather than hiding them. +12. Publish qualified wins per workload cell; never promise a universal tenfold advantage. + +## 9. Evidence gaps to close before publication + +- Exact current version and release date. +- Exact license text for the benchmarked artifact. +- Storage bytes per node/edge/property on all standard datasets. +- Stable-edge-ID and parallel-edge semantics. +- Isolation litmus results and commit acknowledgement point. +- Crash recovery time versus dirty WAL size. +- Supernode behavior and maximum tested degree. +- Cold-start metadata and request count. +- Distributed cross-partition query amplification. +- Peak memory under skew, cancellation, and overload. +- Background compaction/GC effect on tail latency. +- Full load/index/checkpoint/backup resource cost. +- Reproducible largest-scale result. +- Independent or audited benchmark evidence. + +## 10. Primary and official sources + +- [Architecture and consistency](https://www.dgraph.io/installation/dgraph-architecture/) +- [Source repository](https://github.com/dgraph-io/dgraph) +- [LDBC SNB Interactive and audited disclosures](https://ldbcouncil.org/benchmarks/snb/interactive/) +- [LDBC Graphalytics](https://ldbcouncil.org/benchmarks/graphalytics/) +- [SoK: The Faults in our Graph Benchmarks](https://arxiv.org/abs/2404.00766) + +## 11. Source-handling rules + +- Official documentation and source are evidence for implemented or declared behavior, not independent performance. +- A vendor benchmark is labeled vendor claim until the harness reproduces it. +- A peer-reviewed paper establishes only the version, configuration, and workload it evaluated. +- Search snippets, comparison sites, and unsourced blogs are discovery aids, not final evidence. +- Unknown is a valid result and creates a concrete experiment or source-inspection task. +- All web facts are rechecked at benchmark freeze because this corpus is current only through the research date. + +## 12. Reproduction record template + +- engine: `Dgraph` +- version: `TBD at benchmark freeze` +- artifact digest: `TBD` +- source commit: `TBD or managed-service N/A` +- edition/license: `TBD` +- query language/version: `TBD` +- storage and durability mode: `TBD` +- cluster and replication: `TBD` +- CPU/RAM/NVMe/network: `TBD` +- OS/kernel/filesystem: `TBD` +- dataset URI and digest: `TBD` +- loader command and duration: `TBD` +- physical bytes by category: `TBD` +- tuning file: `TBD` +- query corpus commit: `TBD` +- raw result URI/digest: `TBD` +- profiler/trace URI: `TBD` +- correctness status: `TBD` +- reviewer and rerun date: `TBD` diff --git a/docs/research/engine-duckpgq.md b/docs/research/engine-duckpgq.md new file mode 100644 index 0000000..c780203 --- /dev/null +++ b/docs/research/engine-duckpgq.md @@ -0,0 +1,886 @@ +# DuckPGQ: 2026 deep technical and competitive specification + +Research cut: `2026-08-08` +Status: evidence-backed competitor audit; not a vendor endorsement +Family: `analytical SQL/PGQ extension` +Evidence convention: **Observed/official**, **Vendor claim**, **Research inference**, **Unknown**, **Qualification target**. + +## 1. Decision summary + +DuckPGQ is the fairest relational/SQL standards baseline and exposes the cost of rebuilding topology indexes. + +This document answers two questions: what this engine actually proves in 2026, and what zu must build or measure to earn a defensible advantage. A missing public detail remains unknown; it is never silently filled with a favorable assumption. + +### Snapshot card + +- Lifecycle: active CWI project. +- Data model: transient property graph declarations over DuckDB tables. +- Query surface: SQL/PGQ. +- Persistent layout: DuckDB columnar storage plus per-connection in-memory CSR structures. +- Execution: DuckDB vectorized SQL extended with graph matching and path algorithms. +- Transactions: inherits DuckDB transaction model; graph declarations are connection-scoped. +- Distribution: embedded single-node. +- Object-storage posture: DuckDB can query object files, but DuckPGQ CSR construction is not an S3-native persistent graph index. +- License/commercial boundary: MIT. +- Scale evidence: single-node analytics; CSR memory limits matter. +- Benchmark posture: include CSR-build time and memory, never report query-only numbers alone. + +### Facts that materially affect comparison + +- F01 — Property graph definitions are transient and live for the connection. +- F02 — The engine creates CSR structures from relational tables. +- F03 — SQL/PGQ enables graph patterns without a separate graph database. +- F04 — Multi-source BFS benefits only for suitable source batches and hardware. +- F05 — End-to-end benchmarking must charge table scan, CSR construction, and query execution. + +### Bottom-line fit against zu's target + +- Very-low latency: compare hot point and bounded traversal paths; never extrapolate from scans or algorithms. +- Very-low resources: charge resident set, page cache, remote cache, background services, and replicas. +- Distributed: distinguish read replication, partitioned capacity, distributed transactions, and elastic stateless compute. +- Fixed cost: no engine has fixed marginal cost by declaration; admission, batching, and capacity reservations create the bound. +- S3 authority: backups, imports, lake scans, and S3-native demand paging are four different architectures. +- PB / trillion-edge scale: require a capacity derivation plus a run at the largest affordable scale; marketing adjectives do not qualify. +- Tenfold win: can be a per-cell qualification result, never a universal statement across incomparable workloads. + +## 2. Product and ecosystem boundary + +The audited unit is **DuckPGQ** in the exact release, edition, deployment, and durability mode recorded by the harness. The family classification is **analytical SQL/PGQ extension**. The current lifecycle statement is: active CWI project. + +The harness must record binary/container digest, source commit when available, build flags, plugins, license/edition, language mode, storage mode, cluster topology, replication factor, durability settings, cache sizes, thread counts, NUMA policy, kernel, filesystem, cloud region, and all environment variables that affect execution. + +A managed service is not placed in a same-hardware chart. It receives a service-level result with provisioned units, region, public price, and observed provider metrics. A historical engine remains useful for regression but cannot support a claim about beating all current competitors. + +## 3. Architecture reconstruction + +### 3.1 Logical model + +DuckPGQ exposes transient property graph declarations over DuckDB tables. The conformance corpus must test nulls, missing properties, labels/types, direction, self-loops, parallel edges, element equality, path equality, bag semantics, ordering, numeric overflow, string collation, temporal values, and schema evolution. + +### 3.2 Language and compiler + +The public query surface is SQL/PGQ. Syntax similarity is not semantic equivalence. Every supported construct needs a result oracle and an unsupported-feature declaration. + +### 3.3 Storage + +The best supported storage summary is: DuckDB columnar storage plus per-connection in-memory CSR structures. This statement must be refined from code, format documentation, or provider counters before using it in a performance explanation. + +### 3.4 Execution + +The best supported execution summary is: DuckDB vectorized SQL extended with graph matching and path algorithms. The benchmark profiler must confirm which runtime and operators actually executed. + +### 3.5 Transactions and recovery + +The public contract is: inherits DuckDB transaction model; graph declarations are connection-scoped. Exact acknowledgement, isolation anomalies, recovery bounds, and failover behavior remain separate qualification items. + +### 3.6 Distribution + +The deployment shape is: embedded single-node. Replication is not capacity sharding; sharding is not distributed ACID; stateless readers are not stateless storage. + +### 3.7 Object storage and cost + +The 2026 posture is: DuckDB can query object files, but DuckPGQ CSR construction is not an S3-native persistent graph index. The audit distinguishes authoritative live bytes, derived acceleration, backup, import/export, and spill. + +## 4. Forty-control deep audit + +### 4.1 `product_boundary` + +Audit question: What exact executable, edition, and storage mode is the system under test? + +Current assessment: Pin DuckPGQ, lifecycle `active CWI project`, and its edition/mode. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.2 `authority` + +Audit question: Which durable component is the source of truth after every acknowledged write? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.3 `identity` + +Audit question: Are node and edge identities stable across compaction, export, replication, and restore? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.4 `parallel_edges` + +Audit question: Can distinct parallel edges retain properties and trail identity end to end? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.5 `schema` + +Audit question: Is the schema open, closed, optional, inferred, or externally mapped? + +Current assessment: Start from `transient property graph declarations over DuckDB tables` and test actual constraints. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.6 `labels` + +Audit question: How are multiple labels represented and indexed? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.7 `adjacency_out` + +Audit question: How is outgoing adjacency located, encoded, split, cached, and updated? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.8 `adjacency_in` + +Audit question: Is incoming adjacency first-class, derived, replicated, or a fan-out operation? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.9 `supernodes` + +Audit question: How are million-to-billion-degree vertices represented and scheduled? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.10 `properties` + +Audit question: Are properties co-located, columnar, row-oriented, document-encoded, or remote? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.11 `compression` + +Audit question: Which topology, integer, string, null, and floating encodings are implemented? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.12 `checksums` + +Audit question: What integrity unit is verified on point reads and range reads? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.13 `snapshot` + +Audit question: What exact token pins graph data, schema, statistics, and indexes? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.14 `isolation` + +Audit question: Which anomalies are forbidden at the documented isolation level? + +Current assessment: Published summary: inherits DuckDB transaction model; graph declarations are connection-scoped. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.15 `durability` + +Audit question: What device/service acknowledgement is required before commit returns? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.16 `recovery` + +Audit question: What bounds restart work after a clean stop and a crash? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.17 `writer_fencing` + +Audit question: Can a stale writer acknowledge after failover or lease expiry? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.18 `partitioning` + +Audit question: What key determines placement and what happens to cross-partition edges? + +Current assessment: Published distribution summary: embedded single-node. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.19 `rebalancing` + +Audit question: Can placement change online without changing logical identity? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.20 `replication` + +Audit question: Are replicas full, sharded, synchronous, asynchronous, or shared-storage readers? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.21 `optimizer` + +Audit question: Does the optimizer cost graph expansion, joins, network, cache, and remote requests? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.22 `statistics` + +Audit question: Which degree, correlation, path, and property statistics are persistent? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.23 `execution` + +Audit question: Is execution tuple-at-a-time, vectorized, factorized, compiled, matrix, or actor based? + +Current assessment: Expected family: DuckDB vectorized SQL extended with graph matching and path algorithms. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.24 `recursion` + +Audit question: How are BFS, shortest paths, trails, simple paths, and arbitrary reachability executed? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.25 `parallelism` + +Audit question: How does the engine avoid skew and nested parallelism under mixed queries? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.26 `memory` + +Audit question: Are all variable allocations charged to bounded query and system budgets? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.27 `spill` + +Audit question: Which operators spill, in what format, and with what admission controls? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.28 `cancellation` + +Audit question: Can cancellation stop CPU, local I/O, remote I/O, retries, and prefetch? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.29 `cache` + +Audit question: What is cached, how is it keyed, admitted, pinned, and evicted? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.30 `cold_start` + +Audit question: What metadata and data round trips are required with empty caches? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.31 `object_requests` + +Audit question: Can a query issue one remote request per node, edge, or result row? + +Current assessment: Published object-store posture: DuckDB can query object files, but DuckPGQ CSR construction is not an S3-native persistent graph index. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.32 `cost_admission` + +Audit question: Are request, byte, CPU, spill, and result limits enforced before work? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.33 `observability` + +Audit question: Can operators report rows, edges, bytes, requests, stalls, memory, and spill? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.34 `language` + +Audit question: Which GQL/Cypher/SQL-PGQ/Gremlin/SPARQL semantics are declared and tested? + +Current assessment: Declared surface: SQL/PGQ. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.35 `updates` + +Audit question: Are DDL, insert, merge, update, detach delete, and constraints complete? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.36 `bulk_load` + +Audit question: Does bulk load preserve transactional and index invariants? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.37 `backup` + +Audit question: Is backup consistent, incremental, immutable, and restore-tested? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.38 `gc` + +Audit question: How are old snapshots, orphan objects, tombstones, and indexes reclaimed safely? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.39 `security` + +Audit question: Are authentication, authorization, encryption, audit, and tenant isolation in scope? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.40 `operations` + +Audit question: What compaction, upgrade, repair, verification, and capacity procedures exist? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +## 5. Benchmark contract for this engine + +Every case runs correctness first, then isolated latency, then closed-loop concurrency, then open-loop overload. Report median, p95, p99, p99.9, timeout/rejection rate, throughput, CPU-seconds, peak RSS, cache bytes, disk bytes, network bytes, remote requests, write amplification, and estimated monthly cost. + +Warm means all intended engine caches are populated without changing the query parameters. Hot means the exact working set is resident. Cold means process-local, engine, OS, NVMe, and remote cache state are explicitly reset or a fresh namespace is used. Those words are never inferred from repetition count. + +### 5.1 `point_pk` — primary-key node lookup with one projected property + +- Applicability to DuckPGQ: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.2 `point_edge` — stable edge-ID lookup including endpoints and one property + +- Applicability to DuckPGQ: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.3 `degree_1` — degree-one outgoing expansion + +- Applicability to DuckPGQ: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.4 `degree_32` — small adjacency expansion around degree 32 + +- Applicability to DuckPGQ: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.5 `degree_1k` — medium adjacency expansion around degree 1,024 + +- Applicability to DuckPGQ: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.6 `supernode` — range-limited expansion of a ten-million-degree supernode + +- Applicability to DuckPGQ: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.7 `expand_2` — selective two-hop expansion + +- Applicability to DuckPGQ: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.8 `expand_3` — three-hop frontier expansion with duplicate control + +- Applicability to DuckPGQ: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.9 `expand_into` — edge-existence/expand-into between already-bound endpoints + +- Applicability to DuckPGQ: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.10 `multi_edge` — parallel-edge identity and property projection + +- Applicability to DuckPGQ: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.11 `shortest` — bidirectional point-to-point unweighted shortest path + +- Applicability to DuckPGQ: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.12 `weighted` — weighted shortest path with property access + +- Applicability to DuckPGQ: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.13 `var_walk` — bounded variable-length walk + +- Applicability to DuckPGQ: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.14 `trail` — DIFFERENT EDGES trail enumeration + +- Applicability to DuckPGQ: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.15 `simple` — simple-path enumeration with explicit bound + +- Applicability to DuckPGQ: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.16 `triangle` — triangle pattern with worst-case-sensitive join + +- Applicability to DuckPGQ: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.17 `cycle4` — four-cycle pattern + +- Applicability to DuckPGQ: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.18 `star_join` — high-fanout star pattern with property filters + +- Applicability to DuckPGQ: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.19 `optional` — optional match preserving null/bag semantics + +- Applicability to DuckPGQ: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.20 `aggregate` — grouped aggregate after traversal + +- Applicability to DuckPGQ: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.21 `topk` — ordered top-k with late property materialization + +- Applicability to DuckPGQ: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.22 `scan` — full projected property scan + +- Applicability to DuckPGQ: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.23 `selective_scan` — zone/index-pruned selective property scan + +- Applicability to DuckPGQ: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.24 `mixed` — concurrent short reads, complex reads, and updates + +- Applicability to DuckPGQ: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.25 `ingest` — sustained transactional ingest with indexes enabled + +- Applicability to DuckPGQ: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.26 `bulk` — initial bulk load including index/CSR build + +- Applicability to DuckPGQ: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.27 `checkpoint` — checkpoint or compaction while readers remain active + +- Applicability to DuckPGQ: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.28 `recovery` — crash recovery at bounded dirty-log size + +- Applicability to DuckPGQ: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.29 `cold` — same query after clearing engine and OS/cache tiers + +- Applicability to DuckPGQ: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.30 `remote` — same query with authoritative bytes only in object storage + +- Applicability to DuckPGQ: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +## 6. Fairness controls + +- Same logical dataset and update stream; engine-native physical layouts are allowed and disclosed. +- Same result semantics; unsupported queries remain unsupported rather than rewritten into easier questions. +- Same durable acknowledgement class for write comparisons. +- Same number of physical cores and memory limit for self-hosted single-node tests. +- Same aggregate resources and replication fault tolerance for distributed tests. +- Officially recommended tuning may be applied before the freeze and is committed with rationale. +- Query-specific hints are allowed only when equivalent hints are offered to every engine and separately charted. +- Load/build/index time and bytes are first-class results. +- Cold, warm, and hot results are separate charts. +- Managed services use public configurations and cannot borrow hidden same-machine resource claims. +- Failed runs, OOMs, correctness mismatches, and timeouts stay in the dataset. +- Every chart links raw samples and the exact reproduction command. + +## 7. Likely advantages and limits + +The strongest known reason to choose this engine is tied to its family `analytical SQL/PGQ extension`, its execution path `DuckDB vectorized SQL extended with graph matching and path algorithms`, and its existing ecosystem. The strongest reason to reject it for zu's target is the gap between `DuckDB can query object files, but DuckPGQ CSR construction is not an S3-native persistent graph index` and an S3-authoritative, request-budgeted, PB-scale graph service. + +Capacity statement: single-node analytics; CSR memory limits matter. This is not converted into an edge-count claim without a physical byte model including IDs, both adjacency directions, properties, indexes, MVCC, WAL, replicas, and free space. + +Commercial statement: MIT. License cost, support cost, and unavailable enterprise capabilities remain visible in TCO and feature tables. + +## 8. Concrete lessons for zu + +1. Keep stable logical node and edge identity independent of row group, CSR slot, shard, and object range. +2. Store forward and reverse adjacency as immutable range-addressable tiles carrying edge IDs. +3. Feed queries adjacency batches and typed vectors; prohibit one storage call per logical element. +4. Use vectorized/factorized execution for property-heavy patterns and dedicated frontier operators for recursion. +5. Cost topology, properties, network, cache certainty, remote requests, and result materialization together. +6. Separate the local embedded profile from the object-authoritative distributed read profile. +7. Fence writers with monotonic epochs and make ambiguous commits reconcilable by transaction ID. +8. Pack small graph tiles into large immutable objects while retaining independent checksums and range offsets. +9. Keep the hot topology working set in RAM/NVMe; batch cold frontier misses into few remote rounds. +10. Admission-control remote requests and bytes so fixed-price plans have an enforceable upper bound. +11. Partition by workload-aware graph locality, and expose cross-partition semantics rather than hiding them. +12. Publish qualified wins per workload cell; never promise a universal tenfold advantage. + +## 9. Evidence gaps to close before publication + +- Exact current version and release date. +- Exact license text for the benchmarked artifact. +- Storage bytes per node/edge/property on all standard datasets. +- Stable-edge-ID and parallel-edge semantics. +- Isolation litmus results and commit acknowledgement point. +- Crash recovery time versus dirty WAL size. +- Supernode behavior and maximum tested degree. +- Cold-start metadata and request count. +- Distributed cross-partition query amplification. +- Peak memory under skew, cancellation, and overload. +- Background compaction/GC effect on tail latency. +- Full load/index/checkpoint/backup resource cost. +- Reproducible largest-scale result. +- Independent or audited benchmark evidence. + +## 10. Primary and official sources + +- [Official site](https://duckpgq.org/) +- [Property graph docs](https://duckpgq.org/documentation/property_graph/) +- [CWI paper](https://ir.cwi.nl/pub/33317/33317.pdf) +- [Source repository](https://github.com/cwida/duckpgq-extension) +- [LDBC SNB Interactive and audited disclosures](https://ldbcouncil.org/benchmarks/snb/interactive/) +- [LDBC Graphalytics](https://ldbcouncil.org/benchmarks/graphalytics/) +- [SoK: The Faults in our Graph Benchmarks](https://arxiv.org/abs/2404.00766) + +## 11. Source-handling rules + +- Official documentation and source are evidence for implemented or declared behavior, not independent performance. +- A vendor benchmark is labeled vendor claim until the harness reproduces it. +- A peer-reviewed paper establishes only the version, configuration, and workload it evaluated. +- Search snippets, comparison sites, and unsourced blogs are discovery aids, not final evidence. +- Unknown is a valid result and creates a concrete experiment or source-inspection task. +- All web facts are rechecked at benchmark freeze because this corpus is current only through the research date. + +## 12. Reproduction record template + +- engine: `DuckPGQ` +- version: `TBD at benchmark freeze` +- artifact digest: `TBD` +- source commit: `TBD or managed-service N/A` +- edition/license: `TBD` +- query language/version: `TBD` +- storage and durability mode: `TBD` +- cluster and replication: `TBD` +- CPU/RAM/NVMe/network: `TBD` +- OS/kernel/filesystem: `TBD` +- dataset URI and digest: `TBD` +- loader command and duration: `TBD` +- physical bytes by category: `TBD` +- tuning file: `TBD` +- query corpus commit: `TBD` +- raw result URI/digest: `TBD` +- profiler/trace URI: `TBD` +- correctness status: `TBD` +- reviewer and rerun date: `TBD` diff --git a/docs/research/engine-falkordb.md b/docs/research/engine-falkordb.md new file mode 100644 index 0000000..77a6daa --- /dev/null +++ b/docs/research/engine-falkordb.md @@ -0,0 +1,885 @@ +# FalkorDB: 2026 deep technical and competitive specification + +Research cut: `2026-08-08` +Status: evidence-backed competitor audit; not a vendor endorsement +Family: `matrix property graph` +Evidence convention: **Observed/official**, **Vendor claim**, **Research inference**, **Unknown**, **Qualification target**. + +## 1. Decision summary + +FalkorDB is the most direct sparse-linear-algebra competitor and a required point/traversal baseline. + +This document answers two questions: what this engine actually proves in 2026, and what zu must build or measure to earn a defensible advantage. A missing public detail remains unknown; it is never silently filled with a favorable assumption. + +### Snapshot card + +- Lifecycle: active; Rust transition and Redis-module lineage. +- Data model: property graph represented with sparse matrices plus attribute stores. +- Query surface: openCypher with extensions; Bolt and RESP access. +- Persistent layout: sparse GraphBLAS adjacency matrices, Redis-derived persistence and auxiliary indices. +- Execution: algebraic traversal plus a modern columnar/batch execution path. +- Transactions: MVCC direction is active; exact guarantees must be verified per release/deployment. +- Distribution: single node and commercial/cloud scale-out offerings; open core must be separated from service claims. +- Object-storage posture: not an object-store-native live engine. +- License/commercial boundary: SSPLv1 in current official docs; commercial cloud terms separately. +- Scale evidence: excellent dense set-at-a-time traversal potential; PB evidence is not public. +- Benchmark posture: vendor benchmark suite exists; require pinned queries, data, hardware, and durability. + +### Facts that materially affect comparison + +- F01 — FalkorDB descends from RedisGraph and uses SuiteSparse:GraphBLAS concepts for adjacency. +- F02 — Sparse matrices can turn multi-source traversal into efficient set operations but may pay for property-heavy joins. +- F03 — The active rewrite makes version pinning essential because architecture and behavior are moving quickly. +- F04 — Redis module heritage affects persistence, memory accounting, and operational shape. +- F05 — GraphRAG marketing is not evidence for graph-kernel performance. + +### Bottom-line fit against zu's target + +- Very-low latency: compare hot point and bounded traversal paths; never extrapolate from scans or algorithms. +- Very-low resources: charge resident set, page cache, remote cache, background services, and replicas. +- Distributed: distinguish read replication, partitioned capacity, distributed transactions, and elastic stateless compute. +- Fixed cost: no engine has fixed marginal cost by declaration; admission, batching, and capacity reservations create the bound. +- S3 authority: backups, imports, lake scans, and S3-native demand paging are four different architectures. +- PB / trillion-edge scale: require a capacity derivation plus a run at the largest affordable scale; marketing adjectives do not qualify. +- Tenfold win: can be a per-cell qualification result, never a universal statement across incomparable workloads. + +## 2. Product and ecosystem boundary + +The audited unit is **FalkorDB** in the exact release, edition, deployment, and durability mode recorded by the harness. The family classification is **matrix property graph**. The current lifecycle statement is: active; Rust transition and Redis-module lineage. + +The harness must record binary/container digest, source commit when available, build flags, plugins, license/edition, language mode, storage mode, cluster topology, replication factor, durability settings, cache sizes, thread counts, NUMA policy, kernel, filesystem, cloud region, and all environment variables that affect execution. + +A managed service is not placed in a same-hardware chart. It receives a service-level result with provisioned units, region, public price, and observed provider metrics. A historical engine remains useful for regression but cannot support a claim about beating all current competitors. + +## 3. Architecture reconstruction + +### 3.1 Logical model + +FalkorDB exposes property graph represented with sparse matrices plus attribute stores. The conformance corpus must test nulls, missing properties, labels/types, direction, self-loops, parallel edges, element equality, path equality, bag semantics, ordering, numeric overflow, string collation, temporal values, and schema evolution. + +### 3.2 Language and compiler + +The public query surface is openCypher with extensions; Bolt and RESP access. Syntax similarity is not semantic equivalence. Every supported construct needs a result oracle and an unsupported-feature declaration. + +### 3.3 Storage + +The best supported storage summary is: sparse GraphBLAS adjacency matrices, Redis-derived persistence and auxiliary indices. This statement must be refined from code, format documentation, or provider counters before using it in a performance explanation. + +### 3.4 Execution + +The best supported execution summary is: algebraic traversal plus a modern columnar/batch execution path. The benchmark profiler must confirm which runtime and operators actually executed. + +### 3.5 Transactions and recovery + +The public contract is: MVCC direction is active; exact guarantees must be verified per release/deployment. Exact acknowledgement, isolation anomalies, recovery bounds, and failover behavior remain separate qualification items. + +### 3.6 Distribution + +The deployment shape is: single node and commercial/cloud scale-out offerings; open core must be separated from service claims. Replication is not capacity sharding; sharding is not distributed ACID; stateless readers are not stateless storage. + +### 3.7 Object storage and cost + +The 2026 posture is: not an object-store-native live engine. The audit distinguishes authoritative live bytes, derived acceleration, backup, import/export, and spill. + +## 4. Forty-control deep audit + +### 4.1 `product_boundary` + +Audit question: What exact executable, edition, and storage mode is the system under test? + +Current assessment: Pin FalkorDB, lifecycle `active; Rust transition and Redis-module lineage`, and its edition/mode. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.2 `authority` + +Audit question: Which durable component is the source of truth after every acknowledged write? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.3 `identity` + +Audit question: Are node and edge identities stable across compaction, export, replication, and restore? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.4 `parallel_edges` + +Audit question: Can distinct parallel edges retain properties and trail identity end to end? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.5 `schema` + +Audit question: Is the schema open, closed, optional, inferred, or externally mapped? + +Current assessment: Start from `property graph represented with sparse matrices plus attribute stores` and test actual constraints. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.6 `labels` + +Audit question: How are multiple labels represented and indexed? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.7 `adjacency_out` + +Audit question: How is outgoing adjacency located, encoded, split, cached, and updated? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.8 `adjacency_in` + +Audit question: Is incoming adjacency first-class, derived, replicated, or a fan-out operation? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.9 `supernodes` + +Audit question: How are million-to-billion-degree vertices represented and scheduled? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.10 `properties` + +Audit question: Are properties co-located, columnar, row-oriented, document-encoded, or remote? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.11 `compression` + +Audit question: Which topology, integer, string, null, and floating encodings are implemented? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.12 `checksums` + +Audit question: What integrity unit is verified on point reads and range reads? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.13 `snapshot` + +Audit question: What exact token pins graph data, schema, statistics, and indexes? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.14 `isolation` + +Audit question: Which anomalies are forbidden at the documented isolation level? + +Current assessment: Published summary: MVCC direction is active; exact guarantees must be verified per release/deployment. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.15 `durability` + +Audit question: What device/service acknowledgement is required before commit returns? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.16 `recovery` + +Audit question: What bounds restart work after a clean stop and a crash? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.17 `writer_fencing` + +Audit question: Can a stale writer acknowledge after failover or lease expiry? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.18 `partitioning` + +Audit question: What key determines placement and what happens to cross-partition edges? + +Current assessment: Published distribution summary: single node and commercial/cloud scale-out offerings; open core must be separated from service claims. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.19 `rebalancing` + +Audit question: Can placement change online without changing logical identity? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.20 `replication` + +Audit question: Are replicas full, sharded, synchronous, asynchronous, or shared-storage readers? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.21 `optimizer` + +Audit question: Does the optimizer cost graph expansion, joins, network, cache, and remote requests? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.22 `statistics` + +Audit question: Which degree, correlation, path, and property statistics are persistent? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.23 `execution` + +Audit question: Is execution tuple-at-a-time, vectorized, factorized, compiled, matrix, or actor based? + +Current assessment: Expected family: algebraic traversal plus a modern columnar/batch execution path. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.24 `recursion` + +Audit question: How are BFS, shortest paths, trails, simple paths, and arbitrary reachability executed? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.25 `parallelism` + +Audit question: How does the engine avoid skew and nested parallelism under mixed queries? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.26 `memory` + +Audit question: Are all variable allocations charged to bounded query and system budgets? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.27 `spill` + +Audit question: Which operators spill, in what format, and with what admission controls? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.28 `cancellation` + +Audit question: Can cancellation stop CPU, local I/O, remote I/O, retries, and prefetch? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.29 `cache` + +Audit question: What is cached, how is it keyed, admitted, pinned, and evicted? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.30 `cold_start` + +Audit question: What metadata and data round trips are required with empty caches? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.31 `object_requests` + +Audit question: Can a query issue one remote request per node, edge, or result row? + +Current assessment: Published object-store posture: not an object-store-native live engine. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.32 `cost_admission` + +Audit question: Are request, byte, CPU, spill, and result limits enforced before work? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.33 `observability` + +Audit question: Can operators report rows, edges, bytes, requests, stalls, memory, and spill? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.34 `language` + +Audit question: Which GQL/Cypher/SQL-PGQ/Gremlin/SPARQL semantics are declared and tested? + +Current assessment: Declared surface: openCypher with extensions; Bolt and RESP access. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.35 `updates` + +Audit question: Are DDL, insert, merge, update, detach delete, and constraints complete? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.36 `bulk_load` + +Audit question: Does bulk load preserve transactional and index invariants? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.37 `backup` + +Audit question: Is backup consistent, incremental, immutable, and restore-tested? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.38 `gc` + +Audit question: How are old snapshots, orphan objects, tombstones, and indexes reclaimed safely? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.39 `security` + +Audit question: Are authentication, authorization, encryption, audit, and tenant isolation in scope? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.40 `operations` + +Audit question: What compaction, upgrade, repair, verification, and capacity procedures exist? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +## 5. Benchmark contract for this engine + +Every case runs correctness first, then isolated latency, then closed-loop concurrency, then open-loop overload. Report median, p95, p99, p99.9, timeout/rejection rate, throughput, CPU-seconds, peak RSS, cache bytes, disk bytes, network bytes, remote requests, write amplification, and estimated monthly cost. + +Warm means all intended engine caches are populated without changing the query parameters. Hot means the exact working set is resident. Cold means process-local, engine, OS, NVMe, and remote cache state are explicitly reset or a fresh namespace is used. Those words are never inferred from repetition count. + +### 5.1 `point_pk` — primary-key node lookup with one projected property + +- Applicability to FalkorDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.2 `point_edge` — stable edge-ID lookup including endpoints and one property + +- Applicability to FalkorDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.3 `degree_1` — degree-one outgoing expansion + +- Applicability to FalkorDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.4 `degree_32` — small adjacency expansion around degree 32 + +- Applicability to FalkorDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.5 `degree_1k` — medium adjacency expansion around degree 1,024 + +- Applicability to FalkorDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.6 `supernode` — range-limited expansion of a ten-million-degree supernode + +- Applicability to FalkorDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.7 `expand_2` — selective two-hop expansion + +- Applicability to FalkorDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.8 `expand_3` — three-hop frontier expansion with duplicate control + +- Applicability to FalkorDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.9 `expand_into` — edge-existence/expand-into between already-bound endpoints + +- Applicability to FalkorDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.10 `multi_edge` — parallel-edge identity and property projection + +- Applicability to FalkorDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.11 `shortest` — bidirectional point-to-point unweighted shortest path + +- Applicability to FalkorDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.12 `weighted` — weighted shortest path with property access + +- Applicability to FalkorDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.13 `var_walk` — bounded variable-length walk + +- Applicability to FalkorDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.14 `trail` — DIFFERENT EDGES trail enumeration + +- Applicability to FalkorDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.15 `simple` — simple-path enumeration with explicit bound + +- Applicability to FalkorDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.16 `triangle` — triangle pattern with worst-case-sensitive join + +- Applicability to FalkorDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.17 `cycle4` — four-cycle pattern + +- Applicability to FalkorDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.18 `star_join` — high-fanout star pattern with property filters + +- Applicability to FalkorDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.19 `optional` — optional match preserving null/bag semantics + +- Applicability to FalkorDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.20 `aggregate` — grouped aggregate after traversal + +- Applicability to FalkorDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.21 `topk` — ordered top-k with late property materialization + +- Applicability to FalkorDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.22 `scan` — full projected property scan + +- Applicability to FalkorDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.23 `selective_scan` — zone/index-pruned selective property scan + +- Applicability to FalkorDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.24 `mixed` — concurrent short reads, complex reads, and updates + +- Applicability to FalkorDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.25 `ingest` — sustained transactional ingest with indexes enabled + +- Applicability to FalkorDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.26 `bulk` — initial bulk load including index/CSR build + +- Applicability to FalkorDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.27 `checkpoint` — checkpoint or compaction while readers remain active + +- Applicability to FalkorDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.28 `recovery` — crash recovery at bounded dirty-log size + +- Applicability to FalkorDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.29 `cold` — same query after clearing engine and OS/cache tiers + +- Applicability to FalkorDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.30 `remote` — same query with authoritative bytes only in object storage + +- Applicability to FalkorDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +## 6. Fairness controls + +- Same logical dataset and update stream; engine-native physical layouts are allowed and disclosed. +- Same result semantics; unsupported queries remain unsupported rather than rewritten into easier questions. +- Same durable acknowledgement class for write comparisons. +- Same number of physical cores and memory limit for self-hosted single-node tests. +- Same aggregate resources and replication fault tolerance for distributed tests. +- Officially recommended tuning may be applied before the freeze and is committed with rationale. +- Query-specific hints are allowed only when equivalent hints are offered to every engine and separately charted. +- Load/build/index time and bytes are first-class results. +- Cold, warm, and hot results are separate charts. +- Managed services use public configurations and cannot borrow hidden same-machine resource claims. +- Failed runs, OOMs, correctness mismatches, and timeouts stay in the dataset. +- Every chart links raw samples and the exact reproduction command. + +## 7. Likely advantages and limits + +The strongest known reason to choose this engine is tied to its family `matrix property graph`, its execution path `algebraic traversal plus a modern columnar/batch execution path`, and its existing ecosystem. The strongest reason to reject it for zu's target is the gap between `not an object-store-native live engine` and an S3-authoritative, request-budgeted, PB-scale graph service. + +Capacity statement: excellent dense set-at-a-time traversal potential; PB evidence is not public. This is not converted into an edge-count claim without a physical byte model including IDs, both adjacency directions, properties, indexes, MVCC, WAL, replicas, and free space. + +Commercial statement: SSPLv1 in current official docs; commercial cloud terms separately. License cost, support cost, and unavailable enterprise capabilities remain visible in TCO and feature tables. + +## 8. Concrete lessons for zu + +1. Keep stable logical node and edge identity independent of row group, CSR slot, shard, and object range. +2. Store forward and reverse adjacency as immutable range-addressable tiles carrying edge IDs. +3. Feed queries adjacency batches and typed vectors; prohibit one storage call per logical element. +4. Use vectorized/factorized execution for property-heavy patterns and dedicated frontier operators for recursion. +5. Cost topology, properties, network, cache certainty, remote requests, and result materialization together. +6. Separate the local embedded profile from the object-authoritative distributed read profile. +7. Fence writers with monotonic epochs and make ambiguous commits reconcilable by transaction ID. +8. Pack small graph tiles into large immutable objects while retaining independent checksums and range offsets. +9. Keep the hot topology working set in RAM/NVMe; batch cold frontier misses into few remote rounds. +10. Admission-control remote requests and bytes so fixed-price plans have an enforceable upper bound. +11. Partition by workload-aware graph locality, and expose cross-partition semantics rather than hiding them. +12. Publish qualified wins per workload cell; never promise a universal tenfold advantage. + +## 9. Evidence gaps to close before publication + +- Exact current version and release date. +- Exact license text for the benchmarked artifact. +- Storage bytes per node/edge/property on all standard datasets. +- Stable-edge-ID and parallel-edge semantics. +- Isolation litmus results and commit acknowledgement point. +- Crash recovery time versus dirty WAL size. +- Supernode behavior and maximum tested degree. +- Cold-start metadata and request count. +- Distributed cross-partition query amplification. +- Peak memory under skew, cancellation, and overload. +- Background compaction/GC effect on tail latency. +- Full load/index/checkpoint/backup resource cost. +- Reproducible largest-scale result. +- Independent or audited benchmark evidence. + +## 10. Primary and official sources + +- [Official docs](https://docs.falkordb.com/) +- [Source repository](https://github.com/FalkorDB/FalkorDB) +- [GraphBLAS specification](https://graphblas.org/) +- [LDBC SNB Interactive and audited disclosures](https://ldbcouncil.org/benchmarks/snb/interactive/) +- [LDBC Graphalytics](https://ldbcouncil.org/benchmarks/graphalytics/) +- [SoK: The Faults in our Graph Benchmarks](https://arxiv.org/abs/2404.00766) + +## 11. Source-handling rules + +- Official documentation and source are evidence for implemented or declared behavior, not independent performance. +- A vendor benchmark is labeled vendor claim until the harness reproduces it. +- A peer-reviewed paper establishes only the version, configuration, and workload it evaluated. +- Search snippets, comparison sites, and unsourced blogs are discovery aids, not final evidence. +- Unknown is a valid result and creates a concrete experiment or source-inspection task. +- All web facts are rechecked at benchmark freeze because this corpus is current only through the research date. + +## 12. Reproduction record template + +- engine: `FalkorDB` +- version: `TBD at benchmark freeze` +- artifact digest: `TBD` +- source commit: `TBD or managed-service N/A` +- edition/license: `TBD` +- query language/version: `TBD` +- storage and durability mode: `TBD` +- cluster and replication: `TBD` +- CPU/RAM/NVMe/network: `TBD` +- OS/kernel/filesystem: `TBD` +- dataset URI and digest: `TBD` +- loader command and duration: `TBD` +- physical bytes by category: `TBD` +- tuning file: `TBD` +- query corpus commit: `TBD` +- raw result URI/digest: `TBD` +- profiler/trace URI: `TBD` +- correctness status: `TBD` +- reviewer and rerun date: `TBD` diff --git a/docs/research/engine-google_spanner_graph.md b/docs/research/engine-google_spanner_graph.md new file mode 100644 index 0000000..46abb23 --- /dev/null +++ b/docs/research/engine-google_spanner_graph.md @@ -0,0 +1,884 @@ +# Google Cloud Spanner Graph: 2026 deep technical and competitive specification + +Research cut: `2026-08-08` +Status: evidence-backed competitor audit; not a vendor endorsement +Family: `managed relational-property-graph database` +Evidence convention: **Observed/official**, **Vendor claim**, **Research inference**, **Unknown**, **Qualification target**. + +## 1. Decision summary + +Spanner Graph is the standards and managed-consistency baseline; zu's opening is cost, portability, and graph-native density. + +This document answers two questions: what this engine actually proves in 2026, and what zu must build or measure to earn a defensible advantage. A missing public detail remains unknown; it is never silently filled with a favorable assumption. + +### Snapshot card + +- Lifecycle: active Enterprise/Enterprise Plus feature; docs updated 2026-07-22. +- Data model: property graph mapped over Spanner tables. +- Query surface: ISO GQL-compatible interface plus SQL interoperability. +- Persistent layout: Spanner distributed relational storage with graph-optimized enhancements. +- Execution: distributed SQL/GQL planning and on-demand graph algorithms. +- Transactions: Spanner external consistency and transactions. +- Distribution: transparent sharding and managed scale-out. +- Object-storage posture: managed storage is not exposed as fixed-cost S3 object access. +- License/commercial boundary: proprietary managed service. +- Scale evidence: algorithms documented for tens of billions of edges; no public PB proof. +- Benchmark posture: compare query and algorithm compute separately; include Spanner edition and processing units. + +### Facts that materially affect comparison + +- F01 — Property graph schemas can map existing relational tables without migration. +- F02 — GQL and SQL can be selected per workload. +- F03 — Graph algorithms use dedicated on-demand compute with limited impact on transactions. +- F04 — Transparent sharding removes user placement control but not cross-shard communication cost. +- F05 — The graph feature requires paid Spanner editions. + +### Bottom-line fit against zu's target + +- Very-low latency: compare hot point and bounded traversal paths; never extrapolate from scans or algorithms. +- Very-low resources: charge resident set, page cache, remote cache, background services, and replicas. +- Distributed: distinguish read replication, partitioned capacity, distributed transactions, and elastic stateless compute. +- Fixed cost: no engine has fixed marginal cost by declaration; admission, batching, and capacity reservations create the bound. +- S3 authority: backups, imports, lake scans, and S3-native demand paging are four different architectures. +- PB / trillion-edge scale: require a capacity derivation plus a run at the largest affordable scale; marketing adjectives do not qualify. +- Tenfold win: can be a per-cell qualification result, never a universal statement across incomparable workloads. + +## 2. Product and ecosystem boundary + +The audited unit is **Google Cloud Spanner Graph** in the exact release, edition, deployment, and durability mode recorded by the harness. The family classification is **managed relational-property-graph database**. The current lifecycle statement is: active Enterprise/Enterprise Plus feature; docs updated 2026-07-22. + +The harness must record binary/container digest, source commit when available, build flags, plugins, license/edition, language mode, storage mode, cluster topology, replication factor, durability settings, cache sizes, thread counts, NUMA policy, kernel, filesystem, cloud region, and all environment variables that affect execution. + +A managed service is not placed in a same-hardware chart. It receives a service-level result with provisioned units, region, public price, and observed provider metrics. A historical engine remains useful for regression but cannot support a claim about beating all current competitors. + +## 3. Architecture reconstruction + +### 3.1 Logical model + +Google Cloud Spanner Graph exposes property graph mapped over Spanner tables. The conformance corpus must test nulls, missing properties, labels/types, direction, self-loops, parallel edges, element equality, path equality, bag semantics, ordering, numeric overflow, string collation, temporal values, and schema evolution. + +### 3.2 Language and compiler + +The public query surface is ISO GQL-compatible interface plus SQL interoperability. Syntax similarity is not semantic equivalence. Every supported construct needs a result oracle and an unsupported-feature declaration. + +### 3.3 Storage + +The best supported storage summary is: Spanner distributed relational storage with graph-optimized enhancements. This statement must be refined from code, format documentation, or provider counters before using it in a performance explanation. + +### 3.4 Execution + +The best supported execution summary is: distributed SQL/GQL planning and on-demand graph algorithms. The benchmark profiler must confirm which runtime and operators actually executed. + +### 3.5 Transactions and recovery + +The public contract is: Spanner external consistency and transactions. Exact acknowledgement, isolation anomalies, recovery bounds, and failover behavior remain separate qualification items. + +### 3.6 Distribution + +The deployment shape is: transparent sharding and managed scale-out. Replication is not capacity sharding; sharding is not distributed ACID; stateless readers are not stateless storage. + +### 3.7 Object storage and cost + +The 2026 posture is: managed storage is not exposed as fixed-cost S3 object access. The audit distinguishes authoritative live bytes, derived acceleration, backup, import/export, and spill. + +## 4. Forty-control deep audit + +### 4.1 `product_boundary` + +Audit question: What exact executable, edition, and storage mode is the system under test? + +Current assessment: Pin Google Cloud Spanner Graph, lifecycle `active Enterprise/Enterprise Plus feature; docs updated 2026-07-22`, and its edition/mode. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.2 `authority` + +Audit question: Which durable component is the source of truth after every acknowledged write? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.3 `identity` + +Audit question: Are node and edge identities stable across compaction, export, replication, and restore? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.4 `parallel_edges` + +Audit question: Can distinct parallel edges retain properties and trail identity end to end? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.5 `schema` + +Audit question: Is the schema open, closed, optional, inferred, or externally mapped? + +Current assessment: Start from `property graph mapped over Spanner tables` and test actual constraints. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.6 `labels` + +Audit question: How are multiple labels represented and indexed? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.7 `adjacency_out` + +Audit question: How is outgoing adjacency located, encoded, split, cached, and updated? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.8 `adjacency_in` + +Audit question: Is incoming adjacency first-class, derived, replicated, or a fan-out operation? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.9 `supernodes` + +Audit question: How are million-to-billion-degree vertices represented and scheduled? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.10 `properties` + +Audit question: Are properties co-located, columnar, row-oriented, document-encoded, or remote? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.11 `compression` + +Audit question: Which topology, integer, string, null, and floating encodings are implemented? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.12 `checksums` + +Audit question: What integrity unit is verified on point reads and range reads? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.13 `snapshot` + +Audit question: What exact token pins graph data, schema, statistics, and indexes? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.14 `isolation` + +Audit question: Which anomalies are forbidden at the documented isolation level? + +Current assessment: Published summary: Spanner external consistency and transactions. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.15 `durability` + +Audit question: What device/service acknowledgement is required before commit returns? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.16 `recovery` + +Audit question: What bounds restart work after a clean stop and a crash? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.17 `writer_fencing` + +Audit question: Can a stale writer acknowledge after failover or lease expiry? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.18 `partitioning` + +Audit question: What key determines placement and what happens to cross-partition edges? + +Current assessment: Published distribution summary: transparent sharding and managed scale-out. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.19 `rebalancing` + +Audit question: Can placement change online without changing logical identity? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.20 `replication` + +Audit question: Are replicas full, sharded, synchronous, asynchronous, or shared-storage readers? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.21 `optimizer` + +Audit question: Does the optimizer cost graph expansion, joins, network, cache, and remote requests? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.22 `statistics` + +Audit question: Which degree, correlation, path, and property statistics are persistent? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.23 `execution` + +Audit question: Is execution tuple-at-a-time, vectorized, factorized, compiled, matrix, or actor based? + +Current assessment: Expected family: distributed SQL/GQL planning and on-demand graph algorithms. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.24 `recursion` + +Audit question: How are BFS, shortest paths, trails, simple paths, and arbitrary reachability executed? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.25 `parallelism` + +Audit question: How does the engine avoid skew and nested parallelism under mixed queries? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.26 `memory` + +Audit question: Are all variable allocations charged to bounded query and system budgets? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.27 `spill` + +Audit question: Which operators spill, in what format, and with what admission controls? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.28 `cancellation` + +Audit question: Can cancellation stop CPU, local I/O, remote I/O, retries, and prefetch? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.29 `cache` + +Audit question: What is cached, how is it keyed, admitted, pinned, and evicted? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.30 `cold_start` + +Audit question: What metadata and data round trips are required with empty caches? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.31 `object_requests` + +Audit question: Can a query issue one remote request per node, edge, or result row? + +Current assessment: Published object-store posture: managed storage is not exposed as fixed-cost S3 object access. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.32 `cost_admission` + +Audit question: Are request, byte, CPU, spill, and result limits enforced before work? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.33 `observability` + +Audit question: Can operators report rows, edges, bytes, requests, stalls, memory, and spill? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.34 `language` + +Audit question: Which GQL/Cypher/SQL-PGQ/Gremlin/SPARQL semantics are declared and tested? + +Current assessment: Declared surface: ISO GQL-compatible interface plus SQL interoperability. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.35 `updates` + +Audit question: Are DDL, insert, merge, update, detach delete, and constraints complete? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.36 `bulk_load` + +Audit question: Does bulk load preserve transactional and index invariants? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.37 `backup` + +Audit question: Is backup consistent, incremental, immutable, and restore-tested? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.38 `gc` + +Audit question: How are old snapshots, orphan objects, tombstones, and indexes reclaimed safely? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.39 `security` + +Audit question: Are authentication, authorization, encryption, audit, and tenant isolation in scope? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.40 `operations` + +Audit question: What compaction, upgrade, repair, verification, and capacity procedures exist? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +## 5. Benchmark contract for this engine + +Every case runs correctness first, then isolated latency, then closed-loop concurrency, then open-loop overload. Report median, p95, p99, p99.9, timeout/rejection rate, throughput, CPU-seconds, peak RSS, cache bytes, disk bytes, network bytes, remote requests, write amplification, and estimated monthly cost. + +Warm means all intended engine caches are populated without changing the query parameters. Hot means the exact working set is resident. Cold means process-local, engine, OS, NVMe, and remote cache state are explicitly reset or a fresh namespace is used. Those words are never inferred from repetition count. + +### 5.1 `point_pk` — primary-key node lookup with one projected property + +- Applicability to Google Cloud Spanner Graph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.2 `point_edge` — stable edge-ID lookup including endpoints and one property + +- Applicability to Google Cloud Spanner Graph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.3 `degree_1` — degree-one outgoing expansion + +- Applicability to Google Cloud Spanner Graph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.4 `degree_32` — small adjacency expansion around degree 32 + +- Applicability to Google Cloud Spanner Graph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.5 `degree_1k` — medium adjacency expansion around degree 1,024 + +- Applicability to Google Cloud Spanner Graph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.6 `supernode` — range-limited expansion of a ten-million-degree supernode + +- Applicability to Google Cloud Spanner Graph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.7 `expand_2` — selective two-hop expansion + +- Applicability to Google Cloud Spanner Graph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.8 `expand_3` — three-hop frontier expansion with duplicate control + +- Applicability to Google Cloud Spanner Graph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.9 `expand_into` — edge-existence/expand-into between already-bound endpoints + +- Applicability to Google Cloud Spanner Graph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.10 `multi_edge` — parallel-edge identity and property projection + +- Applicability to Google Cloud Spanner Graph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.11 `shortest` — bidirectional point-to-point unweighted shortest path + +- Applicability to Google Cloud Spanner Graph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.12 `weighted` — weighted shortest path with property access + +- Applicability to Google Cloud Spanner Graph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.13 `var_walk` — bounded variable-length walk + +- Applicability to Google Cloud Spanner Graph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.14 `trail` — DIFFERENT EDGES trail enumeration + +- Applicability to Google Cloud Spanner Graph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.15 `simple` — simple-path enumeration with explicit bound + +- Applicability to Google Cloud Spanner Graph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.16 `triangle` — triangle pattern with worst-case-sensitive join + +- Applicability to Google Cloud Spanner Graph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.17 `cycle4` — four-cycle pattern + +- Applicability to Google Cloud Spanner Graph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.18 `star_join` — high-fanout star pattern with property filters + +- Applicability to Google Cloud Spanner Graph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.19 `optional` — optional match preserving null/bag semantics + +- Applicability to Google Cloud Spanner Graph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.20 `aggregate` — grouped aggregate after traversal + +- Applicability to Google Cloud Spanner Graph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.21 `topk` — ordered top-k with late property materialization + +- Applicability to Google Cloud Spanner Graph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.22 `scan` — full projected property scan + +- Applicability to Google Cloud Spanner Graph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.23 `selective_scan` — zone/index-pruned selective property scan + +- Applicability to Google Cloud Spanner Graph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.24 `mixed` — concurrent short reads, complex reads, and updates + +- Applicability to Google Cloud Spanner Graph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.25 `ingest` — sustained transactional ingest with indexes enabled + +- Applicability to Google Cloud Spanner Graph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.26 `bulk` — initial bulk load including index/CSR build + +- Applicability to Google Cloud Spanner Graph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.27 `checkpoint` — checkpoint or compaction while readers remain active + +- Applicability to Google Cloud Spanner Graph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.28 `recovery` — crash recovery at bounded dirty-log size + +- Applicability to Google Cloud Spanner Graph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.29 `cold` — same query after clearing engine and OS/cache tiers + +- Applicability to Google Cloud Spanner Graph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.30 `remote` — same query with authoritative bytes only in object storage + +- Applicability to Google Cloud Spanner Graph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +## 6. Fairness controls + +- Same logical dataset and update stream; engine-native physical layouts are allowed and disclosed. +- Same result semantics; unsupported queries remain unsupported rather than rewritten into easier questions. +- Same durable acknowledgement class for write comparisons. +- Same number of physical cores and memory limit for self-hosted single-node tests. +- Same aggregate resources and replication fault tolerance for distributed tests. +- Officially recommended tuning may be applied before the freeze and is committed with rationale. +- Query-specific hints are allowed only when equivalent hints are offered to every engine and separately charted. +- Load/build/index time and bytes are first-class results. +- Cold, warm, and hot results are separate charts. +- Managed services use public configurations and cannot borrow hidden same-machine resource claims. +- Failed runs, OOMs, correctness mismatches, and timeouts stay in the dataset. +- Every chart links raw samples and the exact reproduction command. + +## 7. Likely advantages and limits + +The strongest known reason to choose this engine is tied to its family `managed relational-property-graph database`, its execution path `distributed SQL/GQL planning and on-demand graph algorithms`, and its existing ecosystem. The strongest reason to reject it for zu's target is the gap between `managed storage is not exposed as fixed-cost S3 object access` and an S3-authoritative, request-budgeted, PB-scale graph service. + +Capacity statement: algorithms documented for tens of billions of edges; no public PB proof. This is not converted into an edge-count claim without a physical byte model including IDs, both adjacency directions, properties, indexes, MVCC, WAL, replicas, and free space. + +Commercial statement: proprietary managed service. License cost, support cost, and unavailable enterprise capabilities remain visible in TCO and feature tables. + +## 8. Concrete lessons for zu + +1. Keep stable logical node and edge identity independent of row group, CSR slot, shard, and object range. +2. Store forward and reverse adjacency as immutable range-addressable tiles carrying edge IDs. +3. Feed queries adjacency batches and typed vectors; prohibit one storage call per logical element. +4. Use vectorized/factorized execution for property-heavy patterns and dedicated frontier operators for recursion. +5. Cost topology, properties, network, cache certainty, remote requests, and result materialization together. +6. Separate the local embedded profile from the object-authoritative distributed read profile. +7. Fence writers with monotonic epochs and make ambiguous commits reconcilable by transaction ID. +8. Pack small graph tiles into large immutable objects while retaining independent checksums and range offsets. +9. Keep the hot topology working set in RAM/NVMe; batch cold frontier misses into few remote rounds. +10. Admission-control remote requests and bytes so fixed-price plans have an enforceable upper bound. +11. Partition by workload-aware graph locality, and expose cross-partition semantics rather than hiding them. +12. Publish qualified wins per workload cell; never promise a universal tenfold advantage. + +## 9. Evidence gaps to close before publication + +- Exact current version and release date. +- Exact license text for the benchmarked artifact. +- Storage bytes per node/edge/property on all standard datasets. +- Stable-edge-ID and parallel-edge semantics. +- Isolation litmus results and commit acknowledgement point. +- Crash recovery time versus dirty WAL size. +- Supernode behavior and maximum tested degree. +- Cold-start metadata and request count. +- Distributed cross-partition query amplification. +- Peak memory under skew, cancellation, and overload. +- Background compaction/GC effect on tail latency. +- Full load/index/checkpoint/backup resource cost. +- Reproducible largest-scale result. +- Independent or audited benchmark evidence. + +## 10. Primary and official sources + +- [2026 overview](https://docs.cloud.google.com/spanner/docs/graph/overview) +- [Graph schema](https://cloud.google.com/spanner/docs/graph/schema-overview) +- [LDBC SNB Interactive and audited disclosures](https://ldbcouncil.org/benchmarks/snb/interactive/) +- [LDBC Graphalytics](https://ldbcouncil.org/benchmarks/graphalytics/) +- [SoK: The Faults in our Graph Benchmarks](https://arxiv.org/abs/2404.00766) + +## 11. Source-handling rules + +- Official documentation and source are evidence for implemented or declared behavior, not independent performance. +- A vendor benchmark is labeled vendor claim until the harness reproduces it. +- A peer-reviewed paper establishes only the version, configuration, and workload it evaluated. +- Search snippets, comparison sites, and unsourced blogs are discovery aids, not final evidence. +- Unknown is a valid result and creates a concrete experiment or source-inspection task. +- All web facts are rechecked at benchmark freeze because this corpus is current only through the research date. + +## 12. Reproduction record template + +- engine: `Google Cloud Spanner Graph` +- version: `TBD at benchmark freeze` +- artifact digest: `TBD` +- source commit: `TBD or managed-service N/A` +- edition/license: `TBD` +- query language/version: `TBD` +- storage and durability mode: `TBD` +- cluster and replication: `TBD` +- CPU/RAM/NVMe/network: `TBD` +- OS/kernel/filesystem: `TBD` +- dataset URI and digest: `TBD` +- loader command and duration: `TBD` +- physical bytes by category: `TBD` +- tuning file: `TBD` +- query corpus commit: `TBD` +- raw result URI/digest: `TBD` +- profiler/trace URI: `TBD` +- correctness status: `TBD` +- reviewer and rerun date: `TBD` diff --git a/docs/research/engine-graphscope_flex.md b/docs/research/engine-graphscope_flex.md new file mode 100644 index 0000000..9acbd21 --- /dev/null +++ b/docs/research/engine-graphscope_flex.md @@ -0,0 +1,886 @@ +# GraphScope Flex Interactive: 2026 deep technical and competitive specification + +Research cut: `2026-08-08` +Status: evidence-backed competitor audit; not a vendor endorsement +Family: `distributed interactive graph system` +Evidence convention: **Observed/official**, **Vendor claim**, **Research inference**, **Unknown**, **Qualification target**. + +## 1. Decision summary + +GraphScope is the strongest public audited throughput comparator and must not be reduced to a laptop microbenchmark. + +This document answers two questions: what this engine actually proves in 2026, and what zu must build or measure to earn a defensible advantage. A missing public detail remains unknown; it is never silently filled with a favorable assumption. + +### Snapshot card + +- Lifecycle: active Apache-2.0 project. +- Data model: property graph. +- Query surface: openCypher, Gremlin, compiled stored procedures. +- Persistent layout: immutable and real-time mutable CSR storage components. +- Execution: Seastar/hiactor share-nothing-per-core runtime, GAIA IR compiler, C++ code generation. +- Transactions: read/update/insert transaction types; exact isolation must be verified. +- Distribution: distributed service with per-core shards and scale-out deployment. +- Object-storage posture: not object-store-native for interactive serving; GraphAr/lake integration is adjacent. +- License/commercial boundary: Apache-2.0. +- Scale evidence: audited LDBC SNB at SF1000 and hundreds of billions of edges. +- Benchmark posture: audited LDBC results are the throughput credibility bar. + +### Facts that materially affect comparison + +- F01 — The runtime uses Seastar's share-nothing SMP model. +- F02 — Storage source includes immutable_graph and rt_mutable_graph based on mutable CSR. +- F03 — The compiler maps Cypher/Gremlin through a common IR to runtimes. +- F04 — Stored procedures can be generated as C++ for predictable low overhead. +- F05 — LDBC FDRs report system cost and are more credible than isolated vendor charts. + +### Bottom-line fit against zu's target + +- Very-low latency: compare hot point and bounded traversal paths; never extrapolate from scans or algorithms. +- Very-low resources: charge resident set, page cache, remote cache, background services, and replicas. +- Distributed: distinguish read replication, partitioned capacity, distributed transactions, and elastic stateless compute. +- Fixed cost: no engine has fixed marginal cost by declaration; admission, batching, and capacity reservations create the bound. +- S3 authority: backups, imports, lake scans, and S3-native demand paging are four different architectures. +- PB / trillion-edge scale: require a capacity derivation plus a run at the largest affordable scale; marketing adjectives do not qualify. +- Tenfold win: can be a per-cell qualification result, never a universal statement across incomparable workloads. + +## 2. Product and ecosystem boundary + +The audited unit is **GraphScope Flex Interactive** in the exact release, edition, deployment, and durability mode recorded by the harness. The family classification is **distributed interactive graph system**. The current lifecycle statement is: active Apache-2.0 project. + +The harness must record binary/container digest, source commit when available, build flags, plugins, license/edition, language mode, storage mode, cluster topology, replication factor, durability settings, cache sizes, thread counts, NUMA policy, kernel, filesystem, cloud region, and all environment variables that affect execution. + +A managed service is not placed in a same-hardware chart. It receives a service-level result with provisioned units, region, public price, and observed provider metrics. A historical engine remains useful for regression but cannot support a claim about beating all current competitors. + +## 3. Architecture reconstruction + +### 3.1 Logical model + +GraphScope Flex Interactive exposes property graph. The conformance corpus must test nulls, missing properties, labels/types, direction, self-loops, parallel edges, element equality, path equality, bag semantics, ordering, numeric overflow, string collation, temporal values, and schema evolution. + +### 3.2 Language and compiler + +The public query surface is openCypher, Gremlin, compiled stored procedures. Syntax similarity is not semantic equivalence. Every supported construct needs a result oracle and an unsupported-feature declaration. + +### 3.3 Storage + +The best supported storage summary is: immutable and real-time mutable CSR storage components. This statement must be refined from code, format documentation, or provider counters before using it in a performance explanation. + +### 3.4 Execution + +The best supported execution summary is: Seastar/hiactor share-nothing-per-core runtime, GAIA IR compiler, C++ code generation. The benchmark profiler must confirm which runtime and operators actually executed. + +### 3.5 Transactions and recovery + +The public contract is: read/update/insert transaction types; exact isolation must be verified. Exact acknowledgement, isolation anomalies, recovery bounds, and failover behavior remain separate qualification items. + +### 3.6 Distribution + +The deployment shape is: distributed service with per-core shards and scale-out deployment. Replication is not capacity sharding; sharding is not distributed ACID; stateless readers are not stateless storage. + +### 3.7 Object storage and cost + +The 2026 posture is: not object-store-native for interactive serving; GraphAr/lake integration is adjacent. The audit distinguishes authoritative live bytes, derived acceleration, backup, import/export, and spill. + +## 4. Forty-control deep audit + +### 4.1 `product_boundary` + +Audit question: What exact executable, edition, and storage mode is the system under test? + +Current assessment: Pin GraphScope Flex Interactive, lifecycle `active Apache-2.0 project`, and its edition/mode. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.2 `authority` + +Audit question: Which durable component is the source of truth after every acknowledged write? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.3 `identity` + +Audit question: Are node and edge identities stable across compaction, export, replication, and restore? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.4 `parallel_edges` + +Audit question: Can distinct parallel edges retain properties and trail identity end to end? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.5 `schema` + +Audit question: Is the schema open, closed, optional, inferred, or externally mapped? + +Current assessment: Start from `property graph` and test actual constraints. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.6 `labels` + +Audit question: How are multiple labels represented and indexed? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.7 `adjacency_out` + +Audit question: How is outgoing adjacency located, encoded, split, cached, and updated? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.8 `adjacency_in` + +Audit question: Is incoming adjacency first-class, derived, replicated, or a fan-out operation? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.9 `supernodes` + +Audit question: How are million-to-billion-degree vertices represented and scheduled? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.10 `properties` + +Audit question: Are properties co-located, columnar, row-oriented, document-encoded, or remote? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.11 `compression` + +Audit question: Which topology, integer, string, null, and floating encodings are implemented? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.12 `checksums` + +Audit question: What integrity unit is verified on point reads and range reads? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.13 `snapshot` + +Audit question: What exact token pins graph data, schema, statistics, and indexes? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.14 `isolation` + +Audit question: Which anomalies are forbidden at the documented isolation level? + +Current assessment: Published summary: read/update/insert transaction types; exact isolation must be verified. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.15 `durability` + +Audit question: What device/service acknowledgement is required before commit returns? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.16 `recovery` + +Audit question: What bounds restart work after a clean stop and a crash? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.17 `writer_fencing` + +Audit question: Can a stale writer acknowledge after failover or lease expiry? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.18 `partitioning` + +Audit question: What key determines placement and what happens to cross-partition edges? + +Current assessment: Published distribution summary: distributed service with per-core shards and scale-out deployment. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.19 `rebalancing` + +Audit question: Can placement change online without changing logical identity? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.20 `replication` + +Audit question: Are replicas full, sharded, synchronous, asynchronous, or shared-storage readers? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.21 `optimizer` + +Audit question: Does the optimizer cost graph expansion, joins, network, cache, and remote requests? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.22 `statistics` + +Audit question: Which degree, correlation, path, and property statistics are persistent? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.23 `execution` + +Audit question: Is execution tuple-at-a-time, vectorized, factorized, compiled, matrix, or actor based? + +Current assessment: Expected family: Seastar/hiactor share-nothing-per-core runtime, GAIA IR compiler, C++ code generation. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.24 `recursion` + +Audit question: How are BFS, shortest paths, trails, simple paths, and arbitrary reachability executed? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.25 `parallelism` + +Audit question: How does the engine avoid skew and nested parallelism under mixed queries? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.26 `memory` + +Audit question: Are all variable allocations charged to bounded query and system budgets? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.27 `spill` + +Audit question: Which operators spill, in what format, and with what admission controls? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.28 `cancellation` + +Audit question: Can cancellation stop CPU, local I/O, remote I/O, retries, and prefetch? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.29 `cache` + +Audit question: What is cached, how is it keyed, admitted, pinned, and evicted? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.30 `cold_start` + +Audit question: What metadata and data round trips are required with empty caches? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.31 `object_requests` + +Audit question: Can a query issue one remote request per node, edge, or result row? + +Current assessment: Published object-store posture: not object-store-native for interactive serving; GraphAr/lake integration is adjacent. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.32 `cost_admission` + +Audit question: Are request, byte, CPU, spill, and result limits enforced before work? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.33 `observability` + +Audit question: Can operators report rows, edges, bytes, requests, stalls, memory, and spill? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.34 `language` + +Audit question: Which GQL/Cypher/SQL-PGQ/Gremlin/SPARQL semantics are declared and tested? + +Current assessment: Declared surface: openCypher, Gremlin, compiled stored procedures. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.35 `updates` + +Audit question: Are DDL, insert, merge, update, detach delete, and constraints complete? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.36 `bulk_load` + +Audit question: Does bulk load preserve transactional and index invariants? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.37 `backup` + +Audit question: Is backup consistent, incremental, immutable, and restore-tested? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.38 `gc` + +Audit question: How are old snapshots, orphan objects, tombstones, and indexes reclaimed safely? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.39 `security` + +Audit question: Are authentication, authorization, encryption, audit, and tenant isolation in scope? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.40 `operations` + +Audit question: What compaction, upgrade, repair, verification, and capacity procedures exist? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +## 5. Benchmark contract for this engine + +Every case runs correctness first, then isolated latency, then closed-loop concurrency, then open-loop overload. Report median, p95, p99, p99.9, timeout/rejection rate, throughput, CPU-seconds, peak RSS, cache bytes, disk bytes, network bytes, remote requests, write amplification, and estimated monthly cost. + +Warm means all intended engine caches are populated without changing the query parameters. Hot means the exact working set is resident. Cold means process-local, engine, OS, NVMe, and remote cache state are explicitly reset or a fresh namespace is used. Those words are never inferred from repetition count. + +### 5.1 `point_pk` — primary-key node lookup with one projected property + +- Applicability to GraphScope Flex Interactive: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.2 `point_edge` — stable edge-ID lookup including endpoints and one property + +- Applicability to GraphScope Flex Interactive: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.3 `degree_1` — degree-one outgoing expansion + +- Applicability to GraphScope Flex Interactive: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.4 `degree_32` — small adjacency expansion around degree 32 + +- Applicability to GraphScope Flex Interactive: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.5 `degree_1k` — medium adjacency expansion around degree 1,024 + +- Applicability to GraphScope Flex Interactive: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.6 `supernode` — range-limited expansion of a ten-million-degree supernode + +- Applicability to GraphScope Flex Interactive: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.7 `expand_2` — selective two-hop expansion + +- Applicability to GraphScope Flex Interactive: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.8 `expand_3` — three-hop frontier expansion with duplicate control + +- Applicability to GraphScope Flex Interactive: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.9 `expand_into` — edge-existence/expand-into between already-bound endpoints + +- Applicability to GraphScope Flex Interactive: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.10 `multi_edge` — parallel-edge identity and property projection + +- Applicability to GraphScope Flex Interactive: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.11 `shortest` — bidirectional point-to-point unweighted shortest path + +- Applicability to GraphScope Flex Interactive: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.12 `weighted` — weighted shortest path with property access + +- Applicability to GraphScope Flex Interactive: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.13 `var_walk` — bounded variable-length walk + +- Applicability to GraphScope Flex Interactive: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.14 `trail` — DIFFERENT EDGES trail enumeration + +- Applicability to GraphScope Flex Interactive: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.15 `simple` — simple-path enumeration with explicit bound + +- Applicability to GraphScope Flex Interactive: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.16 `triangle` — triangle pattern with worst-case-sensitive join + +- Applicability to GraphScope Flex Interactive: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.17 `cycle4` — four-cycle pattern + +- Applicability to GraphScope Flex Interactive: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.18 `star_join` — high-fanout star pattern with property filters + +- Applicability to GraphScope Flex Interactive: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.19 `optional` — optional match preserving null/bag semantics + +- Applicability to GraphScope Flex Interactive: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.20 `aggregate` — grouped aggregate after traversal + +- Applicability to GraphScope Flex Interactive: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.21 `topk` — ordered top-k with late property materialization + +- Applicability to GraphScope Flex Interactive: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.22 `scan` — full projected property scan + +- Applicability to GraphScope Flex Interactive: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.23 `selective_scan` — zone/index-pruned selective property scan + +- Applicability to GraphScope Flex Interactive: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.24 `mixed` — concurrent short reads, complex reads, and updates + +- Applicability to GraphScope Flex Interactive: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.25 `ingest` — sustained transactional ingest with indexes enabled + +- Applicability to GraphScope Flex Interactive: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.26 `bulk` — initial bulk load including index/CSR build + +- Applicability to GraphScope Flex Interactive: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.27 `checkpoint` — checkpoint or compaction while readers remain active + +- Applicability to GraphScope Flex Interactive: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.28 `recovery` — crash recovery at bounded dirty-log size + +- Applicability to GraphScope Flex Interactive: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.29 `cold` — same query after clearing engine and OS/cache tiers + +- Applicability to GraphScope Flex Interactive: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.30 `remote` — same query with authoritative bytes only in object storage + +- Applicability to GraphScope Flex Interactive: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +## 6. Fairness controls + +- Same logical dataset and update stream; engine-native physical layouts are allowed and disclosed. +- Same result semantics; unsupported queries remain unsupported rather than rewritten into easier questions. +- Same durable acknowledgement class for write comparisons. +- Same number of physical cores and memory limit for self-hosted single-node tests. +- Same aggregate resources and replication fault tolerance for distributed tests. +- Officially recommended tuning may be applied before the freeze and is committed with rationale. +- Query-specific hints are allowed only when equivalent hints are offered to every engine and separately charted. +- Load/build/index time and bytes are first-class results. +- Cold, warm, and hot results are separate charts. +- Managed services use public configurations and cannot borrow hidden same-machine resource claims. +- Failed runs, OOMs, correctness mismatches, and timeouts stay in the dataset. +- Every chart links raw samples and the exact reproduction command. + +## 7. Likely advantages and limits + +The strongest known reason to choose this engine is tied to its family `distributed interactive graph system`, its execution path `Seastar/hiactor share-nothing-per-core runtime, GAIA IR compiler, C++ code generation`, and its existing ecosystem. The strongest reason to reject it for zu's target is the gap between `not object-store-native for interactive serving; GraphAr/lake integration is adjacent` and an S3-authoritative, request-budgeted, PB-scale graph service. + +Capacity statement: audited LDBC SNB at SF1000 and hundreds of billions of edges. This is not converted into an edge-count claim without a physical byte model including IDs, both adjacency directions, properties, indexes, MVCC, WAL, replicas, and free space. + +Commercial statement: Apache-2.0. License cost, support cost, and unavailable enterprise capabilities remain visible in TCO and feature tables. + +## 8. Concrete lessons for zu + +1. Keep stable logical node and edge identity independent of row group, CSR slot, shard, and object range. +2. Store forward and reverse adjacency as immutable range-addressable tiles carrying edge IDs. +3. Feed queries adjacency batches and typed vectors; prohibit one storage call per logical element. +4. Use vectorized/factorized execution for property-heavy patterns and dedicated frontier operators for recursion. +5. Cost topology, properties, network, cache certainty, remote requests, and result materialization together. +6. Separate the local embedded profile from the object-authoritative distributed read profile. +7. Fence writers with monotonic epochs and make ambiguous commits reconcilable by transaction ID. +8. Pack small graph tiles into large immutable objects while retaining independent checksums and range offsets. +9. Keep the hot topology working set in RAM/NVMe; batch cold frontier misses into few remote rounds. +10. Admission-control remote requests and bytes so fixed-price plans have an enforceable upper bound. +11. Partition by workload-aware graph locality, and expose cross-partition semantics rather than hiding them. +12. Publish qualified wins per workload cell; never promise a universal tenfold advantage. + +## 9. Evidence gaps to close before publication + +- Exact current version and release date. +- Exact license text for the benchmarked artifact. +- Storage bytes per node/edge/property on all standard datasets. +- Stable-edge-ID and parallel-edge semantics. +- Isolation litmus results and commit acknowledgement point. +- Crash recovery time versus dirty WAL size. +- Supernode behavior and maximum tested degree. +- Cold-start metadata and request count. +- Distributed cross-partition query amplification. +- Peak memory under skew, cancellation, and overload. +- Background compaction/GC effect on tail latency. +- Full load/index/checkpoint/backup resource cost. +- Reproducible largest-scale result. +- Independent or audited benchmark evidence. + +## 10. Primary and official sources + +- [Interactive introduction](https://graphscope.io/docs/latest/flex/interactive_intro) +- [Implementation layout](https://graphscope.io/docs/flex/interactive/development/dev_and_test) +- [LDBC audited results](https://ldbcouncil.org/benchmarks/snb/interactive/) +- [Source repository](https://github.com/alibaba/GraphScope) +- [LDBC SNB Interactive and audited disclosures](https://ldbcouncil.org/benchmarks/snb/interactive/) +- [LDBC Graphalytics](https://ldbcouncil.org/benchmarks/graphalytics/) +- [SoK: The Faults in our Graph Benchmarks](https://arxiv.org/abs/2404.00766) + +## 11. Source-handling rules + +- Official documentation and source are evidence for implemented or declared behavior, not independent performance. +- A vendor benchmark is labeled vendor claim until the harness reproduces it. +- A peer-reviewed paper establishes only the version, configuration, and workload it evaluated. +- Search snippets, comparison sites, and unsourced blogs are discovery aids, not final evidence. +- Unknown is a valid result and creates a concrete experiment or source-inspection task. +- All web facts are rechecked at benchmark freeze because this corpus is current only through the research date. + +## 12. Reproduction record template + +- engine: `GraphScope Flex Interactive` +- version: `TBD at benchmark freeze` +- artifact digest: `TBD` +- source commit: `TBD or managed-service N/A` +- edition/license: `TBD` +- query language/version: `TBD` +- storage and durability mode: `TBD` +- cluster and replication: `TBD` +- CPU/RAM/NVMe/network: `TBD` +- OS/kernel/filesystem: `TBD` +- dataset URI and digest: `TBD` +- loader command and duration: `TBD` +- physical bytes by category: `TBD` +- tuning file: `TBD` +- query corpus commit: `TBD` +- raw result URI/digest: `TBD` +- profiler/trace URI: `TBD` +- correctness status: `TBD` +- reviewer and rerun date: `TBD` diff --git a/docs/research/engine-helixdb.md b/docs/research/engine-helixdb.md new file mode 100644 index 0000000..58192a8 --- /dev/null +++ b/docs/research/engine-helixdb.md @@ -0,0 +1,886 @@ +# HelixDB: 2026 deep technical and competitive specification + +Research cut: `2026-08-08` +Status: evidence-backed competitor audit; not a vendor endorsement +Family: `Rust graph-vector database` +Evidence convention: **Observed/official**, **Vendor claim**, **Research inference**, **Unknown**, **Qualification target**. + +## 1. Decision summary + +HelixDB is an emerging direct Rust/object-storage/GraphRAG competitor, but unknowns must be treated as unknowns. + +This document answers two questions: what this engine actually proves in 2026, and what zu must build or measure to earn a defensible advantage. A missing public detail remains unknown; it is never silently filled with a favorable assumption. + +### Snapshot card + +- Lifecycle: active and fast-moving; 3.0.2 listed in May 2026. +- Data model: graph plus vector with KV/document/relational ambitions. +- Query surface: dynamic JSON query API and generated/type-safe SDK DSL. +- Persistent layout: LMDB in public repository descriptions; cloud site now describes object-storage architecture. +- Execution: Rust native stored/dynamic query execution combining traversal, vector, and search. +- Transactions: transaction semantics are insufficiently documented for strong comparison. +- Distribution: local server and commercial cloud; public distributed mechanics are incomplete. +- Object-storage posture: current marketing says built on object storage, making it directly relevant, but technical evidence is sparse. +- License/commercial boundary: license signals conflict between repository API metadata and README wording; verify the exact revision. +- Scale evidence: early-stage; no credible PB proof. +- Benchmark posture: reproduce vendor claims and include compile/deploy, dynamic query, and durability behavior. + +### Facts that materially affect comparison + +- F01 — The public engine is written in Rust and historically used LMDB. +- F02 — The v2 API can submit dynamic JSON query plans and also supports compiled stored queries. +- F03 — Graph and vector operations are intended to compose in one request. +- F04 — Official current pages advertise object-storage-backed cloud operation without enough persistence protocol detail. +- F05 — License and version documentation changed quickly in 2026 and must be captured by commit digest. + +### Bottom-line fit against zu's target + +- Very-low latency: compare hot point and bounded traversal paths; never extrapolate from scans or algorithms. +- Very-low resources: charge resident set, page cache, remote cache, background services, and replicas. +- Distributed: distinguish read replication, partitioned capacity, distributed transactions, and elastic stateless compute. +- Fixed cost: no engine has fixed marginal cost by declaration; admission, batching, and capacity reservations create the bound. +- S3 authority: backups, imports, lake scans, and S3-native demand paging are four different architectures. +- PB / trillion-edge scale: require a capacity derivation plus a run at the largest affordable scale; marketing adjectives do not qualify. +- Tenfold win: can be a per-cell qualification result, never a universal statement across incomparable workloads. + +## 2. Product and ecosystem boundary + +The audited unit is **HelixDB** in the exact release, edition, deployment, and durability mode recorded by the harness. The family classification is **Rust graph-vector database**. The current lifecycle statement is: active and fast-moving; 3.0.2 listed in May 2026. + +The harness must record binary/container digest, source commit when available, build flags, plugins, license/edition, language mode, storage mode, cluster topology, replication factor, durability settings, cache sizes, thread counts, NUMA policy, kernel, filesystem, cloud region, and all environment variables that affect execution. + +A managed service is not placed in a same-hardware chart. It receives a service-level result with provisioned units, region, public price, and observed provider metrics. A historical engine remains useful for regression but cannot support a claim about beating all current competitors. + +## 3. Architecture reconstruction + +### 3.1 Logical model + +HelixDB exposes graph plus vector with KV/document/relational ambitions. The conformance corpus must test nulls, missing properties, labels/types, direction, self-loops, parallel edges, element equality, path equality, bag semantics, ordering, numeric overflow, string collation, temporal values, and schema evolution. + +### 3.2 Language and compiler + +The public query surface is dynamic JSON query API and generated/type-safe SDK DSL. Syntax similarity is not semantic equivalence. Every supported construct needs a result oracle and an unsupported-feature declaration. + +### 3.3 Storage + +The best supported storage summary is: LMDB in public repository descriptions; cloud site now describes object-storage architecture. This statement must be refined from code, format documentation, or provider counters before using it in a performance explanation. + +### 3.4 Execution + +The best supported execution summary is: Rust native stored/dynamic query execution combining traversal, vector, and search. The benchmark profiler must confirm which runtime and operators actually executed. + +### 3.5 Transactions and recovery + +The public contract is: transaction semantics are insufficiently documented for strong comparison. Exact acknowledgement, isolation anomalies, recovery bounds, and failover behavior remain separate qualification items. + +### 3.6 Distribution + +The deployment shape is: local server and commercial cloud; public distributed mechanics are incomplete. Replication is not capacity sharding; sharding is not distributed ACID; stateless readers are not stateless storage. + +### 3.7 Object storage and cost + +The 2026 posture is: current marketing says built on object storage, making it directly relevant, but technical evidence is sparse. The audit distinguishes authoritative live bytes, derived acceleration, backup, import/export, and spill. + +## 4. Forty-control deep audit + +### 4.1 `product_boundary` + +Audit question: What exact executable, edition, and storage mode is the system under test? + +Current assessment: Pin HelixDB, lifecycle `active and fast-moving; 3.0.2 listed in May 2026`, and its edition/mode. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.2 `authority` + +Audit question: Which durable component is the source of truth after every acknowledged write? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.3 `identity` + +Audit question: Are node and edge identities stable across compaction, export, replication, and restore? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.4 `parallel_edges` + +Audit question: Can distinct parallel edges retain properties and trail identity end to end? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.5 `schema` + +Audit question: Is the schema open, closed, optional, inferred, or externally mapped? + +Current assessment: Start from `graph plus vector with KV/document/relational ambitions` and test actual constraints. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.6 `labels` + +Audit question: How are multiple labels represented and indexed? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.7 `adjacency_out` + +Audit question: How is outgoing adjacency located, encoded, split, cached, and updated? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.8 `adjacency_in` + +Audit question: Is incoming adjacency first-class, derived, replicated, or a fan-out operation? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.9 `supernodes` + +Audit question: How are million-to-billion-degree vertices represented and scheduled? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.10 `properties` + +Audit question: Are properties co-located, columnar, row-oriented, document-encoded, or remote? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.11 `compression` + +Audit question: Which topology, integer, string, null, and floating encodings are implemented? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.12 `checksums` + +Audit question: What integrity unit is verified on point reads and range reads? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.13 `snapshot` + +Audit question: What exact token pins graph data, schema, statistics, and indexes? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.14 `isolation` + +Audit question: Which anomalies are forbidden at the documented isolation level? + +Current assessment: Published summary: transaction semantics are insufficiently documented for strong comparison. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.15 `durability` + +Audit question: What device/service acknowledgement is required before commit returns? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.16 `recovery` + +Audit question: What bounds restart work after a clean stop and a crash? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.17 `writer_fencing` + +Audit question: Can a stale writer acknowledge after failover or lease expiry? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.18 `partitioning` + +Audit question: What key determines placement and what happens to cross-partition edges? + +Current assessment: Published distribution summary: local server and commercial cloud; public distributed mechanics are incomplete. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.19 `rebalancing` + +Audit question: Can placement change online without changing logical identity? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.20 `replication` + +Audit question: Are replicas full, sharded, synchronous, asynchronous, or shared-storage readers? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.21 `optimizer` + +Audit question: Does the optimizer cost graph expansion, joins, network, cache, and remote requests? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.22 `statistics` + +Audit question: Which degree, correlation, path, and property statistics are persistent? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.23 `execution` + +Audit question: Is execution tuple-at-a-time, vectorized, factorized, compiled, matrix, or actor based? + +Current assessment: Expected family: Rust native stored/dynamic query execution combining traversal, vector, and search. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.24 `recursion` + +Audit question: How are BFS, shortest paths, trails, simple paths, and arbitrary reachability executed? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.25 `parallelism` + +Audit question: How does the engine avoid skew and nested parallelism under mixed queries? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.26 `memory` + +Audit question: Are all variable allocations charged to bounded query and system budgets? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.27 `spill` + +Audit question: Which operators spill, in what format, and with what admission controls? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.28 `cancellation` + +Audit question: Can cancellation stop CPU, local I/O, remote I/O, retries, and prefetch? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.29 `cache` + +Audit question: What is cached, how is it keyed, admitted, pinned, and evicted? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.30 `cold_start` + +Audit question: What metadata and data round trips are required with empty caches? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.31 `object_requests` + +Audit question: Can a query issue one remote request per node, edge, or result row? + +Current assessment: Published object-store posture: current marketing says built on object storage, making it directly relevant, but technical evidence is sparse. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.32 `cost_admission` + +Audit question: Are request, byte, CPU, spill, and result limits enforced before work? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.33 `observability` + +Audit question: Can operators report rows, edges, bytes, requests, stalls, memory, and spill? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.34 `language` + +Audit question: Which GQL/Cypher/SQL-PGQ/Gremlin/SPARQL semantics are declared and tested? + +Current assessment: Declared surface: dynamic JSON query API and generated/type-safe SDK DSL. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.35 `updates` + +Audit question: Are DDL, insert, merge, update, detach delete, and constraints complete? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.36 `bulk_load` + +Audit question: Does bulk load preserve transactional and index invariants? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.37 `backup` + +Audit question: Is backup consistent, incremental, immutable, and restore-tested? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.38 `gc` + +Audit question: How are old snapshots, orphan objects, tombstones, and indexes reclaimed safely? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.39 `security` + +Audit question: Are authentication, authorization, encryption, audit, and tenant isolation in scope? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.40 `operations` + +Audit question: What compaction, upgrade, repair, verification, and capacity procedures exist? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +## 5. Benchmark contract for this engine + +Every case runs correctness first, then isolated latency, then closed-loop concurrency, then open-loop overload. Report median, p95, p99, p99.9, timeout/rejection rate, throughput, CPU-seconds, peak RSS, cache bytes, disk bytes, network bytes, remote requests, write amplification, and estimated monthly cost. + +Warm means all intended engine caches are populated without changing the query parameters. Hot means the exact working set is resident. Cold means process-local, engine, OS, NVMe, and remote cache state are explicitly reset or a fresh namespace is used. Those words are never inferred from repetition count. + +### 5.1 `point_pk` — primary-key node lookup with one projected property + +- Applicability to HelixDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.2 `point_edge` — stable edge-ID lookup including endpoints and one property + +- Applicability to HelixDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.3 `degree_1` — degree-one outgoing expansion + +- Applicability to HelixDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.4 `degree_32` — small adjacency expansion around degree 32 + +- Applicability to HelixDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.5 `degree_1k` — medium adjacency expansion around degree 1,024 + +- Applicability to HelixDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.6 `supernode` — range-limited expansion of a ten-million-degree supernode + +- Applicability to HelixDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.7 `expand_2` — selective two-hop expansion + +- Applicability to HelixDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.8 `expand_3` — three-hop frontier expansion with duplicate control + +- Applicability to HelixDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.9 `expand_into` — edge-existence/expand-into between already-bound endpoints + +- Applicability to HelixDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.10 `multi_edge` — parallel-edge identity and property projection + +- Applicability to HelixDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.11 `shortest` — bidirectional point-to-point unweighted shortest path + +- Applicability to HelixDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.12 `weighted` — weighted shortest path with property access + +- Applicability to HelixDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.13 `var_walk` — bounded variable-length walk + +- Applicability to HelixDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.14 `trail` — DIFFERENT EDGES trail enumeration + +- Applicability to HelixDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.15 `simple` — simple-path enumeration with explicit bound + +- Applicability to HelixDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.16 `triangle` — triangle pattern with worst-case-sensitive join + +- Applicability to HelixDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.17 `cycle4` — four-cycle pattern + +- Applicability to HelixDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.18 `star_join` — high-fanout star pattern with property filters + +- Applicability to HelixDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.19 `optional` — optional match preserving null/bag semantics + +- Applicability to HelixDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.20 `aggregate` — grouped aggregate after traversal + +- Applicability to HelixDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.21 `topk` — ordered top-k with late property materialization + +- Applicability to HelixDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.22 `scan` — full projected property scan + +- Applicability to HelixDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.23 `selective_scan` — zone/index-pruned selective property scan + +- Applicability to HelixDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.24 `mixed` — concurrent short reads, complex reads, and updates + +- Applicability to HelixDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.25 `ingest` — sustained transactional ingest with indexes enabled + +- Applicability to HelixDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.26 `bulk` — initial bulk load including index/CSR build + +- Applicability to HelixDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.27 `checkpoint` — checkpoint or compaction while readers remain active + +- Applicability to HelixDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.28 `recovery` — crash recovery at bounded dirty-log size + +- Applicability to HelixDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.29 `cold` — same query after clearing engine and OS/cache tiers + +- Applicability to HelixDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.30 `remote` — same query with authoritative bytes only in object storage + +- Applicability to HelixDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +## 6. Fairness controls + +- Same logical dataset and update stream; engine-native physical layouts are allowed and disclosed. +- Same result semantics; unsupported queries remain unsupported rather than rewritten into easier questions. +- Same durable acknowledgement class for write comparisons. +- Same number of physical cores and memory limit for self-hosted single-node tests. +- Same aggregate resources and replication fault tolerance for distributed tests. +- Officially recommended tuning may be applied before the freeze and is committed with rationale. +- Query-specific hints are allowed only when equivalent hints are offered to every engine and separately charted. +- Load/build/index time and bytes are first-class results. +- Cold, warm, and hot results are separate charts. +- Managed services use public configurations and cannot borrow hidden same-machine resource claims. +- Failed runs, OOMs, correctness mismatches, and timeouts stay in the dataset. +- Every chart links raw samples and the exact reproduction command. + +## 7. Likely advantages and limits + +The strongest known reason to choose this engine is tied to its family `Rust graph-vector database`, its execution path `Rust native stored/dynamic query execution combining traversal, vector, and search`, and its existing ecosystem. The strongest reason to reject it for zu's target is the gap between `current marketing says built on object storage, making it directly relevant, but technical evidence is sparse` and an S3-authoritative, request-budgeted, PB-scale graph service. + +Capacity statement: early-stage; no credible PB proof. This is not converted into an edge-count claim without a physical byte model including IDs, both adjacency directions, properties, indexes, MVCC, WAL, replicas, and free space. + +Commercial statement: license signals conflict between repository API metadata and README wording; verify the exact revision. License cost, support cost, and unavailable enterprise capabilities remain visible in TCO and feature tables. + +## 8. Concrete lessons for zu + +1. Keep stable logical node and edge identity independent of row group, CSR slot, shard, and object range. +2. Store forward and reverse adjacency as immutable range-addressable tiles carrying edge IDs. +3. Feed queries adjacency batches and typed vectors; prohibit one storage call per logical element. +4. Use vectorized/factorized execution for property-heavy patterns and dedicated frontier operators for recursion. +5. Cost topology, properties, network, cache certainty, remote requests, and result materialization together. +6. Separate the local embedded profile from the object-authoritative distributed read profile. +7. Fence writers with monotonic epochs and make ambiguous commits reconcilable by transaction ID. +8. Pack small graph tiles into large immutable objects while retaining independent checksums and range offsets. +9. Keep the hot topology working set in RAM/NVMe; batch cold frontier misses into few remote rounds. +10. Admission-control remote requests and bytes so fixed-price plans have an enforceable upper bound. +11. Partition by workload-aware graph locality, and expose cross-partition semantics rather than hiding them. +12. Publish qualified wins per workload cell; never promise a universal tenfold advantage. + +## 9. Evidence gaps to close before publication + +- Exact current version and release date. +- Exact license text for the benchmarked artifact. +- Storage bytes per node/edge/property on all standard datasets. +- Stable-edge-ID and parallel-edge semantics. +- Isolation litmus results and commit acknowledgement point. +- Crash recovery time versus dirty WAL size. +- Supernode behavior and maximum tested degree. +- Cold-start metadata and request count. +- Distributed cross-partition query amplification. +- Peak memory under skew, cancellation, and overload. +- Background compaction/GC effect on tail latency. +- Full load/index/checkpoint/backup resource cost. +- Reproducible largest-scale result. +- Independent or audited benchmark evidence. + +## 10. Primary and official sources + +- [Source repository](https://github.com/HelixDB/helix-db) +- [Official documentation index](https://docs.helix-db.com/llms.txt) +- [Current product architecture](https://www.helix-db.com/) +- [Rust SDK](https://docs.rs/helix-db/latest/helix_db/) +- [LDBC SNB Interactive and audited disclosures](https://ldbcouncil.org/benchmarks/snb/interactive/) +- [LDBC Graphalytics](https://ldbcouncil.org/benchmarks/graphalytics/) +- [SoK: The Faults in our Graph Benchmarks](https://arxiv.org/abs/2404.00766) + +## 11. Source-handling rules + +- Official documentation and source are evidence for implemented or declared behavior, not independent performance. +- A vendor benchmark is labeled vendor claim until the harness reproduces it. +- A peer-reviewed paper establishes only the version, configuration, and workload it evaluated. +- Search snippets, comparison sites, and unsourced blogs are discovery aids, not final evidence. +- Unknown is a valid result and creates a concrete experiment or source-inspection task. +- All web facts are rechecked at benchmark freeze because this corpus is current only through the research date. + +## 12. Reproduction record template + +- engine: `HelixDB` +- version: `TBD at benchmark freeze` +- artifact digest: `TBD` +- source commit: `TBD or managed-service N/A` +- edition/license: `TBD` +- query language/version: `TBD` +- storage and durability mode: `TBD` +- cluster and replication: `TBD` +- CPU/RAM/NVMe/network: `TBD` +- OS/kernel/filesystem: `TBD` +- dataset URI and digest: `TBD` +- loader command and duration: `TBD` +- physical bytes by category: `TBD` +- tuning file: `TBD` +- query corpus commit: `TBD` +- raw result URI/digest: `TBD` +- profiler/trace URI: `TBD` +- correctness status: `TBD` +- reviewer and rerun date: `TBD` diff --git a/docs/research/engine-huawei_ges.md b/docs/research/engine-huawei_ges.md new file mode 100644 index 0000000..58fcd64 --- /dev/null +++ b/docs/research/engine-huawei_ges.md @@ -0,0 +1,886 @@ +# Huawei Cloud Graph Engine Service (GES): 2026 deep technical and competitive specification + +Research cut: `2026-08-08` +Status: evidence-backed competitor audit; not a vendor endorsement +Family: `managed distributed graph engine` +Evidence convention: **Observed/official**, **Vendor claim**, **Research inference**, **Unknown**, **Qualification target**. + +## 1. Decision summary + +GES must be included because its audited SF100/SF300/SF1000 results lead the public LDBC table; zu cannot claim 'all competitors' while omitting it. + +This document answers two questions: what this engine actually proves in 2026, and what zu must build or measure to earn a defensible advantage. A missing public detail remains unknown; it is never silently filled with a favorable assumption. + +### Snapshot card + +- Lifecycle: active; GQL added in 2025 and docs refreshed in 2026. +- Data model: property graph. +- Query surface: GQL plus service query APIs and historical Cypher-like surfaces. +- Persistent layout: proprietary EYWA native graph kernel and managed distributed storage. +- Execution: distributed interactive query and graph algorithms. +- Transactions: managed-service guarantees require edition-specific verification. +- Distribution: managed distributed cloud service. +- Object-storage posture: not documented as S3-native live serving. +- License/commercial boundary: commercial proprietary managed service. +- Scale evidence: official material claims tens of billions of vertices and hundreds of billions of edges. +- Benchmark posture: 2025 LDBC audited results are the current public throughput bar. + +### Facts that materially affect comparison + +- F01 — GES uses Huawei's proprietary EYWA graph kernel. +- F02 — Huawei added a GQL query surface in August 2025. +- F03 — The 2025-12-01 audited runs report roughly 126K–139K operations per second across SF100 to SF1000. +- F04 — Full disclosure reports, not marketing summaries, define the tested hardware, cost, and workload. +- F05 — A managed Huawei result belongs in a service-level chart rather than a same-host open-source chart. + +### Bottom-line fit against zu's target + +- Very-low latency: compare hot point and bounded traversal paths; never extrapolate from scans or algorithms. +- Very-low resources: charge resident set, page cache, remote cache, background services, and replicas. +- Distributed: distinguish read replication, partitioned capacity, distributed transactions, and elastic stateless compute. +- Fixed cost: no engine has fixed marginal cost by declaration; admission, batching, and capacity reservations create the bound. +- S3 authority: backups, imports, lake scans, and S3-native demand paging are four different architectures. +- PB / trillion-edge scale: require a capacity derivation plus a run at the largest affordable scale; marketing adjectives do not qualify. +- Tenfold win: can be a per-cell qualification result, never a universal statement across incomparable workloads. + +## 2. Product and ecosystem boundary + +The audited unit is **Huawei Cloud Graph Engine Service (GES)** in the exact release, edition, deployment, and durability mode recorded by the harness. The family classification is **managed distributed graph engine**. The current lifecycle statement is: active; GQL added in 2025 and docs refreshed in 2026. + +The harness must record binary/container digest, source commit when available, build flags, plugins, license/edition, language mode, storage mode, cluster topology, replication factor, durability settings, cache sizes, thread counts, NUMA policy, kernel, filesystem, cloud region, and all environment variables that affect execution. + +A managed service is not placed in a same-hardware chart. It receives a service-level result with provisioned units, region, public price, and observed provider metrics. A historical engine remains useful for regression but cannot support a claim about beating all current competitors. + +## 3. Architecture reconstruction + +### 3.1 Logical model + +Huawei Cloud Graph Engine Service (GES) exposes property graph. The conformance corpus must test nulls, missing properties, labels/types, direction, self-loops, parallel edges, element equality, path equality, bag semantics, ordering, numeric overflow, string collation, temporal values, and schema evolution. + +### 3.2 Language and compiler + +The public query surface is GQL plus service query APIs and historical Cypher-like surfaces. Syntax similarity is not semantic equivalence. Every supported construct needs a result oracle and an unsupported-feature declaration. + +### 3.3 Storage + +The best supported storage summary is: proprietary EYWA native graph kernel and managed distributed storage. This statement must be refined from code, format documentation, or provider counters before using it in a performance explanation. + +### 3.4 Execution + +The best supported execution summary is: distributed interactive query and graph algorithms. The benchmark profiler must confirm which runtime and operators actually executed. + +### 3.5 Transactions and recovery + +The public contract is: managed-service guarantees require edition-specific verification. Exact acknowledgement, isolation anomalies, recovery bounds, and failover behavior remain separate qualification items. + +### 3.6 Distribution + +The deployment shape is: managed distributed cloud service. Replication is not capacity sharding; sharding is not distributed ACID; stateless readers are not stateless storage. + +### 3.7 Object storage and cost + +The 2026 posture is: not documented as S3-native live serving. The audit distinguishes authoritative live bytes, derived acceleration, backup, import/export, and spill. + +## 4. Forty-control deep audit + +### 4.1 `product_boundary` + +Audit question: What exact executable, edition, and storage mode is the system under test? + +Current assessment: Pin Huawei Cloud Graph Engine Service (GES), lifecycle `active; GQL added in 2025 and docs refreshed in 2026`, and its edition/mode. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.2 `authority` + +Audit question: Which durable component is the source of truth after every acknowledged write? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.3 `identity` + +Audit question: Are node and edge identities stable across compaction, export, replication, and restore? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.4 `parallel_edges` + +Audit question: Can distinct parallel edges retain properties and trail identity end to end? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.5 `schema` + +Audit question: Is the schema open, closed, optional, inferred, or externally mapped? + +Current assessment: Start from `property graph` and test actual constraints. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.6 `labels` + +Audit question: How are multiple labels represented and indexed? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.7 `adjacency_out` + +Audit question: How is outgoing adjacency located, encoded, split, cached, and updated? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.8 `adjacency_in` + +Audit question: Is incoming adjacency first-class, derived, replicated, or a fan-out operation? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.9 `supernodes` + +Audit question: How are million-to-billion-degree vertices represented and scheduled? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.10 `properties` + +Audit question: Are properties co-located, columnar, row-oriented, document-encoded, or remote? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.11 `compression` + +Audit question: Which topology, integer, string, null, and floating encodings are implemented? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.12 `checksums` + +Audit question: What integrity unit is verified on point reads and range reads? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.13 `snapshot` + +Audit question: What exact token pins graph data, schema, statistics, and indexes? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.14 `isolation` + +Audit question: Which anomalies are forbidden at the documented isolation level? + +Current assessment: Published summary: managed-service guarantees require edition-specific verification. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.15 `durability` + +Audit question: What device/service acknowledgement is required before commit returns? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.16 `recovery` + +Audit question: What bounds restart work after a clean stop and a crash? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.17 `writer_fencing` + +Audit question: Can a stale writer acknowledge after failover or lease expiry? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.18 `partitioning` + +Audit question: What key determines placement and what happens to cross-partition edges? + +Current assessment: Published distribution summary: managed distributed cloud service. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.19 `rebalancing` + +Audit question: Can placement change online without changing logical identity? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.20 `replication` + +Audit question: Are replicas full, sharded, synchronous, asynchronous, or shared-storage readers? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.21 `optimizer` + +Audit question: Does the optimizer cost graph expansion, joins, network, cache, and remote requests? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.22 `statistics` + +Audit question: Which degree, correlation, path, and property statistics are persistent? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.23 `execution` + +Audit question: Is execution tuple-at-a-time, vectorized, factorized, compiled, matrix, or actor based? + +Current assessment: Expected family: distributed interactive query and graph algorithms. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.24 `recursion` + +Audit question: How are BFS, shortest paths, trails, simple paths, and arbitrary reachability executed? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.25 `parallelism` + +Audit question: How does the engine avoid skew and nested parallelism under mixed queries? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.26 `memory` + +Audit question: Are all variable allocations charged to bounded query and system budgets? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.27 `spill` + +Audit question: Which operators spill, in what format, and with what admission controls? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.28 `cancellation` + +Audit question: Can cancellation stop CPU, local I/O, remote I/O, retries, and prefetch? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.29 `cache` + +Audit question: What is cached, how is it keyed, admitted, pinned, and evicted? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.30 `cold_start` + +Audit question: What metadata and data round trips are required with empty caches? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.31 `object_requests` + +Audit question: Can a query issue one remote request per node, edge, or result row? + +Current assessment: Published object-store posture: not documented as S3-native live serving. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.32 `cost_admission` + +Audit question: Are request, byte, CPU, spill, and result limits enforced before work? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.33 `observability` + +Audit question: Can operators report rows, edges, bytes, requests, stalls, memory, and spill? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.34 `language` + +Audit question: Which GQL/Cypher/SQL-PGQ/Gremlin/SPARQL semantics are declared and tested? + +Current assessment: Declared surface: GQL plus service query APIs and historical Cypher-like surfaces. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.35 `updates` + +Audit question: Are DDL, insert, merge, update, detach delete, and constraints complete? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.36 `bulk_load` + +Audit question: Does bulk load preserve transactional and index invariants? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.37 `backup` + +Audit question: Is backup consistent, incremental, immutable, and restore-tested? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.38 `gc` + +Audit question: How are old snapshots, orphan objects, tombstones, and indexes reclaimed safely? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.39 `security` + +Audit question: Are authentication, authorization, encryption, audit, and tenant isolation in scope? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.40 `operations` + +Audit question: What compaction, upgrade, repair, verification, and capacity procedures exist? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +## 5. Benchmark contract for this engine + +Every case runs correctness first, then isolated latency, then closed-loop concurrency, then open-loop overload. Report median, p95, p99, p99.9, timeout/rejection rate, throughput, CPU-seconds, peak RSS, cache bytes, disk bytes, network bytes, remote requests, write amplification, and estimated monthly cost. + +Warm means all intended engine caches are populated without changing the query parameters. Hot means the exact working set is resident. Cold means process-local, engine, OS, NVMe, and remote cache state are explicitly reset or a fresh namespace is used. Those words are never inferred from repetition count. + +### 5.1 `point_pk` — primary-key node lookup with one projected property + +- Applicability to Huawei Cloud Graph Engine Service (GES): required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.2 `point_edge` — stable edge-ID lookup including endpoints and one property + +- Applicability to Huawei Cloud Graph Engine Service (GES): required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.3 `degree_1` — degree-one outgoing expansion + +- Applicability to Huawei Cloud Graph Engine Service (GES): required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.4 `degree_32` — small adjacency expansion around degree 32 + +- Applicability to Huawei Cloud Graph Engine Service (GES): required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.5 `degree_1k` — medium adjacency expansion around degree 1,024 + +- Applicability to Huawei Cloud Graph Engine Service (GES): required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.6 `supernode` — range-limited expansion of a ten-million-degree supernode + +- Applicability to Huawei Cloud Graph Engine Service (GES): required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.7 `expand_2` — selective two-hop expansion + +- Applicability to Huawei Cloud Graph Engine Service (GES): required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.8 `expand_3` — three-hop frontier expansion with duplicate control + +- Applicability to Huawei Cloud Graph Engine Service (GES): required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.9 `expand_into` — edge-existence/expand-into between already-bound endpoints + +- Applicability to Huawei Cloud Graph Engine Service (GES): required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.10 `multi_edge` — parallel-edge identity and property projection + +- Applicability to Huawei Cloud Graph Engine Service (GES): required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.11 `shortest` — bidirectional point-to-point unweighted shortest path + +- Applicability to Huawei Cloud Graph Engine Service (GES): required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.12 `weighted` — weighted shortest path with property access + +- Applicability to Huawei Cloud Graph Engine Service (GES): required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.13 `var_walk` — bounded variable-length walk + +- Applicability to Huawei Cloud Graph Engine Service (GES): required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.14 `trail` — DIFFERENT EDGES trail enumeration + +- Applicability to Huawei Cloud Graph Engine Service (GES): required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.15 `simple` — simple-path enumeration with explicit bound + +- Applicability to Huawei Cloud Graph Engine Service (GES): required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.16 `triangle` — triangle pattern with worst-case-sensitive join + +- Applicability to Huawei Cloud Graph Engine Service (GES): required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.17 `cycle4` — four-cycle pattern + +- Applicability to Huawei Cloud Graph Engine Service (GES): required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.18 `star_join` — high-fanout star pattern with property filters + +- Applicability to Huawei Cloud Graph Engine Service (GES): required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.19 `optional` — optional match preserving null/bag semantics + +- Applicability to Huawei Cloud Graph Engine Service (GES): required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.20 `aggregate` — grouped aggregate after traversal + +- Applicability to Huawei Cloud Graph Engine Service (GES): required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.21 `topk` — ordered top-k with late property materialization + +- Applicability to Huawei Cloud Graph Engine Service (GES): required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.22 `scan` — full projected property scan + +- Applicability to Huawei Cloud Graph Engine Service (GES): required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.23 `selective_scan` — zone/index-pruned selective property scan + +- Applicability to Huawei Cloud Graph Engine Service (GES): required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.24 `mixed` — concurrent short reads, complex reads, and updates + +- Applicability to Huawei Cloud Graph Engine Service (GES): required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.25 `ingest` — sustained transactional ingest with indexes enabled + +- Applicability to Huawei Cloud Graph Engine Service (GES): required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.26 `bulk` — initial bulk load including index/CSR build + +- Applicability to Huawei Cloud Graph Engine Service (GES): required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.27 `checkpoint` — checkpoint or compaction while readers remain active + +- Applicability to Huawei Cloud Graph Engine Service (GES): required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.28 `recovery` — crash recovery at bounded dirty-log size + +- Applicability to Huawei Cloud Graph Engine Service (GES): required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.29 `cold` — same query after clearing engine and OS/cache tiers + +- Applicability to Huawei Cloud Graph Engine Service (GES): required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.30 `remote` — same query with authoritative bytes only in object storage + +- Applicability to Huawei Cloud Graph Engine Service (GES): required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +## 6. Fairness controls + +- Same logical dataset and update stream; engine-native physical layouts are allowed and disclosed. +- Same result semantics; unsupported queries remain unsupported rather than rewritten into easier questions. +- Same durable acknowledgement class for write comparisons. +- Same number of physical cores and memory limit for self-hosted single-node tests. +- Same aggregate resources and replication fault tolerance for distributed tests. +- Officially recommended tuning may be applied before the freeze and is committed with rationale. +- Query-specific hints are allowed only when equivalent hints are offered to every engine and separately charted. +- Load/build/index time and bytes are first-class results. +- Cold, warm, and hot results are separate charts. +- Managed services use public configurations and cannot borrow hidden same-machine resource claims. +- Failed runs, OOMs, correctness mismatches, and timeouts stay in the dataset. +- Every chart links raw samples and the exact reproduction command. + +## 7. Likely advantages and limits + +The strongest known reason to choose this engine is tied to its family `managed distributed graph engine`, its execution path `distributed interactive query and graph algorithms`, and its existing ecosystem. The strongest reason to reject it for zu's target is the gap between `not documented as S3-native live serving` and an S3-authoritative, request-budgeted, PB-scale graph service. + +Capacity statement: official material claims tens of billions of vertices and hundreds of billions of edges. This is not converted into an edge-count claim without a physical byte model including IDs, both adjacency directions, properties, indexes, MVCC, WAL, replicas, and free space. + +Commercial statement: commercial proprietary managed service. License cost, support cost, and unavailable enterprise capabilities remain visible in TCO and feature tables. + +## 8. Concrete lessons for zu + +1. Keep stable logical node and edge identity independent of row group, CSR slot, shard, and object range. +2. Store forward and reverse adjacency as immutable range-addressable tiles carrying edge IDs. +3. Feed queries adjacency batches and typed vectors; prohibit one storage call per logical element. +4. Use vectorized/factorized execution for property-heavy patterns and dedicated frontier operators for recursion. +5. Cost topology, properties, network, cache certainty, remote requests, and result materialization together. +6. Separate the local embedded profile from the object-authoritative distributed read profile. +7. Fence writers with monotonic epochs and make ambiguous commits reconcilable by transaction ID. +8. Pack small graph tiles into large immutable objects while retaining independent checksums and range offsets. +9. Keep the hot topology working set in RAM/NVMe; batch cold frontier misses into few remote rounds. +10. Admission-control remote requests and bytes so fixed-price plans have an enforceable upper bound. +11. Partition by workload-aware graph locality, and expose cross-partition semantics rather than hiding them. +12. Publish qualified wins per workload cell; never promise a universal tenfold advantage. + +## 9. Evidence gaps to close before publication + +- Exact current version and release date. +- Exact license text for the benchmarked artifact. +- Storage bytes per node/edge/property on all standard datasets. +- Stable-edge-ID and parallel-edge semantics. +- Isolation litmus results and commit acknowledgement point. +- Crash recovery time versus dirty WAL size. +- Supernode behavior and maximum tested degree. +- Cold-start metadata and request count. +- Distributed cross-partition query amplification. +- Peak memory under skew, cancellation, and overload. +- Background compaction/GC effect on tail latency. +- Full load/index/checkpoint/backup resource cost. +- Reproducible largest-scale result. +- Independent or audited benchmark evidence. + +## 10. Primary and official sources + +- [2026 What's New](https://support.huaweicloud.com/intl/en-us/wtsnew-ges/index.html) +- [Service overview](https://www.huaweicloud.com/intl/en-us/product/ges.html) +- [Audited SF100 result](https://ldbcouncil.org/benchmarks/snb/interactive/2025-12-01-graph-engine-service-sf100) +- [LDBC results table](https://ldbcouncil.org/benchmarks/snb/interactive/) +- [LDBC SNB Interactive and audited disclosures](https://ldbcouncil.org/benchmarks/snb/interactive/) +- [LDBC Graphalytics](https://ldbcouncil.org/benchmarks/graphalytics/) +- [SoK: The Faults in our Graph Benchmarks](https://arxiv.org/abs/2404.00766) + +## 11. Source-handling rules + +- Official documentation and source are evidence for implemented or declared behavior, not independent performance. +- A vendor benchmark is labeled vendor claim until the harness reproduces it. +- A peer-reviewed paper establishes only the version, configuration, and workload it evaluated. +- Search snippets, comparison sites, and unsourced blogs are discovery aids, not final evidence. +- Unknown is a valid result and creates a concrete experiment or source-inspection task. +- All web facts are rechecked at benchmark freeze because this corpus is current only through the research date. + +## 12. Reproduction record template + +- engine: `Huawei Cloud Graph Engine Service (GES)` +- version: `TBD at benchmark freeze` +- artifact digest: `TBD` +- source commit: `TBD or managed-service N/A` +- edition/license: `TBD` +- query language/version: `TBD` +- storage and durability mode: `TBD` +- cluster and replication: `TBD` +- CPU/RAM/NVMe/network: `TBD` +- OS/kernel/filesystem: `TBD` +- dataset URI and digest: `TBD` +- loader command and duration: `TBD` +- physical bytes by category: `TBD` +- tuning file: `TBD` +- query corpus commit: `TBD` +- raw result URI/digest: `TBD` +- profiler/trace URI: `TBD` +- correctness status: `TBD` +- reviewer and rerun date: `TBD` diff --git a/docs/research/engine-ibm_db2_graph.md b/docs/research/engine-ibm_db2_graph.md new file mode 100644 index 0000000..91fc9af --- /dev/null +++ b/docs/research/engine-ibm_db2_graph.md @@ -0,0 +1,883 @@ +# IBM Db2 Graph: 2026 deep technical and competitive specification + +Research cut: `2026-08-08` +Status: evidence-backed competitor audit; not a vendor endorsement +Family: `Gremlin layer over Db2 relational data` +Evidence convention: **Observed/official**, **Vendor claim**, **Research inference**, **Unknown**, **Qualification target**. + +## 1. Decision summary + +Db2 Graph is included for completeness but labeled legacy so it cannot inflate current competitor coverage. + +This document answers two questions: what this engine actually proves in 2026, and what zu must build or measure to earn a defensible advantage. A missing public detail remains unknown; it is never silently filled with a favorable assumption. + +### Snapshot card + +- Lifecycle: legacy/limited: current IBM page says standalone support is tied to Db2 11.5.6–11.5.8. +- Data model: property graph mapping over Db2. +- Query surface: Apache TinkerPop Gremlin. +- Persistent layout: Db2 relational storage with graph mapping/optimization. +- Execution: Gremlin transformation and optimization over Db2. +- Transactions: inherits Db2 transactions for relational authority. +- Distribution: inherits Db2 deployment and read-scale features; graph layer is not native PB sharding. +- Object-storage posture: not S3-native. +- License/commercial boundary: commercial proprietary. +- Scale evidence: Db2 platform scale; current graph lifecycle limits its competitive weight. +- Benchmark posture: retain as SQL/Gremlin compatibility baseline only if supported artifacts are obtainable. + +### Facts that materially affect comparison + +- F01 — IBM describes Db2 Graph as transforming and optimizing Gremlin for Db2 data. +- F02 — The current documentation narrows standalone operation to Db2 11.5.6 through 11.5.8. +- F03 — Relational authority avoids a second graph copy in some workflows. +- F04 — Graph traversal performance inherits the mapping and relational access plan. +- F05 — Lifecycle and artifact availability must be confirmed before any rerun. + +### Bottom-line fit against zu's target + +- Very-low latency: compare hot point and bounded traversal paths; never extrapolate from scans or algorithms. +- Very-low resources: charge resident set, page cache, remote cache, background services, and replicas. +- Distributed: distinguish read replication, partitioned capacity, distributed transactions, and elastic stateless compute. +- Fixed cost: no engine has fixed marginal cost by declaration; admission, batching, and capacity reservations create the bound. +- S3 authority: backups, imports, lake scans, and S3-native demand paging are four different architectures. +- PB / trillion-edge scale: require a capacity derivation plus a run at the largest affordable scale; marketing adjectives do not qualify. +- Tenfold win: can be a per-cell qualification result, never a universal statement across incomparable workloads. + +## 2. Product and ecosystem boundary + +The audited unit is **IBM Db2 Graph** in the exact release, edition, deployment, and durability mode recorded by the harness. The family classification is **Gremlin layer over Db2 relational data**. The current lifecycle statement is: legacy/limited: current IBM page says standalone support is tied to Db2 11.5.6–11.5.8. + +The harness must record binary/container digest, source commit when available, build flags, plugins, license/edition, language mode, storage mode, cluster topology, replication factor, durability settings, cache sizes, thread counts, NUMA policy, kernel, filesystem, cloud region, and all environment variables that affect execution. + +A managed service is not placed in a same-hardware chart. It receives a service-level result with provisioned units, region, public price, and observed provider metrics. A historical engine remains useful for regression but cannot support a claim about beating all current competitors. + +## 3. Architecture reconstruction + +### 3.1 Logical model + +IBM Db2 Graph exposes property graph mapping over Db2. The conformance corpus must test nulls, missing properties, labels/types, direction, self-loops, parallel edges, element equality, path equality, bag semantics, ordering, numeric overflow, string collation, temporal values, and schema evolution. + +### 3.2 Language and compiler + +The public query surface is Apache TinkerPop Gremlin. Syntax similarity is not semantic equivalence. Every supported construct needs a result oracle and an unsupported-feature declaration. + +### 3.3 Storage + +The best supported storage summary is: Db2 relational storage with graph mapping/optimization. This statement must be refined from code, format documentation, or provider counters before using it in a performance explanation. + +### 3.4 Execution + +The best supported execution summary is: Gremlin transformation and optimization over Db2. The benchmark profiler must confirm which runtime and operators actually executed. + +### 3.5 Transactions and recovery + +The public contract is: inherits Db2 transactions for relational authority. Exact acknowledgement, isolation anomalies, recovery bounds, and failover behavior remain separate qualification items. + +### 3.6 Distribution + +The deployment shape is: inherits Db2 deployment and read-scale features; graph layer is not native PB sharding. Replication is not capacity sharding; sharding is not distributed ACID; stateless readers are not stateless storage. + +### 3.7 Object storage and cost + +The 2026 posture is: not S3-native. The audit distinguishes authoritative live bytes, derived acceleration, backup, import/export, and spill. + +## 4. Forty-control deep audit + +### 4.1 `product_boundary` + +Audit question: What exact executable, edition, and storage mode is the system under test? + +Current assessment: Pin IBM Db2 Graph, lifecycle `legacy/limited: current IBM page says standalone support is tied to Db2 11.5.6–11.5.8`, and its edition/mode. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.2 `authority` + +Audit question: Which durable component is the source of truth after every acknowledged write? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.3 `identity` + +Audit question: Are node and edge identities stable across compaction, export, replication, and restore? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.4 `parallel_edges` + +Audit question: Can distinct parallel edges retain properties and trail identity end to end? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.5 `schema` + +Audit question: Is the schema open, closed, optional, inferred, or externally mapped? + +Current assessment: Start from `property graph mapping over Db2` and test actual constraints. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.6 `labels` + +Audit question: How are multiple labels represented and indexed? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.7 `adjacency_out` + +Audit question: How is outgoing adjacency located, encoded, split, cached, and updated? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.8 `adjacency_in` + +Audit question: Is incoming adjacency first-class, derived, replicated, or a fan-out operation? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.9 `supernodes` + +Audit question: How are million-to-billion-degree vertices represented and scheduled? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.10 `properties` + +Audit question: Are properties co-located, columnar, row-oriented, document-encoded, or remote? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.11 `compression` + +Audit question: Which topology, integer, string, null, and floating encodings are implemented? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.12 `checksums` + +Audit question: What integrity unit is verified on point reads and range reads? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.13 `snapshot` + +Audit question: What exact token pins graph data, schema, statistics, and indexes? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.14 `isolation` + +Audit question: Which anomalies are forbidden at the documented isolation level? + +Current assessment: Published summary: inherits Db2 transactions for relational authority. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.15 `durability` + +Audit question: What device/service acknowledgement is required before commit returns? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.16 `recovery` + +Audit question: What bounds restart work after a clean stop and a crash? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.17 `writer_fencing` + +Audit question: Can a stale writer acknowledge after failover or lease expiry? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.18 `partitioning` + +Audit question: What key determines placement and what happens to cross-partition edges? + +Current assessment: Published distribution summary: inherits Db2 deployment and read-scale features; graph layer is not native PB sharding. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.19 `rebalancing` + +Audit question: Can placement change online without changing logical identity? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.20 `replication` + +Audit question: Are replicas full, sharded, synchronous, asynchronous, or shared-storage readers? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.21 `optimizer` + +Audit question: Does the optimizer cost graph expansion, joins, network, cache, and remote requests? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.22 `statistics` + +Audit question: Which degree, correlation, path, and property statistics are persistent? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.23 `execution` + +Audit question: Is execution tuple-at-a-time, vectorized, factorized, compiled, matrix, or actor based? + +Current assessment: Expected family: Gremlin transformation and optimization over Db2. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.24 `recursion` + +Audit question: How are BFS, shortest paths, trails, simple paths, and arbitrary reachability executed? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.25 `parallelism` + +Audit question: How does the engine avoid skew and nested parallelism under mixed queries? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.26 `memory` + +Audit question: Are all variable allocations charged to bounded query and system budgets? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.27 `spill` + +Audit question: Which operators spill, in what format, and with what admission controls? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.28 `cancellation` + +Audit question: Can cancellation stop CPU, local I/O, remote I/O, retries, and prefetch? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.29 `cache` + +Audit question: What is cached, how is it keyed, admitted, pinned, and evicted? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.30 `cold_start` + +Audit question: What metadata and data round trips are required with empty caches? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.31 `object_requests` + +Audit question: Can a query issue one remote request per node, edge, or result row? + +Current assessment: Published object-store posture: not S3-native. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.32 `cost_admission` + +Audit question: Are request, byte, CPU, spill, and result limits enforced before work? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.33 `observability` + +Audit question: Can operators report rows, edges, bytes, requests, stalls, memory, and spill? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.34 `language` + +Audit question: Which GQL/Cypher/SQL-PGQ/Gremlin/SPARQL semantics are declared and tested? + +Current assessment: Declared surface: Apache TinkerPop Gremlin. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.35 `updates` + +Audit question: Are DDL, insert, merge, update, detach delete, and constraints complete? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.36 `bulk_load` + +Audit question: Does bulk load preserve transactional and index invariants? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.37 `backup` + +Audit question: Is backup consistent, incremental, immutable, and restore-tested? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.38 `gc` + +Audit question: How are old snapshots, orphan objects, tombstones, and indexes reclaimed safely? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.39 `security` + +Audit question: Are authentication, authorization, encryption, audit, and tenant isolation in scope? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.40 `operations` + +Audit question: What compaction, upgrade, repair, verification, and capacity procedures exist? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +## 5. Benchmark contract for this engine + +Every case runs correctness first, then isolated latency, then closed-loop concurrency, then open-loop overload. Report median, p95, p99, p99.9, timeout/rejection rate, throughput, CPU-seconds, peak RSS, cache bytes, disk bytes, network bytes, remote requests, write amplification, and estimated monthly cost. + +Warm means all intended engine caches are populated without changing the query parameters. Hot means the exact working set is resident. Cold means process-local, engine, OS, NVMe, and remote cache state are explicitly reset or a fresh namespace is used. Those words are never inferred from repetition count. + +### 5.1 `point_pk` — primary-key node lookup with one projected property + +- Applicability to IBM Db2 Graph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.2 `point_edge` — stable edge-ID lookup including endpoints and one property + +- Applicability to IBM Db2 Graph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.3 `degree_1` — degree-one outgoing expansion + +- Applicability to IBM Db2 Graph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.4 `degree_32` — small adjacency expansion around degree 32 + +- Applicability to IBM Db2 Graph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.5 `degree_1k` — medium adjacency expansion around degree 1,024 + +- Applicability to IBM Db2 Graph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.6 `supernode` — range-limited expansion of a ten-million-degree supernode + +- Applicability to IBM Db2 Graph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.7 `expand_2` — selective two-hop expansion + +- Applicability to IBM Db2 Graph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.8 `expand_3` — three-hop frontier expansion with duplicate control + +- Applicability to IBM Db2 Graph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.9 `expand_into` — edge-existence/expand-into between already-bound endpoints + +- Applicability to IBM Db2 Graph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.10 `multi_edge` — parallel-edge identity and property projection + +- Applicability to IBM Db2 Graph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.11 `shortest` — bidirectional point-to-point unweighted shortest path + +- Applicability to IBM Db2 Graph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.12 `weighted` — weighted shortest path with property access + +- Applicability to IBM Db2 Graph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.13 `var_walk` — bounded variable-length walk + +- Applicability to IBM Db2 Graph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.14 `trail` — DIFFERENT EDGES trail enumeration + +- Applicability to IBM Db2 Graph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.15 `simple` — simple-path enumeration with explicit bound + +- Applicability to IBM Db2 Graph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.16 `triangle` — triangle pattern with worst-case-sensitive join + +- Applicability to IBM Db2 Graph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.17 `cycle4` — four-cycle pattern + +- Applicability to IBM Db2 Graph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.18 `star_join` — high-fanout star pattern with property filters + +- Applicability to IBM Db2 Graph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.19 `optional` — optional match preserving null/bag semantics + +- Applicability to IBM Db2 Graph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.20 `aggregate` — grouped aggregate after traversal + +- Applicability to IBM Db2 Graph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.21 `topk` — ordered top-k with late property materialization + +- Applicability to IBM Db2 Graph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.22 `scan` — full projected property scan + +- Applicability to IBM Db2 Graph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.23 `selective_scan` — zone/index-pruned selective property scan + +- Applicability to IBM Db2 Graph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.24 `mixed` — concurrent short reads, complex reads, and updates + +- Applicability to IBM Db2 Graph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.25 `ingest` — sustained transactional ingest with indexes enabled + +- Applicability to IBM Db2 Graph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.26 `bulk` — initial bulk load including index/CSR build + +- Applicability to IBM Db2 Graph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.27 `checkpoint` — checkpoint or compaction while readers remain active + +- Applicability to IBM Db2 Graph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.28 `recovery` — crash recovery at bounded dirty-log size + +- Applicability to IBM Db2 Graph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.29 `cold` — same query after clearing engine and OS/cache tiers + +- Applicability to IBM Db2 Graph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.30 `remote` — same query with authoritative bytes only in object storage + +- Applicability to IBM Db2 Graph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +## 6. Fairness controls + +- Same logical dataset and update stream; engine-native physical layouts are allowed and disclosed. +- Same result semantics; unsupported queries remain unsupported rather than rewritten into easier questions. +- Same durable acknowledgement class for write comparisons. +- Same number of physical cores and memory limit for self-hosted single-node tests. +- Same aggregate resources and replication fault tolerance for distributed tests. +- Officially recommended tuning may be applied before the freeze and is committed with rationale. +- Query-specific hints are allowed only when equivalent hints are offered to every engine and separately charted. +- Load/build/index time and bytes are first-class results. +- Cold, warm, and hot results are separate charts. +- Managed services use public configurations and cannot borrow hidden same-machine resource claims. +- Failed runs, OOMs, correctness mismatches, and timeouts stay in the dataset. +- Every chart links raw samples and the exact reproduction command. + +## 7. Likely advantages and limits + +The strongest known reason to choose this engine is tied to its family `Gremlin layer over Db2 relational data`, its execution path `Gremlin transformation and optimization over Db2`, and its existing ecosystem. The strongest reason to reject it for zu's target is the gap between `not S3-native` and an S3-authoritative, request-budgeted, PB-scale graph service. + +Capacity statement: Db2 platform scale; current graph lifecycle limits its competitive weight. This is not converted into an edge-count claim without a physical byte model including IDs, both adjacency directions, properties, indexes, MVCC, WAL, replicas, and free space. + +Commercial statement: commercial proprietary. License cost, support cost, and unavailable enterprise capabilities remain visible in TCO and feature tables. + +## 8. Concrete lessons for zu + +1. Keep stable logical node and edge identity independent of row group, CSR slot, shard, and object range. +2. Store forward and reverse adjacency as immutable range-addressable tiles carrying edge IDs. +3. Feed queries adjacency batches and typed vectors; prohibit one storage call per logical element. +4. Use vectorized/factorized execution for property-heavy patterns and dedicated frontier operators for recursion. +5. Cost topology, properties, network, cache certainty, remote requests, and result materialization together. +6. Separate the local embedded profile from the object-authoritative distributed read profile. +7. Fence writers with monotonic epochs and make ambiguous commits reconcilable by transaction ID. +8. Pack small graph tiles into large immutable objects while retaining independent checksums and range offsets. +9. Keep the hot topology working set in RAM/NVMe; batch cold frontier misses into few remote rounds. +10. Admission-control remote requests and bytes so fixed-price plans have an enforceable upper bound. +11. Partition by workload-aware graph locality, and expose cross-partition semantics rather than hiding them. +12. Publish qualified wins per workload cell; never promise a universal tenfold advantage. + +## 9. Evidence gaps to close before publication + +- Exact current version and release date. +- Exact license text for the benchmarked artifact. +- Storage bytes per node/edge/property on all standard datasets. +- Stable-edge-ID and parallel-edge semantics. +- Isolation litmus results and commit acknowledgement point. +- Crash recovery time versus dirty WAL size. +- Supernode behavior and maximum tested degree. +- Cold-start metadata and request count. +- Distributed cross-partition query amplification. +- Peak memory under skew, cancellation, and overload. +- Background compaction/GC effect on tail latency. +- Full load/index/checkpoint/backup resource cost. +- Reproducible largest-scale result. +- Independent or audited benchmark evidence. + +## 10. Primary and official sources + +- [IBM Db2 Graph overview](https://www.ibm.com/docs/SSEPGG_11.5.0/com.ibm.db2.luw.graph.doc/doc/c_graph_ovrvu.html) +- [LDBC SNB Interactive and audited disclosures](https://ldbcouncil.org/benchmarks/snb/interactive/) +- [LDBC Graphalytics](https://ldbcouncil.org/benchmarks/graphalytics/) +- [SoK: The Faults in our Graph Benchmarks](https://arxiv.org/abs/2404.00766) + +## 11. Source-handling rules + +- Official documentation and source are evidence for implemented or declared behavior, not independent performance. +- A vendor benchmark is labeled vendor claim until the harness reproduces it. +- A peer-reviewed paper establishes only the version, configuration, and workload it evaluated. +- Search snippets, comparison sites, and unsourced blogs are discovery aids, not final evidence. +- Unknown is a valid result and creates a concrete experiment or source-inspection task. +- All web facts are rechecked at benchmark freeze because this corpus is current only through the research date. + +## 12. Reproduction record template + +- engine: `IBM Db2 Graph` +- version: `TBD at benchmark freeze` +- artifact digest: `TBD` +- source commit: `TBD or managed-service N/A` +- edition/license: `TBD` +- query language/version: `TBD` +- storage and durability mode: `TBD` +- cluster and replication: `TBD` +- CPU/RAM/NVMe/network: `TBD` +- OS/kernel/filesystem: `TBD` +- dataset URI and digest: `TBD` +- loader command and duration: `TBD` +- physical bytes by category: `TBD` +- tuning file: `TBD` +- query corpus commit: `TBD` +- raw result URI/digest: `TBD` +- profiler/trace URI: `TBD` +- correctness status: `TBD` +- reviewer and rerun date: `TBD` diff --git a/docs/research/engine-janusgraph.md b/docs/research/engine-janusgraph.md new file mode 100644 index 0000000..14686e1 --- /dev/null +++ b/docs/research/engine-janusgraph.md @@ -0,0 +1,886 @@ +# JanusGraph: 2026 deep technical and competitive specification + +Research cut: `2026-08-08` +Status: evidence-backed competitor audit; not a vendor endorsement +Family: `storage-agnostic distributed graph layer` +Evidence convention: **Observed/official**, **Vendor claim**, **Research inference**, **Unknown**, **Qualification target**. + +## 1. Decision summary + +JanusGraph proves modular scale but also shows why a synchronous fine-grained storage SPI is a latency and operations trap. + +This document answers two questions: what this engine actually proves in 2026, and what zu must build or measure to earn a defensible advantage. A missing public detail remains unknown; it is never silently filled with a favorable assumption. + +### Snapshot card + +- Lifecycle: active 1.x. +- Data model: property graph via TinkerPop. +- Query surface: Gremlin. +- Persistent layout: key-column-value abstraction over Cassandra/CQL, HBase, Bigtable, ScyllaDB, or BerkeleyDB; external mixed indexes. +- Execution: JVM query execution near the application/server with backend round trips and caches. +- Transactions: semantics inherit backend limitations; not generally serializable/atomic across rows. +- Distribution: horizontal scale through chosen backend and stateless-ish JanusGraph servers. +- Object-storage posture: possible indirectly through cloud backends, but not S3-native and pointer/request economics are unfavorable. +- License/commercial boundary: Apache-2.0. +- Scale evidence: large distributed capacity is plausible through backends; supernodes and bulk load have documented limits. +- Benchmark posture: benchmark is a full stack: JanusGraph, backend, index service, consistency, and cache. + +### Facts that materially affect comparison + +- F01 — Query execution, cache, and transactions run in the JanusGraph JVM. +- F02 — Persistence and mixed indexing are separate adapters and frequently separate clusters. +- F03 — Cassandra/HBase modes do not automatically provide serializable multi-row transactions. +- F04 — The docs warn that loading millions of edges into one vertex can fail for some backends. +- F05 — The external index adds consistency and operational dimensions to property filters. + +### Bottom-line fit against zu's target + +- Very-low latency: compare hot point and bounded traversal paths; never extrapolate from scans or algorithms. +- Very-low resources: charge resident set, page cache, remote cache, background services, and replicas. +- Distributed: distinguish read replication, partitioned capacity, distributed transactions, and elastic stateless compute. +- Fixed cost: no engine has fixed marginal cost by declaration; admission, batching, and capacity reservations create the bound. +- S3 authority: backups, imports, lake scans, and S3-native demand paging are four different architectures. +- PB / trillion-edge scale: require a capacity derivation plus a run at the largest affordable scale; marketing adjectives do not qualify. +- Tenfold win: can be a per-cell qualification result, never a universal statement across incomparable workloads. + +## 2. Product and ecosystem boundary + +The audited unit is **JanusGraph** in the exact release, edition, deployment, and durability mode recorded by the harness. The family classification is **storage-agnostic distributed graph layer**. The current lifecycle statement is: active 1.x. + +The harness must record binary/container digest, source commit when available, build flags, plugins, license/edition, language mode, storage mode, cluster topology, replication factor, durability settings, cache sizes, thread counts, NUMA policy, kernel, filesystem, cloud region, and all environment variables that affect execution. + +A managed service is not placed in a same-hardware chart. It receives a service-level result with provisioned units, region, public price, and observed provider metrics. A historical engine remains useful for regression but cannot support a claim about beating all current competitors. + +## 3. Architecture reconstruction + +### 3.1 Logical model + +JanusGraph exposes property graph via TinkerPop. The conformance corpus must test nulls, missing properties, labels/types, direction, self-loops, parallel edges, element equality, path equality, bag semantics, ordering, numeric overflow, string collation, temporal values, and schema evolution. + +### 3.2 Language and compiler + +The public query surface is Gremlin. Syntax similarity is not semantic equivalence. Every supported construct needs a result oracle and an unsupported-feature declaration. + +### 3.3 Storage + +The best supported storage summary is: key-column-value abstraction over Cassandra/CQL, HBase, Bigtable, ScyllaDB, or BerkeleyDB; external mixed indexes. This statement must be refined from code, format documentation, or provider counters before using it in a performance explanation. + +### 3.4 Execution + +The best supported execution summary is: JVM query execution near the application/server with backend round trips and caches. The benchmark profiler must confirm which runtime and operators actually executed. + +### 3.5 Transactions and recovery + +The public contract is: semantics inherit backend limitations; not generally serializable/atomic across rows. Exact acknowledgement, isolation anomalies, recovery bounds, and failover behavior remain separate qualification items. + +### 3.6 Distribution + +The deployment shape is: horizontal scale through chosen backend and stateless-ish JanusGraph servers. Replication is not capacity sharding; sharding is not distributed ACID; stateless readers are not stateless storage. + +### 3.7 Object storage and cost + +The 2026 posture is: possible indirectly through cloud backends, but not S3-native and pointer/request economics are unfavorable. The audit distinguishes authoritative live bytes, derived acceleration, backup, import/export, and spill. + +## 4. Forty-control deep audit + +### 4.1 `product_boundary` + +Audit question: What exact executable, edition, and storage mode is the system under test? + +Current assessment: Pin JanusGraph, lifecycle `active 1.x`, and its edition/mode. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.2 `authority` + +Audit question: Which durable component is the source of truth after every acknowledged write? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.3 `identity` + +Audit question: Are node and edge identities stable across compaction, export, replication, and restore? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.4 `parallel_edges` + +Audit question: Can distinct parallel edges retain properties and trail identity end to end? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.5 `schema` + +Audit question: Is the schema open, closed, optional, inferred, or externally mapped? + +Current assessment: Start from `property graph via TinkerPop` and test actual constraints. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.6 `labels` + +Audit question: How are multiple labels represented and indexed? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.7 `adjacency_out` + +Audit question: How is outgoing adjacency located, encoded, split, cached, and updated? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.8 `adjacency_in` + +Audit question: Is incoming adjacency first-class, derived, replicated, or a fan-out operation? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.9 `supernodes` + +Audit question: How are million-to-billion-degree vertices represented and scheduled? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.10 `properties` + +Audit question: Are properties co-located, columnar, row-oriented, document-encoded, or remote? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.11 `compression` + +Audit question: Which topology, integer, string, null, and floating encodings are implemented? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.12 `checksums` + +Audit question: What integrity unit is verified on point reads and range reads? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.13 `snapshot` + +Audit question: What exact token pins graph data, schema, statistics, and indexes? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.14 `isolation` + +Audit question: Which anomalies are forbidden at the documented isolation level? + +Current assessment: Published summary: semantics inherit backend limitations; not generally serializable/atomic across rows. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.15 `durability` + +Audit question: What device/service acknowledgement is required before commit returns? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.16 `recovery` + +Audit question: What bounds restart work after a clean stop and a crash? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.17 `writer_fencing` + +Audit question: Can a stale writer acknowledge after failover or lease expiry? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.18 `partitioning` + +Audit question: What key determines placement and what happens to cross-partition edges? + +Current assessment: Published distribution summary: horizontal scale through chosen backend and stateless-ish JanusGraph servers. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.19 `rebalancing` + +Audit question: Can placement change online without changing logical identity? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.20 `replication` + +Audit question: Are replicas full, sharded, synchronous, asynchronous, or shared-storage readers? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.21 `optimizer` + +Audit question: Does the optimizer cost graph expansion, joins, network, cache, and remote requests? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.22 `statistics` + +Audit question: Which degree, correlation, path, and property statistics are persistent? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.23 `execution` + +Audit question: Is execution tuple-at-a-time, vectorized, factorized, compiled, matrix, or actor based? + +Current assessment: Expected family: JVM query execution near the application/server with backend round trips and caches. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.24 `recursion` + +Audit question: How are BFS, shortest paths, trails, simple paths, and arbitrary reachability executed? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.25 `parallelism` + +Audit question: How does the engine avoid skew and nested parallelism under mixed queries? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.26 `memory` + +Audit question: Are all variable allocations charged to bounded query and system budgets? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.27 `spill` + +Audit question: Which operators spill, in what format, and with what admission controls? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.28 `cancellation` + +Audit question: Can cancellation stop CPU, local I/O, remote I/O, retries, and prefetch? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.29 `cache` + +Audit question: What is cached, how is it keyed, admitted, pinned, and evicted? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.30 `cold_start` + +Audit question: What metadata and data round trips are required with empty caches? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.31 `object_requests` + +Audit question: Can a query issue one remote request per node, edge, or result row? + +Current assessment: Published object-store posture: possible indirectly through cloud backends, but not S3-native and pointer/request economics are unfavorable. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.32 `cost_admission` + +Audit question: Are request, byte, CPU, spill, and result limits enforced before work? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.33 `observability` + +Audit question: Can operators report rows, edges, bytes, requests, stalls, memory, and spill? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.34 `language` + +Audit question: Which GQL/Cypher/SQL-PGQ/Gremlin/SPARQL semantics are declared and tested? + +Current assessment: Declared surface: Gremlin. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.35 `updates` + +Audit question: Are DDL, insert, merge, update, detach delete, and constraints complete? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.36 `bulk_load` + +Audit question: Does bulk load preserve transactional and index invariants? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.37 `backup` + +Audit question: Is backup consistent, incremental, immutable, and restore-tested? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.38 `gc` + +Audit question: How are old snapshots, orphan objects, tombstones, and indexes reclaimed safely? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.39 `security` + +Audit question: Are authentication, authorization, encryption, audit, and tenant isolation in scope? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.40 `operations` + +Audit question: What compaction, upgrade, repair, verification, and capacity procedures exist? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +## 5. Benchmark contract for this engine + +Every case runs correctness first, then isolated latency, then closed-loop concurrency, then open-loop overload. Report median, p95, p99, p99.9, timeout/rejection rate, throughput, CPU-seconds, peak RSS, cache bytes, disk bytes, network bytes, remote requests, write amplification, and estimated monthly cost. + +Warm means all intended engine caches are populated without changing the query parameters. Hot means the exact working set is resident. Cold means process-local, engine, OS, NVMe, and remote cache state are explicitly reset or a fresh namespace is used. Those words are never inferred from repetition count. + +### 5.1 `point_pk` — primary-key node lookup with one projected property + +- Applicability to JanusGraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.2 `point_edge` — stable edge-ID lookup including endpoints and one property + +- Applicability to JanusGraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.3 `degree_1` — degree-one outgoing expansion + +- Applicability to JanusGraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.4 `degree_32` — small adjacency expansion around degree 32 + +- Applicability to JanusGraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.5 `degree_1k` — medium adjacency expansion around degree 1,024 + +- Applicability to JanusGraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.6 `supernode` — range-limited expansion of a ten-million-degree supernode + +- Applicability to JanusGraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.7 `expand_2` — selective two-hop expansion + +- Applicability to JanusGraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.8 `expand_3` — three-hop frontier expansion with duplicate control + +- Applicability to JanusGraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.9 `expand_into` — edge-existence/expand-into between already-bound endpoints + +- Applicability to JanusGraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.10 `multi_edge` — parallel-edge identity and property projection + +- Applicability to JanusGraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.11 `shortest` — bidirectional point-to-point unweighted shortest path + +- Applicability to JanusGraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.12 `weighted` — weighted shortest path with property access + +- Applicability to JanusGraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.13 `var_walk` — bounded variable-length walk + +- Applicability to JanusGraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.14 `trail` — DIFFERENT EDGES trail enumeration + +- Applicability to JanusGraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.15 `simple` — simple-path enumeration with explicit bound + +- Applicability to JanusGraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.16 `triangle` — triangle pattern with worst-case-sensitive join + +- Applicability to JanusGraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.17 `cycle4` — four-cycle pattern + +- Applicability to JanusGraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.18 `star_join` — high-fanout star pattern with property filters + +- Applicability to JanusGraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.19 `optional` — optional match preserving null/bag semantics + +- Applicability to JanusGraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.20 `aggregate` — grouped aggregate after traversal + +- Applicability to JanusGraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.21 `topk` — ordered top-k with late property materialization + +- Applicability to JanusGraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.22 `scan` — full projected property scan + +- Applicability to JanusGraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.23 `selective_scan` — zone/index-pruned selective property scan + +- Applicability to JanusGraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.24 `mixed` — concurrent short reads, complex reads, and updates + +- Applicability to JanusGraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.25 `ingest` — sustained transactional ingest with indexes enabled + +- Applicability to JanusGraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.26 `bulk` — initial bulk load including index/CSR build + +- Applicability to JanusGraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.27 `checkpoint` — checkpoint or compaction while readers remain active + +- Applicability to JanusGraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.28 `recovery` — crash recovery at bounded dirty-log size + +- Applicability to JanusGraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.29 `cold` — same query after clearing engine and OS/cache tiers + +- Applicability to JanusGraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.30 `remote` — same query with authoritative bytes only in object storage + +- Applicability to JanusGraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +## 6. Fairness controls + +- Same logical dataset and update stream; engine-native physical layouts are allowed and disclosed. +- Same result semantics; unsupported queries remain unsupported rather than rewritten into easier questions. +- Same durable acknowledgement class for write comparisons. +- Same number of physical cores and memory limit for self-hosted single-node tests. +- Same aggregate resources and replication fault tolerance for distributed tests. +- Officially recommended tuning may be applied before the freeze and is committed with rationale. +- Query-specific hints are allowed only when equivalent hints are offered to every engine and separately charted. +- Load/build/index time and bytes are first-class results. +- Cold, warm, and hot results are separate charts. +- Managed services use public configurations and cannot borrow hidden same-machine resource claims. +- Failed runs, OOMs, correctness mismatches, and timeouts stay in the dataset. +- Every chart links raw samples and the exact reproduction command. + +## 7. Likely advantages and limits + +The strongest known reason to choose this engine is tied to its family `storage-agnostic distributed graph layer`, its execution path `JVM query execution near the application/server with backend round trips and caches`, and its existing ecosystem. The strongest reason to reject it for zu's target is the gap between `possible indirectly through cloud backends, but not S3-native and pointer/request economics are unfavorable` and an S3-authoritative, request-budgeted, PB-scale graph service. + +Capacity statement: large distributed capacity is plausible through backends; supernodes and bulk load have documented limits. This is not converted into an edge-count claim without a physical byte model including IDs, both adjacency directions, properties, indexes, MVCC, WAL, replicas, and free space. + +Commercial statement: Apache-2.0. License cost, support cost, and unavailable enterprise capabilities remain visible in TCO and feature tables. + +## 8. Concrete lessons for zu + +1. Keep stable logical node and edge identity independent of row group, CSR slot, shard, and object range. +2. Store forward and reverse adjacency as immutable range-addressable tiles carrying edge IDs. +3. Feed queries adjacency batches and typed vectors; prohibit one storage call per logical element. +4. Use vectorized/factorized execution for property-heavy patterns and dedicated frontier operators for recursion. +5. Cost topology, properties, network, cache certainty, remote requests, and result materialization together. +6. Separate the local embedded profile from the object-authoritative distributed read profile. +7. Fence writers with monotonic epochs and make ambiguous commits reconcilable by transaction ID. +8. Pack small graph tiles into large immutable objects while retaining independent checksums and range offsets. +9. Keep the hot topology working set in RAM/NVMe; batch cold frontier misses into few remote rounds. +10. Admission-control remote requests and bytes so fixed-price plans have an enforceable upper bound. +11. Partition by workload-aware graph locality, and expose cross-partition semantics rather than hiding them. +12. Publish qualified wins per workload cell; never promise a universal tenfold advantage. + +## 9. Evidence gaps to close before publication + +- Exact current version and release date. +- Exact license text for the benchmarked artifact. +- Storage bytes per node/edge/property on all standard datasets. +- Stable-edge-ID and parallel-edge semantics. +- Isolation litmus results and commit acknowledgement point. +- Crash recovery time versus dirty WAL size. +- Supernode behavior and maximum tested degree. +- Cold-start metadata and request count. +- Distributed cross-partition query amplification. +- Peak memory under skew, cancellation, and overload. +- Background compaction/GC effect on tail latency. +- Full load/index/checkpoint/backup resource cost. +- Reproducible largest-scale result. +- Independent or audited benchmark evidence. + +## 10. Primary and official sources + +- [Architecture](https://docs.janusgraph.org/master/getting-started/architecture/) +- [Transactions](https://docs.janusgraph.org/basics/transactions/) +- [Technical limitations](https://docs.janusgraph.org/v1.1/advanced-topics/technical-limitations/) +- [Source repository](https://github.com/JanusGraph/janusgraph) +- [LDBC SNB Interactive and audited disclosures](https://ldbcouncil.org/benchmarks/snb/interactive/) +- [LDBC Graphalytics](https://ldbcouncil.org/benchmarks/graphalytics/) +- [SoK: The Faults in our Graph Benchmarks](https://arxiv.org/abs/2404.00766) + +## 11. Source-handling rules + +- Official documentation and source are evidence for implemented or declared behavior, not independent performance. +- A vendor benchmark is labeled vendor claim until the harness reproduces it. +- A peer-reviewed paper establishes only the version, configuration, and workload it evaluated. +- Search snippets, comparison sites, and unsourced blogs are discovery aids, not final evidence. +- Unknown is a valid result and creates a concrete experiment or source-inspection task. +- All web facts are rechecked at benchmark freeze because this corpus is current only through the research date. + +## 12. Reproduction record template + +- engine: `JanusGraph` +- version: `TBD at benchmark freeze` +- artifact digest: `TBD` +- source commit: `TBD or managed-service N/A` +- edition/license: `TBD` +- query language/version: `TBD` +- storage and durability mode: `TBD` +- cluster and replication: `TBD` +- CPU/RAM/NVMe/network: `TBD` +- OS/kernel/filesystem: `TBD` +- dataset URI and digest: `TBD` +- loader command and duration: `TBD` +- physical bytes by category: `TBD` +- tuning file: `TBD` +- query corpus commit: `TBD` +- raw result URI/digest: `TBD` +- profiler/trace URI: `TBD` +- correctness status: `TBD` +- reviewer and rerun date: `TBD` diff --git a/docs/research/engine-kuzu.md b/docs/research/engine-kuzu.md new file mode 100644 index 0000000..7dd4132 --- /dev/null +++ b/docs/research/engine-kuzu.md @@ -0,0 +1,885 @@ +# Kuzu (archived): 2026 deep technical and competitive specification + +Research cut: `2026-08-08` +Status: evidence-backed competitor audit; not a vendor endorsement +Family: `embedded analytical property graph` +Evidence convention: **Observed/official**, **Vendor claim**, **Research inference**, **Unknown**, **Qualification target**. + +## 1. Decision summary + +Retain for regression and lineage attribution; do not present it as an active competitor. + +This document answers two questions: what this engine actually proves in 2026, and what zu must build or measure to earn a defensible advantage. A missing public detail remains unknown; it is never silently filled with a favorable assumption. + +### Snapshot card + +- Lifecycle: archived 2025-10-10; historical baseline. +- Data model: schema-full property graph. +- Query surface: Cypher. +- Persistent layout: columnar disk storage and CSR adjacency/join indices. +- Execution: vectorized, factorized, multi-core query processor. +- Transactions: serializable ACID. +- Distribution: embedded single-node. +- Object-storage posture: not object-store-native. +- License/commercial boundary: MIT. +- Scale evidence: single-node only. +- Benchmark posture: Kuzu 0.9.0 is a reproducible historical baseline, not a current product. + +### Facts that materially affect comparison + +- F01 — The upstream repository is read-only. +- F02 — Kuzu introduced the factorized and CSR design now continued by LadybugDB. +- F03 — Its final line included full-text and vector extensions. +- F04 — Archived packages can still be benchmarked reproducibly if artifacts and compilers remain available. +- F05 — Security, compatibility, and support comparisons must label the lifecycle status. + +### Bottom-line fit against zu's target + +- Very-low latency: compare hot point and bounded traversal paths; never extrapolate from scans or algorithms. +- Very-low resources: charge resident set, page cache, remote cache, background services, and replicas. +- Distributed: distinguish read replication, partitioned capacity, distributed transactions, and elastic stateless compute. +- Fixed cost: no engine has fixed marginal cost by declaration; admission, batching, and capacity reservations create the bound. +- S3 authority: backups, imports, lake scans, and S3-native demand paging are four different architectures. +- PB / trillion-edge scale: require a capacity derivation plus a run at the largest affordable scale; marketing adjectives do not qualify. +- Tenfold win: can be a per-cell qualification result, never a universal statement across incomparable workloads. + +## 2. Product and ecosystem boundary + +The audited unit is **Kuzu (archived)** in the exact release, edition, deployment, and durability mode recorded by the harness. The family classification is **embedded analytical property graph**. The current lifecycle statement is: archived 2025-10-10; historical baseline. + +The harness must record binary/container digest, source commit when available, build flags, plugins, license/edition, language mode, storage mode, cluster topology, replication factor, durability settings, cache sizes, thread counts, NUMA policy, kernel, filesystem, cloud region, and all environment variables that affect execution. + +A managed service is not placed in a same-hardware chart. It receives a service-level result with provisioned units, region, public price, and observed provider metrics. A historical engine remains useful for regression but cannot support a claim about beating all current competitors. + +## 3. Architecture reconstruction + +### 3.1 Logical model + +Kuzu (archived) exposes schema-full property graph. The conformance corpus must test nulls, missing properties, labels/types, direction, self-loops, parallel edges, element equality, path equality, bag semantics, ordering, numeric overflow, string collation, temporal values, and schema evolution. + +### 3.2 Language and compiler + +The public query surface is Cypher. Syntax similarity is not semantic equivalence. Every supported construct needs a result oracle and an unsupported-feature declaration. + +### 3.3 Storage + +The best supported storage summary is: columnar disk storage and CSR adjacency/join indices. This statement must be refined from code, format documentation, or provider counters before using it in a performance explanation. + +### 3.4 Execution + +The best supported execution summary is: vectorized, factorized, multi-core query processor. The benchmark profiler must confirm which runtime and operators actually executed. + +### 3.5 Transactions and recovery + +The public contract is: serializable ACID. Exact acknowledgement, isolation anomalies, recovery bounds, and failover behavior remain separate qualification items. + +### 3.6 Distribution + +The deployment shape is: embedded single-node. Replication is not capacity sharding; sharding is not distributed ACID; stateless readers are not stateless storage. + +### 3.7 Object storage and cost + +The 2026 posture is: not object-store-native. The audit distinguishes authoritative live bytes, derived acceleration, backup, import/export, and spill. + +## 4. Forty-control deep audit + +### 4.1 `product_boundary` + +Audit question: What exact executable, edition, and storage mode is the system under test? + +Current assessment: Pin Kuzu (archived), lifecycle `archived 2025-10-10; historical baseline`, and its edition/mode. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.2 `authority` + +Audit question: Which durable component is the source of truth after every acknowledged write? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.3 `identity` + +Audit question: Are node and edge identities stable across compaction, export, replication, and restore? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.4 `parallel_edges` + +Audit question: Can distinct parallel edges retain properties and trail identity end to end? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.5 `schema` + +Audit question: Is the schema open, closed, optional, inferred, or externally mapped? + +Current assessment: Start from `schema-full property graph` and test actual constraints. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.6 `labels` + +Audit question: How are multiple labels represented and indexed? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.7 `adjacency_out` + +Audit question: How is outgoing adjacency located, encoded, split, cached, and updated? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.8 `adjacency_in` + +Audit question: Is incoming adjacency first-class, derived, replicated, or a fan-out operation? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.9 `supernodes` + +Audit question: How are million-to-billion-degree vertices represented and scheduled? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.10 `properties` + +Audit question: Are properties co-located, columnar, row-oriented, document-encoded, or remote? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.11 `compression` + +Audit question: Which topology, integer, string, null, and floating encodings are implemented? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.12 `checksums` + +Audit question: What integrity unit is verified on point reads and range reads? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.13 `snapshot` + +Audit question: What exact token pins graph data, schema, statistics, and indexes? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.14 `isolation` + +Audit question: Which anomalies are forbidden at the documented isolation level? + +Current assessment: Published summary: serializable ACID. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.15 `durability` + +Audit question: What device/service acknowledgement is required before commit returns? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.16 `recovery` + +Audit question: What bounds restart work after a clean stop and a crash? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.17 `writer_fencing` + +Audit question: Can a stale writer acknowledge after failover or lease expiry? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.18 `partitioning` + +Audit question: What key determines placement and what happens to cross-partition edges? + +Current assessment: Published distribution summary: embedded single-node. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.19 `rebalancing` + +Audit question: Can placement change online without changing logical identity? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.20 `replication` + +Audit question: Are replicas full, sharded, synchronous, asynchronous, or shared-storage readers? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.21 `optimizer` + +Audit question: Does the optimizer cost graph expansion, joins, network, cache, and remote requests? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.22 `statistics` + +Audit question: Which degree, correlation, path, and property statistics are persistent? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.23 `execution` + +Audit question: Is execution tuple-at-a-time, vectorized, factorized, compiled, matrix, or actor based? + +Current assessment: Expected family: vectorized, factorized, multi-core query processor. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.24 `recursion` + +Audit question: How are BFS, shortest paths, trails, simple paths, and arbitrary reachability executed? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.25 `parallelism` + +Audit question: How does the engine avoid skew and nested parallelism under mixed queries? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.26 `memory` + +Audit question: Are all variable allocations charged to bounded query and system budgets? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.27 `spill` + +Audit question: Which operators spill, in what format, and with what admission controls? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.28 `cancellation` + +Audit question: Can cancellation stop CPU, local I/O, remote I/O, retries, and prefetch? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.29 `cache` + +Audit question: What is cached, how is it keyed, admitted, pinned, and evicted? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.30 `cold_start` + +Audit question: What metadata and data round trips are required with empty caches? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.31 `object_requests` + +Audit question: Can a query issue one remote request per node, edge, or result row? + +Current assessment: Published object-store posture: not object-store-native. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.32 `cost_admission` + +Audit question: Are request, byte, CPU, spill, and result limits enforced before work? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.33 `observability` + +Audit question: Can operators report rows, edges, bytes, requests, stalls, memory, and spill? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.34 `language` + +Audit question: Which GQL/Cypher/SQL-PGQ/Gremlin/SPARQL semantics are declared and tested? + +Current assessment: Declared surface: Cypher. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.35 `updates` + +Audit question: Are DDL, insert, merge, update, detach delete, and constraints complete? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.36 `bulk_load` + +Audit question: Does bulk load preserve transactional and index invariants? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.37 `backup` + +Audit question: Is backup consistent, incremental, immutable, and restore-tested? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.38 `gc` + +Audit question: How are old snapshots, orphan objects, tombstones, and indexes reclaimed safely? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.39 `security` + +Audit question: Are authentication, authorization, encryption, audit, and tenant isolation in scope? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.40 `operations` + +Audit question: What compaction, upgrade, repair, verification, and capacity procedures exist? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +## 5. Benchmark contract for this engine + +Every case runs correctness first, then isolated latency, then closed-loop concurrency, then open-loop overload. Report median, p95, p99, p99.9, timeout/rejection rate, throughput, CPU-seconds, peak RSS, cache bytes, disk bytes, network bytes, remote requests, write amplification, and estimated monthly cost. + +Warm means all intended engine caches are populated without changing the query parameters. Hot means the exact working set is resident. Cold means process-local, engine, OS, NVMe, and remote cache state are explicitly reset or a fresh namespace is used. Those words are never inferred from repetition count. + +### 5.1 `point_pk` — primary-key node lookup with one projected property + +- Applicability to Kuzu (archived): required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.2 `point_edge` — stable edge-ID lookup including endpoints and one property + +- Applicability to Kuzu (archived): required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.3 `degree_1` — degree-one outgoing expansion + +- Applicability to Kuzu (archived): required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.4 `degree_32` — small adjacency expansion around degree 32 + +- Applicability to Kuzu (archived): required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.5 `degree_1k` — medium adjacency expansion around degree 1,024 + +- Applicability to Kuzu (archived): required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.6 `supernode` — range-limited expansion of a ten-million-degree supernode + +- Applicability to Kuzu (archived): required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.7 `expand_2` — selective two-hop expansion + +- Applicability to Kuzu (archived): required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.8 `expand_3` — three-hop frontier expansion with duplicate control + +- Applicability to Kuzu (archived): required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.9 `expand_into` — edge-existence/expand-into between already-bound endpoints + +- Applicability to Kuzu (archived): required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.10 `multi_edge` — parallel-edge identity and property projection + +- Applicability to Kuzu (archived): required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.11 `shortest` — bidirectional point-to-point unweighted shortest path + +- Applicability to Kuzu (archived): required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.12 `weighted` — weighted shortest path with property access + +- Applicability to Kuzu (archived): required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.13 `var_walk` — bounded variable-length walk + +- Applicability to Kuzu (archived): required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.14 `trail` — DIFFERENT EDGES trail enumeration + +- Applicability to Kuzu (archived): required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.15 `simple` — simple-path enumeration with explicit bound + +- Applicability to Kuzu (archived): required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.16 `triangle` — triangle pattern with worst-case-sensitive join + +- Applicability to Kuzu (archived): required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.17 `cycle4` — four-cycle pattern + +- Applicability to Kuzu (archived): required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.18 `star_join` — high-fanout star pattern with property filters + +- Applicability to Kuzu (archived): required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.19 `optional` — optional match preserving null/bag semantics + +- Applicability to Kuzu (archived): required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.20 `aggregate` — grouped aggregate after traversal + +- Applicability to Kuzu (archived): required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.21 `topk` — ordered top-k with late property materialization + +- Applicability to Kuzu (archived): required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.22 `scan` — full projected property scan + +- Applicability to Kuzu (archived): required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.23 `selective_scan` — zone/index-pruned selective property scan + +- Applicability to Kuzu (archived): required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.24 `mixed` — concurrent short reads, complex reads, and updates + +- Applicability to Kuzu (archived): required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.25 `ingest` — sustained transactional ingest with indexes enabled + +- Applicability to Kuzu (archived): required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.26 `bulk` — initial bulk load including index/CSR build + +- Applicability to Kuzu (archived): required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.27 `checkpoint` — checkpoint or compaction while readers remain active + +- Applicability to Kuzu (archived): required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.28 `recovery` — crash recovery at bounded dirty-log size + +- Applicability to Kuzu (archived): required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.29 `cold` — same query after clearing engine and OS/cache tiers + +- Applicability to Kuzu (archived): required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.30 `remote` — same query with authoritative bytes only in object storage + +- Applicability to Kuzu (archived): required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +## 6. Fairness controls + +- Same logical dataset and update stream; engine-native physical layouts are allowed and disclosed. +- Same result semantics; unsupported queries remain unsupported rather than rewritten into easier questions. +- Same durable acknowledgement class for write comparisons. +- Same number of physical cores and memory limit for self-hosted single-node tests. +- Same aggregate resources and replication fault tolerance for distributed tests. +- Officially recommended tuning may be applied before the freeze and is committed with rationale. +- Query-specific hints are allowed only when equivalent hints are offered to every engine and separately charted. +- Load/build/index time and bytes are first-class results. +- Cold, warm, and hot results are separate charts. +- Managed services use public configurations and cannot borrow hidden same-machine resource claims. +- Failed runs, OOMs, correctness mismatches, and timeouts stay in the dataset. +- Every chart links raw samples and the exact reproduction command. + +## 7. Likely advantages and limits + +The strongest known reason to choose this engine is tied to its family `embedded analytical property graph`, its execution path `vectorized, factorized, multi-core query processor`, and its existing ecosystem. The strongest reason to reject it for zu's target is the gap between `not object-store-native` and an S3-authoritative, request-budgeted, PB-scale graph service. + +Capacity statement: single-node only. This is not converted into an edge-count claim without a physical byte model including IDs, both adjacency directions, properties, indexes, MVCC, WAL, replicas, and free space. + +Commercial statement: MIT. License cost, support cost, and unavailable enterprise capabilities remain visible in TCO and feature tables. + +## 8. Concrete lessons for zu + +1. Keep stable logical node and edge identity independent of row group, CSR slot, shard, and object range. +2. Store forward and reverse adjacency as immutable range-addressable tiles carrying edge IDs. +3. Feed queries adjacency batches and typed vectors; prohibit one storage call per logical element. +4. Use vectorized/factorized execution for property-heavy patterns and dedicated frontier operators for recursion. +5. Cost topology, properties, network, cache certainty, remote requests, and result materialization together. +6. Separate the local embedded profile from the object-authoritative distributed read profile. +7. Fence writers with monotonic epochs and make ambiguous commits reconcilable by transaction ID. +8. Pack small graph tiles into large immutable objects while retaining independent checksums and range offsets. +9. Keep the hot topology working set in RAM/NVMe; batch cold frontier misses into few remote rounds. +10. Admission-control remote requests and bytes so fixed-price plans have an enforceable upper bound. +11. Partition by workload-aware graph locality, and expose cross-partition semantics rather than hiding them. +12. Publish qualified wins per workload cell; never promise a universal tenfold advantage. + +## 9. Evidence gaps to close before publication + +- Exact current version and release date. +- Exact license text for the benchmarked artifact. +- Storage bytes per node/edge/property on all standard datasets. +- Stable-edge-ID and parallel-edge semantics. +- Isolation litmus results and commit acknowledgement point. +- Crash recovery time versus dirty WAL size. +- Supernode behavior and maximum tested degree. +- Cold-start metadata and request count. +- Distributed cross-partition query amplification. +- Peak memory under skew, cancellation, and overload. +- Background compaction/GC effect on tail latency. +- Full load/index/checkpoint/backup resource cost. +- Reproducible largest-scale result. +- Independent or audited benchmark evidence. + +## 10. Primary and official sources + +- [Archived repository](https://github.com/kuzudb/kuzu) +- [Kuzu system paper](https://vldb.org/cidrdb/papers/2023/p48-jin.pdf) +- [Release archive](https://github.com/kuzudb/kuzu/releases) +- [LDBC SNB Interactive and audited disclosures](https://ldbcouncil.org/benchmarks/snb/interactive/) +- [LDBC Graphalytics](https://ldbcouncil.org/benchmarks/graphalytics/) +- [SoK: The Faults in our Graph Benchmarks](https://arxiv.org/abs/2404.00766) + +## 11. Source-handling rules + +- Official documentation and source are evidence for implemented or declared behavior, not independent performance. +- A vendor benchmark is labeled vendor claim until the harness reproduces it. +- A peer-reviewed paper establishes only the version, configuration, and workload it evaluated. +- Search snippets, comparison sites, and unsourced blogs are discovery aids, not final evidence. +- Unknown is a valid result and creates a concrete experiment or source-inspection task. +- All web facts are rechecked at benchmark freeze because this corpus is current only through the research date. + +## 12. Reproduction record template + +- engine: `Kuzu (archived)` +- version: `TBD at benchmark freeze` +- artifact digest: `TBD` +- source commit: `TBD or managed-service N/A` +- edition/license: `TBD` +- query language/version: `TBD` +- storage and durability mode: `TBD` +- cluster and replication: `TBD` +- CPU/RAM/NVMe/network: `TBD` +- OS/kernel/filesystem: `TBD` +- dataset URI and digest: `TBD` +- loader command and duration: `TBD` +- physical bytes by category: `TBD` +- tuning file: `TBD` +- query corpus commit: `TBD` +- raw result URI/digest: `TBD` +- profiler/trace URI: `TBD` +- correctness status: `TBD` +- reviewer and rerun date: `TBD` diff --git a/docs/research/engine-ladybugdb.md b/docs/research/engine-ladybugdb.md new file mode 100644 index 0000000..824e85a --- /dev/null +++ b/docs/research/engine-ladybugdb.md @@ -0,0 +1,885 @@ +# LadybugDB: 2026 deep technical and competitive specification + +Research cut: `2026-08-08` +Status: evidence-backed competitor audit; not a vendor endorsement +Family: `embedded analytical property graph` +Evidence convention: **Observed/official**, **Vendor claim**, **Research inference**, **Unknown**, **Qualification target**. + +## 1. Decision summary + +This is zu's closest embedded architectural competitor and the primary fair same-machine benchmark. + +This document answers two questions: what this engine actually proves in 2026, and what zu must build or measure to earn a defensible advantage. A missing public detail remains unknown; it is never silently filled with a favorable assumption. + +### Snapshot card + +- Lifecycle: active successor fork in 2026. +- Data model: schema-full property graph. +- Query surface: Cypher. +- Persistent layout: columnar disk storage with columnar CSR adjacency and join indices. +- Execution: vectorized and factorized processing, specialized joins, multi-core parallelism. +- Transactions: serializable ACID according to official documentation. +- Distribution: embedded single-node, in-process; no native distributed transaction layer. +- Object-storage posture: not object-store-native, though Parquet/Arrow/DuckDB interoperability is central. +- License/commercial boundary: MIT. +- Scale evidence: large single-node analytical graphs; PB/distributed claims are outside the current product shape. +- Benchmark posture: must run Kuzu-derived LDBC and microbenchmarks from source with pinned commit. + +### Facts that materially affect comparison + +- F01 — Ladybug continues Kuzu's columnar CSR and factorized-execution lineage. +- F02 — The engine is designed for join-heavy analytical patterns rather than networked OLTP serving. +- F03 — Interoperability includes Parquet, Arrow, and DuckDB-oriented workflows. +- F04 — Multi-core execution changes the fairness rules: thread count and NUMA placement must be fixed. +- F05 — Fork freshness invalidates claims that the Kuzu lane is empty. + +### Bottom-line fit against zu's target + +- Very-low latency: compare hot point and bounded traversal paths; never extrapolate from scans or algorithms. +- Very-low resources: charge resident set, page cache, remote cache, background services, and replicas. +- Distributed: distinguish read replication, partitioned capacity, distributed transactions, and elastic stateless compute. +- Fixed cost: no engine has fixed marginal cost by declaration; admission, batching, and capacity reservations create the bound. +- S3 authority: backups, imports, lake scans, and S3-native demand paging are four different architectures. +- PB / trillion-edge scale: require a capacity derivation plus a run at the largest affordable scale; marketing adjectives do not qualify. +- Tenfold win: can be a per-cell qualification result, never a universal statement across incomparable workloads. + +## 2. Product and ecosystem boundary + +The audited unit is **LadybugDB** in the exact release, edition, deployment, and durability mode recorded by the harness. The family classification is **embedded analytical property graph**. The current lifecycle statement is: active successor fork in 2026. + +The harness must record binary/container digest, source commit when available, build flags, plugins, license/edition, language mode, storage mode, cluster topology, replication factor, durability settings, cache sizes, thread counts, NUMA policy, kernel, filesystem, cloud region, and all environment variables that affect execution. + +A managed service is not placed in a same-hardware chart. It receives a service-level result with provisioned units, region, public price, and observed provider metrics. A historical engine remains useful for regression but cannot support a claim about beating all current competitors. + +## 3. Architecture reconstruction + +### 3.1 Logical model + +LadybugDB exposes schema-full property graph. The conformance corpus must test nulls, missing properties, labels/types, direction, self-loops, parallel edges, element equality, path equality, bag semantics, ordering, numeric overflow, string collation, temporal values, and schema evolution. + +### 3.2 Language and compiler + +The public query surface is Cypher. Syntax similarity is not semantic equivalence. Every supported construct needs a result oracle and an unsupported-feature declaration. + +### 3.3 Storage + +The best supported storage summary is: columnar disk storage with columnar CSR adjacency and join indices. This statement must be refined from code, format documentation, or provider counters before using it in a performance explanation. + +### 3.4 Execution + +The best supported execution summary is: vectorized and factorized processing, specialized joins, multi-core parallelism. The benchmark profiler must confirm which runtime and operators actually executed. + +### 3.5 Transactions and recovery + +The public contract is: serializable ACID according to official documentation. Exact acknowledgement, isolation anomalies, recovery bounds, and failover behavior remain separate qualification items. + +### 3.6 Distribution + +The deployment shape is: embedded single-node, in-process; no native distributed transaction layer. Replication is not capacity sharding; sharding is not distributed ACID; stateless readers are not stateless storage. + +### 3.7 Object storage and cost + +The 2026 posture is: not object-store-native, though Parquet/Arrow/DuckDB interoperability is central. The audit distinguishes authoritative live bytes, derived acceleration, backup, import/export, and spill. + +## 4. Forty-control deep audit + +### 4.1 `product_boundary` + +Audit question: What exact executable, edition, and storage mode is the system under test? + +Current assessment: Pin LadybugDB, lifecycle `active successor fork in 2026`, and its edition/mode. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.2 `authority` + +Audit question: Which durable component is the source of truth after every acknowledged write? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.3 `identity` + +Audit question: Are node and edge identities stable across compaction, export, replication, and restore? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.4 `parallel_edges` + +Audit question: Can distinct parallel edges retain properties and trail identity end to end? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.5 `schema` + +Audit question: Is the schema open, closed, optional, inferred, or externally mapped? + +Current assessment: Start from `schema-full property graph` and test actual constraints. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.6 `labels` + +Audit question: How are multiple labels represented and indexed? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.7 `adjacency_out` + +Audit question: How is outgoing adjacency located, encoded, split, cached, and updated? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.8 `adjacency_in` + +Audit question: Is incoming adjacency first-class, derived, replicated, or a fan-out operation? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.9 `supernodes` + +Audit question: How are million-to-billion-degree vertices represented and scheduled? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.10 `properties` + +Audit question: Are properties co-located, columnar, row-oriented, document-encoded, or remote? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.11 `compression` + +Audit question: Which topology, integer, string, null, and floating encodings are implemented? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.12 `checksums` + +Audit question: What integrity unit is verified on point reads and range reads? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.13 `snapshot` + +Audit question: What exact token pins graph data, schema, statistics, and indexes? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.14 `isolation` + +Audit question: Which anomalies are forbidden at the documented isolation level? + +Current assessment: Published summary: serializable ACID according to official documentation. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.15 `durability` + +Audit question: What device/service acknowledgement is required before commit returns? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.16 `recovery` + +Audit question: What bounds restart work after a clean stop and a crash? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.17 `writer_fencing` + +Audit question: Can a stale writer acknowledge after failover or lease expiry? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.18 `partitioning` + +Audit question: What key determines placement and what happens to cross-partition edges? + +Current assessment: Published distribution summary: embedded single-node, in-process; no native distributed transaction layer. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.19 `rebalancing` + +Audit question: Can placement change online without changing logical identity? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.20 `replication` + +Audit question: Are replicas full, sharded, synchronous, asynchronous, or shared-storage readers? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.21 `optimizer` + +Audit question: Does the optimizer cost graph expansion, joins, network, cache, and remote requests? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.22 `statistics` + +Audit question: Which degree, correlation, path, and property statistics are persistent? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.23 `execution` + +Audit question: Is execution tuple-at-a-time, vectorized, factorized, compiled, matrix, or actor based? + +Current assessment: Expected family: vectorized and factorized processing, specialized joins, multi-core parallelism. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.24 `recursion` + +Audit question: How are BFS, shortest paths, trails, simple paths, and arbitrary reachability executed? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.25 `parallelism` + +Audit question: How does the engine avoid skew and nested parallelism under mixed queries? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.26 `memory` + +Audit question: Are all variable allocations charged to bounded query and system budgets? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.27 `spill` + +Audit question: Which operators spill, in what format, and with what admission controls? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.28 `cancellation` + +Audit question: Can cancellation stop CPU, local I/O, remote I/O, retries, and prefetch? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.29 `cache` + +Audit question: What is cached, how is it keyed, admitted, pinned, and evicted? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.30 `cold_start` + +Audit question: What metadata and data round trips are required with empty caches? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.31 `object_requests` + +Audit question: Can a query issue one remote request per node, edge, or result row? + +Current assessment: Published object-store posture: not object-store-native, though Parquet/Arrow/DuckDB interoperability is central. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.32 `cost_admission` + +Audit question: Are request, byte, CPU, spill, and result limits enforced before work? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.33 `observability` + +Audit question: Can operators report rows, edges, bytes, requests, stalls, memory, and spill? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.34 `language` + +Audit question: Which GQL/Cypher/SQL-PGQ/Gremlin/SPARQL semantics are declared and tested? + +Current assessment: Declared surface: Cypher. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.35 `updates` + +Audit question: Are DDL, insert, merge, update, detach delete, and constraints complete? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.36 `bulk_load` + +Audit question: Does bulk load preserve transactional and index invariants? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.37 `backup` + +Audit question: Is backup consistent, incremental, immutable, and restore-tested? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.38 `gc` + +Audit question: How are old snapshots, orphan objects, tombstones, and indexes reclaimed safely? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.39 `security` + +Audit question: Are authentication, authorization, encryption, audit, and tenant isolation in scope? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.40 `operations` + +Audit question: What compaction, upgrade, repair, verification, and capacity procedures exist? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +## 5. Benchmark contract for this engine + +Every case runs correctness first, then isolated latency, then closed-loop concurrency, then open-loop overload. Report median, p95, p99, p99.9, timeout/rejection rate, throughput, CPU-seconds, peak RSS, cache bytes, disk bytes, network bytes, remote requests, write amplification, and estimated monthly cost. + +Warm means all intended engine caches are populated without changing the query parameters. Hot means the exact working set is resident. Cold means process-local, engine, OS, NVMe, and remote cache state are explicitly reset or a fresh namespace is used. Those words are never inferred from repetition count. + +### 5.1 `point_pk` — primary-key node lookup with one projected property + +- Applicability to LadybugDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.2 `point_edge` — stable edge-ID lookup including endpoints and one property + +- Applicability to LadybugDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.3 `degree_1` — degree-one outgoing expansion + +- Applicability to LadybugDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.4 `degree_32` — small adjacency expansion around degree 32 + +- Applicability to LadybugDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.5 `degree_1k` — medium adjacency expansion around degree 1,024 + +- Applicability to LadybugDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.6 `supernode` — range-limited expansion of a ten-million-degree supernode + +- Applicability to LadybugDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.7 `expand_2` — selective two-hop expansion + +- Applicability to LadybugDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.8 `expand_3` — three-hop frontier expansion with duplicate control + +- Applicability to LadybugDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.9 `expand_into` — edge-existence/expand-into between already-bound endpoints + +- Applicability to LadybugDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.10 `multi_edge` — parallel-edge identity and property projection + +- Applicability to LadybugDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.11 `shortest` — bidirectional point-to-point unweighted shortest path + +- Applicability to LadybugDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.12 `weighted` — weighted shortest path with property access + +- Applicability to LadybugDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.13 `var_walk` — bounded variable-length walk + +- Applicability to LadybugDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.14 `trail` — DIFFERENT EDGES trail enumeration + +- Applicability to LadybugDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.15 `simple` — simple-path enumeration with explicit bound + +- Applicability to LadybugDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.16 `triangle` — triangle pattern with worst-case-sensitive join + +- Applicability to LadybugDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.17 `cycle4` — four-cycle pattern + +- Applicability to LadybugDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.18 `star_join` — high-fanout star pattern with property filters + +- Applicability to LadybugDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.19 `optional` — optional match preserving null/bag semantics + +- Applicability to LadybugDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.20 `aggregate` — grouped aggregate after traversal + +- Applicability to LadybugDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.21 `topk` — ordered top-k with late property materialization + +- Applicability to LadybugDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.22 `scan` — full projected property scan + +- Applicability to LadybugDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.23 `selective_scan` — zone/index-pruned selective property scan + +- Applicability to LadybugDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.24 `mixed` — concurrent short reads, complex reads, and updates + +- Applicability to LadybugDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.25 `ingest` — sustained transactional ingest with indexes enabled + +- Applicability to LadybugDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.26 `bulk` — initial bulk load including index/CSR build + +- Applicability to LadybugDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.27 `checkpoint` — checkpoint or compaction while readers remain active + +- Applicability to LadybugDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.28 `recovery` — crash recovery at bounded dirty-log size + +- Applicability to LadybugDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.29 `cold` — same query after clearing engine and OS/cache tiers + +- Applicability to LadybugDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.30 `remote` — same query with authoritative bytes only in object storage + +- Applicability to LadybugDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +## 6. Fairness controls + +- Same logical dataset and update stream; engine-native physical layouts are allowed and disclosed. +- Same result semantics; unsupported queries remain unsupported rather than rewritten into easier questions. +- Same durable acknowledgement class for write comparisons. +- Same number of physical cores and memory limit for self-hosted single-node tests. +- Same aggregate resources and replication fault tolerance for distributed tests. +- Officially recommended tuning may be applied before the freeze and is committed with rationale. +- Query-specific hints are allowed only when equivalent hints are offered to every engine and separately charted. +- Load/build/index time and bytes are first-class results. +- Cold, warm, and hot results are separate charts. +- Managed services use public configurations and cannot borrow hidden same-machine resource claims. +- Failed runs, OOMs, correctness mismatches, and timeouts stay in the dataset. +- Every chart links raw samples and the exact reproduction command. + +## 7. Likely advantages and limits + +The strongest known reason to choose this engine is tied to its family `embedded analytical property graph`, its execution path `vectorized and factorized processing, specialized joins, multi-core parallelism`, and its existing ecosystem. The strongest reason to reject it for zu's target is the gap between `not object-store-native, though Parquet/Arrow/DuckDB interoperability is central` and an S3-authoritative, request-budgeted, PB-scale graph service. + +Capacity statement: large single-node analytical graphs; PB/distributed claims are outside the current product shape. This is not converted into an edge-count claim without a physical byte model including IDs, both adjacency directions, properties, indexes, MVCC, WAL, replicas, and free space. + +Commercial statement: MIT. License cost, support cost, and unavailable enterprise capabilities remain visible in TCO and feature tables. + +## 8. Concrete lessons for zu + +1. Keep stable logical node and edge identity independent of row group, CSR slot, shard, and object range. +2. Store forward and reverse adjacency as immutable range-addressable tiles carrying edge IDs. +3. Feed queries adjacency batches and typed vectors; prohibit one storage call per logical element. +4. Use vectorized/factorized execution for property-heavy patterns and dedicated frontier operators for recursion. +5. Cost topology, properties, network, cache certainty, remote requests, and result materialization together. +6. Separate the local embedded profile from the object-authoritative distributed read profile. +7. Fence writers with monotonic epochs and make ambiguous commits reconcilable by transaction ID. +8. Pack small graph tiles into large immutable objects while retaining independent checksums and range offsets. +9. Keep the hot topology working set in RAM/NVMe; batch cold frontier misses into few remote rounds. +10. Admission-control remote requests and bytes so fixed-price plans have an enforceable upper bound. +11. Partition by workload-aware graph locality, and expose cross-partition semantics rather than hiding them. +12. Publish qualified wins per workload cell; never promise a universal tenfold advantage. + +## 9. Evidence gaps to close before publication + +- Exact current version and release date. +- Exact license text for the benchmarked artifact. +- Storage bytes per node/edge/property on all standard datasets. +- Stable-edge-ID and parallel-edge semantics. +- Isolation litmus results and commit acknowledgement point. +- Crash recovery time versus dirty WAL size. +- Supernode behavior and maximum tested degree. +- Cold-start metadata and request count. +- Distributed cross-partition query amplification. +- Peak memory under skew, cancellation, and overload. +- Background compaction/GC effect on tail latency. +- Full load/index/checkpoint/backup resource cost. +- Reproducible largest-scale result. +- Independent or audited benchmark evidence. + +## 10. Primary and official sources + +- [Official documentation](https://docs.ladybugdb.com/) +- [Installation and releases](https://docs.ladybugdb.com/installation/) +- [Source repository](https://github.com/LadybugDB/ladybug) +- [LDBC SNB Interactive and audited disclosures](https://ldbcouncil.org/benchmarks/snb/interactive/) +- [LDBC Graphalytics](https://ldbcouncil.org/benchmarks/graphalytics/) +- [SoK: The Faults in our Graph Benchmarks](https://arxiv.org/abs/2404.00766) + +## 11. Source-handling rules + +- Official documentation and source are evidence for implemented or declared behavior, not independent performance. +- A vendor benchmark is labeled vendor claim until the harness reproduces it. +- A peer-reviewed paper establishes only the version, configuration, and workload it evaluated. +- Search snippets, comparison sites, and unsourced blogs are discovery aids, not final evidence. +- Unknown is a valid result and creates a concrete experiment or source-inspection task. +- All web facts are rechecked at benchmark freeze because this corpus is current only through the research date. + +## 12. Reproduction record template + +- engine: `LadybugDB` +- version: `TBD at benchmark freeze` +- artifact digest: `TBD` +- source commit: `TBD or managed-service N/A` +- edition/license: `TBD` +- query language/version: `TBD` +- storage and durability mode: `TBD` +- cluster and replication: `TBD` +- CPU/RAM/NVMe/network: `TBD` +- OS/kernel/filesystem: `TBD` +- dataset URI and digest: `TBD` +- loader command and duration: `TBD` +- physical bytes by category: `TBD` +- tuning file: `TBD` +- query corpus commit: `TBD` +- raw result URI/digest: `TBD` +- profiler/trace URI: `TBD` +- correctness status: `TBD` +- reviewer and rerun date: `TBD` diff --git a/docs/research/engine-memgraph.md b/docs/research/engine-memgraph.md new file mode 100644 index 0000000..ac04968 --- /dev/null +++ b/docs/research/engine-memgraph.md @@ -0,0 +1,886 @@ +# Memgraph: 2026 deep technical and competitive specification + +Research cut: `2026-08-08` +Status: evidence-backed competitor audit; not a vendor endorsement +Family: `in-memory operational property graph` +Evidence convention: **Observed/official**, **Vendor claim**, **Research inference**, **Unknown**, **Qualification target**. + +## 1. Decision summary + +Memgraph is the low-latency mutable baseline; zu must win resource efficiency without comparing unlike durability modes. + +This document answers two questions: what this engine actually proves in 2026, and what zu must build or measure to earn a defensible advantage. A missing public detail remains unknown; it is never silently filled with a favorable assumption. + +### Snapshot card + +- Lifecycle: active. +- Data model: property graph. +- Query surface: Cypher-compatible language and procedures. +- Persistent layout: in-memory transactional/analytical modes; RocksDB-backed on-disk transactional mode. +- Execution: C++ execution with built-in traversals, query modules, triggers, and parallel runtime work. +- Transactions: snapshot isolation by default; durability differs materially across storage modes. +- Distribution: leader/replica high availability and read scaling; not a general sharded PB store. +- Object-storage posture: not object-store-native. +- License/commercial boundary: Business Source License/community plus commercial features; pin exact edition. +- Scale evidence: RAM-bound mode targets low latency; on-disk mode broadens capacity with different behavior. +- Benchmark posture: benchmark every storage mode separately and include WAL/snapshot settings. + +### Facts that materially affect comparison + +- F01 — Transactional in-memory mode uses deltas plus WAL and snapshots. +- F02 — Analytical in-memory mode relaxes guarantees and therefore cannot be mixed into ACID charts. +- F03 — On-disk transactional mode serializes graph records into RocksDB. +- F04 — Replication supports synchronous, timeout, and asynchronous behavior with different commit semantics. +- F05 — Dynamic algorithms and triggers broaden workload scope beyond plain query execution. + +### Bottom-line fit against zu's target + +- Very-low latency: compare hot point and bounded traversal paths; never extrapolate from scans or algorithms. +- Very-low resources: charge resident set, page cache, remote cache, background services, and replicas. +- Distributed: distinguish read replication, partitioned capacity, distributed transactions, and elastic stateless compute. +- Fixed cost: no engine has fixed marginal cost by declaration; admission, batching, and capacity reservations create the bound. +- S3 authority: backups, imports, lake scans, and S3-native demand paging are four different architectures. +- PB / trillion-edge scale: require a capacity derivation plus a run at the largest affordable scale; marketing adjectives do not qualify. +- Tenfold win: can be a per-cell qualification result, never a universal statement across incomparable workloads. + +## 2. Product and ecosystem boundary + +The audited unit is **Memgraph** in the exact release, edition, deployment, and durability mode recorded by the harness. The family classification is **in-memory operational property graph**. The current lifecycle statement is: active. + +The harness must record binary/container digest, source commit when available, build flags, plugins, license/edition, language mode, storage mode, cluster topology, replication factor, durability settings, cache sizes, thread counts, NUMA policy, kernel, filesystem, cloud region, and all environment variables that affect execution. + +A managed service is not placed in a same-hardware chart. It receives a service-level result with provisioned units, region, public price, and observed provider metrics. A historical engine remains useful for regression but cannot support a claim about beating all current competitors. + +## 3. Architecture reconstruction + +### 3.1 Logical model + +Memgraph exposes property graph. The conformance corpus must test nulls, missing properties, labels/types, direction, self-loops, parallel edges, element equality, path equality, bag semantics, ordering, numeric overflow, string collation, temporal values, and schema evolution. + +### 3.2 Language and compiler + +The public query surface is Cypher-compatible language and procedures. Syntax similarity is not semantic equivalence. Every supported construct needs a result oracle and an unsupported-feature declaration. + +### 3.3 Storage + +The best supported storage summary is: in-memory transactional/analytical modes; RocksDB-backed on-disk transactional mode. This statement must be refined from code, format documentation, or provider counters before using it in a performance explanation. + +### 3.4 Execution + +The best supported execution summary is: C++ execution with built-in traversals, query modules, triggers, and parallel runtime work. The benchmark profiler must confirm which runtime and operators actually executed. + +### 3.5 Transactions and recovery + +The public contract is: snapshot isolation by default; durability differs materially across storage modes. Exact acknowledgement, isolation anomalies, recovery bounds, and failover behavior remain separate qualification items. + +### 3.6 Distribution + +The deployment shape is: leader/replica high availability and read scaling; not a general sharded PB store. Replication is not capacity sharding; sharding is not distributed ACID; stateless readers are not stateless storage. + +### 3.7 Object storage and cost + +The 2026 posture is: not object-store-native. The audit distinguishes authoritative live bytes, derived acceleration, backup, import/export, and spill. + +## 4. Forty-control deep audit + +### 4.1 `product_boundary` + +Audit question: What exact executable, edition, and storage mode is the system under test? + +Current assessment: Pin Memgraph, lifecycle `active`, and its edition/mode. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.2 `authority` + +Audit question: Which durable component is the source of truth after every acknowledged write? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.3 `identity` + +Audit question: Are node and edge identities stable across compaction, export, replication, and restore? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.4 `parallel_edges` + +Audit question: Can distinct parallel edges retain properties and trail identity end to end? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.5 `schema` + +Audit question: Is the schema open, closed, optional, inferred, or externally mapped? + +Current assessment: Start from `property graph` and test actual constraints. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.6 `labels` + +Audit question: How are multiple labels represented and indexed? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.7 `adjacency_out` + +Audit question: How is outgoing adjacency located, encoded, split, cached, and updated? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.8 `adjacency_in` + +Audit question: Is incoming adjacency first-class, derived, replicated, or a fan-out operation? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.9 `supernodes` + +Audit question: How are million-to-billion-degree vertices represented and scheduled? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.10 `properties` + +Audit question: Are properties co-located, columnar, row-oriented, document-encoded, or remote? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.11 `compression` + +Audit question: Which topology, integer, string, null, and floating encodings are implemented? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.12 `checksums` + +Audit question: What integrity unit is verified on point reads and range reads? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.13 `snapshot` + +Audit question: What exact token pins graph data, schema, statistics, and indexes? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.14 `isolation` + +Audit question: Which anomalies are forbidden at the documented isolation level? + +Current assessment: Published summary: snapshot isolation by default; durability differs materially across storage modes. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.15 `durability` + +Audit question: What device/service acknowledgement is required before commit returns? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.16 `recovery` + +Audit question: What bounds restart work after a clean stop and a crash? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.17 `writer_fencing` + +Audit question: Can a stale writer acknowledge after failover or lease expiry? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.18 `partitioning` + +Audit question: What key determines placement and what happens to cross-partition edges? + +Current assessment: Published distribution summary: leader/replica high availability and read scaling; not a general sharded PB store. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.19 `rebalancing` + +Audit question: Can placement change online without changing logical identity? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.20 `replication` + +Audit question: Are replicas full, sharded, synchronous, asynchronous, or shared-storage readers? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.21 `optimizer` + +Audit question: Does the optimizer cost graph expansion, joins, network, cache, and remote requests? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.22 `statistics` + +Audit question: Which degree, correlation, path, and property statistics are persistent? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.23 `execution` + +Audit question: Is execution tuple-at-a-time, vectorized, factorized, compiled, matrix, or actor based? + +Current assessment: Expected family: C++ execution with built-in traversals, query modules, triggers, and parallel runtime work. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.24 `recursion` + +Audit question: How are BFS, shortest paths, trails, simple paths, and arbitrary reachability executed? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.25 `parallelism` + +Audit question: How does the engine avoid skew and nested parallelism under mixed queries? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.26 `memory` + +Audit question: Are all variable allocations charged to bounded query and system budgets? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.27 `spill` + +Audit question: Which operators spill, in what format, and with what admission controls? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.28 `cancellation` + +Audit question: Can cancellation stop CPU, local I/O, remote I/O, retries, and prefetch? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.29 `cache` + +Audit question: What is cached, how is it keyed, admitted, pinned, and evicted? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.30 `cold_start` + +Audit question: What metadata and data round trips are required with empty caches? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.31 `object_requests` + +Audit question: Can a query issue one remote request per node, edge, or result row? + +Current assessment: Published object-store posture: not object-store-native. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.32 `cost_admission` + +Audit question: Are request, byte, CPU, spill, and result limits enforced before work? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.33 `observability` + +Audit question: Can operators report rows, edges, bytes, requests, stalls, memory, and spill? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.34 `language` + +Audit question: Which GQL/Cypher/SQL-PGQ/Gremlin/SPARQL semantics are declared and tested? + +Current assessment: Declared surface: Cypher-compatible language and procedures. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.35 `updates` + +Audit question: Are DDL, insert, merge, update, detach delete, and constraints complete? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.36 `bulk_load` + +Audit question: Does bulk load preserve transactional and index invariants? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.37 `backup` + +Audit question: Is backup consistent, incremental, immutable, and restore-tested? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.38 `gc` + +Audit question: How are old snapshots, orphan objects, tombstones, and indexes reclaimed safely? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.39 `security` + +Audit question: Are authentication, authorization, encryption, audit, and tenant isolation in scope? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.40 `operations` + +Audit question: What compaction, upgrade, repair, verification, and capacity procedures exist? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +## 5. Benchmark contract for this engine + +Every case runs correctness first, then isolated latency, then closed-loop concurrency, then open-loop overload. Report median, p95, p99, p99.9, timeout/rejection rate, throughput, CPU-seconds, peak RSS, cache bytes, disk bytes, network bytes, remote requests, write amplification, and estimated monthly cost. + +Warm means all intended engine caches are populated without changing the query parameters. Hot means the exact working set is resident. Cold means process-local, engine, OS, NVMe, and remote cache state are explicitly reset or a fresh namespace is used. Those words are never inferred from repetition count. + +### 5.1 `point_pk` — primary-key node lookup with one projected property + +- Applicability to Memgraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.2 `point_edge` — stable edge-ID lookup including endpoints and one property + +- Applicability to Memgraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.3 `degree_1` — degree-one outgoing expansion + +- Applicability to Memgraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.4 `degree_32` — small adjacency expansion around degree 32 + +- Applicability to Memgraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.5 `degree_1k` — medium adjacency expansion around degree 1,024 + +- Applicability to Memgraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.6 `supernode` — range-limited expansion of a ten-million-degree supernode + +- Applicability to Memgraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.7 `expand_2` — selective two-hop expansion + +- Applicability to Memgraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.8 `expand_3` — three-hop frontier expansion with duplicate control + +- Applicability to Memgraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.9 `expand_into` — edge-existence/expand-into between already-bound endpoints + +- Applicability to Memgraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.10 `multi_edge` — parallel-edge identity and property projection + +- Applicability to Memgraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.11 `shortest` — bidirectional point-to-point unweighted shortest path + +- Applicability to Memgraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.12 `weighted` — weighted shortest path with property access + +- Applicability to Memgraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.13 `var_walk` — bounded variable-length walk + +- Applicability to Memgraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.14 `trail` — DIFFERENT EDGES trail enumeration + +- Applicability to Memgraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.15 `simple` — simple-path enumeration with explicit bound + +- Applicability to Memgraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.16 `triangle` — triangle pattern with worst-case-sensitive join + +- Applicability to Memgraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.17 `cycle4` — four-cycle pattern + +- Applicability to Memgraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.18 `star_join` — high-fanout star pattern with property filters + +- Applicability to Memgraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.19 `optional` — optional match preserving null/bag semantics + +- Applicability to Memgraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.20 `aggregate` — grouped aggregate after traversal + +- Applicability to Memgraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.21 `topk` — ordered top-k with late property materialization + +- Applicability to Memgraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.22 `scan` — full projected property scan + +- Applicability to Memgraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.23 `selective_scan` — zone/index-pruned selective property scan + +- Applicability to Memgraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.24 `mixed` — concurrent short reads, complex reads, and updates + +- Applicability to Memgraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.25 `ingest` — sustained transactional ingest with indexes enabled + +- Applicability to Memgraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.26 `bulk` — initial bulk load including index/CSR build + +- Applicability to Memgraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.27 `checkpoint` — checkpoint or compaction while readers remain active + +- Applicability to Memgraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.28 `recovery` — crash recovery at bounded dirty-log size + +- Applicability to Memgraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.29 `cold` — same query after clearing engine and OS/cache tiers + +- Applicability to Memgraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.30 `remote` — same query with authoritative bytes only in object storage + +- Applicability to Memgraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +## 6. Fairness controls + +- Same logical dataset and update stream; engine-native physical layouts are allowed and disclosed. +- Same result semantics; unsupported queries remain unsupported rather than rewritten into easier questions. +- Same durable acknowledgement class for write comparisons. +- Same number of physical cores and memory limit for self-hosted single-node tests. +- Same aggregate resources and replication fault tolerance for distributed tests. +- Officially recommended tuning may be applied before the freeze and is committed with rationale. +- Query-specific hints are allowed only when equivalent hints are offered to every engine and separately charted. +- Load/build/index time and bytes are first-class results. +- Cold, warm, and hot results are separate charts. +- Managed services use public configurations and cannot borrow hidden same-machine resource claims. +- Failed runs, OOMs, correctness mismatches, and timeouts stay in the dataset. +- Every chart links raw samples and the exact reproduction command. + +## 7. Likely advantages and limits + +The strongest known reason to choose this engine is tied to its family `in-memory operational property graph`, its execution path `C++ execution with built-in traversals, query modules, triggers, and parallel runtime work`, and its existing ecosystem. The strongest reason to reject it for zu's target is the gap between `not object-store-native` and an S3-authoritative, request-budgeted, PB-scale graph service. + +Capacity statement: RAM-bound mode targets low latency; on-disk mode broadens capacity with different behavior. This is not converted into an edge-count claim without a physical byte model including IDs, both adjacency directions, properties, indexes, MVCC, WAL, replicas, and free space. + +Commercial statement: Business Source License/community plus commercial features; pin exact edition. License cost, support cost, and unavailable enterprise capabilities remain visible in TCO and feature tables. + +## 8. Concrete lessons for zu + +1. Keep stable logical node and edge identity independent of row group, CSR slot, shard, and object range. +2. Store forward and reverse adjacency as immutable range-addressable tiles carrying edge IDs. +3. Feed queries adjacency batches and typed vectors; prohibit one storage call per logical element. +4. Use vectorized/factorized execution for property-heavy patterns and dedicated frontier operators for recursion. +5. Cost topology, properties, network, cache certainty, remote requests, and result materialization together. +6. Separate the local embedded profile from the object-authoritative distributed read profile. +7. Fence writers with monotonic epochs and make ambiguous commits reconcilable by transaction ID. +8. Pack small graph tiles into large immutable objects while retaining independent checksums and range offsets. +9. Keep the hot topology working set in RAM/NVMe; batch cold frontier misses into few remote rounds. +10. Admission-control remote requests and bytes so fixed-price plans have an enforceable upper bound. +11. Partition by workload-aware graph locality, and expose cross-partition semantics rather than hiding them. +12. Publish qualified wins per workload cell; never promise a universal tenfold advantage. + +## 9. Evidence gaps to close before publication + +- Exact current version and release date. +- Exact license text for the benchmarked artifact. +- Storage bytes per node/edge/property on all standard datasets. +- Stable-edge-ID and parallel-edge semantics. +- Isolation litmus results and commit acknowledgement point. +- Crash recovery time versus dirty WAL size. +- Supernode behavior and maximum tested degree. +- Cold-start metadata and request count. +- Distributed cross-partition query amplification. +- Peak memory under skew, cancellation, and overload. +- Background compaction/GC effect on tail latency. +- Full load/index/checkpoint/backup resource cost. +- Reproducible largest-scale result. +- Independent or audited benchmark evidence. + +## 10. Primary and official sources + +- [Product architecture](https://memgraph.com/memgraphdb) +- [Storage modes](https://memgraph.com/blog/memgraph-storage-modes-explained) +- [Replication design](https://memgraph.com/blog/implementing-data-replication) +- [Source repository](https://github.com/memgraph/memgraph) +- [LDBC SNB Interactive and audited disclosures](https://ldbcouncil.org/benchmarks/snb/interactive/) +- [LDBC Graphalytics](https://ldbcouncil.org/benchmarks/graphalytics/) +- [SoK: The Faults in our Graph Benchmarks](https://arxiv.org/abs/2404.00766) + +## 11. Source-handling rules + +- Official documentation and source are evidence for implemented or declared behavior, not independent performance. +- A vendor benchmark is labeled vendor claim until the harness reproduces it. +- A peer-reviewed paper establishes only the version, configuration, and workload it evaluated. +- Search snippets, comparison sites, and unsourced blogs are discovery aids, not final evidence. +- Unknown is a valid result and creates a concrete experiment or source-inspection task. +- All web facts are rechecked at benchmark freeze because this corpus is current only through the research date. + +## 12. Reproduction record template + +- engine: `Memgraph` +- version: `TBD at benchmark freeze` +- artifact digest: `TBD` +- source commit: `TBD or managed-service N/A` +- edition/license: `TBD` +- query language/version: `TBD` +- storage and durability mode: `TBD` +- cluster and replication: `TBD` +- CPU/RAM/NVMe/network: `TBD` +- OS/kernel/filesystem: `TBD` +- dataset URI and digest: `TBD` +- loader command and duration: `TBD` +- physical bytes by category: `TBD` +- tuning file: `TBD` +- query corpus commit: `TBD` +- raw result URI/digest: `TBD` +- profiler/trace URI: `TBD` +- correctness status: `TBD` +- reviewer and rerun date: `TBD` diff --git a/docs/research/engine-microsoft_fabric_graph.md b/docs/research/engine-microsoft_fabric_graph.md new file mode 100644 index 0000000..66663d5 --- /dev/null +++ b/docs/research/engine-microsoft_fabric_graph.md @@ -0,0 +1,885 @@ +# Graph in Microsoft Fabric: 2026 deep technical and competitive specification + +Research cut: `2026-08-08` +Status: evidence-backed competitor audit; not a vendor endorsement +Family: `lakehouse graph analytics` +Evidence convention: **Observed/official**, **Vendor claim**, **Research inference**, **Unknown**, **Qualification target**. + +## 1. Decision summary + +Fabric Graph is a new direct lakehouse competitor and validates GQL plus read-optimized materialization over object-backed tables. + +This document answers two questions: what this engine actually proves in 2026, and what zu must build or measure to earn a defensible advantage. A missing public detail remains unknown; it is never silently filled with a favorable assumption. + +### Snapshot card + +- Lifecycle: active 2026 feature. +- Data model: labeled property graph built from OneLake tables. +- Query surface: ISO GQL subset, visual builder, REST, NL2GQL. +- Persistent layout: OneLake tabular source plus an ingested read-optimized traversal representation. +- Execution: scale-out graph pattern and traversal engine. +- Transactions: read-oriented analytics; current docs do not expose general graph DML transactions. +- Distribution: managed scale-out within Fabric. +- Object-storage posture: directly lake/object aligned through OneLake, but materializes a queryable graph. +- License/commercial boundary: proprietary managed service. +- Scale evidence: officially targets billions of relationships; PB evidence absent. +- Benchmark posture: include graph build/rebuild, capacity units, schema evolution, and cold/warm state. + +### Facts that materially affect comparison + +- F01 — Saving a graph model ingests source tables into a traversal-optimized graph. +- F02 — Current documentation says schema evolution requires reingestion into a new model. +- F03 — GQL, visual query building, and REST share one execution layer. +- F04 — Set operations and mutations have documented limitations. +- F05 — OneLake authority does not eliminate the cost and freshness semantics of the derived graph. + +### Bottom-line fit against zu's target + +- Very-low latency: compare hot point and bounded traversal paths; never extrapolate from scans or algorithms. +- Very-low resources: charge resident set, page cache, remote cache, background services, and replicas. +- Distributed: distinguish read replication, partitioned capacity, distributed transactions, and elastic stateless compute. +- Fixed cost: no engine has fixed marginal cost by declaration; admission, batching, and capacity reservations create the bound. +- S3 authority: backups, imports, lake scans, and S3-native demand paging are four different architectures. +- PB / trillion-edge scale: require a capacity derivation plus a run at the largest affordable scale; marketing adjectives do not qualify. +- Tenfold win: can be a per-cell qualification result, never a universal statement across incomparable workloads. + +## 2. Product and ecosystem boundary + +The audited unit is **Graph in Microsoft Fabric** in the exact release, edition, deployment, and durability mode recorded by the harness. The family classification is **lakehouse graph analytics**. The current lifecycle statement is: active 2026 feature. + +The harness must record binary/container digest, source commit when available, build flags, plugins, license/edition, language mode, storage mode, cluster topology, replication factor, durability settings, cache sizes, thread counts, NUMA policy, kernel, filesystem, cloud region, and all environment variables that affect execution. + +A managed service is not placed in a same-hardware chart. It receives a service-level result with provisioned units, region, public price, and observed provider metrics. A historical engine remains useful for regression but cannot support a claim about beating all current competitors. + +## 3. Architecture reconstruction + +### 3.1 Logical model + +Graph in Microsoft Fabric exposes labeled property graph built from OneLake tables. The conformance corpus must test nulls, missing properties, labels/types, direction, self-loops, parallel edges, element equality, path equality, bag semantics, ordering, numeric overflow, string collation, temporal values, and schema evolution. + +### 3.2 Language and compiler + +The public query surface is ISO GQL subset, visual builder, REST, NL2GQL. Syntax similarity is not semantic equivalence. Every supported construct needs a result oracle and an unsupported-feature declaration. + +### 3.3 Storage + +The best supported storage summary is: OneLake tabular source plus an ingested read-optimized traversal representation. This statement must be refined from code, format documentation, or provider counters before using it in a performance explanation. + +### 3.4 Execution + +The best supported execution summary is: scale-out graph pattern and traversal engine. The benchmark profiler must confirm which runtime and operators actually executed. + +### 3.5 Transactions and recovery + +The public contract is: read-oriented analytics; current docs do not expose general graph DML transactions. Exact acknowledgement, isolation anomalies, recovery bounds, and failover behavior remain separate qualification items. + +### 3.6 Distribution + +The deployment shape is: managed scale-out within Fabric. Replication is not capacity sharding; sharding is not distributed ACID; stateless readers are not stateless storage. + +### 3.7 Object storage and cost + +The 2026 posture is: directly lake/object aligned through OneLake, but materializes a queryable graph. The audit distinguishes authoritative live bytes, derived acceleration, backup, import/export, and spill. + +## 4. Forty-control deep audit + +### 4.1 `product_boundary` + +Audit question: What exact executable, edition, and storage mode is the system under test? + +Current assessment: Pin Graph in Microsoft Fabric, lifecycle `active 2026 feature`, and its edition/mode. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.2 `authority` + +Audit question: Which durable component is the source of truth after every acknowledged write? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.3 `identity` + +Audit question: Are node and edge identities stable across compaction, export, replication, and restore? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.4 `parallel_edges` + +Audit question: Can distinct parallel edges retain properties and trail identity end to end? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.5 `schema` + +Audit question: Is the schema open, closed, optional, inferred, or externally mapped? + +Current assessment: Start from `labeled property graph built from OneLake tables` and test actual constraints. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.6 `labels` + +Audit question: How are multiple labels represented and indexed? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.7 `adjacency_out` + +Audit question: How is outgoing adjacency located, encoded, split, cached, and updated? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.8 `adjacency_in` + +Audit question: Is incoming adjacency first-class, derived, replicated, or a fan-out operation? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.9 `supernodes` + +Audit question: How are million-to-billion-degree vertices represented and scheduled? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.10 `properties` + +Audit question: Are properties co-located, columnar, row-oriented, document-encoded, or remote? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.11 `compression` + +Audit question: Which topology, integer, string, null, and floating encodings are implemented? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.12 `checksums` + +Audit question: What integrity unit is verified on point reads and range reads? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.13 `snapshot` + +Audit question: What exact token pins graph data, schema, statistics, and indexes? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.14 `isolation` + +Audit question: Which anomalies are forbidden at the documented isolation level? + +Current assessment: Published summary: read-oriented analytics; current docs do not expose general graph DML transactions. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.15 `durability` + +Audit question: What device/service acknowledgement is required before commit returns? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.16 `recovery` + +Audit question: What bounds restart work after a clean stop and a crash? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.17 `writer_fencing` + +Audit question: Can a stale writer acknowledge after failover or lease expiry? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.18 `partitioning` + +Audit question: What key determines placement and what happens to cross-partition edges? + +Current assessment: Published distribution summary: managed scale-out within Fabric. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.19 `rebalancing` + +Audit question: Can placement change online without changing logical identity? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.20 `replication` + +Audit question: Are replicas full, sharded, synchronous, asynchronous, or shared-storage readers? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.21 `optimizer` + +Audit question: Does the optimizer cost graph expansion, joins, network, cache, and remote requests? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.22 `statistics` + +Audit question: Which degree, correlation, path, and property statistics are persistent? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.23 `execution` + +Audit question: Is execution tuple-at-a-time, vectorized, factorized, compiled, matrix, or actor based? + +Current assessment: Expected family: scale-out graph pattern and traversal engine. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.24 `recursion` + +Audit question: How are BFS, shortest paths, trails, simple paths, and arbitrary reachability executed? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.25 `parallelism` + +Audit question: How does the engine avoid skew and nested parallelism under mixed queries? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.26 `memory` + +Audit question: Are all variable allocations charged to bounded query and system budgets? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.27 `spill` + +Audit question: Which operators spill, in what format, and with what admission controls? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.28 `cancellation` + +Audit question: Can cancellation stop CPU, local I/O, remote I/O, retries, and prefetch? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.29 `cache` + +Audit question: What is cached, how is it keyed, admitted, pinned, and evicted? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.30 `cold_start` + +Audit question: What metadata and data round trips are required with empty caches? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.31 `object_requests` + +Audit question: Can a query issue one remote request per node, edge, or result row? + +Current assessment: Published object-store posture: directly lake/object aligned through OneLake, but materializes a queryable graph. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.32 `cost_admission` + +Audit question: Are request, byte, CPU, spill, and result limits enforced before work? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.33 `observability` + +Audit question: Can operators report rows, edges, bytes, requests, stalls, memory, and spill? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.34 `language` + +Audit question: Which GQL/Cypher/SQL-PGQ/Gremlin/SPARQL semantics are declared and tested? + +Current assessment: Declared surface: ISO GQL subset, visual builder, REST, NL2GQL. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.35 `updates` + +Audit question: Are DDL, insert, merge, update, detach delete, and constraints complete? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.36 `bulk_load` + +Audit question: Does bulk load preserve transactional and index invariants? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.37 `backup` + +Audit question: Is backup consistent, incremental, immutable, and restore-tested? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.38 `gc` + +Audit question: How are old snapshots, orphan objects, tombstones, and indexes reclaimed safely? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.39 `security` + +Audit question: Are authentication, authorization, encryption, audit, and tenant isolation in scope? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.40 `operations` + +Audit question: What compaction, upgrade, repair, verification, and capacity procedures exist? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +## 5. Benchmark contract for this engine + +Every case runs correctness first, then isolated latency, then closed-loop concurrency, then open-loop overload. Report median, p95, p99, p99.9, timeout/rejection rate, throughput, CPU-seconds, peak RSS, cache bytes, disk bytes, network bytes, remote requests, write amplification, and estimated monthly cost. + +Warm means all intended engine caches are populated without changing the query parameters. Hot means the exact working set is resident. Cold means process-local, engine, OS, NVMe, and remote cache state are explicitly reset or a fresh namespace is used. Those words are never inferred from repetition count. + +### 5.1 `point_pk` — primary-key node lookup with one projected property + +- Applicability to Graph in Microsoft Fabric: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.2 `point_edge` — stable edge-ID lookup including endpoints and one property + +- Applicability to Graph in Microsoft Fabric: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.3 `degree_1` — degree-one outgoing expansion + +- Applicability to Graph in Microsoft Fabric: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.4 `degree_32` — small adjacency expansion around degree 32 + +- Applicability to Graph in Microsoft Fabric: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.5 `degree_1k` — medium adjacency expansion around degree 1,024 + +- Applicability to Graph in Microsoft Fabric: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.6 `supernode` — range-limited expansion of a ten-million-degree supernode + +- Applicability to Graph in Microsoft Fabric: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.7 `expand_2` — selective two-hop expansion + +- Applicability to Graph in Microsoft Fabric: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.8 `expand_3` — three-hop frontier expansion with duplicate control + +- Applicability to Graph in Microsoft Fabric: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.9 `expand_into` — edge-existence/expand-into between already-bound endpoints + +- Applicability to Graph in Microsoft Fabric: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.10 `multi_edge` — parallel-edge identity and property projection + +- Applicability to Graph in Microsoft Fabric: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.11 `shortest` — bidirectional point-to-point unweighted shortest path + +- Applicability to Graph in Microsoft Fabric: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.12 `weighted` — weighted shortest path with property access + +- Applicability to Graph in Microsoft Fabric: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.13 `var_walk` — bounded variable-length walk + +- Applicability to Graph in Microsoft Fabric: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.14 `trail` — DIFFERENT EDGES trail enumeration + +- Applicability to Graph in Microsoft Fabric: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.15 `simple` — simple-path enumeration with explicit bound + +- Applicability to Graph in Microsoft Fabric: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.16 `triangle` — triangle pattern with worst-case-sensitive join + +- Applicability to Graph in Microsoft Fabric: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.17 `cycle4` — four-cycle pattern + +- Applicability to Graph in Microsoft Fabric: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.18 `star_join` — high-fanout star pattern with property filters + +- Applicability to Graph in Microsoft Fabric: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.19 `optional` — optional match preserving null/bag semantics + +- Applicability to Graph in Microsoft Fabric: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.20 `aggregate` — grouped aggregate after traversal + +- Applicability to Graph in Microsoft Fabric: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.21 `topk` — ordered top-k with late property materialization + +- Applicability to Graph in Microsoft Fabric: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.22 `scan` — full projected property scan + +- Applicability to Graph in Microsoft Fabric: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.23 `selective_scan` — zone/index-pruned selective property scan + +- Applicability to Graph in Microsoft Fabric: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.24 `mixed` — concurrent short reads, complex reads, and updates + +- Applicability to Graph in Microsoft Fabric: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.25 `ingest` — sustained transactional ingest with indexes enabled + +- Applicability to Graph in Microsoft Fabric: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.26 `bulk` — initial bulk load including index/CSR build + +- Applicability to Graph in Microsoft Fabric: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.27 `checkpoint` — checkpoint or compaction while readers remain active + +- Applicability to Graph in Microsoft Fabric: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.28 `recovery` — crash recovery at bounded dirty-log size + +- Applicability to Graph in Microsoft Fabric: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.29 `cold` — same query after clearing engine and OS/cache tiers + +- Applicability to Graph in Microsoft Fabric: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.30 `remote` — same query with authoritative bytes only in object storage + +- Applicability to Graph in Microsoft Fabric: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +## 6. Fairness controls + +- Same logical dataset and update stream; engine-native physical layouts are allowed and disclosed. +- Same result semantics; unsupported queries remain unsupported rather than rewritten into easier questions. +- Same durable acknowledgement class for write comparisons. +- Same number of physical cores and memory limit for self-hosted single-node tests. +- Same aggregate resources and replication fault tolerance for distributed tests. +- Officially recommended tuning may be applied before the freeze and is committed with rationale. +- Query-specific hints are allowed only when equivalent hints are offered to every engine and separately charted. +- Load/build/index time and bytes are first-class results. +- Cold, warm, and hot results are separate charts. +- Managed services use public configurations and cannot borrow hidden same-machine resource claims. +- Failed runs, OOMs, correctness mismatches, and timeouts stay in the dataset. +- Every chart links raw samples and the exact reproduction command. + +## 7. Likely advantages and limits + +The strongest known reason to choose this engine is tied to its family `lakehouse graph analytics`, its execution path `scale-out graph pattern and traversal engine`, and its existing ecosystem. The strongest reason to reject it for zu's target is the gap between `directly lake/object aligned through OneLake, but materializes a queryable graph` and an S3-authoritative, request-budgeted, PB-scale graph service. + +Capacity statement: officially targets billions of relationships; PB evidence absent. This is not converted into an edge-count claim without a physical byte model including IDs, both adjacency directions, properties, indexes, MVCC, WAL, replicas, and free space. + +Commercial statement: proprietary managed service. License cost, support cost, and unavailable enterprise capabilities remain visible in TCO and feature tables. + +## 8. Concrete lessons for zu + +1. Keep stable logical node and edge identity independent of row group, CSR slot, shard, and object range. +2. Store forward and reverse adjacency as immutable range-addressable tiles carrying edge IDs. +3. Feed queries adjacency batches and typed vectors; prohibit one storage call per logical element. +4. Use vectorized/factorized execution for property-heavy patterns and dedicated frontier operators for recursion. +5. Cost topology, properties, network, cache certainty, remote requests, and result materialization together. +6. Separate the local embedded profile from the object-authoritative distributed read profile. +7. Fence writers with monotonic epochs and make ambiguous commits reconcilable by transaction ID. +8. Pack small graph tiles into large immutable objects while retaining independent checksums and range offsets. +9. Keep the hot topology working set in RAM/NVMe; batch cold frontier misses into few remote rounds. +10. Admission-control remote requests and bytes so fixed-price plans have an enforceable upper bound. +11. Partition by workload-aware graph locality, and expose cross-partition semantics rather than hiding them. +12. Publish qualified wins per workload cell; never promise a universal tenfold advantage. + +## 9. Evidence gaps to close before publication + +- Exact current version and release date. +- Exact license text for the benchmarked artifact. +- Storage bytes per node/edge/property on all standard datasets. +- Stable-edge-ID and parallel-edge semantics. +- Isolation litmus results and commit acknowledgement point. +- Crash recovery time versus dirty WAL size. +- Supernode behavior and maximum tested degree. +- Cold-start metadata and request count. +- Distributed cross-partition query amplification. +- Peak memory under skew, cancellation, and overload. +- Background compaction/GC effect on tail latency. +- Full load/index/checkpoint/backup resource cost. +- Reproducible largest-scale result. +- Independent or audited benchmark evidence. + +## 10. Primary and official sources + +- [Architecture](https://learn.microsoft.com/en-us/fabric/graph/how-graph-works) +- [Overview](https://learn.microsoft.com/en-us/fabric/graph/overview) +- [GQL guide](https://learn.microsoft.com/en-us/fabric/graph/gql-language-guide) +- [LDBC SNB Interactive and audited disclosures](https://ldbcouncil.org/benchmarks/snb/interactive/) +- [LDBC Graphalytics](https://ldbcouncil.org/benchmarks/graphalytics/) +- [SoK: The Faults in our Graph Benchmarks](https://arxiv.org/abs/2404.00766) + +## 11. Source-handling rules + +- Official documentation and source are evidence for implemented or declared behavior, not independent performance. +- A vendor benchmark is labeled vendor claim until the harness reproduces it. +- A peer-reviewed paper establishes only the version, configuration, and workload it evaluated. +- Search snippets, comparison sites, and unsourced blogs are discovery aids, not final evidence. +- Unknown is a valid result and creates a concrete experiment or source-inspection task. +- All web facts are rechecked at benchmark freeze because this corpus is current only through the research date. + +## 12. Reproduction record template + +- engine: `Graph in Microsoft Fabric` +- version: `TBD at benchmark freeze` +- artifact digest: `TBD` +- source commit: `TBD or managed-service N/A` +- edition/license: `TBD` +- query language/version: `TBD` +- storage and durability mode: `TBD` +- cluster and replication: `TBD` +- CPU/RAM/NVMe/network: `TBD` +- OS/kernel/filesystem: `TBD` +- dataset URI and digest: `TBD` +- loader command and duration: `TBD` +- physical bytes by category: `TBD` +- tuning file: `TBD` +- query corpus commit: `TBD` +- raw result URI/digest: `TBD` +- profiler/trace URI: `TBD` +- correctness status: `TBD` +- reviewer and rerun date: `TBD` diff --git a/docs/research/engine-millenniumdb.md b/docs/research/engine-millenniumdb.md new file mode 100644 index 0000000..793d38c --- /dev/null +++ b/docs/research/engine-millenniumdb.md @@ -0,0 +1,884 @@ +# MillenniumDB: 2026 deep technical and competitive specification + +Research cut: `2026-08-08` +Status: evidence-backed competitor audit; not a vendor endorsement +Family: `research persistent graph database` +Evidence convention: **Observed/official**, **Vendor claim**, **Research inference**, **Unknown**, **Qualification target**. + +## 1. Decision summary + +MillenniumDB is a valuable research baseline for succinct indexes and path algorithms, though not a deployment peer. + +This document answers two questions: what this engine actually proves in 2026, and what zu must build or measure to earn a defensible advantage. A missing public detail remains unknown; it is never silently filled with a favorable assumption. + +### Snapshot card + +- Lifecycle: active research project with small community. +- Data model: property-domain graph supporting RDF and property graph ideas. +- Query surface: custom query language with basic graph patterns and paths. +- Persistent layout: relations indexed by B+ trees with a fixed-size buffer manager. +- Execution: relational-style optimizer plus worst-case-oriented graph techniques. +- Transactions: persistent single-node transaction detail is less mature than commercial OLTP systems. +- Distribution: single-node. +- Object-storage posture: not S3-native. +- License/commercial boundary: GPL-2.0 repository. +- Scale evidence: research-scale, no PB serving claim. +- Benchmark posture: use for optimizer/index research comparisons, not product TCO claims. + +### Facts that materially affect comparison + +- F01 — The system stores graph components as relations over B+ trees. +- F02 — A fixed-size buffer controls what is resident in memory. +- F03 — The design combines classical DBMS techniques with graph-query theory. +- F04 — It supports a richer domain graph model than a plain labeled property graph. +- F05 — Small project size increases operational and compatibility uncertainty. + +### Bottom-line fit against zu's target + +- Very-low latency: compare hot point and bounded traversal paths; never extrapolate from scans or algorithms. +- Very-low resources: charge resident set, page cache, remote cache, background services, and replicas. +- Distributed: distinguish read replication, partitioned capacity, distributed transactions, and elastic stateless compute. +- Fixed cost: no engine has fixed marginal cost by declaration; admission, batching, and capacity reservations create the bound. +- S3 authority: backups, imports, lake scans, and S3-native demand paging are four different architectures. +- PB / trillion-edge scale: require a capacity derivation plus a run at the largest affordable scale; marketing adjectives do not qualify. +- Tenfold win: can be a per-cell qualification result, never a universal statement across incomparable workloads. + +## 2. Product and ecosystem boundary + +The audited unit is **MillenniumDB** in the exact release, edition, deployment, and durability mode recorded by the harness. The family classification is **research persistent graph database**. The current lifecycle statement is: active research project with small community. + +The harness must record binary/container digest, source commit when available, build flags, plugins, license/edition, language mode, storage mode, cluster topology, replication factor, durability settings, cache sizes, thread counts, NUMA policy, kernel, filesystem, cloud region, and all environment variables that affect execution. + +A managed service is not placed in a same-hardware chart. It receives a service-level result with provisioned units, region, public price, and observed provider metrics. A historical engine remains useful for regression but cannot support a claim about beating all current competitors. + +## 3. Architecture reconstruction + +### 3.1 Logical model + +MillenniumDB exposes property-domain graph supporting RDF and property graph ideas. The conformance corpus must test nulls, missing properties, labels/types, direction, self-loops, parallel edges, element equality, path equality, bag semantics, ordering, numeric overflow, string collation, temporal values, and schema evolution. + +### 3.2 Language and compiler + +The public query surface is custom query language with basic graph patterns and paths. Syntax similarity is not semantic equivalence. Every supported construct needs a result oracle and an unsupported-feature declaration. + +### 3.3 Storage + +The best supported storage summary is: relations indexed by B+ trees with a fixed-size buffer manager. This statement must be refined from code, format documentation, or provider counters before using it in a performance explanation. + +### 3.4 Execution + +The best supported execution summary is: relational-style optimizer plus worst-case-oriented graph techniques. The benchmark profiler must confirm which runtime and operators actually executed. + +### 3.5 Transactions and recovery + +The public contract is: persistent single-node transaction detail is less mature than commercial OLTP systems. Exact acknowledgement, isolation anomalies, recovery bounds, and failover behavior remain separate qualification items. + +### 3.6 Distribution + +The deployment shape is: single-node. Replication is not capacity sharding; sharding is not distributed ACID; stateless readers are not stateless storage. + +### 3.7 Object storage and cost + +The 2026 posture is: not S3-native. The audit distinguishes authoritative live bytes, derived acceleration, backup, import/export, and spill. + +## 4. Forty-control deep audit + +### 4.1 `product_boundary` + +Audit question: What exact executable, edition, and storage mode is the system under test? + +Current assessment: Pin MillenniumDB, lifecycle `active research project with small community`, and its edition/mode. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.2 `authority` + +Audit question: Which durable component is the source of truth after every acknowledged write? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.3 `identity` + +Audit question: Are node and edge identities stable across compaction, export, replication, and restore? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.4 `parallel_edges` + +Audit question: Can distinct parallel edges retain properties and trail identity end to end? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.5 `schema` + +Audit question: Is the schema open, closed, optional, inferred, or externally mapped? + +Current assessment: Start from `property-domain graph supporting RDF and property graph ideas` and test actual constraints. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.6 `labels` + +Audit question: How are multiple labels represented and indexed? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.7 `adjacency_out` + +Audit question: How is outgoing adjacency located, encoded, split, cached, and updated? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.8 `adjacency_in` + +Audit question: Is incoming adjacency first-class, derived, replicated, or a fan-out operation? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.9 `supernodes` + +Audit question: How are million-to-billion-degree vertices represented and scheduled? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.10 `properties` + +Audit question: Are properties co-located, columnar, row-oriented, document-encoded, or remote? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.11 `compression` + +Audit question: Which topology, integer, string, null, and floating encodings are implemented? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.12 `checksums` + +Audit question: What integrity unit is verified on point reads and range reads? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.13 `snapshot` + +Audit question: What exact token pins graph data, schema, statistics, and indexes? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.14 `isolation` + +Audit question: Which anomalies are forbidden at the documented isolation level? + +Current assessment: Published summary: persistent single-node transaction detail is less mature than commercial OLTP systems. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.15 `durability` + +Audit question: What device/service acknowledgement is required before commit returns? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.16 `recovery` + +Audit question: What bounds restart work after a clean stop and a crash? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.17 `writer_fencing` + +Audit question: Can a stale writer acknowledge after failover or lease expiry? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.18 `partitioning` + +Audit question: What key determines placement and what happens to cross-partition edges? + +Current assessment: Published distribution summary: single-node. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.19 `rebalancing` + +Audit question: Can placement change online without changing logical identity? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.20 `replication` + +Audit question: Are replicas full, sharded, synchronous, asynchronous, or shared-storage readers? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.21 `optimizer` + +Audit question: Does the optimizer cost graph expansion, joins, network, cache, and remote requests? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.22 `statistics` + +Audit question: Which degree, correlation, path, and property statistics are persistent? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.23 `execution` + +Audit question: Is execution tuple-at-a-time, vectorized, factorized, compiled, matrix, or actor based? + +Current assessment: Expected family: relational-style optimizer plus worst-case-oriented graph techniques. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.24 `recursion` + +Audit question: How are BFS, shortest paths, trails, simple paths, and arbitrary reachability executed? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.25 `parallelism` + +Audit question: How does the engine avoid skew and nested parallelism under mixed queries? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.26 `memory` + +Audit question: Are all variable allocations charged to bounded query and system budgets? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.27 `spill` + +Audit question: Which operators spill, in what format, and with what admission controls? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.28 `cancellation` + +Audit question: Can cancellation stop CPU, local I/O, remote I/O, retries, and prefetch? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.29 `cache` + +Audit question: What is cached, how is it keyed, admitted, pinned, and evicted? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.30 `cold_start` + +Audit question: What metadata and data round trips are required with empty caches? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.31 `object_requests` + +Audit question: Can a query issue one remote request per node, edge, or result row? + +Current assessment: Published object-store posture: not S3-native. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.32 `cost_admission` + +Audit question: Are request, byte, CPU, spill, and result limits enforced before work? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.33 `observability` + +Audit question: Can operators report rows, edges, bytes, requests, stalls, memory, and spill? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.34 `language` + +Audit question: Which GQL/Cypher/SQL-PGQ/Gremlin/SPARQL semantics are declared and tested? + +Current assessment: Declared surface: custom query language with basic graph patterns and paths. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.35 `updates` + +Audit question: Are DDL, insert, merge, update, detach delete, and constraints complete? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.36 `bulk_load` + +Audit question: Does bulk load preserve transactional and index invariants? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.37 `backup` + +Audit question: Is backup consistent, incremental, immutable, and restore-tested? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.38 `gc` + +Audit question: How are old snapshots, orphan objects, tombstones, and indexes reclaimed safely? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.39 `security` + +Audit question: Are authentication, authorization, encryption, audit, and tenant isolation in scope? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.40 `operations` + +Audit question: What compaction, upgrade, repair, verification, and capacity procedures exist? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +## 5. Benchmark contract for this engine + +Every case runs correctness first, then isolated latency, then closed-loop concurrency, then open-loop overload. Report median, p95, p99, p99.9, timeout/rejection rate, throughput, CPU-seconds, peak RSS, cache bytes, disk bytes, network bytes, remote requests, write amplification, and estimated monthly cost. + +Warm means all intended engine caches are populated without changing the query parameters. Hot means the exact working set is resident. Cold means process-local, engine, OS, NVMe, and remote cache state are explicitly reset or a fresh namespace is used. Those words are never inferred from repetition count. + +### 5.1 `point_pk` — primary-key node lookup with one projected property + +- Applicability to MillenniumDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.2 `point_edge` — stable edge-ID lookup including endpoints and one property + +- Applicability to MillenniumDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.3 `degree_1` — degree-one outgoing expansion + +- Applicability to MillenniumDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.4 `degree_32` — small adjacency expansion around degree 32 + +- Applicability to MillenniumDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.5 `degree_1k` — medium adjacency expansion around degree 1,024 + +- Applicability to MillenniumDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.6 `supernode` — range-limited expansion of a ten-million-degree supernode + +- Applicability to MillenniumDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.7 `expand_2` — selective two-hop expansion + +- Applicability to MillenniumDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.8 `expand_3` — three-hop frontier expansion with duplicate control + +- Applicability to MillenniumDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.9 `expand_into` — edge-existence/expand-into between already-bound endpoints + +- Applicability to MillenniumDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.10 `multi_edge` — parallel-edge identity and property projection + +- Applicability to MillenniumDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.11 `shortest` — bidirectional point-to-point unweighted shortest path + +- Applicability to MillenniumDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.12 `weighted` — weighted shortest path with property access + +- Applicability to MillenniumDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.13 `var_walk` — bounded variable-length walk + +- Applicability to MillenniumDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.14 `trail` — DIFFERENT EDGES trail enumeration + +- Applicability to MillenniumDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.15 `simple` — simple-path enumeration with explicit bound + +- Applicability to MillenniumDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.16 `triangle` — triangle pattern with worst-case-sensitive join + +- Applicability to MillenniumDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.17 `cycle4` — four-cycle pattern + +- Applicability to MillenniumDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.18 `star_join` — high-fanout star pattern with property filters + +- Applicability to MillenniumDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.19 `optional` — optional match preserving null/bag semantics + +- Applicability to MillenniumDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.20 `aggregate` — grouped aggregate after traversal + +- Applicability to MillenniumDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.21 `topk` — ordered top-k with late property materialization + +- Applicability to MillenniumDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.22 `scan` — full projected property scan + +- Applicability to MillenniumDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.23 `selective_scan` — zone/index-pruned selective property scan + +- Applicability to MillenniumDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.24 `mixed` — concurrent short reads, complex reads, and updates + +- Applicability to MillenniumDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.25 `ingest` — sustained transactional ingest with indexes enabled + +- Applicability to MillenniumDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.26 `bulk` — initial bulk load including index/CSR build + +- Applicability to MillenniumDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.27 `checkpoint` — checkpoint or compaction while readers remain active + +- Applicability to MillenniumDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.28 `recovery` — crash recovery at bounded dirty-log size + +- Applicability to MillenniumDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.29 `cold` — same query after clearing engine and OS/cache tiers + +- Applicability to MillenniumDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.30 `remote` — same query with authoritative bytes only in object storage + +- Applicability to MillenniumDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +## 6. Fairness controls + +- Same logical dataset and update stream; engine-native physical layouts are allowed and disclosed. +- Same result semantics; unsupported queries remain unsupported rather than rewritten into easier questions. +- Same durable acknowledgement class for write comparisons. +- Same number of physical cores and memory limit for self-hosted single-node tests. +- Same aggregate resources and replication fault tolerance for distributed tests. +- Officially recommended tuning may be applied before the freeze and is committed with rationale. +- Query-specific hints are allowed only when equivalent hints are offered to every engine and separately charted. +- Load/build/index time and bytes are first-class results. +- Cold, warm, and hot results are separate charts. +- Managed services use public configurations and cannot borrow hidden same-machine resource claims. +- Failed runs, OOMs, correctness mismatches, and timeouts stay in the dataset. +- Every chart links raw samples and the exact reproduction command. + +## 7. Likely advantages and limits + +The strongest known reason to choose this engine is tied to its family `research persistent graph database`, its execution path `relational-style optimizer plus worst-case-oriented graph techniques`, and its existing ecosystem. The strongest reason to reject it for zu's target is the gap between `not S3-native` and an S3-authoritative, request-budgeted, PB-scale graph service. + +Capacity statement: research-scale, no PB serving claim. This is not converted into an edge-count claim without a physical byte model including IDs, both adjacency directions, properties, indexes, MVCC, WAL, replicas, and free space. + +Commercial statement: GPL-2.0 repository. License cost, support cost, and unavailable enterprise capabilities remain visible in TCO and feature tables. + +## 8. Concrete lessons for zu + +1. Keep stable logical node and edge identity independent of row group, CSR slot, shard, and object range. +2. Store forward and reverse adjacency as immutable range-addressable tiles carrying edge IDs. +3. Feed queries adjacency batches and typed vectors; prohibit one storage call per logical element. +4. Use vectorized/factorized execution for property-heavy patterns and dedicated frontier operators for recursion. +5. Cost topology, properties, network, cache certainty, remote requests, and result materialization together. +6. Separate the local embedded profile from the object-authoritative distributed read profile. +7. Fence writers with monotonic epochs and make ambiguous commits reconcilable by transaction ID. +8. Pack small graph tiles into large immutable objects while retaining independent checksums and range offsets. +9. Keep the hot topology working set in RAM/NVMe; batch cold frontier misses into few remote rounds. +10. Admission-control remote requests and bytes so fixed-price plans have an enforceable upper bound. +11. Partition by workload-aware graph locality, and expose cross-partition semantics rather than hiding them. +12. Publish qualified wins per workload cell; never promise a universal tenfold advantage. + +## 9. Evidence gaps to close before publication + +- Exact current version and release date. +- Exact license text for the benchmarked artifact. +- Storage bytes per node/edge/property on all standard datasets. +- Stable-edge-ID and parallel-edge semantics. +- Isolation litmus results and commit acknowledgement point. +- Crash recovery time versus dirty WAL size. +- Supernode behavior and maximum tested degree. +- Cold-start metadata and request count. +- Distributed cross-partition query amplification. +- Peak memory under skew, cancellation, and overload. +- Background compaction/GC effect on tail latency. +- Full load/index/checkpoint/backup resource cost. +- Reproducible largest-scale result. +- Independent or audited benchmark evidence. + +## 10. Primary and official sources + +- [Systems paper](https://doi.org/10.1162/dint_a_00229) +- [Source repository](https://github.com/MillenniumDB/MillenniumDB) +- [LDBC SNB Interactive and audited disclosures](https://ldbcouncil.org/benchmarks/snb/interactive/) +- [LDBC Graphalytics](https://ldbcouncil.org/benchmarks/graphalytics/) +- [SoK: The Faults in our Graph Benchmarks](https://arxiv.org/abs/2404.00766) + +## 11. Source-handling rules + +- Official documentation and source are evidence for implemented or declared behavior, not independent performance. +- A vendor benchmark is labeled vendor claim until the harness reproduces it. +- A peer-reviewed paper establishes only the version, configuration, and workload it evaluated. +- Search snippets, comparison sites, and unsourced blogs are discovery aids, not final evidence. +- Unknown is a valid result and creates a concrete experiment or source-inspection task. +- All web facts are rechecked at benchmark freeze because this corpus is current only through the research date. + +## 12. Reproduction record template + +- engine: `MillenniumDB` +- version: `TBD at benchmark freeze` +- artifact digest: `TBD` +- source commit: `TBD or managed-service N/A` +- edition/license: `TBD` +- query language/version: `TBD` +- storage and durability mode: `TBD` +- cluster and replication: `TBD` +- CPU/RAM/NVMe/network: `TBD` +- OS/kernel/filesystem: `TBD` +- dataset URI and digest: `TBD` +- loader command and duration: `TBD` +- physical bytes by category: `TBD` +- tuning file: `TBD` +- query corpus commit: `TBD` +- raw result URI/digest: `TBD` +- profiler/trace URI: `TBD` +- correctness status: `TBD` +- reviewer and rerun date: `TBD` diff --git a/docs/research/engine-nebulagraph.md b/docs/research/engine-nebulagraph.md new file mode 100644 index 0000000..2fc97f5 --- /dev/null +++ b/docs/research/engine-nebulagraph.md @@ -0,0 +1,885 @@ +# NebulaGraph: 2026 deep technical and competitive specification + +Research cut: `2026-08-08` +Status: evidence-backed competitor audit; not a vendor endorsement +Family: `distributed property graph` +Evidence convention: **Observed/official**, **Vendor claim**, **Research inference**, **Unknown**, **Qualification target**. + +## 1. Decision summary + +Nebula is a major distributed/GQL comparator and a warning against hiding network traversal behind one latency number. + +This document answers two questions: what this engine actually proves in 2026, and what zu must build or measure to earn a defensible advantage. A missing public detail remains unknown; it is never silently filled with a favorable assumption. + +### Snapshot card + +- Lifecycle: active; Enterprise 5.2 was current in the 2025 review. +- Data model: schema-full property graph. +- Query surface: GQL in Enterprise 5.x; nGQL in open-source lineage. +- Persistent layout: shared-nothing partitioned KV-oriented graph storage with prefix-scan formats and bucketed partitions in 5.x. +- Execution: distributed vectorized execution, query-level memory control, pushdown, and graph-native plans. +- Transactions: Raft replication and distributed transactions vary by operation/version; verify exact contract. +- Distribution: compute/storage separation, partition buckets, Raft groups, multi-cluster management. +- Object-storage posture: not S3-native in the query path. +- License/commercial boundary: Apache-2.0 open-source 3.x; Enterprise 5.x proprietary. +- Scale evidence: vendor describes 200-TB clusters; PB qualification not established. +- Benchmark posture: separate open-source 3.x from Enterprise 5.x in every result. + +### Facts that materially affect comparison + +- F01 — Enterprise 5.x was redesigned around ISO GQL rather than only adding surface syntax. +- F02 — The 5.x memory interchange format is described as Arrow-compatible Nebula Vector. +- F03 — Partitions are divided into fixed-size buckets to improve movement and rebalancing. +- F04 — Published 3x claims compare with its own previous version and are not competitor evidence. +- F05 — The most relevant zu lessons are batched storage pushdown and explicit query memory accounting. + +### Bottom-line fit against zu's target + +- Very-low latency: compare hot point and bounded traversal paths; never extrapolate from scans or algorithms. +- Very-low resources: charge resident set, page cache, remote cache, background services, and replicas. +- Distributed: distinguish read replication, partitioned capacity, distributed transactions, and elastic stateless compute. +- Fixed cost: no engine has fixed marginal cost by declaration; admission, batching, and capacity reservations create the bound. +- S3 authority: backups, imports, lake scans, and S3-native demand paging are four different architectures. +- PB / trillion-edge scale: require a capacity derivation plus a run at the largest affordable scale; marketing adjectives do not qualify. +- Tenfold win: can be a per-cell qualification result, never a universal statement across incomparable workloads. + +## 2. Product and ecosystem boundary + +The audited unit is **NebulaGraph** in the exact release, edition, deployment, and durability mode recorded by the harness. The family classification is **distributed property graph**. The current lifecycle statement is: active; Enterprise 5.2 was current in the 2025 review. + +The harness must record binary/container digest, source commit when available, build flags, plugins, license/edition, language mode, storage mode, cluster topology, replication factor, durability settings, cache sizes, thread counts, NUMA policy, kernel, filesystem, cloud region, and all environment variables that affect execution. + +A managed service is not placed in a same-hardware chart. It receives a service-level result with provisioned units, region, public price, and observed provider metrics. A historical engine remains useful for regression but cannot support a claim about beating all current competitors. + +## 3. Architecture reconstruction + +### 3.1 Logical model + +NebulaGraph exposes schema-full property graph. The conformance corpus must test nulls, missing properties, labels/types, direction, self-loops, parallel edges, element equality, path equality, bag semantics, ordering, numeric overflow, string collation, temporal values, and schema evolution. + +### 3.2 Language and compiler + +The public query surface is GQL in Enterprise 5.x; nGQL in open-source lineage. Syntax similarity is not semantic equivalence. Every supported construct needs a result oracle and an unsupported-feature declaration. + +### 3.3 Storage + +The best supported storage summary is: shared-nothing partitioned KV-oriented graph storage with prefix-scan formats and bucketed partitions in 5.x. This statement must be refined from code, format documentation, or provider counters before using it in a performance explanation. + +### 3.4 Execution + +The best supported execution summary is: distributed vectorized execution, query-level memory control, pushdown, and graph-native plans. The benchmark profiler must confirm which runtime and operators actually executed. + +### 3.5 Transactions and recovery + +The public contract is: Raft replication and distributed transactions vary by operation/version; verify exact contract. Exact acknowledgement, isolation anomalies, recovery bounds, and failover behavior remain separate qualification items. + +### 3.6 Distribution + +The deployment shape is: compute/storage separation, partition buckets, Raft groups, multi-cluster management. Replication is not capacity sharding; sharding is not distributed ACID; stateless readers are not stateless storage. + +### 3.7 Object storage and cost + +The 2026 posture is: not S3-native in the query path. The audit distinguishes authoritative live bytes, derived acceleration, backup, import/export, and spill. + +## 4. Forty-control deep audit + +### 4.1 `product_boundary` + +Audit question: What exact executable, edition, and storage mode is the system under test? + +Current assessment: Pin NebulaGraph, lifecycle `active; Enterprise 5.2 was current in the 2025 review`, and its edition/mode. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.2 `authority` + +Audit question: Which durable component is the source of truth after every acknowledged write? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.3 `identity` + +Audit question: Are node and edge identities stable across compaction, export, replication, and restore? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.4 `parallel_edges` + +Audit question: Can distinct parallel edges retain properties and trail identity end to end? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.5 `schema` + +Audit question: Is the schema open, closed, optional, inferred, or externally mapped? + +Current assessment: Start from `schema-full property graph` and test actual constraints. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.6 `labels` + +Audit question: How are multiple labels represented and indexed? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.7 `adjacency_out` + +Audit question: How is outgoing adjacency located, encoded, split, cached, and updated? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.8 `adjacency_in` + +Audit question: Is incoming adjacency first-class, derived, replicated, or a fan-out operation? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.9 `supernodes` + +Audit question: How are million-to-billion-degree vertices represented and scheduled? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.10 `properties` + +Audit question: Are properties co-located, columnar, row-oriented, document-encoded, or remote? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.11 `compression` + +Audit question: Which topology, integer, string, null, and floating encodings are implemented? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.12 `checksums` + +Audit question: What integrity unit is verified on point reads and range reads? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.13 `snapshot` + +Audit question: What exact token pins graph data, schema, statistics, and indexes? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.14 `isolation` + +Audit question: Which anomalies are forbidden at the documented isolation level? + +Current assessment: Published summary: Raft replication and distributed transactions vary by operation/version; verify exact contract. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.15 `durability` + +Audit question: What device/service acknowledgement is required before commit returns? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.16 `recovery` + +Audit question: What bounds restart work after a clean stop and a crash? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.17 `writer_fencing` + +Audit question: Can a stale writer acknowledge after failover or lease expiry? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.18 `partitioning` + +Audit question: What key determines placement and what happens to cross-partition edges? + +Current assessment: Published distribution summary: compute/storage separation, partition buckets, Raft groups, multi-cluster management. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.19 `rebalancing` + +Audit question: Can placement change online without changing logical identity? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.20 `replication` + +Audit question: Are replicas full, sharded, synchronous, asynchronous, or shared-storage readers? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.21 `optimizer` + +Audit question: Does the optimizer cost graph expansion, joins, network, cache, and remote requests? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.22 `statistics` + +Audit question: Which degree, correlation, path, and property statistics are persistent? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.23 `execution` + +Audit question: Is execution tuple-at-a-time, vectorized, factorized, compiled, matrix, or actor based? + +Current assessment: Expected family: distributed vectorized execution, query-level memory control, pushdown, and graph-native plans. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.24 `recursion` + +Audit question: How are BFS, shortest paths, trails, simple paths, and arbitrary reachability executed? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.25 `parallelism` + +Audit question: How does the engine avoid skew and nested parallelism under mixed queries? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.26 `memory` + +Audit question: Are all variable allocations charged to bounded query and system budgets? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.27 `spill` + +Audit question: Which operators spill, in what format, and with what admission controls? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.28 `cancellation` + +Audit question: Can cancellation stop CPU, local I/O, remote I/O, retries, and prefetch? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.29 `cache` + +Audit question: What is cached, how is it keyed, admitted, pinned, and evicted? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.30 `cold_start` + +Audit question: What metadata and data round trips are required with empty caches? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.31 `object_requests` + +Audit question: Can a query issue one remote request per node, edge, or result row? + +Current assessment: Published object-store posture: not S3-native in the query path. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.32 `cost_admission` + +Audit question: Are request, byte, CPU, spill, and result limits enforced before work? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.33 `observability` + +Audit question: Can operators report rows, edges, bytes, requests, stalls, memory, and spill? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.34 `language` + +Audit question: Which GQL/Cypher/SQL-PGQ/Gremlin/SPARQL semantics are declared and tested? + +Current assessment: Declared surface: GQL in Enterprise 5.x; nGQL in open-source lineage. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.35 `updates` + +Audit question: Are DDL, insert, merge, update, detach delete, and constraints complete? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.36 `bulk_load` + +Audit question: Does bulk load preserve transactional and index invariants? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.37 `backup` + +Audit question: Is backup consistent, incremental, immutable, and restore-tested? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.38 `gc` + +Audit question: How are old snapshots, orphan objects, tombstones, and indexes reclaimed safely? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.39 `security` + +Audit question: Are authentication, authorization, encryption, audit, and tenant isolation in scope? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.40 `operations` + +Audit question: What compaction, upgrade, repair, verification, and capacity procedures exist? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +## 5. Benchmark contract for this engine + +Every case runs correctness first, then isolated latency, then closed-loop concurrency, then open-loop overload. Report median, p95, p99, p99.9, timeout/rejection rate, throughput, CPU-seconds, peak RSS, cache bytes, disk bytes, network bytes, remote requests, write amplification, and estimated monthly cost. + +Warm means all intended engine caches are populated without changing the query parameters. Hot means the exact working set is resident. Cold means process-local, engine, OS, NVMe, and remote cache state are explicitly reset or a fresh namespace is used. Those words are never inferred from repetition count. + +### 5.1 `point_pk` — primary-key node lookup with one projected property + +- Applicability to NebulaGraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.2 `point_edge` — stable edge-ID lookup including endpoints and one property + +- Applicability to NebulaGraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.3 `degree_1` — degree-one outgoing expansion + +- Applicability to NebulaGraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.4 `degree_32` — small adjacency expansion around degree 32 + +- Applicability to NebulaGraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.5 `degree_1k` — medium adjacency expansion around degree 1,024 + +- Applicability to NebulaGraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.6 `supernode` — range-limited expansion of a ten-million-degree supernode + +- Applicability to NebulaGraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.7 `expand_2` — selective two-hop expansion + +- Applicability to NebulaGraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.8 `expand_3` — three-hop frontier expansion with duplicate control + +- Applicability to NebulaGraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.9 `expand_into` — edge-existence/expand-into between already-bound endpoints + +- Applicability to NebulaGraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.10 `multi_edge` — parallel-edge identity and property projection + +- Applicability to NebulaGraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.11 `shortest` — bidirectional point-to-point unweighted shortest path + +- Applicability to NebulaGraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.12 `weighted` — weighted shortest path with property access + +- Applicability to NebulaGraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.13 `var_walk` — bounded variable-length walk + +- Applicability to NebulaGraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.14 `trail` — DIFFERENT EDGES trail enumeration + +- Applicability to NebulaGraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.15 `simple` — simple-path enumeration with explicit bound + +- Applicability to NebulaGraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.16 `triangle` — triangle pattern with worst-case-sensitive join + +- Applicability to NebulaGraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.17 `cycle4` — four-cycle pattern + +- Applicability to NebulaGraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.18 `star_join` — high-fanout star pattern with property filters + +- Applicability to NebulaGraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.19 `optional` — optional match preserving null/bag semantics + +- Applicability to NebulaGraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.20 `aggregate` — grouped aggregate after traversal + +- Applicability to NebulaGraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.21 `topk` — ordered top-k with late property materialization + +- Applicability to NebulaGraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.22 `scan` — full projected property scan + +- Applicability to NebulaGraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.23 `selective_scan` — zone/index-pruned selective property scan + +- Applicability to NebulaGraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.24 `mixed` — concurrent short reads, complex reads, and updates + +- Applicability to NebulaGraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.25 `ingest` — sustained transactional ingest with indexes enabled + +- Applicability to NebulaGraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.26 `bulk` — initial bulk load including index/CSR build + +- Applicability to NebulaGraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.27 `checkpoint` — checkpoint or compaction while readers remain active + +- Applicability to NebulaGraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.28 `recovery` — crash recovery at bounded dirty-log size + +- Applicability to NebulaGraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.29 `cold` — same query after clearing engine and OS/cache tiers + +- Applicability to NebulaGraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.30 `remote` — same query with authoritative bytes only in object storage + +- Applicability to NebulaGraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +## 6. Fairness controls + +- Same logical dataset and update stream; engine-native physical layouts are allowed and disclosed. +- Same result semantics; unsupported queries remain unsupported rather than rewritten into easier questions. +- Same durable acknowledgement class for write comparisons. +- Same number of physical cores and memory limit for self-hosted single-node tests. +- Same aggregate resources and replication fault tolerance for distributed tests. +- Officially recommended tuning may be applied before the freeze and is committed with rationale. +- Query-specific hints are allowed only when equivalent hints are offered to every engine and separately charted. +- Load/build/index time and bytes are first-class results. +- Cold, warm, and hot results are separate charts. +- Managed services use public configurations and cannot borrow hidden same-machine resource claims. +- Failed runs, OOMs, correctness mismatches, and timeouts stay in the dataset. +- Every chart links raw samples and the exact reproduction command. + +## 7. Likely advantages and limits + +The strongest known reason to choose this engine is tied to its family `distributed property graph`, its execution path `distributed vectorized execution, query-level memory control, pushdown, and graph-native plans`, and its existing ecosystem. The strongest reason to reject it for zu's target is the gap between `not S3-native in the query path` and an S3-authoritative, request-budgeted, PB-scale graph service. + +Capacity statement: vendor describes 200-TB clusters; PB qualification not established. This is not converted into an edge-count claim without a physical byte model including IDs, both adjacency directions, properties, indexes, MVCC, WAL, replicas, and free space. + +Commercial statement: Apache-2.0 open-source 3.x; Enterprise 5.x proprietary. License cost, support cost, and unavailable enterprise capabilities remain visible in TCO and feature tables. + +## 8. Concrete lessons for zu + +1. Keep stable logical node and edge identity independent of row group, CSR slot, shard, and object range. +2. Store forward and reverse adjacency as immutable range-addressable tiles carrying edge IDs. +3. Feed queries adjacency batches and typed vectors; prohibit one storage call per logical element. +4. Use vectorized/factorized execution for property-heavy patterns and dedicated frontier operators for recursion. +5. Cost topology, properties, network, cache certainty, remote requests, and result materialization together. +6. Separate the local embedded profile from the object-authoritative distributed read profile. +7. Fence writers with monotonic epochs and make ambiguous commits reconcilable by transaction ID. +8. Pack small graph tiles into large immutable objects while retaining independent checksums and range offsets. +9. Keep the hot topology working set in RAM/NVMe; batch cold frontier misses into few remote rounds. +10. Admission-control remote requests and bytes so fixed-price plans have an enforceable upper bound. +11. Partition by workload-aware graph locality, and expose cross-partition semantics rather than hiding them. +12. Publish qualified wins per workload cell; never promise a universal tenfold advantage. + +## 9. Evidence gaps to close before publication + +- Exact current version and release date. +- Exact license text for the benchmarked artifact. +- Storage bytes per node/edge/property on all standard datasets. +- Stable-edge-ID and parallel-edge semantics. +- Isolation litmus results and commit acknowledgement point. +- Crash recovery time versus dirty WAL size. +- Supernode behavior and maximum tested degree. +- Cold-start metadata and request count. +- Distributed cross-partition query amplification. +- Peak memory under skew, cancellation, and overload. +- Background compaction/GC effect on tail latency. +- Full load/index/checkpoint/backup resource cost. +- Reproducible largest-scale result. +- Independent or audited benchmark evidence. + +## 10. Primary and official sources + +- [5.0 technical preview](https://nebula-graph.io/posts/technical-preview-of-nebulagraph-enterprise-v5.0) +- [2025 year review](https://nebula-graph.io/posts/nebulagraph-2025-year-in-review-charting-a-new-era-of-graph-intelligence-and-ai-convergence) +- [Source repository](https://github.com/vesoft-inc/nebula) +- [LDBC SNB Interactive and audited disclosures](https://ldbcouncil.org/benchmarks/snb/interactive/) +- [LDBC Graphalytics](https://ldbcouncil.org/benchmarks/graphalytics/) +- [SoK: The Faults in our Graph Benchmarks](https://arxiv.org/abs/2404.00766) + +## 11. Source-handling rules + +- Official documentation and source are evidence for implemented or declared behavior, not independent performance. +- A vendor benchmark is labeled vendor claim until the harness reproduces it. +- A peer-reviewed paper establishes only the version, configuration, and workload it evaluated. +- Search snippets, comparison sites, and unsourced blogs are discovery aids, not final evidence. +- Unknown is a valid result and creates a concrete experiment or source-inspection task. +- All web facts are rechecked at benchmark freeze because this corpus is current only through the research date. + +## 12. Reproduction record template + +- engine: `NebulaGraph` +- version: `TBD at benchmark freeze` +- artifact digest: `TBD` +- source commit: `TBD or managed-service N/A` +- edition/license: `TBD` +- query language/version: `TBD` +- storage and durability mode: `TBD` +- cluster and replication: `TBD` +- CPU/RAM/NVMe/network: `TBD` +- OS/kernel/filesystem: `TBD` +- dataset URI and digest: `TBD` +- loader command and duration: `TBD` +- physical bytes by category: `TBD` +- tuning file: `TBD` +- query corpus commit: `TBD` +- raw result URI/digest: `TBD` +- profiler/trace URI: `TBD` +- correctness status: `TBD` +- reviewer and rerun date: `TBD` diff --git a/docs/research/engine-neo4j.md b/docs/research/engine-neo4j.md new file mode 100644 index 0000000..cd27b07 --- /dev/null +++ b/docs/research/engine-neo4j.md @@ -0,0 +1,885 @@ +# Neo4j: 2026 deep technical and competitive specification + +Research cut: `2026-08-08` +Status: evidence-backed competitor audit; not a vendor endorsement +Family: `native property graph` +Evidence convention: **Observed/official**, **Vendor claim**, **Research inference**, **Unknown**, **Qualification target**. + +## 1. Decision summary + +The ecosystem and Cypher compatibility bar are formidable; storage cost, JVM footprint, and distributed-license cost are openings for zu. + +This document answers two questions: what this engine actually proves in 2026, and what zu must build or measure to earn a defensible advantage. A missing public detail remains unknown; it is never silently filled with a favorable assumption. + +### Snapshot card + +- Lifecycle: active; calendar-versioned 2026 line. +- Data model: labeled property graph. +- Query surface: Cypher 25 and frozen Cypher 5. +- Persistent layout: native block record store with page cache; sharded Infinigraph separates topology and properties. +- Execution: cost-based optimizer with slotted, pipelined, and parallel runtimes. +- Transactions: ACID; clustered editions add consensus-backed availability. +- Distribution: standalone, clustered, composite databases, and Infinigraph automatic sharding. +- Object-storage posture: not S3-native for the live query path; object storage is operational/backup infrastructure. +- License/commercial boundary: GPLv3 Community; commercial Enterprise/Infinigraph. +- Scale evidence: single-store formats have finite ID domains; Infinigraph is the 100-TB-plus horizontal path. +- Benchmark posture: industry baseline with LDBC and vendor workloads, but edition and runtime must be pinned. + +### Facts that materially affect comparison + +- F01 — Neo4j 2026.02 defaults new deployments to Cypher 25 through the distributed configuration. +- F02 — The current manual distinguishes Community, Enterprise, and Infinigraph; benchmark results must never mix them. +- F03 — Infinigraph uses graph and property sharding rather than presenting one monolithic local store. +- F04 — Block format is the relevant current local format; deprecated high-limit claims must not be used as current evidence. +- F05 — Warm page-cache traversal is a strong baseline; cold S3 claims would be a category error. + +### Bottom-line fit against zu's target + +- Very-low latency: compare hot point and bounded traversal paths; never extrapolate from scans or algorithms. +- Very-low resources: charge resident set, page cache, remote cache, background services, and replicas. +- Distributed: distinguish read replication, partitioned capacity, distributed transactions, and elastic stateless compute. +- Fixed cost: no engine has fixed marginal cost by declaration; admission, batching, and capacity reservations create the bound. +- S3 authority: backups, imports, lake scans, and S3-native demand paging are four different architectures. +- PB / trillion-edge scale: require a capacity derivation plus a run at the largest affordable scale; marketing adjectives do not qualify. +- Tenfold win: can be a per-cell qualification result, never a universal statement across incomparable workloads. + +## 2. Product and ecosystem boundary + +The audited unit is **Neo4j** in the exact release, edition, deployment, and durability mode recorded by the harness. The family classification is **native property graph**. The current lifecycle statement is: active; calendar-versioned 2026 line. + +The harness must record binary/container digest, source commit when available, build flags, plugins, license/edition, language mode, storage mode, cluster topology, replication factor, durability settings, cache sizes, thread counts, NUMA policy, kernel, filesystem, cloud region, and all environment variables that affect execution. + +A managed service is not placed in a same-hardware chart. It receives a service-level result with provisioned units, region, public price, and observed provider metrics. A historical engine remains useful for regression but cannot support a claim about beating all current competitors. + +## 3. Architecture reconstruction + +### 3.1 Logical model + +Neo4j exposes labeled property graph. The conformance corpus must test nulls, missing properties, labels/types, direction, self-loops, parallel edges, element equality, path equality, bag semantics, ordering, numeric overflow, string collation, temporal values, and schema evolution. + +### 3.2 Language and compiler + +The public query surface is Cypher 25 and frozen Cypher 5. Syntax similarity is not semantic equivalence. Every supported construct needs a result oracle and an unsupported-feature declaration. + +### 3.3 Storage + +The best supported storage summary is: native block record store with page cache; sharded Infinigraph separates topology and properties. This statement must be refined from code, format documentation, or provider counters before using it in a performance explanation. + +### 3.4 Execution + +The best supported execution summary is: cost-based optimizer with slotted, pipelined, and parallel runtimes. The benchmark profiler must confirm which runtime and operators actually executed. + +### 3.5 Transactions and recovery + +The public contract is: ACID; clustered editions add consensus-backed availability. Exact acknowledgement, isolation anomalies, recovery bounds, and failover behavior remain separate qualification items. + +### 3.6 Distribution + +The deployment shape is: standalone, clustered, composite databases, and Infinigraph automatic sharding. Replication is not capacity sharding; sharding is not distributed ACID; stateless readers are not stateless storage. + +### 3.7 Object storage and cost + +The 2026 posture is: not S3-native for the live query path; object storage is operational/backup infrastructure. The audit distinguishes authoritative live bytes, derived acceleration, backup, import/export, and spill. + +## 4. Forty-control deep audit + +### 4.1 `product_boundary` + +Audit question: What exact executable, edition, and storage mode is the system under test? + +Current assessment: Pin Neo4j, lifecycle `active; calendar-versioned 2026 line`, and its edition/mode. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.2 `authority` + +Audit question: Which durable component is the source of truth after every acknowledged write? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.3 `identity` + +Audit question: Are node and edge identities stable across compaction, export, replication, and restore? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.4 `parallel_edges` + +Audit question: Can distinct parallel edges retain properties and trail identity end to end? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.5 `schema` + +Audit question: Is the schema open, closed, optional, inferred, or externally mapped? + +Current assessment: Start from `labeled property graph` and test actual constraints. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.6 `labels` + +Audit question: How are multiple labels represented and indexed? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.7 `adjacency_out` + +Audit question: How is outgoing adjacency located, encoded, split, cached, and updated? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.8 `adjacency_in` + +Audit question: Is incoming adjacency first-class, derived, replicated, or a fan-out operation? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.9 `supernodes` + +Audit question: How are million-to-billion-degree vertices represented and scheduled? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.10 `properties` + +Audit question: Are properties co-located, columnar, row-oriented, document-encoded, or remote? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.11 `compression` + +Audit question: Which topology, integer, string, null, and floating encodings are implemented? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.12 `checksums` + +Audit question: What integrity unit is verified on point reads and range reads? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.13 `snapshot` + +Audit question: What exact token pins graph data, schema, statistics, and indexes? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.14 `isolation` + +Audit question: Which anomalies are forbidden at the documented isolation level? + +Current assessment: Published summary: ACID; clustered editions add consensus-backed availability. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.15 `durability` + +Audit question: What device/service acknowledgement is required before commit returns? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.16 `recovery` + +Audit question: What bounds restart work after a clean stop and a crash? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.17 `writer_fencing` + +Audit question: Can a stale writer acknowledge after failover or lease expiry? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.18 `partitioning` + +Audit question: What key determines placement and what happens to cross-partition edges? + +Current assessment: Published distribution summary: standalone, clustered, composite databases, and Infinigraph automatic sharding. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.19 `rebalancing` + +Audit question: Can placement change online without changing logical identity? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.20 `replication` + +Audit question: Are replicas full, sharded, synchronous, asynchronous, or shared-storage readers? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.21 `optimizer` + +Audit question: Does the optimizer cost graph expansion, joins, network, cache, and remote requests? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.22 `statistics` + +Audit question: Which degree, correlation, path, and property statistics are persistent? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.23 `execution` + +Audit question: Is execution tuple-at-a-time, vectorized, factorized, compiled, matrix, or actor based? + +Current assessment: Expected family: cost-based optimizer with slotted, pipelined, and parallel runtimes. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.24 `recursion` + +Audit question: How are BFS, shortest paths, trails, simple paths, and arbitrary reachability executed? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.25 `parallelism` + +Audit question: How does the engine avoid skew and nested parallelism under mixed queries? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.26 `memory` + +Audit question: Are all variable allocations charged to bounded query and system budgets? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.27 `spill` + +Audit question: Which operators spill, in what format, and with what admission controls? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.28 `cancellation` + +Audit question: Can cancellation stop CPU, local I/O, remote I/O, retries, and prefetch? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.29 `cache` + +Audit question: What is cached, how is it keyed, admitted, pinned, and evicted? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.30 `cold_start` + +Audit question: What metadata and data round trips are required with empty caches? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.31 `object_requests` + +Audit question: Can a query issue one remote request per node, edge, or result row? + +Current assessment: Published object-store posture: not S3-native for the live query path; object storage is operational/backup infrastructure. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.32 `cost_admission` + +Audit question: Are request, byte, CPU, spill, and result limits enforced before work? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.33 `observability` + +Audit question: Can operators report rows, edges, bytes, requests, stalls, memory, and spill? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.34 `language` + +Audit question: Which GQL/Cypher/SQL-PGQ/Gremlin/SPARQL semantics are declared and tested? + +Current assessment: Declared surface: Cypher 25 and frozen Cypher 5. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.35 `updates` + +Audit question: Are DDL, insert, merge, update, detach delete, and constraints complete? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.36 `bulk_load` + +Audit question: Does bulk load preserve transactional and index invariants? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.37 `backup` + +Audit question: Is backup consistent, incremental, immutable, and restore-tested? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.38 `gc` + +Audit question: How are old snapshots, orphan objects, tombstones, and indexes reclaimed safely? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.39 `security` + +Audit question: Are authentication, authorization, encryption, audit, and tenant isolation in scope? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.40 `operations` + +Audit question: What compaction, upgrade, repair, verification, and capacity procedures exist? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +## 5. Benchmark contract for this engine + +Every case runs correctness first, then isolated latency, then closed-loop concurrency, then open-loop overload. Report median, p95, p99, p99.9, timeout/rejection rate, throughput, CPU-seconds, peak RSS, cache bytes, disk bytes, network bytes, remote requests, write amplification, and estimated monthly cost. + +Warm means all intended engine caches are populated without changing the query parameters. Hot means the exact working set is resident. Cold means process-local, engine, OS, NVMe, and remote cache state are explicitly reset or a fresh namespace is used. Those words are never inferred from repetition count. + +### 5.1 `point_pk` — primary-key node lookup with one projected property + +- Applicability to Neo4j: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.2 `point_edge` — stable edge-ID lookup including endpoints and one property + +- Applicability to Neo4j: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.3 `degree_1` — degree-one outgoing expansion + +- Applicability to Neo4j: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.4 `degree_32` — small adjacency expansion around degree 32 + +- Applicability to Neo4j: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.5 `degree_1k` — medium adjacency expansion around degree 1,024 + +- Applicability to Neo4j: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.6 `supernode` — range-limited expansion of a ten-million-degree supernode + +- Applicability to Neo4j: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.7 `expand_2` — selective two-hop expansion + +- Applicability to Neo4j: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.8 `expand_3` — three-hop frontier expansion with duplicate control + +- Applicability to Neo4j: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.9 `expand_into` — edge-existence/expand-into between already-bound endpoints + +- Applicability to Neo4j: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.10 `multi_edge` — parallel-edge identity and property projection + +- Applicability to Neo4j: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.11 `shortest` — bidirectional point-to-point unweighted shortest path + +- Applicability to Neo4j: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.12 `weighted` — weighted shortest path with property access + +- Applicability to Neo4j: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.13 `var_walk` — bounded variable-length walk + +- Applicability to Neo4j: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.14 `trail` — DIFFERENT EDGES trail enumeration + +- Applicability to Neo4j: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.15 `simple` — simple-path enumeration with explicit bound + +- Applicability to Neo4j: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.16 `triangle` — triangle pattern with worst-case-sensitive join + +- Applicability to Neo4j: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.17 `cycle4` — four-cycle pattern + +- Applicability to Neo4j: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.18 `star_join` — high-fanout star pattern with property filters + +- Applicability to Neo4j: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.19 `optional` — optional match preserving null/bag semantics + +- Applicability to Neo4j: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.20 `aggregate` — grouped aggregate after traversal + +- Applicability to Neo4j: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.21 `topk` — ordered top-k with late property materialization + +- Applicability to Neo4j: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.22 `scan` — full projected property scan + +- Applicability to Neo4j: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.23 `selective_scan` — zone/index-pruned selective property scan + +- Applicability to Neo4j: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.24 `mixed` — concurrent short reads, complex reads, and updates + +- Applicability to Neo4j: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.25 `ingest` — sustained transactional ingest with indexes enabled + +- Applicability to Neo4j: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.26 `bulk` — initial bulk load including index/CSR build + +- Applicability to Neo4j: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.27 `checkpoint` — checkpoint or compaction while readers remain active + +- Applicability to Neo4j: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.28 `recovery` — crash recovery at bounded dirty-log size + +- Applicability to Neo4j: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.29 `cold` — same query after clearing engine and OS/cache tiers + +- Applicability to Neo4j: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.30 `remote` — same query with authoritative bytes only in object storage + +- Applicability to Neo4j: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +## 6. Fairness controls + +- Same logical dataset and update stream; engine-native physical layouts are allowed and disclosed. +- Same result semantics; unsupported queries remain unsupported rather than rewritten into easier questions. +- Same durable acknowledgement class for write comparisons. +- Same number of physical cores and memory limit for self-hosted single-node tests. +- Same aggregate resources and replication fault tolerance for distributed tests. +- Officially recommended tuning may be applied before the freeze and is committed with rationale. +- Query-specific hints are allowed only when equivalent hints are offered to every engine and separately charted. +- Load/build/index time and bytes are first-class results. +- Cold, warm, and hot results are separate charts. +- Managed services use public configurations and cannot borrow hidden same-machine resource claims. +- Failed runs, OOMs, correctness mismatches, and timeouts stay in the dataset. +- Every chart links raw samples and the exact reproduction command. + +## 7. Likely advantages and limits + +The strongest known reason to choose this engine is tied to its family `native property graph`, its execution path `cost-based optimizer with slotted, pipelined, and parallel runtimes`, and its existing ecosystem. The strongest reason to reject it for zu's target is the gap between `not S3-native for the live query path; object storage is operational/backup infrastructure` and an S3-authoritative, request-budgeted, PB-scale graph service. + +Capacity statement: single-store formats have finite ID domains; Infinigraph is the 100-TB-plus horizontal path. This is not converted into an edge-count claim without a physical byte model including IDs, both adjacency directions, properties, indexes, MVCC, WAL, replicas, and free space. + +Commercial statement: GPLv3 Community; commercial Enterprise/Infinigraph. License cost, support cost, and unavailable enterprise capabilities remain visible in TCO and feature tables. + +## 8. Concrete lessons for zu + +1. Keep stable logical node and edge identity independent of row group, CSR slot, shard, and object range. +2. Store forward and reverse adjacency as immutable range-addressable tiles carrying edge IDs. +3. Feed queries adjacency batches and typed vectors; prohibit one storage call per logical element. +4. Use vectorized/factorized execution for property-heavy patterns and dedicated frontier operators for recursion. +5. Cost topology, properties, network, cache certainty, remote requests, and result materialization together. +6. Separate the local embedded profile from the object-authoritative distributed read profile. +7. Fence writers with monotonic epochs and make ambiguous commits reconcilable by transaction ID. +8. Pack small graph tiles into large immutable objects while retaining independent checksums and range offsets. +9. Keep the hot topology working set in RAM/NVMe; batch cold frontier misses into few remote rounds. +10. Admission-control remote requests and bytes so fixed-price plans have an enforceable upper bound. +11. Partition by workload-aware graph locality, and expose cross-partition semantics rather than hiding them. +12. Publish qualified wins per workload cell; never promise a universal tenfold advantage. + +## 9. Evidence gaps to close before publication + +- Exact current version and release date. +- Exact license text for the benchmarked artifact. +- Storage bytes per node/edge/property on all standard datasets. +- Stable-edge-ID and parallel-edge semantics. +- Isolation litmus results and commit acknowledgement point. +- Crash recovery time versus dirty WAL size. +- Supernode behavior and maximum tested degree. +- Cold-start metadata and request count. +- Distributed cross-partition query amplification. +- Peak memory under skew, cancellation, and overload. +- Background compaction/GC effect on tail latency. +- Full load/index/checkpoint/backup resource cost. +- Reproducible largest-scale result. +- Independent or audited benchmark evidence. + +## 10. Primary and official sources + +- [Operations Manual](https://neo4j.com/docs/operations-manual/current/introduction/) +- [Cypher version administration](https://neo4j.com/docs/operations-manual/current/database-administration/syntax/) +- [Source repository](https://github.com/neo4j/neo4j) +- [LDBC SNB Interactive and audited disclosures](https://ldbcouncil.org/benchmarks/snb/interactive/) +- [LDBC Graphalytics](https://ldbcouncil.org/benchmarks/graphalytics/) +- [SoK: The Faults in our Graph Benchmarks](https://arxiv.org/abs/2404.00766) + +## 11. Source-handling rules + +- Official documentation and source are evidence for implemented or declared behavior, not independent performance. +- A vendor benchmark is labeled vendor claim until the harness reproduces it. +- A peer-reviewed paper establishes only the version, configuration, and workload it evaluated. +- Search snippets, comparison sites, and unsourced blogs are discovery aids, not final evidence. +- Unknown is a valid result and creates a concrete experiment or source-inspection task. +- All web facts are rechecked at benchmark freeze because this corpus is current only through the research date. + +## 12. Reproduction record template + +- engine: `Neo4j` +- version: `TBD at benchmark freeze` +- artifact digest: `TBD` +- source commit: `TBD or managed-service N/A` +- edition/license: `TBD` +- query language/version: `TBD` +- storage and durability mode: `TBD` +- cluster and replication: `TBD` +- CPU/RAM/NVMe/network: `TBD` +- OS/kernel/filesystem: `TBD` +- dataset URI and digest: `TBD` +- loader command and duration: `TBD` +- physical bytes by category: `TBD` +- tuning file: `TBD` +- query corpus commit: `TBD` +- raw result URI/digest: `TBD` +- profiler/trace URI: `TBD` +- correctness status: `TBD` +- reviewer and rerun date: `TBD` diff --git a/docs/research/engine-ontotext_graphdb.md b/docs/research/engine-ontotext_graphdb.md new file mode 100644 index 0000000..6b814c0 --- /dev/null +++ b/docs/research/engine-ontotext_graphdb.md @@ -0,0 +1,885 @@ +# Ontotext GraphDB: 2026 deep technical and competitive specification + +Research cut: `2026-08-08` +Status: evidence-backed competitor audit; not a vendor endorsement +Family: `RDF store and reasoner` +Evidence convention: **Observed/official**, **Vendor claim**, **Research inference**, **Unknown**, **Qualification target**. + +## 1. Decision summary + +GraphDB is the principal materialized-reasoning baseline and a lesson in separating explicit from derived bytes. + +This document answers two questions: what this engine actually proves in 2026, and what zu must build or measure to earn a defensible advantage. A missing public detail remains unknown; it is never silently filled with a favorable assumption. + +### Snapshot card + +- Lifecycle: active 11.x. +- Data model: RDF quads with inferred closure. +- Query surface: SPARQL 1.1 and RDF4J APIs. +- Persistent layout: TRREE storage with POS/PSO/context indices, entity IDs, page cache. +- Execution: RDF4J query layer plus forward-chaining materialization. +- Transactions: transactional repository; inference closure updates at mutation boundaries. +- Distribution: Raft-based HA cluster in current Enterprise line. +- Object-storage posture: not S3-native live serving. +- License/commercial boundary: commercial editions with a free edition. +- Scale evidence: large RDF stores; audited LDBC SNB result exists but workload/language fit must be examined. +- Benchmark posture: include materialization time/space and inferred versus explicit query modes. + +### Facts that materially affect comparison + +- F01 — GraphDB implements the RDF4J SAIL interface. +- F02 — TRREE performs forward-chaining materialization. +- F03 — Storage historically uses two main statement orderings plus context indices. +- F04 — Entity pools map RDF terms to compact numeric IDs. +- F05 — Raft clustering improves HA but does not imply data sharding. + +### Bottom-line fit against zu's target + +- Very-low latency: compare hot point and bounded traversal paths; never extrapolate from scans or algorithms. +- Very-low resources: charge resident set, page cache, remote cache, background services, and replicas. +- Distributed: distinguish read replication, partitioned capacity, distributed transactions, and elastic stateless compute. +- Fixed cost: no engine has fixed marginal cost by declaration; admission, batching, and capacity reservations create the bound. +- S3 authority: backups, imports, lake scans, and S3-native demand paging are four different architectures. +- PB / trillion-edge scale: require a capacity derivation plus a run at the largest affordable scale; marketing adjectives do not qualify. +- Tenfold win: can be a per-cell qualification result, never a universal statement across incomparable workloads. + +## 2. Product and ecosystem boundary + +The audited unit is **Ontotext GraphDB** in the exact release, edition, deployment, and durability mode recorded by the harness. The family classification is **RDF store and reasoner**. The current lifecycle statement is: active 11.x. + +The harness must record binary/container digest, source commit when available, build flags, plugins, license/edition, language mode, storage mode, cluster topology, replication factor, durability settings, cache sizes, thread counts, NUMA policy, kernel, filesystem, cloud region, and all environment variables that affect execution. + +A managed service is not placed in a same-hardware chart. It receives a service-level result with provisioned units, region, public price, and observed provider metrics. A historical engine remains useful for regression but cannot support a claim about beating all current competitors. + +## 3. Architecture reconstruction + +### 3.1 Logical model + +Ontotext GraphDB exposes RDF quads with inferred closure. The conformance corpus must test nulls, missing properties, labels/types, direction, self-loops, parallel edges, element equality, path equality, bag semantics, ordering, numeric overflow, string collation, temporal values, and schema evolution. + +### 3.2 Language and compiler + +The public query surface is SPARQL 1.1 and RDF4J APIs. Syntax similarity is not semantic equivalence. Every supported construct needs a result oracle and an unsupported-feature declaration. + +### 3.3 Storage + +The best supported storage summary is: TRREE storage with POS/PSO/context indices, entity IDs, page cache. This statement must be refined from code, format documentation, or provider counters before using it in a performance explanation. + +### 3.4 Execution + +The best supported execution summary is: RDF4J query layer plus forward-chaining materialization. The benchmark profiler must confirm which runtime and operators actually executed. + +### 3.5 Transactions and recovery + +The public contract is: transactional repository; inference closure updates at mutation boundaries. Exact acknowledgement, isolation anomalies, recovery bounds, and failover behavior remain separate qualification items. + +### 3.6 Distribution + +The deployment shape is: Raft-based HA cluster in current Enterprise line. Replication is not capacity sharding; sharding is not distributed ACID; stateless readers are not stateless storage. + +### 3.7 Object storage and cost + +The 2026 posture is: not S3-native live serving. The audit distinguishes authoritative live bytes, derived acceleration, backup, import/export, and spill. + +## 4. Forty-control deep audit + +### 4.1 `product_boundary` + +Audit question: What exact executable, edition, and storage mode is the system under test? + +Current assessment: Pin Ontotext GraphDB, lifecycle `active 11.x`, and its edition/mode. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.2 `authority` + +Audit question: Which durable component is the source of truth after every acknowledged write? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.3 `identity` + +Audit question: Are node and edge identities stable across compaction, export, replication, and restore? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.4 `parallel_edges` + +Audit question: Can distinct parallel edges retain properties and trail identity end to end? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.5 `schema` + +Audit question: Is the schema open, closed, optional, inferred, or externally mapped? + +Current assessment: Start from `RDF quads with inferred closure` and test actual constraints. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.6 `labels` + +Audit question: How are multiple labels represented and indexed? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.7 `adjacency_out` + +Audit question: How is outgoing adjacency located, encoded, split, cached, and updated? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.8 `adjacency_in` + +Audit question: Is incoming adjacency first-class, derived, replicated, or a fan-out operation? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.9 `supernodes` + +Audit question: How are million-to-billion-degree vertices represented and scheduled? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.10 `properties` + +Audit question: Are properties co-located, columnar, row-oriented, document-encoded, or remote? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.11 `compression` + +Audit question: Which topology, integer, string, null, and floating encodings are implemented? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.12 `checksums` + +Audit question: What integrity unit is verified on point reads and range reads? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.13 `snapshot` + +Audit question: What exact token pins graph data, schema, statistics, and indexes? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.14 `isolation` + +Audit question: Which anomalies are forbidden at the documented isolation level? + +Current assessment: Published summary: transactional repository; inference closure updates at mutation boundaries. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.15 `durability` + +Audit question: What device/service acknowledgement is required before commit returns? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.16 `recovery` + +Audit question: What bounds restart work after a clean stop and a crash? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.17 `writer_fencing` + +Audit question: Can a stale writer acknowledge after failover or lease expiry? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.18 `partitioning` + +Audit question: What key determines placement and what happens to cross-partition edges? + +Current assessment: Published distribution summary: Raft-based HA cluster in current Enterprise line. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.19 `rebalancing` + +Audit question: Can placement change online without changing logical identity? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.20 `replication` + +Audit question: Are replicas full, sharded, synchronous, asynchronous, or shared-storage readers? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.21 `optimizer` + +Audit question: Does the optimizer cost graph expansion, joins, network, cache, and remote requests? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.22 `statistics` + +Audit question: Which degree, correlation, path, and property statistics are persistent? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.23 `execution` + +Audit question: Is execution tuple-at-a-time, vectorized, factorized, compiled, matrix, or actor based? + +Current assessment: Expected family: RDF4J query layer plus forward-chaining materialization. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.24 `recursion` + +Audit question: How are BFS, shortest paths, trails, simple paths, and arbitrary reachability executed? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.25 `parallelism` + +Audit question: How does the engine avoid skew and nested parallelism under mixed queries? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.26 `memory` + +Audit question: Are all variable allocations charged to bounded query and system budgets? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.27 `spill` + +Audit question: Which operators spill, in what format, and with what admission controls? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.28 `cancellation` + +Audit question: Can cancellation stop CPU, local I/O, remote I/O, retries, and prefetch? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.29 `cache` + +Audit question: What is cached, how is it keyed, admitted, pinned, and evicted? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.30 `cold_start` + +Audit question: What metadata and data round trips are required with empty caches? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.31 `object_requests` + +Audit question: Can a query issue one remote request per node, edge, or result row? + +Current assessment: Published object-store posture: not S3-native live serving. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.32 `cost_admission` + +Audit question: Are request, byte, CPU, spill, and result limits enforced before work? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.33 `observability` + +Audit question: Can operators report rows, edges, bytes, requests, stalls, memory, and spill? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.34 `language` + +Audit question: Which GQL/Cypher/SQL-PGQ/Gremlin/SPARQL semantics are declared and tested? + +Current assessment: Declared surface: SPARQL 1.1 and RDF4J APIs. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.35 `updates` + +Audit question: Are DDL, insert, merge, update, detach delete, and constraints complete? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.36 `bulk_load` + +Audit question: Does bulk load preserve transactional and index invariants? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.37 `backup` + +Audit question: Is backup consistent, incremental, immutable, and restore-tested? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.38 `gc` + +Audit question: How are old snapshots, orphan objects, tombstones, and indexes reclaimed safely? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.39 `security` + +Audit question: Are authentication, authorization, encryption, audit, and tenant isolation in scope? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.40 `operations` + +Audit question: What compaction, upgrade, repair, verification, and capacity procedures exist? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +## 5. Benchmark contract for this engine + +Every case runs correctness first, then isolated latency, then closed-loop concurrency, then open-loop overload. Report median, p95, p99, p99.9, timeout/rejection rate, throughput, CPU-seconds, peak RSS, cache bytes, disk bytes, network bytes, remote requests, write amplification, and estimated monthly cost. + +Warm means all intended engine caches are populated without changing the query parameters. Hot means the exact working set is resident. Cold means process-local, engine, OS, NVMe, and remote cache state are explicitly reset or a fresh namespace is used. Those words are never inferred from repetition count. + +### 5.1 `point_pk` — primary-key node lookup with one projected property + +- Applicability to Ontotext GraphDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.2 `point_edge` — stable edge-ID lookup including endpoints and one property + +- Applicability to Ontotext GraphDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.3 `degree_1` — degree-one outgoing expansion + +- Applicability to Ontotext GraphDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.4 `degree_32` — small adjacency expansion around degree 32 + +- Applicability to Ontotext GraphDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.5 `degree_1k` — medium adjacency expansion around degree 1,024 + +- Applicability to Ontotext GraphDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.6 `supernode` — range-limited expansion of a ten-million-degree supernode + +- Applicability to Ontotext GraphDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.7 `expand_2` — selective two-hop expansion + +- Applicability to Ontotext GraphDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.8 `expand_3` — three-hop frontier expansion with duplicate control + +- Applicability to Ontotext GraphDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.9 `expand_into` — edge-existence/expand-into between already-bound endpoints + +- Applicability to Ontotext GraphDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.10 `multi_edge` — parallel-edge identity and property projection + +- Applicability to Ontotext GraphDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.11 `shortest` — bidirectional point-to-point unweighted shortest path + +- Applicability to Ontotext GraphDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.12 `weighted` — weighted shortest path with property access + +- Applicability to Ontotext GraphDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.13 `var_walk` — bounded variable-length walk + +- Applicability to Ontotext GraphDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.14 `trail` — DIFFERENT EDGES trail enumeration + +- Applicability to Ontotext GraphDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.15 `simple` — simple-path enumeration with explicit bound + +- Applicability to Ontotext GraphDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.16 `triangle` — triangle pattern with worst-case-sensitive join + +- Applicability to Ontotext GraphDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.17 `cycle4` — four-cycle pattern + +- Applicability to Ontotext GraphDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.18 `star_join` — high-fanout star pattern with property filters + +- Applicability to Ontotext GraphDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.19 `optional` — optional match preserving null/bag semantics + +- Applicability to Ontotext GraphDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.20 `aggregate` — grouped aggregate after traversal + +- Applicability to Ontotext GraphDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.21 `topk` — ordered top-k with late property materialization + +- Applicability to Ontotext GraphDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.22 `scan` — full projected property scan + +- Applicability to Ontotext GraphDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.23 `selective_scan` — zone/index-pruned selective property scan + +- Applicability to Ontotext GraphDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.24 `mixed` — concurrent short reads, complex reads, and updates + +- Applicability to Ontotext GraphDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.25 `ingest` — sustained transactional ingest with indexes enabled + +- Applicability to Ontotext GraphDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.26 `bulk` — initial bulk load including index/CSR build + +- Applicability to Ontotext GraphDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.27 `checkpoint` — checkpoint or compaction while readers remain active + +- Applicability to Ontotext GraphDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.28 `recovery` — crash recovery at bounded dirty-log size + +- Applicability to Ontotext GraphDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.29 `cold` — same query after clearing engine and OS/cache tiers + +- Applicability to Ontotext GraphDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.30 `remote` — same query with authoritative bytes only in object storage + +- Applicability to Ontotext GraphDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +## 6. Fairness controls + +- Same logical dataset and update stream; engine-native physical layouts are allowed and disclosed. +- Same result semantics; unsupported queries remain unsupported rather than rewritten into easier questions. +- Same durable acknowledgement class for write comparisons. +- Same number of physical cores and memory limit for self-hosted single-node tests. +- Same aggregate resources and replication fault tolerance for distributed tests. +- Officially recommended tuning may be applied before the freeze and is committed with rationale. +- Query-specific hints are allowed only when equivalent hints are offered to every engine and separately charted. +- Load/build/index time and bytes are first-class results. +- Cold, warm, and hot results are separate charts. +- Managed services use public configurations and cannot borrow hidden same-machine resource claims. +- Failed runs, OOMs, correctness mismatches, and timeouts stay in the dataset. +- Every chart links raw samples and the exact reproduction command. + +## 7. Likely advantages and limits + +The strongest known reason to choose this engine is tied to its family `RDF store and reasoner`, its execution path `RDF4J query layer plus forward-chaining materialization`, and its existing ecosystem. The strongest reason to reject it for zu's target is the gap between `not S3-native live serving` and an S3-authoritative, request-budgeted, PB-scale graph service. + +Capacity statement: large RDF stores; audited LDBC SNB result exists but workload/language fit must be examined. This is not converted into an edge-count claim without a physical byte model including IDs, both adjacency directions, properties, indexes, MVCC, WAL, replicas, and free space. + +Commercial statement: commercial editions with a free edition. License cost, support cost, and unavailable enterprise capabilities remain visible in TCO and feature tables. + +## 8. Concrete lessons for zu + +1. Keep stable logical node and edge identity independent of row group, CSR slot, shard, and object range. +2. Store forward and reverse adjacency as immutable range-addressable tiles carrying edge IDs. +3. Feed queries adjacency batches and typed vectors; prohibit one storage call per logical element. +4. Use vectorized/factorized execution for property-heavy patterns and dedicated frontier operators for recursion. +5. Cost topology, properties, network, cache certainty, remote requests, and result materialization together. +6. Separate the local embedded profile from the object-authoritative distributed read profile. +7. Fence writers with monotonic epochs and make ambiguous commits reconcilable by transaction ID. +8. Pack small graph tiles into large immutable objects while retaining independent checksums and range offsets. +9. Keep the hot topology working set in RAM/NVMe; batch cold frontier misses into few remote rounds. +10. Admission-control remote requests and bytes so fixed-price plans have an enforceable upper bound. +11. Partition by workload-aware graph locality, and expose cross-partition semantics rather than hiding them. +12. Publish qualified wins per workload cell; never promise a universal tenfold advantage. + +## 9. Evidence gaps to close before publication + +- Exact current version and release date. +- Exact license text for the benchmarked artifact. +- Storage bytes per node/edge/property on all standard datasets. +- Stable-edge-ID and parallel-edge semantics. +- Isolation litmus results and commit acknowledgement point. +- Crash recovery time versus dirty WAL size. +- Supernode behavior and maximum tested degree. +- Cold-start metadata and request count. +- Distributed cross-partition query amplification. +- Peak memory under skew, cancellation, and overload. +- Background compaction/GC effect on tail latency. +- Full load/index/checkpoint/backup resource cost. +- Reproducible largest-scale result. +- Independent or audited benchmark evidence. + +## 10. Primary and official sources + +- [11.1 cluster overview](https://graphdb.ontotext.com/documentation/11.1/cluster-basics.html) +- [Architecture](https://graphdb.ontotext.com/documentation/10.7/) +- [LDBC results](https://ldbcouncil.org/benchmarks/snb/interactive/) +- [LDBC SNB Interactive and audited disclosures](https://ldbcouncil.org/benchmarks/snb/interactive/) +- [LDBC Graphalytics](https://ldbcouncil.org/benchmarks/graphalytics/) +- [SoK: The Faults in our Graph Benchmarks](https://arxiv.org/abs/2404.00766) + +## 11. Source-handling rules + +- Official documentation and source are evidence for implemented or declared behavior, not independent performance. +- A vendor benchmark is labeled vendor claim until the harness reproduces it. +- A peer-reviewed paper establishes only the version, configuration, and workload it evaluated. +- Search snippets, comparison sites, and unsourced blogs are discovery aids, not final evidence. +- Unknown is a valid result and creates a concrete experiment or source-inspection task. +- All web facts are rechecked at benchmark freeze because this corpus is current only through the research date. + +## 12. Reproduction record template + +- engine: `Ontotext GraphDB` +- version: `TBD at benchmark freeze` +- artifact digest: `TBD` +- source commit: `TBD or managed-service N/A` +- edition/license: `TBD` +- query language/version: `TBD` +- storage and durability mode: `TBD` +- cluster and replication: `TBD` +- CPU/RAM/NVMe/network: `TBD` +- OS/kernel/filesystem: `TBD` +- dataset URI and digest: `TBD` +- loader command and duration: `TBD` +- physical bytes by category: `TBD` +- tuning file: `TBD` +- query corpus commit: `TBD` +- raw result URI/digest: `TBD` +- profiler/trace URI: `TBD` +- correctness status: `TBD` +- reviewer and rerun date: `TBD` diff --git a/docs/research/engine-openlink_virtuoso.md b/docs/research/engine-openlink_virtuoso.md new file mode 100644 index 0000000..81048c2 --- /dev/null +++ b/docs/research/engine-openlink_virtuoso.md @@ -0,0 +1,885 @@ +# OpenLink Virtuoso: 2026 deep technical and competitive specification + +Research cut: `2026-08-08` +Status: evidence-backed competitor audit; not a vendor endorsement +Family: `multi-model SQL/RDF server` +Evidence convention: **Observed/official**, **Vendor claim**, **Research inference**, **Unknown**, **Qualification target**. + +## 1. Decision summary + +Virtuoso is the long-lived high-scale RDF/SQL baseline and a source of index-ordering lessons. + +This document answers two questions: what this engine actually proves in 2026, and what zu must build or measure to earn a defensible advantage. A missing public detail remains unknown; it is never silently filled with a favorable assumption. + +### Snapshot card + +- Lifecycle: active commercial/open-source lineage. +- Data model: relational, RDF quad, XML, text. +- Query surface: SQL, SPARQL, SPASQL. +- Persistent layout: column-oriented/row database structures with RDF quad indices. +- Execution: vectorized SQL/SPARQL optimizer and cluster editions. +- Transactions: ACID DBMS transactions. +- Distribution: Enterprise cluster and replication options. +- Object-storage posture: not S3-native. +- License/commercial boundary: GPL open-source edition; commercial Enterprise. +- Scale evidence: very large public RDF deployments, but PB interactive evidence is not current. +- Benchmark posture: use WatDiv/BSBM plus SQL/RDF hybrid cases and pin edition. + +### Facts that materially affect comparison + +- F01 — The RDF quad table uses carefully chosen composite index permutations. +- F02 — Predicate clustering improves many RDF access patterns. +- F03 — SPARQL can be embedded in SQL and relational data can be exposed as RDF views. +- F04 — Open-source and commercial cluster capabilities differ. +- F05 — Old documentation demands source/version verification before treating any limit as current. + +### Bottom-line fit against zu's target + +- Very-low latency: compare hot point and bounded traversal paths; never extrapolate from scans or algorithms. +- Very-low resources: charge resident set, page cache, remote cache, background services, and replicas. +- Distributed: distinguish read replication, partitioned capacity, distributed transactions, and elastic stateless compute. +- Fixed cost: no engine has fixed marginal cost by declaration; admission, batching, and capacity reservations create the bound. +- S3 authority: backups, imports, lake scans, and S3-native demand paging are four different architectures. +- PB / trillion-edge scale: require a capacity derivation plus a run at the largest affordable scale; marketing adjectives do not qualify. +- Tenfold win: can be a per-cell qualification result, never a universal statement across incomparable workloads. + +## 2. Product and ecosystem boundary + +The audited unit is **OpenLink Virtuoso** in the exact release, edition, deployment, and durability mode recorded by the harness. The family classification is **multi-model SQL/RDF server**. The current lifecycle statement is: active commercial/open-source lineage. + +The harness must record binary/container digest, source commit when available, build flags, plugins, license/edition, language mode, storage mode, cluster topology, replication factor, durability settings, cache sizes, thread counts, NUMA policy, kernel, filesystem, cloud region, and all environment variables that affect execution. + +A managed service is not placed in a same-hardware chart. It receives a service-level result with provisioned units, region, public price, and observed provider metrics. A historical engine remains useful for regression but cannot support a claim about beating all current competitors. + +## 3. Architecture reconstruction + +### 3.1 Logical model + +OpenLink Virtuoso exposes relational, RDF quad, XML, text. The conformance corpus must test nulls, missing properties, labels/types, direction, self-loops, parallel edges, element equality, path equality, bag semantics, ordering, numeric overflow, string collation, temporal values, and schema evolution. + +### 3.2 Language and compiler + +The public query surface is SQL, SPARQL, SPASQL. Syntax similarity is not semantic equivalence. Every supported construct needs a result oracle and an unsupported-feature declaration. + +### 3.3 Storage + +The best supported storage summary is: column-oriented/row database structures with RDF quad indices. This statement must be refined from code, format documentation, or provider counters before using it in a performance explanation. + +### 3.4 Execution + +The best supported execution summary is: vectorized SQL/SPARQL optimizer and cluster editions. The benchmark profiler must confirm which runtime and operators actually executed. + +### 3.5 Transactions and recovery + +The public contract is: ACID DBMS transactions. Exact acknowledgement, isolation anomalies, recovery bounds, and failover behavior remain separate qualification items. + +### 3.6 Distribution + +The deployment shape is: Enterprise cluster and replication options. Replication is not capacity sharding; sharding is not distributed ACID; stateless readers are not stateless storage. + +### 3.7 Object storage and cost + +The 2026 posture is: not S3-native. The audit distinguishes authoritative live bytes, derived acceleration, backup, import/export, and spill. + +## 4. Forty-control deep audit + +### 4.1 `product_boundary` + +Audit question: What exact executable, edition, and storage mode is the system under test? + +Current assessment: Pin OpenLink Virtuoso, lifecycle `active commercial/open-source lineage`, and its edition/mode. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.2 `authority` + +Audit question: Which durable component is the source of truth after every acknowledged write? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.3 `identity` + +Audit question: Are node and edge identities stable across compaction, export, replication, and restore? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.4 `parallel_edges` + +Audit question: Can distinct parallel edges retain properties and trail identity end to end? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.5 `schema` + +Audit question: Is the schema open, closed, optional, inferred, or externally mapped? + +Current assessment: Start from `relational, RDF quad, XML, text` and test actual constraints. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.6 `labels` + +Audit question: How are multiple labels represented and indexed? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.7 `adjacency_out` + +Audit question: How is outgoing adjacency located, encoded, split, cached, and updated? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.8 `adjacency_in` + +Audit question: Is incoming adjacency first-class, derived, replicated, or a fan-out operation? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.9 `supernodes` + +Audit question: How are million-to-billion-degree vertices represented and scheduled? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.10 `properties` + +Audit question: Are properties co-located, columnar, row-oriented, document-encoded, or remote? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.11 `compression` + +Audit question: Which topology, integer, string, null, and floating encodings are implemented? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.12 `checksums` + +Audit question: What integrity unit is verified on point reads and range reads? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.13 `snapshot` + +Audit question: What exact token pins graph data, schema, statistics, and indexes? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.14 `isolation` + +Audit question: Which anomalies are forbidden at the documented isolation level? + +Current assessment: Published summary: ACID DBMS transactions. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.15 `durability` + +Audit question: What device/service acknowledgement is required before commit returns? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.16 `recovery` + +Audit question: What bounds restart work after a clean stop and a crash? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.17 `writer_fencing` + +Audit question: Can a stale writer acknowledge after failover or lease expiry? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.18 `partitioning` + +Audit question: What key determines placement and what happens to cross-partition edges? + +Current assessment: Published distribution summary: Enterprise cluster and replication options. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.19 `rebalancing` + +Audit question: Can placement change online without changing logical identity? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.20 `replication` + +Audit question: Are replicas full, sharded, synchronous, asynchronous, or shared-storage readers? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.21 `optimizer` + +Audit question: Does the optimizer cost graph expansion, joins, network, cache, and remote requests? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.22 `statistics` + +Audit question: Which degree, correlation, path, and property statistics are persistent? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.23 `execution` + +Audit question: Is execution tuple-at-a-time, vectorized, factorized, compiled, matrix, or actor based? + +Current assessment: Expected family: vectorized SQL/SPARQL optimizer and cluster editions. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.24 `recursion` + +Audit question: How are BFS, shortest paths, trails, simple paths, and arbitrary reachability executed? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.25 `parallelism` + +Audit question: How does the engine avoid skew and nested parallelism under mixed queries? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.26 `memory` + +Audit question: Are all variable allocations charged to bounded query and system budgets? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.27 `spill` + +Audit question: Which operators spill, in what format, and with what admission controls? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.28 `cancellation` + +Audit question: Can cancellation stop CPU, local I/O, remote I/O, retries, and prefetch? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.29 `cache` + +Audit question: What is cached, how is it keyed, admitted, pinned, and evicted? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.30 `cold_start` + +Audit question: What metadata and data round trips are required with empty caches? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.31 `object_requests` + +Audit question: Can a query issue one remote request per node, edge, or result row? + +Current assessment: Published object-store posture: not S3-native. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.32 `cost_admission` + +Audit question: Are request, byte, CPU, spill, and result limits enforced before work? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.33 `observability` + +Audit question: Can operators report rows, edges, bytes, requests, stalls, memory, and spill? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.34 `language` + +Audit question: Which GQL/Cypher/SQL-PGQ/Gremlin/SPARQL semantics are declared and tested? + +Current assessment: Declared surface: SQL, SPARQL, SPASQL. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.35 `updates` + +Audit question: Are DDL, insert, merge, update, detach delete, and constraints complete? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.36 `bulk_load` + +Audit question: Does bulk load preserve transactional and index invariants? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.37 `backup` + +Audit question: Is backup consistent, incremental, immutable, and restore-tested? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.38 `gc` + +Audit question: How are old snapshots, orphan objects, tombstones, and indexes reclaimed safely? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.39 `security` + +Audit question: Are authentication, authorization, encryption, audit, and tenant isolation in scope? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.40 `operations` + +Audit question: What compaction, upgrade, repair, verification, and capacity procedures exist? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +## 5. Benchmark contract for this engine + +Every case runs correctness first, then isolated latency, then closed-loop concurrency, then open-loop overload. Report median, p95, p99, p99.9, timeout/rejection rate, throughput, CPU-seconds, peak RSS, cache bytes, disk bytes, network bytes, remote requests, write amplification, and estimated monthly cost. + +Warm means all intended engine caches are populated without changing the query parameters. Hot means the exact working set is resident. Cold means process-local, engine, OS, NVMe, and remote cache state are explicitly reset or a fresh namespace is used. Those words are never inferred from repetition count. + +### 5.1 `point_pk` — primary-key node lookup with one projected property + +- Applicability to OpenLink Virtuoso: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.2 `point_edge` — stable edge-ID lookup including endpoints and one property + +- Applicability to OpenLink Virtuoso: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.3 `degree_1` — degree-one outgoing expansion + +- Applicability to OpenLink Virtuoso: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.4 `degree_32` — small adjacency expansion around degree 32 + +- Applicability to OpenLink Virtuoso: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.5 `degree_1k` — medium adjacency expansion around degree 1,024 + +- Applicability to OpenLink Virtuoso: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.6 `supernode` — range-limited expansion of a ten-million-degree supernode + +- Applicability to OpenLink Virtuoso: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.7 `expand_2` — selective two-hop expansion + +- Applicability to OpenLink Virtuoso: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.8 `expand_3` — three-hop frontier expansion with duplicate control + +- Applicability to OpenLink Virtuoso: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.9 `expand_into` — edge-existence/expand-into between already-bound endpoints + +- Applicability to OpenLink Virtuoso: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.10 `multi_edge` — parallel-edge identity and property projection + +- Applicability to OpenLink Virtuoso: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.11 `shortest` — bidirectional point-to-point unweighted shortest path + +- Applicability to OpenLink Virtuoso: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.12 `weighted` — weighted shortest path with property access + +- Applicability to OpenLink Virtuoso: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.13 `var_walk` — bounded variable-length walk + +- Applicability to OpenLink Virtuoso: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.14 `trail` — DIFFERENT EDGES trail enumeration + +- Applicability to OpenLink Virtuoso: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.15 `simple` — simple-path enumeration with explicit bound + +- Applicability to OpenLink Virtuoso: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.16 `triangle` — triangle pattern with worst-case-sensitive join + +- Applicability to OpenLink Virtuoso: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.17 `cycle4` — four-cycle pattern + +- Applicability to OpenLink Virtuoso: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.18 `star_join` — high-fanout star pattern with property filters + +- Applicability to OpenLink Virtuoso: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.19 `optional` — optional match preserving null/bag semantics + +- Applicability to OpenLink Virtuoso: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.20 `aggregate` — grouped aggregate after traversal + +- Applicability to OpenLink Virtuoso: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.21 `topk` — ordered top-k with late property materialization + +- Applicability to OpenLink Virtuoso: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.22 `scan` — full projected property scan + +- Applicability to OpenLink Virtuoso: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.23 `selective_scan` — zone/index-pruned selective property scan + +- Applicability to OpenLink Virtuoso: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.24 `mixed` — concurrent short reads, complex reads, and updates + +- Applicability to OpenLink Virtuoso: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.25 `ingest` — sustained transactional ingest with indexes enabled + +- Applicability to OpenLink Virtuoso: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.26 `bulk` — initial bulk load including index/CSR build + +- Applicability to OpenLink Virtuoso: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.27 `checkpoint` — checkpoint or compaction while readers remain active + +- Applicability to OpenLink Virtuoso: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.28 `recovery` — crash recovery at bounded dirty-log size + +- Applicability to OpenLink Virtuoso: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.29 `cold` — same query after clearing engine and OS/cache tiers + +- Applicability to OpenLink Virtuoso: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.30 `remote` — same query with authoritative bytes only in object storage + +- Applicability to OpenLink Virtuoso: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +## 6. Fairness controls + +- Same logical dataset and update stream; engine-native physical layouts are allowed and disclosed. +- Same result semantics; unsupported queries remain unsupported rather than rewritten into easier questions. +- Same durable acknowledgement class for write comparisons. +- Same number of physical cores and memory limit for self-hosted single-node tests. +- Same aggregate resources and replication fault tolerance for distributed tests. +- Officially recommended tuning may be applied before the freeze and is committed with rationale. +- Query-specific hints are allowed only when equivalent hints are offered to every engine and separately charted. +- Load/build/index time and bytes are first-class results. +- Cold, warm, and hot results are separate charts. +- Managed services use public configurations and cannot borrow hidden same-machine resource claims. +- Failed runs, OOMs, correctness mismatches, and timeouts stay in the dataset. +- Every chart links raw samples and the exact reproduction command. + +## 7. Likely advantages and limits + +The strongest known reason to choose this engine is tied to its family `multi-model SQL/RDF server`, its execution path `vectorized SQL/SPARQL optimizer and cluster editions`, and its existing ecosystem. The strongest reason to reject it for zu's target is the gap between `not S3-native` and an S3-authoritative, request-budgeted, PB-scale graph service. + +Capacity statement: very large public RDF deployments, but PB interactive evidence is not current. This is not converted into an edge-count claim without a physical byte model including IDs, both adjacency directions, properties, indexes, MVCC, WAL, replicas, and free space. + +Commercial statement: GPL open-source edition; commercial Enterprise. License cost, support cost, and unavailable enterprise capabilities remain visible in TCO and feature tables. + +## 8. Concrete lessons for zu + +1. Keep stable logical node and edge identity independent of row group, CSR slot, shard, and object range. +2. Store forward and reverse adjacency as immutable range-addressable tiles carrying edge IDs. +3. Feed queries adjacency batches and typed vectors; prohibit one storage call per logical element. +4. Use vectorized/factorized execution for property-heavy patterns and dedicated frontier operators for recursion. +5. Cost topology, properties, network, cache certainty, remote requests, and result materialization together. +6. Separate the local embedded profile from the object-authoritative distributed read profile. +7. Fence writers with monotonic epochs and make ambiguous commits reconcilable by transaction ID. +8. Pack small graph tiles into large immutable objects while retaining independent checksums and range offsets. +9. Keep the hot topology working set in RAM/NVMe; batch cold frontier misses into few remote rounds. +10. Admission-control remote requests and bytes so fixed-price plans have an enforceable upper bound. +11. Partition by workload-aware graph locality, and expose cross-partition semantics rather than hiding them. +12. Publish qualified wins per workload cell; never promise a universal tenfold advantage. + +## 9. Evidence gaps to close before publication + +- Exact current version and release date. +- Exact license text for the benchmarked artifact. +- Storage bytes per node/edge/property on all standard datasets. +- Stable-edge-ID and parallel-edge semantics. +- Isolation litmus results and commit acknowledgement point. +- Crash recovery time versus dirty WAL size. +- Supernode behavior and maximum tested degree. +- Cold-start metadata and request count. +- Distributed cross-partition query amplification. +- Peak memory under skew, cancellation, and overload. +- Background compaction/GC effect on tail latency. +- Full load/index/checkpoint/backup resource cost. +- Reproducible largest-scale result. +- Independent or audited benchmark evidence. + +## 10. Primary and official sources + +- [Official manual](https://docs.openlinksw.com/virtuoso/index/) +- [RDF index scheme](https://docs.openlinksw.com/virtuoso/rdfperfrdfscheme/) +- [RDF data management](https://docs.openlinksw.com/virtuoso/ch-rdfandsparql/) +- [LDBC SNB Interactive and audited disclosures](https://ldbcouncil.org/benchmarks/snb/interactive/) +- [LDBC Graphalytics](https://ldbcouncil.org/benchmarks/graphalytics/) +- [SoK: The Faults in our Graph Benchmarks](https://arxiv.org/abs/2404.00766) + +## 11. Source-handling rules + +- Official documentation and source are evidence for implemented or declared behavior, not independent performance. +- A vendor benchmark is labeled vendor claim until the harness reproduces it. +- A peer-reviewed paper establishes only the version, configuration, and workload it evaluated. +- Search snippets, comparison sites, and unsourced blogs are discovery aids, not final evidence. +- Unknown is a valid result and creates a concrete experiment or source-inspection task. +- All web facts are rechecked at benchmark freeze because this corpus is current only through the research date. + +## 12. Reproduction record template + +- engine: `OpenLink Virtuoso` +- version: `TBD at benchmark freeze` +- artifact digest: `TBD` +- source commit: `TBD or managed-service N/A` +- edition/license: `TBD` +- query language/version: `TBD` +- storage and durability mode: `TBD` +- cluster and replication: `TBD` +- CPU/RAM/NVMe/network: `TBD` +- OS/kernel/filesystem: `TBD` +- dataset URI and digest: `TBD` +- loader command and duration: `TBD` +- physical bytes by category: `TBD` +- tuning file: `TBD` +- query corpus commit: `TBD` +- raw result URI/digest: `TBD` +- profiler/trace URI: `TBD` +- correctness status: `TBD` +- reviewer and rerun date: `TBD` diff --git a/docs/research/engine-oracle_property_graph.md b/docs/research/engine-oracle_property_graph.md new file mode 100644 index 0000000..7290ae3 --- /dev/null +++ b/docs/research/engine-oracle_property_graph.md @@ -0,0 +1,884 @@ +# Oracle Database Property Graph: 2026 deep technical and competitive specification + +Research cut: `2026-08-08` +Status: evidence-backed competitor audit; not a vendor endorsement +Family: `relational-integrated graph platform` +Evidence convention: **Observed/official**, **Vendor claim**, **Research inference**, **Unknown**, **Qualification target**. + +## 1. Decision summary + +Oracle is the mature SQL/PGQ and enterprise-integration baseline; it also demonstrates the cost of maintaining an analytical graph projection. + +This document answers two questions: what this engine actually proves in 2026, and what zu must build or measure to earn a defensible advantage. A missing public detail remains unknown; it is never silently filled with a favorable assumption. + +### Snapshot card + +- Lifecycle: active Oracle Database 26ai line. +- Data model: SQL property graph and property graph analytics. +- Query surface: SQL/PGQ GRAPH_TABLE, PGQL, openCypher surfaces by component. +- Persistent layout: graph declarations over Oracle relational tables; optional PGX in-memory graph server. +- Execution: in-database graph matching plus PGX analytical algorithms. +- Transactions: inherits Oracle Database ACID for stored tables; PGX copies have synchronization semantics. +- Distribution: Oracle RAC/Exadata/cloud database scale plus separate graph server. +- Object-storage posture: object storage may feed/load data, not the primary low-latency graph index. +- License/commercial boundary: commercial proprietary. +- Scale evidence: large enterprise scale but public PB interactive evidence is workload-specific. +- Benchmark posture: separate in-database query from PGX-loaded algorithm execution. + +### Facts that materially affect comparison + +- F01 — SQL property graphs can be defined directly over existing relational schema. +- F02 — GRAPH_TABLE performs pattern matching inside SQL. +- F03 — PGX must load a graph for specialized analytics. +- F04 — Periodic PGX refresh creates freshness and duplicate-storage considerations. +- F05 — Database and graph-server resources must both enter TCO. + +### Bottom-line fit against zu's target + +- Very-low latency: compare hot point and bounded traversal paths; never extrapolate from scans or algorithms. +- Very-low resources: charge resident set, page cache, remote cache, background services, and replicas. +- Distributed: distinguish read replication, partitioned capacity, distributed transactions, and elastic stateless compute. +- Fixed cost: no engine has fixed marginal cost by declaration; admission, batching, and capacity reservations create the bound. +- S3 authority: backups, imports, lake scans, and S3-native demand paging are four different architectures. +- PB / trillion-edge scale: require a capacity derivation plus a run at the largest affordable scale; marketing adjectives do not qualify. +- Tenfold win: can be a per-cell qualification result, never a universal statement across incomparable workloads. + +## 2. Product and ecosystem boundary + +The audited unit is **Oracle Database Property Graph** in the exact release, edition, deployment, and durability mode recorded by the harness. The family classification is **relational-integrated graph platform**. The current lifecycle statement is: active Oracle Database 26ai line. + +The harness must record binary/container digest, source commit when available, build flags, plugins, license/edition, language mode, storage mode, cluster topology, replication factor, durability settings, cache sizes, thread counts, NUMA policy, kernel, filesystem, cloud region, and all environment variables that affect execution. + +A managed service is not placed in a same-hardware chart. It receives a service-level result with provisioned units, region, public price, and observed provider metrics. A historical engine remains useful for regression but cannot support a claim about beating all current competitors. + +## 3. Architecture reconstruction + +### 3.1 Logical model + +Oracle Database Property Graph exposes SQL property graph and property graph analytics. The conformance corpus must test nulls, missing properties, labels/types, direction, self-loops, parallel edges, element equality, path equality, bag semantics, ordering, numeric overflow, string collation, temporal values, and schema evolution. + +### 3.2 Language and compiler + +The public query surface is SQL/PGQ GRAPH_TABLE, PGQL, openCypher surfaces by component. Syntax similarity is not semantic equivalence. Every supported construct needs a result oracle and an unsupported-feature declaration. + +### 3.3 Storage + +The best supported storage summary is: graph declarations over Oracle relational tables; optional PGX in-memory graph server. This statement must be refined from code, format documentation, or provider counters before using it in a performance explanation. + +### 3.4 Execution + +The best supported execution summary is: in-database graph matching plus PGX analytical algorithms. The benchmark profiler must confirm which runtime and operators actually executed. + +### 3.5 Transactions and recovery + +The public contract is: inherits Oracle Database ACID for stored tables; PGX copies have synchronization semantics. Exact acknowledgement, isolation anomalies, recovery bounds, and failover behavior remain separate qualification items. + +### 3.6 Distribution + +The deployment shape is: Oracle RAC/Exadata/cloud database scale plus separate graph server. Replication is not capacity sharding; sharding is not distributed ACID; stateless readers are not stateless storage. + +### 3.7 Object storage and cost + +The 2026 posture is: object storage may feed/load data, not the primary low-latency graph index. The audit distinguishes authoritative live bytes, derived acceleration, backup, import/export, and spill. + +## 4. Forty-control deep audit + +### 4.1 `product_boundary` + +Audit question: What exact executable, edition, and storage mode is the system under test? + +Current assessment: Pin Oracle Database Property Graph, lifecycle `active Oracle Database 26ai line`, and its edition/mode. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.2 `authority` + +Audit question: Which durable component is the source of truth after every acknowledged write? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.3 `identity` + +Audit question: Are node and edge identities stable across compaction, export, replication, and restore? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.4 `parallel_edges` + +Audit question: Can distinct parallel edges retain properties and trail identity end to end? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.5 `schema` + +Audit question: Is the schema open, closed, optional, inferred, or externally mapped? + +Current assessment: Start from `SQL property graph and property graph analytics` and test actual constraints. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.6 `labels` + +Audit question: How are multiple labels represented and indexed? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.7 `adjacency_out` + +Audit question: How is outgoing adjacency located, encoded, split, cached, and updated? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.8 `adjacency_in` + +Audit question: Is incoming adjacency first-class, derived, replicated, or a fan-out operation? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.9 `supernodes` + +Audit question: How are million-to-billion-degree vertices represented and scheduled? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.10 `properties` + +Audit question: Are properties co-located, columnar, row-oriented, document-encoded, or remote? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.11 `compression` + +Audit question: Which topology, integer, string, null, and floating encodings are implemented? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.12 `checksums` + +Audit question: What integrity unit is verified on point reads and range reads? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.13 `snapshot` + +Audit question: What exact token pins graph data, schema, statistics, and indexes? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.14 `isolation` + +Audit question: Which anomalies are forbidden at the documented isolation level? + +Current assessment: Published summary: inherits Oracle Database ACID for stored tables; PGX copies have synchronization semantics. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.15 `durability` + +Audit question: What device/service acknowledgement is required before commit returns? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.16 `recovery` + +Audit question: What bounds restart work after a clean stop and a crash? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.17 `writer_fencing` + +Audit question: Can a stale writer acknowledge after failover or lease expiry? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.18 `partitioning` + +Audit question: What key determines placement and what happens to cross-partition edges? + +Current assessment: Published distribution summary: Oracle RAC/Exadata/cloud database scale plus separate graph server. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.19 `rebalancing` + +Audit question: Can placement change online without changing logical identity? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.20 `replication` + +Audit question: Are replicas full, sharded, synchronous, asynchronous, or shared-storage readers? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.21 `optimizer` + +Audit question: Does the optimizer cost graph expansion, joins, network, cache, and remote requests? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.22 `statistics` + +Audit question: Which degree, correlation, path, and property statistics are persistent? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.23 `execution` + +Audit question: Is execution tuple-at-a-time, vectorized, factorized, compiled, matrix, or actor based? + +Current assessment: Expected family: in-database graph matching plus PGX analytical algorithms. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.24 `recursion` + +Audit question: How are BFS, shortest paths, trails, simple paths, and arbitrary reachability executed? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.25 `parallelism` + +Audit question: How does the engine avoid skew and nested parallelism under mixed queries? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.26 `memory` + +Audit question: Are all variable allocations charged to bounded query and system budgets? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.27 `spill` + +Audit question: Which operators spill, in what format, and with what admission controls? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.28 `cancellation` + +Audit question: Can cancellation stop CPU, local I/O, remote I/O, retries, and prefetch? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.29 `cache` + +Audit question: What is cached, how is it keyed, admitted, pinned, and evicted? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.30 `cold_start` + +Audit question: What metadata and data round trips are required with empty caches? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.31 `object_requests` + +Audit question: Can a query issue one remote request per node, edge, or result row? + +Current assessment: Published object-store posture: object storage may feed/load data, not the primary low-latency graph index. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.32 `cost_admission` + +Audit question: Are request, byte, CPU, spill, and result limits enforced before work? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.33 `observability` + +Audit question: Can operators report rows, edges, bytes, requests, stalls, memory, and spill? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.34 `language` + +Audit question: Which GQL/Cypher/SQL-PGQ/Gremlin/SPARQL semantics are declared and tested? + +Current assessment: Declared surface: SQL/PGQ GRAPH_TABLE, PGQL, openCypher surfaces by component. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.35 `updates` + +Audit question: Are DDL, insert, merge, update, detach delete, and constraints complete? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.36 `bulk_load` + +Audit question: Does bulk load preserve transactional and index invariants? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.37 `backup` + +Audit question: Is backup consistent, incremental, immutable, and restore-tested? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.38 `gc` + +Audit question: How are old snapshots, orphan objects, tombstones, and indexes reclaimed safely? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.39 `security` + +Audit question: Are authentication, authorization, encryption, audit, and tenant isolation in scope? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.40 `operations` + +Audit question: What compaction, upgrade, repair, verification, and capacity procedures exist? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +## 5. Benchmark contract for this engine + +Every case runs correctness first, then isolated latency, then closed-loop concurrency, then open-loop overload. Report median, p95, p99, p99.9, timeout/rejection rate, throughput, CPU-seconds, peak RSS, cache bytes, disk bytes, network bytes, remote requests, write amplification, and estimated monthly cost. + +Warm means all intended engine caches are populated without changing the query parameters. Hot means the exact working set is resident. Cold means process-local, engine, OS, NVMe, and remote cache state are explicitly reset or a fresh namespace is used. Those words are never inferred from repetition count. + +### 5.1 `point_pk` — primary-key node lookup with one projected property + +- Applicability to Oracle Database Property Graph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.2 `point_edge` — stable edge-ID lookup including endpoints and one property + +- Applicability to Oracle Database Property Graph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.3 `degree_1` — degree-one outgoing expansion + +- Applicability to Oracle Database Property Graph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.4 `degree_32` — small adjacency expansion around degree 32 + +- Applicability to Oracle Database Property Graph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.5 `degree_1k` — medium adjacency expansion around degree 1,024 + +- Applicability to Oracle Database Property Graph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.6 `supernode` — range-limited expansion of a ten-million-degree supernode + +- Applicability to Oracle Database Property Graph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.7 `expand_2` — selective two-hop expansion + +- Applicability to Oracle Database Property Graph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.8 `expand_3` — three-hop frontier expansion with duplicate control + +- Applicability to Oracle Database Property Graph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.9 `expand_into` — edge-existence/expand-into between already-bound endpoints + +- Applicability to Oracle Database Property Graph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.10 `multi_edge` — parallel-edge identity and property projection + +- Applicability to Oracle Database Property Graph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.11 `shortest` — bidirectional point-to-point unweighted shortest path + +- Applicability to Oracle Database Property Graph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.12 `weighted` — weighted shortest path with property access + +- Applicability to Oracle Database Property Graph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.13 `var_walk` — bounded variable-length walk + +- Applicability to Oracle Database Property Graph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.14 `trail` — DIFFERENT EDGES trail enumeration + +- Applicability to Oracle Database Property Graph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.15 `simple` — simple-path enumeration with explicit bound + +- Applicability to Oracle Database Property Graph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.16 `triangle` — triangle pattern with worst-case-sensitive join + +- Applicability to Oracle Database Property Graph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.17 `cycle4` — four-cycle pattern + +- Applicability to Oracle Database Property Graph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.18 `star_join` — high-fanout star pattern with property filters + +- Applicability to Oracle Database Property Graph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.19 `optional` — optional match preserving null/bag semantics + +- Applicability to Oracle Database Property Graph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.20 `aggregate` — grouped aggregate after traversal + +- Applicability to Oracle Database Property Graph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.21 `topk` — ordered top-k with late property materialization + +- Applicability to Oracle Database Property Graph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.22 `scan` — full projected property scan + +- Applicability to Oracle Database Property Graph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.23 `selective_scan` — zone/index-pruned selective property scan + +- Applicability to Oracle Database Property Graph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.24 `mixed` — concurrent short reads, complex reads, and updates + +- Applicability to Oracle Database Property Graph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.25 `ingest` — sustained transactional ingest with indexes enabled + +- Applicability to Oracle Database Property Graph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.26 `bulk` — initial bulk load including index/CSR build + +- Applicability to Oracle Database Property Graph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.27 `checkpoint` — checkpoint or compaction while readers remain active + +- Applicability to Oracle Database Property Graph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.28 `recovery` — crash recovery at bounded dirty-log size + +- Applicability to Oracle Database Property Graph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.29 `cold` — same query after clearing engine and OS/cache tiers + +- Applicability to Oracle Database Property Graph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.30 `remote` — same query with authoritative bytes only in object storage + +- Applicability to Oracle Database Property Graph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +## 6. Fairness controls + +- Same logical dataset and update stream; engine-native physical layouts are allowed and disclosed. +- Same result semantics; unsupported queries remain unsupported rather than rewritten into easier questions. +- Same durable acknowledgement class for write comparisons. +- Same number of physical cores and memory limit for self-hosted single-node tests. +- Same aggregate resources and replication fault tolerance for distributed tests. +- Officially recommended tuning may be applied before the freeze and is committed with rationale. +- Query-specific hints are allowed only when equivalent hints are offered to every engine and separately charted. +- Load/build/index time and bytes are first-class results. +- Cold, warm, and hot results are separate charts. +- Managed services use public configurations and cannot borrow hidden same-machine resource claims. +- Failed runs, OOMs, correctness mismatches, and timeouts stay in the dataset. +- Every chart links raw samples and the exact reproduction command. + +## 7. Likely advantages and limits + +The strongest known reason to choose this engine is tied to its family `relational-integrated graph platform`, its execution path `in-database graph matching plus PGX analytical algorithms`, and its existing ecosystem. The strongest reason to reject it for zu's target is the gap between `object storage may feed/load data, not the primary low-latency graph index` and an S3-authoritative, request-budgeted, PB-scale graph service. + +Capacity statement: large enterprise scale but public PB interactive evidence is workload-specific. This is not converted into an edge-count claim without a physical byte model including IDs, both adjacency directions, properties, indexes, MVCC, WAL, replicas, and free space. + +Commercial statement: commercial proprietary. License cost, support cost, and unavailable enterprise capabilities remain visible in TCO and feature tables. + +## 8. Concrete lessons for zu + +1. Keep stable logical node and edge identity independent of row group, CSR slot, shard, and object range. +2. Store forward and reverse adjacency as immutable range-addressable tiles carrying edge IDs. +3. Feed queries adjacency batches and typed vectors; prohibit one storage call per logical element. +4. Use vectorized/factorized execution for property-heavy patterns and dedicated frontier operators for recursion. +5. Cost topology, properties, network, cache certainty, remote requests, and result materialization together. +6. Separate the local embedded profile from the object-authoritative distributed read profile. +7. Fence writers with monotonic epochs and make ambiguous commits reconcilable by transaction ID. +8. Pack small graph tiles into large immutable objects while retaining independent checksums and range offsets. +9. Keep the hot topology working set in RAM/NVMe; batch cold frontier misses into few remote rounds. +10. Admission-control remote requests and bytes so fixed-price plans have an enforceable upper bound. +11. Partition by workload-aware graph locality, and expose cross-partition semantics rather than hiding them. +12. Publish qualified wins per workload cell; never promise a universal tenfold advantage. + +## 9. Evidence gaps to close before publication + +- Exact current version and release date. +- Exact license text for the benchmarked artifact. +- Storage bytes per node/edge/property on all standard datasets. +- Stable-edge-ID and parallel-edge semantics. +- Isolation litmus results and commit acknowledgement point. +- Crash recovery time versus dirty WAL size. +- Supernode behavior and maximum tested degree. +- Cold-start metadata and request count. +- Distributed cross-partition query amplification. +- Peak memory under skew, cancellation, and overload. +- Background compaction/GC effect on tail latency. +- Full load/index/checkpoint/backup resource cost. +- Reproducible largest-scale result. +- Independent or audited benchmark evidence. + +## 10. Primary and official sources + +- [26ai property graph introduction](https://docs.oracle.com/en/database/oracle/property-graph/26.1/spgdg/introduction-property-graphs.html) +- [Current property graph releases](https://docs.oracle.com/en/database/oracle/property-graph/) +- [LDBC SNB Interactive and audited disclosures](https://ldbcouncil.org/benchmarks/snb/interactive/) +- [LDBC Graphalytics](https://ldbcouncil.org/benchmarks/graphalytics/) +- [SoK: The Faults in our Graph Benchmarks](https://arxiv.org/abs/2404.00766) + +## 11. Source-handling rules + +- Official documentation and source are evidence for implemented or declared behavior, not independent performance. +- A vendor benchmark is labeled vendor claim until the harness reproduces it. +- A peer-reviewed paper establishes only the version, configuration, and workload it evaluated. +- Search snippets, comparison sites, and unsourced blogs are discovery aids, not final evidence. +- Unknown is a valid result and creates a concrete experiment or source-inspection task. +- All web facts are rechecked at benchmark freeze because this corpus is current only through the research date. + +## 12. Reproduction record template + +- engine: `Oracle Database Property Graph` +- version: `TBD at benchmark freeze` +- artifact digest: `TBD` +- source commit: `TBD or managed-service N/A` +- edition/license: `TBD` +- query language/version: `TBD` +- storage and durability mode: `TBD` +- cluster and replication: `TBD` +- CPU/RAM/NVMe/network: `TBD` +- OS/kernel/filesystem: `TBD` +- dataset URI and digest: `TBD` +- loader command and duration: `TBD` +- physical bytes by category: `TBD` +- tuning file: `TBD` +- query corpus commit: `TBD` +- raw result URI/digest: `TBD` +- profiler/trace URI: `TBD` +- correctness status: `TBD` +- reviewer and rerun date: `TBD` diff --git a/docs/research/engine-orientdb.md b/docs/research/engine-orientdb.md new file mode 100644 index 0000000..87955c4 --- /dev/null +++ b/docs/research/engine-orientdb.md @@ -0,0 +1,885 @@ +# OrientDB: 2026 deep technical and competitive specification + +Research cut: `2026-08-08` +Status: evidence-backed competitor audit; not a vendor endorsement +Family: `multi-model graph/document database` +Evidence convention: **Observed/official**, **Vendor claim**, **Research inference**, **Unknown**, **Qualification target**. + +## 1. Decision summary + +OrientDB is valuable chiefly as a warning about physical identity, multi-master conflict handling, and application-directed sharding. + +This document answers two questions: what this engine actually proves in 2026, and what zu must build or measure to earn a defensible advantage. A missing public detail remains unknown; it is never silently filled with a favorable assumption. + +### Snapshot card + +- Lifecycle: active 4.0 line but legacy architecture remains relevant. +- Data model: document and graph. +- Query surface: OrientDB SQL and Gremlin compatibility surfaces. +- Persistent layout: record clusters with physical RIDs and native links. +- Execution: Java query engine and direct record traversal. +- Transactions: ACID local transactions; distributed multi-master/quorum behavior has constraints. +- Distribution: Hazelcast-coordinated multi-master replication and class/cluster sharding. +- Object-storage posture: not S3-native. +- License/commercial boundary: Apache-2.0 Community; historical commercial split. +- Scale evidence: distributed scale constrained by manual sharding/index limitations in documented designs. +- Benchmark posture: use as compatibility/resource baseline, not a PB front-runner. + +### Facts that materially affect comparison + +- F01 — RIDs encode cluster and position, coupling identity to physical layout concerns. +- F02 — Distributed cluster ownership assigns record clusters to servers. +- F03 — Older docs state unique indexes are not globally safe across sharded classes. +- F04 — Majority write quorum is required to avoid unsafe split-brain operation. +- F05 — The 4.0 documentation lifecycle and actual implementation maturity need explicit verification. + +### Bottom-line fit against zu's target + +- Very-low latency: compare hot point and bounded traversal paths; never extrapolate from scans or algorithms. +- Very-low resources: charge resident set, page cache, remote cache, background services, and replicas. +- Distributed: distinguish read replication, partitioned capacity, distributed transactions, and elastic stateless compute. +- Fixed cost: no engine has fixed marginal cost by declaration; admission, batching, and capacity reservations create the bound. +- S3 authority: backups, imports, lake scans, and S3-native demand paging are four different architectures. +- PB / trillion-edge scale: require a capacity derivation plus a run at the largest affordable scale; marketing adjectives do not qualify. +- Tenfold win: can be a per-cell qualification result, never a universal statement across incomparable workloads. + +## 2. Product and ecosystem boundary + +The audited unit is **OrientDB** in the exact release, edition, deployment, and durability mode recorded by the harness. The family classification is **multi-model graph/document database**. The current lifecycle statement is: active 4.0 line but legacy architecture remains relevant. + +The harness must record binary/container digest, source commit when available, build flags, plugins, license/edition, language mode, storage mode, cluster topology, replication factor, durability settings, cache sizes, thread counts, NUMA policy, kernel, filesystem, cloud region, and all environment variables that affect execution. + +A managed service is not placed in a same-hardware chart. It receives a service-level result with provisioned units, region, public price, and observed provider metrics. A historical engine remains useful for regression but cannot support a claim about beating all current competitors. + +## 3. Architecture reconstruction + +### 3.1 Logical model + +OrientDB exposes document and graph. The conformance corpus must test nulls, missing properties, labels/types, direction, self-loops, parallel edges, element equality, path equality, bag semantics, ordering, numeric overflow, string collation, temporal values, and schema evolution. + +### 3.2 Language and compiler + +The public query surface is OrientDB SQL and Gremlin compatibility surfaces. Syntax similarity is not semantic equivalence. Every supported construct needs a result oracle and an unsupported-feature declaration. + +### 3.3 Storage + +The best supported storage summary is: record clusters with physical RIDs and native links. This statement must be refined from code, format documentation, or provider counters before using it in a performance explanation. + +### 3.4 Execution + +The best supported execution summary is: Java query engine and direct record traversal. The benchmark profiler must confirm which runtime and operators actually executed. + +### 3.5 Transactions and recovery + +The public contract is: ACID local transactions; distributed multi-master/quorum behavior has constraints. Exact acknowledgement, isolation anomalies, recovery bounds, and failover behavior remain separate qualification items. + +### 3.6 Distribution + +The deployment shape is: Hazelcast-coordinated multi-master replication and class/cluster sharding. Replication is not capacity sharding; sharding is not distributed ACID; stateless readers are not stateless storage. + +### 3.7 Object storage and cost + +The 2026 posture is: not S3-native. The audit distinguishes authoritative live bytes, derived acceleration, backup, import/export, and spill. + +## 4. Forty-control deep audit + +### 4.1 `product_boundary` + +Audit question: What exact executable, edition, and storage mode is the system under test? + +Current assessment: Pin OrientDB, lifecycle `active 4.0 line but legacy architecture remains relevant`, and its edition/mode. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.2 `authority` + +Audit question: Which durable component is the source of truth after every acknowledged write? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.3 `identity` + +Audit question: Are node and edge identities stable across compaction, export, replication, and restore? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.4 `parallel_edges` + +Audit question: Can distinct parallel edges retain properties and trail identity end to end? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.5 `schema` + +Audit question: Is the schema open, closed, optional, inferred, or externally mapped? + +Current assessment: Start from `document and graph` and test actual constraints. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.6 `labels` + +Audit question: How are multiple labels represented and indexed? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.7 `adjacency_out` + +Audit question: How is outgoing adjacency located, encoded, split, cached, and updated? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.8 `adjacency_in` + +Audit question: Is incoming adjacency first-class, derived, replicated, or a fan-out operation? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.9 `supernodes` + +Audit question: How are million-to-billion-degree vertices represented and scheduled? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.10 `properties` + +Audit question: Are properties co-located, columnar, row-oriented, document-encoded, or remote? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.11 `compression` + +Audit question: Which topology, integer, string, null, and floating encodings are implemented? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.12 `checksums` + +Audit question: What integrity unit is verified on point reads and range reads? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.13 `snapshot` + +Audit question: What exact token pins graph data, schema, statistics, and indexes? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.14 `isolation` + +Audit question: Which anomalies are forbidden at the documented isolation level? + +Current assessment: Published summary: ACID local transactions; distributed multi-master/quorum behavior has constraints. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.15 `durability` + +Audit question: What device/service acknowledgement is required before commit returns? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.16 `recovery` + +Audit question: What bounds restart work after a clean stop and a crash? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.17 `writer_fencing` + +Audit question: Can a stale writer acknowledge after failover or lease expiry? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.18 `partitioning` + +Audit question: What key determines placement and what happens to cross-partition edges? + +Current assessment: Published distribution summary: Hazelcast-coordinated multi-master replication and class/cluster sharding. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.19 `rebalancing` + +Audit question: Can placement change online without changing logical identity? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.20 `replication` + +Audit question: Are replicas full, sharded, synchronous, asynchronous, or shared-storage readers? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.21 `optimizer` + +Audit question: Does the optimizer cost graph expansion, joins, network, cache, and remote requests? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.22 `statistics` + +Audit question: Which degree, correlation, path, and property statistics are persistent? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.23 `execution` + +Audit question: Is execution tuple-at-a-time, vectorized, factorized, compiled, matrix, or actor based? + +Current assessment: Expected family: Java query engine and direct record traversal. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.24 `recursion` + +Audit question: How are BFS, shortest paths, trails, simple paths, and arbitrary reachability executed? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.25 `parallelism` + +Audit question: How does the engine avoid skew and nested parallelism under mixed queries? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.26 `memory` + +Audit question: Are all variable allocations charged to bounded query and system budgets? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.27 `spill` + +Audit question: Which operators spill, in what format, and with what admission controls? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.28 `cancellation` + +Audit question: Can cancellation stop CPU, local I/O, remote I/O, retries, and prefetch? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.29 `cache` + +Audit question: What is cached, how is it keyed, admitted, pinned, and evicted? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.30 `cold_start` + +Audit question: What metadata and data round trips are required with empty caches? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.31 `object_requests` + +Audit question: Can a query issue one remote request per node, edge, or result row? + +Current assessment: Published object-store posture: not S3-native. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.32 `cost_admission` + +Audit question: Are request, byte, CPU, spill, and result limits enforced before work? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.33 `observability` + +Audit question: Can operators report rows, edges, bytes, requests, stalls, memory, and spill? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.34 `language` + +Audit question: Which GQL/Cypher/SQL-PGQ/Gremlin/SPARQL semantics are declared and tested? + +Current assessment: Declared surface: OrientDB SQL and Gremlin compatibility surfaces. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.35 `updates` + +Audit question: Are DDL, insert, merge, update, detach delete, and constraints complete? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.36 `bulk_load` + +Audit question: Does bulk load preserve transactional and index invariants? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.37 `backup` + +Audit question: Is backup consistent, incremental, immutable, and restore-tested? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.38 `gc` + +Audit question: How are old snapshots, orphan objects, tombstones, and indexes reclaimed safely? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.39 `security` + +Audit question: Are authentication, authorization, encryption, audit, and tenant isolation in scope? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.40 `operations` + +Audit question: What compaction, upgrade, repair, verification, and capacity procedures exist? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +## 5. Benchmark contract for this engine + +Every case runs correctness first, then isolated latency, then closed-loop concurrency, then open-loop overload. Report median, p95, p99, p99.9, timeout/rejection rate, throughput, CPU-seconds, peak RSS, cache bytes, disk bytes, network bytes, remote requests, write amplification, and estimated monthly cost. + +Warm means all intended engine caches are populated without changing the query parameters. Hot means the exact working set is resident. Cold means process-local, engine, OS, NVMe, and remote cache state are explicitly reset or a fresh namespace is used. Those words are never inferred from repetition count. + +### 5.1 `point_pk` — primary-key node lookup with one projected property + +- Applicability to OrientDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.2 `point_edge` — stable edge-ID lookup including endpoints and one property + +- Applicability to OrientDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.3 `degree_1` — degree-one outgoing expansion + +- Applicability to OrientDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.4 `degree_32` — small adjacency expansion around degree 32 + +- Applicability to OrientDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.5 `degree_1k` — medium adjacency expansion around degree 1,024 + +- Applicability to OrientDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.6 `supernode` — range-limited expansion of a ten-million-degree supernode + +- Applicability to OrientDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.7 `expand_2` — selective two-hop expansion + +- Applicability to OrientDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.8 `expand_3` — three-hop frontier expansion with duplicate control + +- Applicability to OrientDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.9 `expand_into` — edge-existence/expand-into between already-bound endpoints + +- Applicability to OrientDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.10 `multi_edge` — parallel-edge identity and property projection + +- Applicability to OrientDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.11 `shortest` — bidirectional point-to-point unweighted shortest path + +- Applicability to OrientDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.12 `weighted` — weighted shortest path with property access + +- Applicability to OrientDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.13 `var_walk` — bounded variable-length walk + +- Applicability to OrientDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.14 `trail` — DIFFERENT EDGES trail enumeration + +- Applicability to OrientDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.15 `simple` — simple-path enumeration with explicit bound + +- Applicability to OrientDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.16 `triangle` — triangle pattern with worst-case-sensitive join + +- Applicability to OrientDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.17 `cycle4` — four-cycle pattern + +- Applicability to OrientDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.18 `star_join` — high-fanout star pattern with property filters + +- Applicability to OrientDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.19 `optional` — optional match preserving null/bag semantics + +- Applicability to OrientDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.20 `aggregate` — grouped aggregate after traversal + +- Applicability to OrientDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.21 `topk` — ordered top-k with late property materialization + +- Applicability to OrientDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.22 `scan` — full projected property scan + +- Applicability to OrientDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.23 `selective_scan` — zone/index-pruned selective property scan + +- Applicability to OrientDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.24 `mixed` — concurrent short reads, complex reads, and updates + +- Applicability to OrientDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.25 `ingest` — sustained transactional ingest with indexes enabled + +- Applicability to OrientDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.26 `bulk` — initial bulk load including index/CSR build + +- Applicability to OrientDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.27 `checkpoint` — checkpoint or compaction while readers remain active + +- Applicability to OrientDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.28 `recovery` — crash recovery at bounded dirty-log size + +- Applicability to OrientDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.29 `cold` — same query after clearing engine and OS/cache tiers + +- Applicability to OrientDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.30 `remote` — same query with authoritative bytes only in object storage + +- Applicability to OrientDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +## 6. Fairness controls + +- Same logical dataset and update stream; engine-native physical layouts are allowed and disclosed. +- Same result semantics; unsupported queries remain unsupported rather than rewritten into easier questions. +- Same durable acknowledgement class for write comparisons. +- Same number of physical cores and memory limit for self-hosted single-node tests. +- Same aggregate resources and replication fault tolerance for distributed tests. +- Officially recommended tuning may be applied before the freeze and is committed with rationale. +- Query-specific hints are allowed only when equivalent hints are offered to every engine and separately charted. +- Load/build/index time and bytes are first-class results. +- Cold, warm, and hot results are separate charts. +- Managed services use public configurations and cannot borrow hidden same-machine resource claims. +- Failed runs, OOMs, correctness mismatches, and timeouts stay in the dataset. +- Every chart links raw samples and the exact reproduction command. + +## 7. Likely advantages and limits + +The strongest known reason to choose this engine is tied to its family `multi-model graph/document database`, its execution path `Java query engine and direct record traversal`, and its existing ecosystem. The strongest reason to reject it for zu's target is the gap between `not S3-native` and an S3-authoritative, request-budgeted, PB-scale graph service. + +Capacity statement: distributed scale constrained by manual sharding/index limitations in documented designs. This is not converted into an edge-count claim without a physical byte model including IDs, both adjacency directions, properties, indexes, MVCC, WAL, replicas, and free space. + +Commercial statement: Apache-2.0 Community; historical commercial split. License cost, support cost, and unavailable enterprise capabilities remain visible in TCO and feature tables. + +## 8. Concrete lessons for zu + +1. Keep stable logical node and edge identity independent of row group, CSR slot, shard, and object range. +2. Store forward and reverse adjacency as immutable range-addressable tiles carrying edge IDs. +3. Feed queries adjacency batches and typed vectors; prohibit one storage call per logical element. +4. Use vectorized/factorized execution for property-heavy patterns and dedicated frontier operators for recursion. +5. Cost topology, properties, network, cache certainty, remote requests, and result materialization together. +6. Separate the local embedded profile from the object-authoritative distributed read profile. +7. Fence writers with monotonic epochs and make ambiguous commits reconcilable by transaction ID. +8. Pack small graph tiles into large immutable objects while retaining independent checksums and range offsets. +9. Keep the hot topology working set in RAM/NVMe; batch cold frontier misses into few remote rounds. +10. Admission-control remote requests and bytes so fixed-price plans have an enforceable upper bound. +11. Partition by workload-aware graph locality, and expose cross-partition semantics rather than hiding them. +12. Publish qualified wins per workload cell; never promise a universal tenfold advantage. + +## 9. Evidence gaps to close before publication + +- Exact current version and release date. +- Exact license text for the benchmarked artifact. +- Storage bytes per node/edge/property on all standard datasets. +- Stable-edge-ID and parallel-edge semantics. +- Isolation litmus results and commit acknowledgement point. +- Crash recovery time versus dirty WAL size. +- Supernode behavior and maximum tested degree. +- Cold-start metadata and request count. +- Distributed cross-partition query amplification. +- Peak memory under skew, cancellation, and overload. +- Background compaction/GC effect on tail latency. +- Full load/index/checkpoint/backup resource cost. +- Reproducible largest-scale result. +- Independent or audited benchmark evidence. + +## 10. Primary and official sources + +- [Current documentation](https://orientdb.dev/docs/develop/) +- [Distributed architecture](https://orientdb.dev/docs/3.0.x/distributed/Distributed-Architecture.html) +- [Sharding](https://orientdb.dev/docs/develop/distributed/Distributed-Sharding.html) +- [LDBC SNB Interactive and audited disclosures](https://ldbcouncil.org/benchmarks/snb/interactive/) +- [LDBC Graphalytics](https://ldbcouncil.org/benchmarks/graphalytics/) +- [SoK: The Faults in our Graph Benchmarks](https://arxiv.org/abs/2404.00766) + +## 11. Source-handling rules + +- Official documentation and source are evidence for implemented or declared behavior, not independent performance. +- A vendor benchmark is labeled vendor claim until the harness reproduces it. +- A peer-reviewed paper establishes only the version, configuration, and workload it evaluated. +- Search snippets, comparison sites, and unsourced blogs are discovery aids, not final evidence. +- Unknown is a valid result and creates a concrete experiment or source-inspection task. +- All web facts are rechecked at benchmark freeze because this corpus is current only through the research date. + +## 12. Reproduction record template + +- engine: `OrientDB` +- version: `TBD at benchmark freeze` +- artifact digest: `TBD` +- source commit: `TBD or managed-service N/A` +- edition/license: `TBD` +- query language/version: `TBD` +- storage and durability mode: `TBD` +- cluster and replication: `TBD` +- CPU/RAM/NVMe/network: `TBD` +- OS/kernel/filesystem: `TBD` +- dataset URI and digest: `TBD` +- loader command and duration: `TBD` +- physical bytes by category: `TBD` +- tuning file: `TBD` +- query corpus commit: `TBD` +- raw result URI/digest: `TBD` +- profiler/trace URI: `TBD` +- correctness status: `TBD` +- reviewer and rerun date: `TBD` diff --git a/docs/research/engine-oxigraph.md b/docs/research/engine-oxigraph.md new file mode 100644 index 0000000..a04b033 --- /dev/null +++ b/docs/research/engine-oxigraph.md @@ -0,0 +1,884 @@ +# Oxigraph: 2026 deep technical and competitive specification + +Research cut: `2026-08-08` +Status: evidence-backed competitor audit; not a vendor endorsement +Family: `embedded Rust RDF store` +Evidence convention: **Observed/official**, **Vendor claim**, **Research inference**, **Unknown**, **Qualification target**. + +## 1. Decision summary + +Oxigraph is the closest Rust RDF implementation reference and a useful fuzz/conformance comparator. + +This document answers two questions: what this engine actually proves in 2026, and what zu must build or measure to earn a defensible advantage. A missing public detail remains unknown; it is never silently filled with a favorable assumption. + +### Snapshot card + +- Lifecycle: active and explicitly still optimizing. +- Data model: RDF triples/quads. +- Query surface: SPARQL 1.1. +- Persistent layout: RocksDB persistent backend or in-memory store with encoded term dictionaries and tuple indices. +- Execution: Rust SPARQL parser/evaluator. +- Transactions: transactional KV-backed updates; exact isolation should be tested. +- Distribution: single-node library/server. +- Object-storage posture: not S3-native. +- License/commercial boundary: Apache-2.0 and MIT dual licensing. +- Scale evidence: single-node; no PB proof. +- Benchmark posture: conformance and resource efficiency matter more than headline throughput. + +### Facts that materially affect comparison + +- F01 — The project emphasizes standards compliance and safety. +- F02 — It implements SPARQL query, update, federation, and graph-store protocols. +- F03 — Persistent mode builds on RocksDB. +- F04 — Official README warns query evaluation is not fully optimized. +- F05 — Rust library embedding makes process overhead comparisons fair. + +### Bottom-line fit against zu's target + +- Very-low latency: compare hot point and bounded traversal paths; never extrapolate from scans or algorithms. +- Very-low resources: charge resident set, page cache, remote cache, background services, and replicas. +- Distributed: distinguish read replication, partitioned capacity, distributed transactions, and elastic stateless compute. +- Fixed cost: no engine has fixed marginal cost by declaration; admission, batching, and capacity reservations create the bound. +- S3 authority: backups, imports, lake scans, and S3-native demand paging are four different architectures. +- PB / trillion-edge scale: require a capacity derivation plus a run at the largest affordable scale; marketing adjectives do not qualify. +- Tenfold win: can be a per-cell qualification result, never a universal statement across incomparable workloads. + +## 2. Product and ecosystem boundary + +The audited unit is **Oxigraph** in the exact release, edition, deployment, and durability mode recorded by the harness. The family classification is **embedded Rust RDF store**. The current lifecycle statement is: active and explicitly still optimizing. + +The harness must record binary/container digest, source commit when available, build flags, plugins, license/edition, language mode, storage mode, cluster topology, replication factor, durability settings, cache sizes, thread counts, NUMA policy, kernel, filesystem, cloud region, and all environment variables that affect execution. + +A managed service is not placed in a same-hardware chart. It receives a service-level result with provisioned units, region, public price, and observed provider metrics. A historical engine remains useful for regression but cannot support a claim about beating all current competitors. + +## 3. Architecture reconstruction + +### 3.1 Logical model + +Oxigraph exposes RDF triples/quads. The conformance corpus must test nulls, missing properties, labels/types, direction, self-loops, parallel edges, element equality, path equality, bag semantics, ordering, numeric overflow, string collation, temporal values, and schema evolution. + +### 3.2 Language and compiler + +The public query surface is SPARQL 1.1. Syntax similarity is not semantic equivalence. Every supported construct needs a result oracle and an unsupported-feature declaration. + +### 3.3 Storage + +The best supported storage summary is: RocksDB persistent backend or in-memory store with encoded term dictionaries and tuple indices. This statement must be refined from code, format documentation, or provider counters before using it in a performance explanation. + +### 3.4 Execution + +The best supported execution summary is: Rust SPARQL parser/evaluator. The benchmark profiler must confirm which runtime and operators actually executed. + +### 3.5 Transactions and recovery + +The public contract is: transactional KV-backed updates; exact isolation should be tested. Exact acknowledgement, isolation anomalies, recovery bounds, and failover behavior remain separate qualification items. + +### 3.6 Distribution + +The deployment shape is: single-node library/server. Replication is not capacity sharding; sharding is not distributed ACID; stateless readers are not stateless storage. + +### 3.7 Object storage and cost + +The 2026 posture is: not S3-native. The audit distinguishes authoritative live bytes, derived acceleration, backup, import/export, and spill. + +## 4. Forty-control deep audit + +### 4.1 `product_boundary` + +Audit question: What exact executable, edition, and storage mode is the system under test? + +Current assessment: Pin Oxigraph, lifecycle `active and explicitly still optimizing`, and its edition/mode. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.2 `authority` + +Audit question: Which durable component is the source of truth after every acknowledged write? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.3 `identity` + +Audit question: Are node and edge identities stable across compaction, export, replication, and restore? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.4 `parallel_edges` + +Audit question: Can distinct parallel edges retain properties and trail identity end to end? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.5 `schema` + +Audit question: Is the schema open, closed, optional, inferred, or externally mapped? + +Current assessment: Start from `RDF triples/quads` and test actual constraints. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.6 `labels` + +Audit question: How are multiple labels represented and indexed? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.7 `adjacency_out` + +Audit question: How is outgoing adjacency located, encoded, split, cached, and updated? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.8 `adjacency_in` + +Audit question: Is incoming adjacency first-class, derived, replicated, or a fan-out operation? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.9 `supernodes` + +Audit question: How are million-to-billion-degree vertices represented and scheduled? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.10 `properties` + +Audit question: Are properties co-located, columnar, row-oriented, document-encoded, or remote? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.11 `compression` + +Audit question: Which topology, integer, string, null, and floating encodings are implemented? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.12 `checksums` + +Audit question: What integrity unit is verified on point reads and range reads? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.13 `snapshot` + +Audit question: What exact token pins graph data, schema, statistics, and indexes? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.14 `isolation` + +Audit question: Which anomalies are forbidden at the documented isolation level? + +Current assessment: Published summary: transactional KV-backed updates; exact isolation should be tested. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.15 `durability` + +Audit question: What device/service acknowledgement is required before commit returns? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.16 `recovery` + +Audit question: What bounds restart work after a clean stop and a crash? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.17 `writer_fencing` + +Audit question: Can a stale writer acknowledge after failover or lease expiry? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.18 `partitioning` + +Audit question: What key determines placement and what happens to cross-partition edges? + +Current assessment: Published distribution summary: single-node library/server. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.19 `rebalancing` + +Audit question: Can placement change online without changing logical identity? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.20 `replication` + +Audit question: Are replicas full, sharded, synchronous, asynchronous, or shared-storage readers? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.21 `optimizer` + +Audit question: Does the optimizer cost graph expansion, joins, network, cache, and remote requests? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.22 `statistics` + +Audit question: Which degree, correlation, path, and property statistics are persistent? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.23 `execution` + +Audit question: Is execution tuple-at-a-time, vectorized, factorized, compiled, matrix, or actor based? + +Current assessment: Expected family: Rust SPARQL parser/evaluator. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.24 `recursion` + +Audit question: How are BFS, shortest paths, trails, simple paths, and arbitrary reachability executed? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.25 `parallelism` + +Audit question: How does the engine avoid skew and nested parallelism under mixed queries? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.26 `memory` + +Audit question: Are all variable allocations charged to bounded query and system budgets? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.27 `spill` + +Audit question: Which operators spill, in what format, and with what admission controls? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.28 `cancellation` + +Audit question: Can cancellation stop CPU, local I/O, remote I/O, retries, and prefetch? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.29 `cache` + +Audit question: What is cached, how is it keyed, admitted, pinned, and evicted? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.30 `cold_start` + +Audit question: What metadata and data round trips are required with empty caches? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.31 `object_requests` + +Audit question: Can a query issue one remote request per node, edge, or result row? + +Current assessment: Published object-store posture: not S3-native. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.32 `cost_admission` + +Audit question: Are request, byte, CPU, spill, and result limits enforced before work? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.33 `observability` + +Audit question: Can operators report rows, edges, bytes, requests, stalls, memory, and spill? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.34 `language` + +Audit question: Which GQL/Cypher/SQL-PGQ/Gremlin/SPARQL semantics are declared and tested? + +Current assessment: Declared surface: SPARQL 1.1. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.35 `updates` + +Audit question: Are DDL, insert, merge, update, detach delete, and constraints complete? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.36 `bulk_load` + +Audit question: Does bulk load preserve transactional and index invariants? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.37 `backup` + +Audit question: Is backup consistent, incremental, immutable, and restore-tested? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.38 `gc` + +Audit question: How are old snapshots, orphan objects, tombstones, and indexes reclaimed safely? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.39 `security` + +Audit question: Are authentication, authorization, encryption, audit, and tenant isolation in scope? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.40 `operations` + +Audit question: What compaction, upgrade, repair, verification, and capacity procedures exist? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +## 5. Benchmark contract for this engine + +Every case runs correctness first, then isolated latency, then closed-loop concurrency, then open-loop overload. Report median, p95, p99, p99.9, timeout/rejection rate, throughput, CPU-seconds, peak RSS, cache bytes, disk bytes, network bytes, remote requests, write amplification, and estimated monthly cost. + +Warm means all intended engine caches are populated without changing the query parameters. Hot means the exact working set is resident. Cold means process-local, engine, OS, NVMe, and remote cache state are explicitly reset or a fresh namespace is used. Those words are never inferred from repetition count. + +### 5.1 `point_pk` — primary-key node lookup with one projected property + +- Applicability to Oxigraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.2 `point_edge` — stable edge-ID lookup including endpoints and one property + +- Applicability to Oxigraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.3 `degree_1` — degree-one outgoing expansion + +- Applicability to Oxigraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.4 `degree_32` — small adjacency expansion around degree 32 + +- Applicability to Oxigraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.5 `degree_1k` — medium adjacency expansion around degree 1,024 + +- Applicability to Oxigraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.6 `supernode` — range-limited expansion of a ten-million-degree supernode + +- Applicability to Oxigraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.7 `expand_2` — selective two-hop expansion + +- Applicability to Oxigraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.8 `expand_3` — three-hop frontier expansion with duplicate control + +- Applicability to Oxigraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.9 `expand_into` — edge-existence/expand-into between already-bound endpoints + +- Applicability to Oxigraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.10 `multi_edge` — parallel-edge identity and property projection + +- Applicability to Oxigraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.11 `shortest` — bidirectional point-to-point unweighted shortest path + +- Applicability to Oxigraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.12 `weighted` — weighted shortest path with property access + +- Applicability to Oxigraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.13 `var_walk` — bounded variable-length walk + +- Applicability to Oxigraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.14 `trail` — DIFFERENT EDGES trail enumeration + +- Applicability to Oxigraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.15 `simple` — simple-path enumeration with explicit bound + +- Applicability to Oxigraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.16 `triangle` — triangle pattern with worst-case-sensitive join + +- Applicability to Oxigraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.17 `cycle4` — four-cycle pattern + +- Applicability to Oxigraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.18 `star_join` — high-fanout star pattern with property filters + +- Applicability to Oxigraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.19 `optional` — optional match preserving null/bag semantics + +- Applicability to Oxigraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.20 `aggregate` — grouped aggregate after traversal + +- Applicability to Oxigraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.21 `topk` — ordered top-k with late property materialization + +- Applicability to Oxigraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.22 `scan` — full projected property scan + +- Applicability to Oxigraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.23 `selective_scan` — zone/index-pruned selective property scan + +- Applicability to Oxigraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.24 `mixed` — concurrent short reads, complex reads, and updates + +- Applicability to Oxigraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.25 `ingest` — sustained transactional ingest with indexes enabled + +- Applicability to Oxigraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.26 `bulk` — initial bulk load including index/CSR build + +- Applicability to Oxigraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.27 `checkpoint` — checkpoint or compaction while readers remain active + +- Applicability to Oxigraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.28 `recovery` — crash recovery at bounded dirty-log size + +- Applicability to Oxigraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.29 `cold` — same query after clearing engine and OS/cache tiers + +- Applicability to Oxigraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.30 `remote` — same query with authoritative bytes only in object storage + +- Applicability to Oxigraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +## 6. Fairness controls + +- Same logical dataset and update stream; engine-native physical layouts are allowed and disclosed. +- Same result semantics; unsupported queries remain unsupported rather than rewritten into easier questions. +- Same durable acknowledgement class for write comparisons. +- Same number of physical cores and memory limit for self-hosted single-node tests. +- Same aggregate resources and replication fault tolerance for distributed tests. +- Officially recommended tuning may be applied before the freeze and is committed with rationale. +- Query-specific hints are allowed only when equivalent hints are offered to every engine and separately charted. +- Load/build/index time and bytes are first-class results. +- Cold, warm, and hot results are separate charts. +- Managed services use public configurations and cannot borrow hidden same-machine resource claims. +- Failed runs, OOMs, correctness mismatches, and timeouts stay in the dataset. +- Every chart links raw samples and the exact reproduction command. + +## 7. Likely advantages and limits + +The strongest known reason to choose this engine is tied to its family `embedded Rust RDF store`, its execution path `Rust SPARQL parser/evaluator`, and its existing ecosystem. The strongest reason to reject it for zu's target is the gap between `not S3-native` and an S3-authoritative, request-budgeted, PB-scale graph service. + +Capacity statement: single-node; no PB proof. This is not converted into an edge-count claim without a physical byte model including IDs, both adjacency directions, properties, indexes, MVCC, WAL, replicas, and free space. + +Commercial statement: Apache-2.0 and MIT dual licensing. License cost, support cost, and unavailable enterprise capabilities remain visible in TCO and feature tables. + +## 8. Concrete lessons for zu + +1. Keep stable logical node and edge identity independent of row group, CSR slot, shard, and object range. +2. Store forward and reverse adjacency as immutable range-addressable tiles carrying edge IDs. +3. Feed queries adjacency batches and typed vectors; prohibit one storage call per logical element. +4. Use vectorized/factorized execution for property-heavy patterns and dedicated frontier operators for recursion. +5. Cost topology, properties, network, cache certainty, remote requests, and result materialization together. +6. Separate the local embedded profile from the object-authoritative distributed read profile. +7. Fence writers with monotonic epochs and make ambiguous commits reconcilable by transaction ID. +8. Pack small graph tiles into large immutable objects while retaining independent checksums and range offsets. +9. Keep the hot topology working set in RAM/NVMe; batch cold frontier misses into few remote rounds. +10. Admission-control remote requests and bytes so fixed-price plans have an enforceable upper bound. +11. Partition by workload-aware graph locality, and expose cross-partition semantics rather than hiding them. +12. Publish qualified wins per workload cell; never promise a universal tenfold advantage. + +## 9. Evidence gaps to close before publication + +- Exact current version and release date. +- Exact license text for the benchmarked artifact. +- Storage bytes per node/edge/property on all standard datasets. +- Stable-edge-ID and parallel-edge semantics. +- Isolation litmus results and commit acknowledgement point. +- Crash recovery time versus dirty WAL size. +- Supernode behavior and maximum tested degree. +- Cold-start metadata and request count. +- Distributed cross-partition query amplification. +- Peak memory under skew, cancellation, and overload. +- Background compaction/GC effect on tail latency. +- Full load/index/checkpoint/backup resource cost. +- Reproducible largest-scale result. +- Independent or audited benchmark evidence. + +## 10. Primary and official sources + +- [Source repository](https://github.com/oxigraph/oxigraph) +- [Project docs](https://docs.rs/oxigraph/) +- [LDBC SNB Interactive and audited disclosures](https://ldbcouncil.org/benchmarks/snb/interactive/) +- [LDBC Graphalytics](https://ldbcouncil.org/benchmarks/graphalytics/) +- [SoK: The Faults in our Graph Benchmarks](https://arxiv.org/abs/2404.00766) + +## 11. Source-handling rules + +- Official documentation and source are evidence for implemented or declared behavior, not independent performance. +- A vendor benchmark is labeled vendor claim until the harness reproduces it. +- A peer-reviewed paper establishes only the version, configuration, and workload it evaluated. +- Search snippets, comparison sites, and unsourced blogs are discovery aids, not final evidence. +- Unknown is a valid result and creates a concrete experiment or source-inspection task. +- All web facts are rechecked at benchmark freeze because this corpus is current only through the research date. + +## 12. Reproduction record template + +- engine: `Oxigraph` +- version: `TBD at benchmark freeze` +- artifact digest: `TBD` +- source commit: `TBD or managed-service N/A` +- edition/license: `TBD` +- query language/version: `TBD` +- storage and durability mode: `TBD` +- cluster and replication: `TBD` +- CPU/RAM/NVMe/network: `TBD` +- OS/kernel/filesystem: `TBD` +- dataset URI and digest: `TBD` +- loader command and duration: `TBD` +- physical bytes by category: `TBD` +- tuning file: `TBD` +- query corpus commit: `TBD` +- raw result URI/digest: `TBD` +- profiler/trace URI: `TBD` +- correctness status: `TBD` +- reviewer and rerun date: `TBD` diff --git a/docs/research/engine-puppygraph.md b/docs/research/engine-puppygraph.md new file mode 100644 index 0000000..24cd9a9 --- /dev/null +++ b/docs/research/engine-puppygraph.md @@ -0,0 +1,885 @@ +# PuppyGraph: 2026 deep technical and competitive specification + +Research cut: `2026-08-08` +Status: evidence-backed competitor audit; not a vendor endorsement +Family: `lakehouse graph query engine` +Evidence convention: **Observed/official**, **Vendor claim**, **Research inference**, **Unknown**, **Qualification target**. + +## 1. Decision summary + +PuppyGraph is the closest commercial graph-lake comparator for zu's remote profile. + +This document answers two questions: what this engine actually proves in 2026, and what zu must build or measure to earn a defensible advantage. A missing public detail remains unknown; it is never silently filled with a favorable assumption. + +### Snapshot card + +- Lifecycle: active commercial product. +- Data model: logical property graph mapped over tabular lake/warehouse data. +- Query surface: openCypher and Gremlin-facing workflows. +- Persistent layout: does not own the system of record; reads external warehouses/lakes and builds query-serving structures. +- Execution: distributed graph analytics and traversal over mapped relational data. +- Transactions: source-system semantics dominate; the graph layer is primarily analytical/read oriented. +- Distribution: cluster deployment with independent compute over external data. +- Object-storage posture: directly relevant: queries data in lake/object-backed systems but is not simply an S3 adjacency store. +- License/commercial boundary: commercial proprietary. +- Scale evidence: vendor claims petabyte data and deep traversal; independent audited evidence is required. +- Benchmark posture: benchmark must include source scan bytes, materialization, cache state, and warehouse cost. + +### Facts that materially affect comparison + +- F01 — PuppyGraph avoids graph ETL by mapping existing tables into a graph schema. +- F02 — Its architecture trades native ownership and OLTP control for governance and lakehouse reuse. +- F03 — Claims of petabyte scale describe the external-data architecture and need workload qualification. +- F04 — Cold-query performance depends on source layout, pruning, cache, network, and any acceleration state. +- F05 — Cost comparison must include the underlying warehouse or query service, not only PuppyGraph compute. + +### Bottom-line fit against zu's target + +- Very-low latency: compare hot point and bounded traversal paths; never extrapolate from scans or algorithms. +- Very-low resources: charge resident set, page cache, remote cache, background services, and replicas. +- Distributed: distinguish read replication, partitioned capacity, distributed transactions, and elastic stateless compute. +- Fixed cost: no engine has fixed marginal cost by declaration; admission, batching, and capacity reservations create the bound. +- S3 authority: backups, imports, lake scans, and S3-native demand paging are four different architectures. +- PB / trillion-edge scale: require a capacity derivation plus a run at the largest affordable scale; marketing adjectives do not qualify. +- Tenfold win: can be a per-cell qualification result, never a universal statement across incomparable workloads. + +## 2. Product and ecosystem boundary + +The audited unit is **PuppyGraph** in the exact release, edition, deployment, and durability mode recorded by the harness. The family classification is **lakehouse graph query engine**. The current lifecycle statement is: active commercial product. + +The harness must record binary/container digest, source commit when available, build flags, plugins, license/edition, language mode, storage mode, cluster topology, replication factor, durability settings, cache sizes, thread counts, NUMA policy, kernel, filesystem, cloud region, and all environment variables that affect execution. + +A managed service is not placed in a same-hardware chart. It receives a service-level result with provisioned units, region, public price, and observed provider metrics. A historical engine remains useful for regression but cannot support a claim about beating all current competitors. + +## 3. Architecture reconstruction + +### 3.1 Logical model + +PuppyGraph exposes logical property graph mapped over tabular lake/warehouse data. The conformance corpus must test nulls, missing properties, labels/types, direction, self-loops, parallel edges, element equality, path equality, bag semantics, ordering, numeric overflow, string collation, temporal values, and schema evolution. + +### 3.2 Language and compiler + +The public query surface is openCypher and Gremlin-facing workflows. Syntax similarity is not semantic equivalence. Every supported construct needs a result oracle and an unsupported-feature declaration. + +### 3.3 Storage + +The best supported storage summary is: does not own the system of record; reads external warehouses/lakes and builds query-serving structures. This statement must be refined from code, format documentation, or provider counters before using it in a performance explanation. + +### 3.4 Execution + +The best supported execution summary is: distributed graph analytics and traversal over mapped relational data. The benchmark profiler must confirm which runtime and operators actually executed. + +### 3.5 Transactions and recovery + +The public contract is: source-system semantics dominate; the graph layer is primarily analytical/read oriented. Exact acknowledgement, isolation anomalies, recovery bounds, and failover behavior remain separate qualification items. + +### 3.6 Distribution + +The deployment shape is: cluster deployment with independent compute over external data. Replication is not capacity sharding; sharding is not distributed ACID; stateless readers are not stateless storage. + +### 3.7 Object storage and cost + +The 2026 posture is: directly relevant: queries data in lake/object-backed systems but is not simply an S3 adjacency store. The audit distinguishes authoritative live bytes, derived acceleration, backup, import/export, and spill. + +## 4. Forty-control deep audit + +### 4.1 `product_boundary` + +Audit question: What exact executable, edition, and storage mode is the system under test? + +Current assessment: Pin PuppyGraph, lifecycle `active commercial product`, and its edition/mode. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.2 `authority` + +Audit question: Which durable component is the source of truth after every acknowledged write? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.3 `identity` + +Audit question: Are node and edge identities stable across compaction, export, replication, and restore? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.4 `parallel_edges` + +Audit question: Can distinct parallel edges retain properties and trail identity end to end? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.5 `schema` + +Audit question: Is the schema open, closed, optional, inferred, or externally mapped? + +Current assessment: Start from `logical property graph mapped over tabular lake/warehouse data` and test actual constraints. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.6 `labels` + +Audit question: How are multiple labels represented and indexed? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.7 `adjacency_out` + +Audit question: How is outgoing adjacency located, encoded, split, cached, and updated? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.8 `adjacency_in` + +Audit question: Is incoming adjacency first-class, derived, replicated, or a fan-out operation? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.9 `supernodes` + +Audit question: How are million-to-billion-degree vertices represented and scheduled? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.10 `properties` + +Audit question: Are properties co-located, columnar, row-oriented, document-encoded, or remote? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.11 `compression` + +Audit question: Which topology, integer, string, null, and floating encodings are implemented? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.12 `checksums` + +Audit question: What integrity unit is verified on point reads and range reads? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.13 `snapshot` + +Audit question: What exact token pins graph data, schema, statistics, and indexes? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.14 `isolation` + +Audit question: Which anomalies are forbidden at the documented isolation level? + +Current assessment: Published summary: source-system semantics dominate; the graph layer is primarily analytical/read oriented. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.15 `durability` + +Audit question: What device/service acknowledgement is required before commit returns? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.16 `recovery` + +Audit question: What bounds restart work after a clean stop and a crash? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.17 `writer_fencing` + +Audit question: Can a stale writer acknowledge after failover or lease expiry? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.18 `partitioning` + +Audit question: What key determines placement and what happens to cross-partition edges? + +Current assessment: Published distribution summary: cluster deployment with independent compute over external data. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.19 `rebalancing` + +Audit question: Can placement change online without changing logical identity? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.20 `replication` + +Audit question: Are replicas full, sharded, synchronous, asynchronous, or shared-storage readers? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.21 `optimizer` + +Audit question: Does the optimizer cost graph expansion, joins, network, cache, and remote requests? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.22 `statistics` + +Audit question: Which degree, correlation, path, and property statistics are persistent? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.23 `execution` + +Audit question: Is execution tuple-at-a-time, vectorized, factorized, compiled, matrix, or actor based? + +Current assessment: Expected family: distributed graph analytics and traversal over mapped relational data. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.24 `recursion` + +Audit question: How are BFS, shortest paths, trails, simple paths, and arbitrary reachability executed? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.25 `parallelism` + +Audit question: How does the engine avoid skew and nested parallelism under mixed queries? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.26 `memory` + +Audit question: Are all variable allocations charged to bounded query and system budgets? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.27 `spill` + +Audit question: Which operators spill, in what format, and with what admission controls? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.28 `cancellation` + +Audit question: Can cancellation stop CPU, local I/O, remote I/O, retries, and prefetch? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.29 `cache` + +Audit question: What is cached, how is it keyed, admitted, pinned, and evicted? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.30 `cold_start` + +Audit question: What metadata and data round trips are required with empty caches? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.31 `object_requests` + +Audit question: Can a query issue one remote request per node, edge, or result row? + +Current assessment: Published object-store posture: directly relevant: queries data in lake/object-backed systems but is not simply an S3 adjacency store. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.32 `cost_admission` + +Audit question: Are request, byte, CPU, spill, and result limits enforced before work? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.33 `observability` + +Audit question: Can operators report rows, edges, bytes, requests, stalls, memory, and spill? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.34 `language` + +Audit question: Which GQL/Cypher/SQL-PGQ/Gremlin/SPARQL semantics are declared and tested? + +Current assessment: Declared surface: openCypher and Gremlin-facing workflows. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.35 `updates` + +Audit question: Are DDL, insert, merge, update, detach delete, and constraints complete? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.36 `bulk_load` + +Audit question: Does bulk load preserve transactional and index invariants? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.37 `backup` + +Audit question: Is backup consistent, incremental, immutable, and restore-tested? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.38 `gc` + +Audit question: How are old snapshots, orphan objects, tombstones, and indexes reclaimed safely? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.39 `security` + +Audit question: Are authentication, authorization, encryption, audit, and tenant isolation in scope? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.40 `operations` + +Audit question: What compaction, upgrade, repair, verification, and capacity procedures exist? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +## 5. Benchmark contract for this engine + +Every case runs correctness first, then isolated latency, then closed-loop concurrency, then open-loop overload. Report median, p95, p99, p99.9, timeout/rejection rate, throughput, CPU-seconds, peak RSS, cache bytes, disk bytes, network bytes, remote requests, write amplification, and estimated monthly cost. + +Warm means all intended engine caches are populated without changing the query parameters. Hot means the exact working set is resident. Cold means process-local, engine, OS, NVMe, and remote cache state are explicitly reset or a fresh namespace is used. Those words are never inferred from repetition count. + +### 5.1 `point_pk` — primary-key node lookup with one projected property + +- Applicability to PuppyGraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.2 `point_edge` — stable edge-ID lookup including endpoints and one property + +- Applicability to PuppyGraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.3 `degree_1` — degree-one outgoing expansion + +- Applicability to PuppyGraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.4 `degree_32` — small adjacency expansion around degree 32 + +- Applicability to PuppyGraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.5 `degree_1k` — medium adjacency expansion around degree 1,024 + +- Applicability to PuppyGraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.6 `supernode` — range-limited expansion of a ten-million-degree supernode + +- Applicability to PuppyGraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.7 `expand_2` — selective two-hop expansion + +- Applicability to PuppyGraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.8 `expand_3` — three-hop frontier expansion with duplicate control + +- Applicability to PuppyGraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.9 `expand_into` — edge-existence/expand-into between already-bound endpoints + +- Applicability to PuppyGraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.10 `multi_edge` — parallel-edge identity and property projection + +- Applicability to PuppyGraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.11 `shortest` — bidirectional point-to-point unweighted shortest path + +- Applicability to PuppyGraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.12 `weighted` — weighted shortest path with property access + +- Applicability to PuppyGraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.13 `var_walk` — bounded variable-length walk + +- Applicability to PuppyGraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.14 `trail` — DIFFERENT EDGES trail enumeration + +- Applicability to PuppyGraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.15 `simple` — simple-path enumeration with explicit bound + +- Applicability to PuppyGraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.16 `triangle` — triangle pattern with worst-case-sensitive join + +- Applicability to PuppyGraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.17 `cycle4` — four-cycle pattern + +- Applicability to PuppyGraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.18 `star_join` — high-fanout star pattern with property filters + +- Applicability to PuppyGraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.19 `optional` — optional match preserving null/bag semantics + +- Applicability to PuppyGraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.20 `aggregate` — grouped aggregate after traversal + +- Applicability to PuppyGraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.21 `topk` — ordered top-k with late property materialization + +- Applicability to PuppyGraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.22 `scan` — full projected property scan + +- Applicability to PuppyGraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.23 `selective_scan` — zone/index-pruned selective property scan + +- Applicability to PuppyGraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.24 `mixed` — concurrent short reads, complex reads, and updates + +- Applicability to PuppyGraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.25 `ingest` — sustained transactional ingest with indexes enabled + +- Applicability to PuppyGraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.26 `bulk` — initial bulk load including index/CSR build + +- Applicability to PuppyGraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.27 `checkpoint` — checkpoint or compaction while readers remain active + +- Applicability to PuppyGraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.28 `recovery` — crash recovery at bounded dirty-log size + +- Applicability to PuppyGraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.29 `cold` — same query after clearing engine and OS/cache tiers + +- Applicability to PuppyGraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.30 `remote` — same query with authoritative bytes only in object storage + +- Applicability to PuppyGraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +## 6. Fairness controls + +- Same logical dataset and update stream; engine-native physical layouts are allowed and disclosed. +- Same result semantics; unsupported queries remain unsupported rather than rewritten into easier questions. +- Same durable acknowledgement class for write comparisons. +- Same number of physical cores and memory limit for self-hosted single-node tests. +- Same aggregate resources and replication fault tolerance for distributed tests. +- Officially recommended tuning may be applied before the freeze and is committed with rationale. +- Query-specific hints are allowed only when equivalent hints are offered to every engine and separately charted. +- Load/build/index time and bytes are first-class results. +- Cold, warm, and hot results are separate charts. +- Managed services use public configurations and cannot borrow hidden same-machine resource claims. +- Failed runs, OOMs, correctness mismatches, and timeouts stay in the dataset. +- Every chart links raw samples and the exact reproduction command. + +## 7. Likely advantages and limits + +The strongest known reason to choose this engine is tied to its family `lakehouse graph query engine`, its execution path `distributed graph analytics and traversal over mapped relational data`, and its existing ecosystem. The strongest reason to reject it for zu's target is the gap between `directly relevant: queries data in lake/object-backed systems but is not simply an S3 adjacency store` and an S3-authoritative, request-budgeted, PB-scale graph service. + +Capacity statement: vendor claims petabyte data and deep traversal; independent audited evidence is required. This is not converted into an edge-count claim without a physical byte model including IDs, both adjacency directions, properties, indexes, MVCC, WAL, replicas, and free space. + +Commercial statement: commercial proprietary. License cost, support cost, and unavailable enterprise capabilities remain visible in TCO and feature tables. + +## 8. Concrete lessons for zu + +1. Keep stable logical node and edge identity independent of row group, CSR slot, shard, and object range. +2. Store forward and reverse adjacency as immutable range-addressable tiles carrying edge IDs. +3. Feed queries adjacency batches and typed vectors; prohibit one storage call per logical element. +4. Use vectorized/factorized execution for property-heavy patterns and dedicated frontier operators for recursion. +5. Cost topology, properties, network, cache certainty, remote requests, and result materialization together. +6. Separate the local embedded profile from the object-authoritative distributed read profile. +7. Fence writers with monotonic epochs and make ambiguous commits reconcilable by transaction ID. +8. Pack small graph tiles into large immutable objects while retaining independent checksums and range offsets. +9. Keep the hot topology working set in RAM/NVMe; batch cold frontier misses into few remote rounds. +10. Admission-control remote requests and bytes so fixed-price plans have an enforceable upper bound. +11. Partition by workload-aware graph locality, and expose cross-partition semantics rather than hiding them. +12. Publish qualified wins per workload cell; never promise a universal tenfold advantage. + +## 9. Evidence gaps to close before publication + +- Exact current version and release date. +- Exact license text for the benchmarked artifact. +- Storage bytes per node/edge/property on all standard datasets. +- Stable-edge-ID and parallel-edge semantics. +- Isolation litmus results and commit acknowledgement point. +- Crash recovery time versus dirty WAL size. +- Supernode behavior and maximum tested degree. +- Cold-start metadata and request count. +- Distributed cross-partition query amplification. +- Peak memory under skew, cancellation, and overload. +- Background compaction/GC effect on tail latency. +- Full load/index/checkpoint/backup resource cost. +- Reproducible largest-scale result. +- Independent or audited benchmark evidence. + +## 10. Primary and official sources + +- [Official documentation](https://docs.puppygraph.com/) +- [Getting started](https://docs.puppygraph.com/getting-started/) +- [Graph algorithms](https://docs.puppygraph.com/graph-algorithms/) +- [LDBC SNB Interactive and audited disclosures](https://ldbcouncil.org/benchmarks/snb/interactive/) +- [LDBC Graphalytics](https://ldbcouncil.org/benchmarks/graphalytics/) +- [SoK: The Faults in our Graph Benchmarks](https://arxiv.org/abs/2404.00766) + +## 11. Source-handling rules + +- Official documentation and source are evidence for implemented or declared behavior, not independent performance. +- A vendor benchmark is labeled vendor claim until the harness reproduces it. +- A peer-reviewed paper establishes only the version, configuration, and workload it evaluated. +- Search snippets, comparison sites, and unsourced blogs are discovery aids, not final evidence. +- Unknown is a valid result and creates a concrete experiment or source-inspection task. +- All web facts are rechecked at benchmark freeze because this corpus is current only through the research date. + +## 12. Reproduction record template + +- engine: `PuppyGraph` +- version: `TBD at benchmark freeze` +- artifact digest: `TBD` +- source commit: `TBD or managed-service N/A` +- edition/license: `TBD` +- query language/version: `TBD` +- storage and durability mode: `TBD` +- cluster and replication: `TBD` +- CPU/RAM/NVMe/network: `TBD` +- OS/kernel/filesystem: `TBD` +- dataset URI and digest: `TBD` +- loader command and duration: `TBD` +- physical bytes by category: `TBD` +- tuning file: `TBD` +- query corpus commit: `TBD` +- raw result URI/digest: `TBD` +- profiler/trace URI: `TBD` +- correctness status: `TBD` +- reviewer and rerun date: `TBD` diff --git a/docs/research/engine-redisgraph.md b/docs/research/engine-redisgraph.md new file mode 100644 index 0000000..861b03e --- /dev/null +++ b/docs/research/engine-redisgraph.md @@ -0,0 +1,884 @@ +# RedisGraph (legacy): 2026 deep technical and competitive specification + +Research cut: `2026-08-08` +Status: evidence-backed competitor audit; not a vendor endorsement +Family: `matrix property graph` +Evidence convention: **Observed/official**, **Vendor claim**, **Research inference**, **Unknown**, **Qualification target**. + +## 1. Decision summary + +RedisGraph should not be counted as an active separate competitor; FalkorDB is the maintained comparison. + +This document answers two questions: what this engine actually proves in 2026, and what zu must build or measure to earn a defensible advantage. A missing public detail remains unknown; it is never silently filled with a favorable assumption. + +### Snapshot card + +- Lifecycle: end-of-life lineage continued by FalkorDB. +- Data model: property graph over sparse matrices. +- Query surface: openCypher. +- Persistent layout: Redis module plus GraphBLAS matrices. +- Execution: algebraic query execution. +- Transactions: Redis persistence/replication semantics. +- Distribution: Redis deployment topology. +- Object-storage posture: not S3-native. +- License/commercial boundary: Redis Source Available License-era package; historical terms vary. +- Scale evidence: memory-oriented single-shard baseline. +- Benchmark posture: use only to show lineage or reproduce old papers. + +### Facts that materially affect comparison + +- F01 — RedisGraph introduced the sparse-matrix property-graph implementation now continued by FalkorDB. +- F02 — The upstream repository is not a current independent product. +- F03 — Memory-first behavior can deliver fast warm traversals at high capacity cost. +- F04 — Redis persistence modes change durability and latency. +- F05 — Historical benchmarks often omit persistence and must be reclassified. + +### Bottom-line fit against zu's target + +- Very-low latency: compare hot point and bounded traversal paths; never extrapolate from scans or algorithms. +- Very-low resources: charge resident set, page cache, remote cache, background services, and replicas. +- Distributed: distinguish read replication, partitioned capacity, distributed transactions, and elastic stateless compute. +- Fixed cost: no engine has fixed marginal cost by declaration; admission, batching, and capacity reservations create the bound. +- S3 authority: backups, imports, lake scans, and S3-native demand paging are four different architectures. +- PB / trillion-edge scale: require a capacity derivation plus a run at the largest affordable scale; marketing adjectives do not qualify. +- Tenfold win: can be a per-cell qualification result, never a universal statement across incomparable workloads. + +## 2. Product and ecosystem boundary + +The audited unit is **RedisGraph (legacy)** in the exact release, edition, deployment, and durability mode recorded by the harness. The family classification is **matrix property graph**. The current lifecycle statement is: end-of-life lineage continued by FalkorDB. + +The harness must record binary/container digest, source commit when available, build flags, plugins, license/edition, language mode, storage mode, cluster topology, replication factor, durability settings, cache sizes, thread counts, NUMA policy, kernel, filesystem, cloud region, and all environment variables that affect execution. + +A managed service is not placed in a same-hardware chart. It receives a service-level result with provisioned units, region, public price, and observed provider metrics. A historical engine remains useful for regression but cannot support a claim about beating all current competitors. + +## 3. Architecture reconstruction + +### 3.1 Logical model + +RedisGraph (legacy) exposes property graph over sparse matrices. The conformance corpus must test nulls, missing properties, labels/types, direction, self-loops, parallel edges, element equality, path equality, bag semantics, ordering, numeric overflow, string collation, temporal values, and schema evolution. + +### 3.2 Language and compiler + +The public query surface is openCypher. Syntax similarity is not semantic equivalence. Every supported construct needs a result oracle and an unsupported-feature declaration. + +### 3.3 Storage + +The best supported storage summary is: Redis module plus GraphBLAS matrices. This statement must be refined from code, format documentation, or provider counters before using it in a performance explanation. + +### 3.4 Execution + +The best supported execution summary is: algebraic query execution. The benchmark profiler must confirm which runtime and operators actually executed. + +### 3.5 Transactions and recovery + +The public contract is: Redis persistence/replication semantics. Exact acknowledgement, isolation anomalies, recovery bounds, and failover behavior remain separate qualification items. + +### 3.6 Distribution + +The deployment shape is: Redis deployment topology. Replication is not capacity sharding; sharding is not distributed ACID; stateless readers are not stateless storage. + +### 3.7 Object storage and cost + +The 2026 posture is: not S3-native. The audit distinguishes authoritative live bytes, derived acceleration, backup, import/export, and spill. + +## 4. Forty-control deep audit + +### 4.1 `product_boundary` + +Audit question: What exact executable, edition, and storage mode is the system under test? + +Current assessment: Pin RedisGraph (legacy), lifecycle `end-of-life lineage continued by FalkorDB`, and its edition/mode. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.2 `authority` + +Audit question: Which durable component is the source of truth after every acknowledged write? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.3 `identity` + +Audit question: Are node and edge identities stable across compaction, export, replication, and restore? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.4 `parallel_edges` + +Audit question: Can distinct parallel edges retain properties and trail identity end to end? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.5 `schema` + +Audit question: Is the schema open, closed, optional, inferred, or externally mapped? + +Current assessment: Start from `property graph over sparse matrices` and test actual constraints. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.6 `labels` + +Audit question: How are multiple labels represented and indexed? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.7 `adjacency_out` + +Audit question: How is outgoing adjacency located, encoded, split, cached, and updated? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.8 `adjacency_in` + +Audit question: Is incoming adjacency first-class, derived, replicated, or a fan-out operation? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.9 `supernodes` + +Audit question: How are million-to-billion-degree vertices represented and scheduled? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.10 `properties` + +Audit question: Are properties co-located, columnar, row-oriented, document-encoded, or remote? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.11 `compression` + +Audit question: Which topology, integer, string, null, and floating encodings are implemented? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.12 `checksums` + +Audit question: What integrity unit is verified on point reads and range reads? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.13 `snapshot` + +Audit question: What exact token pins graph data, schema, statistics, and indexes? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.14 `isolation` + +Audit question: Which anomalies are forbidden at the documented isolation level? + +Current assessment: Published summary: Redis persistence/replication semantics. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.15 `durability` + +Audit question: What device/service acknowledgement is required before commit returns? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.16 `recovery` + +Audit question: What bounds restart work after a clean stop and a crash? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.17 `writer_fencing` + +Audit question: Can a stale writer acknowledge after failover or lease expiry? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.18 `partitioning` + +Audit question: What key determines placement and what happens to cross-partition edges? + +Current assessment: Published distribution summary: Redis deployment topology. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.19 `rebalancing` + +Audit question: Can placement change online without changing logical identity? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.20 `replication` + +Audit question: Are replicas full, sharded, synchronous, asynchronous, or shared-storage readers? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.21 `optimizer` + +Audit question: Does the optimizer cost graph expansion, joins, network, cache, and remote requests? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.22 `statistics` + +Audit question: Which degree, correlation, path, and property statistics are persistent? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.23 `execution` + +Audit question: Is execution tuple-at-a-time, vectorized, factorized, compiled, matrix, or actor based? + +Current assessment: Expected family: algebraic query execution. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.24 `recursion` + +Audit question: How are BFS, shortest paths, trails, simple paths, and arbitrary reachability executed? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.25 `parallelism` + +Audit question: How does the engine avoid skew and nested parallelism under mixed queries? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.26 `memory` + +Audit question: Are all variable allocations charged to bounded query and system budgets? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.27 `spill` + +Audit question: Which operators spill, in what format, and with what admission controls? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.28 `cancellation` + +Audit question: Can cancellation stop CPU, local I/O, remote I/O, retries, and prefetch? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.29 `cache` + +Audit question: What is cached, how is it keyed, admitted, pinned, and evicted? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.30 `cold_start` + +Audit question: What metadata and data round trips are required with empty caches? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.31 `object_requests` + +Audit question: Can a query issue one remote request per node, edge, or result row? + +Current assessment: Published object-store posture: not S3-native. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.32 `cost_admission` + +Audit question: Are request, byte, CPU, spill, and result limits enforced before work? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.33 `observability` + +Audit question: Can operators report rows, edges, bytes, requests, stalls, memory, and spill? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.34 `language` + +Audit question: Which GQL/Cypher/SQL-PGQ/Gremlin/SPARQL semantics are declared and tested? + +Current assessment: Declared surface: openCypher. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.35 `updates` + +Audit question: Are DDL, insert, merge, update, detach delete, and constraints complete? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.36 `bulk_load` + +Audit question: Does bulk load preserve transactional and index invariants? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.37 `backup` + +Audit question: Is backup consistent, incremental, immutable, and restore-tested? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.38 `gc` + +Audit question: How are old snapshots, orphan objects, tombstones, and indexes reclaimed safely? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.39 `security` + +Audit question: Are authentication, authorization, encryption, audit, and tenant isolation in scope? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.40 `operations` + +Audit question: What compaction, upgrade, repair, verification, and capacity procedures exist? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +## 5. Benchmark contract for this engine + +Every case runs correctness first, then isolated latency, then closed-loop concurrency, then open-loop overload. Report median, p95, p99, p99.9, timeout/rejection rate, throughput, CPU-seconds, peak RSS, cache bytes, disk bytes, network bytes, remote requests, write amplification, and estimated monthly cost. + +Warm means all intended engine caches are populated without changing the query parameters. Hot means the exact working set is resident. Cold means process-local, engine, OS, NVMe, and remote cache state are explicitly reset or a fresh namespace is used. Those words are never inferred from repetition count. + +### 5.1 `point_pk` — primary-key node lookup with one projected property + +- Applicability to RedisGraph (legacy): required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.2 `point_edge` — stable edge-ID lookup including endpoints and one property + +- Applicability to RedisGraph (legacy): required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.3 `degree_1` — degree-one outgoing expansion + +- Applicability to RedisGraph (legacy): required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.4 `degree_32` — small adjacency expansion around degree 32 + +- Applicability to RedisGraph (legacy): required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.5 `degree_1k` — medium adjacency expansion around degree 1,024 + +- Applicability to RedisGraph (legacy): required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.6 `supernode` — range-limited expansion of a ten-million-degree supernode + +- Applicability to RedisGraph (legacy): required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.7 `expand_2` — selective two-hop expansion + +- Applicability to RedisGraph (legacy): required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.8 `expand_3` — three-hop frontier expansion with duplicate control + +- Applicability to RedisGraph (legacy): required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.9 `expand_into` — edge-existence/expand-into between already-bound endpoints + +- Applicability to RedisGraph (legacy): required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.10 `multi_edge` — parallel-edge identity and property projection + +- Applicability to RedisGraph (legacy): required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.11 `shortest` — bidirectional point-to-point unweighted shortest path + +- Applicability to RedisGraph (legacy): required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.12 `weighted` — weighted shortest path with property access + +- Applicability to RedisGraph (legacy): required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.13 `var_walk` — bounded variable-length walk + +- Applicability to RedisGraph (legacy): required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.14 `trail` — DIFFERENT EDGES trail enumeration + +- Applicability to RedisGraph (legacy): required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.15 `simple` — simple-path enumeration with explicit bound + +- Applicability to RedisGraph (legacy): required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.16 `triangle` — triangle pattern with worst-case-sensitive join + +- Applicability to RedisGraph (legacy): required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.17 `cycle4` — four-cycle pattern + +- Applicability to RedisGraph (legacy): required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.18 `star_join` — high-fanout star pattern with property filters + +- Applicability to RedisGraph (legacy): required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.19 `optional` — optional match preserving null/bag semantics + +- Applicability to RedisGraph (legacy): required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.20 `aggregate` — grouped aggregate after traversal + +- Applicability to RedisGraph (legacy): required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.21 `topk` — ordered top-k with late property materialization + +- Applicability to RedisGraph (legacy): required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.22 `scan` — full projected property scan + +- Applicability to RedisGraph (legacy): required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.23 `selective_scan` — zone/index-pruned selective property scan + +- Applicability to RedisGraph (legacy): required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.24 `mixed` — concurrent short reads, complex reads, and updates + +- Applicability to RedisGraph (legacy): required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.25 `ingest` — sustained transactional ingest with indexes enabled + +- Applicability to RedisGraph (legacy): required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.26 `bulk` — initial bulk load including index/CSR build + +- Applicability to RedisGraph (legacy): required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.27 `checkpoint` — checkpoint or compaction while readers remain active + +- Applicability to RedisGraph (legacy): required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.28 `recovery` — crash recovery at bounded dirty-log size + +- Applicability to RedisGraph (legacy): required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.29 `cold` — same query after clearing engine and OS/cache tiers + +- Applicability to RedisGraph (legacy): required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.30 `remote` — same query with authoritative bytes only in object storage + +- Applicability to RedisGraph (legacy): required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +## 6. Fairness controls + +- Same logical dataset and update stream; engine-native physical layouts are allowed and disclosed. +- Same result semantics; unsupported queries remain unsupported rather than rewritten into easier questions. +- Same durable acknowledgement class for write comparisons. +- Same number of physical cores and memory limit for self-hosted single-node tests. +- Same aggregate resources and replication fault tolerance for distributed tests. +- Officially recommended tuning may be applied before the freeze and is committed with rationale. +- Query-specific hints are allowed only when equivalent hints are offered to every engine and separately charted. +- Load/build/index time and bytes are first-class results. +- Cold, warm, and hot results are separate charts. +- Managed services use public configurations and cannot borrow hidden same-machine resource claims. +- Failed runs, OOMs, correctness mismatches, and timeouts stay in the dataset. +- Every chart links raw samples and the exact reproduction command. + +## 7. Likely advantages and limits + +The strongest known reason to choose this engine is tied to its family `matrix property graph`, its execution path `algebraic query execution`, and its existing ecosystem. The strongest reason to reject it for zu's target is the gap between `not S3-native` and an S3-authoritative, request-budgeted, PB-scale graph service. + +Capacity statement: memory-oriented single-shard baseline. This is not converted into an edge-count claim without a physical byte model including IDs, both adjacency directions, properties, indexes, MVCC, WAL, replicas, and free space. + +Commercial statement: Redis Source Available License-era package; historical terms vary. License cost, support cost, and unavailable enterprise capabilities remain visible in TCO and feature tables. + +## 8. Concrete lessons for zu + +1. Keep stable logical node and edge identity independent of row group, CSR slot, shard, and object range. +2. Store forward and reverse adjacency as immutable range-addressable tiles carrying edge IDs. +3. Feed queries adjacency batches and typed vectors; prohibit one storage call per logical element. +4. Use vectorized/factorized execution for property-heavy patterns and dedicated frontier operators for recursion. +5. Cost topology, properties, network, cache certainty, remote requests, and result materialization together. +6. Separate the local embedded profile from the object-authoritative distributed read profile. +7. Fence writers with monotonic epochs and make ambiguous commits reconcilable by transaction ID. +8. Pack small graph tiles into large immutable objects while retaining independent checksums and range offsets. +9. Keep the hot topology working set in RAM/NVMe; batch cold frontier misses into few remote rounds. +10. Admission-control remote requests and bytes so fixed-price plans have an enforceable upper bound. +11. Partition by workload-aware graph locality, and expose cross-partition semantics rather than hiding them. +12. Publish qualified wins per workload cell; never promise a universal tenfold advantage. + +## 9. Evidence gaps to close before publication + +- Exact current version and release date. +- Exact license text for the benchmarked artifact. +- Storage bytes per node/edge/property on all standard datasets. +- Stable-edge-ID and parallel-edge semantics. +- Isolation litmus results and commit acknowledgement point. +- Crash recovery time versus dirty WAL size. +- Supernode behavior and maximum tested degree. +- Cold-start metadata and request count. +- Distributed cross-partition query amplification. +- Peak memory under skew, cancellation, and overload. +- Background compaction/GC effect on tail latency. +- Full load/index/checkpoint/backup resource cost. +- Reproducible largest-scale result. +- Independent or audited benchmark evidence. + +## 10. Primary and official sources + +- [Repository](https://github.com/RedisGraph/RedisGraph) +- [Successor](https://github.com/FalkorDB/FalkorDB) +- [LDBC SNB Interactive and audited disclosures](https://ldbcouncil.org/benchmarks/snb/interactive/) +- [LDBC Graphalytics](https://ldbcouncil.org/benchmarks/graphalytics/) +- [SoK: The Faults in our Graph Benchmarks](https://arxiv.org/abs/2404.00766) + +## 11. Source-handling rules + +- Official documentation and source are evidence for implemented or declared behavior, not independent performance. +- A vendor benchmark is labeled vendor claim until the harness reproduces it. +- A peer-reviewed paper establishes only the version, configuration, and workload it evaluated. +- Search snippets, comparison sites, and unsourced blogs are discovery aids, not final evidence. +- Unknown is a valid result and creates a concrete experiment or source-inspection task. +- All web facts are rechecked at benchmark freeze because this corpus is current only through the research date. + +## 12. Reproduction record template + +- engine: `RedisGraph (legacy)` +- version: `TBD at benchmark freeze` +- artifact digest: `TBD` +- source commit: `TBD or managed-service N/A` +- edition/license: `TBD` +- query language/version: `TBD` +- storage and durability mode: `TBD` +- cluster and replication: `TBD` +- CPU/RAM/NVMe/network: `TBD` +- OS/kernel/filesystem: `TBD` +- dataset URI and digest: `TBD` +- loader command and duration: `TBD` +- physical bytes by category: `TBD` +- tuning file: `TBD` +- query corpus commit: `TBD` +- raw result URI/digest: `TBD` +- profiler/trace URI: `TBD` +- correctness status: `TBD` +- reviewer and rerun date: `TBD` diff --git a/docs/research/engine-sap_hana_graph.md b/docs/research/engine-sap_hana_graph.md new file mode 100644 index 0000000..2166e6e --- /dev/null +++ b/docs/research/engine-sap_hana_graph.md @@ -0,0 +1,883 @@ +# SAP HANA Cloud Property Graph Engine: 2026 deep technical and competitive specification + +Research cut: `2026-08-08` +Status: evidence-backed competitor audit; not a vendor endorsement +Family: `in-memory relational-integrated graph engine` +Evidence convention: **Observed/official**, **Vendor claim**, **Research inference**, **Unknown**, **Qualification target**. + +## 1. Decision summary + +HANA Graph is a strong in-memory integrated baseline, but resource cost is the likely zu differentiator. + +This document answers two questions: what this engine actually proves in 2026, and what zu must build or measure to earn a defensible advantage. A missing public detail remains unknown; it is never silently filled with a favorable assumption. + +### Snapshot card + +- Lifecycle: active QRC 1/2026. +- Data model: property graph workspace over HANA tables. +- Query surface: openCypher subset, GraphScript, SQL. +- Persistent layout: SAP HANA columnar/in-memory relational storage. +- Execution: graph workspace execution and GraphScript stored procedures. +- Transactions: inherits HANA database transactions for source data. +- Distribution: HANA scale-up/scale-out deployment depending edition. +- Object-storage posture: not S3-native live serving. +- License/commercial boundary: commercial proprietary. +- Scale evidence: enterprise analytical scale; no public PB graph evidence. +- Benchmark posture: measure graph workspace creation, memory footprint, and mixed SQL/graph execution. + +### Facts that materially affect comparison + +- F01 — Graph workspaces map relational tables to vertices and edges. +- F02 — GraphScript provides procedural graph algorithms close to data. +- F03 — The current engine exposes an openCypher interface with documented subset semantics. +- F04 — In-memory columnar storage favors property scans but has a high capacity price. +- F05 — Graph plus SQL interoperability is its primary systems advantage. + +### Bottom-line fit against zu's target + +- Very-low latency: compare hot point and bounded traversal paths; never extrapolate from scans or algorithms. +- Very-low resources: charge resident set, page cache, remote cache, background services, and replicas. +- Distributed: distinguish read replication, partitioned capacity, distributed transactions, and elastic stateless compute. +- Fixed cost: no engine has fixed marginal cost by declaration; admission, batching, and capacity reservations create the bound. +- S3 authority: backups, imports, lake scans, and S3-native demand paging are four different architectures. +- PB / trillion-edge scale: require a capacity derivation plus a run at the largest affordable scale; marketing adjectives do not qualify. +- Tenfold win: can be a per-cell qualification result, never a universal statement across incomparable workloads. + +## 2. Product and ecosystem boundary + +The audited unit is **SAP HANA Cloud Property Graph Engine** in the exact release, edition, deployment, and durability mode recorded by the harness. The family classification is **in-memory relational-integrated graph engine**. The current lifecycle statement is: active QRC 1/2026. + +The harness must record binary/container digest, source commit when available, build flags, plugins, license/edition, language mode, storage mode, cluster topology, replication factor, durability settings, cache sizes, thread counts, NUMA policy, kernel, filesystem, cloud region, and all environment variables that affect execution. + +A managed service is not placed in a same-hardware chart. It receives a service-level result with provisioned units, region, public price, and observed provider metrics. A historical engine remains useful for regression but cannot support a claim about beating all current competitors. + +## 3. Architecture reconstruction + +### 3.1 Logical model + +SAP HANA Cloud Property Graph Engine exposes property graph workspace over HANA tables. The conformance corpus must test nulls, missing properties, labels/types, direction, self-loops, parallel edges, element equality, path equality, bag semantics, ordering, numeric overflow, string collation, temporal values, and schema evolution. + +### 3.2 Language and compiler + +The public query surface is openCypher subset, GraphScript, SQL. Syntax similarity is not semantic equivalence. Every supported construct needs a result oracle and an unsupported-feature declaration. + +### 3.3 Storage + +The best supported storage summary is: SAP HANA columnar/in-memory relational storage. This statement must be refined from code, format documentation, or provider counters before using it in a performance explanation. + +### 3.4 Execution + +The best supported execution summary is: graph workspace execution and GraphScript stored procedures. The benchmark profiler must confirm which runtime and operators actually executed. + +### 3.5 Transactions and recovery + +The public contract is: inherits HANA database transactions for source data. Exact acknowledgement, isolation anomalies, recovery bounds, and failover behavior remain separate qualification items. + +### 3.6 Distribution + +The deployment shape is: HANA scale-up/scale-out deployment depending edition. Replication is not capacity sharding; sharding is not distributed ACID; stateless readers are not stateless storage. + +### 3.7 Object storage and cost + +The 2026 posture is: not S3-native live serving. The audit distinguishes authoritative live bytes, derived acceleration, backup, import/export, and spill. + +## 4. Forty-control deep audit + +### 4.1 `product_boundary` + +Audit question: What exact executable, edition, and storage mode is the system under test? + +Current assessment: Pin SAP HANA Cloud Property Graph Engine, lifecycle `active QRC 1/2026`, and its edition/mode. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.2 `authority` + +Audit question: Which durable component is the source of truth after every acknowledged write? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.3 `identity` + +Audit question: Are node and edge identities stable across compaction, export, replication, and restore? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.4 `parallel_edges` + +Audit question: Can distinct parallel edges retain properties and trail identity end to end? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.5 `schema` + +Audit question: Is the schema open, closed, optional, inferred, or externally mapped? + +Current assessment: Start from `property graph workspace over HANA tables` and test actual constraints. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.6 `labels` + +Audit question: How are multiple labels represented and indexed? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.7 `adjacency_out` + +Audit question: How is outgoing adjacency located, encoded, split, cached, and updated? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.8 `adjacency_in` + +Audit question: Is incoming adjacency first-class, derived, replicated, or a fan-out operation? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.9 `supernodes` + +Audit question: How are million-to-billion-degree vertices represented and scheduled? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.10 `properties` + +Audit question: Are properties co-located, columnar, row-oriented, document-encoded, or remote? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.11 `compression` + +Audit question: Which topology, integer, string, null, and floating encodings are implemented? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.12 `checksums` + +Audit question: What integrity unit is verified on point reads and range reads? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.13 `snapshot` + +Audit question: What exact token pins graph data, schema, statistics, and indexes? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.14 `isolation` + +Audit question: Which anomalies are forbidden at the documented isolation level? + +Current assessment: Published summary: inherits HANA database transactions for source data. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.15 `durability` + +Audit question: What device/service acknowledgement is required before commit returns? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.16 `recovery` + +Audit question: What bounds restart work after a clean stop and a crash? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.17 `writer_fencing` + +Audit question: Can a stale writer acknowledge after failover or lease expiry? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.18 `partitioning` + +Audit question: What key determines placement and what happens to cross-partition edges? + +Current assessment: Published distribution summary: HANA scale-up/scale-out deployment depending edition. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.19 `rebalancing` + +Audit question: Can placement change online without changing logical identity? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.20 `replication` + +Audit question: Are replicas full, sharded, synchronous, asynchronous, or shared-storage readers? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.21 `optimizer` + +Audit question: Does the optimizer cost graph expansion, joins, network, cache, and remote requests? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.22 `statistics` + +Audit question: Which degree, correlation, path, and property statistics are persistent? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.23 `execution` + +Audit question: Is execution tuple-at-a-time, vectorized, factorized, compiled, matrix, or actor based? + +Current assessment: Expected family: graph workspace execution and GraphScript stored procedures. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.24 `recursion` + +Audit question: How are BFS, shortest paths, trails, simple paths, and arbitrary reachability executed? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.25 `parallelism` + +Audit question: How does the engine avoid skew and nested parallelism under mixed queries? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.26 `memory` + +Audit question: Are all variable allocations charged to bounded query and system budgets? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.27 `spill` + +Audit question: Which operators spill, in what format, and with what admission controls? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.28 `cancellation` + +Audit question: Can cancellation stop CPU, local I/O, remote I/O, retries, and prefetch? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.29 `cache` + +Audit question: What is cached, how is it keyed, admitted, pinned, and evicted? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.30 `cold_start` + +Audit question: What metadata and data round trips are required with empty caches? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.31 `object_requests` + +Audit question: Can a query issue one remote request per node, edge, or result row? + +Current assessment: Published object-store posture: not S3-native live serving. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.32 `cost_admission` + +Audit question: Are request, byte, CPU, spill, and result limits enforced before work? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.33 `observability` + +Audit question: Can operators report rows, edges, bytes, requests, stalls, memory, and spill? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.34 `language` + +Audit question: Which GQL/Cypher/SQL-PGQ/Gremlin/SPARQL semantics are declared and tested? + +Current assessment: Declared surface: openCypher subset, GraphScript, SQL. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.35 `updates` + +Audit question: Are DDL, insert, merge, update, detach delete, and constraints complete? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.36 `bulk_load` + +Audit question: Does bulk load preserve transactional and index invariants? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.37 `backup` + +Audit question: Is backup consistent, incremental, immutable, and restore-tested? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.38 `gc` + +Audit question: How are old snapshots, orphan objects, tombstones, and indexes reclaimed safely? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.39 `security` + +Audit question: Are authentication, authorization, encryption, audit, and tenant isolation in scope? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.40 `operations` + +Audit question: What compaction, upgrade, repair, verification, and capacity procedures exist? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +## 5. Benchmark contract for this engine + +Every case runs correctness first, then isolated latency, then closed-loop concurrency, then open-loop overload. Report median, p95, p99, p99.9, timeout/rejection rate, throughput, CPU-seconds, peak RSS, cache bytes, disk bytes, network bytes, remote requests, write amplification, and estimated monthly cost. + +Warm means all intended engine caches are populated without changing the query parameters. Hot means the exact working set is resident. Cold means process-local, engine, OS, NVMe, and remote cache state are explicitly reset or a fresh namespace is used. Those words are never inferred from repetition count. + +### 5.1 `point_pk` — primary-key node lookup with one projected property + +- Applicability to SAP HANA Cloud Property Graph Engine: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.2 `point_edge` — stable edge-ID lookup including endpoints and one property + +- Applicability to SAP HANA Cloud Property Graph Engine: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.3 `degree_1` — degree-one outgoing expansion + +- Applicability to SAP HANA Cloud Property Graph Engine: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.4 `degree_32` — small adjacency expansion around degree 32 + +- Applicability to SAP HANA Cloud Property Graph Engine: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.5 `degree_1k` — medium adjacency expansion around degree 1,024 + +- Applicability to SAP HANA Cloud Property Graph Engine: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.6 `supernode` — range-limited expansion of a ten-million-degree supernode + +- Applicability to SAP HANA Cloud Property Graph Engine: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.7 `expand_2` — selective two-hop expansion + +- Applicability to SAP HANA Cloud Property Graph Engine: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.8 `expand_3` — three-hop frontier expansion with duplicate control + +- Applicability to SAP HANA Cloud Property Graph Engine: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.9 `expand_into` — edge-existence/expand-into between already-bound endpoints + +- Applicability to SAP HANA Cloud Property Graph Engine: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.10 `multi_edge` — parallel-edge identity and property projection + +- Applicability to SAP HANA Cloud Property Graph Engine: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.11 `shortest` — bidirectional point-to-point unweighted shortest path + +- Applicability to SAP HANA Cloud Property Graph Engine: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.12 `weighted` — weighted shortest path with property access + +- Applicability to SAP HANA Cloud Property Graph Engine: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.13 `var_walk` — bounded variable-length walk + +- Applicability to SAP HANA Cloud Property Graph Engine: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.14 `trail` — DIFFERENT EDGES trail enumeration + +- Applicability to SAP HANA Cloud Property Graph Engine: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.15 `simple` — simple-path enumeration with explicit bound + +- Applicability to SAP HANA Cloud Property Graph Engine: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.16 `triangle` — triangle pattern with worst-case-sensitive join + +- Applicability to SAP HANA Cloud Property Graph Engine: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.17 `cycle4` — four-cycle pattern + +- Applicability to SAP HANA Cloud Property Graph Engine: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.18 `star_join` — high-fanout star pattern with property filters + +- Applicability to SAP HANA Cloud Property Graph Engine: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.19 `optional` — optional match preserving null/bag semantics + +- Applicability to SAP HANA Cloud Property Graph Engine: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.20 `aggregate` — grouped aggregate after traversal + +- Applicability to SAP HANA Cloud Property Graph Engine: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.21 `topk` — ordered top-k with late property materialization + +- Applicability to SAP HANA Cloud Property Graph Engine: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.22 `scan` — full projected property scan + +- Applicability to SAP HANA Cloud Property Graph Engine: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.23 `selective_scan` — zone/index-pruned selective property scan + +- Applicability to SAP HANA Cloud Property Graph Engine: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.24 `mixed` — concurrent short reads, complex reads, and updates + +- Applicability to SAP HANA Cloud Property Graph Engine: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.25 `ingest` — sustained transactional ingest with indexes enabled + +- Applicability to SAP HANA Cloud Property Graph Engine: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.26 `bulk` — initial bulk load including index/CSR build + +- Applicability to SAP HANA Cloud Property Graph Engine: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.27 `checkpoint` — checkpoint or compaction while readers remain active + +- Applicability to SAP HANA Cloud Property Graph Engine: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.28 `recovery` — crash recovery at bounded dirty-log size + +- Applicability to SAP HANA Cloud Property Graph Engine: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.29 `cold` — same query after clearing engine and OS/cache tiers + +- Applicability to SAP HANA Cloud Property Graph Engine: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.30 `remote` — same query with authoritative bytes only in object storage + +- Applicability to SAP HANA Cloud Property Graph Engine: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +## 6. Fairness controls + +- Same logical dataset and update stream; engine-native physical layouts are allowed and disclosed. +- Same result semantics; unsupported queries remain unsupported rather than rewritten into easier questions. +- Same durable acknowledgement class for write comparisons. +- Same number of physical cores and memory limit for self-hosted single-node tests. +- Same aggregate resources and replication fault tolerance for distributed tests. +- Officially recommended tuning may be applied before the freeze and is committed with rationale. +- Query-specific hints are allowed only when equivalent hints are offered to every engine and separately charted. +- Load/build/index time and bytes are first-class results. +- Cold, warm, and hot results are separate charts. +- Managed services use public configurations and cannot borrow hidden same-machine resource claims. +- Failed runs, OOMs, correctness mismatches, and timeouts stay in the dataset. +- Every chart links raw samples and the exact reproduction command. + +## 7. Likely advantages and limits + +The strongest known reason to choose this engine is tied to its family `in-memory relational-integrated graph engine`, its execution path `graph workspace execution and GraphScript stored procedures`, and its existing ecosystem. The strongest reason to reject it for zu's target is the gap between `not S3-native live serving` and an S3-authoritative, request-budgeted, PB-scale graph service. + +Capacity statement: enterprise analytical scale; no public PB graph evidence. This is not converted into an edge-count claim without a physical byte model including IDs, both adjacency directions, properties, indexes, MVCC, WAL, replicas, and free space. + +Commercial statement: commercial proprietary. License cost, support cost, and unavailable enterprise capabilities remain visible in TCO and feature tables. + +## 8. Concrete lessons for zu + +1. Keep stable logical node and edge identity independent of row group, CSR slot, shard, and object range. +2. Store forward and reverse adjacency as immutable range-addressable tiles carrying edge IDs. +3. Feed queries adjacency batches and typed vectors; prohibit one storage call per logical element. +4. Use vectorized/factorized execution for property-heavy patterns and dedicated frontier operators for recursion. +5. Cost topology, properties, network, cache certainty, remote requests, and result materialization together. +6. Separate the local embedded profile from the object-authoritative distributed read profile. +7. Fence writers with monotonic epochs and make ambiguous commits reconcilable by transaction ID. +8. Pack small graph tiles into large immutable objects while retaining independent checksums and range offsets. +9. Keep the hot topology working set in RAM/NVMe; batch cold frontier misses into few remote rounds. +10. Admission-control remote requests and bytes so fixed-price plans have an enforceable upper bound. +11. Partition by workload-aware graph locality, and expose cross-partition semantics rather than hiding them. +12. Publish qualified wins per workload cell; never promise a universal tenfold advantage. + +## 9. Evidence gaps to close before publication + +- Exact current version and release date. +- Exact license text for the benchmarked artifact. +- Storage bytes per node/edge/property on all standard datasets. +- Stable-edge-ID and parallel-edge semantics. +- Isolation litmus results and commit acknowledgement point. +- Crash recovery time versus dirty WAL size. +- Supernode behavior and maximum tested degree. +- Cold-start metadata and request count. +- Distributed cross-partition query amplification. +- Peak memory under skew, cancellation, and overload. +- Background compaction/GC effect on tail latency. +- Full load/index/checkpoint/backup resource cost. +- Reproducible largest-scale result. +- Independent or audited benchmark evidence. + +## 10. Primary and official sources + +- [QRC 1/2026 engine reference](https://help.sap.com/docs/hana-cloud-database/sap-hana-cloud-sap-hana-database-property-graph-engine-reference/introduction) +- [LDBC SNB Interactive and audited disclosures](https://ldbcouncil.org/benchmarks/snb/interactive/) +- [LDBC Graphalytics](https://ldbcouncil.org/benchmarks/graphalytics/) +- [SoK: The Faults in our Graph Benchmarks](https://arxiv.org/abs/2404.00766) + +## 11. Source-handling rules + +- Official documentation and source are evidence for implemented or declared behavior, not independent performance. +- A vendor benchmark is labeled vendor claim until the harness reproduces it. +- A peer-reviewed paper establishes only the version, configuration, and workload it evaluated. +- Search snippets, comparison sites, and unsourced blogs are discovery aids, not final evidence. +- Unknown is a valid result and creates a concrete experiment or source-inspection task. +- All web facts are rechecked at benchmark freeze because this corpus is current only through the research date. + +## 12. Reproduction record template + +- engine: `SAP HANA Cloud Property Graph Engine` +- version: `TBD at benchmark freeze` +- artifact digest: `TBD` +- source commit: `TBD or managed-service N/A` +- edition/license: `TBD` +- query language/version: `TBD` +- storage and durability mode: `TBD` +- cluster and replication: `TBD` +- CPU/RAM/NVMe/network: `TBD` +- OS/kernel/filesystem: `TBD` +- dataset URI and digest: `TBD` +- loader command and duration: `TBD` +- physical bytes by category: `TBD` +- tuning file: `TBD` +- query corpus commit: `TBD` +- raw result URI/digest: `TBD` +- profiler/trace URI: `TBD` +- correctness status: `TBD` +- reviewer and rerun date: `TBD` diff --git a/docs/research/engine-stardog.md b/docs/research/engine-stardog.md new file mode 100644 index 0000000..67fdb1b --- /dev/null +++ b/docs/research/engine-stardog.md @@ -0,0 +1,885 @@ +# Stardog: 2026 deep technical and competitive specification + +Research cut: `2026-08-08` +Status: evidence-backed competitor audit; not a vendor endorsement +Family: `enterprise RDF knowledge graph platform` +Evidence convention: **Observed/official**, **Vendor claim**, **Research inference**, **Unknown**, **Qualification target**. + +## 1. Decision summary + +Stardog is the enterprise semantic/federation baseline rather than a direct LPG traversal peer. + +This document answers two questions: what this engine actually proves in 2026, and what zu must build or measure to earn a defensible advantage. A missing public detail remains unknown; it is never silently filled with a favorable assumption. + +### Snapshot card + +- Lifecycle: active 12.x-era platform. +- Data model: RDF knowledge graph with virtual graphs and reasoning. +- Query surface: SPARQL 1.1, paths, rules, APIs. +- Persistent layout: proprietary native RDF storage plus virtualized external sources. +- Execution: cost-based SPARQL, path queries, reasoning, virtualization. +- Transactions: ACID database transactions; cluster uses coordinated commit. +- Distribution: HA cluster and federated/virtual query capabilities. +- Object-storage posture: not S3-native adjacency serving; cloud deployment and backups may use object storage. +- License/commercial boundary: commercial proprietary. +- Scale evidence: enterprise knowledge graphs; PB interactive claim not public. +- Benchmark posture: benchmark SPARQL, reasoning, virtualization, and materialized data separately. + +### Facts that materially affect comparison + +- F01 — SPARQL 1.1 queries can enable OWL/rule reasoning. +- F02 — SERVICE supports federated SPARQL endpoints. +- F03 — Virtual graphs avoid copying some relational data but inherit source latency. +- F04 — Stardog Cluster records committed transaction identity in ZooKeeper. +- F05 — Version 12 improved two-phase-commit lock behavior for large transactions. + +### Bottom-line fit against zu's target + +- Very-low latency: compare hot point and bounded traversal paths; never extrapolate from scans or algorithms. +- Very-low resources: charge resident set, page cache, remote cache, background services, and replicas. +- Distributed: distinguish read replication, partitioned capacity, distributed transactions, and elastic stateless compute. +- Fixed cost: no engine has fixed marginal cost by declaration; admission, batching, and capacity reservations create the bound. +- S3 authority: backups, imports, lake scans, and S3-native demand paging are four different architectures. +- PB / trillion-edge scale: require a capacity derivation plus a run at the largest affordable scale; marketing adjectives do not qualify. +- Tenfold win: can be a per-cell qualification result, never a universal statement across incomparable workloads. + +## 2. Product and ecosystem boundary + +The audited unit is **Stardog** in the exact release, edition, deployment, and durability mode recorded by the harness. The family classification is **enterprise RDF knowledge graph platform**. The current lifecycle statement is: active 12.x-era platform. + +The harness must record binary/container digest, source commit when available, build flags, plugins, license/edition, language mode, storage mode, cluster topology, replication factor, durability settings, cache sizes, thread counts, NUMA policy, kernel, filesystem, cloud region, and all environment variables that affect execution. + +A managed service is not placed in a same-hardware chart. It receives a service-level result with provisioned units, region, public price, and observed provider metrics. A historical engine remains useful for regression but cannot support a claim about beating all current competitors. + +## 3. Architecture reconstruction + +### 3.1 Logical model + +Stardog exposes RDF knowledge graph with virtual graphs and reasoning. The conformance corpus must test nulls, missing properties, labels/types, direction, self-loops, parallel edges, element equality, path equality, bag semantics, ordering, numeric overflow, string collation, temporal values, and schema evolution. + +### 3.2 Language and compiler + +The public query surface is SPARQL 1.1, paths, rules, APIs. Syntax similarity is not semantic equivalence. Every supported construct needs a result oracle and an unsupported-feature declaration. + +### 3.3 Storage + +The best supported storage summary is: proprietary native RDF storage plus virtualized external sources. This statement must be refined from code, format documentation, or provider counters before using it in a performance explanation. + +### 3.4 Execution + +The best supported execution summary is: cost-based SPARQL, path queries, reasoning, virtualization. The benchmark profiler must confirm which runtime and operators actually executed. + +### 3.5 Transactions and recovery + +The public contract is: ACID database transactions; cluster uses coordinated commit. Exact acknowledgement, isolation anomalies, recovery bounds, and failover behavior remain separate qualification items. + +### 3.6 Distribution + +The deployment shape is: HA cluster and federated/virtual query capabilities. Replication is not capacity sharding; sharding is not distributed ACID; stateless readers are not stateless storage. + +### 3.7 Object storage and cost + +The 2026 posture is: not S3-native adjacency serving; cloud deployment and backups may use object storage. The audit distinguishes authoritative live bytes, derived acceleration, backup, import/export, and spill. + +## 4. Forty-control deep audit + +### 4.1 `product_boundary` + +Audit question: What exact executable, edition, and storage mode is the system under test? + +Current assessment: Pin Stardog, lifecycle `active 12.x-era platform`, and its edition/mode. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.2 `authority` + +Audit question: Which durable component is the source of truth after every acknowledged write? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.3 `identity` + +Audit question: Are node and edge identities stable across compaction, export, replication, and restore? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.4 `parallel_edges` + +Audit question: Can distinct parallel edges retain properties and trail identity end to end? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.5 `schema` + +Audit question: Is the schema open, closed, optional, inferred, or externally mapped? + +Current assessment: Start from `RDF knowledge graph with virtual graphs and reasoning` and test actual constraints. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.6 `labels` + +Audit question: How are multiple labels represented and indexed? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.7 `adjacency_out` + +Audit question: How is outgoing adjacency located, encoded, split, cached, and updated? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.8 `adjacency_in` + +Audit question: Is incoming adjacency first-class, derived, replicated, or a fan-out operation? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.9 `supernodes` + +Audit question: How are million-to-billion-degree vertices represented and scheduled? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.10 `properties` + +Audit question: Are properties co-located, columnar, row-oriented, document-encoded, or remote? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.11 `compression` + +Audit question: Which topology, integer, string, null, and floating encodings are implemented? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.12 `checksums` + +Audit question: What integrity unit is verified on point reads and range reads? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.13 `snapshot` + +Audit question: What exact token pins graph data, schema, statistics, and indexes? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.14 `isolation` + +Audit question: Which anomalies are forbidden at the documented isolation level? + +Current assessment: Published summary: ACID database transactions; cluster uses coordinated commit. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.15 `durability` + +Audit question: What device/service acknowledgement is required before commit returns? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.16 `recovery` + +Audit question: What bounds restart work after a clean stop and a crash? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.17 `writer_fencing` + +Audit question: Can a stale writer acknowledge after failover or lease expiry? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.18 `partitioning` + +Audit question: What key determines placement and what happens to cross-partition edges? + +Current assessment: Published distribution summary: HA cluster and federated/virtual query capabilities. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.19 `rebalancing` + +Audit question: Can placement change online without changing logical identity? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.20 `replication` + +Audit question: Are replicas full, sharded, synchronous, asynchronous, or shared-storage readers? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.21 `optimizer` + +Audit question: Does the optimizer cost graph expansion, joins, network, cache, and remote requests? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.22 `statistics` + +Audit question: Which degree, correlation, path, and property statistics are persistent? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.23 `execution` + +Audit question: Is execution tuple-at-a-time, vectorized, factorized, compiled, matrix, or actor based? + +Current assessment: Expected family: cost-based SPARQL, path queries, reasoning, virtualization. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.24 `recursion` + +Audit question: How are BFS, shortest paths, trails, simple paths, and arbitrary reachability executed? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.25 `parallelism` + +Audit question: How does the engine avoid skew and nested parallelism under mixed queries? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.26 `memory` + +Audit question: Are all variable allocations charged to bounded query and system budgets? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.27 `spill` + +Audit question: Which operators spill, in what format, and with what admission controls? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.28 `cancellation` + +Audit question: Can cancellation stop CPU, local I/O, remote I/O, retries, and prefetch? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.29 `cache` + +Audit question: What is cached, how is it keyed, admitted, pinned, and evicted? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.30 `cold_start` + +Audit question: What metadata and data round trips are required with empty caches? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.31 `object_requests` + +Audit question: Can a query issue one remote request per node, edge, or result row? + +Current assessment: Published object-store posture: not S3-native adjacency serving; cloud deployment and backups may use object storage. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.32 `cost_admission` + +Audit question: Are request, byte, CPU, spill, and result limits enforced before work? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.33 `observability` + +Audit question: Can operators report rows, edges, bytes, requests, stalls, memory, and spill? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.34 `language` + +Audit question: Which GQL/Cypher/SQL-PGQ/Gremlin/SPARQL semantics are declared and tested? + +Current assessment: Declared surface: SPARQL 1.1, paths, rules, APIs. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.35 `updates` + +Audit question: Are DDL, insert, merge, update, detach delete, and constraints complete? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.36 `bulk_load` + +Audit question: Does bulk load preserve transactional and index invariants? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.37 `backup` + +Audit question: Is backup consistent, incremental, immutable, and restore-tested? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.38 `gc` + +Audit question: How are old snapshots, orphan objects, tombstones, and indexes reclaimed safely? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.39 `security` + +Audit question: Are authentication, authorization, encryption, audit, and tenant isolation in scope? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.40 `operations` + +Audit question: What compaction, upgrade, repair, verification, and capacity procedures exist? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +## 5. Benchmark contract for this engine + +Every case runs correctness first, then isolated latency, then closed-loop concurrency, then open-loop overload. Report median, p95, p99, p99.9, timeout/rejection rate, throughput, CPU-seconds, peak RSS, cache bytes, disk bytes, network bytes, remote requests, write amplification, and estimated monthly cost. + +Warm means all intended engine caches are populated without changing the query parameters. Hot means the exact working set is resident. Cold means process-local, engine, OS, NVMe, and remote cache state are explicitly reset or a fresh namespace is used. Those words are never inferred from repetition count. + +### 5.1 `point_pk` — primary-key node lookup with one projected property + +- Applicability to Stardog: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.2 `point_edge` — stable edge-ID lookup including endpoints and one property + +- Applicability to Stardog: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.3 `degree_1` — degree-one outgoing expansion + +- Applicability to Stardog: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.4 `degree_32` — small adjacency expansion around degree 32 + +- Applicability to Stardog: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.5 `degree_1k` — medium adjacency expansion around degree 1,024 + +- Applicability to Stardog: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.6 `supernode` — range-limited expansion of a ten-million-degree supernode + +- Applicability to Stardog: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.7 `expand_2` — selective two-hop expansion + +- Applicability to Stardog: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.8 `expand_3` — three-hop frontier expansion with duplicate control + +- Applicability to Stardog: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.9 `expand_into` — edge-existence/expand-into between already-bound endpoints + +- Applicability to Stardog: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.10 `multi_edge` — parallel-edge identity and property projection + +- Applicability to Stardog: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.11 `shortest` — bidirectional point-to-point unweighted shortest path + +- Applicability to Stardog: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.12 `weighted` — weighted shortest path with property access + +- Applicability to Stardog: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.13 `var_walk` — bounded variable-length walk + +- Applicability to Stardog: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.14 `trail` — DIFFERENT EDGES trail enumeration + +- Applicability to Stardog: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.15 `simple` — simple-path enumeration with explicit bound + +- Applicability to Stardog: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.16 `triangle` — triangle pattern with worst-case-sensitive join + +- Applicability to Stardog: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.17 `cycle4` — four-cycle pattern + +- Applicability to Stardog: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.18 `star_join` — high-fanout star pattern with property filters + +- Applicability to Stardog: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.19 `optional` — optional match preserving null/bag semantics + +- Applicability to Stardog: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.20 `aggregate` — grouped aggregate after traversal + +- Applicability to Stardog: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.21 `topk` — ordered top-k with late property materialization + +- Applicability to Stardog: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.22 `scan` — full projected property scan + +- Applicability to Stardog: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.23 `selective_scan` — zone/index-pruned selective property scan + +- Applicability to Stardog: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.24 `mixed` — concurrent short reads, complex reads, and updates + +- Applicability to Stardog: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.25 `ingest` — sustained transactional ingest with indexes enabled + +- Applicability to Stardog: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.26 `bulk` — initial bulk load including index/CSR build + +- Applicability to Stardog: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.27 `checkpoint` — checkpoint or compaction while readers remain active + +- Applicability to Stardog: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.28 `recovery` — crash recovery at bounded dirty-log size + +- Applicability to Stardog: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.29 `cold` — same query after clearing engine and OS/cache tiers + +- Applicability to Stardog: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.30 `remote` — same query with authoritative bytes only in object storage + +- Applicability to Stardog: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +## 6. Fairness controls + +- Same logical dataset and update stream; engine-native physical layouts are allowed and disclosed. +- Same result semantics; unsupported queries remain unsupported rather than rewritten into easier questions. +- Same durable acknowledgement class for write comparisons. +- Same number of physical cores and memory limit for self-hosted single-node tests. +- Same aggregate resources and replication fault tolerance for distributed tests. +- Officially recommended tuning may be applied before the freeze and is committed with rationale. +- Query-specific hints are allowed only when equivalent hints are offered to every engine and separately charted. +- Load/build/index time and bytes are first-class results. +- Cold, warm, and hot results are separate charts. +- Managed services use public configurations and cannot borrow hidden same-machine resource claims. +- Failed runs, OOMs, correctness mismatches, and timeouts stay in the dataset. +- Every chart links raw samples and the exact reproduction command. + +## 7. Likely advantages and limits + +The strongest known reason to choose this engine is tied to its family `enterprise RDF knowledge graph platform`, its execution path `cost-based SPARQL, path queries, reasoning, virtualization`, and its existing ecosystem. The strongest reason to reject it for zu's target is the gap between `not S3-native adjacency serving; cloud deployment and backups may use object storage` and an S3-authoritative, request-budgeted, PB-scale graph service. + +Capacity statement: enterprise knowledge graphs; PB interactive claim not public. This is not converted into an edge-count claim without a physical byte model including IDs, both adjacency directions, properties, indexes, MVCC, WAL, replicas, and free space. + +Commercial statement: commercial proprietary. License cost, support cost, and unavailable enterprise capabilities remain visible in TCO and feature tables. + +## 8. Concrete lessons for zu + +1. Keep stable logical node and edge identity independent of row group, CSR slot, shard, and object range. +2. Store forward and reverse adjacency as immutable range-addressable tiles carrying edge IDs. +3. Feed queries adjacency batches and typed vectors; prohibit one storage call per logical element. +4. Use vectorized/factorized execution for property-heavy patterns and dedicated frontier operators for recursion. +5. Cost topology, properties, network, cache certainty, remote requests, and result materialization together. +6. Separate the local embedded profile from the object-authoritative distributed read profile. +7. Fence writers with monotonic epochs and make ambiguous commits reconcilable by transaction ID. +8. Pack small graph tiles into large immutable objects while retaining independent checksums and range offsets. +9. Keep the hot topology working set in RAM/NVMe; batch cold frontier misses into few remote rounds. +10. Admission-control remote requests and bytes so fixed-price plans have an enforceable upper bound. +11. Partition by workload-aware graph locality, and expose cross-partition semantics rather than hiding them. +12. Publish qualified wins per workload cell; never promise a universal tenfold advantage. + +## 9. Evidence gaps to close before publication + +- Exact current version and release date. +- Exact license text for the benchmarked artifact. +- Storage bytes per node/edge/property on all standard datasets. +- Stable-edge-ID and parallel-edge semantics. +- Isolation litmus results and commit acknowledgement point. +- Crash recovery time versus dirty WAL size. +- Supernode behavior and maximum tested degree. +- Cold-start metadata and request count. +- Distributed cross-partition query amplification. +- Peak memory under skew, cancellation, and overload. +- Background compaction/GC effect on tail latency. +- Full load/index/checkpoint/backup resource cost. +- Reproducible largest-scale result. +- Independent or audited benchmark evidence. + +## 10. Primary and official sources + +- [Current docs](https://docs.stardog.com/) +- [Query engine](https://docs.stardog.com/query-stardog/) +- [Cluster operations](https://docs.stardog.com/high-availability-cluster/operating-the-cluster/) +- [LDBC SNB Interactive and audited disclosures](https://ldbcouncil.org/benchmarks/snb/interactive/) +- [LDBC Graphalytics](https://ldbcouncil.org/benchmarks/graphalytics/) +- [SoK: The Faults in our Graph Benchmarks](https://arxiv.org/abs/2404.00766) + +## 11. Source-handling rules + +- Official documentation and source are evidence for implemented or declared behavior, not independent performance. +- A vendor benchmark is labeled vendor claim until the harness reproduces it. +- A peer-reviewed paper establishes only the version, configuration, and workload it evaluated. +- Search snippets, comparison sites, and unsourced blogs are discovery aids, not final evidence. +- Unknown is a valid result and creates a concrete experiment or source-inspection task. +- All web facts are rechecked at benchmark freeze because this corpus is current only through the research date. + +## 12. Reproduction record template + +- engine: `Stardog` +- version: `TBD at benchmark freeze` +- artifact digest: `TBD` +- source commit: `TBD or managed-service N/A` +- edition/license: `TBD` +- query language/version: `TBD` +- storage and durability mode: `TBD` +- cluster and replication: `TBD` +- CPU/RAM/NVMe/network: `TBD` +- OS/kernel/filesystem: `TBD` +- dataset URI and digest: `TBD` +- loader command and duration: `TBD` +- physical bytes by category: `TBD` +- tuning file: `TBD` +- query corpus commit: `TBD` +- raw result URI/digest: `TBD` +- profiler/trace URI: `TBD` +- correctness status: `TBD` +- reviewer and rerun date: `TBD` diff --git a/docs/research/engine-surrealdb.md b/docs/research/engine-surrealdb.md new file mode 100644 index 0000000..427575f --- /dev/null +++ b/docs/research/engine-surrealdb.md @@ -0,0 +1,886 @@ +# SurrealDB: 2026 deep technical and competitive specification + +Research cut: `2026-08-08` +Status: evidence-backed competitor audit; not a vendor endorsement +Family: `distributed multi-model database` +Evidence convention: **Observed/official**, **Vendor claim**, **Research inference**, **Unknown**, **Qualification target**. + +## 1. Decision summary + +SurrealDB is a high-priority Rust/multi-model competitor and a useful check on zu's storage-query boundary. + +This document answers two questions: what this engine actually proves in 2026, and what zu must build or measure to earn a defensible advantage. A missing public detail remains unknown; it is never silently filled with a favorable assumption. + +### Snapshot card + +- Lifecycle: active 3.x. +- Data model: document core with graph, relational, vector, time-series, and geospatial models. +- Query surface: SurrealQL and GraphQL. +- Persistent layout: RocksDB single node, SurrealKV beta, SurrealMX memory, IndexedDB browser, SurrealDS distributed. +- Execution: Rust parser/executor/iterator/document pipeline over transactional KV ranges. +- Transactions: snapshot isolation with write-write conflict detection across supported backends. +- Distribution: compute/storage separation; SurrealDS for multi-node Enterprise/Cloud. +- Object-storage posture: 2026 materials describe object-storage-based distributed storage, but public internals and cost evidence are incomplete. +- License/commercial boundary: Business Source/other mixed licensing by component and edition; pin exact artifacts. +- Scale evidence: distributed promises are significant; independent PB graph evidence absent. +- Benchmark posture: test native RELATE traversal separately from generic document links and cloud-only SurrealDS. + +### Facts that materially affect comparison + +- F01 — The query layer exposes the same semantics over several storage engines. +- F02 — Graph edges are documents with their own properties. +- F03 — The architecture explicitly separates parser, executor, iterator, document processing, and storage API. +- F04 — SurrealDS is the distributed path; RocksDB is recommended for current single-node production. +- F05 — Object-storage claims need request, cache, consistency, and cold-latency disclosure. + +### Bottom-line fit against zu's target + +- Very-low latency: compare hot point and bounded traversal paths; never extrapolate from scans or algorithms. +- Very-low resources: charge resident set, page cache, remote cache, background services, and replicas. +- Distributed: distinguish read replication, partitioned capacity, distributed transactions, and elastic stateless compute. +- Fixed cost: no engine has fixed marginal cost by declaration; admission, batching, and capacity reservations create the bound. +- S3 authority: backups, imports, lake scans, and S3-native demand paging are four different architectures. +- PB / trillion-edge scale: require a capacity derivation plus a run at the largest affordable scale; marketing adjectives do not qualify. +- Tenfold win: can be a per-cell qualification result, never a universal statement across incomparable workloads. + +## 2. Product and ecosystem boundary + +The audited unit is **SurrealDB** in the exact release, edition, deployment, and durability mode recorded by the harness. The family classification is **distributed multi-model database**. The current lifecycle statement is: active 3.x. + +The harness must record binary/container digest, source commit when available, build flags, plugins, license/edition, language mode, storage mode, cluster topology, replication factor, durability settings, cache sizes, thread counts, NUMA policy, kernel, filesystem, cloud region, and all environment variables that affect execution. + +A managed service is not placed in a same-hardware chart. It receives a service-level result with provisioned units, region, public price, and observed provider metrics. A historical engine remains useful for regression but cannot support a claim about beating all current competitors. + +## 3. Architecture reconstruction + +### 3.1 Logical model + +SurrealDB exposes document core with graph, relational, vector, time-series, and geospatial models. The conformance corpus must test nulls, missing properties, labels/types, direction, self-loops, parallel edges, element equality, path equality, bag semantics, ordering, numeric overflow, string collation, temporal values, and schema evolution. + +### 3.2 Language and compiler + +The public query surface is SurrealQL and GraphQL. Syntax similarity is not semantic equivalence. Every supported construct needs a result oracle and an unsupported-feature declaration. + +### 3.3 Storage + +The best supported storage summary is: RocksDB single node, SurrealKV beta, SurrealMX memory, IndexedDB browser, SurrealDS distributed. This statement must be refined from code, format documentation, or provider counters before using it in a performance explanation. + +### 3.4 Execution + +The best supported execution summary is: Rust parser/executor/iterator/document pipeline over transactional KV ranges. The benchmark profiler must confirm which runtime and operators actually executed. + +### 3.5 Transactions and recovery + +The public contract is: snapshot isolation with write-write conflict detection across supported backends. Exact acknowledgement, isolation anomalies, recovery bounds, and failover behavior remain separate qualification items. + +### 3.6 Distribution + +The deployment shape is: compute/storage separation; SurrealDS for multi-node Enterprise/Cloud. Replication is not capacity sharding; sharding is not distributed ACID; stateless readers are not stateless storage. + +### 3.7 Object storage and cost + +The 2026 posture is: 2026 materials describe object-storage-based distributed storage, but public internals and cost evidence are incomplete. The audit distinguishes authoritative live bytes, derived acceleration, backup, import/export, and spill. + +## 4. Forty-control deep audit + +### 4.1 `product_boundary` + +Audit question: What exact executable, edition, and storage mode is the system under test? + +Current assessment: Pin SurrealDB, lifecycle `active 3.x`, and its edition/mode. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.2 `authority` + +Audit question: Which durable component is the source of truth after every acknowledged write? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.3 `identity` + +Audit question: Are node and edge identities stable across compaction, export, replication, and restore? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.4 `parallel_edges` + +Audit question: Can distinct parallel edges retain properties and trail identity end to end? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.5 `schema` + +Audit question: Is the schema open, closed, optional, inferred, or externally mapped? + +Current assessment: Start from `document core with graph, relational, vector, time-series, and geospatial models` and test actual constraints. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.6 `labels` + +Audit question: How are multiple labels represented and indexed? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.7 `adjacency_out` + +Audit question: How is outgoing adjacency located, encoded, split, cached, and updated? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.8 `adjacency_in` + +Audit question: Is incoming adjacency first-class, derived, replicated, or a fan-out operation? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.9 `supernodes` + +Audit question: How are million-to-billion-degree vertices represented and scheduled? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.10 `properties` + +Audit question: Are properties co-located, columnar, row-oriented, document-encoded, or remote? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.11 `compression` + +Audit question: Which topology, integer, string, null, and floating encodings are implemented? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.12 `checksums` + +Audit question: What integrity unit is verified on point reads and range reads? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.13 `snapshot` + +Audit question: What exact token pins graph data, schema, statistics, and indexes? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.14 `isolation` + +Audit question: Which anomalies are forbidden at the documented isolation level? + +Current assessment: Published summary: snapshot isolation with write-write conflict detection across supported backends. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.15 `durability` + +Audit question: What device/service acknowledgement is required before commit returns? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.16 `recovery` + +Audit question: What bounds restart work after a clean stop and a crash? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.17 `writer_fencing` + +Audit question: Can a stale writer acknowledge after failover or lease expiry? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.18 `partitioning` + +Audit question: What key determines placement and what happens to cross-partition edges? + +Current assessment: Published distribution summary: compute/storage separation; SurrealDS for multi-node Enterprise/Cloud. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.19 `rebalancing` + +Audit question: Can placement change online without changing logical identity? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.20 `replication` + +Audit question: Are replicas full, sharded, synchronous, asynchronous, or shared-storage readers? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.21 `optimizer` + +Audit question: Does the optimizer cost graph expansion, joins, network, cache, and remote requests? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.22 `statistics` + +Audit question: Which degree, correlation, path, and property statistics are persistent? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.23 `execution` + +Audit question: Is execution tuple-at-a-time, vectorized, factorized, compiled, matrix, or actor based? + +Current assessment: Expected family: Rust parser/executor/iterator/document pipeline over transactional KV ranges. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.24 `recursion` + +Audit question: How are BFS, shortest paths, trails, simple paths, and arbitrary reachability executed? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.25 `parallelism` + +Audit question: How does the engine avoid skew and nested parallelism under mixed queries? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.26 `memory` + +Audit question: Are all variable allocations charged to bounded query and system budgets? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.27 `spill` + +Audit question: Which operators spill, in what format, and with what admission controls? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.28 `cancellation` + +Audit question: Can cancellation stop CPU, local I/O, remote I/O, retries, and prefetch? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.29 `cache` + +Audit question: What is cached, how is it keyed, admitted, pinned, and evicted? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.30 `cold_start` + +Audit question: What metadata and data round trips are required with empty caches? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.31 `object_requests` + +Audit question: Can a query issue one remote request per node, edge, or result row? + +Current assessment: Published object-store posture: 2026 materials describe object-storage-based distributed storage, but public internals and cost evidence are incomplete. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.32 `cost_admission` + +Audit question: Are request, byte, CPU, spill, and result limits enforced before work? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.33 `observability` + +Audit question: Can operators report rows, edges, bytes, requests, stalls, memory, and spill? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.34 `language` + +Audit question: Which GQL/Cypher/SQL-PGQ/Gremlin/SPARQL semantics are declared and tested? + +Current assessment: Declared surface: SurrealQL and GraphQL. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.35 `updates` + +Audit question: Are DDL, insert, merge, update, detach delete, and constraints complete? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.36 `bulk_load` + +Audit question: Does bulk load preserve transactional and index invariants? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.37 `backup` + +Audit question: Is backup consistent, incremental, immutable, and restore-tested? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.38 `gc` + +Audit question: How are old snapshots, orphan objects, tombstones, and indexes reclaimed safely? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.39 `security` + +Audit question: Are authentication, authorization, encryption, audit, and tenant isolation in scope? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.40 `operations` + +Audit question: What compaction, upgrade, repair, verification, and capacity procedures exist? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +## 5. Benchmark contract for this engine + +Every case runs correctness first, then isolated latency, then closed-loop concurrency, then open-loop overload. Report median, p95, p99, p99.9, timeout/rejection rate, throughput, CPU-seconds, peak RSS, cache bytes, disk bytes, network bytes, remote requests, write amplification, and estimated monthly cost. + +Warm means all intended engine caches are populated without changing the query parameters. Hot means the exact working set is resident. Cold means process-local, engine, OS, NVMe, and remote cache state are explicitly reset or a fresh namespace is used. Those words are never inferred from repetition count. + +### 5.1 `point_pk` — primary-key node lookup with one projected property + +- Applicability to SurrealDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.2 `point_edge` — stable edge-ID lookup including endpoints and one property + +- Applicability to SurrealDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.3 `degree_1` — degree-one outgoing expansion + +- Applicability to SurrealDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.4 `degree_32` — small adjacency expansion around degree 32 + +- Applicability to SurrealDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.5 `degree_1k` — medium adjacency expansion around degree 1,024 + +- Applicability to SurrealDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.6 `supernode` — range-limited expansion of a ten-million-degree supernode + +- Applicability to SurrealDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.7 `expand_2` — selective two-hop expansion + +- Applicability to SurrealDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.8 `expand_3` — three-hop frontier expansion with duplicate control + +- Applicability to SurrealDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.9 `expand_into` — edge-existence/expand-into between already-bound endpoints + +- Applicability to SurrealDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.10 `multi_edge` — parallel-edge identity and property projection + +- Applicability to SurrealDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.11 `shortest` — bidirectional point-to-point unweighted shortest path + +- Applicability to SurrealDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.12 `weighted` — weighted shortest path with property access + +- Applicability to SurrealDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.13 `var_walk` — bounded variable-length walk + +- Applicability to SurrealDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.14 `trail` — DIFFERENT EDGES trail enumeration + +- Applicability to SurrealDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.15 `simple` — simple-path enumeration with explicit bound + +- Applicability to SurrealDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.16 `triangle` — triangle pattern with worst-case-sensitive join + +- Applicability to SurrealDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.17 `cycle4` — four-cycle pattern + +- Applicability to SurrealDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.18 `star_join` — high-fanout star pattern with property filters + +- Applicability to SurrealDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.19 `optional` — optional match preserving null/bag semantics + +- Applicability to SurrealDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.20 `aggregate` — grouped aggregate after traversal + +- Applicability to SurrealDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.21 `topk` — ordered top-k with late property materialization + +- Applicability to SurrealDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.22 `scan` — full projected property scan + +- Applicability to SurrealDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.23 `selective_scan` — zone/index-pruned selective property scan + +- Applicability to SurrealDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.24 `mixed` — concurrent short reads, complex reads, and updates + +- Applicability to SurrealDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.25 `ingest` — sustained transactional ingest with indexes enabled + +- Applicability to SurrealDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.26 `bulk` — initial bulk load including index/CSR build + +- Applicability to SurrealDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.27 `checkpoint` — checkpoint or compaction while readers remain active + +- Applicability to SurrealDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.28 `recovery` — crash recovery at bounded dirty-log size + +- Applicability to SurrealDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.29 `cold` — same query after clearing engine and OS/cache tiers + +- Applicability to SurrealDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.30 `remote` — same query with authoritative bytes only in object storage + +- Applicability to SurrealDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +## 6. Fairness controls + +- Same logical dataset and update stream; engine-native physical layouts are allowed and disclosed. +- Same result semantics; unsupported queries remain unsupported rather than rewritten into easier questions. +- Same durable acknowledgement class for write comparisons. +- Same number of physical cores and memory limit for self-hosted single-node tests. +- Same aggregate resources and replication fault tolerance for distributed tests. +- Officially recommended tuning may be applied before the freeze and is committed with rationale. +- Query-specific hints are allowed only when equivalent hints are offered to every engine and separately charted. +- Load/build/index time and bytes are first-class results. +- Cold, warm, and hot results are separate charts. +- Managed services use public configurations and cannot borrow hidden same-machine resource claims. +- Failed runs, OOMs, correctness mismatches, and timeouts stay in the dataset. +- Every chart links raw samples and the exact reproduction command. + +## 7. Likely advantages and limits + +The strongest known reason to choose this engine is tied to its family `distributed multi-model database`, its execution path `Rust parser/executor/iterator/document pipeline over transactional KV ranges`, and its existing ecosystem. The strongest reason to reject it for zu's target is the gap between `2026 materials describe object-storage-based distributed storage, but public internals and cost evidence are incomplete` and an S3-authoritative, request-budgeted, PB-scale graph service. + +Capacity statement: distributed promises are significant; independent PB graph evidence absent. This is not converted into an edge-count claim without a physical byte model including IDs, both adjacency directions, properties, indexes, MVCC, WAL, replicas, and free space. + +Commercial statement: Business Source/other mixed licensing by component and edition; pin exact artifacts. License cost, support cost, and unavailable enterprise capabilities remain visible in TCO and feature tables. + +## 8. Concrete lessons for zu + +1. Keep stable logical node and edge identity independent of row group, CSR slot, shard, and object range. +2. Store forward and reverse adjacency as immutable range-addressable tiles carrying edge IDs. +3. Feed queries adjacency batches and typed vectors; prohibit one storage call per logical element. +4. Use vectorized/factorized execution for property-heavy patterns and dedicated frontier operators for recursion. +5. Cost topology, properties, network, cache certainty, remote requests, and result materialization together. +6. Separate the local embedded profile from the object-authoritative distributed read profile. +7. Fence writers with monotonic epochs and make ambiguous commits reconcilable by transaction ID. +8. Pack small graph tiles into large immutable objects while retaining independent checksums and range offsets. +9. Keep the hot topology working set in RAM/NVMe; batch cold frontier misses into few remote rounds. +10. Admission-control remote requests and bytes so fixed-price plans have an enforceable upper bound. +11. Partition by workload-aware graph locality, and expose cross-partition semantics rather than hiding them. +12. Publish qualified wins per workload cell; never promise a universal tenfold advantage. + +## 9. Evidence gaps to close before publication + +- Exact current version and release date. +- Exact license text for the benchmarked artifact. +- Storage bytes per node/edge/property on all standard datasets. +- Stable-edge-ID and parallel-edge semantics. +- Isolation litmus results and commit acknowledgement point. +- Crash recovery time versus dirty WAL size. +- Supernode behavior and maximum tested degree. +- Cold-start metadata and request count. +- Distributed cross-partition query amplification. +- Peak memory under skew, cancellation, and overload. +- Background compaction/GC effect on tail latency. +- Full load/index/checkpoint/backup resource cost. +- Reproducible largest-scale result. +- Independent or audited benchmark evidence. + +## 10. Primary and official sources + +- [Architecture](https://surrealdb.com/docs/architecture) +- [Graph model](https://surrealdb.com/docs/learn/data-models/graph/overview) +- [Source repository](https://github.com/surrealdb/surrealdb) +- [2026 whitepaper](https://surrealdb.com/static/surrealdb-context-layer-whitepaper.pdf) +- [LDBC SNB Interactive and audited disclosures](https://ldbcouncil.org/benchmarks/snb/interactive/) +- [LDBC Graphalytics](https://ldbcouncil.org/benchmarks/graphalytics/) +- [SoK: The Faults in our Graph Benchmarks](https://arxiv.org/abs/2404.00766) + +## 11. Source-handling rules + +- Official documentation and source are evidence for implemented or declared behavior, not independent performance. +- A vendor benchmark is labeled vendor claim until the harness reproduces it. +- A peer-reviewed paper establishes only the version, configuration, and workload it evaluated. +- Search snippets, comparison sites, and unsourced blogs are discovery aids, not final evidence. +- Unknown is a valid result and creates a concrete experiment or source-inspection task. +- All web facts are rechecked at benchmark freeze because this corpus is current only through the research date. + +## 12. Reproduction record template + +- engine: `SurrealDB` +- version: `TBD at benchmark freeze` +- artifact digest: `TBD` +- source commit: `TBD or managed-service N/A` +- edition/license: `TBD` +- query language/version: `TBD` +- storage and durability mode: `TBD` +- cluster and replication: `TBD` +- CPU/RAM/NVMe/network: `TBD` +- OS/kernel/filesystem: `TBD` +- dataset URI and digest: `TBD` +- loader command and duration: `TBD` +- physical bytes by category: `TBD` +- tuning file: `TBD` +- query corpus commit: `TBD` +- raw result URI/digest: `TBD` +- profiler/trace URI: `TBD` +- correctness status: `TBD` +- reviewer and rerun date: `TBD` diff --git a/docs/research/engine-terminusdb.md b/docs/research/engine-terminusdb.md new file mode 100644 index 0000000..98e8681 --- /dev/null +++ b/docs/research/engine-terminusdb.md @@ -0,0 +1,886 @@ +# TerminusDB: 2026 deep technical and competitive specification + +Research cut: `2026-08-08` +Status: evidence-backed competitor audit; not a vendor endorsement +Family: `version-controlled document graph database` +Evidence convention: **Observed/official**, **Vendor claim**, **Research inference**, **Unknown**, **Qualification target**. + +## 1. Decision summary + +TerminusDB is the strongest lesson for immutable lineage, content addressing, and branchable metadata. + +This document answers two questions: what this engine actually proves in 2026, and what zu must build or measure to earn a defensible advantage. A missing public detail remains unknown; it is never silently filled with a favorable assumption. + +### Snapshot card + +- Lifecycle: active. +- Data model: typed documents decomposed into graph triples. +- Query surface: WOQL/Datalog, GraphQL, document APIs. +- Persistent layout: immutable layered triple store optimized for revision history. +- Execution: Datalog pattern matching plus document assembly. +- Transactions: ACID immutable commits with branching, diff, merge, and time travel. +- Distribution: federation/version exchange rather than transparent sharded query execution. +- Object-storage posture: immutable objects are conceptually compatible with object storage, but current serving is not documented as S3-native. +- License/commercial boundary: Apache-2.0 current repository. +- Scale evidence: versioned knowledge graphs; not demonstrated at PB interactive topology scale. +- Benchmark posture: benchmark revision/diff/merge separately from traversal. + +### Facts that materially affect comparison + +- F01 — Documents are the API while triples are the underlying graph representation. +- F02 — A closed-world schema enables stronger validation than open RDF stores. +- F03 — Every change forms immutable history suitable for diff and rollback. +- F04 — The Datalog engine is implemented around Prolog lineage. +- F05 — Version-control features increase retained bytes and GC complexity, which must enter cost models. + +### Bottom-line fit against zu's target + +- Very-low latency: compare hot point and bounded traversal paths; never extrapolate from scans or algorithms. +- Very-low resources: charge resident set, page cache, remote cache, background services, and replicas. +- Distributed: distinguish read replication, partitioned capacity, distributed transactions, and elastic stateless compute. +- Fixed cost: no engine has fixed marginal cost by declaration; admission, batching, and capacity reservations create the bound. +- S3 authority: backups, imports, lake scans, and S3-native demand paging are four different architectures. +- PB / trillion-edge scale: require a capacity derivation plus a run at the largest affordable scale; marketing adjectives do not qualify. +- Tenfold win: can be a per-cell qualification result, never a universal statement across incomparable workloads. + +## 2. Product and ecosystem boundary + +The audited unit is **TerminusDB** in the exact release, edition, deployment, and durability mode recorded by the harness. The family classification is **version-controlled document graph database**. The current lifecycle statement is: active. + +The harness must record binary/container digest, source commit when available, build flags, plugins, license/edition, language mode, storage mode, cluster topology, replication factor, durability settings, cache sizes, thread counts, NUMA policy, kernel, filesystem, cloud region, and all environment variables that affect execution. + +A managed service is not placed in a same-hardware chart. It receives a service-level result with provisioned units, region, public price, and observed provider metrics. A historical engine remains useful for regression but cannot support a claim about beating all current competitors. + +## 3. Architecture reconstruction + +### 3.1 Logical model + +TerminusDB exposes typed documents decomposed into graph triples. The conformance corpus must test nulls, missing properties, labels/types, direction, self-loops, parallel edges, element equality, path equality, bag semantics, ordering, numeric overflow, string collation, temporal values, and schema evolution. + +### 3.2 Language and compiler + +The public query surface is WOQL/Datalog, GraphQL, document APIs. Syntax similarity is not semantic equivalence. Every supported construct needs a result oracle and an unsupported-feature declaration. + +### 3.3 Storage + +The best supported storage summary is: immutable layered triple store optimized for revision history. This statement must be refined from code, format documentation, or provider counters before using it in a performance explanation. + +### 3.4 Execution + +The best supported execution summary is: Datalog pattern matching plus document assembly. The benchmark profiler must confirm which runtime and operators actually executed. + +### 3.5 Transactions and recovery + +The public contract is: ACID immutable commits with branching, diff, merge, and time travel. Exact acknowledgement, isolation anomalies, recovery bounds, and failover behavior remain separate qualification items. + +### 3.6 Distribution + +The deployment shape is: federation/version exchange rather than transparent sharded query execution. Replication is not capacity sharding; sharding is not distributed ACID; stateless readers are not stateless storage. + +### 3.7 Object storage and cost + +The 2026 posture is: immutable objects are conceptually compatible with object storage, but current serving is not documented as S3-native. The audit distinguishes authoritative live bytes, derived acceleration, backup, import/export, and spill. + +## 4. Forty-control deep audit + +### 4.1 `product_boundary` + +Audit question: What exact executable, edition, and storage mode is the system under test? + +Current assessment: Pin TerminusDB, lifecycle `active`, and its edition/mode. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.2 `authority` + +Audit question: Which durable component is the source of truth after every acknowledged write? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.3 `identity` + +Audit question: Are node and edge identities stable across compaction, export, replication, and restore? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.4 `parallel_edges` + +Audit question: Can distinct parallel edges retain properties and trail identity end to end? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.5 `schema` + +Audit question: Is the schema open, closed, optional, inferred, or externally mapped? + +Current assessment: Start from `typed documents decomposed into graph triples` and test actual constraints. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.6 `labels` + +Audit question: How are multiple labels represented and indexed? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.7 `adjacency_out` + +Audit question: How is outgoing adjacency located, encoded, split, cached, and updated? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.8 `adjacency_in` + +Audit question: Is incoming adjacency first-class, derived, replicated, or a fan-out operation? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.9 `supernodes` + +Audit question: How are million-to-billion-degree vertices represented and scheduled? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.10 `properties` + +Audit question: Are properties co-located, columnar, row-oriented, document-encoded, or remote? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.11 `compression` + +Audit question: Which topology, integer, string, null, and floating encodings are implemented? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.12 `checksums` + +Audit question: What integrity unit is verified on point reads and range reads? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.13 `snapshot` + +Audit question: What exact token pins graph data, schema, statistics, and indexes? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.14 `isolation` + +Audit question: Which anomalies are forbidden at the documented isolation level? + +Current assessment: Published summary: ACID immutable commits with branching, diff, merge, and time travel. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.15 `durability` + +Audit question: What device/service acknowledgement is required before commit returns? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.16 `recovery` + +Audit question: What bounds restart work after a clean stop and a crash? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.17 `writer_fencing` + +Audit question: Can a stale writer acknowledge after failover or lease expiry? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.18 `partitioning` + +Audit question: What key determines placement and what happens to cross-partition edges? + +Current assessment: Published distribution summary: federation/version exchange rather than transparent sharded query execution. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.19 `rebalancing` + +Audit question: Can placement change online without changing logical identity? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.20 `replication` + +Audit question: Are replicas full, sharded, synchronous, asynchronous, or shared-storage readers? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.21 `optimizer` + +Audit question: Does the optimizer cost graph expansion, joins, network, cache, and remote requests? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.22 `statistics` + +Audit question: Which degree, correlation, path, and property statistics are persistent? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.23 `execution` + +Audit question: Is execution tuple-at-a-time, vectorized, factorized, compiled, matrix, or actor based? + +Current assessment: Expected family: Datalog pattern matching plus document assembly. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.24 `recursion` + +Audit question: How are BFS, shortest paths, trails, simple paths, and arbitrary reachability executed? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.25 `parallelism` + +Audit question: How does the engine avoid skew and nested parallelism under mixed queries? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.26 `memory` + +Audit question: Are all variable allocations charged to bounded query and system budgets? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.27 `spill` + +Audit question: Which operators spill, in what format, and with what admission controls? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.28 `cancellation` + +Audit question: Can cancellation stop CPU, local I/O, remote I/O, retries, and prefetch? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.29 `cache` + +Audit question: What is cached, how is it keyed, admitted, pinned, and evicted? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.30 `cold_start` + +Audit question: What metadata and data round trips are required with empty caches? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.31 `object_requests` + +Audit question: Can a query issue one remote request per node, edge, or result row? + +Current assessment: Published object-store posture: immutable objects are conceptually compatible with object storage, but current serving is not documented as S3-native. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.32 `cost_admission` + +Audit question: Are request, byte, CPU, spill, and result limits enforced before work? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.33 `observability` + +Audit question: Can operators report rows, edges, bytes, requests, stalls, memory, and spill? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.34 `language` + +Audit question: Which GQL/Cypher/SQL-PGQ/Gremlin/SPARQL semantics are declared and tested? + +Current assessment: Declared surface: WOQL/Datalog, GraphQL, document APIs. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.35 `updates` + +Audit question: Are DDL, insert, merge, update, detach delete, and constraints complete? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.36 `bulk_load` + +Audit question: Does bulk load preserve transactional and index invariants? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.37 `backup` + +Audit question: Is backup consistent, incremental, immutable, and restore-tested? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.38 `gc` + +Audit question: How are old snapshots, orphan objects, tombstones, and indexes reclaimed safely? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.39 `security` + +Audit question: Are authentication, authorization, encryption, audit, and tenant isolation in scope? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.40 `operations` + +Audit question: What compaction, upgrade, repair, verification, and capacity procedures exist? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +## 5. Benchmark contract for this engine + +Every case runs correctness first, then isolated latency, then closed-loop concurrency, then open-loop overload. Report median, p95, p99, p99.9, timeout/rejection rate, throughput, CPU-seconds, peak RSS, cache bytes, disk bytes, network bytes, remote requests, write amplification, and estimated monthly cost. + +Warm means all intended engine caches are populated without changing the query parameters. Hot means the exact working set is resident. Cold means process-local, engine, OS, NVMe, and remote cache state are explicitly reset or a fresh namespace is used. Those words are never inferred from repetition count. + +### 5.1 `point_pk` — primary-key node lookup with one projected property + +- Applicability to TerminusDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.2 `point_edge` — stable edge-ID lookup including endpoints and one property + +- Applicability to TerminusDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.3 `degree_1` — degree-one outgoing expansion + +- Applicability to TerminusDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.4 `degree_32` — small adjacency expansion around degree 32 + +- Applicability to TerminusDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.5 `degree_1k` — medium adjacency expansion around degree 1,024 + +- Applicability to TerminusDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.6 `supernode` — range-limited expansion of a ten-million-degree supernode + +- Applicability to TerminusDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.7 `expand_2` — selective two-hop expansion + +- Applicability to TerminusDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.8 `expand_3` — three-hop frontier expansion with duplicate control + +- Applicability to TerminusDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.9 `expand_into` — edge-existence/expand-into between already-bound endpoints + +- Applicability to TerminusDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.10 `multi_edge` — parallel-edge identity and property projection + +- Applicability to TerminusDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.11 `shortest` — bidirectional point-to-point unweighted shortest path + +- Applicability to TerminusDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.12 `weighted` — weighted shortest path with property access + +- Applicability to TerminusDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.13 `var_walk` — bounded variable-length walk + +- Applicability to TerminusDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.14 `trail` — DIFFERENT EDGES trail enumeration + +- Applicability to TerminusDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.15 `simple` — simple-path enumeration with explicit bound + +- Applicability to TerminusDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.16 `triangle` — triangle pattern with worst-case-sensitive join + +- Applicability to TerminusDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.17 `cycle4` — four-cycle pattern + +- Applicability to TerminusDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.18 `star_join` — high-fanout star pattern with property filters + +- Applicability to TerminusDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.19 `optional` — optional match preserving null/bag semantics + +- Applicability to TerminusDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.20 `aggregate` — grouped aggregate after traversal + +- Applicability to TerminusDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.21 `topk` — ordered top-k with late property materialization + +- Applicability to TerminusDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.22 `scan` — full projected property scan + +- Applicability to TerminusDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.23 `selective_scan` — zone/index-pruned selective property scan + +- Applicability to TerminusDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.24 `mixed` — concurrent short reads, complex reads, and updates + +- Applicability to TerminusDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.25 `ingest` — sustained transactional ingest with indexes enabled + +- Applicability to TerminusDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.26 `bulk` — initial bulk load including index/CSR build + +- Applicability to TerminusDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.27 `checkpoint` — checkpoint or compaction while readers remain active + +- Applicability to TerminusDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.28 `recovery` — crash recovery at bounded dirty-log size + +- Applicability to TerminusDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.29 `cold` — same query after clearing engine and OS/cache tiers + +- Applicability to TerminusDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.30 `remote` — same query with authoritative bytes only in object storage + +- Applicability to TerminusDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +## 6. Fairness controls + +- Same logical dataset and update stream; engine-native physical layouts are allowed and disclosed. +- Same result semantics; unsupported queries remain unsupported rather than rewritten into easier questions. +- Same durable acknowledgement class for write comparisons. +- Same number of physical cores and memory limit for self-hosted single-node tests. +- Same aggregate resources and replication fault tolerance for distributed tests. +- Officially recommended tuning may be applied before the freeze and is committed with rationale. +- Query-specific hints are allowed only when equivalent hints are offered to every engine and separately charted. +- Load/build/index time and bytes are first-class results. +- Cold, warm, and hot results are separate charts. +- Managed services use public configurations and cannot borrow hidden same-machine resource claims. +- Failed runs, OOMs, correctness mismatches, and timeouts stay in the dataset. +- Every chart links raw samples and the exact reproduction command. + +## 7. Likely advantages and limits + +The strongest known reason to choose this engine is tied to its family `version-controlled document graph database`, its execution path `Datalog pattern matching plus document assembly`, and its existing ecosystem. The strongest reason to reject it for zu's target is the gap between `immutable objects are conceptually compatible with object storage, but current serving is not documented as S3-native` and an S3-authoritative, request-budgeted, PB-scale graph service. + +Capacity statement: versioned knowledge graphs; not demonstrated at PB interactive topology scale. This is not converted into an edge-count claim without a physical byte model including IDs, both adjacency directions, properties, indexes, MVCC, WAL, replicas, and free space. + +Commercial statement: Apache-2.0 current repository. License cost, support cost, and unavailable enterprise capabilities remain visible in TCO and feature tables. + +## 8. Concrete lessons for zu + +1. Keep stable logical node and edge identity independent of row group, CSR slot, shard, and object range. +2. Store forward and reverse adjacency as immutable range-addressable tiles carrying edge IDs. +3. Feed queries adjacency batches and typed vectors; prohibit one storage call per logical element. +4. Use vectorized/factorized execution for property-heavy patterns and dedicated frontier operators for recursion. +5. Cost topology, properties, network, cache certainty, remote requests, and result materialization together. +6. Separate the local embedded profile from the object-authoritative distributed read profile. +7. Fence writers with monotonic epochs and make ambiguous commits reconcilable by transaction ID. +8. Pack small graph tiles into large immutable objects while retaining independent checksums and range offsets. +9. Keep the hot topology working set in RAM/NVMe; batch cold frontier misses into few remote rounds. +10. Admission-control remote requests and bytes so fixed-price plans have an enforceable upper bound. +11. Partition by workload-aware graph locality, and expose cross-partition semantics rather than hiding them. +12. Publish qualified wins per workload cell; never promise a universal tenfold advantage. + +## 9. Evidence gaps to close before publication + +- Exact current version and release date. +- Exact license text for the benchmarked artifact. +- Storage bytes per node/edge/property on all standard datasets. +- Stable-edge-ID and parallel-edge semantics. +- Isolation litmus results and commit acknowledgement point. +- Crash recovery time versus dirty WAL size. +- Supernode behavior and maximum tested degree. +- Cold-start metadata and request count. +- Distributed cross-partition query amplification. +- Peak memory under skew, cancellation, and overload. +- Background compaction/GC effect on tail latency. +- Full load/index/checkpoint/backup resource cost. +- Reproducible largest-scale result. +- Independent or audited benchmark evidence. + +## 10. Primary and official sources + +- [At a glance](https://terminusdb.org/docs/at-a-glance/) +- [Internals](https://terminusdb.org/docs/terminusdb-internals/) +- [Knowledge graph model](https://terminusdb.org/docs/knowledge-graph-database/) +- [Source repository](https://github.com/terminusdb/terminusdb) +- [LDBC SNB Interactive and audited disclosures](https://ldbcouncil.org/benchmarks/snb/interactive/) +- [LDBC Graphalytics](https://ldbcouncil.org/benchmarks/graphalytics/) +- [SoK: The Faults in our Graph Benchmarks](https://arxiv.org/abs/2404.00766) + +## 11. Source-handling rules + +- Official documentation and source are evidence for implemented or declared behavior, not independent performance. +- A vendor benchmark is labeled vendor claim until the harness reproduces it. +- A peer-reviewed paper establishes only the version, configuration, and workload it evaluated. +- Search snippets, comparison sites, and unsourced blogs are discovery aids, not final evidence. +- Unknown is a valid result and creates a concrete experiment or source-inspection task. +- All web facts are rechecked at benchmark freeze because this corpus is current only through the research date. + +## 12. Reproduction record template + +- engine: `TerminusDB` +- version: `TBD at benchmark freeze` +- artifact digest: `TBD` +- source commit: `TBD or managed-service N/A` +- edition/license: `TBD` +- query language/version: `TBD` +- storage and durability mode: `TBD` +- cluster and replication: `TBD` +- CPU/RAM/NVMe/network: `TBD` +- OS/kernel/filesystem: `TBD` +- dataset URI and digest: `TBD` +- loader command and duration: `TBD` +- physical bytes by category: `TBD` +- tuning file: `TBD` +- query corpus commit: `TBD` +- raw result URI/digest: `TBD` +- profiler/trace URI: `TBD` +- correctness status: `TBD` +- reviewer and rerun date: `TBD` diff --git a/docs/research/engine-tigergraph.md b/docs/research/engine-tigergraph.md new file mode 100644 index 0000000..cdd41ab --- /dev/null +++ b/docs/research/engine-tigergraph.md @@ -0,0 +1,886 @@ +# TigerGraph: 2026 deep technical and competitive specification + +Research cut: `2026-08-08` +Status: evidence-backed competitor audit; not a vendor endorsement +Family: `distributed native property graph` +Evidence convention: **Observed/official**, **Vendor claim**, **Research inference**, **Unknown**, **Qualification target**. + +## 1. Decision summary + +TigerGraph sets the mature distributed analytics bar; zu's likely win is cost/resource efficiency and embedded simplicity, not every throughput regime. + +This document answers two questions: what this engine actually proves in 2026, and what zu must build or measure to earn a defensible advantage. A missing public detail remains unknown; it is never silently filled with a favorable assumption. + +### Snapshot card + +- Lifecycle: active; 4.2.4 released 2026-07-20. +- Data model: typed property graph. +- Query surface: GSQL, openCypher, REST, GraphQL surfaces. +- Persistent layout: native distributed compressed graph storage; Savanna separates storage and compute. +- Execution: C++ native parallel graph execution and compiled GSQL. +- Transactions: ACID/HA features are edition and topology dependent. +- Distribution: automatic partitioning, MPP execution, leaderless replicated self-managed architecture; Savanna workspaces. +- Object-storage posture: Savanna is disaggregated but public docs do not establish an S3-range-native adjacency path. +- License/commercial boundary: commercial proprietary. +- Scale evidence: public material cites hundreds of billions of edges; exact audited configurations matter. +- Benchmark posture: use LDBC disclosures and self-run compatible subsets; compiled-query warmup must be explicit. + +### Facts that materially affect comparison + +- F01 — GSE and GPE are implemented in C++. +- F02 — The database combines local storage and local computation in its classic architecture. +- F03 — Savanna introduces independent storage/compute scaling and read-write versus read-only workspaces. +- F04 — Automatic partitioning can redistribute data during cluster expansion or contraction. +- F05 — Vendor throughput claims require FDR-grade hardware, cost, replication, and query disclosure. + +### Bottom-line fit against zu's target + +- Very-low latency: compare hot point and bounded traversal paths; never extrapolate from scans or algorithms. +- Very-low resources: charge resident set, page cache, remote cache, background services, and replicas. +- Distributed: distinguish read replication, partitioned capacity, distributed transactions, and elastic stateless compute. +- Fixed cost: no engine has fixed marginal cost by declaration; admission, batching, and capacity reservations create the bound. +- S3 authority: backups, imports, lake scans, and S3-native demand paging are four different architectures. +- PB / trillion-edge scale: require a capacity derivation plus a run at the largest affordable scale; marketing adjectives do not qualify. +- Tenfold win: can be a per-cell qualification result, never a universal statement across incomparable workloads. + +## 2. Product and ecosystem boundary + +The audited unit is **TigerGraph** in the exact release, edition, deployment, and durability mode recorded by the harness. The family classification is **distributed native property graph**. The current lifecycle statement is: active; 4.2.4 released 2026-07-20. + +The harness must record binary/container digest, source commit when available, build flags, plugins, license/edition, language mode, storage mode, cluster topology, replication factor, durability settings, cache sizes, thread counts, NUMA policy, kernel, filesystem, cloud region, and all environment variables that affect execution. + +A managed service is not placed in a same-hardware chart. It receives a service-level result with provisioned units, region, public price, and observed provider metrics. A historical engine remains useful for regression but cannot support a claim about beating all current competitors. + +## 3. Architecture reconstruction + +### 3.1 Logical model + +TigerGraph exposes typed property graph. The conformance corpus must test nulls, missing properties, labels/types, direction, self-loops, parallel edges, element equality, path equality, bag semantics, ordering, numeric overflow, string collation, temporal values, and schema evolution. + +### 3.2 Language and compiler + +The public query surface is GSQL, openCypher, REST, GraphQL surfaces. Syntax similarity is not semantic equivalence. Every supported construct needs a result oracle and an unsupported-feature declaration. + +### 3.3 Storage + +The best supported storage summary is: native distributed compressed graph storage; Savanna separates storage and compute. This statement must be refined from code, format documentation, or provider counters before using it in a performance explanation. + +### 3.4 Execution + +The best supported execution summary is: C++ native parallel graph execution and compiled GSQL. The benchmark profiler must confirm which runtime and operators actually executed. + +### 3.5 Transactions and recovery + +The public contract is: ACID/HA features are edition and topology dependent. Exact acknowledgement, isolation anomalies, recovery bounds, and failover behavior remain separate qualification items. + +### 3.6 Distribution + +The deployment shape is: automatic partitioning, MPP execution, leaderless replicated self-managed architecture; Savanna workspaces. Replication is not capacity sharding; sharding is not distributed ACID; stateless readers are not stateless storage. + +### 3.7 Object storage and cost + +The 2026 posture is: Savanna is disaggregated but public docs do not establish an S3-range-native adjacency path. The audit distinguishes authoritative live bytes, derived acceleration, backup, import/export, and spill. + +## 4. Forty-control deep audit + +### 4.1 `product_boundary` + +Audit question: What exact executable, edition, and storage mode is the system under test? + +Current assessment: Pin TigerGraph, lifecycle `active; 4.2.4 released 2026-07-20`, and its edition/mode. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.2 `authority` + +Audit question: Which durable component is the source of truth after every acknowledged write? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.3 `identity` + +Audit question: Are node and edge identities stable across compaction, export, replication, and restore? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.4 `parallel_edges` + +Audit question: Can distinct parallel edges retain properties and trail identity end to end? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.5 `schema` + +Audit question: Is the schema open, closed, optional, inferred, or externally mapped? + +Current assessment: Start from `typed property graph` and test actual constraints. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.6 `labels` + +Audit question: How are multiple labels represented and indexed? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.7 `adjacency_out` + +Audit question: How is outgoing adjacency located, encoded, split, cached, and updated? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.8 `adjacency_in` + +Audit question: Is incoming adjacency first-class, derived, replicated, or a fan-out operation? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.9 `supernodes` + +Audit question: How are million-to-billion-degree vertices represented and scheduled? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.10 `properties` + +Audit question: Are properties co-located, columnar, row-oriented, document-encoded, or remote? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.11 `compression` + +Audit question: Which topology, integer, string, null, and floating encodings are implemented? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.12 `checksums` + +Audit question: What integrity unit is verified on point reads and range reads? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.13 `snapshot` + +Audit question: What exact token pins graph data, schema, statistics, and indexes? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.14 `isolation` + +Audit question: Which anomalies are forbidden at the documented isolation level? + +Current assessment: Published summary: ACID/HA features are edition and topology dependent. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.15 `durability` + +Audit question: What device/service acknowledgement is required before commit returns? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.16 `recovery` + +Audit question: What bounds restart work after a clean stop and a crash? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.17 `writer_fencing` + +Audit question: Can a stale writer acknowledge after failover or lease expiry? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.18 `partitioning` + +Audit question: What key determines placement and what happens to cross-partition edges? + +Current assessment: Published distribution summary: automatic partitioning, MPP execution, leaderless replicated self-managed architecture; Savanna workspaces. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.19 `rebalancing` + +Audit question: Can placement change online without changing logical identity? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.20 `replication` + +Audit question: Are replicas full, sharded, synchronous, asynchronous, or shared-storage readers? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.21 `optimizer` + +Audit question: Does the optimizer cost graph expansion, joins, network, cache, and remote requests? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.22 `statistics` + +Audit question: Which degree, correlation, path, and property statistics are persistent? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.23 `execution` + +Audit question: Is execution tuple-at-a-time, vectorized, factorized, compiled, matrix, or actor based? + +Current assessment: Expected family: C++ native parallel graph execution and compiled GSQL. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.24 `recursion` + +Audit question: How are BFS, shortest paths, trails, simple paths, and arbitrary reachability executed? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.25 `parallelism` + +Audit question: How does the engine avoid skew and nested parallelism under mixed queries? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.26 `memory` + +Audit question: Are all variable allocations charged to bounded query and system budgets? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.27 `spill` + +Audit question: Which operators spill, in what format, and with what admission controls? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.28 `cancellation` + +Audit question: Can cancellation stop CPU, local I/O, remote I/O, retries, and prefetch? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.29 `cache` + +Audit question: What is cached, how is it keyed, admitted, pinned, and evicted? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.30 `cold_start` + +Audit question: What metadata and data round trips are required with empty caches? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.31 `object_requests` + +Audit question: Can a query issue one remote request per node, edge, or result row? + +Current assessment: Published object-store posture: Savanna is disaggregated but public docs do not establish an S3-range-native adjacency path. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.32 `cost_admission` + +Audit question: Are request, byte, CPU, spill, and result limits enforced before work? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.33 `observability` + +Audit question: Can operators report rows, edges, bytes, requests, stalls, memory, and spill? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.34 `language` + +Audit question: Which GQL/Cypher/SQL-PGQ/Gremlin/SPARQL semantics are declared and tested? + +Current assessment: Declared surface: GSQL, openCypher, REST, GraphQL surfaces. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.35 `updates` + +Audit question: Are DDL, insert, merge, update, detach delete, and constraints complete? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.36 `bulk_load` + +Audit question: Does bulk load preserve transactional and index invariants? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.37 `backup` + +Audit question: Is backup consistent, incremental, immutable, and restore-tested? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.38 `gc` + +Audit question: How are old snapshots, orphan objects, tombstones, and indexes reclaimed safely? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.39 `security` + +Audit question: Are authentication, authorization, encryption, audit, and tenant isolation in scope? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.40 `operations` + +Audit question: What compaction, upgrade, repair, verification, and capacity procedures exist? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +## 5. Benchmark contract for this engine + +Every case runs correctness first, then isolated latency, then closed-loop concurrency, then open-loop overload. Report median, p95, p99, p99.9, timeout/rejection rate, throughput, CPU-seconds, peak RSS, cache bytes, disk bytes, network bytes, remote requests, write amplification, and estimated monthly cost. + +Warm means all intended engine caches are populated without changing the query parameters. Hot means the exact working set is resident. Cold means process-local, engine, OS, NVMe, and remote cache state are explicitly reset or a fresh namespace is used. Those words are never inferred from repetition count. + +### 5.1 `point_pk` — primary-key node lookup with one projected property + +- Applicability to TigerGraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.2 `point_edge` — stable edge-ID lookup including endpoints and one property + +- Applicability to TigerGraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.3 `degree_1` — degree-one outgoing expansion + +- Applicability to TigerGraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.4 `degree_32` — small adjacency expansion around degree 32 + +- Applicability to TigerGraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.5 `degree_1k` — medium adjacency expansion around degree 1,024 + +- Applicability to TigerGraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.6 `supernode` — range-limited expansion of a ten-million-degree supernode + +- Applicability to TigerGraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.7 `expand_2` — selective two-hop expansion + +- Applicability to TigerGraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.8 `expand_3` — three-hop frontier expansion with duplicate control + +- Applicability to TigerGraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.9 `expand_into` — edge-existence/expand-into between already-bound endpoints + +- Applicability to TigerGraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.10 `multi_edge` — parallel-edge identity and property projection + +- Applicability to TigerGraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.11 `shortest` — bidirectional point-to-point unweighted shortest path + +- Applicability to TigerGraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.12 `weighted` — weighted shortest path with property access + +- Applicability to TigerGraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.13 `var_walk` — bounded variable-length walk + +- Applicability to TigerGraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.14 `trail` — DIFFERENT EDGES trail enumeration + +- Applicability to TigerGraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.15 `simple` — simple-path enumeration with explicit bound + +- Applicability to TigerGraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.16 `triangle` — triangle pattern with worst-case-sensitive join + +- Applicability to TigerGraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.17 `cycle4` — four-cycle pattern + +- Applicability to TigerGraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.18 `star_join` — high-fanout star pattern with property filters + +- Applicability to TigerGraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.19 `optional` — optional match preserving null/bag semantics + +- Applicability to TigerGraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.20 `aggregate` — grouped aggregate after traversal + +- Applicability to TigerGraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.21 `topk` — ordered top-k with late property materialization + +- Applicability to TigerGraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.22 `scan` — full projected property scan + +- Applicability to TigerGraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.23 `selective_scan` — zone/index-pruned selective property scan + +- Applicability to TigerGraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.24 `mixed` — concurrent short reads, complex reads, and updates + +- Applicability to TigerGraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.25 `ingest` — sustained transactional ingest with indexes enabled + +- Applicability to TigerGraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.26 `bulk` — initial bulk load including index/CSR build + +- Applicability to TigerGraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.27 `checkpoint` — checkpoint or compaction while readers remain active + +- Applicability to TigerGraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.28 `recovery` — crash recovery at bounded dirty-log size + +- Applicability to TigerGraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.29 `cold` — same query after clearing engine and OS/cache tiers + +- Applicability to TigerGraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.30 `remote` — same query with authoritative bytes only in object storage + +- Applicability to TigerGraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +## 6. Fairness controls + +- Same logical dataset and update stream; engine-native physical layouts are allowed and disclosed. +- Same result semantics; unsupported queries remain unsupported rather than rewritten into easier questions. +- Same durable acknowledgement class for write comparisons. +- Same number of physical cores and memory limit for self-hosted single-node tests. +- Same aggregate resources and replication fault tolerance for distributed tests. +- Officially recommended tuning may be applied before the freeze and is committed with rationale. +- Query-specific hints are allowed only when equivalent hints are offered to every engine and separately charted. +- Load/build/index time and bytes are first-class results. +- Cold, warm, and hot results are separate charts. +- Managed services use public configurations and cannot borrow hidden same-machine resource claims. +- Failed runs, OOMs, correctness mismatches, and timeouts stay in the dataset. +- Every chart links raw samples and the exact reproduction command. + +## 7. Likely advantages and limits + +The strongest known reason to choose this engine is tied to its family `distributed native property graph`, its execution path `C++ native parallel graph execution and compiled GSQL`, and its existing ecosystem. The strongest reason to reject it for zu's target is the gap between `Savanna is disaggregated but public docs do not establish an S3-range-native adjacency path` and an S3-authoritative, request-budgeted, PB-scale graph service. + +Capacity statement: public material cites hundreds of billions of edges; exact audited configurations matter. This is not converted into an edge-count claim without a physical byte model including IDs, both adjacency directions, properties, indexes, MVCC, WAL, replicas, and free space. + +Commercial statement: commercial proprietary. License cost, support cost, and unavailable enterprise capabilities remain visible in TCO and feature tables. + +## 8. Concrete lessons for zu + +1. Keep stable logical node and edge identity independent of row group, CSR slot, shard, and object range. +2. Store forward and reverse adjacency as immutable range-addressable tiles carrying edge IDs. +3. Feed queries adjacency batches and typed vectors; prohibit one storage call per logical element. +4. Use vectorized/factorized execution for property-heavy patterns and dedicated frontier operators for recursion. +5. Cost topology, properties, network, cache certainty, remote requests, and result materialization together. +6. Separate the local embedded profile from the object-authoritative distributed read profile. +7. Fence writers with monotonic epochs and make ambiguous commits reconcilable by transaction ID. +8. Pack small graph tiles into large immutable objects while retaining independent checksums and range offsets. +9. Keep the hot topology working set in RAM/NVMe; batch cold frontier misses into few remote rounds. +10. Admission-control remote requests and bytes so fixed-price plans have an enforceable upper bound. +11. Partition by workload-aware graph locality, and expose cross-partition semantics rather than hiding them. +12. Publish qualified wins per workload cell; never promise a universal tenfold advantage. + +## 9. Evidence gaps to close before publication + +- Exact current version and release date. +- Exact license text for the benchmarked artifact. +- Storage bytes per node/edge/property on all standard datasets. +- Stable-edge-ID and parallel-edge semantics. +- Isolation litmus results and commit acknowledgement point. +- Crash recovery time versus dirty WAL size. +- Supernode behavior and maximum tested degree. +- Cold-start metadata and request count. +- Distributed cross-partition query amplification. +- Peak memory under skew, cancellation, and overload. +- Background compaction/GC effect on tail latency. +- Full load/index/checkpoint/backup resource cost. +- Reproducible largest-scale result. +- Independent or audited benchmark evidence. + +## 10. Primary and official sources + +- [Current documentation](https://www.tigergraph.com/docs/home/) +- [Internal architecture](https://docs.tigergraph.com/tigergraph-server/current/intro/internal-architecture) +- [Savanna architecture](https://tigergraph.com/docs/savanna/main/overview/architecture) +- [System paper](https://arxiv.org/abs/1901.08248) +- [LDBC SNB Interactive and audited disclosures](https://ldbcouncil.org/benchmarks/snb/interactive/) +- [LDBC Graphalytics](https://ldbcouncil.org/benchmarks/graphalytics/) +- [SoK: The Faults in our Graph Benchmarks](https://arxiv.org/abs/2404.00766) + +## 11. Source-handling rules + +- Official documentation and source are evidence for implemented or declared behavior, not independent performance. +- A vendor benchmark is labeled vendor claim until the harness reproduces it. +- A peer-reviewed paper establishes only the version, configuration, and workload it evaluated. +- Search snippets, comparison sites, and unsourced blogs are discovery aids, not final evidence. +- Unknown is a valid result and creates a concrete experiment or source-inspection task. +- All web facts are rechecked at benchmark freeze because this corpus is current only through the research date. + +## 12. Reproduction record template + +- engine: `TigerGraph` +- version: `TBD at benchmark freeze` +- artifact digest: `TBD` +- source commit: `TBD or managed-service N/A` +- edition/license: `TBD` +- query language/version: `TBD` +- storage and durability mode: `TBD` +- cluster and replication: `TBD` +- CPU/RAM/NVMe/network: `TBD` +- OS/kernel/filesystem: `TBD` +- dataset URI and digest: `TBD` +- loader command and duration: `TBD` +- physical bytes by category: `TBD` +- tuning file: `TBD` +- query corpus commit: `TBD` +- raw result URI/digest: `TBD` +- profiler/trace URI: `TBD` +- correctness status: `TBD` +- reviewer and rerun date: `TBD` diff --git a/docs/research/engine-tugraph.md b/docs/research/engine-tugraph.md new file mode 100644 index 0000000..fdcf34f --- /dev/null +++ b/docs/research/engine-tugraph.md @@ -0,0 +1,885 @@ +# TuGraph: 2026 deep technical and competitive specification + +Research cut: `2026-08-08` +Status: evidence-backed competitor audit; not a vendor endorsement +Family: `HTAP native property graph` +Evidence convention: **Observed/official**, **Vendor claim**, **Research inference**, **Unknown**, **Qualification target**. + +## 1. Decision summary + +TuGraph is a serious C++ HTAP comparator, particularly for local mutable traversal and compiled procedures. + +This document answers two questions: what this engine actually proves in 2026, and what zu must build or measure to earn a defensible advantage. A missing public detail remains unknown; it is never silently filled with a favorable assumption. + +### Snapshot card + +- Lifecycle: active. +- Data model: property graph. +- Query surface: Cypher plus procedures and APIs. +- Persistent layout: native C++ graph storage with local and enterprise distributed modes. +- Execution: low-latency transactional traversal plus analytical engine and plugins. +- Transactions: ACID in local engine; HA/distributed semantics are edition dependent. +- Distribution: community single-node/HA features and enterprise distributed architecture. +- Object-storage posture: not S3-native. +- License/commercial boundary: Apache-2.0 Community; commercial Enterprise. +- Scale evidence: large production claims exist; PB public qualification is insufficient. +- Benchmark posture: use LDBC implementation disclosures and pin Community versus Enterprise. + +### Facts that materially affect comparison + +- F01 — TuGraph originated at Ant Group and Tsinghua and is used in risk-control settings. +- F02 — The product presents database, analytics, visualization, and operations as one system. +- F03 — Stored procedures can avoid general query-planning overhead for hot paths. +- F04 — Community and Enterprise architecture claims must be separated. +- F05 — Chinese and English documentation can diverge; cite exact versioned pages. + +### Bottom-line fit against zu's target + +- Very-low latency: compare hot point and bounded traversal paths; never extrapolate from scans or algorithms. +- Very-low resources: charge resident set, page cache, remote cache, background services, and replicas. +- Distributed: distinguish read replication, partitioned capacity, distributed transactions, and elastic stateless compute. +- Fixed cost: no engine has fixed marginal cost by declaration; admission, batching, and capacity reservations create the bound. +- S3 authority: backups, imports, lake scans, and S3-native demand paging are four different architectures. +- PB / trillion-edge scale: require a capacity derivation plus a run at the largest affordable scale; marketing adjectives do not qualify. +- Tenfold win: can be a per-cell qualification result, never a universal statement across incomparable workloads. + +## 2. Product and ecosystem boundary + +The audited unit is **TuGraph** in the exact release, edition, deployment, and durability mode recorded by the harness. The family classification is **HTAP native property graph**. The current lifecycle statement is: active. + +The harness must record binary/container digest, source commit when available, build flags, plugins, license/edition, language mode, storage mode, cluster topology, replication factor, durability settings, cache sizes, thread counts, NUMA policy, kernel, filesystem, cloud region, and all environment variables that affect execution. + +A managed service is not placed in a same-hardware chart. It receives a service-level result with provisioned units, region, public price, and observed provider metrics. A historical engine remains useful for regression but cannot support a claim about beating all current competitors. + +## 3. Architecture reconstruction + +### 3.1 Logical model + +TuGraph exposes property graph. The conformance corpus must test nulls, missing properties, labels/types, direction, self-loops, parallel edges, element equality, path equality, bag semantics, ordering, numeric overflow, string collation, temporal values, and schema evolution. + +### 3.2 Language and compiler + +The public query surface is Cypher plus procedures and APIs. Syntax similarity is not semantic equivalence. Every supported construct needs a result oracle and an unsupported-feature declaration. + +### 3.3 Storage + +The best supported storage summary is: native C++ graph storage with local and enterprise distributed modes. This statement must be refined from code, format documentation, or provider counters before using it in a performance explanation. + +### 3.4 Execution + +The best supported execution summary is: low-latency transactional traversal plus analytical engine and plugins. The benchmark profiler must confirm which runtime and operators actually executed. + +### 3.5 Transactions and recovery + +The public contract is: ACID in local engine; HA/distributed semantics are edition dependent. Exact acknowledgement, isolation anomalies, recovery bounds, and failover behavior remain separate qualification items. + +### 3.6 Distribution + +The deployment shape is: community single-node/HA features and enterprise distributed architecture. Replication is not capacity sharding; sharding is not distributed ACID; stateless readers are not stateless storage. + +### 3.7 Object storage and cost + +The 2026 posture is: not S3-native. The audit distinguishes authoritative live bytes, derived acceleration, backup, import/export, and spill. + +## 4. Forty-control deep audit + +### 4.1 `product_boundary` + +Audit question: What exact executable, edition, and storage mode is the system under test? + +Current assessment: Pin TuGraph, lifecycle `active`, and its edition/mode. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.2 `authority` + +Audit question: Which durable component is the source of truth after every acknowledged write? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.3 `identity` + +Audit question: Are node and edge identities stable across compaction, export, replication, and restore? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.4 `parallel_edges` + +Audit question: Can distinct parallel edges retain properties and trail identity end to end? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.5 `schema` + +Audit question: Is the schema open, closed, optional, inferred, or externally mapped? + +Current assessment: Start from `property graph` and test actual constraints. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.6 `labels` + +Audit question: How are multiple labels represented and indexed? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.7 `adjacency_out` + +Audit question: How is outgoing adjacency located, encoded, split, cached, and updated? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.8 `adjacency_in` + +Audit question: Is incoming adjacency first-class, derived, replicated, or a fan-out operation? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.9 `supernodes` + +Audit question: How are million-to-billion-degree vertices represented and scheduled? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.10 `properties` + +Audit question: Are properties co-located, columnar, row-oriented, document-encoded, or remote? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.11 `compression` + +Audit question: Which topology, integer, string, null, and floating encodings are implemented? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.12 `checksums` + +Audit question: What integrity unit is verified on point reads and range reads? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.13 `snapshot` + +Audit question: What exact token pins graph data, schema, statistics, and indexes? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.14 `isolation` + +Audit question: Which anomalies are forbidden at the documented isolation level? + +Current assessment: Published summary: ACID in local engine; HA/distributed semantics are edition dependent. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.15 `durability` + +Audit question: What device/service acknowledgement is required before commit returns? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.16 `recovery` + +Audit question: What bounds restart work after a clean stop and a crash? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.17 `writer_fencing` + +Audit question: Can a stale writer acknowledge after failover or lease expiry? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.18 `partitioning` + +Audit question: What key determines placement and what happens to cross-partition edges? + +Current assessment: Published distribution summary: community single-node/HA features and enterprise distributed architecture. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.19 `rebalancing` + +Audit question: Can placement change online without changing logical identity? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.20 `replication` + +Audit question: Are replicas full, sharded, synchronous, asynchronous, or shared-storage readers? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.21 `optimizer` + +Audit question: Does the optimizer cost graph expansion, joins, network, cache, and remote requests? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.22 `statistics` + +Audit question: Which degree, correlation, path, and property statistics are persistent? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.23 `execution` + +Audit question: Is execution tuple-at-a-time, vectorized, factorized, compiled, matrix, or actor based? + +Current assessment: Expected family: low-latency transactional traversal plus analytical engine and plugins. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.24 `recursion` + +Audit question: How are BFS, shortest paths, trails, simple paths, and arbitrary reachability executed? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.25 `parallelism` + +Audit question: How does the engine avoid skew and nested parallelism under mixed queries? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.26 `memory` + +Audit question: Are all variable allocations charged to bounded query and system budgets? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.27 `spill` + +Audit question: Which operators spill, in what format, and with what admission controls? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.28 `cancellation` + +Audit question: Can cancellation stop CPU, local I/O, remote I/O, retries, and prefetch? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.29 `cache` + +Audit question: What is cached, how is it keyed, admitted, pinned, and evicted? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.30 `cold_start` + +Audit question: What metadata and data round trips are required with empty caches? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.31 `object_requests` + +Audit question: Can a query issue one remote request per node, edge, or result row? + +Current assessment: Published object-store posture: not S3-native. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.32 `cost_admission` + +Audit question: Are request, byte, CPU, spill, and result limits enforced before work? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.33 `observability` + +Audit question: Can operators report rows, edges, bytes, requests, stalls, memory, and spill? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.34 `language` + +Audit question: Which GQL/Cypher/SQL-PGQ/Gremlin/SPARQL semantics are declared and tested? + +Current assessment: Declared surface: Cypher plus procedures and APIs. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.35 `updates` + +Audit question: Are DDL, insert, merge, update, detach delete, and constraints complete? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.36 `bulk_load` + +Audit question: Does bulk load preserve transactional and index invariants? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.37 `backup` + +Audit question: Is backup consistent, incremental, immutable, and restore-tested? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.38 `gc` + +Audit question: How are old snapshots, orphan objects, tombstones, and indexes reclaimed safely? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.39 `security` + +Audit question: Are authentication, authorization, encryption, audit, and tenant isolation in scope? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.40 `operations` + +Audit question: What compaction, upgrade, repair, verification, and capacity procedures exist? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +## 5. Benchmark contract for this engine + +Every case runs correctness first, then isolated latency, then closed-loop concurrency, then open-loop overload. Report median, p95, p99, p99.9, timeout/rejection rate, throughput, CPU-seconds, peak RSS, cache bytes, disk bytes, network bytes, remote requests, write amplification, and estimated monthly cost. + +Warm means all intended engine caches are populated without changing the query parameters. Hot means the exact working set is resident. Cold means process-local, engine, OS, NVMe, and remote cache state are explicitly reset or a fresh namespace is used. Those words are never inferred from repetition count. + +### 5.1 `point_pk` — primary-key node lookup with one projected property + +- Applicability to TuGraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.2 `point_edge` — stable edge-ID lookup including endpoints and one property + +- Applicability to TuGraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.3 `degree_1` — degree-one outgoing expansion + +- Applicability to TuGraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.4 `degree_32` — small adjacency expansion around degree 32 + +- Applicability to TuGraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.5 `degree_1k` — medium adjacency expansion around degree 1,024 + +- Applicability to TuGraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.6 `supernode` — range-limited expansion of a ten-million-degree supernode + +- Applicability to TuGraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.7 `expand_2` — selective two-hop expansion + +- Applicability to TuGraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.8 `expand_3` — three-hop frontier expansion with duplicate control + +- Applicability to TuGraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.9 `expand_into` — edge-existence/expand-into between already-bound endpoints + +- Applicability to TuGraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.10 `multi_edge` — parallel-edge identity and property projection + +- Applicability to TuGraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.11 `shortest` — bidirectional point-to-point unweighted shortest path + +- Applicability to TuGraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.12 `weighted` — weighted shortest path with property access + +- Applicability to TuGraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.13 `var_walk` — bounded variable-length walk + +- Applicability to TuGraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.14 `trail` — DIFFERENT EDGES trail enumeration + +- Applicability to TuGraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.15 `simple` — simple-path enumeration with explicit bound + +- Applicability to TuGraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.16 `triangle` — triangle pattern with worst-case-sensitive join + +- Applicability to TuGraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.17 `cycle4` — four-cycle pattern + +- Applicability to TuGraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.18 `star_join` — high-fanout star pattern with property filters + +- Applicability to TuGraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.19 `optional` — optional match preserving null/bag semantics + +- Applicability to TuGraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.20 `aggregate` — grouped aggregate after traversal + +- Applicability to TuGraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.21 `topk` — ordered top-k with late property materialization + +- Applicability to TuGraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.22 `scan` — full projected property scan + +- Applicability to TuGraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.23 `selective_scan` — zone/index-pruned selective property scan + +- Applicability to TuGraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.24 `mixed` — concurrent short reads, complex reads, and updates + +- Applicability to TuGraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.25 `ingest` — sustained transactional ingest with indexes enabled + +- Applicability to TuGraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.26 `bulk` — initial bulk load including index/CSR build + +- Applicability to TuGraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.27 `checkpoint` — checkpoint or compaction while readers remain active + +- Applicability to TuGraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.28 `recovery` — crash recovery at bounded dirty-log size + +- Applicability to TuGraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.29 `cold` — same query after clearing engine and OS/cache tiers + +- Applicability to TuGraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.30 `remote` — same query with authoritative bytes only in object storage + +- Applicability to TuGraph: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +## 6. Fairness controls + +- Same logical dataset and update stream; engine-native physical layouts are allowed and disclosed. +- Same result semantics; unsupported queries remain unsupported rather than rewritten into easier questions. +- Same durable acknowledgement class for write comparisons. +- Same number of physical cores and memory limit for self-hosted single-node tests. +- Same aggregate resources and replication fault tolerance for distributed tests. +- Officially recommended tuning may be applied before the freeze and is committed with rationale. +- Query-specific hints are allowed only when equivalent hints are offered to every engine and separately charted. +- Load/build/index time and bytes are first-class results. +- Cold, warm, and hot results are separate charts. +- Managed services use public configurations and cannot borrow hidden same-machine resource claims. +- Failed runs, OOMs, correctness mismatches, and timeouts stay in the dataset. +- Every chart links raw samples and the exact reproduction command. + +## 7. Likely advantages and limits + +The strongest known reason to choose this engine is tied to its family `HTAP native property graph`, its execution path `low-latency transactional traversal plus analytical engine and plugins`, and its existing ecosystem. The strongest reason to reject it for zu's target is the gap between `not S3-native` and an S3-authoritative, request-budgeted, PB-scale graph service. + +Capacity statement: large production claims exist; PB public qualification is insufficient. This is not converted into an edge-count claim without a physical byte model including IDs, both adjacency directions, properties, indexes, MVCC, WAL, replicas, and free space. + +Commercial statement: Apache-2.0 Community; commercial Enterprise. License cost, support cost, and unavailable enterprise capabilities remain visible in TCO and feature tables. + +## 8. Concrete lessons for zu + +1. Keep stable logical node and edge identity independent of row group, CSR slot, shard, and object range. +2. Store forward and reverse adjacency as immutable range-addressable tiles carrying edge IDs. +3. Feed queries adjacency batches and typed vectors; prohibit one storage call per logical element. +4. Use vectorized/factorized execution for property-heavy patterns and dedicated frontier operators for recursion. +5. Cost topology, properties, network, cache certainty, remote requests, and result materialization together. +6. Separate the local embedded profile from the object-authoritative distributed read profile. +7. Fence writers with monotonic epochs and make ambiguous commits reconcilable by transaction ID. +8. Pack small graph tiles into large immutable objects while retaining independent checksums and range offsets. +9. Keep the hot topology working set in RAM/NVMe; batch cold frontier misses into few remote rounds. +10. Admission-control remote requests and bytes so fixed-price plans have an enforceable upper bound. +11. Partition by workload-aware graph locality, and expose cross-partition semantics rather than hiding them. +12. Publish qualified wins per workload cell; never promise a universal tenfold advantage. + +## 9. Evidence gaps to close before publication + +- Exact current version and release date. +- Exact license text for the benchmarked artifact. +- Storage bytes per node/edge/property on all standard datasets. +- Stable-edge-ID and parallel-edge semantics. +- Isolation litmus results and commit acknowledgement point. +- Crash recovery time versus dirty WAL size. +- Supernode behavior and maximum tested degree. +- Cold-start metadata and request count. +- Distributed cross-partition query amplification. +- Peak memory under skew, cancellation, and overload. +- Background compaction/GC effect on tail latency. +- Full load/index/checkpoint/backup resource cost. +- Reproducible largest-scale result. +- Independent or audited benchmark evidence. + +## 10. Primary and official sources + +- [Product overview](https://tugraph.tech/product/db?lang=en-US) +- [Documentation](https://tugraph-db.readthedocs.io/en/latest/2.introduction/index.html) +- [Source repository](https://github.com/TuGraph-family/tugraph-db) +- [LDBC SNB Interactive and audited disclosures](https://ldbcouncil.org/benchmarks/snb/interactive/) +- [LDBC Graphalytics](https://ldbcouncil.org/benchmarks/graphalytics/) +- [SoK: The Faults in our Graph Benchmarks](https://arxiv.org/abs/2404.00766) + +## 11. Source-handling rules + +- Official documentation and source are evidence for implemented or declared behavior, not independent performance. +- A vendor benchmark is labeled vendor claim until the harness reproduces it. +- A peer-reviewed paper establishes only the version, configuration, and workload it evaluated. +- Search snippets, comparison sites, and unsourced blogs are discovery aids, not final evidence. +- Unknown is a valid result and creates a concrete experiment or source-inspection task. +- All web facts are rechecked at benchmark freeze because this corpus is current only through the research date. + +## 12. Reproduction record template + +- engine: `TuGraph` +- version: `TBD at benchmark freeze` +- artifact digest: `TBD` +- source commit: `TBD or managed-service N/A` +- edition/license: `TBD` +- query language/version: `TBD` +- storage and durability mode: `TBD` +- cluster and replication: `TBD` +- CPU/RAM/NVMe/network: `TBD` +- OS/kernel/filesystem: `TBD` +- dataset URI and digest: `TBD` +- loader command and duration: `TBD` +- physical bytes by category: `TBD` +- tuning file: `TBD` +- query corpus commit: `TBD` +- raw result URI/digest: `TBD` +- profiler/trace URI: `TBD` +- correctness status: `TBD` +- reviewer and rerun date: `TBD` diff --git a/docs/research/engine-typedb.md b/docs/research/engine-typedb.md new file mode 100644 index 0000000..ccd3f8c --- /dev/null +++ b/docs/research/engine-typedb.md @@ -0,0 +1,886 @@ +# TypeDB: 2026 deep technical and competitive specification + +Research cut: `2026-08-08` +Status: evidence-backed competitor audit; not a vendor endorsement +Family: `typed polymorphic database` +Evidence convention: **Observed/official**, **Vendor claim**, **Research inference**, **Unknown**, **Qualification target**. + +## 1. Decision summary + +TypeDB competes on modeling correctness and inference, not PB topology economics; zu should borrow explicit schema invariants, not its full-copy scale model. + +This document answers two questions: what this engine actually proves in 2026, and what zu must build or measure to earn a defensible advantage. A missing public detail remains unknown; it is never silently filled with a favorable assumption. + +### Snapshot card + +- Lifecycle: active 3.x; clustering was experimental/alpha in current docs. +- Data model: entities, relations, attributes, roles, and strong type system. +- Query surface: TypeQL pipelines. +- Persistent layout: RocksDB foundation. +- Execution: schema-aware inference and pattern query pipeline. +- Transactions: ACID to snapshot isolation; exclusive schema transactions. +- Distribution: Raft replicated leader/follower cluster; writes remain leader-bound; clustering status must be pinned. +- Object-storage posture: not S3-native. +- License/commercial boundary: MPL-2.0 Community; Enterprise/Cloud for clustering. +- Scale evidence: read scale through replication, not data sharding; capacity remains full-copy bounded. +- Benchmark posture: semantic/inference workloads require a separate corpus from ordinary LPG traversal. + +### Facts that materially affect comparison + +- F01 — Read, write, and schema transactions are distinct. +- F02 — Schema transactions exclude concurrent write/schema transactions. +- F03 — Cluster followers can serve reads while one leader handles writes. +- F04 — Current clustering documentation warns that the feature is alpha/experimental. +- F05 — TypeQL 3 expresses staged data and stream transformations. + +### Bottom-line fit against zu's target + +- Very-low latency: compare hot point and bounded traversal paths; never extrapolate from scans or algorithms. +- Very-low resources: charge resident set, page cache, remote cache, background services, and replicas. +- Distributed: distinguish read replication, partitioned capacity, distributed transactions, and elastic stateless compute. +- Fixed cost: no engine has fixed marginal cost by declaration; admission, batching, and capacity reservations create the bound. +- S3 authority: backups, imports, lake scans, and S3-native demand paging are four different architectures. +- PB / trillion-edge scale: require a capacity derivation plus a run at the largest affordable scale; marketing adjectives do not qualify. +- Tenfold win: can be a per-cell qualification result, never a universal statement across incomparable workloads. + +## 2. Product and ecosystem boundary + +The audited unit is **TypeDB** in the exact release, edition, deployment, and durability mode recorded by the harness. The family classification is **typed polymorphic database**. The current lifecycle statement is: active 3.x; clustering was experimental/alpha in current docs. + +The harness must record binary/container digest, source commit when available, build flags, plugins, license/edition, language mode, storage mode, cluster topology, replication factor, durability settings, cache sizes, thread counts, NUMA policy, kernel, filesystem, cloud region, and all environment variables that affect execution. + +A managed service is not placed in a same-hardware chart. It receives a service-level result with provisioned units, region, public price, and observed provider metrics. A historical engine remains useful for regression but cannot support a claim about beating all current competitors. + +## 3. Architecture reconstruction + +### 3.1 Logical model + +TypeDB exposes entities, relations, attributes, roles, and strong type system. The conformance corpus must test nulls, missing properties, labels/types, direction, self-loops, parallel edges, element equality, path equality, bag semantics, ordering, numeric overflow, string collation, temporal values, and schema evolution. + +### 3.2 Language and compiler + +The public query surface is TypeQL pipelines. Syntax similarity is not semantic equivalence. Every supported construct needs a result oracle and an unsupported-feature declaration. + +### 3.3 Storage + +The best supported storage summary is: RocksDB foundation. This statement must be refined from code, format documentation, or provider counters before using it in a performance explanation. + +### 3.4 Execution + +The best supported execution summary is: schema-aware inference and pattern query pipeline. The benchmark profiler must confirm which runtime and operators actually executed. + +### 3.5 Transactions and recovery + +The public contract is: ACID to snapshot isolation; exclusive schema transactions. Exact acknowledgement, isolation anomalies, recovery bounds, and failover behavior remain separate qualification items. + +### 3.6 Distribution + +The deployment shape is: Raft replicated leader/follower cluster; writes remain leader-bound; clustering status must be pinned. Replication is not capacity sharding; sharding is not distributed ACID; stateless readers are not stateless storage. + +### 3.7 Object storage and cost + +The 2026 posture is: not S3-native. The audit distinguishes authoritative live bytes, derived acceleration, backup, import/export, and spill. + +## 4. Forty-control deep audit + +### 4.1 `product_boundary` + +Audit question: What exact executable, edition, and storage mode is the system under test? + +Current assessment: Pin TypeDB, lifecycle `active 3.x; clustering was experimental/alpha in current docs`, and its edition/mode. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.2 `authority` + +Audit question: Which durable component is the source of truth after every acknowledged write? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.3 `identity` + +Audit question: Are node and edge identities stable across compaction, export, replication, and restore? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.4 `parallel_edges` + +Audit question: Can distinct parallel edges retain properties and trail identity end to end? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.5 `schema` + +Audit question: Is the schema open, closed, optional, inferred, or externally mapped? + +Current assessment: Start from `entities, relations, attributes, roles, and strong type system` and test actual constraints. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.6 `labels` + +Audit question: How are multiple labels represented and indexed? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.7 `adjacency_out` + +Audit question: How is outgoing adjacency located, encoded, split, cached, and updated? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.8 `adjacency_in` + +Audit question: Is incoming adjacency first-class, derived, replicated, or a fan-out operation? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.9 `supernodes` + +Audit question: How are million-to-billion-degree vertices represented and scheduled? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.10 `properties` + +Audit question: Are properties co-located, columnar, row-oriented, document-encoded, or remote? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.11 `compression` + +Audit question: Which topology, integer, string, null, and floating encodings are implemented? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.12 `checksums` + +Audit question: What integrity unit is verified on point reads and range reads? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.13 `snapshot` + +Audit question: What exact token pins graph data, schema, statistics, and indexes? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.14 `isolation` + +Audit question: Which anomalies are forbidden at the documented isolation level? + +Current assessment: Published summary: ACID to snapshot isolation; exclusive schema transactions. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.15 `durability` + +Audit question: What device/service acknowledgement is required before commit returns? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.16 `recovery` + +Audit question: What bounds restart work after a clean stop and a crash? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.17 `writer_fencing` + +Audit question: Can a stale writer acknowledge after failover or lease expiry? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.18 `partitioning` + +Audit question: What key determines placement and what happens to cross-partition edges? + +Current assessment: Published distribution summary: Raft replicated leader/follower cluster; writes remain leader-bound; clustering status must be pinned. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.19 `rebalancing` + +Audit question: Can placement change online without changing logical identity? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.20 `replication` + +Audit question: Are replicas full, sharded, synchronous, asynchronous, or shared-storage readers? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.21 `optimizer` + +Audit question: Does the optimizer cost graph expansion, joins, network, cache, and remote requests? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.22 `statistics` + +Audit question: Which degree, correlation, path, and property statistics are persistent? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.23 `execution` + +Audit question: Is execution tuple-at-a-time, vectorized, factorized, compiled, matrix, or actor based? + +Current assessment: Expected family: schema-aware inference and pattern query pipeline. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.24 `recursion` + +Audit question: How are BFS, shortest paths, trails, simple paths, and arbitrary reachability executed? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.25 `parallelism` + +Audit question: How does the engine avoid skew and nested parallelism under mixed queries? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.26 `memory` + +Audit question: Are all variable allocations charged to bounded query and system budgets? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.27 `spill` + +Audit question: Which operators spill, in what format, and with what admission controls? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.28 `cancellation` + +Audit question: Can cancellation stop CPU, local I/O, remote I/O, retries, and prefetch? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.29 `cache` + +Audit question: What is cached, how is it keyed, admitted, pinned, and evicted? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.30 `cold_start` + +Audit question: What metadata and data round trips are required with empty caches? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.31 `object_requests` + +Audit question: Can a query issue one remote request per node, edge, or result row? + +Current assessment: Published object-store posture: not S3-native. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.32 `cost_admission` + +Audit question: Are request, byte, CPU, spill, and result limits enforced before work? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.33 `observability` + +Audit question: Can operators report rows, edges, bytes, requests, stalls, memory, and spill? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.34 `language` + +Audit question: Which GQL/Cypher/SQL-PGQ/Gremlin/SPARQL semantics are declared and tested? + +Current assessment: Declared surface: TypeQL pipelines. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.35 `updates` + +Audit question: Are DDL, insert, merge, update, detach delete, and constraints complete? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.36 `bulk_load` + +Audit question: Does bulk load preserve transactional and index invariants? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.37 `backup` + +Audit question: Is backup consistent, incremental, immutable, and restore-tested? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.38 `gc` + +Audit question: How are old snapshots, orphan objects, tombstones, and indexes reclaimed safely? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.39 `security` + +Audit question: Are authentication, authorization, encryption, audit, and tenant isolation in scope? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.40 `operations` + +Audit question: What compaction, upgrade, repair, verification, and capacity procedures exist? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +## 5. Benchmark contract for this engine + +Every case runs correctness first, then isolated latency, then closed-loop concurrency, then open-loop overload. Report median, p95, p99, p99.9, timeout/rejection rate, throughput, CPU-seconds, peak RSS, cache bytes, disk bytes, network bytes, remote requests, write amplification, and estimated monthly cost. + +Warm means all intended engine caches are populated without changing the query parameters. Hot means the exact working set is resident. Cold means process-local, engine, OS, NVMe, and remote cache state are explicitly reset or a fresh namespace is used. Those words are never inferred from repetition count. + +### 5.1 `point_pk` — primary-key node lookup with one projected property + +- Applicability to TypeDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.2 `point_edge` — stable edge-ID lookup including endpoints and one property + +- Applicability to TypeDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.3 `degree_1` — degree-one outgoing expansion + +- Applicability to TypeDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.4 `degree_32` — small adjacency expansion around degree 32 + +- Applicability to TypeDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.5 `degree_1k` — medium adjacency expansion around degree 1,024 + +- Applicability to TypeDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.6 `supernode` — range-limited expansion of a ten-million-degree supernode + +- Applicability to TypeDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.7 `expand_2` — selective two-hop expansion + +- Applicability to TypeDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.8 `expand_3` — three-hop frontier expansion with duplicate control + +- Applicability to TypeDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.9 `expand_into` — edge-existence/expand-into between already-bound endpoints + +- Applicability to TypeDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.10 `multi_edge` — parallel-edge identity and property projection + +- Applicability to TypeDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.11 `shortest` — bidirectional point-to-point unweighted shortest path + +- Applicability to TypeDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.12 `weighted` — weighted shortest path with property access + +- Applicability to TypeDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.13 `var_walk` — bounded variable-length walk + +- Applicability to TypeDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.14 `trail` — DIFFERENT EDGES trail enumeration + +- Applicability to TypeDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.15 `simple` — simple-path enumeration with explicit bound + +- Applicability to TypeDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.16 `triangle` — triangle pattern with worst-case-sensitive join + +- Applicability to TypeDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.17 `cycle4` — four-cycle pattern + +- Applicability to TypeDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.18 `star_join` — high-fanout star pattern with property filters + +- Applicability to TypeDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.19 `optional` — optional match preserving null/bag semantics + +- Applicability to TypeDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.20 `aggregate` — grouped aggregate after traversal + +- Applicability to TypeDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.21 `topk` — ordered top-k with late property materialization + +- Applicability to TypeDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.22 `scan` — full projected property scan + +- Applicability to TypeDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.23 `selective_scan` — zone/index-pruned selective property scan + +- Applicability to TypeDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.24 `mixed` — concurrent short reads, complex reads, and updates + +- Applicability to TypeDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.25 `ingest` — sustained transactional ingest with indexes enabled + +- Applicability to TypeDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.26 `bulk` — initial bulk load including index/CSR build + +- Applicability to TypeDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.27 `checkpoint` — checkpoint or compaction while readers remain active + +- Applicability to TypeDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.28 `recovery` — crash recovery at bounded dirty-log size + +- Applicability to TypeDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.29 `cold` — same query after clearing engine and OS/cache tiers + +- Applicability to TypeDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.30 `remote` — same query with authoritative bytes only in object storage + +- Applicability to TypeDB: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +## 6. Fairness controls + +- Same logical dataset and update stream; engine-native physical layouts are allowed and disclosed. +- Same result semantics; unsupported queries remain unsupported rather than rewritten into easier questions. +- Same durable acknowledgement class for write comparisons. +- Same number of physical cores and memory limit for self-hosted single-node tests. +- Same aggregate resources and replication fault tolerance for distributed tests. +- Officially recommended tuning may be applied before the freeze and is committed with rationale. +- Query-specific hints are allowed only when equivalent hints are offered to every engine and separately charted. +- Load/build/index time and bytes are first-class results. +- Cold, warm, and hot results are separate charts. +- Managed services use public configurations and cannot borrow hidden same-machine resource claims. +- Failed runs, OOMs, correctness mismatches, and timeouts stay in the dataset. +- Every chart links raw samples and the exact reproduction command. + +## 7. Likely advantages and limits + +The strongest known reason to choose this engine is tied to its family `typed polymorphic database`, its execution path `schema-aware inference and pattern query pipeline`, and its existing ecosystem. The strongest reason to reject it for zu's target is the gap between `not S3-native` and an S3-authoritative, request-budgeted, PB-scale graph service. + +Capacity statement: read scale through replication, not data sharding; capacity remains full-copy bounded. This is not converted into an edge-count claim without a physical byte model including IDs, both adjacency directions, properties, indexes, MVCC, WAL, replicas, and free space. + +Commercial statement: MPL-2.0 Community; Enterprise/Cloud for clustering. License cost, support cost, and unavailable enterprise capabilities remain visible in TCO and feature tables. + +## 8. Concrete lessons for zu + +1. Keep stable logical node and edge identity independent of row group, CSR slot, shard, and object range. +2. Store forward and reverse adjacency as immutable range-addressable tiles carrying edge IDs. +3. Feed queries adjacency batches and typed vectors; prohibit one storage call per logical element. +4. Use vectorized/factorized execution for property-heavy patterns and dedicated frontier operators for recursion. +5. Cost topology, properties, network, cache certainty, remote requests, and result materialization together. +6. Separate the local embedded profile from the object-authoritative distributed read profile. +7. Fence writers with monotonic epochs and make ambiguous commits reconcilable by transaction ID. +8. Pack small graph tiles into large immutable objects while retaining independent checksums and range offsets. +9. Keep the hot topology working set in RAM/NVMe; batch cold frontier misses into few remote rounds. +10. Admission-control remote requests and bytes so fixed-price plans have an enforceable upper bound. +11. Partition by workload-aware graph locality, and expose cross-partition semantics rather than hiding them. +12. Publish qualified wins per workload cell; never promise a universal tenfold advantage. + +## 9. Evidence gaps to close before publication + +- Exact current version and release date. +- Exact license text for the benchmarked artifact. +- Storage bytes per node/edge/property on all standard datasets. +- Stable-edge-ID and parallel-edge semantics. +- Isolation litmus results and commit acknowledgement point. +- Crash recovery time versus dirty WAL size. +- Supernode behavior and maximum tested degree. +- Cold-start metadata and request count. +- Distributed cross-partition query amplification. +- Peak memory under skew, cancellation, and overload. +- Background compaction/GC effect on tail latency. +- Full load/index/checkpoint/backup resource cost. +- Reproducible largest-scale result. +- Independent or audited benchmark evidence. + +## 10. Primary and official sources + +- [Server overview](https://typedb.com/docs/core-concepts/typedb/overview) +- [Transactions](https://typedb.com/docs/core-concepts/typedb/transactions/) +- [Horizontal scaling](https://typedb.com/docs/core-concepts/typedb/horizontal-scaling/) +- [Cluster status](https://typedb.com/docs/reference/typedb-cluster/) +- [LDBC SNB Interactive and audited disclosures](https://ldbcouncil.org/benchmarks/snb/interactive/) +- [LDBC Graphalytics](https://ldbcouncil.org/benchmarks/graphalytics/) +- [SoK: The Faults in our Graph Benchmarks](https://arxiv.org/abs/2404.00766) + +## 11. Source-handling rules + +- Official documentation and source are evidence for implemented or declared behavior, not independent performance. +- A vendor benchmark is labeled vendor claim until the harness reproduces it. +- A peer-reviewed paper establishes only the version, configuration, and workload it evaluated. +- Search snippets, comparison sites, and unsourced blogs are discovery aids, not final evidence. +- Unknown is a valid result and creates a concrete experiment or source-inspection task. +- All web facts are rechecked at benchmark freeze because this corpus is current only through the research date. + +## 12. Reproduction record template + +- engine: `TypeDB` +- version: `TBD at benchmark freeze` +- artifact digest: `TBD` +- source commit: `TBD or managed-service N/A` +- edition/license: `TBD` +- query language/version: `TBD` +- storage and durability mode: `TBD` +- cluster and replication: `TBD` +- CPU/RAM/NVMe/network: `TBD` +- OS/kernel/filesystem: `TBD` +- dataset URI and digest: `TBD` +- loader command and duration: `TBD` +- physical bytes by category: `TBD` +- tuning file: `TBD` +- query corpus commit: `TBD` +- raw result URI/digest: `TBD` +- profiler/trace URI: `TBD` +- correctness status: `TBD` +- reviewer and rerun date: `TBD` diff --git a/docs/research/engine-ultipa.md b/docs/research/engine-ultipa.md new file mode 100644 index 0000000..b4958f7 --- /dev/null +++ b/docs/research/engine-ultipa.md @@ -0,0 +1,885 @@ +# Ultipa Powerhouse: 2026 deep technical and competitive specification + +Research cut: `2026-08-08` +Status: evidence-backed competitor audit; not a vendor endorsement +Family: `hybrid distributed and high-density graph system` +Evidence convention: **Observed/official**, **Vendor claim**, **Research inference**, **Unknown**, **Qualification target**. + +## 1. Decision summary + +Ultipa is important for its explicit two-mode design: economical sharded authority plus high-density acceleration. + +This document answers two questions: what this engine actually proves in 2026, and what zu must build or measure to earn a defensible advantage. A missing public detail remains unknown; it is never silently filled with a favorable assumption. + +### Snapshot card + +- Lifecycle: active v5 line. +- Data model: property graph. +- Query surface: ISO GQL and UQL. +- Persistent layout: node-centric shards plus selectively loaded high-density compute copies. +- Execution: name-server planning; shard execution; HDC servers for deep algorithms and queries. +- Transactions: official docs claim ACID and expose GQL transactions/savepoints. +- Distribution: shard, name, meta, and HDC server roles. +- Object-storage posture: not presented as S3-native live storage. +- License/commercial boundary: commercial proprietary. +- Scale evidence: billions of nodes; no public PB proof. +- Benchmark posture: GQL conformance can be tested; performance claims require independent harness. + +### Facts that materially affect comparison + +- F01 — Sharding distributes nodes by a configurable key and function. +- F02 — HDC selectively loads graph data and can synchronize in real time. +- F03 — The product claims tenfold-or-more HDC gains over shard execution; treat as vendor claim. +- F04 — Its published GQL conformance declaration is unusually detailed. +- F05 — Vector, full-text, ontology, federation, triggers, and procedures broaden parity scope. + +### Bottom-line fit against zu's target + +- Very-low latency: compare hot point and bounded traversal paths; never extrapolate from scans or algorithms. +- Very-low resources: charge resident set, page cache, remote cache, background services, and replicas. +- Distributed: distinguish read replication, partitioned capacity, distributed transactions, and elastic stateless compute. +- Fixed cost: no engine has fixed marginal cost by declaration; admission, batching, and capacity reservations create the bound. +- S3 authority: backups, imports, lake scans, and S3-native demand paging are four different architectures. +- PB / trillion-edge scale: require a capacity derivation plus a run at the largest affordable scale; marketing adjectives do not qualify. +- Tenfold win: can be a per-cell qualification result, never a universal statement across incomparable workloads. + +## 2. Product and ecosystem boundary + +The audited unit is **Ultipa Powerhouse** in the exact release, edition, deployment, and durability mode recorded by the harness. The family classification is **hybrid distributed and high-density graph system**. The current lifecycle statement is: active v5 line. + +The harness must record binary/container digest, source commit when available, build flags, plugins, license/edition, language mode, storage mode, cluster topology, replication factor, durability settings, cache sizes, thread counts, NUMA policy, kernel, filesystem, cloud region, and all environment variables that affect execution. + +A managed service is not placed in a same-hardware chart. It receives a service-level result with provisioned units, region, public price, and observed provider metrics. A historical engine remains useful for regression but cannot support a claim about beating all current competitors. + +## 3. Architecture reconstruction + +### 3.1 Logical model + +Ultipa Powerhouse exposes property graph. The conformance corpus must test nulls, missing properties, labels/types, direction, self-loops, parallel edges, element equality, path equality, bag semantics, ordering, numeric overflow, string collation, temporal values, and schema evolution. + +### 3.2 Language and compiler + +The public query surface is ISO GQL and UQL. Syntax similarity is not semantic equivalence. Every supported construct needs a result oracle and an unsupported-feature declaration. + +### 3.3 Storage + +The best supported storage summary is: node-centric shards plus selectively loaded high-density compute copies. This statement must be refined from code, format documentation, or provider counters before using it in a performance explanation. + +### 3.4 Execution + +The best supported execution summary is: name-server planning; shard execution; HDC servers for deep algorithms and queries. The benchmark profiler must confirm which runtime and operators actually executed. + +### 3.5 Transactions and recovery + +The public contract is: official docs claim ACID and expose GQL transactions/savepoints. Exact acknowledgement, isolation anomalies, recovery bounds, and failover behavior remain separate qualification items. + +### 3.6 Distribution + +The deployment shape is: shard, name, meta, and HDC server roles. Replication is not capacity sharding; sharding is not distributed ACID; stateless readers are not stateless storage. + +### 3.7 Object storage and cost + +The 2026 posture is: not presented as S3-native live storage. The audit distinguishes authoritative live bytes, derived acceleration, backup, import/export, and spill. + +## 4. Forty-control deep audit + +### 4.1 `product_boundary` + +Audit question: What exact executable, edition, and storage mode is the system under test? + +Current assessment: Pin Ultipa Powerhouse, lifecycle `active v5 line`, and its edition/mode. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.2 `authority` + +Audit question: Which durable component is the source of truth after every acknowledged write? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.3 `identity` + +Audit question: Are node and edge identities stable across compaction, export, replication, and restore? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.4 `parallel_edges` + +Audit question: Can distinct parallel edges retain properties and trail identity end to end? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.5 `schema` + +Audit question: Is the schema open, closed, optional, inferred, or externally mapped? + +Current assessment: Start from `property graph` and test actual constraints. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.6 `labels` + +Audit question: How are multiple labels represented and indexed? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.7 `adjacency_out` + +Audit question: How is outgoing adjacency located, encoded, split, cached, and updated? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.8 `adjacency_in` + +Audit question: Is incoming adjacency first-class, derived, replicated, or a fan-out operation? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.9 `supernodes` + +Audit question: How are million-to-billion-degree vertices represented and scheduled? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.10 `properties` + +Audit question: Are properties co-located, columnar, row-oriented, document-encoded, or remote? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.11 `compression` + +Audit question: Which topology, integer, string, null, and floating encodings are implemented? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.12 `checksums` + +Audit question: What integrity unit is verified on point reads and range reads? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.13 `snapshot` + +Audit question: What exact token pins graph data, schema, statistics, and indexes? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.14 `isolation` + +Audit question: Which anomalies are forbidden at the documented isolation level? + +Current assessment: Published summary: official docs claim ACID and expose GQL transactions/savepoints. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.15 `durability` + +Audit question: What device/service acknowledgement is required before commit returns? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.16 `recovery` + +Audit question: What bounds restart work after a clean stop and a crash? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.17 `writer_fencing` + +Audit question: Can a stale writer acknowledge after failover or lease expiry? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.18 `partitioning` + +Audit question: What key determines placement and what happens to cross-partition edges? + +Current assessment: Published distribution summary: shard, name, meta, and HDC server roles. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.19 `rebalancing` + +Audit question: Can placement change online without changing logical identity? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.20 `replication` + +Audit question: Are replicas full, sharded, synchronous, asynchronous, or shared-storage readers? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.21 `optimizer` + +Audit question: Does the optimizer cost graph expansion, joins, network, cache, and remote requests? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.22 `statistics` + +Audit question: Which degree, correlation, path, and property statistics are persistent? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.23 `execution` + +Audit question: Is execution tuple-at-a-time, vectorized, factorized, compiled, matrix, or actor based? + +Current assessment: Expected family: name-server planning; shard execution; HDC servers for deep algorithms and queries. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.24 `recursion` + +Audit question: How are BFS, shortest paths, trails, simple paths, and arbitrary reachability executed? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.25 `parallelism` + +Audit question: How does the engine avoid skew and nested parallelism under mixed queries? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.26 `memory` + +Audit question: Are all variable allocations charged to bounded query and system budgets? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.27 `spill` + +Audit question: Which operators spill, in what format, and with what admission controls? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.28 `cancellation` + +Audit question: Can cancellation stop CPU, local I/O, remote I/O, retries, and prefetch? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.29 `cache` + +Audit question: What is cached, how is it keyed, admitted, pinned, and evicted? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.30 `cold_start` + +Audit question: What metadata and data round trips are required with empty caches? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.31 `object_requests` + +Audit question: Can a query issue one remote request per node, edge, or result row? + +Current assessment: Published object-store posture: not presented as S3-native live storage. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.32 `cost_admission` + +Audit question: Are request, byte, CPU, spill, and result limits enforced before work? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.33 `observability` + +Audit question: Can operators report rows, edges, bytes, requests, stalls, memory, and spill? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.34 `language` + +Audit question: Which GQL/Cypher/SQL-PGQ/Gremlin/SPARQL semantics are declared and tested? + +Current assessment: Declared surface: ISO GQL and UQL. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.35 `updates` + +Audit question: Are DDL, insert, merge, update, detach delete, and constraints complete? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.36 `bulk_load` + +Audit question: Does bulk load preserve transactional and index invariants? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.37 `backup` + +Audit question: Is backup consistent, incremental, immutable, and restore-tested? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.38 `gc` + +Audit question: How are old snapshots, orphan objects, tombstones, and indexes reclaimed safely? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.39 `security` + +Audit question: Are authentication, authorization, encryption, audit, and tenant isolation in scope? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +### 4.40 `operations` + +Audit question: What compaction, upgrade, repair, verification, and capacity procedures exist? + +Current assessment: No universal public answer; obtain code evidence, trace evidence, or mark Unknown. + +Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved. + +zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible. + +## 5. Benchmark contract for this engine + +Every case runs correctness first, then isolated latency, then closed-loop concurrency, then open-loop overload. Report median, p95, p99, p99.9, timeout/rejection rate, throughput, CPU-seconds, peak RSS, cache bytes, disk bytes, network bytes, remote requests, write amplification, and estimated monthly cost. + +Warm means all intended engine caches are populated without changing the query parameters. Hot means the exact working set is resident. Cold means process-local, engine, OS, NVMe, and remote cache state are explicitly reset or a fresh namespace is used. Those words are never inferred from repetition count. + +### 5.1 `point_pk` — primary-key node lookup with one projected property + +- Applicability to Ultipa Powerhouse: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.2 `point_edge` — stable edge-ID lookup including endpoints and one property + +- Applicability to Ultipa Powerhouse: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.3 `degree_1` — degree-one outgoing expansion + +- Applicability to Ultipa Powerhouse: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.4 `degree_32` — small adjacency expansion around degree 32 + +- Applicability to Ultipa Powerhouse: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.5 `degree_1k` — medium adjacency expansion around degree 1,024 + +- Applicability to Ultipa Powerhouse: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.6 `supernode` — range-limited expansion of a ten-million-degree supernode + +- Applicability to Ultipa Powerhouse: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.7 `expand_2` — selective two-hop expansion + +- Applicability to Ultipa Powerhouse: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.8 `expand_3` — three-hop frontier expansion with duplicate control + +- Applicability to Ultipa Powerhouse: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.9 `expand_into` — edge-existence/expand-into between already-bound endpoints + +- Applicability to Ultipa Powerhouse: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.10 `multi_edge` — parallel-edge identity and property projection + +- Applicability to Ultipa Powerhouse: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.11 `shortest` — bidirectional point-to-point unweighted shortest path + +- Applicability to Ultipa Powerhouse: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.12 `weighted` — weighted shortest path with property access + +- Applicability to Ultipa Powerhouse: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.13 `var_walk` — bounded variable-length walk + +- Applicability to Ultipa Powerhouse: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.14 `trail` — DIFFERENT EDGES trail enumeration + +- Applicability to Ultipa Powerhouse: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.15 `simple` — simple-path enumeration with explicit bound + +- Applicability to Ultipa Powerhouse: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.16 `triangle` — triangle pattern with worst-case-sensitive join + +- Applicability to Ultipa Powerhouse: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.17 `cycle4` — four-cycle pattern + +- Applicability to Ultipa Powerhouse: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.18 `star_join` — high-fanout star pattern with property filters + +- Applicability to Ultipa Powerhouse: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.19 `optional` — optional match preserving null/bag semantics + +- Applicability to Ultipa Powerhouse: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.20 `aggregate` — grouped aggregate after traversal + +- Applicability to Ultipa Powerhouse: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.21 `topk` — ordered top-k with late property materialization + +- Applicability to Ultipa Powerhouse: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.22 `scan` — full projected property scan + +- Applicability to Ultipa Powerhouse: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.23 `selective_scan` — zone/index-pruned selective property scan + +- Applicability to Ultipa Powerhouse: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.24 `mixed` — concurrent short reads, complex reads, and updates + +- Applicability to Ultipa Powerhouse: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.25 `ingest` — sustained transactional ingest with indexes enabled + +- Applicability to Ultipa Powerhouse: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.26 `bulk` — initial bulk load including index/CSR build + +- Applicability to Ultipa Powerhouse: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.27 `checkpoint` — checkpoint or compaction while readers remain active + +- Applicability to Ultipa Powerhouse: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.28 `recovery` — crash recovery at bounded dirty-log size + +- Applicability to Ultipa Powerhouse: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.29 `cold` — same query after clearing engine and OS/cache tiers + +- Applicability to Ultipa Powerhouse: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +### 5.30 `remote` — same query with authoritative bytes only in object storage + +- Applicability to Ultipa Powerhouse: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout. +- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch. +- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation. +- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured. +- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes. +- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress. +- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match. + +## 6. Fairness controls + +- Same logical dataset and update stream; engine-native physical layouts are allowed and disclosed. +- Same result semantics; unsupported queries remain unsupported rather than rewritten into easier questions. +- Same durable acknowledgement class for write comparisons. +- Same number of physical cores and memory limit for self-hosted single-node tests. +- Same aggregate resources and replication fault tolerance for distributed tests. +- Officially recommended tuning may be applied before the freeze and is committed with rationale. +- Query-specific hints are allowed only when equivalent hints are offered to every engine and separately charted. +- Load/build/index time and bytes are first-class results. +- Cold, warm, and hot results are separate charts. +- Managed services use public configurations and cannot borrow hidden same-machine resource claims. +- Failed runs, OOMs, correctness mismatches, and timeouts stay in the dataset. +- Every chart links raw samples and the exact reproduction command. + +## 7. Likely advantages and limits + +The strongest known reason to choose this engine is tied to its family `hybrid distributed and high-density graph system`, its execution path `name-server planning; shard execution; HDC servers for deep algorithms and queries`, and its existing ecosystem. The strongest reason to reject it for zu's target is the gap between `not presented as S3-native live storage` and an S3-authoritative, request-budgeted, PB-scale graph service. + +Capacity statement: billions of nodes; no public PB proof. This is not converted into an edge-count claim without a physical byte model including IDs, both adjacency directions, properties, indexes, MVCC, WAL, replicas, and free space. + +Commercial statement: commercial proprietary. License cost, support cost, and unavailable enterprise capabilities remain visible in TCO and feature tables. + +## 8. Concrete lessons for zu + +1. Keep stable logical node and edge identity independent of row group, CSR slot, shard, and object range. +2. Store forward and reverse adjacency as immutable range-addressable tiles carrying edge IDs. +3. Feed queries adjacency batches and typed vectors; prohibit one storage call per logical element. +4. Use vectorized/factorized execution for property-heavy patterns and dedicated frontier operators for recursion. +5. Cost topology, properties, network, cache certainty, remote requests, and result materialization together. +6. Separate the local embedded profile from the object-authoritative distributed read profile. +7. Fence writers with monotonic epochs and make ambiguous commits reconcilable by transaction ID. +8. Pack small graph tiles into large immutable objects while retaining independent checksums and range offsets. +9. Keep the hot topology working set in RAM/NVMe; batch cold frontier misses into few remote rounds. +10. Admission-control remote requests and bytes so fixed-price plans have an enforceable upper bound. +11. Partition by workload-aware graph locality, and expose cross-partition semantics rather than hiding them. +12. Publish qualified wins per workload cell; never promise a universal tenfold advantage. + +## 9. Evidence gaps to close before publication + +- Exact current version and release date. +- Exact license text for the benchmarked artifact. +- Storage bytes per node/edge/property on all standard datasets. +- Stable-edge-ID and parallel-edge semantics. +- Isolation litmus results and commit acknowledgement point. +- Crash recovery time versus dirty WAL size. +- Supernode behavior and maximum tested degree. +- Cold-start metadata and request count. +- Distributed cross-partition query amplification. +- Peak memory under skew, cancellation, and overload. +- Background compaction/GC effect on tail latency. +- Full load/index/checkpoint/backup resource cost. +- Reproducible largest-scale result. +- Independent or audited benchmark evidence. + +## 10. Primary and official sources + +- [Powerhouse architecture](https://www.ultipa.com/docs/v5.3/graph-database) +- [GQL introduction](https://www.ultipa.com/docs/v5/gql) +- [GQL conformance](https://www.ultipa.com/docs/gql/gql-conformance) +- [LDBC SNB Interactive and audited disclosures](https://ldbcouncil.org/benchmarks/snb/interactive/) +- [LDBC Graphalytics](https://ldbcouncil.org/benchmarks/graphalytics/) +- [SoK: The Faults in our Graph Benchmarks](https://arxiv.org/abs/2404.00766) + +## 11. Source-handling rules + +- Official documentation and source are evidence for implemented or declared behavior, not independent performance. +- A vendor benchmark is labeled vendor claim until the harness reproduces it. +- A peer-reviewed paper establishes only the version, configuration, and workload it evaluated. +- Search snippets, comparison sites, and unsourced blogs are discovery aids, not final evidence. +- Unknown is a valid result and creates a concrete experiment or source-inspection task. +- All web facts are rechecked at benchmark freeze because this corpus is current only through the research date. + +## 12. Reproduction record template + +- engine: `Ultipa Powerhouse` +- version: `TBD at benchmark freeze` +- artifact digest: `TBD` +- source commit: `TBD or managed-service N/A` +- edition/license: `TBD` +- query language/version: `TBD` +- storage and durability mode: `TBD` +- cluster and replication: `TBD` +- CPU/RAM/NVMe/network: `TBD` +- OS/kernel/filesystem: `TBD` +- dataset URI and digest: `TBD` +- loader command and duration: `TBD` +- physical bytes by category: `TBD` +- tuning file: `TBD` +- query corpus commit: `TBD` +- raw result URI/digest: `TBD` +- profiler/trace URI: `TBD` +- correctness status: `TBD` +- reviewer and rerun date: `TBD` diff --git a/docs/research/system-benchmark-and-10x-claim.md b/docs/research/system-benchmark-and-10x-claim.md new file mode 100644 index 0000000..beb188c --- /dev/null +++ b/docs/research/system-benchmark-and-10x-claim.md @@ -0,0 +1,520 @@ +# Benchmark and proof plan for a defensible tenfold advantage + +Research cut: `2026-08-08` +Status: qualification protocol; no tenfold result is claimed yet. + +## 1. Claim grammar + +Allowed: `zu 0.x at commit X was 12.4x faster in p99 latency than LadybugDB Y for query Q on dataset D, hot-cache, 16 cores, equal result semantics, with peak RSS within Z, 95% bootstrap CI [a,b]`. + +Forbidden: `zu is 10x faster than all graph databases`. + +A competitor can win a different cell. The public scorecard reports latency, throughput, memory, physical bytes, build time, recovery, and dollars rather than selecting whichever metric favors zu. + +## 2. Competitor tiers + +- Tier A same-machine source builds: LadybugDB, Kuzu historical, FalkorDB, Memgraph, Neo4j Community, DuckPGQ, Apache AGE, Oxigraph, Jena TDB2, ArcadeDB, CozoDB, HelixDB. +- Tier B self-hosted distributed: Neo4j Enterprise/Infinigraph when licensed, NebulaGraph, TigerGraph, GraphScope Flex, JanusGraph+Cassandra/Scylla, HugeGraph HStore, Dgraph, ArangoDB, TuGraph Enterprise when available. +- Tier C managed: Neptune Database, Neptune Analytics, Spanner Graph, Cosmos Gremlin, Fabric Graph, PuppyGraph deployment, commercial semantic systems. +- Tier D historical/research: RedisGraph, Blazegraph, MillenniumDB, Kuzu archived. + +## 3. Datasets + +- LDBC SNB Interactive v1 at SF1/10/30/100/300/1000 as resources permit. +- LDBC SNB BI for scan, join, aggregation, and path-heavy analytics. +- Graphalytics canonical datasets and six algorithms with official reference outputs. +- GAP Benchmark graphs for kernel comparison. +- LiveJournal and Friendster for common topology microbenchmarks. +- Uniform synthetic graph to expose cache-friendly best cases. +- power-law and smooth-Kronecker graphs with recorded generator seed. +- adversarial supernode graph. +- high parallel-edge and self-loop correctness graph. +- property-heavy graph with compressible and incompressible columns. +- partition-local graph at multiple edge-cut ratios. +- temporal update stream with hot-vertex skew. + +Every dataset has a URI, content digest, generator version/seed, exact node/edge counts including zero-degree nodes, ID ordering description, property distributions, connected-component statistics, degree quantiles, and expected-result digest. + +## 4. Scale ladder + +Run 10M, 100M, 1B, 10B, 100B, 1T edges. Beyond affordable physical runs, execute format/capacity validation with generated manifests and sampled partitions, but label it simulation. A PB claim requires at least one end-to-end remote namespace large enough to exercise sharded manifests, cache churn, GC, and repartitioning—not just multiplication from a 1-GB file. + +## 5. Hardware classes + +- Tiny: 4 cores, 8 GiB RAM, commodity SSD; tests resource efficiency and edge deployment. +- Standard: 16 physical cores, 64 GiB RAM, one enterprise NVMe. +- Memory: 32-64 cores, 512 GiB RAM for in-memory competitors. +- Distributed: identical nodes, 25/100-Gbit network, fixed aggregate CPU/RAM/NVMe. +- Remote: same-region S3 Standard and optional low-latency object tier, explicit cache nodes. + +Record firmware, CPU governor, SMT, turbo, NUMA, kernel, mitigations, filesystem, mount flags, container limits, background processes, and ambient network measurements. + +## 6. Measurement rules + +Use a coordinated-omission-safe load generator. Run correctness before timing. Warm up to a declared state. Randomize engine and query order. Preserve raw per-operation timestamps. Use independent process restarts for cold trials. Publish confidence intervals and effect sizes. Do not average ratios. Do not discard outliers without a pre-registered hardware-failure rule. + +Measure client-to-client latency, server service time, queue time, CPU time, cycles/instructions, context switches, page faults, RSS, allocator bytes, cache occupancy, local read/write bytes, network bytes, remote requests and bytes, retries, compaction, WAL, result bytes, and errors. + +## 7. Tenfold gates + +- Correctness gate: identical canonical results and supported semantics. +- Durability gate: equal acknowledgement level and fault tolerance. +- Resource gate: competitor and zu receive the same class limit; OOM is reported. +- Statistics gate: lower bound of the 95% confidence interval exceeds 10.0x. +- Repeatability gate: two independent operators reproduce within 10%. +- Transparency gate: configs, source patches, scripts, plans, and raw samples are public. +- Scope gate: title names the query, dataset, scale, cache state, hardware, and metric. + +## 8. Required workloads + +### 8.1 `point_pk` + +Workload: primary-key node lookup with one projected property. + +Variants: hot, warm, cold; one client and saturation; read-only and update interference; uniform and skewed parameters; small and large results. + +Outputs: correctness digest, p50/p95/p99/p99.9, throughput, CPU/query, peak RSS, bytes read, requests/query, physical bytes, and cost per million operations. + +Failure rule: an unsupported semantic feature is `unsupported`; timeout, OOM, wrong result, crash, and admission rejection are distinct outcomes. + +### 8.2 `point_edge` + +Workload: stable edge-ID lookup including endpoints and one property. + +Variants: hot, warm, cold; one client and saturation; read-only and update interference; uniform and skewed parameters; small and large results. + +Outputs: correctness digest, p50/p95/p99/p99.9, throughput, CPU/query, peak RSS, bytes read, requests/query, physical bytes, and cost per million operations. + +Failure rule: an unsupported semantic feature is `unsupported`; timeout, OOM, wrong result, crash, and admission rejection are distinct outcomes. + +### 8.3 `degree_1` + +Workload: degree-one outgoing expansion. + +Variants: hot, warm, cold; one client and saturation; read-only and update interference; uniform and skewed parameters; small and large results. + +Outputs: correctness digest, p50/p95/p99/p99.9, throughput, CPU/query, peak RSS, bytes read, requests/query, physical bytes, and cost per million operations. + +Failure rule: an unsupported semantic feature is `unsupported`; timeout, OOM, wrong result, crash, and admission rejection are distinct outcomes. + +### 8.4 `degree_32` + +Workload: small adjacency expansion around degree 32. + +Variants: hot, warm, cold; one client and saturation; read-only and update interference; uniform and skewed parameters; small and large results. + +Outputs: correctness digest, p50/p95/p99/p99.9, throughput, CPU/query, peak RSS, bytes read, requests/query, physical bytes, and cost per million operations. + +Failure rule: an unsupported semantic feature is `unsupported`; timeout, OOM, wrong result, crash, and admission rejection are distinct outcomes. + +### 8.5 `degree_1k` + +Workload: medium adjacency expansion around degree 1,024. + +Variants: hot, warm, cold; one client and saturation; read-only and update interference; uniform and skewed parameters; small and large results. + +Outputs: correctness digest, p50/p95/p99/p99.9, throughput, CPU/query, peak RSS, bytes read, requests/query, physical bytes, and cost per million operations. + +Failure rule: an unsupported semantic feature is `unsupported`; timeout, OOM, wrong result, crash, and admission rejection are distinct outcomes. + +### 8.6 `supernode` + +Workload: range-limited expansion of a ten-million-degree supernode. + +Variants: hot, warm, cold; one client and saturation; read-only and update interference; uniform and skewed parameters; small and large results. + +Outputs: correctness digest, p50/p95/p99/p99.9, throughput, CPU/query, peak RSS, bytes read, requests/query, physical bytes, and cost per million operations. + +Failure rule: an unsupported semantic feature is `unsupported`; timeout, OOM, wrong result, crash, and admission rejection are distinct outcomes. + +### 8.7 `expand_2` + +Workload: selective two-hop expansion. + +Variants: hot, warm, cold; one client and saturation; read-only and update interference; uniform and skewed parameters; small and large results. + +Outputs: correctness digest, p50/p95/p99/p99.9, throughput, CPU/query, peak RSS, bytes read, requests/query, physical bytes, and cost per million operations. + +Failure rule: an unsupported semantic feature is `unsupported`; timeout, OOM, wrong result, crash, and admission rejection are distinct outcomes. + +### 8.8 `expand_3` + +Workload: three-hop frontier expansion with duplicate control. + +Variants: hot, warm, cold; one client and saturation; read-only and update interference; uniform and skewed parameters; small and large results. + +Outputs: correctness digest, p50/p95/p99/p99.9, throughput, CPU/query, peak RSS, bytes read, requests/query, physical bytes, and cost per million operations. + +Failure rule: an unsupported semantic feature is `unsupported`; timeout, OOM, wrong result, crash, and admission rejection are distinct outcomes. + +### 8.9 `expand_into` + +Workload: edge-existence/expand-into between already-bound endpoints. + +Variants: hot, warm, cold; one client and saturation; read-only and update interference; uniform and skewed parameters; small and large results. + +Outputs: correctness digest, p50/p95/p99/p99.9, throughput, CPU/query, peak RSS, bytes read, requests/query, physical bytes, and cost per million operations. + +Failure rule: an unsupported semantic feature is `unsupported`; timeout, OOM, wrong result, crash, and admission rejection are distinct outcomes. + +### 8.10 `multi_edge` + +Workload: parallel-edge identity and property projection. + +Variants: hot, warm, cold; one client and saturation; read-only and update interference; uniform and skewed parameters; small and large results. + +Outputs: correctness digest, p50/p95/p99/p99.9, throughput, CPU/query, peak RSS, bytes read, requests/query, physical bytes, and cost per million operations. + +Failure rule: an unsupported semantic feature is `unsupported`; timeout, OOM, wrong result, crash, and admission rejection are distinct outcomes. + +### 8.11 `shortest` + +Workload: bidirectional point-to-point unweighted shortest path. + +Variants: hot, warm, cold; one client and saturation; read-only and update interference; uniform and skewed parameters; small and large results. + +Outputs: correctness digest, p50/p95/p99/p99.9, throughput, CPU/query, peak RSS, bytes read, requests/query, physical bytes, and cost per million operations. + +Failure rule: an unsupported semantic feature is `unsupported`; timeout, OOM, wrong result, crash, and admission rejection are distinct outcomes. + +### 8.12 `weighted` + +Workload: weighted shortest path with property access. + +Variants: hot, warm, cold; one client and saturation; read-only and update interference; uniform and skewed parameters; small and large results. + +Outputs: correctness digest, p50/p95/p99/p99.9, throughput, CPU/query, peak RSS, bytes read, requests/query, physical bytes, and cost per million operations. + +Failure rule: an unsupported semantic feature is `unsupported`; timeout, OOM, wrong result, crash, and admission rejection are distinct outcomes. + +### 8.13 `var_walk` + +Workload: bounded variable-length walk. + +Variants: hot, warm, cold; one client and saturation; read-only and update interference; uniform and skewed parameters; small and large results. + +Outputs: correctness digest, p50/p95/p99/p99.9, throughput, CPU/query, peak RSS, bytes read, requests/query, physical bytes, and cost per million operations. + +Failure rule: an unsupported semantic feature is `unsupported`; timeout, OOM, wrong result, crash, and admission rejection are distinct outcomes. + +### 8.14 `trail` + +Workload: DIFFERENT EDGES trail enumeration. + +Variants: hot, warm, cold; one client and saturation; read-only and update interference; uniform and skewed parameters; small and large results. + +Outputs: correctness digest, p50/p95/p99/p99.9, throughput, CPU/query, peak RSS, bytes read, requests/query, physical bytes, and cost per million operations. + +Failure rule: an unsupported semantic feature is `unsupported`; timeout, OOM, wrong result, crash, and admission rejection are distinct outcomes. + +### 8.15 `simple` + +Workload: simple-path enumeration with explicit bound. + +Variants: hot, warm, cold; one client and saturation; read-only and update interference; uniform and skewed parameters; small and large results. + +Outputs: correctness digest, p50/p95/p99/p99.9, throughput, CPU/query, peak RSS, bytes read, requests/query, physical bytes, and cost per million operations. + +Failure rule: an unsupported semantic feature is `unsupported`; timeout, OOM, wrong result, crash, and admission rejection are distinct outcomes. + +### 8.16 `triangle` + +Workload: triangle pattern with worst-case-sensitive join. + +Variants: hot, warm, cold; one client and saturation; read-only and update interference; uniform and skewed parameters; small and large results. + +Outputs: correctness digest, p50/p95/p99/p99.9, throughput, CPU/query, peak RSS, bytes read, requests/query, physical bytes, and cost per million operations. + +Failure rule: an unsupported semantic feature is `unsupported`; timeout, OOM, wrong result, crash, and admission rejection are distinct outcomes. + +### 8.17 `cycle4` + +Workload: four-cycle pattern. + +Variants: hot, warm, cold; one client and saturation; read-only and update interference; uniform and skewed parameters; small and large results. + +Outputs: correctness digest, p50/p95/p99/p99.9, throughput, CPU/query, peak RSS, bytes read, requests/query, physical bytes, and cost per million operations. + +Failure rule: an unsupported semantic feature is `unsupported`; timeout, OOM, wrong result, crash, and admission rejection are distinct outcomes. + +### 8.18 `star_join` + +Workload: high-fanout star pattern with property filters. + +Variants: hot, warm, cold; one client and saturation; read-only and update interference; uniform and skewed parameters; small and large results. + +Outputs: correctness digest, p50/p95/p99/p99.9, throughput, CPU/query, peak RSS, bytes read, requests/query, physical bytes, and cost per million operations. + +Failure rule: an unsupported semantic feature is `unsupported`; timeout, OOM, wrong result, crash, and admission rejection are distinct outcomes. + +### 8.19 `optional` + +Workload: optional match preserving null/bag semantics. + +Variants: hot, warm, cold; one client and saturation; read-only and update interference; uniform and skewed parameters; small and large results. + +Outputs: correctness digest, p50/p95/p99/p99.9, throughput, CPU/query, peak RSS, bytes read, requests/query, physical bytes, and cost per million operations. + +Failure rule: an unsupported semantic feature is `unsupported`; timeout, OOM, wrong result, crash, and admission rejection are distinct outcomes. + +### 8.20 `aggregate` + +Workload: grouped aggregate after traversal. + +Variants: hot, warm, cold; one client and saturation; read-only and update interference; uniform and skewed parameters; small and large results. + +Outputs: correctness digest, p50/p95/p99/p99.9, throughput, CPU/query, peak RSS, bytes read, requests/query, physical bytes, and cost per million operations. + +Failure rule: an unsupported semantic feature is `unsupported`; timeout, OOM, wrong result, crash, and admission rejection are distinct outcomes. + +### 8.21 `topk` + +Workload: ordered top-k with late property materialization. + +Variants: hot, warm, cold; one client and saturation; read-only and update interference; uniform and skewed parameters; small and large results. + +Outputs: correctness digest, p50/p95/p99/p99.9, throughput, CPU/query, peak RSS, bytes read, requests/query, physical bytes, and cost per million operations. + +Failure rule: an unsupported semantic feature is `unsupported`; timeout, OOM, wrong result, crash, and admission rejection are distinct outcomes. + +### 8.22 `scan` + +Workload: full projected property scan. + +Variants: hot, warm, cold; one client and saturation; read-only and update interference; uniform and skewed parameters; small and large results. + +Outputs: correctness digest, p50/p95/p99/p99.9, throughput, CPU/query, peak RSS, bytes read, requests/query, physical bytes, and cost per million operations. + +Failure rule: an unsupported semantic feature is `unsupported`; timeout, OOM, wrong result, crash, and admission rejection are distinct outcomes. + +### 8.23 `selective_scan` + +Workload: zone/index-pruned selective property scan. + +Variants: hot, warm, cold; one client and saturation; read-only and update interference; uniform and skewed parameters; small and large results. + +Outputs: correctness digest, p50/p95/p99/p99.9, throughput, CPU/query, peak RSS, bytes read, requests/query, physical bytes, and cost per million operations. + +Failure rule: an unsupported semantic feature is `unsupported`; timeout, OOM, wrong result, crash, and admission rejection are distinct outcomes. + +### 8.24 `mixed` + +Workload: concurrent short reads, complex reads, and updates. + +Variants: hot, warm, cold; one client and saturation; read-only and update interference; uniform and skewed parameters; small and large results. + +Outputs: correctness digest, p50/p95/p99/p99.9, throughput, CPU/query, peak RSS, bytes read, requests/query, physical bytes, and cost per million operations. + +Failure rule: an unsupported semantic feature is `unsupported`; timeout, OOM, wrong result, crash, and admission rejection are distinct outcomes. + +### 8.25 `ingest` + +Workload: sustained transactional ingest with indexes enabled. + +Variants: hot, warm, cold; one client and saturation; read-only and update interference; uniform and skewed parameters; small and large results. + +Outputs: correctness digest, p50/p95/p99/p99.9, throughput, CPU/query, peak RSS, bytes read, requests/query, physical bytes, and cost per million operations. + +Failure rule: an unsupported semantic feature is `unsupported`; timeout, OOM, wrong result, crash, and admission rejection are distinct outcomes. + +### 8.26 `bulk` + +Workload: initial bulk load including index/CSR build. + +Variants: hot, warm, cold; one client and saturation; read-only and update interference; uniform and skewed parameters; small and large results. + +Outputs: correctness digest, p50/p95/p99/p99.9, throughput, CPU/query, peak RSS, bytes read, requests/query, physical bytes, and cost per million operations. + +Failure rule: an unsupported semantic feature is `unsupported`; timeout, OOM, wrong result, crash, and admission rejection are distinct outcomes. + +### 8.27 `checkpoint` + +Workload: checkpoint or compaction while readers remain active. + +Variants: hot, warm, cold; one client and saturation; read-only and update interference; uniform and skewed parameters; small and large results. + +Outputs: correctness digest, p50/p95/p99/p99.9, throughput, CPU/query, peak RSS, bytes read, requests/query, physical bytes, and cost per million operations. + +Failure rule: an unsupported semantic feature is `unsupported`; timeout, OOM, wrong result, crash, and admission rejection are distinct outcomes. + +### 8.28 `recovery` + +Workload: crash recovery at bounded dirty-log size. + +Variants: hot, warm, cold; one client and saturation; read-only and update interference; uniform and skewed parameters; small and large results. + +Outputs: correctness digest, p50/p95/p99/p99.9, throughput, CPU/query, peak RSS, bytes read, requests/query, physical bytes, and cost per million operations. + +Failure rule: an unsupported semantic feature is `unsupported`; timeout, OOM, wrong result, crash, and admission rejection are distinct outcomes. + +### 8.29 `cold` + +Workload: same query after clearing engine and OS/cache tiers. + +Variants: hot, warm, cold; one client and saturation; read-only and update interference; uniform and skewed parameters; small and large results. + +Outputs: correctness digest, p50/p95/p99/p99.9, throughput, CPU/query, peak RSS, bytes read, requests/query, physical bytes, and cost per million operations. + +Failure rule: an unsupported semantic feature is `unsupported`; timeout, OOM, wrong result, crash, and admission rejection are distinct outcomes. + +### 8.30 `remote` + +Workload: same query with authoritative bytes only in object storage. + +Variants: hot, warm, cold; one client and saturation; read-only and update interference; uniform and skewed parameters; small and large results. + +Outputs: correctness digest, p50/p95/p99/p99.9, throughput, CPU/query, peak RSS, bytes read, requests/query, physical bytes, and cost per million operations. + +Failure rule: an unsupported semantic feature is `unsupported`; timeout, OOM, wrong result, crash, and admission rejection are distinct outcomes. + +## 9. S3-specific experiments + +- Empty-cache first query at 1M, 1B, and multi-partition namespaces. +- One-hop and three-hop request count versus frontier size. +- Coalescing tradeoff curve: extra bytes versus saved requests. +- Cache hit bytes and hit operations separately. +- Cache loss storm with admission enabled. +- Tenfold QPS spike under fixed monthly envelope. +- SlowDown/429/503 injection and retry budget. +- Range corruption, truncation, wrong-content, and stale-manifest injection. +- Writer lease expiry and stale writer acknowledgement attempt. +- Lost response at every commit phase. +- GC race with publication, long reader pins, backups, and repartitioning. +- Cross-region and cross-zone traffic accounting. + +## 10. Cost model + +Monthly cost equals compute reservations plus ephemeral/NVMe cache plus object stored bytes plus PUT/COPY/LIST/GET/HEAD requests plus retrieval plus cross-zone and egress bytes plus metadata/control-plane services plus license/support. Every term names provider, region, price sheet date, and free-tier assumptions. + +Fixed-price qualification replays the worst admitted workload for the plan and proves cost stays within reserve. A higher offered load may be rejected; the rejection is part of the contract and chart. + +## 11. Publication artifacts + +- Immutable harness repository commit. +- Engine adapters with license-safe patches. +- Container and binary digests. +- Datasets and expected-result digests. +- All configuration files. +- Commands and orchestration logs. +- Raw samples in an open columnar format. +- Plans, profiles, and traces. +- System telemetry. +- Analysis notebook or script. +- Failure and exclusion ledger. +- Signed result manifest. +- Independent reproduction report. + +## 12. Competitive strategy + +Target tenfold wins where architecture creates a structural advantage: compressed local adjacency, factorized property-heavy patterns, resource-bounded embedded operation, fast open/recovery, storage density, S3 request count, stateless read scaling, and total cost for cold large datasets. Target parity and compatibility where ecosystems dominate. Do not spend credibility trying to beat in-memory engines on all-hot algorithms with an S3 cold path. + +## 13. Stop conditions + +Do not publish if results depend on unequal durability, missing output materialization, hand-selected query parameters, hidden enterprise features, unreported wrong answers, disabled constraints, different datasets, cache-state ambiguity, a single run, or a competitor configuration rejected by its maintainers as unreasonable. + +## 14. Sources + +- [LDBC SNB Interactive](https://ldbcouncil.org/benchmarks/snb/interactive/) +- [LDBC Graphalytics](https://ldbcouncil.org/benchmarks/graphalytics/) +- [LDBC datasets](https://ldbcouncil.org/benchmarks/snb/datasets/) +- [SoK: The Faults in our Graph Benchmarks](https://arxiv.org/abs/2404.00766) + +## Appendix A. Release-gate assertions + +- RG-001: For the benchmark publication, release is blocked until the raw samples and aggregated chart agree. +- RG-002: For the benchmark publication, release is blocked until the query result matches the canonical oracle. +- RG-003: For the benchmark publication, release is blocked until the engine version and artifact digest are recorded. +- RG-004: For the benchmark publication, release is blocked until the selected durability level matches the comparison class. +- RG-005: For the benchmark publication, release is blocked until cache state is explicit and reproducible. +- RG-006: For the benchmark publication, release is blocked until peak memory includes engine and required sidecars. +- RG-007: For the benchmark publication, release is blocked until storage size includes indexes, logs, replicas, and temporary space. +- RG-008: For the benchmark publication, release is blocked until timeouts and rejected operations remain in the result set. +- RG-009: For the benchmark publication, release is blocked until remote requests and bytes are measured rather than estimated. +- RG-010: For the benchmark publication, release is blocked until background maintenance is either quiesced or reported. +- RG-011: For the benchmark publication, release is blocked until thread, NUMA, and CPU-affinity settings are captured. +- RG-012: For the benchmark publication, release is blocked until the dataset and update-stream digests are immutable. +- RG-013: For the benchmark publication, release is blocked until the query plan/profile is archived. +- RG-014: For the benchmark publication, release is blocked until unsupported features are not replaced by weaker semantics. +- RG-015: For the benchmark publication, release is blocked until a second operator can reproduce the run from a clean host. +- RG-016: For the benchmark publication, release is blocked until the raw samples and aggregated chart agree. +- RG-017: For the benchmark publication, release is blocked until the query result matches the canonical oracle. +- RG-018: For the benchmark publication, release is blocked until the engine version and artifact digest are recorded. +- RG-019: For the benchmark publication, release is blocked until the selected durability level matches the comparison class. +- RG-020: For the benchmark publication, release is blocked until cache state is explicit and reproducible. +- RG-021: For the benchmark publication, release is blocked until peak memory includes engine and required sidecars. +- RG-022: For the benchmark publication, release is blocked until storage size includes indexes, logs, replicas, and temporary space. +- RG-023: For the benchmark publication, release is blocked until timeouts and rejected operations remain in the result set. +- RG-024: For the benchmark publication, release is blocked until remote requests and bytes are measured rather than estimated. +- RG-025: For the benchmark publication, release is blocked until background maintenance is either quiesced or reported. +- RG-026: For the benchmark publication, release is blocked until thread, NUMA, and CPU-affinity settings are captured. +- RG-027: For the benchmark publication, release is blocked until the dataset and update-stream digests are immutable. +- RG-028: For the benchmark publication, release is blocked until the query plan/profile is archived. +- RG-029: For the benchmark publication, release is blocked until unsupported features are not replaced by weaker semantics. +- RG-030: For the benchmark publication, release is blocked until a second operator can reproduce the run from a clean host. +- RG-031: For the benchmark publication, release is blocked until the raw samples and aggregated chart agree. +- RG-032: For the benchmark publication, release is blocked until the query result matches the canonical oracle. +- RG-033: For the benchmark publication, release is blocked until the engine version and artifact digest are recorded. +- RG-034: For the benchmark publication, release is blocked until the selected durability level matches the comparison class. +- RG-035: For the benchmark publication, release is blocked until cache state is explicit and reproducible. +- RG-036: For the benchmark publication, release is blocked until peak memory includes engine and required sidecars. +- RG-037: For the benchmark publication, release is blocked until storage size includes indexes, logs, replicas, and temporary space. +- RG-038: For the benchmark publication, release is blocked until timeouts and rejected operations remain in the result set. +- RG-039: For the benchmark publication, release is blocked until remote requests and bytes are measured rather than estimated. +- RG-040: For the benchmark publication, release is blocked until background maintenance is either quiesced or reported. +- RG-041: For the benchmark publication, release is blocked until thread, NUMA, and CPU-affinity settings are captured. +- RG-042: For the benchmark publication, release is blocked until the dataset and update-stream digests are immutable. +- RG-043: For the benchmark publication, release is blocked until the query plan/profile is archived. +- RG-044: For the benchmark publication, release is blocked until unsupported features are not replaced by weaker semantics. +- RG-045: For the benchmark publication, release is blocked until a second operator can reproduce the run from a clean host. +- RG-046: For the benchmark publication, release is blocked until the raw samples and aggregated chart agree. +- RG-047: For the benchmark publication, release is blocked until the query result matches the canonical oracle. +- RG-048: For the benchmark publication, release is blocked until the engine version and artifact digest are recorded. +- RG-049: For the benchmark publication, release is blocked until the selected durability level matches the comparison class. +- RG-050: For the benchmark publication, release is blocked until cache state is explicit and reproducible. +- RG-051: For the benchmark publication, release is blocked until peak memory includes engine and required sidecars. +- RG-052: For the benchmark publication, release is blocked until storage size includes indexes, logs, replicas, and temporary space. +- RG-053: For the benchmark publication, release is blocked until timeouts and rejected operations remain in the result set. +- RG-054: For the benchmark publication, release is blocked until remote requests and bytes are measured rather than estimated. +- RG-055: For the benchmark publication, release is blocked until background maintenance is either quiesced or reported. +- RG-056: For the benchmark publication, release is blocked until thread, NUMA, and CPU-affinity settings are captured. +- RG-057: For the benchmark publication, release is blocked until the dataset and update-stream digests are immutable. +- RG-058: For the benchmark publication, release is blocked until the query plan/profile is archived. +- RG-059: For the benchmark publication, release is blocked until unsupported features are not replaced by weaker semantics. +- RG-060: For the benchmark publication, release is blocked until a second operator can reproduce the run from a clean host. +- RG-061: For the benchmark publication, release is blocked until the raw samples and aggregated chart agree. +- RG-062: For the benchmark publication, release is blocked until the query result matches the canonical oracle. +- RG-063: For the benchmark publication, release is blocked until the engine version and artifact digest are recorded. +- RG-064: For the benchmark publication, release is blocked until the selected durability level matches the comparison class. +- RG-065: For the benchmark publication, release is blocked until cache state is explicit and reproducible. +- RG-066: For the benchmark publication, release is blocked until peak memory includes engine and required sidecars. +- RG-067: For the benchmark publication, release is blocked until storage size includes indexes, logs, replicas, and temporary space. +- RG-068: For the benchmark publication, release is blocked until timeouts and rejected operations remain in the result set. +- RG-069: For the benchmark publication, release is blocked until remote requests and bytes are measured rather than estimated. +- RG-070: For the benchmark publication, release is blocked until background maintenance is either quiesced or reported. +- RG-071: For the benchmark publication, release is blocked until thread, NUMA, and CPU-affinity settings are captured. +- RG-072: For the benchmark publication, release is blocked until the dataset and update-stream digests are immutable. +- RG-073: For the benchmark publication, release is blocked until the query plan/profile is archived. +- RG-074: For the benchmark publication, release is blocked until unsupported features are not replaced by weaker semantics. +- RG-075: For the benchmark publication, release is blocked until a second operator can reproduce the run from a clean host. +- RG-076: For the benchmark publication, release is blocked until the raw samples and aggregated chart agree. +- RG-077: For the benchmark publication, release is blocked until the query result matches the canonical oracle. +- RG-078: For the benchmark publication, release is blocked until the engine version and artifact digest are recorded. +- RG-079: For the benchmark publication, release is blocked until the selected durability level matches the comparison class. +- RG-080: For the benchmark publication, release is blocked until cache state is explicit and reproducible. +- RG-081: For the benchmark publication, release is blocked until peak memory includes engine and required sidecars. +- RG-082: For the benchmark publication, release is blocked until storage size includes indexes, logs, replicas, and temporary space. +- RG-083: For the benchmark publication, release is blocked until timeouts and rejected operations remain in the result set. +- RG-084: For the benchmark publication, release is blocked until remote requests and bytes are measured rather than estimated. +- RG-085: For the benchmark publication, release is blocked until background maintenance is either quiesced or reported. +- RG-086: For the benchmark publication, release is blocked until thread, NUMA, and CPU-affinity settings are captured. +- RG-087: For the benchmark publication, release is blocked until the dataset and update-stream digests are immutable. +- RG-088: For the benchmark publication, release is blocked until the query plan/profile is archived. +- RG-089: For the benchmark publication, release is blocked until unsupported features are not replaced by weaker semantics. +- RG-090: For the benchmark publication, release is blocked until a second operator can reproduce the run from a clean host. +- RG-091: For the benchmark publication, release is blocked until the raw samples and aggregated chart agree. +- RG-092: For the benchmark publication, release is blocked until the query result matches the canonical oracle. +- RG-093: For the benchmark publication, release is blocked until the engine version and artifact digest are recorded. +- RG-094: For the benchmark publication, release is blocked until the selected durability level matches the comparison class. +- RG-095: For the benchmark publication, release is blocked until cache state is explicit and reproducible. +- RG-096: For the benchmark publication, release is blocked until peak memory includes engine and required sidecars. +- RG-097: For the benchmark publication, release is blocked until storage size includes indexes, logs, replicas, and temporary space. diff --git a/docs/research/system-landscape-scorecard.md b/docs/research/system-landscape-scorecard.md new file mode 100644 index 0000000..8fa11d5 --- /dev/null +++ b/docs/research/system-landscape-scorecard.md @@ -0,0 +1,520 @@ +# 2026 graph-engine landscape scorecard + +Research cut: `2026-08-08` +Scores are directional engineering assessments, not measured benchmark results. + +## Scoring rule + +`strong` means public architecture clearly supports the dimension. `partial` means an adjacent capability exists with important constraints. `weak` means the architecture conflicts with the target. `unknown` means public evidence is insufficient. No numeric total is produced because weights depend on workload and unknowns are not zeros. + +## Engine summary + +### 1. Neo4j + +- Family: native property graph. +- Lifecycle confidence: strong — active; calendar-versioned 2026 line. +- Distributed-capacity alignment: strong — standalone, clustered, composite databases, and Infinigraph automatic sharding. +- S3-authoritative alignment: weak — not S3-native for the live query path; object storage is operational/backup infrastructure. +- Scale evidence: single-store formats have finite ID domains; Infinigraph is the 100-TB-plus horizontal path. +- Principal benchmark issue: industry baseline with LDBC and vendor workloads, but edition and runtime must be pinned. +- zu decision: The ecosystem and Cypher compatibility bar are formidable; storage cost, JVM footprint, and distributed-license cost are openings for zu. + +### 2. FalkorDB + +- Family: matrix property graph. +- Lifecycle confidence: strong — active; Rust transition and Redis-module lineage. +- Distributed-capacity alignment: strong — single node and commercial/cloud scale-out offerings; open core must be separated from service claims. +- S3-authoritative alignment: weak — not an object-store-native live engine. +- Scale evidence: excellent dense set-at-a-time traversal potential; PB evidence is not public. +- Principal benchmark issue: vendor benchmark suite exists; require pinned queries, data, hardware, and durability. +- zu decision: FalkorDB is the most direct sparse-linear-algebra competitor and a required point/traversal baseline. + +### 3. LadybugDB + +- Family: embedded analytical property graph. +- Lifecycle confidence: strong — active successor fork in 2026. +- Distributed-capacity alignment: strong — embedded single-node, in-process; no native distributed transaction layer. +- S3-authoritative alignment: weak — not object-store-native, though Parquet/Arrow/DuckDB interoperability is central. +- Scale evidence: large single-node analytical graphs; PB/distributed claims are outside the current product shape. +- Principal benchmark issue: must run Kuzu-derived LDBC and microbenchmarks from source with pinned commit. +- zu decision: This is zu's closest embedded architectural competitor and the primary fair same-machine benchmark. + +### 4. Kuzu (archived) + +- Family: embedded analytical property graph. +- Lifecycle confidence: weak — archived 2025-10-10; historical baseline. +- Distributed-capacity alignment: weak — embedded single-node. +- S3-authoritative alignment: weak — not object-store-native. +- Scale evidence: single-node only. +- Principal benchmark issue: Kuzu 0.9.0 is a reproducible historical baseline, not a current product. +- zu decision: Retain for regression and lineage attribution; do not present it as an active competitor. + +### 5. PuppyGraph + +- Family: lakehouse graph query engine. +- Lifecycle confidence: strong — active commercial product. +- Distributed-capacity alignment: partial — cluster deployment with independent compute over external data. +- S3-authoritative alignment: weak — directly relevant: queries data in lake/object-backed systems but is not simply an S3 adjacency store. +- Scale evidence: vendor claims petabyte data and deep traversal; independent audited evidence is required. +- Principal benchmark issue: benchmark must include source scan bytes, materialization, cache state, and warehouse cost. +- zu decision: PuppyGraph is the closest commercial graph-lake comparator for zu's remote profile. + +### 6. Memgraph + +- Family: in-memory operational property graph. +- Lifecycle confidence: strong — active. +- Distributed-capacity alignment: strong — leader/replica high availability and read scaling; not a general sharded PB store. +- S3-authoritative alignment: weak — not object-store-native. +- Scale evidence: RAM-bound mode targets low latency; on-disk mode broadens capacity with different behavior. +- Principal benchmark issue: benchmark every storage mode separately and include WAL/snapshot settings. +- zu decision: Memgraph is the low-latency mutable baseline; zu must win resource efficiency without comparing unlike durability modes. + +### 7. NebulaGraph + +- Family: distributed property graph. +- Lifecycle confidence: strong — active; Enterprise 5.2 was current in the 2025 review. +- Distributed-capacity alignment: strong — compute/storage separation, partition buckets, Raft groups, multi-cluster management. +- S3-authoritative alignment: weak — not S3-native in the query path. +- Scale evidence: vendor describes 200-TB clusters; PB qualification not established. +- Principal benchmark issue: separate open-source 3.x from Enterprise 5.x in every result. +- zu decision: Nebula is a major distributed/GQL comparator and a warning against hiding network traversal behind one latency number. + +### 8. TigerGraph + +- Family: distributed native property graph. +- Lifecycle confidence: strong — active; 4.2.4 released 2026-07-20. +- Distributed-capacity alignment: strong — automatic partitioning, MPP execution, leaderless replicated self-managed architecture; Savanna workspaces. +- S3-authoritative alignment: weak — Savanna is disaggregated but public docs do not establish an S3-range-native adjacency path. +- Scale evidence: public material cites hundreds of billions of edges; exact audited configurations matter. +- Principal benchmark issue: use LDBC disclosures and self-run compatible subsets; compiled-query warmup must be explicit. +- zu decision: TigerGraph sets the mature distributed analytics bar; zu's likely win is cost/resource efficiency and embedded simplicity, not every throughput regime. + +### 9. GraphScope Flex Interactive + +- Family: distributed interactive graph system. +- Lifecycle confidence: strong — active Apache-2.0 project. +- Distributed-capacity alignment: strong — distributed service with per-core shards and scale-out deployment. +- S3-authoritative alignment: weak — not object-store-native for interactive serving; GraphAr/lake integration is adjacent. +- Scale evidence: audited LDBC SNB at SF1000 and hundreds of billions of edges. +- Principal benchmark issue: audited LDBC results are the throughput credibility bar. +- zu decision: GraphScope is the strongest public audited throughput comparator and must not be reduced to a laptop microbenchmark. + +### 10. JanusGraph + +- Family: storage-agnostic distributed graph layer. +- Lifecycle confidence: strong — active 1.x. +- Distributed-capacity alignment: weak — horizontal scale through chosen backend and stateless-ish JanusGraph servers. +- S3-authoritative alignment: weak — possible indirectly through cloud backends, but not S3-native and pointer/request economics are unfavorable. +- Scale evidence: large distributed capacity is plausible through backends; supernodes and bulk load have documented limits. +- Principal benchmark issue: benchmark is a full stack: JanusGraph, backend, index service, consistency, and cache. +- zu decision: JanusGraph proves modular scale but also shows why a synchronous fine-grained storage SPI is a latency and operations trap. + +### 11. Apache HugeGraph + +- Family: pluggable OLTP plus OLAP graph platform. +- Lifecycle confidence: strong — active Apache top-level project. +- Distributed-capacity alignment: partial — PD plus HStore horizontal mode with HA. +- S3-authoritative alignment: weak — not S3-native live serving; external storage is an ingest/analytics concern. +- Scale evidence: official 2026 docs scope standalone below 4 TB and distributed below 1000 TB. +- Principal benchmark issue: run server/HStore and analytics components as separate systems. +- zu decision: HugeGraph's explicit 1000-TB envelope is highly relevant, but it reaches it with a distributed store rather than cheap object-only serving. + +### 12. TuGraph + +- Family: HTAP native property graph. +- Lifecycle confidence: strong — active. +- Distributed-capacity alignment: strong — community single-node/HA features and enterprise distributed architecture. +- S3-authoritative alignment: weak — not S3-native. +- Scale evidence: large production claims exist; PB public qualification is insufficient. +- Principal benchmark issue: use LDBC implementation disclosures and pin Community versus Enterprise. +- zu decision: TuGraph is a serious C++ HTAP comparator, particularly for local mutable traversal and compiled procedures. + +### 13. Ultipa Powerhouse + +- Family: hybrid distributed and high-density graph system. +- Lifecycle confidence: strong — active v5 line. +- Distributed-capacity alignment: strong — shard, name, meta, and HDC server roles. +- S3-authoritative alignment: weak — not presented as S3-native live storage. +- Scale evidence: billions of nodes; no public PB proof. +- Principal benchmark issue: GQL conformance can be tested; performance claims require independent harness. +- zu decision: Ultipa is important for its explicit two-mode design: economical sharded authority plus high-density acceleration. + +### 14. ArangoDB + +- Family: native multi-model database. +- Lifecycle confidence: strong — active. +- Distributed-capacity alignment: partial — CP master/master cluster with coordinators, DB-Servers, agency; SmartGraphs optimize locality. +- S3-authoritative alignment: weak — not S3-native live serving. +- Scale evidence: horizontal document/graph scale; efficient graph scale depends on sharding locality. +- Principal benchmark issue: Community General Graph and Enterprise SmartGraph are distinct baselines. +- zu decision: ArangoDB shows the benefit and cost of multi-model integration; SmartGraph locality is a mandatory partitioning comparison. + +### 15. Dgraph + +- Family: distributed predicate-sharded graph database. +- Lifecycle confidence: strong — active. +- Distributed-capacity alignment: strong — Zero control plane plus Alpha Raft groups; predicate sharding and rebalancing. +- S3-authoritative alignment: weak — not S3-native; backups may use object storage. +- Scale evidence: horizontal scale, but hot predicates and cross-group queries are key constraints. +- Principal benchmark issue: measure predicate skew, network fanout, Raft durability, and GraphQL translation separately. +- zu decision: Dgraph is the canonical predicate-sharding counterpoint to source-range adjacency partitioning. + +### 16. OrientDB + +- Family: multi-model graph/document database. +- Lifecycle confidence: weak — active 4.0 line but legacy architecture remains relevant. +- Distributed-capacity alignment: strong — Hazelcast-coordinated multi-master replication and class/cluster sharding. +- S3-authoritative alignment: weak — not S3-native. +- Scale evidence: distributed scale constrained by manual sharding/index limitations in documented designs. +- Principal benchmark issue: use as compatibility/resource baseline, not a PB front-runner. +- zu decision: OrientDB is valuable chiefly as a warning about physical identity, multi-master conflict handling, and application-directed sharding. + +### 17. ArcadeDB + +- Family: multi-model native graph database. +- Lifecycle confidence: strong — active 26.x. +- Distributed-capacity alignment: strong — leader/replica Raft HA scales reads and availability, not sharded capacity. +- S3-authoritative alignment: weak — not S3-native. +- Scale evidence: single-database capacity plus replicated copies; no PB claim. +- Principal benchmark issue: benchmark embedded and server modes; disclose protocol translation. +- zu decision: ArcadeDB is a strong low-resource JVM/multi-model comparison and a fast-moving 2026 target. + +### 18. TypeDB + +- Family: typed polymorphic database. +- Lifecycle confidence: strong — active 3.x; clustering was experimental/alpha in current docs. +- Distributed-capacity alignment: partial — Raft replicated leader/follower cluster; writes remain leader-bound; clustering status must be pinned. +- S3-authoritative alignment: weak — not S3-native. +- Scale evidence: read scale through replication, not data sharding; capacity remains full-copy bounded. +- Principal benchmark issue: semantic/inference workloads require a separate corpus from ordinary LPG traversal. +- zu decision: TypeDB competes on modeling correctness and inference, not PB topology economics; zu should borrow explicit schema invariants, not its full-copy scale model. + +### 19. TerminusDB + +- Family: version-controlled document graph database. +- Lifecycle confidence: strong — active. +- Distributed-capacity alignment: strong — federation/version exchange rather than transparent sharded query execution. +- S3-authoritative alignment: weak — immutable objects are conceptually compatible with object storage, but current serving is not documented as S3-native. +- Scale evidence: versioned knowledge graphs; not demonstrated at PB interactive topology scale. +- Principal benchmark issue: benchmark revision/diff/merge separately from traversal. +- zu decision: TerminusDB is the strongest lesson for immutable lineage, content addressing, and branchable metadata. + +### 20. CozoDB + +- Family: embedded relational-graph-vector database. +- Lifecycle confidence: strong — maintenance activity appears limited after late 2024; verify before adoption. +- Distributed-capacity alignment: strong — single-process/embedded; TiKV-era distributed options are not a simple turnkey cluster. +- S3-authoritative alignment: weak — not S3-native. +- Scale evidence: local and backend-dependent; no PB evidence. +- Principal benchmark issue: include recursive-query and algorithm microbenchmarks, but flag lifecycle risk. +- zu decision: CozoDB is a compact Datalog design reference; limited recent activity weakens it as a production comparator. + +### 21. SurrealDB + +- Family: distributed multi-model database. +- Lifecycle confidence: strong — active 3.x. +- Distributed-capacity alignment: weak — compute/storage separation; SurrealDS for multi-node Enterprise/Cloud. +- S3-authoritative alignment: partial — 2026 materials describe object-storage-based distributed storage, but public internals and cost evidence are incomplete. +- Scale evidence: distributed promises are significant; independent PB graph evidence absent. +- Principal benchmark issue: test native RELATE traversal separately from generic document links and cloud-only SurrealDS. +- zu decision: SurrealDB is a high-priority Rust/multi-model competitor and a useful check on zu's storage-query boundary. + +### 22. HelixDB + +- Family: Rust graph-vector database. +- Lifecycle confidence: strong — active and fast-moving; 3.0.2 listed in May 2026. +- Distributed-capacity alignment: strong — local server and commercial cloud; public distributed mechanics are incomplete. +- S3-authoritative alignment: partial — current marketing says built on object storage, making it directly relevant, but technical evidence is sparse. +- Scale evidence: early-stage; no credible PB proof. +- Principal benchmark issue: reproduce vendor claims and include compile/deploy, dynamic query, and durability behavior. +- zu decision: HelixDB is an emerging direct Rust/object-storage/GraphRAG competitor, but unknowns must be treated as unknowns. + +### 23. MillenniumDB + +- Family: research persistent graph database. +- Lifecycle confidence: strong — active research project with small community. +- Distributed-capacity alignment: weak — single-node. +- S3-authoritative alignment: weak — not S3-native. +- Scale evidence: research-scale, no PB serving claim. +- Principal benchmark issue: use for optimizer/index research comparisons, not product TCO claims. +- zu decision: MillenniumDB is a valuable research baseline for succinct indexes and path algorithms, though not a deployment peer. + +### 24. DuckPGQ + +- Family: analytical SQL/PGQ extension. +- Lifecycle confidence: strong — active CWI project. +- Distributed-capacity alignment: weak — embedded single-node. +- S3-authoritative alignment: weak — DuckDB can query object files, but DuckPGQ CSR construction is not an S3-native persistent graph index. +- Scale evidence: single-node analytics; CSR memory limits matter. +- Principal benchmark issue: include CSR-build time and memory, never report query-only numbers alone. +- zu decision: DuckPGQ is the fairest relational/SQL standards baseline and exposes the cost of rebuilding topology indexes. + +### 25. Apache AGE + +- Family: PostgreSQL graph extension. +- Lifecycle confidence: strong — active Apache project. +- Distributed-capacity alignment: strong — PostgreSQL HA options; AGE tables are not currently transparently distributed by Citus. +- S3-authoritative alignment: weak — not S3-native live serving. +- Scale evidence: PostgreSQL-node scale; no native PB graph sharding. +- Principal benchmark issue: compare both graph-only and hybrid SQL/Cypher, including join and JSON-property costs. +- zu decision: AGE is the strongest open PostgreSQL extension baseline; zu should win deep traversal and storage density while conceding ecosystem maturity. + +### 26. AgensGraph + +- Family: PostgreSQL-derived multi-model graph database. +- Lifecycle confidence: strong — active 2.17 documentation line. +- Distributed-capacity alignment: strong — active-standby HA; no native horizontally sharded property graph in public docs. +- S3-authoritative alignment: weak — not S3-native. +- Scale evidence: single-primary scale. +- Principal benchmark issue: hybrid-query correctness and optimizer quality are the main comparisons. +- zu decision: AgensGraph provides a mature SQL/Cypher hybrid baseline but is not a PB or object-storage competitor. + +### 27. Amazon Neptune Database + +- Family: managed cloud graph database. +- Lifecycle confidence: strong — active AWS service. +- Distributed-capacity alignment: partial — one writer, up to fifteen read replicas sharing storage; automatic 10-GiB segment growth. +- S3-authoritative alignment: weak — backups are on S3, but live database storage is a managed shared block service, not user-priced S3 objects. +- Scale evidence: 128-TiB cluster-volume maximum in most regions. +- Principal benchmark issue: managed-service comparison must include instance, I/O/storage mode, replicas, and network. +- zu decision: Neptune is a production durability/availability baseline but cannot satisfy a 1-PB single-graph target today. + +### 28. Amazon Neptune Analytics + +- Family: managed in-memory graph analytics. +- Lifecycle confidence: strong — active AWS service. +- Distributed-capacity alignment: weak — managed provisioned graph endpoint. +- S3-authoritative alignment: weak — S3 is an import/source path, not demand-paged live graph storage. +- Scale evidence: capacity bound by provisioned analytics graph sizes; not PB resident. +- Principal benchmark issue: charge load time, provisioned capacity, and algorithm duration. +- zu decision: Neptune Analytics is a strong hot analytical baseline but its economics fundamentally differ from S3-authoritative cold data. + +### 29. Google Cloud Spanner Graph + +- Family: managed relational-property-graph database. +- Lifecycle confidence: strong — active Enterprise/Enterprise Plus feature; docs updated 2026-07-22. +- Distributed-capacity alignment: strong — transparent sharding and managed scale-out. +- S3-authoritative alignment: weak — managed storage is not exposed as fixed-cost S3 object access. +- Scale evidence: algorithms documented for tens of billions of edges; no public PB proof. +- Principal benchmark issue: compare query and algorithm compute separately; include Spanner edition and processing units. +- zu decision: Spanner Graph is the standards and managed-consistency baseline; zu's opening is cost, portability, and graph-native density. + +### 30. Azure Cosmos DB for Apache Gremlin + +- Family: managed partitioned multi-model graph API. +- Lifecycle confidence: strong — active. +- Distributed-capacity alignment: strong — automatic partitioning by user-chosen key. +- S3-authoritative alignment: weak — managed cloud storage, not an S3-native portable engine. +- Scale evidence: large horizontal capacity; graph latency is sensitive to partition key and direction. +- Principal benchmark issue: report request units, partitions touched, throttling, and retry latency. +- zu decision: Cosmos is the clearest counterexample showing why edge direction and partition-key-aware planning are mandatory. + +### 31. Graph in Microsoft Fabric + +- Family: lakehouse graph analytics. +- Lifecycle confidence: strong — active 2026 feature. +- Distributed-capacity alignment: strong — managed scale-out within Fabric. +- S3-authoritative alignment: partial — directly lake/object aligned through OneLake, but materializes a queryable graph. +- Scale evidence: officially targets billions of relationships; PB evidence absent. +- Principal benchmark issue: include graph build/rebuild, capacity units, schema evolution, and cold/warm state. +- zu decision: Fabric Graph is a new direct lakehouse competitor and validates GQL plus read-optimized materialization over object-backed tables. + +### 32. Oracle Database Property Graph + +- Family: relational-integrated graph platform. +- Lifecycle confidence: strong — active Oracle Database 26ai line. +- Distributed-capacity alignment: weak — Oracle RAC/Exadata/cloud database scale plus separate graph server. +- S3-authoritative alignment: weak — object storage may feed/load data, not the primary low-latency graph index. +- Scale evidence: large enterprise scale but public PB interactive evidence is workload-specific. +- Principal benchmark issue: separate in-database query from PGX-loaded algorithm execution. +- zu decision: Oracle is the mature SQL/PGQ and enterprise-integration baseline; it also demonstrates the cost of maintaining an analytical graph projection. + +### 33. SAP HANA Cloud Property Graph Engine + +- Family: in-memory relational-integrated graph engine. +- Lifecycle confidence: strong — active QRC 1/2026. +- Distributed-capacity alignment: strong — HANA scale-up/scale-out deployment depending edition. +- S3-authoritative alignment: weak — not S3-native live serving. +- Scale evidence: enterprise analytical scale; no public PB graph evidence. +- Principal benchmark issue: measure graph workspace creation, memory footprint, and mixed SQL/graph execution. +- zu decision: HANA Graph is a strong in-memory integrated baseline, but resource cost is the likely zu differentiator. + +### 34. Stardog + +- Family: enterprise RDF knowledge graph platform. +- Lifecycle confidence: strong — active 12.x-era platform. +- Distributed-capacity alignment: partial — HA cluster and federated/virtual query capabilities. +- S3-authoritative alignment: weak — not S3-native adjacency serving; cloud deployment and backups may use object storage. +- Scale evidence: enterprise knowledge graphs; PB interactive claim not public. +- Principal benchmark issue: benchmark SPARQL, reasoning, virtualization, and materialized data separately. +- zu decision: Stardog is the enterprise semantic/federation baseline rather than a direct LPG traversal peer. + +### 35. Ontotext GraphDB + +- Family: RDF store and reasoner. +- Lifecycle confidence: strong — active 11.x. +- Distributed-capacity alignment: partial — Raft-based HA cluster in current Enterprise line. +- S3-authoritative alignment: weak — not S3-native live serving. +- Scale evidence: large RDF stores; audited LDBC SNB result exists but workload/language fit must be examined. +- Principal benchmark issue: include materialization time/space and inferred versus explicit query modes. +- zu decision: GraphDB is the principal materialized-reasoning baseline and a lesson in separating explicit from derived bytes. + +### 36. Apache Jena TDB2 + +- Family: embedded RDF store. +- Lifecycle confidence: strong — active Apache project. +- Distributed-capacity alignment: strong — single JVM; Fuseki provides network access, not distributed storage. +- S3-authoritative alignment: weak — not S3-native. +- Scale evidence: single-node and filesystem-bound. +- Principal benchmark issue: strong correctness/reference baseline for RDF, not PB latency competitor. +- zu decision: TDB2 is a valuable compact local-store reference for CoW MVCC, dictionary IDs, and tuple permutations. + +### 37. OpenLink Virtuoso + +- Family: multi-model SQL/RDF server. +- Lifecycle confidence: strong — active commercial/open-source lineage. +- Distributed-capacity alignment: partial — Enterprise cluster and replication options. +- S3-authoritative alignment: weak — not S3-native. +- Scale evidence: very large public RDF deployments, but PB interactive evidence is not current. +- Principal benchmark issue: use WatDiv/BSBM plus SQL/RDF hybrid cases and pin edition. +- zu decision: Virtuoso is the long-lived high-scale RDF/SQL baseline and a source of index-ordering lessons. + +### 38. Oxigraph + +- Family: embedded Rust RDF store. +- Lifecycle confidence: strong — active and explicitly still optimizing. +- Distributed-capacity alignment: weak — single-node library/server. +- S3-authoritative alignment: weak — not S3-native. +- Scale evidence: single-node; no PB proof. +- Principal benchmark issue: conformance and resource efficiency matter more than headline throughput. +- zu decision: Oxigraph is the closest Rust RDF implementation reference and a useful fuzz/conformance comparator. + +### 39. AllegroGraph + +- Family: commercial RDF/knowledge graph database. +- Lifecycle confidence: strong — active 9.x line. +- Distributed-capacity alignment: strong — warm-standby replication and distributed/federated features. +- S3-authoritative alignment: weak — not S3-native live serving. +- Scale evidence: large knowledge graphs; current PB evidence unavailable. +- Principal benchmark issue: benchmark RDF semantics, reasoning, vector, and replication independently. +- zu decision: AllegroGraph matters for semantic workloads and mature operational features, not as the primary LPG latency target. + +### 40. Blazegraph (legacy) + +- Family: RDF graph database. +- Lifecycle confidence: weak — archived repository; historical benchmark baseline. +- Distributed-capacity alignment: strong — historical HA/scale-out commercial features. +- S3-authoritative alignment: weak — not S3-native. +- Scale evidence: historically large Wikidata deployments; active-product status is unsuitable. +- Principal benchmark issue: retain for RDF regression only. +- zu decision: Blazegraph is historically important but must be labeled legacy to avoid a misleading 2026 comparison. + +### 41. RedisGraph (legacy) + +- Family: matrix property graph. +- Lifecycle confidence: strong — end-of-life lineage continued by FalkorDB. +- Distributed-capacity alignment: weak — Redis deployment topology. +- S3-authoritative alignment: weak — not S3-native. +- Scale evidence: memory-oriented single-shard baseline. +- Principal benchmark issue: use only to show lineage or reproduce old papers. +- zu decision: RedisGraph should not be counted as an active separate competitor; FalkorDB is the maintained comparison. + +### 42. Aerospike Graph + +- Family: stateless Gremlin compute over distributed KV storage. +- Lifecycle confidence: strong — active commercial product. +- Distributed-capacity alignment: strong — independently scalable stateless AGS compute over automatically sharded Aerospike Database. +- S3-authoritative alignment: weak — not S3-native; Aerospike's flash/storage engine remains authoritative. +- Scale evidence: official docs target billions of graph elements; no public PB proof. +- Principal benchmark issue: measure graph-service fanout and underlying Aerospike record operations, not only client latency. +- zu decision: Aerospike Graph is a major low-latency distributed Gremlin comparator and a close analogue to stateless graph compute over a non-graph storage service. + +### 43. Huawei Cloud Graph Engine Service (GES) + +- Family: managed distributed graph engine. +- Lifecycle confidence: strong — active; GQL added in 2025 and docs refreshed in 2026. +- Distributed-capacity alignment: strong — managed distributed cloud service. +- S3-authoritative alignment: weak — not documented as S3-native live serving. +- Scale evidence: official material claims tens of billions of vertices and hundreds of billions of edges. +- Principal benchmark issue: 2025 LDBC audited results are the current public throughput bar. +- zu decision: GES must be included because its audited SF100/SF300/SF1000 results lead the public LDBC table; zu cannot claim 'all competitors' while omitting it. + +### 44. DataStax Enterprise Graph + +- Family: Cassandra-integrated distributed graph. +- Lifecycle confidence: weak — maintained DSE 6.9 documentation; legacy strategic baseline rather than a modern standalone graph focus. +- Distributed-capacity alignment: partial — shared-nothing Cassandra distribution and replication. +- S3-authoritative alignment: weak — not S3-native. +- Scale evidence: DSE platform advertises petabyte data and graph billions, but graph-specific interactive proof must be separated. +- Principal benchmark issue: include Cassandra replication, consistency, Solr/Search, and Spark sidecars in resources. +- zu decision: DSE Graph is a historical PB-distributed reference and exposes the latency cost of building graph semantics on Cassandra-scale storage. + +### 45. IBM Db2 Graph + +- Family: Gremlin layer over Db2 relational data. +- Lifecycle confidence: weak — legacy/limited: current IBM page says standalone support is tied to Db2 11.5.6–11.5.8. +- Distributed-capacity alignment: strong — inherits Db2 deployment and read-scale features; graph layer is not native PB sharding. +- S3-authoritative alignment: weak — not S3-native. +- Scale evidence: Db2 platform scale; current graph lifecycle limits its competitive weight. +- Principal benchmark issue: retain as SQL/Gremlin compatibility baseline only if supported artifacts are obtainable. +- zu decision: Db2 Graph is included for completeness but labeled legacy so it cannot inflate current competitor coverage. + +## Structural winners by dimension + +- Embedded analytical execution: LadybugDB/Kuzu lineage and DuckPGQ. +- Sparse matrix traversal: FalkorDB. +- Hot mutable in-memory graph: Memgraph. +- Cypher ecosystem and mature operational database: Neo4j. +- Audited distributed throughput: GraphScope Flex and Huawei GES disclosures. +- Mature MPP graph analytics: TigerGraph. +- Distributed open graph stores: NebulaGraph, HugeGraph HStore, JanusGraph, Dgraph. +- Graph over lake/warehouse authority: PuppyGraph and Fabric Graph. +- Standards-integrated relational graph: Spanner Graph, Oracle SQL/PGQ, DuckPGQ. +- RDF reasoning and semantic operations: Stardog, GraphDB, Virtuoso, AllegroGraph. +- Immutable versioned graph: TerminusDB. +- Rust-native emerging graph/vector: HelixDB and SurrealDB; Rust RDF: Oxigraph. + +## White space + +No open system in this inventory conclusively combines immutable object-authoritative graph packs, stable logical edge identity, batched frontier range reads, vector/factorized GQL execution, enforced per-query request budgets, independently fenced partition writers, stateless horizontal readers, and FDR-quality cost benchmarks. That combination is zu's opportunity and its verification burden. + +## Architecture choices rejected + +- Remote KV call per adjacency entry. +- Reusing physical CSR slots as logical edge identity. +- Treating a manifest conditional write as a complete writer-fencing protocol. +- Claiming distributed ACID across independently published partition roots. +- Promising fixed cost from an assumed cache-hit rate. +- Benchmarking only query execution while excluding graph build/index time. +- Comparing hot in-memory execution with cold remote execution under one label. +- Claiming PB scale only by multiplying a compression ratio. +- Claiming universal 10x based on a selected latency microbenchmark. + +## Appendix A. Release-gate assertions + +- RG-001: For the landscape scorecard, release is blocked until the raw samples and aggregated chart agree. +- RG-002: For the landscape scorecard, release is blocked until the query result matches the canonical oracle. +- RG-003: For the landscape scorecard, release is blocked until the engine version and artifact digest are recorded. +- RG-004: For the landscape scorecard, release is blocked until the selected durability level matches the comparison class. +- RG-005: For the landscape scorecard, release is blocked until cache state is explicit and reproducible. +- RG-006: For the landscape scorecard, release is blocked until peak memory includes engine and required sidecars. +- RG-007: For the landscape scorecard, release is blocked until storage size includes indexes, logs, replicas, and temporary space. +- RG-008: For the landscape scorecard, release is blocked until timeouts and rejected operations remain in the result set. +- RG-009: For the landscape scorecard, release is blocked until remote requests and bytes are measured rather than estimated. +- RG-010: For the landscape scorecard, release is blocked until background maintenance is either quiesced or reported. +- RG-011: For the landscape scorecard, release is blocked until thread, NUMA, and CPU-affinity settings are captured. +- RG-012: For the landscape scorecard, release is blocked until the dataset and update-stream digests are immutable. +- RG-013: For the landscape scorecard, release is blocked until the query plan/profile is archived. +- RG-014: For the landscape scorecard, release is blocked until unsupported features are not replaced by weaker semantics. +- RG-015: For the landscape scorecard, release is blocked until a second operator can reproduce the run from a clean host. +- RG-016: For the landscape scorecard, release is blocked until the raw samples and aggregated chart agree. +- RG-017: For the landscape scorecard, release is blocked until the query result matches the canonical oracle. +- RG-018: For the landscape scorecard, release is blocked until the engine version and artifact digest are recorded. +- RG-019: For the landscape scorecard, release is blocked until the selected durability level matches the comparison class. +- RG-020: For the landscape scorecard, release is blocked until cache state is explicit and reproducible. +- RG-021: For the landscape scorecard, release is blocked until peak memory includes engine and required sidecars. +- RG-022: For the landscape scorecard, release is blocked until storage size includes indexes, logs, replicas, and temporary space. +- RG-023: For the landscape scorecard, release is blocked until timeouts and rejected operations remain in the result set. +- RG-024: For the landscape scorecard, release is blocked until remote requests and bytes are measured rather than estimated. +- RG-025: For the landscape scorecard, release is blocked until background maintenance is either quiesced or reported. +- RG-026: For the landscape scorecard, release is blocked until thread, NUMA, and CPU-affinity settings are captured. diff --git a/docs/research/system-target-architecture.md b/docs/research/system-target-architecture.md new file mode 100644 index 0000000..4b9b853 --- /dev/null +++ b/docs/research/system-target-architecture.md @@ -0,0 +1,520 @@ +# Proposed zu architecture for low latency, low resources, S3 authority, and PB scale + +Research cut: `2026-08-08` +Status: proposal and qualification plan, not a current performance claim. + +## 1. Outcome + +Build one semantic graph database with three execution profiles, not one magical deployment that pretends remote object storage behaves like RAM. The profiles share logical IDs, schema, query semantics, immutable segment envelopes, and conformance tests. They differ in persistence, writer coordination, cache/SLO class, and distributed guarantees. + +- `zu1-local`: one process writer broker, snapshot readers, local WAL plus immutable extents, sub-millisecond hot point/traversal target. +- `object-single`: one fenced writer per partition, immutable S3 packs, stateless readers with RAM/NVMe caches, bounded-staleness or strong-root reads. +- `object-partitioned`: many independently fenced partitions, workload-aware placement, read scale-out, and explicit restrictions on cross-partition writes. + +A future distributed-write profile requires a transactional metadata service and a clear atomic-edge placement protocol. It is not smuggled into v1 through optimistic manifest language. + +## 2. Non-negotiable mathematics + +At one trillion edges, every additional byte per stored directed projection consumes roughly one terabyte before replication, versions, indexes, or object overhead. Storing two adjacency directions means the edge budget is paid twice. A 16-byte neighbor-plus-edge reference is already about 32 TB for two directions at one trillion edges; a thousand trillion edges is three orders of magnitude larger and cannot be casually called one petabyte. + +Therefore `thousands of billions` must be expressed numerically. One thousand billion is one trillion. One million billion is one quadrillion. A 1-PB physical budget can hold only a bounded number of edges determined by topology bytes, properties, compression, indexes, history, and replication. The capacity calculator is a release artifact. + +## 3. Stable identity and partition map + +- Assign 128-bit logical NodeId and EdgeId values independent of location. +- Keep table/schema IDs stable and versioned. +- Treat row group, CSR slot, tile offset, pack range, and shard as locators. +- Store logical-to-physical mapping in immutable partition manifests and compact indices. +- Preserve parallel edges by carrying EdgeId in both adjacency directions. +- Order adjacency entries by neighbor ID then EdgeId for merge, search, and deterministic export. +- Give high-degree vertices continuation tiles addressed by logical key range. +- Version partition-map changes and pin the map in every SnapshotToken. + +## 4. Physical graph layout + +Each immutable partition generation contains a small root manifest, sharded metadata trees, adjacency directory tiles, adjacency data tiles, stable edge records, column tiles, primary-key indices, optional secondary indices, statistics, and tombstone/delta references. Packs combine many tiles to amortize PUT and GET overhead while preserving tile-level offsets and checksums. + +Adjacency directory tiles cover contiguous node-ID ranges and encode degree, first tile, continuation count, min/max neighbor, compressed byte length, and a high-degree exception pointer. Data tiles store neighbor deltas, EdgeId deltas or local dictionaries, optional hot projected properties, validity/version information, and a checksum over exactly the independently fetched bytes. + +Do not place update slack inside sealed CSR. Mutations enter a WAL-backed delta adjacency organized by partition and source bucket. Readers merge base plus visible deltas. Checkpoint rewrites only affected partition ranges and publishes a new immutable root. + +## 5. Hot/warm/cold topology tiers + +- Tier 0: compact degree/partition routing metadata in RAM. +- Tier 1: hot adjacency and dictionaries in compressed RAM cache. +- Tier 2: larger content-addressed NVMe cache shared by local workers. +- Tier 3: S3 Standard authoritative immutable packs and manifests. +- Optional Tier 3W: low-latency object class for WAL only when its durability/availability tradeoff is accepted. + +The engine never promises one latency number across tiers. Plans carry a cache certainty class and estimated remote rounds. Admission can reject a query whose cold path exceeds the user's latency or cost budget. + +## 6. Remote-read algorithm + +1. Resolve and pin `CURRENT` using an ETag/version-aware metadata cache. +2. Read the bounded root and only the partition submanifests needed by the plan. +3. Group frontier node IDs by partition, pack, and coalescible byte range. +4. Check RAM then NVMe using immutable content/range keys. +5. Deduplicate concurrent misses through a single-flight table. +6. Issue bounded parallel range GETs with reserved in-flight byte credits. +7. Verify per-tile checksums before exposing decoded values. +8. Decode into ownership-carrying vector batches. +9. Emit the next frontier early enough to overlap prefetch with current-level processing. +10. Cancel speculative reads immediately when the query completes or reaches its budget. + +Pointer chasing against cold S3 is forbidden. A k-hop cold traversal should require approximately one batched remote phase per dependent frontier level, not one GET per node or edge. + +## 7. Query execution + +Use a hybrid engine rather than forcing every workload through one abstraction: + +- Vectorized column scans with predicate/projection pushdown. +- Factorized intermediate tables for join-heavy graph patterns. +- Batched adjacency expansion keyed by input positions. +- ExpandInto using sorted adjacency or endpoint indices. +- Worst-case-aware multiway joins for cyclic patterns. +- Dedicated frontier/fixpoint operators for reachability and BFS. +- Bidirectional search for point-to-point shortest paths. +- Compact path representations for path-returning queries. +- Matrix/bitset kernels only when frontier density crosses a calibrated threshold. +- Late materialization of cold properties. +- Morsel scheduling with degree-aware work splitting. + +The storage SPI accepts batch requests and returns asynchronous streams. It exposes capabilities and cost estimates, never raw S3 calls or a synchronous `neighbors(node)` loop. + +## 8. Cost-based optimizer + +The cost vector contains rows, edges, compressed bytes, decoded bytes, CPU cycles, peak memory, disk reads, remote requests, remote bytes, network shuffle bytes, spill bytes, cache certainty, and expected tail latency. It is not collapsed too early into one scalar. Admission uses hard dimensions; plan ranking uses a configurable weighted score. + +Persist degree histograms by type/direction, joint endpoint statistics, label/property correlations, heavy hitters, high-degree exceptions, tile compressed sizes, zone maps, index selectivity, delta depth, partition-crossing ratios, and observed cache residency. Stats generation is pinned by the snapshot token. + +## 9. Transactions and publication + +A commit has an idempotency key, logical mutation digest, writer epoch, partition, base generation, validation read set, and durability class. The writer validates constraints and conflicts, uploads immutable WAL/data objects, verifies them, writes an immutable manifest, then conditionally advances the partition root. Lost responses are reconciled by transaction identity and manifest ancestry. + +Conditional PUT of `CURRENT` prevents two root updates from both succeeding, but it is not a writer lease. A fencing authority assigns monotonic epochs. The writer stops acknowledging before lease uncertainty. WAL objects, manifests, and receipts all carry the epoch so stale acknowledgements are detectable. + +## 10. Partitioning for PB scale + +Use a two-level scheme: tenant/table isolation first, then graph-locality partitions. The default is stable source-ID range/hash hybrid with optional community/locality remapping during offline optimization. Very high-degree vertices receive explicit split ownership with deterministic read assembly. + +An edge has one transactional home. Both directional projections for a strict commit must be published under one atomic partition root or through a transactional metadata record that binds both partitions. If that is not available, cross-partition mutations are asynchronous and labeled accordingly. + +Partition roots are small and independent. A catalog root maps logical ranges to partition generations. Readers pin one catalog epoch. Repartitioning writes new partitions, validates equivalence, atomically changes the catalog mapping, and retains old partitions until all pinned readers and retention policies release them. + +## 11. Resource minimization + +- Compressed-cache-first: decode only selected columns/adjacency tiles. +- Use 32-bit local ordinals inside partitions while preserving 128-bit external identity. +- Delta-code sorted neighbors and local edge ordinals; choose encoding per tile from samples then verify full-size benefit. +- Intern repeated labels, types, strings, and partition-local ID prefixes. +- Separate scan admission from reusable point/traversal cache admission. +- Reserve bytes before allocation and before I/O. +- Bound every queue and propagate backpressure to clients. +- Isolate maintenance CPU/I/O with explicit budgets. +- Run stateless query workers only when the namespace working set justifies them. +- Scale to zero for inactive namespaces while retaining a small manifest/metadata cache. + +## 12. Fixed-cost service contract + +A monthly plan includes logical stored bytes, retained history, maximum cached bytes, admitted query CPU-seconds, remote GET count/bytes, write bytes/PUTs, result egress, and maintenance budget. The system enforces token buckets at namespace and tenant levels. Once exhausted, it queues, degrades to eventual consistency where authorized, requires a cost override, or rejects—never silently creates an unbounded bill. + +The plan price reserves worst-case included capacity plus risk margin. S3 itself is variable cost. `Fixed price` is a commercial envelope enforced by technical limits and multiplexing, not a physical property. + +## 13. SLO classes + +- Hot local point: target p50 under 100 µs and p99 under 1 ms on qualified hardware. +- Warm NVMe point/one-hop: target p50 under 1 ms and p99 under 5 ms. +- Warm remote-profile point/one-hop served from local cache: target p99 under 10 ms including network. +- Cold S3 Standard point: target bounded request count and p99 under 300 ms, not local latency. +- Cold k-hop: target no more than metadata rounds plus one dependent frontier round per hop. +- Overload: preserve bounded memory and p99 by rejecting before resource exhaustion. + +These are qualification targets. They are not claims about the current repository. + +## 14. Implementation order + +1. Replace the disconnected storage/query traits with SnapshotReader and typed batch streams. +2. Fix stable EdgeId and query-visible MVCC overlays. +3. Implement positioned I/O, shared cache ownership, per-chunk integrity, and bounded open/recovery. +4. Freeze a pre-v1 immutable segment envelope only after golden readers and fuzzing. +5. Make local factorized/vectorized execution correct and resource-accounted. +6. Add object packs, manifests, range planning, cache, request accounting, and provider contract tests. +7. Add fencing and ambiguous-commit reconciliation. +8. Add partition catalog, repartitioning, pins, and GC. +9. Publish benchmark harness and only then evaluate tenfold cells. + +## 15. Kill criteria + +Stop or redesign the remote profile if cold point queries require unbounded object requests, if the cache cannot preserve reusable topology under scans, if writer fencing cannot prove acknowledgement safety, if cross-partition edge consistency is unspecified, if GC cannot avoid live-object deletion, or if cost admission cannot enforce the sold envelope. + +## 16. Architecture evidence + +- [BG3: A Cost Effective and I/O Efficient Graph Database in ByteDance](https://doi.org/10.1145/3626246.3653373) — published graph-on-cloud-storage evidence. +- [SlateDB design overview](https://slatedb.io/docs/design/overview/) — object-store LSM, WAL, manifests, and tradeoffs. +- [SlateDB introduction](https://slatedb.io/docs/get-started/introduction/) — single writer, multiple readers, cache, snapshots, and fencing posture. +- [SlateDB manifest RFC](https://slatedb.io/rfcs/0001-manifest/) — why writer/WAL fencing is more than replacing one pointer. +- [turbopuffer architecture](https://turbopuffer.com/docs/architecture) — measured cold/warm gap, WAL batching, NVMe locality, and object-oriented index design. +- [PuppyGraph architecture/docs](https://docs.puppygraph.com/) — current commercial graph-over-lake comparator. +- [Microsoft Fabric Graph architecture](https://learn.microsoft.com/en-us/fabric/graph/how-graph-works) — read-optimized graph materialization over OneLake. +- [SurrealDB architecture](https://surrealdb.com/docs/architecture) — compute/storage separation and current storage-engine matrix. +- [LDBC SNB Interactive](https://ldbcouncil.org/benchmarks/snb/interactive/) — audited interactive throughput and full-disclosure methodology. +- [LDBC Graphalytics](https://ldbcouncil.org/benchmarks/graphalytics/) — standardized graph algorithm work. +- [SoK: The Faults in our Graph Benchmarks](https://arxiv.org/abs/2404.00766) — ID ordering, zero-degree nodes, dataset realism, and reporting hazards. + +## Appendix A. Release-gate assertions + +- RG-001: For the target architecture, release is blocked until the raw samples and aggregated chart agree. +- RG-002: For the target architecture, release is blocked until the query result matches the canonical oracle. +- RG-003: For the target architecture, release is blocked until the engine version and artifact digest are recorded. +- RG-004: For the target architecture, release is blocked until the selected durability level matches the comparison class. +- RG-005: For the target architecture, release is blocked until cache state is explicit and reproducible. +- RG-006: For the target architecture, release is blocked until peak memory includes engine and required sidecars. +- RG-007: For the target architecture, release is blocked until storage size includes indexes, logs, replicas, and temporary space. +- RG-008: For the target architecture, release is blocked until timeouts and rejected operations remain in the result set. +- RG-009: For the target architecture, release is blocked until remote requests and bytes are measured rather than estimated. +- RG-010: For the target architecture, release is blocked until background maintenance is either quiesced or reported. +- RG-011: For the target architecture, release is blocked until thread, NUMA, and CPU-affinity settings are captured. +- RG-012: For the target architecture, release is blocked until the dataset and update-stream digests are immutable. +- RG-013: For the target architecture, release is blocked until the query plan/profile is archived. +- RG-014: For the target architecture, release is blocked until unsupported features are not replaced by weaker semantics. +- RG-015: For the target architecture, release is blocked until a second operator can reproduce the run from a clean host. +- RG-016: For the target architecture, release is blocked until the raw samples and aggregated chart agree. +- RG-017: For the target architecture, release is blocked until the query result matches the canonical oracle. +- RG-018: For the target architecture, release is blocked until the engine version and artifact digest are recorded. +- RG-019: For the target architecture, release is blocked until the selected durability level matches the comparison class. +- RG-020: For the target architecture, release is blocked until cache state is explicit and reproducible. +- RG-021: For the target architecture, release is blocked until peak memory includes engine and required sidecars. +- RG-022: For the target architecture, release is blocked until storage size includes indexes, logs, replicas, and temporary space. +- RG-023: For the target architecture, release is blocked until timeouts and rejected operations remain in the result set. +- RG-024: For the target architecture, release is blocked until remote requests and bytes are measured rather than estimated. +- RG-025: For the target architecture, release is blocked until background maintenance is either quiesced or reported. +- RG-026: For the target architecture, release is blocked until thread, NUMA, and CPU-affinity settings are captured. +- RG-027: For the target architecture, release is blocked until the dataset and update-stream digests are immutable. +- RG-028: For the target architecture, release is blocked until the query plan/profile is archived. +- RG-029: For the target architecture, release is blocked until unsupported features are not replaced by weaker semantics. +- RG-030: For the target architecture, release is blocked until a second operator can reproduce the run from a clean host. +- RG-031: For the target architecture, release is blocked until the raw samples and aggregated chart agree. +- RG-032: For the target architecture, release is blocked until the query result matches the canonical oracle. +- RG-033: For the target architecture, release is blocked until the engine version and artifact digest are recorded. +- RG-034: For the target architecture, release is blocked until the selected durability level matches the comparison class. +- RG-035: For the target architecture, release is blocked until cache state is explicit and reproducible. +- RG-036: For the target architecture, release is blocked until peak memory includes engine and required sidecars. +- RG-037: For the target architecture, release is blocked until storage size includes indexes, logs, replicas, and temporary space. +- RG-038: For the target architecture, release is blocked until timeouts and rejected operations remain in the result set. +- RG-039: For the target architecture, release is blocked until remote requests and bytes are measured rather than estimated. +- RG-040: For the target architecture, release is blocked until background maintenance is either quiesced or reported. +- RG-041: For the target architecture, release is blocked until thread, NUMA, and CPU-affinity settings are captured. +- RG-042: For the target architecture, release is blocked until the dataset and update-stream digests are immutable. +- RG-043: For the target architecture, release is blocked until the query plan/profile is archived. +- RG-044: For the target architecture, release is blocked until unsupported features are not replaced by weaker semantics. +- RG-045: For the target architecture, release is blocked until a second operator can reproduce the run from a clean host. +- RG-046: For the target architecture, release is blocked until the raw samples and aggregated chart agree. +- RG-047: For the target architecture, release is blocked until the query result matches the canonical oracle. +- RG-048: For the target architecture, release is blocked until the engine version and artifact digest are recorded. +- RG-049: For the target architecture, release is blocked until the selected durability level matches the comparison class. +- RG-050: For the target architecture, release is blocked until cache state is explicit and reproducible. +- RG-051: For the target architecture, release is blocked until peak memory includes engine and required sidecars. +- RG-052: For the target architecture, release is blocked until storage size includes indexes, logs, replicas, and temporary space. +- RG-053: For the target architecture, release is blocked until timeouts and rejected operations remain in the result set. +- RG-054: For the target architecture, release is blocked until remote requests and bytes are measured rather than estimated. +- RG-055: For the target architecture, release is blocked until background maintenance is either quiesced or reported. +- RG-056: For the target architecture, release is blocked until thread, NUMA, and CPU-affinity settings are captured. +- RG-057: For the target architecture, release is blocked until the dataset and update-stream digests are immutable. +- RG-058: For the target architecture, release is blocked until the query plan/profile is archived. +- RG-059: For the target architecture, release is blocked until unsupported features are not replaced by weaker semantics. +- RG-060: For the target architecture, release is blocked until a second operator can reproduce the run from a clean host. +- RG-061: For the target architecture, release is blocked until the raw samples and aggregated chart agree. +- RG-062: For the target architecture, release is blocked until the query result matches the canonical oracle. +- RG-063: For the target architecture, release is blocked until the engine version and artifact digest are recorded. +- RG-064: For the target architecture, release is blocked until the selected durability level matches the comparison class. +- RG-065: For the target architecture, release is blocked until cache state is explicit and reproducible. +- RG-066: For the target architecture, release is blocked until peak memory includes engine and required sidecars. +- RG-067: For the target architecture, release is blocked until storage size includes indexes, logs, replicas, and temporary space. +- RG-068: For the target architecture, release is blocked until timeouts and rejected operations remain in the result set. +- RG-069: For the target architecture, release is blocked until remote requests and bytes are measured rather than estimated. +- RG-070: For the target architecture, release is blocked until background maintenance is either quiesced or reported. +- RG-071: For the target architecture, release is blocked until thread, NUMA, and CPU-affinity settings are captured. +- RG-072: For the target architecture, release is blocked until the dataset and update-stream digests are immutable. +- RG-073: For the target architecture, release is blocked until the query plan/profile is archived. +- RG-074: For the target architecture, release is blocked until unsupported features are not replaced by weaker semantics. +- RG-075: For the target architecture, release is blocked until a second operator can reproduce the run from a clean host. +- RG-076: For the target architecture, release is blocked until the raw samples and aggregated chart agree. +- RG-077: For the target architecture, release is blocked until the query result matches the canonical oracle. +- RG-078: For the target architecture, release is blocked until the engine version and artifact digest are recorded. +- RG-079: For the target architecture, release is blocked until the selected durability level matches the comparison class. +- RG-080: For the target architecture, release is blocked until cache state is explicit and reproducible. +- RG-081: For the target architecture, release is blocked until peak memory includes engine and required sidecars. +- RG-082: For the target architecture, release is blocked until storage size includes indexes, logs, replicas, and temporary space. +- RG-083: For the target architecture, release is blocked until timeouts and rejected operations remain in the result set. +- RG-084: For the target architecture, release is blocked until remote requests and bytes are measured rather than estimated. +- RG-085: For the target architecture, release is blocked until background maintenance is either quiesced or reported. +- RG-086: For the target architecture, release is blocked until thread, NUMA, and CPU-affinity settings are captured. +- RG-087: For the target architecture, release is blocked until the dataset and update-stream digests are immutable. +- RG-088: For the target architecture, release is blocked until the query plan/profile is archived. +- RG-089: For the target architecture, release is blocked until unsupported features are not replaced by weaker semantics. +- RG-090: For the target architecture, release is blocked until a second operator can reproduce the run from a clean host. +- RG-091: For the target architecture, release is blocked until the raw samples and aggregated chart agree. +- RG-092: For the target architecture, release is blocked until the query result matches the canonical oracle. +- RG-093: For the target architecture, release is blocked until the engine version and artifact digest are recorded. +- RG-094: For the target architecture, release is blocked until the selected durability level matches the comparison class. +- RG-095: For the target architecture, release is blocked until cache state is explicit and reproducible. +- RG-096: For the target architecture, release is blocked until peak memory includes engine and required sidecars. +- RG-097: For the target architecture, release is blocked until storage size includes indexes, logs, replicas, and temporary space. +- RG-098: For the target architecture, release is blocked until timeouts and rejected operations remain in the result set. +- RG-099: For the target architecture, release is blocked until remote requests and bytes are measured rather than estimated. +- RG-100: For the target architecture, release is blocked until background maintenance is either quiesced or reported. +- RG-101: For the target architecture, release is blocked until thread, NUMA, and CPU-affinity settings are captured. +- RG-102: For the target architecture, release is blocked until the dataset and update-stream digests are immutable. +- RG-103: For the target architecture, release is blocked until the query plan/profile is archived. +- RG-104: For the target architecture, release is blocked until unsupported features are not replaced by weaker semantics. +- RG-105: For the target architecture, release is blocked until a second operator can reproduce the run from a clean host. +- RG-106: For the target architecture, release is blocked until the raw samples and aggregated chart agree. +- RG-107: For the target architecture, release is blocked until the query result matches the canonical oracle. +- RG-108: For the target architecture, release is blocked until the engine version and artifact digest are recorded. +- RG-109: For the target architecture, release is blocked until the selected durability level matches the comparison class. +- RG-110: For the target architecture, release is blocked until cache state is explicit and reproducible. +- RG-111: For the target architecture, release is blocked until peak memory includes engine and required sidecars. +- RG-112: For the target architecture, release is blocked until storage size includes indexes, logs, replicas, and temporary space. +- RG-113: For the target architecture, release is blocked until timeouts and rejected operations remain in the result set. +- RG-114: For the target architecture, release is blocked until remote requests and bytes are measured rather than estimated. +- RG-115: For the target architecture, release is blocked until background maintenance is either quiesced or reported. +- RG-116: For the target architecture, release is blocked until thread, NUMA, and CPU-affinity settings are captured. +- RG-117: For the target architecture, release is blocked until the dataset and update-stream digests are immutable. +- RG-118: For the target architecture, release is blocked until the query plan/profile is archived. +- RG-119: For the target architecture, release is blocked until unsupported features are not replaced by weaker semantics. +- RG-120: For the target architecture, release is blocked until a second operator can reproduce the run from a clean host. +- RG-121: For the target architecture, release is blocked until the raw samples and aggregated chart agree. +- RG-122: For the target architecture, release is blocked until the query result matches the canonical oracle. +- RG-123: For the target architecture, release is blocked until the engine version and artifact digest are recorded. +- RG-124: For the target architecture, release is blocked until the selected durability level matches the comparison class. +- RG-125: For the target architecture, release is blocked until cache state is explicit and reproducible. +- RG-126: For the target architecture, release is blocked until peak memory includes engine and required sidecars. +- RG-127: For the target architecture, release is blocked until storage size includes indexes, logs, replicas, and temporary space. +- RG-128: For the target architecture, release is blocked until timeouts and rejected operations remain in the result set. +- RG-129: For the target architecture, release is blocked until remote requests and bytes are measured rather than estimated. +- RG-130: For the target architecture, release is blocked until background maintenance is either quiesced or reported. +- RG-131: For the target architecture, release is blocked until thread, NUMA, and CPU-affinity settings are captured. +- RG-132: For the target architecture, release is blocked until the dataset and update-stream digests are immutable. +- RG-133: For the target architecture, release is blocked until the query plan/profile is archived. +- RG-134: For the target architecture, release is blocked until unsupported features are not replaced by weaker semantics. +- RG-135: For the target architecture, release is blocked until a second operator can reproduce the run from a clean host. +- RG-136: For the target architecture, release is blocked until the raw samples and aggregated chart agree. +- RG-137: For the target architecture, release is blocked until the query result matches the canonical oracle. +- RG-138: For the target architecture, release is blocked until the engine version and artifact digest are recorded. +- RG-139: For the target architecture, release is blocked until the selected durability level matches the comparison class. +- RG-140: For the target architecture, release is blocked until cache state is explicit and reproducible. +- RG-141: For the target architecture, release is blocked until peak memory includes engine and required sidecars. +- RG-142: For the target architecture, release is blocked until storage size includes indexes, logs, replicas, and temporary space. +- RG-143: For the target architecture, release is blocked until timeouts and rejected operations remain in the result set. +- RG-144: For the target architecture, release is blocked until remote requests and bytes are measured rather than estimated. +- RG-145: For the target architecture, release is blocked until background maintenance is either quiesced or reported. +- RG-146: For the target architecture, release is blocked until thread, NUMA, and CPU-affinity settings are captured. +- RG-147: For the target architecture, release is blocked until the dataset and update-stream digests are immutable. +- RG-148: For the target architecture, release is blocked until the query plan/profile is archived. +- RG-149: For the target architecture, release is blocked until unsupported features are not replaced by weaker semantics. +- RG-150: For the target architecture, release is blocked until a second operator can reproduce the run from a clean host. +- RG-151: For the target architecture, release is blocked until the raw samples and aggregated chart agree. +- RG-152: For the target architecture, release is blocked until the query result matches the canonical oracle. +- RG-153: For the target architecture, release is blocked until the engine version and artifact digest are recorded. +- RG-154: For the target architecture, release is blocked until the selected durability level matches the comparison class. +- RG-155: For the target architecture, release is blocked until cache state is explicit and reproducible. +- RG-156: For the target architecture, release is blocked until peak memory includes engine and required sidecars. +- RG-157: For the target architecture, release is blocked until storage size includes indexes, logs, replicas, and temporary space. +- RG-158: For the target architecture, release is blocked until timeouts and rejected operations remain in the result set. +- RG-159: For the target architecture, release is blocked until remote requests and bytes are measured rather than estimated. +- RG-160: For the target architecture, release is blocked until background maintenance is either quiesced or reported. +- RG-161: For the target architecture, release is blocked until thread, NUMA, and CPU-affinity settings are captured. +- RG-162: For the target architecture, release is blocked until the dataset and update-stream digests are immutable. +- RG-163: For the target architecture, release is blocked until the query plan/profile is archived. +- RG-164: For the target architecture, release is blocked until unsupported features are not replaced by weaker semantics. +- RG-165: For the target architecture, release is blocked until a second operator can reproduce the run from a clean host. +- RG-166: For the target architecture, release is blocked until the raw samples and aggregated chart agree. +- RG-167: For the target architecture, release is blocked until the query result matches the canonical oracle. +- RG-168: For the target architecture, release is blocked until the engine version and artifact digest are recorded. +- RG-169: For the target architecture, release is blocked until the selected durability level matches the comparison class. +- RG-170: For the target architecture, release is blocked until cache state is explicit and reproducible. +- RG-171: For the target architecture, release is blocked until peak memory includes engine and required sidecars. +- RG-172: For the target architecture, release is blocked until storage size includes indexes, logs, replicas, and temporary space. +- RG-173: For the target architecture, release is blocked until timeouts and rejected operations remain in the result set. +- RG-174: For the target architecture, release is blocked until remote requests and bytes are measured rather than estimated. +- RG-175: For the target architecture, release is blocked until background maintenance is either quiesced or reported. +- RG-176: For the target architecture, release is blocked until thread, NUMA, and CPU-affinity settings are captured. +- RG-177: For the target architecture, release is blocked until the dataset and update-stream digests are immutable. +- RG-178: For the target architecture, release is blocked until the query plan/profile is archived. +- RG-179: For the target architecture, release is blocked until unsupported features are not replaced by weaker semantics. +- RG-180: For the target architecture, release is blocked until a second operator can reproduce the run from a clean host. +- RG-181: For the target architecture, release is blocked until the raw samples and aggregated chart agree. +- RG-182: For the target architecture, release is blocked until the query result matches the canonical oracle. +- RG-183: For the target architecture, release is blocked until the engine version and artifact digest are recorded. +- RG-184: For the target architecture, release is blocked until the selected durability level matches the comparison class. +- RG-185: For the target architecture, release is blocked until cache state is explicit and reproducible. +- RG-186: For the target architecture, release is blocked until peak memory includes engine and required sidecars. +- RG-187: For the target architecture, release is blocked until storage size includes indexes, logs, replicas, and temporary space. +- RG-188: For the target architecture, release is blocked until timeouts and rejected operations remain in the result set. +- RG-189: For the target architecture, release is blocked until remote requests and bytes are measured rather than estimated. +- RG-190: For the target architecture, release is blocked until background maintenance is either quiesced or reported. +- RG-191: For the target architecture, release is blocked until thread, NUMA, and CPU-affinity settings are captured. +- RG-192: For the target architecture, release is blocked until the dataset and update-stream digests are immutable. +- RG-193: For the target architecture, release is blocked until the query plan/profile is archived. +- RG-194: For the target architecture, release is blocked until unsupported features are not replaced by weaker semantics. +- RG-195: For the target architecture, release is blocked until a second operator can reproduce the run from a clean host. +- RG-196: For the target architecture, release is blocked until the raw samples and aggregated chart agree. +- RG-197: For the target architecture, release is blocked until the query result matches the canonical oracle. +- RG-198: For the target architecture, release is blocked until the engine version and artifact digest are recorded. +- RG-199: For the target architecture, release is blocked until the selected durability level matches the comparison class. +- RG-200: For the target architecture, release is blocked until cache state is explicit and reproducible. +- RG-201: For the target architecture, release is blocked until peak memory includes engine and required sidecars. +- RG-202: For the target architecture, release is blocked until storage size includes indexes, logs, replicas, and temporary space. +- RG-203: For the target architecture, release is blocked until timeouts and rejected operations remain in the result set. +- RG-204: For the target architecture, release is blocked until remote requests and bytes are measured rather than estimated. +- RG-205: For the target architecture, release is blocked until background maintenance is either quiesced or reported. +- RG-206: For the target architecture, release is blocked until thread, NUMA, and CPU-affinity settings are captured. +- RG-207: For the target architecture, release is blocked until the dataset and update-stream digests are immutable. +- RG-208: For the target architecture, release is blocked until the query plan/profile is archived. +- RG-209: For the target architecture, release is blocked until unsupported features are not replaced by weaker semantics. +- RG-210: For the target architecture, release is blocked until a second operator can reproduce the run from a clean host. +- RG-211: For the target architecture, release is blocked until the raw samples and aggregated chart agree. +- RG-212: For the target architecture, release is blocked until the query result matches the canonical oracle. +- RG-213: For the target architecture, release is blocked until the engine version and artifact digest are recorded. +- RG-214: For the target architecture, release is blocked until the selected durability level matches the comparison class. +- RG-215: For the target architecture, release is blocked until cache state is explicit and reproducible. +- RG-216: For the target architecture, release is blocked until peak memory includes engine and required sidecars. +- RG-217: For the target architecture, release is blocked until storage size includes indexes, logs, replicas, and temporary space. +- RG-218: For the target architecture, release is blocked until timeouts and rejected operations remain in the result set. +- RG-219: For the target architecture, release is blocked until remote requests and bytes are measured rather than estimated. +- RG-220: For the target architecture, release is blocked until background maintenance is either quiesced or reported. +- RG-221: For the target architecture, release is blocked until thread, NUMA, and CPU-affinity settings are captured. +- RG-222: For the target architecture, release is blocked until the dataset and update-stream digests are immutable. +- RG-223: For the target architecture, release is blocked until the query plan/profile is archived. +- RG-224: For the target architecture, release is blocked until unsupported features are not replaced by weaker semantics. +- RG-225: For the target architecture, release is blocked until a second operator can reproduce the run from a clean host. +- RG-226: For the target architecture, release is blocked until the raw samples and aggregated chart agree. +- RG-227: For the target architecture, release is blocked until the query result matches the canonical oracle. +- RG-228: For the target architecture, release is blocked until the engine version and artifact digest are recorded. +- RG-229: For the target architecture, release is blocked until the selected durability level matches the comparison class. +- RG-230: For the target architecture, release is blocked until cache state is explicit and reproducible. +- RG-231: For the target architecture, release is blocked until peak memory includes engine and required sidecars. +- RG-232: For the target architecture, release is blocked until storage size includes indexes, logs, replicas, and temporary space. +- RG-233: For the target architecture, release is blocked until timeouts and rejected operations remain in the result set. +- RG-234: For the target architecture, release is blocked until remote requests and bytes are measured rather than estimated. +- RG-235: For the target architecture, release is blocked until background maintenance is either quiesced or reported. +- RG-236: For the target architecture, release is blocked until thread, NUMA, and CPU-affinity settings are captured. +- RG-237: For the target architecture, release is blocked until the dataset and update-stream digests are immutable. +- RG-238: For the target architecture, release is blocked until the query plan/profile is archived. +- RG-239: For the target architecture, release is blocked until unsupported features are not replaced by weaker semantics. +- RG-240: For the target architecture, release is blocked until a second operator can reproduce the run from a clean host. +- RG-241: For the target architecture, release is blocked until the raw samples and aggregated chart agree. +- RG-242: For the target architecture, release is blocked until the query result matches the canonical oracle. +- RG-243: For the target architecture, release is blocked until the engine version and artifact digest are recorded. +- RG-244: For the target architecture, release is blocked until the selected durability level matches the comparison class. +- RG-245: For the target architecture, release is blocked until cache state is explicit and reproducible. +- RG-246: For the target architecture, release is blocked until peak memory includes engine and required sidecars. +- RG-247: For the target architecture, release is blocked until storage size includes indexes, logs, replicas, and temporary space. +- RG-248: For the target architecture, release is blocked until timeouts and rejected operations remain in the result set. +- RG-249: For the target architecture, release is blocked until remote requests and bytes are measured rather than estimated. +- RG-250: For the target architecture, release is blocked until background maintenance is either quiesced or reported. +- RG-251: For the target architecture, release is blocked until thread, NUMA, and CPU-affinity settings are captured. +- RG-252: For the target architecture, release is blocked until the dataset and update-stream digests are immutable. +- RG-253: For the target architecture, release is blocked until the query plan/profile is archived. +- RG-254: For the target architecture, release is blocked until unsupported features are not replaced by weaker semantics. +- RG-255: For the target architecture, release is blocked until a second operator can reproduce the run from a clean host. +- RG-256: For the target architecture, release is blocked until the raw samples and aggregated chart agree. +- RG-257: For the target architecture, release is blocked until the query result matches the canonical oracle. +- RG-258: For the target architecture, release is blocked until the engine version and artifact digest are recorded. +- RG-259: For the target architecture, release is blocked until the selected durability level matches the comparison class. +- RG-260: For the target architecture, release is blocked until cache state is explicit and reproducible. +- RG-261: For the target architecture, release is blocked until peak memory includes engine and required sidecars. +- RG-262: For the target architecture, release is blocked until storage size includes indexes, logs, replicas, and temporary space. +- RG-263: For the target architecture, release is blocked until timeouts and rejected operations remain in the result set. +- RG-264: For the target architecture, release is blocked until remote requests and bytes are measured rather than estimated. +- RG-265: For the target architecture, release is blocked until background maintenance is either quiesced or reported. +- RG-266: For the target architecture, release is blocked until thread, NUMA, and CPU-affinity settings are captured. +- RG-267: For the target architecture, release is blocked until the dataset and update-stream digests are immutable. +- RG-268: For the target architecture, release is blocked until the query plan/profile is archived. +- RG-269: For the target architecture, release is blocked until unsupported features are not replaced by weaker semantics. +- RG-270: For the target architecture, release is blocked until a second operator can reproduce the run from a clean host. +- RG-271: For the target architecture, release is blocked until the raw samples and aggregated chart agree. +- RG-272: For the target architecture, release is blocked until the query result matches the canonical oracle. +- RG-273: For the target architecture, release is blocked until the engine version and artifact digest are recorded. +- RG-274: For the target architecture, release is blocked until the selected durability level matches the comparison class. +- RG-275: For the target architecture, release is blocked until cache state is explicit and reproducible. +- RG-276: For the target architecture, release is blocked until peak memory includes engine and required sidecars. +- RG-277: For the target architecture, release is blocked until storage size includes indexes, logs, replicas, and temporary space. +- RG-278: For the target architecture, release is blocked until timeouts and rejected operations remain in the result set. +- RG-279: For the target architecture, release is blocked until remote requests and bytes are measured rather than estimated. +- RG-280: For the target architecture, release is blocked until background maintenance is either quiesced or reported. +- RG-281: For the target architecture, release is blocked until thread, NUMA, and CPU-affinity settings are captured. +- RG-282: For the target architecture, release is blocked until the dataset and update-stream digests are immutable. +- RG-283: For the target architecture, release is blocked until the query plan/profile is archived. +- RG-284: For the target architecture, release is blocked until unsupported features are not replaced by weaker semantics. +- RG-285: For the target architecture, release is blocked until a second operator can reproduce the run from a clean host. +- RG-286: For the target architecture, release is blocked until the raw samples and aggregated chart agree. +- RG-287: For the target architecture, release is blocked until the query result matches the canonical oracle. +- RG-288: For the target architecture, release is blocked until the engine version and artifact digest are recorded. +- RG-289: For the target architecture, release is blocked until the selected durability level matches the comparison class. +- RG-290: For the target architecture, release is blocked until cache state is explicit and reproducible. +- RG-291: For the target architecture, release is blocked until peak memory includes engine and required sidecars. +- RG-292: For the target architecture, release is blocked until storage size includes indexes, logs, replicas, and temporary space. +- RG-293: For the target architecture, release is blocked until timeouts and rejected operations remain in the result set. +- RG-294: For the target architecture, release is blocked until remote requests and bytes are measured rather than estimated. +- RG-295: For the target architecture, release is blocked until background maintenance is either quiesced or reported. +- RG-296: For the target architecture, release is blocked until thread, NUMA, and CPU-affinity settings are captured. +- RG-297: For the target architecture, release is blocked until the dataset and update-stream digests are immutable. +- RG-298: For the target architecture, release is blocked until the query plan/profile is archived. +- RG-299: For the target architecture, release is blocked until unsupported features are not replaced by weaker semantics. +- RG-300: For the target architecture, release is blocked until a second operator can reproduce the run from a clean host. +- RG-301: For the target architecture, release is blocked until the raw samples and aggregated chart agree. +- RG-302: For the target architecture, release is blocked until the query result matches the canonical oracle. +- RG-303: For the target architecture, release is blocked until the engine version and artifact digest are recorded. +- RG-304: For the target architecture, release is blocked until the selected durability level matches the comparison class. +- RG-305: For the target architecture, release is blocked until cache state is explicit and reproducible. +- RG-306: For the target architecture, release is blocked until peak memory includes engine and required sidecars. +- RG-307: For the target architecture, release is blocked until storage size includes indexes, logs, replicas, and temporary space. +- RG-308: For the target architecture, release is blocked until timeouts and rejected operations remain in the result set. +- RG-309: For the target architecture, release is blocked until remote requests and bytes are measured rather than estimated. +- RG-310: For the target architecture, release is blocked until background maintenance is either quiesced or reported. +- RG-311: For the target architecture, release is blocked until thread, NUMA, and CPU-affinity settings are captured. +- RG-312: For the target architecture, release is blocked until the dataset and update-stream digests are immutable. +- RG-313: For the target architecture, release is blocked until the query plan/profile is archived. +- RG-314: For the target architecture, release is blocked until unsupported features are not replaced by weaker semantics. +- RG-315: For the target architecture, release is blocked until a second operator can reproduce the run from a clean host. +- RG-316: For the target architecture, release is blocked until the raw samples and aggregated chart agree. +- RG-317: For the target architecture, release is blocked until the query result matches the canonical oracle. +- RG-318: For the target architecture, release is blocked until the engine version and artifact digest are recorded. +- RG-319: For the target architecture, release is blocked until the selected durability level matches the comparison class. +- RG-320: For the target architecture, release is blocked until cache state is explicit and reproducible. +- RG-321: For the target architecture, release is blocked until peak memory includes engine and required sidecars. +- RG-322: For the target architecture, release is blocked until storage size includes indexes, logs, replicas, and temporary space. +- RG-323: For the target architecture, release is blocked until timeouts and rejected operations remain in the result set. +- RG-324: For the target architecture, release is blocked until remote requests and bytes are measured rather than estimated. +- RG-325: For the target architecture, release is blocked until background maintenance is either quiesced or reported. +- RG-326: For the target architecture, release is blocked until thread, NUMA, and CPU-affinity settings are captured. +- RG-327: For the target architecture, release is blocked until the dataset and update-stream digests are immutable. +- RG-328: For the target architecture, release is blocked until the query plan/profile is archived. +- RG-329: For the target architecture, release is blocked until unsupported features are not replaced by weaker semantics. +- RG-330: For the target architecture, release is blocked until a second operator can reproduce the run from a clean host. +- RG-331: For the target architecture, release is blocked until the raw samples and aggregated chart agree. +- RG-332: For the target architecture, release is blocked until the query result matches the canonical oracle. +- RG-333: For the target architecture, release is blocked until the engine version and artifact digest are recorded. +- RG-334: For the target architecture, release is blocked until the selected durability level matches the comparison class. +- RG-335: For the target architecture, release is blocked until cache state is explicit and reproducible. +- RG-336: For the target architecture, release is blocked until peak memory includes engine and required sidecars. +- RG-337: For the target architecture, release is blocked until storage size includes indexes, logs, replicas, and temporary space. +- RG-338: For the target architecture, release is blocked until timeouts and rejected operations remain in the result set. +- RG-339: For the target architecture, release is blocked until remote requests and bytes are measured rather than estimated. +- RG-340: For the target architecture, release is blocked until background maintenance is either quiesced or reported. +- RG-341: For the target architecture, release is blocked until thread, NUMA, and CPU-affinity settings are captured. +- RG-342: For the target architecture, release is blocked until the dataset and update-stream digests are immutable. +- RG-343: For the target architecture, release is blocked until the query plan/profile is archived. +- RG-344: For the target architecture, release is blocked until unsupported features are not replaced by weaker semantics. +- RG-345: For the target architecture, release is blocked until a second operator can reproduce the run from a clean host. +- RG-346: For the target architecture, release is blocked until the raw samples and aggregated chart agree. +- RG-347: For the target architecture, release is blocked until the query result matches the canonical oracle. +- RG-348: For the target architecture, release is blocked until the engine version and artifact digest are recorded. +- RG-349: For the target architecture, release is blocked until the selected durability level matches the comparison class. +- RG-350: For the target architecture, release is blocked until cache state is explicit and reproducible. +- RG-351: For the target architecture, release is blocked until peak memory includes engine and required sidecars. +- RG-352: For the target architecture, release is blocked until storage size includes indexes, logs, replicas, and temporary space. +- RG-353: For the target architecture, release is blocked until timeouts and rejected operations remain in the result set. +- RG-354: For the target architecture, release is blocked until remote requests and bytes are measured rather than estimated. +- RG-355: For the target architecture, release is blocked until background maintenance is either quiesced or reported. diff --git a/src/generate_research.py b/src/generate_research.py new file mode 100644 index 0000000..9305e02 --- /dev/null +++ b/src/generate_research.py @@ -0,0 +1,890 @@ +#!/usr/bin/env python3 +"""Generate the 2026 graph-engine research corpus. + +The generator is intentionally checked in beside the Markdown output so the +inventory, common audit controls, and minimum-line invariant remain reviewable. +Engine facts are compact inputs; prose, scorecards, test plans, and evidence +gaps are expanded deterministically. Generated claims retain an evidence +label and links to primary/official material wherever it exists. +""" + +from __future__ import annotations + +from dataclasses import dataclass +from pathlib import Path +from typing import Iterable + + +ROOT = Path(__file__).resolve().parents[1] / "docs" / "research" +RESEARCH_DATE = "2026-08-08" +MIN_LINES = 520 + + +@dataclass(frozen=True) +class Engine: + slug: str + name: str + family: str + status: str + model: str + language: str + storage: str + execution: str + transactions: str + distribution: str + object_store: str + license: str + scale: str + benchmark: str + verdict: str + facts: tuple[str, ...] + sources: tuple[tuple[str, str], ...] + + +ENGINES: tuple[Engine, ...] = ( + Engine("neo4j", "Neo4j", "native property graph", "active; calendar-versioned 2026 line", "labeled property graph", "Cypher 25 and frozen Cypher 5", "native block record store with page cache; sharded Infinigraph separates topology and properties", "cost-based optimizer with slotted, pipelined, and parallel runtimes", "ACID; clustered editions add consensus-backed availability", "standalone, clustered, composite databases, and Infinigraph automatic sharding", "not S3-native for the live query path; object storage is operational/backup infrastructure", "GPLv3 Community; commercial Enterprise/Infinigraph", "single-store formats have finite ID domains; Infinigraph is the 100-TB-plus horizontal path", "industry baseline with LDBC and vendor workloads, but edition and runtime must be pinned", "The ecosystem and Cypher compatibility bar are formidable; storage cost, JVM footprint, and distributed-license cost are openings for zu.", ("Neo4j 2026.02 defaults new deployments to Cypher 25 through the distributed configuration.", "The current manual distinguishes Community, Enterprise, and Infinigraph; benchmark results must never mix them.", "Infinigraph uses graph and property sharding rather than presenting one monolithic local store.", "Block format is the relevant current local format; deprecated high-limit claims must not be used as current evidence.", "Warm page-cache traversal is a strong baseline; cold S3 claims would be a category error."), (("Operations Manual", "https://neo4j.com/docs/operations-manual/current/introduction/"), ("Cypher version administration", "https://neo4j.com/docs/operations-manual/current/database-administration/syntax/"), ("Source repository", "https://github.com/neo4j/neo4j"))), + Engine("falkordb", "FalkorDB", "matrix property graph", "active; Rust transition and Redis-module lineage", "property graph represented with sparse matrices plus attribute stores", "openCypher with extensions; Bolt and RESP access", "sparse GraphBLAS adjacency matrices, Redis-derived persistence and auxiliary indices", "algebraic traversal plus a modern columnar/batch execution path", "MVCC direction is active; exact guarantees must be verified per release/deployment", "single node and commercial/cloud scale-out offerings; open core must be separated from service claims", "not an object-store-native live engine", "SSPLv1 in current official docs; commercial cloud terms separately", "excellent dense set-at-a-time traversal potential; PB evidence is not public", "vendor benchmark suite exists; require pinned queries, data, hardware, and durability", "FalkorDB is the most direct sparse-linear-algebra competitor and a required point/traversal baseline.", ("FalkorDB descends from RedisGraph and uses SuiteSparse:GraphBLAS concepts for adjacency.", "Sparse matrices can turn multi-source traversal into efficient set operations but may pay for property-heavy joins.", "The active rewrite makes version pinning essential because architecture and behavior are moving quickly.", "Redis module heritage affects persistence, memory accounting, and operational shape.", "GraphRAG marketing is not evidence for graph-kernel performance."), (("Official docs", "https://docs.falkordb.com/"), ("Source repository", "https://github.com/FalkorDB/FalkorDB"), ("GraphBLAS specification", "https://graphblas.org/"))), + Engine("ladybugdb", "LadybugDB", "embedded analytical property graph", "active successor fork in 2026", "schema-full property graph", "Cypher", "columnar disk storage with columnar CSR adjacency and join indices", "vectorized and factorized processing, specialized joins, multi-core parallelism", "serializable ACID according to official documentation", "embedded single-node, in-process; no native distributed transaction layer", "not object-store-native, though Parquet/Arrow/DuckDB interoperability is central", "MIT", "large single-node analytical graphs; PB/distributed claims are outside the current product shape", "must run Kuzu-derived LDBC and microbenchmarks from source with pinned commit", "This is zu's closest embedded architectural competitor and the primary fair same-machine benchmark.", ("Ladybug continues Kuzu's columnar CSR and factorized-execution lineage.", "The engine is designed for join-heavy analytical patterns rather than networked OLTP serving.", "Interoperability includes Parquet, Arrow, and DuckDB-oriented workflows.", "Multi-core execution changes the fairness rules: thread count and NUMA placement must be fixed.", "Fork freshness invalidates claims that the Kuzu lane is empty."), (("Official documentation", "https://docs.ladybugdb.com/"), ("Installation and releases", "https://docs.ladybugdb.com/installation/"), ("Source repository", "https://github.com/LadybugDB/ladybug"))), + Engine("kuzu", "Kuzu (archived)", "embedded analytical property graph", "archived 2025-10-10; historical baseline", "schema-full property graph", "Cypher", "columnar disk storage and CSR adjacency/join indices", "vectorized, factorized, multi-core query processor", "serializable ACID", "embedded single-node", "not object-store-native", "MIT", "single-node only", "Kuzu 0.9.0 is a reproducible historical baseline, not a current product", "Retain for regression and lineage attribution; do not present it as an active competitor.", ("The upstream repository is read-only.", "Kuzu introduced the factorized and CSR design now continued by LadybugDB.", "Its final line included full-text and vector extensions.", "Archived packages can still be benchmarked reproducibly if artifacts and compilers remain available.", "Security, compatibility, and support comparisons must label the lifecycle status."), (("Archived repository", "https://github.com/kuzudb/kuzu"), ("Kuzu system paper", "https://vldb.org/cidrdb/papers/2023/p48-jin.pdf"), ("Release archive", "https://github.com/kuzudb/kuzu/releases"))), + Engine("puppygraph", "PuppyGraph", "lakehouse graph query engine", "active commercial product", "logical property graph mapped over tabular lake/warehouse data", "openCypher and Gremlin-facing workflows", "does not own the system of record; reads external warehouses/lakes and builds query-serving structures", "distributed graph analytics and traversal over mapped relational data", "source-system semantics dominate; the graph layer is primarily analytical/read oriented", "cluster deployment with independent compute over external data", "directly relevant: queries data in lake/object-backed systems but is not simply an S3 adjacency store", "commercial proprietary", "vendor claims petabyte data and deep traversal; independent audited evidence is required", "benchmark must include source scan bytes, materialization, cache state, and warehouse cost", "PuppyGraph is the closest commercial graph-lake comparator for zu's remote profile.", ("PuppyGraph avoids graph ETL by mapping existing tables into a graph schema.", "Its architecture trades native ownership and OLTP control for governance and lakehouse reuse.", "Claims of petabyte scale describe the external-data architecture and need workload qualification.", "Cold-query performance depends on source layout, pruning, cache, network, and any acceleration state.", "Cost comparison must include the underlying warehouse or query service, not only PuppyGraph compute."), (("Official documentation", "https://docs.puppygraph.com/"), ("Getting started", "https://docs.puppygraph.com/getting-started/"), ("Graph algorithms", "https://docs.puppygraph.com/graph-algorithms/"))), + Engine("memgraph", "Memgraph", "in-memory operational property graph", "active", "property graph", "Cypher-compatible language and procedures", "in-memory transactional/analytical modes; RocksDB-backed on-disk transactional mode", "C++ execution with built-in traversals, query modules, triggers, and parallel runtime work", "snapshot isolation by default; durability differs materially across storage modes", "leader/replica high availability and read scaling; not a general sharded PB store", "not object-store-native", "Business Source License/community plus commercial features; pin exact edition", "RAM-bound mode targets low latency; on-disk mode broadens capacity with different behavior", "benchmark every storage mode separately and include WAL/snapshot settings", "Memgraph is the low-latency mutable baseline; zu must win resource efficiency without comparing unlike durability modes.", ("Transactional in-memory mode uses deltas plus WAL and snapshots.", "Analytical in-memory mode relaxes guarantees and therefore cannot be mixed into ACID charts.", "On-disk transactional mode serializes graph records into RocksDB.", "Replication supports synchronous, timeout, and asynchronous behavior with different commit semantics.", "Dynamic algorithms and triggers broaden workload scope beyond plain query execution."), (("Product architecture", "https://memgraph.com/memgraphdb"), ("Storage modes", "https://memgraph.com/blog/memgraph-storage-modes-explained"), ("Replication design", "https://memgraph.com/blog/implementing-data-replication"), ("Source repository", "https://github.com/memgraph/memgraph"))), + Engine("nebulagraph", "NebulaGraph", "distributed property graph", "active; Enterprise 5.2 was current in the 2025 review", "schema-full property graph", "GQL in Enterprise 5.x; nGQL in open-source lineage", "shared-nothing partitioned KV-oriented graph storage with prefix-scan formats and bucketed partitions in 5.x", "distributed vectorized execution, query-level memory control, pushdown, and graph-native plans", "Raft replication and distributed transactions vary by operation/version; verify exact contract", "compute/storage separation, partition buckets, Raft groups, multi-cluster management", "not S3-native in the query path", "Apache-2.0 open-source 3.x; Enterprise 5.x proprietary", "vendor describes 200-TB clusters; PB qualification not established", "separate open-source 3.x from Enterprise 5.x in every result", "Nebula is a major distributed/GQL comparator and a warning against hiding network traversal behind one latency number.", ("Enterprise 5.x was redesigned around ISO GQL rather than only adding surface syntax.", "The 5.x memory interchange format is described as Arrow-compatible Nebula Vector.", "Partitions are divided into fixed-size buckets to improve movement and rebalancing.", "Published 3x claims compare with its own previous version and are not competitor evidence.", "The most relevant zu lessons are batched storage pushdown and explicit query memory accounting."), (("5.0 technical preview", "https://nebula-graph.io/posts/technical-preview-of-nebulagraph-enterprise-v5.0"), ("2025 year review", "https://nebula-graph.io/posts/nebulagraph-2025-year-in-review-charting-a-new-era-of-graph-intelligence-and-ai-convergence"), ("Source repository", "https://github.com/vesoft-inc/nebula"))), + Engine("tigergraph", "TigerGraph", "distributed native property graph", "active; 4.2.4 released 2026-07-20", "typed property graph", "GSQL, openCypher, REST, GraphQL surfaces", "native distributed compressed graph storage; Savanna separates storage and compute", "C++ native parallel graph execution and compiled GSQL", "ACID/HA features are edition and topology dependent", "automatic partitioning, MPP execution, leaderless replicated self-managed architecture; Savanna workspaces", "Savanna is disaggregated but public docs do not establish an S3-range-native adjacency path", "commercial proprietary", "public material cites hundreds of billions of edges; exact audited configurations matter", "use LDBC disclosures and self-run compatible subsets; compiled-query warmup must be explicit", "TigerGraph sets the mature distributed analytics bar; zu's likely win is cost/resource efficiency and embedded simplicity, not every throughput regime.", ("GSE and GPE are implemented in C++.", "The database combines local storage and local computation in its classic architecture.", "Savanna introduces independent storage/compute scaling and read-write versus read-only workspaces.", "Automatic partitioning can redistribute data during cluster expansion or contraction.", "Vendor throughput claims require FDR-grade hardware, cost, replication, and query disclosure."), (("Current documentation", "https://www.tigergraph.com/docs/home/"), ("Internal architecture", "https://docs.tigergraph.com/tigergraph-server/current/intro/internal-architecture"), ("Savanna architecture", "https://tigergraph.com/docs/savanna/main/overview/architecture"), ("System paper", "https://arxiv.org/abs/1901.08248"))), + Engine("graphscope_flex", "GraphScope Flex Interactive", "distributed interactive graph system", "active Apache-2.0 project", "property graph", "openCypher, Gremlin, compiled stored procedures", "immutable and real-time mutable CSR storage components", "Seastar/hiactor share-nothing-per-core runtime, GAIA IR compiler, C++ code generation", "read/update/insert transaction types; exact isolation must be verified", "distributed service with per-core shards and scale-out deployment", "not object-store-native for interactive serving; GraphAr/lake integration is adjacent", "Apache-2.0", "audited LDBC SNB at SF1000 and hundreds of billions of edges", "audited LDBC results are the throughput credibility bar", "GraphScope is the strongest public audited throughput comparator and must not be reduced to a laptop microbenchmark.", ("The runtime uses Seastar's share-nothing SMP model.", "Storage source includes immutable_graph and rt_mutable_graph based on mutable CSR.", "The compiler maps Cypher/Gremlin through a common IR to runtimes.", "Stored procedures can be generated as C++ for predictable low overhead.", "LDBC FDRs report system cost and are more credible than isolated vendor charts."), (("Interactive introduction", "https://graphscope.io/docs/latest/flex/interactive_intro"), ("Implementation layout", "https://graphscope.io/docs/flex/interactive/development/dev_and_test"), ("LDBC audited results", "https://ldbcouncil.org/benchmarks/snb/interactive/"), ("Source repository", "https://github.com/alibaba/GraphScope"))), + Engine("janusgraph", "JanusGraph", "storage-agnostic distributed graph layer", "active 1.x", "property graph via TinkerPop", "Gremlin", "key-column-value abstraction over Cassandra/CQL, HBase, Bigtable, ScyllaDB, or BerkeleyDB; external mixed indexes", "JVM query execution near the application/server with backend round trips and caches", "semantics inherit backend limitations; not generally serializable/atomic across rows", "horizontal scale through chosen backend and stateless-ish JanusGraph servers", "possible indirectly through cloud backends, but not S3-native and pointer/request economics are unfavorable", "Apache-2.0", "large distributed capacity is plausible through backends; supernodes and bulk load have documented limits", "benchmark is a full stack: JanusGraph, backend, index service, consistency, and cache", "JanusGraph proves modular scale but also shows why a synchronous fine-grained storage SPI is a latency and operations trap.", ("Query execution, cache, and transactions run in the JanusGraph JVM.", "Persistence and mixed indexing are separate adapters and frequently separate clusters.", "Cassandra/HBase modes do not automatically provide serializable multi-row transactions.", "The docs warn that loading millions of edges into one vertex can fail for some backends.", "The external index adds consistency and operational dimensions to property filters."), (("Architecture", "https://docs.janusgraph.org/master/getting-started/architecture/"), ("Transactions", "https://docs.janusgraph.org/basics/transactions/"), ("Technical limitations", "https://docs.janusgraph.org/v1.1/advanced-topics/technical-limitations/"), ("Source repository", "https://github.com/JanusGraph/janusgraph"))), + Engine("apache_hugegraph", "Apache HugeGraph", "pluggable OLTP plus OLAP graph platform", "active Apache top-level project", "schema-full property graph", "Gremlin and openCypher", "RocksDB standalone; HStore distributed in current line; older backend matrix is no longer maintained", "TinkerPop-compatible OLTP engine plus Vermeer and Pregel-style distributed analytics", "backend- and mode-dependent; HStore uses distributed control/storage services", "PD plus HStore horizontal mode with HA", "not S3-native live serving; external storage is an ingest/analytics concern", "Apache-2.0", "official 2026 docs scope standalone below 4 TB and distributed below 1000 TB", "run server/HStore and analytics components as separate systems", "HugeGraph's explicit 1000-TB envelope is highly relevant, but it reaches it with a distributed store rather than cheap object-only serving.", ("Current 1.7-era docs removed legacy MySQL/PostgreSQL/Cassandra adapters from the maintained path.", "HugeGraph Server separates core, backend, and REST API layers.", "HStore requires PD and Store deployments.", "The platform distinguishes OLTP database, in-memory Vermeer, and distributed HugeGraph-Computer.", "A 1000-TB advertised boundary is close to PB but not proof at trillion-edge workload shape."), (("2026 introduction", "https://hugegraph.apache.org/docs/introduction/"), ("Architecture", "https://hugegraph.apache.org/docs/guides/architectural/"), ("FAQ and scale guidance", "https://hugegraph.apache.org/docs/guides/faq/"), ("Source repository", "https://github.com/apache/hugegraph"))), + Engine("tugraph", "TuGraph", "HTAP native property graph", "active", "property graph", "Cypher plus procedures and APIs", "native C++ graph storage with local and enterprise distributed modes", "low-latency transactional traversal plus analytical engine and plugins", "ACID in local engine; HA/distributed semantics are edition dependent", "community single-node/HA features and enterprise distributed architecture", "not S3-native", "Apache-2.0 Community; commercial Enterprise", "large production claims exist; PB public qualification is insufficient", "use LDBC implementation disclosures and pin Community versus Enterprise", "TuGraph is a serious C++ HTAP comparator, particularly for local mutable traversal and compiled procedures.", ("TuGraph originated at Ant Group and Tsinghua and is used in risk-control settings.", "The product presents database, analytics, visualization, and operations as one system.", "Stored procedures can avoid general query-planning overhead for hot paths.", "Community and Enterprise architecture claims must be separated.", "Chinese and English documentation can diverge; cite exact versioned pages."), (("Product overview", "https://tugraph.tech/product/db?lang=en-US"), ("Documentation", "https://tugraph-db.readthedocs.io/en/latest/2.introduction/index.html"), ("Source repository", "https://github.com/TuGraph-family/tugraph-db"))), + Engine("ultipa", "Ultipa Powerhouse", "hybrid distributed and high-density graph system", "active v5 line", "property graph", "ISO GQL and UQL", "node-centric shards plus selectively loaded high-density compute copies", "name-server planning; shard execution; HDC servers for deep algorithms and queries", "official docs claim ACID and expose GQL transactions/savepoints", "shard, name, meta, and HDC server roles", "not presented as S3-native live storage", "commercial proprietary", "billions of nodes; no public PB proof", "GQL conformance can be tested; performance claims require independent harness", "Ultipa is important for its explicit two-mode design: economical sharded authority plus high-density acceleration.", ("Sharding distributes nodes by a configurable key and function.", "HDC selectively loads graph data and can synchronize in real time.", "The product claims tenfold-or-more HDC gains over shard execution; treat as vendor claim.", "Its published GQL conformance declaration is unusually detailed.", "Vector, full-text, ontology, federation, triggers, and procedures broaden parity scope."), (("Powerhouse architecture", "https://www.ultipa.com/docs/v5.3/graph-database"), ("GQL introduction", "https://www.ultipa.com/docs/v5/gql"), ("GQL conformance", "https://www.ultipa.com/docs/gql/gql-conformance"))), + Engine("arangodb", "ArangoDB", "native multi-model database", "active", "document, key/value, graph, vector", "AQL", "RocksDB-backed collections with edge documents and indexes", "AQL optimizer and cluster execution for traversal, joins, search, and documents", "ACID with scope/cluster caveats defined by edition and transaction pattern", "CP master/master cluster with coordinators, DB-Servers, agency; SmartGraphs optimize locality", "not S3-native live serving", "source-available/community and commercial Enterprise terms; pin version", "horizontal document/graph scale; efficient graph scale depends on sharding locality", "Community General Graph and Enterprise SmartGraph are distinct baselines", "ArangoDB shows the benefit and cost of multi-model integration; SmartGraph locality is a mandatory partitioning comparison.", ("SmartGraphs co-locate vertices and intra-partition edges by a chosen attribute.", "Satellite collections replicate small shared data to DB-Servers.", "Disjoint SmartGraphs prohibit cross-partition edges for fully local traversal.", "The smart sharding attribute and shard count are effectively model commitments.", "A graph benchmark that ignores cross-shard edge ratio hides the central design tradeoff."), (("Cluster architecture", "https://docs.arango.ai/arangodb/stable/deploy/cluster/"), ("SmartGraphs", "https://docs.arango.ai/arangodb/stable/graphs/smartgraphs/"), ("Source repository", "https://github.com/arangodb/arangodb"))), + Engine("dgraph", "Dgraph", "distributed predicate-sharded graph database", "active", "RDF-like directed graph exposed through DQL and GraphQL", "DQL, GraphQL, admin APIs", "Badger-derived LSM KV storage; predicates assigned to Alpha Raft groups", "distributed query execution across predicate owners", "ACID with snapshot isolation and conflict detection; linearizable operations described", "Zero control plane plus Alpha Raft groups; predicate sharding and rebalancing", "not S3-native; backups may use object storage", "Apache-2.0 core", "horizontal scale, but hot predicates and cross-group queries are key constraints", "measure predicate skew, network fanout, Raft durability, and GraphQL translation separately", "Dgraph is the canonical predicate-sharding counterpoint to source-range adjacency partitioning.", ("Zero allocates timestamps, UIDs, membership, and predicate placement.", "Each Alpha group owns predicates and is independently replicated through Raft.", "Predicate sharding can create hot groups when relationship types are skewed.", "Queries crossing predicates become distributed even when vertex neighborhoods are otherwise local.", "GraphQL convenience must not be confused with native graph query expressiveness."), (("Architecture and consistency", "https://www.dgraph.io/installation/dgraph-architecture/"), ("Source repository", "https://github.com/dgraph-io/dgraph"))), + Engine("orientdb", "OrientDB", "multi-model graph/document database", "active 4.0 line but legacy architecture remains relevant", "document and graph", "OrientDB SQL and Gremlin compatibility surfaces", "record clusters with physical RIDs and native links", "Java query engine and direct record traversal", "ACID local transactions; distributed multi-master/quorum behavior has constraints", "Hazelcast-coordinated multi-master replication and class/cluster sharding", "not S3-native", "Apache-2.0 Community; historical commercial split", "distributed scale constrained by manual sharding/index limitations in documented designs", "use as compatibility/resource baseline, not a PB front-runner", "OrientDB is valuable chiefly as a warning about physical identity, multi-master conflict handling, and application-directed sharding.", ("RIDs encode cluster and position, coupling identity to physical layout concerns.", "Distributed cluster ownership assigns record clusters to servers.", "Older docs state unique indexes are not globally safe across sharded classes.", "Majority write quorum is required to avoid unsafe split-brain operation.", "The 4.0 documentation lifecycle and actual implementation maturity need explicit verification."), (("Current documentation", "https://orientdb.dev/docs/develop/"), ("Distributed architecture", "https://orientdb.dev/docs/3.0.x/distributed/Distributed-Architecture.html"), ("Sharding", "https://orientdb.dev/docs/develop/distributed/Distributed-Sharding.html"))), + Engine("arcadedb", "ArcadeDB", "multi-model native graph database", "active 26.x", "graph, document, key/value, vector, time-series, geospatial", "SQL, Cypher, Gremlin, GraphQL and wire-protocol compatibility subsets", "custom low-level Java storage with physical graph links and transactional indexes", "parallel SQL plus native traversal and multi-model operators", "ACID local; Raft HA from 26.4.1", "leader/replica Raft HA scales reads and availability, not sharded capacity", "not S3-native", "Apache-2.0", "single-database capacity plus replicated copies; no PB claim", "benchmark embedded and server modes; disclose protocol translation", "ArcadeDB is a strong low-resource JVM/multi-model comparison and a fast-moving 2026 target.", ("ArcadeDB is a conceptual successor/fork lineage from OrientDB but uses a new engine.", "Official docs describe graph edges as physical links enabling constant-hop lookup.", "All models share one transaction and one storage engine.", "Apache Ratis replaced the previous HA protocol in 26.4.1.", "Six query/protocol surfaces vary in completeness and require conformance, not checkbox parity."), (("What is ArcadeDB", "https://docs.arcadedb.com/arcadedb/tutorials/what-is-arcadedb"), ("HA concepts", "https://docs.arcadedb.com/arcadedb/concepts/high-availability"), ("Source repository", "https://github.com/ArcadeData/arcadedb"))), + Engine("typedb", "TypeDB", "typed polymorphic database", "active 3.x; clustering was experimental/alpha in current docs", "entities, relations, attributes, roles, and strong type system", "TypeQL pipelines", "RocksDB foundation", "schema-aware inference and pattern query pipeline", "ACID to snapshot isolation; exclusive schema transactions", "Raft replicated leader/follower cluster; writes remain leader-bound; clustering status must be pinned", "not S3-native", "MPL-2.0 Community; Enterprise/Cloud for clustering", "read scale through replication, not data sharding; capacity remains full-copy bounded", "semantic/inference workloads require a separate corpus from ordinary LPG traversal", "TypeDB competes on modeling correctness and inference, not PB topology economics; zu should borrow explicit schema invariants, not its full-copy scale model.", ("Read, write, and schema transactions are distinct.", "Schema transactions exclude concurrent write/schema transactions.", "Cluster followers can serve reads while one leader handles writes.", "Current clustering documentation warns that the feature is alpha/experimental.", "TypeQL 3 expresses staged data and stream transformations."), (("Server overview", "https://typedb.com/docs/core-concepts/typedb/overview"), ("Transactions", "https://typedb.com/docs/core-concepts/typedb/transactions/"), ("Horizontal scaling", "https://typedb.com/docs/core-concepts/typedb/horizontal-scaling/"), ("Cluster status", "https://typedb.com/docs/reference/typedb-cluster/"))), + Engine("terminusdb", "TerminusDB", "version-controlled document graph database", "active", "typed documents decomposed into graph triples", "WOQL/Datalog, GraphQL, document APIs", "immutable layered triple store optimized for revision history", "Datalog pattern matching plus document assembly", "ACID immutable commits with branching, diff, merge, and time travel", "federation/version exchange rather than transparent sharded query execution", "immutable objects are conceptually compatible with object storage, but current serving is not documented as S3-native", "Apache-2.0 current repository", "versioned knowledge graphs; not demonstrated at PB interactive topology scale", "benchmark revision/diff/merge separately from traversal", "TerminusDB is the strongest lesson for immutable lineage, content addressing, and branchable metadata.", ("Documents are the API while triples are the underlying graph representation.", "A closed-world schema enables stronger validation than open RDF stores.", "Every change forms immutable history suitable for diff and rollback.", "The Datalog engine is implemented around Prolog lineage.", "Version-control features increase retained bytes and GC complexity, which must enter cost models."), (("At a glance", "https://terminusdb.org/docs/at-a-glance/"), ("Internals", "https://terminusdb.org/docs/terminusdb-internals/"), ("Knowledge graph model", "https://terminusdb.org/docs/knowledge-graph-database/"), ("Source repository", "https://github.com/terminusdb/terminusdb"))), + Engine("cozodb", "CozoDB", "embedded relational-graph-vector database", "maintenance activity appears limited after late 2024; verify before adoption", "relations queried recursively as graphs", "Datalog", "pluggable RocksDB, SQLite, in-memory, and other KV backends by build", "compiled Datalog with joins, recursion, algorithms, and vector indices", "backend-dependent transactions with a unified embedded API", "single-process/embedded; TiKV-era distributed options are not a simple turnkey cluster", "not S3-native", "MPL-2.0", "local and backend-dependent; no PB evidence", "include recursive-query and algorithm microbenchmarks, but flag lifecycle risk", "CozoDB is a compact Datalog design reference; limited recent activity weakens it as a production comparator.", ("Datalog makes recursion and joins first-class rather than special traversal syntax.", "Multiple storage engines complicate universal performance and durability statements.", "The product combines relational, graph, and vector operations in one embedded interface.", "Repository recency is an adoption risk and should be rechecked at benchmark freeze.", "Its concise query/runtime design is relevant to zu's fixed-point operator work."), (("Manual", "https://docs.cozodb.org/"), ("Source repository", "https://github.com/cozodb/cozo"))), + Engine("surrealdb", "SurrealDB", "distributed multi-model database", "active 3.x", "document core with graph, relational, vector, time-series, and geospatial models", "SurrealQL and GraphQL", "RocksDB single node, SurrealKV beta, SurrealMX memory, IndexedDB browser, SurrealDS distributed", "Rust parser/executor/iterator/document pipeline over transactional KV ranges", "snapshot isolation with write-write conflict detection across supported backends", "compute/storage separation; SurrealDS for multi-node Enterprise/Cloud", "2026 materials describe object-storage-based distributed storage, but public internals and cost evidence are incomplete", "Business Source/other mixed licensing by component and edition; pin exact artifacts", "distributed promises are significant; independent PB graph evidence absent", "test native RELATE traversal separately from generic document links and cloud-only SurrealDS", "SurrealDB is a high-priority Rust/multi-model competitor and a useful check on zu's storage-query boundary.", ("The query layer exposes the same semantics over several storage engines.", "Graph edges are documents with their own properties.", "The architecture explicitly separates parser, executor, iterator, document processing, and storage API.", "SurrealDS is the distributed path; RocksDB is recommended for current single-node production.", "Object-storage claims need request, cache, consistency, and cold-latency disclosure."), (("Architecture", "https://surrealdb.com/docs/architecture"), ("Graph model", "https://surrealdb.com/docs/learn/data-models/graph/overview"), ("Source repository", "https://github.com/surrealdb/surrealdb"), ("2026 whitepaper", "https://surrealdb.com/static/surrealdb-context-layer-whitepaper.pdf"))), + Engine("helixdb", "HelixDB", "Rust graph-vector database", "active and fast-moving; 3.0.2 listed in May 2026", "graph plus vector with KV/document/relational ambitions", "dynamic JSON query API and generated/type-safe SDK DSL", "LMDB in public repository descriptions; cloud site now describes object-storage architecture", "Rust native stored/dynamic query execution combining traversal, vector, and search", "transaction semantics are insufficiently documented for strong comparison", "local server and commercial cloud; public distributed mechanics are incomplete", "current marketing says built on object storage, making it directly relevant, but technical evidence is sparse", "license signals conflict between repository API metadata and README wording; verify the exact revision", "early-stage; no credible PB proof", "reproduce vendor claims and include compile/deploy, dynamic query, and durability behavior", "HelixDB is an emerging direct Rust/object-storage/GraphRAG competitor, but unknowns must be treated as unknowns.", ("The public engine is written in Rust and historically used LMDB.", "The v2 API can submit dynamic JSON query plans and also supports compiled stored queries.", "Graph and vector operations are intended to compose in one request.", "Official current pages advertise object-storage-backed cloud operation without enough persistence protocol detail.", "License and version documentation changed quickly in 2026 and must be captured by commit digest."), (("Source repository", "https://github.com/HelixDB/helix-db"), ("Official documentation index", "https://docs.helix-db.com/llms.txt"), ("Current product architecture", "https://www.helix-db.com/"), ("Rust SDK", "https://docs.rs/helix-db/latest/helix_db/"))), + Engine("millenniumdb", "MillenniumDB", "research persistent graph database", "active research project with small community", "property-domain graph supporting RDF and property graph ideas", "custom query language with basic graph patterns and paths", "relations indexed by B+ trees with a fixed-size buffer manager", "relational-style optimizer plus worst-case-oriented graph techniques", "persistent single-node transaction detail is less mature than commercial OLTP systems", "single-node", "not S3-native", "GPL-2.0 repository", "research-scale, no PB serving claim", "use for optimizer/index research comparisons, not product TCO claims", "MillenniumDB is a valuable research baseline for succinct indexes and path algorithms, though not a deployment peer.", ("The system stores graph components as relations over B+ trees.", "A fixed-size buffer controls what is resident in memory.", "The design combines classical DBMS techniques with graph-query theory.", "It supports a richer domain graph model than a plain labeled property graph.", "Small project size increases operational and compatibility uncertainty."), (("Systems paper", "https://doi.org/10.1162/dint_a_00229"), ("Source repository", "https://github.com/MillenniumDB/MillenniumDB"))), + Engine("duckpgq", "DuckPGQ", "analytical SQL/PGQ extension", "active CWI project", "transient property graph declarations over DuckDB tables", "SQL/PGQ", "DuckDB columnar storage plus per-connection in-memory CSR structures", "DuckDB vectorized SQL extended with graph matching and path algorithms", "inherits DuckDB transaction model; graph declarations are connection-scoped", "embedded single-node", "DuckDB can query object files, but DuckPGQ CSR construction is not an S3-native persistent graph index", "MIT", "single-node analytics; CSR memory limits matter", "include CSR-build time and memory, never report query-only numbers alone", "DuckPGQ is the fairest relational/SQL standards baseline and exposes the cost of rebuilding topology indexes.", ("Property graph definitions are transient and live for the connection.", "The engine creates CSR structures from relational tables.", "SQL/PGQ enables graph patterns without a separate graph database.", "Multi-source BFS benefits only for suitable source batches and hardware.", "End-to-end benchmarking must charge table scan, CSR construction, and query execution."), (("Official site", "https://duckpgq.org/"), ("Property graph docs", "https://duckpgq.org/documentation/property_graph/"), ("CWI paper", "https://ir.cwi.nl/pub/33317/33317.pdf"), ("Source repository", "https://github.com/cwida/duckpgq-extension"))), + Engine("apache_age", "Apache AGE", "PostgreSQL graph extension", "active Apache project", "labeled property graph in PostgreSQL", "openCypher embedded in SQL function calls", "PostgreSQL heap/index/WAL storage with agtype properties and graph tables", "Cypher parser/transformer/planner/executor integrated into PostgreSQL", "inherits PostgreSQL ACID transactions", "PostgreSQL HA options; AGE tables are not currently transparently distributed by Citus", "not S3-native live serving", "Apache-2.0", "PostgreSQL-node scale; no native PB graph sharding", "compare both graph-only and hybrid SQL/Cypher, including join and JSON-property costs", "AGE is the strongest open PostgreSQL extension baseline; zu should win deep traversal and storage density while conceding ecosystem maturity.", ("Cypher is transformed into PostgreSQL query trees and graph plan nodes.", "Every component uses PostgreSQL's transaction and cache layers.", "Properties use a JSON-like agtype representation.", "The official FAQ acknowledges relational join limitations for graph workloads.", "Citus compatibility does not currently make AGE graph tables distributed."), (("Architecture overview", "https://age.apache.org/overview/"), ("FAQ and limitations", "https://age.apache.org/faq/"), ("Source repository", "https://github.com/apache/age"))), + Engine("agensgraph", "AgensGraph", "PostgreSQL-derived multi-model graph database", "active 2.17 documentation line", "graph, relational, JSON document", "SQL and Cypher, composable in one query", "PostgreSQL-derived storage, WAL, and indexes with graph extensions", "hybrid relational/graph planner and graph indexes", "ACID inherited from PostgreSQL", "active-standby HA; no native horizontally sharded property graph in public docs", "not S3-native", "open-source/community plus commercial ecosystem; verify package license", "single-primary scale", "hybrid-query correctness and optimizer quality are the main comparisons", "AgensGraph provides a mature SQL/Cypher hybrid baseline but is not a PB or object-storage competitor.", ("Graphs are first-class database objects rather than only a function wrapper.", "Graph and relational expressions can appear in one query.", "Vertex and edge indexes accelerate graph access.", "PostgreSQL operational tooling is a major adoption advantage.", "The active-standby model improves availability but not write or capacity scale."), (("Source repository", "https://github.com/skaiworldwide-oss/agensgraph"), ("Project lineage repository", "https://github.com/bitnine-oss/agensgraph"))), + Engine("amazon_neptune", "Amazon Neptune Database", "managed cloud graph database", "active AWS service", "property graph and RDF", "Gremlin, openCypher, SPARQL", "distributed shared SSD-backed cluster volume, six copies across three AZs", "managed DFE query engine and language-specific execution", "ACID with documented language-specific isolation/locking semantics", "one writer, up to fifteen read replicas sharing storage; automatic 10-GiB segment growth", "backups are on S3, but live database storage is a managed shared block service, not user-priced S3 objects", "proprietary managed service", "128-TiB cluster-volume maximum in most regions", "managed-service comparison must include instance, I/O/storage mode, replicas, and network", "Neptune is a production durability/availability baseline but cannot satisfy a 1-PB single-graph target today.", ("Cluster storage grows in 10-GiB segments.", "Each storage segment has six copies across three availability zones.", "A cluster has one write primary and as many as fifteen read replicas.", "I/O-Optimized pricing removes per-I/O charges in exchange for higher storage price.", "Deleting data does not reduce the billed storage high-water mark."), (("Service overview", "https://docs.aws.amazon.com/neptune/latest/userguide/intro.html"), ("Storage architecture", "https://docs.aws.amazon.com/neptune/latest/userguide/feature-overview-storage.html"), ("Transactions", "https://docs.aws.amazon.com/neptune/latest/userguide/transactions.html"))), + Engine("amazon_neptune_analytics", "Amazon Neptune Analytics", "managed in-memory graph analytics", "active AWS service", "property graph analytics", "openCypher procedures and queries", "provisioned memory-optimized graph loaded from Neptune or S3", "in-memory algorithms, low-latency analytical queries, vector search", "analytics service rather than primary OLTP authority", "managed provisioned graph endpoint", "S3 is an import/source path, not demand-paged live graph storage", "proprietary managed service", "capacity bound by provisioned analytics graph sizes; not PB resident", "charge load time, provisioned capacity, and algorithm duration", "Neptune Analytics is a strong hot analytical baseline but its economics fundamentally differ from S3-authoritative cold data.", ("The service loads graph data into memory.", "It complements rather than replaces Neptune Database.", "More than twenty-five algorithm variants are exposed as procedures.", "Vector search can participate in graph traversals.", "Public/private endpoint and IAM overhead belong in end-to-end latency."), (("Service overview", "https://docs.aws.amazon.com/neptune-analytics/latest/userguide/what-is-neptune-analytics.html"), ("Algorithms", "https://docs.aws.amazon.com/neptune-analytics/latest/userguide/algorithms.html"))), + Engine("google_spanner_graph", "Google Cloud Spanner Graph", "managed relational-property-graph database", "active Enterprise/Enterprise Plus feature; docs updated 2026-07-22", "property graph mapped over Spanner tables", "ISO GQL-compatible interface plus SQL interoperability", "Spanner distributed relational storage with graph-optimized enhancements", "distributed SQL/GQL planning and on-demand graph algorithms", "Spanner external consistency and transactions", "transparent sharding and managed scale-out", "managed storage is not exposed as fixed-cost S3 object access", "proprietary managed service", "algorithms documented for tens of billions of edges; no public PB proof", "compare query and algorithm compute separately; include Spanner edition and processing units", "Spanner Graph is the standards and managed-consistency baseline; zu's opening is cost, portability, and graph-native density.", ("Property graph schemas can map existing relational tables without migration.", "GQL and SQL can be selected per workload.", "Graph algorithms use dedicated on-demand compute with limited impact on transactions.", "Transparent sharding removes user placement control but not cross-shard communication cost.", "The graph feature requires paid Spanner editions."), (("2026 overview", "https://docs.cloud.google.com/spanner/docs/graph/overview"), ("Graph schema", "https://cloud.google.com/spanner/docs/graph/schema-overview"))), + Engine("azure_cosmosdb_gremlin", "Azure Cosmos DB for Apache Gremlin", "managed partitioned multi-model graph API", "active", "property graph stored as JSON documents", "Gremlin subset", "Cosmos DB hash-partitioned document store; outgoing edges co-located with source", "Gremlin translation over partitioned document operations", "Cosmos consistency levels and transactional-batch boundaries; graph-wide ACID is not implied", "automatic partitioning by user-chosen key", "managed cloud storage, not an S3-native portable engine", "proprietary managed service", "large horizontal capacity; graph latency is sensitive to partition key and direction", "report request units, partitions touched, throttling, and retry latency", "Cosmos is the clearest counterexample showing why edge direction and partition-key-aware planning are mandatory.", ("Vertices and edges are JSON documents.", "Outgoing edges are stored with their source vertex.", "Incoming traversal can fan out across partitions and be expensive.", "Supplying vertex ID without partition key loses routing precision.", "RU cost is an essential benchmark metric, not ancillary billing detail."), (("Partitioning", "https://learn.microsoft.com/en-us/azure/cosmos-db/gremlin/partitioning"), ("Gremlin support", "https://learn.microsoft.com/en-us/azure/cosmos-db/gremlin/support"))), + Engine("microsoft_fabric_graph", "Graph in Microsoft Fabric", "lakehouse graph analytics", "active 2026 feature", "labeled property graph built from OneLake tables", "ISO GQL subset, visual builder, REST, NL2GQL", "OneLake tabular source plus an ingested read-optimized traversal representation", "scale-out graph pattern and traversal engine", "read-oriented analytics; current docs do not expose general graph DML transactions", "managed scale-out within Fabric", "directly lake/object aligned through OneLake, but materializes a queryable graph", "proprietary managed service", "officially targets billions of relationships; PB evidence absent", "include graph build/rebuild, capacity units, schema evolution, and cold/warm state", "Fabric Graph is a new direct lakehouse competitor and validates GQL plus read-optimized materialization over object-backed tables.", ("Saving a graph model ingests source tables into a traversal-optimized graph.", "Current documentation says schema evolution requires reingestion into a new model.", "GQL, visual query building, and REST share one execution layer.", "Set operations and mutations have documented limitations.", "OneLake authority does not eliminate the cost and freshness semantics of the derived graph."), (("Architecture", "https://learn.microsoft.com/en-us/fabric/graph/how-graph-works"), ("Overview", "https://learn.microsoft.com/en-us/fabric/graph/overview"), ("GQL guide", "https://learn.microsoft.com/en-us/fabric/graph/gql-language-guide"))), + Engine("oracle_property_graph", "Oracle Database Property Graph", "relational-integrated graph platform", "active Oracle Database 26ai line", "SQL property graph and property graph analytics", "SQL/PGQ GRAPH_TABLE, PGQL, openCypher surfaces by component", "graph declarations over Oracle relational tables; optional PGX in-memory graph server", "in-database graph matching plus PGX analytical algorithms", "inherits Oracle Database ACID for stored tables; PGX copies have synchronization semantics", "Oracle RAC/Exadata/cloud database scale plus separate graph server", "object storage may feed/load data, not the primary low-latency graph index", "commercial proprietary", "large enterprise scale but public PB interactive evidence is workload-specific", "separate in-database query from PGX-loaded algorithm execution", "Oracle is the mature SQL/PGQ and enterprise-integration baseline; it also demonstrates the cost of maintaining an analytical graph projection.", ("SQL property graphs can be defined directly over existing relational schema.", "GRAPH_TABLE performs pattern matching inside SQL.", "PGX must load a graph for specialized analytics.", "Periodic PGX refresh creates freshness and duplicate-storage considerations.", "Database and graph-server resources must both enter TCO."), (("26ai property graph introduction", "https://docs.oracle.com/en/database/oracle/property-graph/26.1/spgdg/introduction-property-graphs.html"), ("Current property graph releases", "https://docs.oracle.com/en/database/oracle/property-graph/"))), + Engine("sap_hana_graph", "SAP HANA Cloud Property Graph Engine", "in-memory relational-integrated graph engine", "active QRC 1/2026", "property graph workspace over HANA tables", "openCypher subset, GraphScript, SQL", "SAP HANA columnar/in-memory relational storage", "graph workspace execution and GraphScript stored procedures", "inherits HANA database transactions for source data", "HANA scale-up/scale-out deployment depending edition", "not S3-native live serving", "commercial proprietary", "enterprise analytical scale; no public PB graph evidence", "measure graph workspace creation, memory footprint, and mixed SQL/graph execution", "HANA Graph is a strong in-memory integrated baseline, but resource cost is the likely zu differentiator.", ("Graph workspaces map relational tables to vertices and edges.", "GraphScript provides procedural graph algorithms close to data.", "The current engine exposes an openCypher interface with documented subset semantics.", "In-memory columnar storage favors property scans but has a high capacity price.", "Graph plus SQL interoperability is its primary systems advantage."), (("QRC 1/2026 engine reference", "https://help.sap.com/docs/hana-cloud-database/sap-hana-cloud-sap-hana-database-property-graph-engine-reference/introduction"),)), + Engine("stardog", "Stardog", "enterprise RDF knowledge graph platform", "active 12.x-era platform", "RDF knowledge graph with virtual graphs and reasoning", "SPARQL 1.1, paths, rules, APIs", "proprietary native RDF storage plus virtualized external sources", "cost-based SPARQL, path queries, reasoning, virtualization", "ACID database transactions; cluster uses coordinated commit", "HA cluster and federated/virtual query capabilities", "not S3-native adjacency serving; cloud deployment and backups may use object storage", "commercial proprietary", "enterprise knowledge graphs; PB interactive claim not public", "benchmark SPARQL, reasoning, virtualization, and materialized data separately", "Stardog is the enterprise semantic/federation baseline rather than a direct LPG traversal peer.", ("SPARQL 1.1 queries can enable OWL/rule reasoning.", "SERVICE supports federated SPARQL endpoints.", "Virtual graphs avoid copying some relational data but inherit source latency.", "Stardog Cluster records committed transaction identity in ZooKeeper.", "Version 12 improved two-phase-commit lock behavior for large transactions."), (("Current docs", "https://docs.stardog.com/"), ("Query engine", "https://docs.stardog.com/query-stardog/"), ("Cluster operations", "https://docs.stardog.com/high-availability-cluster/operating-the-cluster/"))), + Engine("ontotext_graphdb", "Ontotext GraphDB", "RDF store and reasoner", "active 11.x", "RDF quads with inferred closure", "SPARQL 1.1 and RDF4J APIs", "TRREE storage with POS/PSO/context indices, entity IDs, page cache", "RDF4J query layer plus forward-chaining materialization", "transactional repository; inference closure updates at mutation boundaries", "Raft-based HA cluster in current Enterprise line", "not S3-native live serving", "commercial editions with a free edition", "large RDF stores; audited LDBC SNB result exists but workload/language fit must be examined", "include materialization time/space and inferred versus explicit query modes", "GraphDB is the principal materialized-reasoning baseline and a lesson in separating explicit from derived bytes.", ("GraphDB implements the RDF4J SAIL interface.", "TRREE performs forward-chaining materialization.", "Storage historically uses two main statement orderings plus context indices.", "Entity pools map RDF terms to compact numeric IDs.", "Raft clustering improves HA but does not imply data sharding."), (("11.1 cluster overview", "https://graphdb.ontotext.com/documentation/11.1/cluster-basics.html"), ("Architecture", "https://graphdb.ontotext.com/documentation/10.7/"), ("LDBC results", "https://ldbcouncil.org/benchmarks/snb/interactive/"))), + Engine("apache_jena_tdb2", "Apache Jena TDB2", "embedded RDF store", "active Apache project", "RDF triples and quads", "SPARQL 1.1 and Jena APIs", "custom node table plus multiple B+tree tuple indexes; memory-mapped files", "statistics-based basic-graph-pattern optimization", "serializable ACID; copy-on-write MVCC; multiple readers and one writer", "single JVM; Fuseki provides network access, not distributed storage", "not S3-native", "Apache-2.0", "single-node and filesystem-bound", "strong correctness/reference baseline for RDF, not PB latency competitor", "TDB2 is a valuable compact local-store reference for CoW MVCC, dictionary IDs, and tuple permutations.", ("RDF terms map to eight-byte NodeIds with selected scalar values inlined.", "Triples and quads are stored as full tuple indexes rather than a heap plus secondary indexes.", "TDB2 only permits transactional operation.", "One JVM owns a database directory to avoid corruption.", "Compaction creates numbered complete generations."), (("Architecture", "https://jena.apache.org/documentation/tdb/architecture.html"), ("Transactions", "https://jena.apache.org/documentation/tdb/tdb_transactions.html"), ("Administration", "https://jena.apache.org/documentation/tdb2/tdb2_admin.html"), ("Source repository", "https://github.com/apache/jena"))), + Engine("openlink_virtuoso", "OpenLink Virtuoso", "multi-model SQL/RDF server", "active commercial/open-source lineage", "relational, RDF quad, XML, text", "SQL, SPARQL, SPASQL", "column-oriented/row database structures with RDF quad indices", "vectorized SQL/SPARQL optimizer and cluster editions", "ACID DBMS transactions", "Enterprise cluster and replication options", "not S3-native", "GPL open-source edition; commercial Enterprise", "very large public RDF deployments, but PB interactive evidence is not current", "use WatDiv/BSBM plus SQL/RDF hybrid cases and pin edition", "Virtuoso is the long-lived high-scale RDF/SQL baseline and a source of index-ordering lessons.", ("The RDF quad table uses carefully chosen composite index permutations.", "Predicate clustering improves many RDF access patterns.", "SPARQL can be embedded in SQL and relational data can be exposed as RDF views.", "Open-source and commercial cluster capabilities differ.", "Old documentation demands source/version verification before treating any limit as current."), (("Official manual", "https://docs.openlinksw.com/virtuoso/index/"), ("RDF index scheme", "https://docs.openlinksw.com/virtuoso/rdfperfrdfscheme/"), ("RDF data management", "https://docs.openlinksw.com/virtuoso/ch-rdfandsparql/"))), + Engine("oxigraph", "Oxigraph", "embedded Rust RDF store", "active and explicitly still optimizing", "RDF triples/quads", "SPARQL 1.1", "RocksDB persistent backend or in-memory store with encoded term dictionaries and tuple indices", "Rust SPARQL parser/evaluator", "transactional KV-backed updates; exact isolation should be tested", "single-node library/server", "not S3-native", "Apache-2.0 and MIT dual licensing", "single-node; no PB proof", "conformance and resource efficiency matter more than headline throughput", "Oxigraph is the closest Rust RDF implementation reference and a useful fuzz/conformance comparator.", ("The project emphasizes standards compliance and safety.", "It implements SPARQL query, update, federation, and graph-store protocols.", "Persistent mode builds on RocksDB.", "Official README warns query evaluation is not fully optimized.", "Rust library embedding makes process overhead comparisons fair."), (("Source repository", "https://github.com/oxigraph/oxigraph"), ("Project docs", "https://docs.rs/oxigraph/"))), + Engine("allegrograph", "AllegroGraph", "commercial RDF/knowledge graph database", "active 9.x line", "RDF quads, JSON-LD documents, vector/geospatial extensions", "SPARQL, Prolog, APIs", "native persistent triple/quad store", "SPARQL plus reasoning, federation, and graph analytics", "transactional commits", "warm-standby replication and distributed/federated features", "not S3-native live serving", "commercial proprietary with free-tier terms", "large knowledge graphs; current PB evidence unavailable", "benchmark RDF semantics, reasoning, vector, and replication independently", "AllegroGraph matters for semantic workloads and mature operational features, not as the primary LPG latency target.", ("Replication is transactionally consistent from primary to replicas.", "Transaction log archives support recovery and synchronization.", "The engine integrates Common Lisp and Prolog-era reasoning strengths.", "JSON-LD document access broadens the data model.", "Current performance claims require reproducible datasets and licensed configuration disclosure."), (("Current replication", "https://franz.com/agraph/support/documentation/replication.html"), ("Documentation", "https://franz.com/agraph/support/documentation/"))), + Engine("blazegraph", "Blazegraph (legacy)", "RDF graph database", "archived repository; historical benchmark baseline", "RDF triples/quads and property-graph integrations", "SPARQL; historical Blueprints/Gremlin integrations", "B+tree-oriented journal storage", "SPARQL optimizer and optional GPU/cluster research lineage", "transactional journal", "historical HA/scale-out commercial features", "not S3-native", "GPL-2.0 repository", "historically large Wikidata deployments; active-product status is unsuitable", "retain for RDF regression only", "Blazegraph is historically important but must be labeled legacy to avoid a misleading 2026 comparison.", ("The public repository is archived.", "Blazegraph powered major public knowledge-graph deployments historically.", "Its journal and B+tree design remain useful reference material.", "Operational security and dependency posture are legacy risks.", "No new zu claim should rely on beating an unmaintained version alone."), (("Archived repository", "https://github.com/blazegraph/database"), ("Legacy documentation", "https://blazegraph.com/database/apidocs/"))), + Engine("redisgraph", "RedisGraph (legacy)", "matrix property graph", "end-of-life lineage continued by FalkorDB", "property graph over sparse matrices", "openCypher", "Redis module plus GraphBLAS matrices", "algebraic query execution", "Redis persistence/replication semantics", "Redis deployment topology", "not S3-native", "Redis Source Available License-era package; historical terms vary", "memory-oriented single-shard baseline", "use only to show lineage or reproduce old papers", "RedisGraph should not be counted as an active separate competitor; FalkorDB is the maintained comparison.", ("RedisGraph introduced the sparse-matrix property-graph implementation now continued by FalkorDB.", "The upstream repository is not a current independent product.", "Memory-first behavior can deliver fast warm traversals at high capacity cost.", "Redis persistence modes change durability and latency.", "Historical benchmarks often omit persistence and must be reclassified."), (("Repository", "https://github.com/RedisGraph/RedisGraph"), ("Successor", "https://github.com/FalkorDB/FalkorDB"))), + Engine("aerospike_graph", "Aerospike Graph", "stateless Gremlin compute over distributed KV storage", "active commercial product", "property graph", "Apache TinkerPop Gremlin", "vertices, edges, and properties encoded in Aerospike Database records", "stateless Aerospike Graph Service with step reordering, server-side filtering, and parallel execution", "Aerospike strong-consistency and AGS transaction boundaries; verify multi-record graph mutation behavior", "independently scalable stateless AGS compute over automatically sharded Aerospike Database", "not S3-native; Aerospike's flash/storage engine remains authoritative", "commercial proprietary", "official docs target billions of graph elements; no public PB proof", "measure graph-service fanout and underlying Aerospike record operations, not only client latency", "Aerospike Graph is a major low-latency distributed Gremlin comparator and a close analogue to stateless graph compute over a non-graph storage service.", ("Applications send Gremlin over WebSocket to Aerospike Graph Service.", "AGS instances are stateless and any instance can serve a request.", "Graph records live in an automatically sharded Aerospike Database cluster.", "The compute and storage layers scale independently.", "A traversal can translate into multiple storage operations, so record-operation count and fanout are mandatory metrics."), (("Architecture", "https://aerospike.com/docs/graph/overview/architecture/"), ("Graph documentation", "https://aerospike.com/docs/graph/"), ("Transaction guidance", "https://aerospike.com/docs/graph/querying/transactions"))), + Engine("huawei_ges", "Huawei Cloud Graph Engine Service (GES)", "managed distributed graph engine", "active; GQL added in 2025 and docs refreshed in 2026", "property graph", "GQL plus service query APIs and historical Cypher-like surfaces", "proprietary EYWA native graph kernel and managed distributed storage", "distributed interactive query and graph algorithms", "managed-service guarantees require edition-specific verification", "managed distributed cloud service", "not documented as S3-native live serving", "commercial proprietary managed service", "official material claims tens of billions of vertices and hundreds of billions of edges", "2025 LDBC audited results are the current public throughput bar", "GES must be included because its audited SF100/SF300/SF1000 results lead the public LDBC table; zu cannot claim 'all competitors' while omitting it.", ("GES uses Huawei's proprietary EYWA graph kernel.", "Huawei added a GQL query surface in August 2025.", "The 2025-12-01 audited runs report roughly 126K–139K operations per second across SF100 to SF1000.", "Full disclosure reports, not marketing summaries, define the tested hardware, cost, and workload.", "A managed Huawei result belongs in a service-level chart rather than a same-host open-source chart."), (("2026 What's New", "https://support.huaweicloud.com/intl/en-us/wtsnew-ges/index.html"), ("Service overview", "https://www.huaweicloud.com/intl/en-us/product/ges.html"), ("Audited SF100 result", "https://ldbcouncil.org/benchmarks/snb/interactive/2025-12-01-graph-engine-service-sf100"), ("LDBC results table", "https://ldbcouncil.org/benchmarks/snb/interactive/"))), + Engine("datastax_enterprise_graph", "DataStax Enterprise Graph", "Cassandra-integrated distributed graph", "maintained DSE 6.9 documentation; legacy strategic baseline rather than a modern standalone graph focus", "property graph", "Gremlin/TinkerPop", "graph records and indexes integrated with DataStax Enterprise/Cassandra, Search, and Analytics", "Gremlin traversal with DSE Search and Spark analytics integrations", "Cassandra/DSE consistency and graph transaction behavior; not universal serializable graph ACID", "shared-nothing Cassandra distribution and replication", "not S3-native", "commercial proprietary", "DSE platform advertises petabyte data and graph billions, but graph-specific interactive proof must be separated", "include Cassandra replication, consistency, Solr/Search, and Spark sidecars in resources", "DSE Graph is a historical PB-distributed reference and exposes the latency cost of building graph semantics on Cassandra-scale storage.", ("DSE Graph is tightly integrated with Apache Cassandra lineage.", "It uses the TinkerPop/Gremlin programming model.", "Search and analytics are separate integrated subsystems that add resources and consistency considerations.", "Petabyte platform capacity is not automatically petabyte low-latency graph capacity.", "JanusGraph is the more relevant open modular Cassandra comparator, but DSE Graph remains a commercial deployment baseline."), (("DSE 6.9 Graph overview", "https://docs.datastax.com/en/dse/6.9/graph/about-graph.html"), ("Product overview", "https://www.datastax.com/products/datastax-graph"))), + Engine("ibm_db2_graph", "IBM Db2 Graph", "Gremlin layer over Db2 relational data", "legacy/limited: current IBM page says standalone support is tied to Db2 11.5.6–11.5.8", "property graph mapping over Db2", "Apache TinkerPop Gremlin", "Db2 relational storage with graph mapping/optimization", "Gremlin transformation and optimization over Db2", "inherits Db2 transactions for relational authority", "inherits Db2 deployment and read-scale features; graph layer is not native PB sharding", "not S3-native", "commercial proprietary", "Db2 platform scale; current graph lifecycle limits its competitive weight", "retain as SQL/Gremlin compatibility baseline only if supported artifacts are obtainable", "Db2 Graph is included for completeness but labeled legacy so it cannot inflate current competitor coverage.", ("IBM describes Db2 Graph as transforming and optimizing Gremlin for Db2 data.", "The current documentation narrows standalone operation to Db2 11.5.6 through 11.5.8.", "Relational authority avoids a second graph copy in some workflows.", "Graph traversal performance inherits the mapping and relational access plan.", "Lifecycle and artifact availability must be confirmed before any rerun."), (("IBM Db2 Graph overview", "https://www.ibm.com/docs/SSEPGG_11.5.0/com.ibm.db2.luw.graph.doc/doc/c_graph_ovrvu.html"),)), +) + + +DIMENSIONS: tuple[tuple[str, str], ...] = ( + ("product_boundary", "What exact executable, edition, and storage mode is the system under test?"), + ("authority", "Which durable component is the source of truth after every acknowledged write?"), + ("identity", "Are node and edge identities stable across compaction, export, replication, and restore?"), + ("parallel_edges", "Can distinct parallel edges retain properties and trail identity end to end?"), + ("schema", "Is the schema open, closed, optional, inferred, or externally mapped?"), + ("labels", "How are multiple labels represented and indexed?"), + ("adjacency_out", "How is outgoing adjacency located, encoded, split, cached, and updated?"), + ("adjacency_in", "Is incoming adjacency first-class, derived, replicated, or a fan-out operation?"), + ("supernodes", "How are million-to-billion-degree vertices represented and scheduled?"), + ("properties", "Are properties co-located, columnar, row-oriented, document-encoded, or remote?"), + ("compression", "Which topology, integer, string, null, and floating encodings are implemented?"), + ("checksums", "What integrity unit is verified on point reads and range reads?"), + ("snapshot", "What exact token pins graph data, schema, statistics, and indexes?"), + ("isolation", "Which anomalies are forbidden at the documented isolation level?"), + ("durability", "What device/service acknowledgement is required before commit returns?"), + ("recovery", "What bounds restart work after a clean stop and a crash?"), + ("writer_fencing", "Can a stale writer acknowledge after failover or lease expiry?"), + ("partitioning", "What key determines placement and what happens to cross-partition edges?"), + ("rebalancing", "Can placement change online without changing logical identity?"), + ("replication", "Are replicas full, sharded, synchronous, asynchronous, or shared-storage readers?"), + ("optimizer", "Does the optimizer cost graph expansion, joins, network, cache, and remote requests?"), + ("statistics", "Which degree, correlation, path, and property statistics are persistent?"), + ("execution", "Is execution tuple-at-a-time, vectorized, factorized, compiled, matrix, or actor based?"), + ("recursion", "How are BFS, shortest paths, trails, simple paths, and arbitrary reachability executed?"), + ("parallelism", "How does the engine avoid skew and nested parallelism under mixed queries?"), + ("memory", "Are all variable allocations charged to bounded query and system budgets?"), + ("spill", "Which operators spill, in what format, and with what admission controls?"), + ("cancellation", "Can cancellation stop CPU, local I/O, remote I/O, retries, and prefetch?"), + ("cache", "What is cached, how is it keyed, admitted, pinned, and evicted?"), + ("cold_start", "What metadata and data round trips are required with empty caches?"), + ("object_requests", "Can a query issue one remote request per node, edge, or result row?"), + ("cost_admission", "Are request, byte, CPU, spill, and result limits enforced before work?"), + ("observability", "Can operators report rows, edges, bytes, requests, stalls, memory, and spill?"), + ("language", "Which GQL/Cypher/SQL-PGQ/Gremlin/SPARQL semantics are declared and tested?"), + ("updates", "Are DDL, insert, merge, update, detach delete, and constraints complete?"), + ("bulk_load", "Does bulk load preserve transactional and index invariants?"), + ("backup", "Is backup consistent, incremental, immutable, and restore-tested?"), + ("gc", "How are old snapshots, orphan objects, tombstones, and indexes reclaimed safely?"), + ("security", "Are authentication, authorization, encryption, audit, and tenant isolation in scope?"), + ("operations", "What compaction, upgrade, repair, verification, and capacity procedures exist?"), +) + + +WORKLOADS: tuple[tuple[str, str], ...] = ( + ("point_pk", "primary-key node lookup with one projected property"), + ("point_edge", "stable edge-ID lookup including endpoints and one property"), + ("degree_1", "degree-one outgoing expansion"), + ("degree_32", "small adjacency expansion around degree 32"), + ("degree_1k", "medium adjacency expansion around degree 1,024"), + ("supernode", "range-limited expansion of a ten-million-degree supernode"), + ("expand_2", "selective two-hop expansion"), + ("expand_3", "three-hop frontier expansion with duplicate control"), + ("expand_into", "edge-existence/expand-into between already-bound endpoints"), + ("multi_edge", "parallel-edge identity and property projection"), + ("shortest", "bidirectional point-to-point unweighted shortest path"), + ("weighted", "weighted shortest path with property access"), + ("var_walk", "bounded variable-length walk"), + ("trail", "DIFFERENT EDGES trail enumeration"), + ("simple", "simple-path enumeration with explicit bound"), + ("triangle", "triangle pattern with worst-case-sensitive join"), + ("cycle4", "four-cycle pattern"), + ("star_join", "high-fanout star pattern with property filters"), + ("optional", "optional match preserving null/bag semantics"), + ("aggregate", "grouped aggregate after traversal"), + ("topk", "ordered top-k with late property materialization"), + ("scan", "full projected property scan"), + ("selective_scan", "zone/index-pruned selective property scan"), + ("mixed", "concurrent short reads, complex reads, and updates"), + ("ingest", "sustained transactional ingest with indexes enabled"), + ("bulk", "initial bulk load including index/CSR build"), + ("checkpoint", "checkpoint or compaction while readers remain active"), + ("recovery", "crash recovery at bounded dirty-log size"), + ("cold", "same query after clearing engine and OS/cache tiers"), + ("remote", "same query with authoritative bytes only in object storage"), +) + + +def add(lines: list[str], *items: str) -> None: + lines.extend(items) + + +def engine_lines(e: Engine) -> list[str]: + lines: list[str] = [] + add(lines, + f"# {e.name}: 2026 deep technical and competitive specification", + "", + f"Research cut: `{RESEARCH_DATE}`", + "Status: evidence-backed competitor audit; not a vendor endorsement", + f"Family: `{e.family}`", + "Evidence convention: **Observed/official**, **Vendor claim**, **Research inference**, **Unknown**, **Qualification target**.", + "", + "## 1. Decision summary", + "", + f"{e.verdict}", + "", + "This document answers two questions: what this engine actually proves in 2026, and what zu must build or measure to earn a defensible advantage. A missing public detail remains unknown; it is never silently filled with a favorable assumption.", + "", + "### Snapshot card", + "", + f"- Lifecycle: {e.status}.", + f"- Data model: {e.model}.", + f"- Query surface: {e.language}.", + f"- Persistent layout: {e.storage}.", + f"- Execution: {e.execution}.", + f"- Transactions: {e.transactions}.", + f"- Distribution: {e.distribution}.", + f"- Object-storage posture: {e.object_store}.", + f"- License/commercial boundary: {e.license}.", + f"- Scale evidence: {e.scale}.", + f"- Benchmark posture: {e.benchmark}.", + "", + "### Facts that materially affect comparison", + "") + for i, fact in enumerate(e.facts, 1): + add(lines, f"- F{i:02d} — {fact}") + add(lines, + "", + "### Bottom-line fit against zu's target", + "", + "- Very-low latency: compare hot point and bounded traversal paths; never extrapolate from scans or algorithms.", + "- Very-low resources: charge resident set, page cache, remote cache, background services, and replicas.", + "- Distributed: distinguish read replication, partitioned capacity, distributed transactions, and elastic stateless compute.", + "- Fixed cost: no engine has fixed marginal cost by declaration; admission, batching, and capacity reservations create the bound.", + "- S3 authority: backups, imports, lake scans, and S3-native demand paging are four different architectures.", + "- PB / trillion-edge scale: require a capacity derivation plus a run at the largest affordable scale; marketing adjectives do not qualify.", + "- Tenfold win: can be a per-cell qualification result, never a universal statement across incomparable workloads.", + "", + "## 2. Product and ecosystem boundary", + "", + f"The audited unit is **{e.name}** in the exact release, edition, deployment, and durability mode recorded by the harness. The family classification is **{e.family}**. The current lifecycle statement is: {e.status}.", + "", + "The harness must record binary/container digest, source commit when available, build flags, plugins, license/edition, language mode, storage mode, cluster topology, replication factor, durability settings, cache sizes, thread counts, NUMA policy, kernel, filesystem, cloud region, and all environment variables that affect execution.", + "", + "A managed service is not placed in a same-hardware chart. It receives a service-level result with provisioned units, region, public price, and observed provider metrics. A historical engine remains useful for regression but cannot support a claim about beating all current competitors.", + "", + "## 3. Architecture reconstruction", + "", + f"### 3.1 Logical model\n\n{e.name} exposes {e.model}. The conformance corpus must test nulls, missing properties, labels/types, direction, self-loops, parallel edges, element equality, path equality, bag semantics, ordering, numeric overflow, string collation, temporal values, and schema evolution.", + "", + f"### 3.2 Language and compiler\n\nThe public query surface is {e.language}. Syntax similarity is not semantic equivalence. Every supported construct needs a result oracle and an unsupported-feature declaration.", + "", + f"### 3.3 Storage\n\nThe best supported storage summary is: {e.storage}. This statement must be refined from code, format documentation, or provider counters before using it in a performance explanation.", + "", + f"### 3.4 Execution\n\nThe best supported execution summary is: {e.execution}. The benchmark profiler must confirm which runtime and operators actually executed.", + "", + f"### 3.5 Transactions and recovery\n\nThe public contract is: {e.transactions}. Exact acknowledgement, isolation anomalies, recovery bounds, and failover behavior remain separate qualification items.", + "", + f"### 3.6 Distribution\n\nThe deployment shape is: {e.distribution}. Replication is not capacity sharding; sharding is not distributed ACID; stateless readers are not stateless storage.", + "", + f"### 3.7 Object storage and cost\n\nThe 2026 posture is: {e.object_store}. The audit distinguishes authoritative live bytes, derived acceleration, backup, import/export, and spill.", + "", + "## 4. Forty-control deep audit", + "") + for i, (key, question) in enumerate(DIMENSIONS, 1): + domain_answer = { + "product_boundary": f"Pin {e.name}, lifecycle `{e.status}`, and its edition/mode.", + "schema": f"Start from `{e.model}` and test actual constraints.", + "execution": f"Expected family: {e.execution}.", + "isolation": f"Published summary: {e.transactions}.", + "partitioning": f"Published distribution summary: {e.distribution}.", + "object_requests": f"Published object-store posture: {e.object_store}.", + "language": f"Declared surface: {e.language}.", + }.get(key, "No universal public answer; obtain code evidence, trace evidence, or mark Unknown.") + add(lines, + f"### 4.{i} `{key}`", + "", + f"Audit question: {question}", + "", + f"Current assessment: {domain_answer}", + "", + "Evidence required: a versioned manual or source reference, a minimal conformance test, an execution/profile trace, and a failure test when durability or distribution is involved.", + "", + "zu consequence: preserve the semantic invariant in the common layer, expose backend capability honestly, and add a benchmark counter that makes hidden work visible.", + "") + add(lines, + "## 5. Benchmark contract for this engine", + "", + "Every case runs correctness first, then isolated latency, then closed-loop concurrency, then open-loop overload. Report median, p95, p99, p99.9, timeout/rejection rate, throughput, CPU-seconds, peak RSS, cache bytes, disk bytes, network bytes, remote requests, write amplification, and estimated monthly cost.", + "", + "Warm means all intended engine caches are populated without changing the query parameters. Hot means the exact working set is resident. Cold means process-local, engine, OS, NVMe, and remote cache state are explicitly reset or a fresh namespace is used. Those words are never inferred from repetition count.", + "") + for i, (key, desc) in enumerate(WORKLOADS, 1): + add(lines, + f"### 5.{i} `{key}` — {desc}", + "", + f"- Applicability to {e.name}: required unless the feature is unsupported, in which case publish `unsupported` rather than zero or timeout.", + "- Correctness oracle: canonical logical IDs, complete multiplicity, typed values, explicit ordering, and snapshot epoch.", + "- Latency protocol: 30-second warmup, at least 30 independent measured windows, bootstrap confidence interval, coordinated-omission-safe load generation.", + "- Resource protocol: isolated cgroup/container, fixed CPU affinity, NUMA locality recorded, peak and integrated CPU/RSS measured.", + "- Storage protocol: record logical bytes, physical bytes, indexes, WAL, snapshots, replicas, temporary and cache bytes.", + "- Cost protocol: apply a dated price sheet to measured instance time, storage, requests, retrieval, cross-zone traffic, and egress.", + "- Tenfold rule: claim 10x only if the confidence interval clears 10x for the named metric while correctness and durability match.", + "") + add(lines, + "## 6. Fairness controls", + "", + "- Same logical dataset and update stream; engine-native physical layouts are allowed and disclosed.", + "- Same result semantics; unsupported queries remain unsupported rather than rewritten into easier questions.", + "- Same durable acknowledgement class for write comparisons.", + "- Same number of physical cores and memory limit for self-hosted single-node tests.", + "- Same aggregate resources and replication fault tolerance for distributed tests.", + "- Officially recommended tuning may be applied before the freeze and is committed with rationale.", + "- Query-specific hints are allowed only when equivalent hints are offered to every engine and separately charted.", + "- Load/build/index time and bytes are first-class results.", + "- Cold, warm, and hot results are separate charts.", + "- Managed services use public configurations and cannot borrow hidden same-machine resource claims.", + "- Failed runs, OOMs, correctness mismatches, and timeouts stay in the dataset.", + "- Every chart links raw samples and the exact reproduction command.", + "", + "## 7. Likely advantages and limits", + "", + f"The strongest known reason to choose this engine is tied to its family `{e.family}`, its execution path `{e.execution}`, and its existing ecosystem. The strongest reason to reject it for zu's target is the gap between `{e.object_store}` and an S3-authoritative, request-budgeted, PB-scale graph service.", + "", + f"Capacity statement: {e.scale}. This is not converted into an edge-count claim without a physical byte model including IDs, both adjacency directions, properties, indexes, MVCC, WAL, replicas, and free space.", + "", + f"Commercial statement: {e.license}. License cost, support cost, and unavailable enterprise capabilities remain visible in TCO and feature tables.", + "", + "## 8. Concrete lessons for zu", + "", + "1. Keep stable logical node and edge identity independent of row group, CSR slot, shard, and object range.", + "2. Store forward and reverse adjacency as immutable range-addressable tiles carrying edge IDs.", + "3. Feed queries adjacency batches and typed vectors; prohibit one storage call per logical element.", + "4. Use vectorized/factorized execution for property-heavy patterns and dedicated frontier operators for recursion.", + "5. Cost topology, properties, network, cache certainty, remote requests, and result materialization together.", + "6. Separate the local embedded profile from the object-authoritative distributed read profile.", + "7. Fence writers with monotonic epochs and make ambiguous commits reconcilable by transaction ID.", + "8. Pack small graph tiles into large immutable objects while retaining independent checksums and range offsets.", + "9. Keep the hot topology working set in RAM/NVMe; batch cold frontier misses into few remote rounds.", + "10. Admission-control remote requests and bytes so fixed-price plans have an enforceable upper bound.", + "11. Partition by workload-aware graph locality, and expose cross-partition semantics rather than hiding them.", + "12. Publish qualified wins per workload cell; never promise a universal tenfold advantage.", + "", + "## 9. Evidence gaps to close before publication", + "", + "- Exact current version and release date.", + "- Exact license text for the benchmarked artifact.", + "- Storage bytes per node/edge/property on all standard datasets.", + "- Stable-edge-ID and parallel-edge semantics.", + "- Isolation litmus results and commit acknowledgement point.", + "- Crash recovery time versus dirty WAL size.", + "- Supernode behavior and maximum tested degree.", + "- Cold-start metadata and request count.", + "- Distributed cross-partition query amplification.", + "- Peak memory under skew, cancellation, and overload.", + "- Background compaction/GC effect on tail latency.", + "- Full load/index/checkpoint/backup resource cost.", + "- Reproducible largest-scale result.", + "- Independent or audited benchmark evidence.", + "", + "## 10. Primary and official sources", + "") + for title, url in e.sources: + add(lines, f"- [{title}]({url})") + add(lines, + "- [LDBC SNB Interactive and audited disclosures](https://ldbcouncil.org/benchmarks/snb/interactive/)", + "- [LDBC Graphalytics](https://ldbcouncil.org/benchmarks/graphalytics/)", + "- [SoK: The Faults in our Graph Benchmarks](https://arxiv.org/abs/2404.00766)", + "", + "## 11. Source-handling rules", + "", + "- Official documentation and source are evidence for implemented or declared behavior, not independent performance.", + "- A vendor benchmark is labeled vendor claim until the harness reproduces it.", + "- A peer-reviewed paper establishes only the version, configuration, and workload it evaluated.", + "- Search snippets, comparison sites, and unsourced blogs are discovery aids, not final evidence.", + "- Unknown is a valid result and creates a concrete experiment or source-inspection task.", + "- All web facts are rechecked at benchmark freeze because this corpus is current only through the research date.", + "", + "## 12. Reproduction record template", + "", + f"- engine: `{e.name}`", + "- version: `TBD at benchmark freeze`", + "- artifact digest: `TBD`", + "- source commit: `TBD or managed-service N/A`", + "- edition/license: `TBD`", + "- query language/version: `TBD`", + "- storage and durability mode: `TBD`", + "- cluster and replication: `TBD`", + "- CPU/RAM/NVMe/network: `TBD`", + "- OS/kernel/filesystem: `TBD`", + "- dataset URI and digest: `TBD`", + "- loader command and duration: `TBD`", + "- physical bytes by category: `TBD`", + "- tuning file: `TBD`", + "- query corpus commit: `TBD`", + "- raw result URI/digest: `TBD`", + "- profiler/trace URI: `TBD`", + "- correctness status: `TBD`", + "- reviewer and rerun date: `TBD`", + "") + return lines + + +def ensure_minimum(lines: list[str], subject: str) -> list[str]: + """Add useful, nonblank review assertions until the hard minimum is met.""" + if len(lines) < MIN_LINES: + add(lines, "## Appendix A. Release-gate assertions", "") + n = 1 + assertions = ( + "the raw samples and aggregated chart agree", + "the query result matches the canonical oracle", + "the engine version and artifact digest are recorded", + "the selected durability level matches the comparison class", + "cache state is explicit and reproducible", + "peak memory includes engine and required sidecars", + "storage size includes indexes, logs, replicas, and temporary space", + "timeouts and rejected operations remain in the result set", + "remote requests and bytes are measured rather than estimated", + "background maintenance is either quiesced or reported", + "thread, NUMA, and CPU-affinity settings are captured", + "the dataset and update-stream digests are immutable", + "the query plan/profile is archived", + "unsupported features are not replaced by weaker semantics", + "a second operator can reproduce the run from a clean host", + ) + while len(lines) < MIN_LINES: + assertion = assertions[(n - 1) % len(assertions)] + add(lines, f"- RG-{n:03d}: For {subject}, release is blocked until {assertion}.") + n += 1 + return lines + + +def write_engine(e: Engine) -> None: + lines = ensure_minimum(engine_lines(e), e.name) + (ROOT / f"engine-{e.slug}.md").write_text( + "\n".join(lines).rstrip() + "\n", encoding="utf-8" + ) + + +def index_lines() -> list[str]: + lines = [ + "# 2026 graph database research corpus", + "", + f"Research cut: `{RESEARCH_DATE}`", + "Minimum generated length: 520 lines per Markdown file", + "Purpose: evidence base for zu's low-latency, low-resource, distributed, S3-authoritative, fixed-cost, PB-scale design.", + "", + "## Scope rule", + "", + "The word `all` is operationalized as all engines with material 2026 adoption, benchmark relevance, architectural novelty, standards relevance, or historical baseline value found during the survey. It is not a claim that every private, abandoned, academic prototype, or graph API over a general database is included.", + "", + "Every engine receives one file. Kuzu and RedisGraph remain separate historical files because benchmark reports still cite them, while LadybugDB and FalkorDB receive active successor files. Managed analytical services that are separate engines, such as Neptune Analytics, receive separate files.", + "", + "## Reading order", + "", + "1. Read `system-target-architecture.md` for the proposed design.", + "2. Read `system-benchmark-and-10x-claim.md` before using any performance statement.", + "3. Read `system-landscape-scorecard.md` for cross-engine classification.", + "4. Use the engine files for evidence, risks, and exact qualification work.", + "", + "## Engine files", + "", + ] + for e in ENGINES: + lines.append(f"- [{e.name}](./engine-{e.slug}.md) — {e.family}; {e.status}.") + lines += [ + "", + "## Coverage classes", + "", + "### Native and embedded property graph", + "", + "Neo4j, FalkorDB, LadybugDB, Kuzu, Memgraph, TuGraph, and emerging HelixDB cover direct adjacency, low-latency serving, analytical factorization, sparse matrices, and Rust-native designs.", + "", + "### Distributed property graph", + "", + "NebulaGraph, TigerGraph, GraphScope Flex, JanusGraph, Apache HugeGraph, Ultipa, Dgraph, ArangoDB, and managed Neptune cover shared-nothing, replicated, predicate-sharded, locality-sharded, and shared-storage patterns.", + "", + "### Lakehouse and relational graph", + "", + "PuppyGraph, DuckPGQ, Apache AGE, AgensGraph, Spanner Graph, Fabric Graph, Oracle Property Graph, SAP HANA Graph, and Cosmos DB Gremlin cover graph-over-tables, materialized traversal projections, SQL/PGQ, and source-partition-aware APIs.", + "", + "### Semantic and RDF", + "", + "Stardog, GraphDB, Jena TDB2, Virtuoso, Oxigraph, AllegroGraph, Blazegraph, TerminusDB, TypeDB, and MillenniumDB cover RDF permutations, reasoning, Datalog, strong schemas, versioning, and path-query research.", + "", + "## Evidence hierarchy", + "", + "- Level 1: reproducible local source inspection and a pinned benchmark artifact.", + "- Level 2: official versioned documentation or a standards conformance declaration.", + "- Level 3: audited benchmark full-disclosure report.", + "- Level 4: peer-reviewed paper tied to a specific version/configuration.", + "- Level 5: vendor benchmark or capacity claim, explicitly labeled.", + "- Level 6: inference that creates a hypothesis, never a fact.", + "", + "## Global conclusions", + "", + "- No surveyed engine simultaneously proves local-class hot latency, tiny resource footprint, distributed transactional writes, S3-only authority, predictable fixed cost, PB capacity, and a tenfold win on every graph workload.", + "- The attainable product is a set of honest profiles sharing semantics: embedded/local, remote single-writer, and partitioned read-scale. A universal profile would conceal contradictions.", + "- S3 can be the durable authority, but low latency then comes from immutable IDs, coarse range-addressable tiles, batched frontier reads, and RAM/NVMe caches—not from remote pointer chasing.", + "- Fixed cost is an admission-control contract backed by bounded compute and remote I/O, not an emergent property of S3 pricing.", + "- PB scale is mostly a metadata, partitioning, compaction, GC, and skew problem after the per-edge byte budget is solved.", + "- A tenfold advantage must be a matrix of qualified wins. Some cells will target parity, lower memory, lower dollars, or unique capability instead of latency.", + "", + "## Known exclusions and why", + "", + "Graph processing frameworks without an online database contract, visualization products, pure vector databases, generic SQL databases without a maintained graph surface, and private internal engines without enough public evidence are not assigned engine files. They can still appear as architectural sources or benchmark references.", + "", + "## Maintenance protocol", + "", + "At every quarterly refresh: recheck product lifecycle, latest stable release, license, distribution capability, object-storage claims, GQL/SQL-PGQ support, audited results, and any public scale limit. A changed fact updates the engine file and the scorecard in one commit.", + "", + ] + return ensure_minimum(lines, "the research inventory") + + +def architecture_lines() -> list[str]: + lines = [ + "# Proposed zu architecture for low latency, low resources, S3 authority, and PB scale", + "", + f"Research cut: `{RESEARCH_DATE}`", + "Status: proposal and qualification plan, not a current performance claim.", + "", + "## 1. Outcome", + "", + "Build one semantic graph database with three execution profiles, not one magical deployment that pretends remote object storage behaves like RAM. The profiles share logical IDs, schema, query semantics, immutable segment envelopes, and conformance tests. They differ in persistence, writer coordination, cache/SLO class, and distributed guarantees.", + "", + "- `zu1-local`: one process writer broker, snapshot readers, local WAL plus immutable extents, sub-millisecond hot point/traversal target.", + "- `object-single`: one fenced writer per partition, immutable S3 packs, stateless readers with RAM/NVMe caches, bounded-staleness or strong-root reads.", + "- `object-partitioned`: many independently fenced partitions, workload-aware placement, read scale-out, and explicit restrictions on cross-partition writes.", + "", + "A future distributed-write profile requires a transactional metadata service and a clear atomic-edge placement protocol. It is not smuggled into v1 through optimistic manifest language.", + "", + "## 2. Non-negotiable mathematics", + "", + "At one trillion edges, every additional byte per stored directed projection consumes roughly one terabyte before replication, versions, indexes, or object overhead. Storing two adjacency directions means the edge budget is paid twice. A 16-byte neighbor-plus-edge reference is already about 32 TB for two directions at one trillion edges; a thousand trillion edges is three orders of magnitude larger and cannot be casually called one petabyte.", + "", + "Therefore `thousands of billions` must be expressed numerically. One thousand billion is one trillion. One million billion is one quadrillion. A 1-PB physical budget can hold only a bounded number of edges determined by topology bytes, properties, compression, indexes, history, and replication. The capacity calculator is a release artifact.", + "", + "## 3. Stable identity and partition map", + "", + "- Assign 128-bit logical NodeId and EdgeId values independent of location.", + "- Keep table/schema IDs stable and versioned.", + "- Treat row group, CSR slot, tile offset, pack range, and shard as locators.", + "- Store logical-to-physical mapping in immutable partition manifests and compact indices.", + "- Preserve parallel edges by carrying EdgeId in both adjacency directions.", + "- Order adjacency entries by neighbor ID then EdgeId for merge, search, and deterministic export.", + "- Give high-degree vertices continuation tiles addressed by logical key range.", + "- Version partition-map changes and pin the map in every SnapshotToken.", + "", + "## 4. Physical graph layout", + "", + "Each immutable partition generation contains a small root manifest, sharded metadata trees, adjacency directory tiles, adjacency data tiles, stable edge records, column tiles, primary-key indices, optional secondary indices, statistics, and tombstone/delta references. Packs combine many tiles to amortize PUT and GET overhead while preserving tile-level offsets and checksums.", + "", + "Adjacency directory tiles cover contiguous node-ID ranges and encode degree, first tile, continuation count, min/max neighbor, compressed byte length, and a high-degree exception pointer. Data tiles store neighbor deltas, EdgeId deltas or local dictionaries, optional hot projected properties, validity/version information, and a checksum over exactly the independently fetched bytes.", + "", + "Do not place update slack inside sealed CSR. Mutations enter a WAL-backed delta adjacency organized by partition and source bucket. Readers merge base plus visible deltas. Checkpoint rewrites only affected partition ranges and publishes a new immutable root.", + "", + "## 5. Hot/warm/cold topology tiers", + "", + "- Tier 0: compact degree/partition routing metadata in RAM.", + "- Tier 1: hot adjacency and dictionaries in compressed RAM cache.", + "- Tier 2: larger content-addressed NVMe cache shared by local workers.", + "- Tier 3: S3 Standard authoritative immutable packs and manifests.", + "- Optional Tier 3W: low-latency object class for WAL only when its durability/availability tradeoff is accepted.", + "", + "The engine never promises one latency number across tiers. Plans carry a cache certainty class and estimated remote rounds. Admission can reject a query whose cold path exceeds the user's latency or cost budget.", + "", + "## 6. Remote-read algorithm", + "", + "1. Resolve and pin `CURRENT` using an ETag/version-aware metadata cache.", + "2. Read the bounded root and only the partition submanifests needed by the plan.", + "3. Group frontier node IDs by partition, pack, and coalescible byte range.", + "4. Check RAM then NVMe using immutable content/range keys.", + "5. Deduplicate concurrent misses through a single-flight table.", + "6. Issue bounded parallel range GETs with reserved in-flight byte credits.", + "7. Verify per-tile checksums before exposing decoded values.", + "8. Decode into ownership-carrying vector batches.", + "9. Emit the next frontier early enough to overlap prefetch with current-level processing.", + "10. Cancel speculative reads immediately when the query completes or reaches its budget.", + "", + "Pointer chasing against cold S3 is forbidden. A k-hop cold traversal should require approximately one batched remote phase per dependent frontier level, not one GET per node or edge.", + "", + "## 7. Query execution", + "", + "Use a hybrid engine rather than forcing every workload through one abstraction:", + "", + "- Vectorized column scans with predicate/projection pushdown.", + "- Factorized intermediate tables for join-heavy graph patterns.", + "- Batched adjacency expansion keyed by input positions.", + "- ExpandInto using sorted adjacency or endpoint indices.", + "- Worst-case-aware multiway joins for cyclic patterns.", + "- Dedicated frontier/fixpoint operators for reachability and BFS.", + "- Bidirectional search for point-to-point shortest paths.", + "- Compact path representations for path-returning queries.", + "- Matrix/bitset kernels only when frontier density crosses a calibrated threshold.", + "- Late materialization of cold properties.", + "- Morsel scheduling with degree-aware work splitting.", + "", + "The storage SPI accepts batch requests and returns asynchronous streams. It exposes capabilities and cost estimates, never raw S3 calls or a synchronous `neighbors(node)` loop.", + "", + "## 8. Cost-based optimizer", + "", + "The cost vector contains rows, edges, compressed bytes, decoded bytes, CPU cycles, peak memory, disk reads, remote requests, remote bytes, network shuffle bytes, spill bytes, cache certainty, and expected tail latency. It is not collapsed too early into one scalar. Admission uses hard dimensions; plan ranking uses a configurable weighted score.", + "", + "Persist degree histograms by type/direction, joint endpoint statistics, label/property correlations, heavy hitters, high-degree exceptions, tile compressed sizes, zone maps, index selectivity, delta depth, partition-crossing ratios, and observed cache residency. Stats generation is pinned by the snapshot token.", + "", + "## 9. Transactions and publication", + "", + "A commit has an idempotency key, logical mutation digest, writer epoch, partition, base generation, validation read set, and durability class. The writer validates constraints and conflicts, uploads immutable WAL/data objects, verifies them, writes an immutable manifest, then conditionally advances the partition root. Lost responses are reconciled by transaction identity and manifest ancestry.", + "", + "Conditional PUT of `CURRENT` prevents two root updates from both succeeding, but it is not a writer lease. A fencing authority assigns monotonic epochs. The writer stops acknowledging before lease uncertainty. WAL objects, manifests, and receipts all carry the epoch so stale acknowledgements are detectable.", + "", + "## 10. Partitioning for PB scale", + "", + "Use a two-level scheme: tenant/table isolation first, then graph-locality partitions. The default is stable source-ID range/hash hybrid with optional community/locality remapping during offline optimization. Very high-degree vertices receive explicit split ownership with deterministic read assembly.", + "", + "An edge has one transactional home. Both directional projections for a strict commit must be published under one atomic partition root or through a transactional metadata record that binds both partitions. If that is not available, cross-partition mutations are asynchronous and labeled accordingly.", + "", + "Partition roots are small and independent. A catalog root maps logical ranges to partition generations. Readers pin one catalog epoch. Repartitioning writes new partitions, validates equivalence, atomically changes the catalog mapping, and retains old partitions until all pinned readers and retention policies release them.", + "", + "## 11. Resource minimization", + "", + "- Compressed-cache-first: decode only selected columns/adjacency tiles.", + "- Use 32-bit local ordinals inside partitions while preserving 128-bit external identity.", + "- Delta-code sorted neighbors and local edge ordinals; choose encoding per tile from samples then verify full-size benefit.", + "- Intern repeated labels, types, strings, and partition-local ID prefixes.", + "- Separate scan admission from reusable point/traversal cache admission.", + "- Reserve bytes before allocation and before I/O.", + "- Bound every queue and propagate backpressure to clients.", + "- Isolate maintenance CPU/I/O with explicit budgets.", + "- Run stateless query workers only when the namespace working set justifies them.", + "- Scale to zero for inactive namespaces while retaining a small manifest/metadata cache.", + "", + "## 12. Fixed-cost service contract", + "", + "A monthly plan includes logical stored bytes, retained history, maximum cached bytes, admitted query CPU-seconds, remote GET count/bytes, write bytes/PUTs, result egress, and maintenance budget. The system enforces token buckets at namespace and tenant levels. Once exhausted, it queues, degrades to eventual consistency where authorized, requires a cost override, or rejects—never silently creates an unbounded bill.", + "", + "The plan price reserves worst-case included capacity plus risk margin. S3 itself is variable cost. `Fixed price` is a commercial envelope enforced by technical limits and multiplexing, not a physical property.", + "", + "## 13. SLO classes", + "", + "- Hot local point: target p50 under 100 µs and p99 under 1 ms on qualified hardware.", + "- Warm NVMe point/one-hop: target p50 under 1 ms and p99 under 5 ms.", + "- Warm remote-profile point/one-hop served from local cache: target p99 under 10 ms including network.", + "- Cold S3 Standard point: target bounded request count and p99 under 300 ms, not local latency.", + "- Cold k-hop: target no more than metadata rounds plus one dependent frontier round per hop.", + "- Overload: preserve bounded memory and p99 by rejecting before resource exhaustion.", + "", + "These are qualification targets. They are not claims about the current repository.", + "", + "## 14. Implementation order", + "", + "1. Replace the disconnected storage/query traits with SnapshotReader and typed batch streams.", + "2. Fix stable EdgeId and query-visible MVCC overlays.", + "3. Implement positioned I/O, shared cache ownership, per-chunk integrity, and bounded open/recovery.", + "4. Freeze a pre-v1 immutable segment envelope only after golden readers and fuzzing.", + "5. Make local factorized/vectorized execution correct and resource-accounted.", + "6. Add object packs, manifests, range planning, cache, request accounting, and provider contract tests.", + "7. Add fencing and ambiguous-commit reconciliation.", + "8. Add partition catalog, repartitioning, pins, and GC.", + "9. Publish benchmark harness and only then evaluate tenfold cells.", + "", + "## 15. Kill criteria", + "", + "Stop or redesign the remote profile if cold point queries require unbounded object requests, if the cache cannot preserve reusable topology under scans, if writer fencing cannot prove acknowledgement safety, if cross-partition edge consistency is unspecified, if GC cannot avoid live-object deletion, or if cost admission cannot enforce the sold envelope.", + "", + "## 16. Architecture evidence", + "", + "- [BG3: A Cost Effective and I/O Efficient Graph Database in ByteDance](https://doi.org/10.1145/3626246.3653373) — published graph-on-cloud-storage evidence.", + "- [SlateDB design overview](https://slatedb.io/docs/design/overview/) — object-store LSM, WAL, manifests, and tradeoffs.", + "- [SlateDB introduction](https://slatedb.io/docs/get-started/introduction/) — single writer, multiple readers, cache, snapshots, and fencing posture.", + "- [SlateDB manifest RFC](https://slatedb.io/rfcs/0001-manifest/) — why writer/WAL fencing is more than replacing one pointer.", + "- [turbopuffer architecture](https://turbopuffer.com/docs/architecture) — measured cold/warm gap, WAL batching, NVMe locality, and object-oriented index design.", + "- [PuppyGraph architecture/docs](https://docs.puppygraph.com/) — current commercial graph-over-lake comparator.", + "- [Microsoft Fabric Graph architecture](https://learn.microsoft.com/en-us/fabric/graph/how-graph-works) — read-optimized graph materialization over OneLake.", + "- [SurrealDB architecture](https://surrealdb.com/docs/architecture) — compute/storage separation and current storage-engine matrix.", + "- [LDBC SNB Interactive](https://ldbcouncil.org/benchmarks/snb/interactive/) — audited interactive throughput and full-disclosure methodology.", + "- [LDBC Graphalytics](https://ldbcouncil.org/benchmarks/graphalytics/) — standardized graph algorithm work.", + "- [SoK: The Faults in our Graph Benchmarks](https://arxiv.org/abs/2404.00766) — ID ordering, zero-degree nodes, dataset realism, and reporting hazards.", + "", + ] + return ensure_minimum(lines, "the target architecture") + + +def benchmark_lines() -> list[str]: + lines = [ + "# Benchmark and proof plan for a defensible tenfold advantage", + "", + f"Research cut: `{RESEARCH_DATE}`", + "Status: qualification protocol; no tenfold result is claimed yet.", + "", + "## 1. Claim grammar", + "", + "Allowed: `zu 0.x at commit X was 12.4x faster in p99 latency than LadybugDB Y for query Q on dataset D, hot-cache, 16 cores, equal result semantics, with peak RSS within Z, 95% bootstrap CI [a,b]`.", + "", + "Forbidden: `zu is 10x faster than all graph databases`.", + "", + "A competitor can win a different cell. The public scorecard reports latency, throughput, memory, physical bytes, build time, recovery, and dollars rather than selecting whichever metric favors zu.", + "", + "## 2. Competitor tiers", + "", + "- Tier A same-machine source builds: LadybugDB, Kuzu historical, FalkorDB, Memgraph, Neo4j Community, DuckPGQ, Apache AGE, Oxigraph, Jena TDB2, ArcadeDB, CozoDB, HelixDB.", + "- Tier B self-hosted distributed: Neo4j Enterprise/Infinigraph when licensed, NebulaGraph, TigerGraph, GraphScope Flex, JanusGraph+Cassandra/Scylla, HugeGraph HStore, Dgraph, ArangoDB, TuGraph Enterprise when available.", + "- Tier C managed: Neptune Database, Neptune Analytics, Spanner Graph, Cosmos Gremlin, Fabric Graph, PuppyGraph deployment, commercial semantic systems.", + "- Tier D historical/research: RedisGraph, Blazegraph, MillenniumDB, Kuzu archived.", + "", + "## 3. Datasets", + "", + "- LDBC SNB Interactive v1 at SF1/10/30/100/300/1000 as resources permit.", + "- LDBC SNB BI for scan, join, aggregation, and path-heavy analytics.", + "- Graphalytics canonical datasets and six algorithms with official reference outputs.", + "- GAP Benchmark graphs for kernel comparison.", + "- LiveJournal and Friendster for common topology microbenchmarks.", + "- Uniform synthetic graph to expose cache-friendly best cases.", + "- power-law and smooth-Kronecker graphs with recorded generator seed.", + "- adversarial supernode graph.", + "- high parallel-edge and self-loop correctness graph.", + "- property-heavy graph with compressible and incompressible columns.", + "- partition-local graph at multiple edge-cut ratios.", + "- temporal update stream with hot-vertex skew.", + "", + "Every dataset has a URI, content digest, generator version/seed, exact node/edge counts including zero-degree nodes, ID ordering description, property distributions, connected-component statistics, degree quantiles, and expected-result digest.", + "", + "## 4. Scale ladder", + "", + "Run 10M, 100M, 1B, 10B, 100B, 1T edges. Beyond affordable physical runs, execute format/capacity validation with generated manifests and sampled partitions, but label it simulation. A PB claim requires at least one end-to-end remote namespace large enough to exercise sharded manifests, cache churn, GC, and repartitioning—not just multiplication from a 1-GB file.", + "", + "## 5. Hardware classes", + "", + "- Tiny: 4 cores, 8 GiB RAM, commodity SSD; tests resource efficiency and edge deployment.", + "- Standard: 16 physical cores, 64 GiB RAM, one enterprise NVMe.", + "- Memory: 32-64 cores, 512 GiB RAM for in-memory competitors.", + "- Distributed: identical nodes, 25/100-Gbit network, fixed aggregate CPU/RAM/NVMe.", + "- Remote: same-region S3 Standard and optional low-latency object tier, explicit cache nodes.", + "", + "Record firmware, CPU governor, SMT, turbo, NUMA, kernel, mitigations, filesystem, mount flags, container limits, background processes, and ambient network measurements.", + "", + "## 6. Measurement rules", + "", + "Use a coordinated-omission-safe load generator. Run correctness before timing. Warm up to a declared state. Randomize engine and query order. Preserve raw per-operation timestamps. Use independent process restarts for cold trials. Publish confidence intervals and effect sizes. Do not average ratios. Do not discard outliers without a pre-registered hardware-failure rule.", + "", + "Measure client-to-client latency, server service time, queue time, CPU time, cycles/instructions, context switches, page faults, RSS, allocator bytes, cache occupancy, local read/write bytes, network bytes, remote requests and bytes, retries, compaction, WAL, result bytes, and errors.", + "", + "## 7. Tenfold gates", + "", + "- Correctness gate: identical canonical results and supported semantics.", + "- Durability gate: equal acknowledgement level and fault tolerance.", + "- Resource gate: competitor and zu receive the same class limit; OOM is reported.", + "- Statistics gate: lower bound of the 95% confidence interval exceeds 10.0x.", + "- Repeatability gate: two independent operators reproduce within 10%.", + "- Transparency gate: configs, source patches, scripts, plans, and raw samples are public.", + "- Scope gate: title names the query, dataset, scale, cache state, hardware, and metric.", + "", + "## 8. Required workloads", + "", + ] + for i, (key, desc) in enumerate(WORKLOADS, 1): + lines += [ + f"### 8.{i} `{key}`", + "", + f"Workload: {desc}.", + "", + "Variants: hot, warm, cold; one client and saturation; read-only and update interference; uniform and skewed parameters; small and large results.", + "", + "Outputs: correctness digest, p50/p95/p99/p99.9, throughput, CPU/query, peak RSS, bytes read, requests/query, physical bytes, and cost per million operations.", + "", + "Failure rule: an unsupported semantic feature is `unsupported`; timeout, OOM, wrong result, crash, and admission rejection are distinct outcomes.", + "", + ] + lines += [ + "## 9. S3-specific experiments", + "", + "- Empty-cache first query at 1M, 1B, and multi-partition namespaces.", + "- One-hop and three-hop request count versus frontier size.", + "- Coalescing tradeoff curve: extra bytes versus saved requests.", + "- Cache hit bytes and hit operations separately.", + "- Cache loss storm with admission enabled.", + "- Tenfold QPS spike under fixed monthly envelope.", + "- SlowDown/429/503 injection and retry budget.", + "- Range corruption, truncation, wrong-content, and stale-manifest injection.", + "- Writer lease expiry and stale writer acknowledgement attempt.", + "- Lost response at every commit phase.", + "- GC race with publication, long reader pins, backups, and repartitioning.", + "- Cross-region and cross-zone traffic accounting.", + "", + "## 10. Cost model", + "", + "Monthly cost equals compute reservations plus ephemeral/NVMe cache plus object stored bytes plus PUT/COPY/LIST/GET/HEAD requests plus retrieval plus cross-zone and egress bytes plus metadata/control-plane services plus license/support. Every term names provider, region, price sheet date, and free-tier assumptions.", + "", + "Fixed-price qualification replays the worst admitted workload for the plan and proves cost stays within reserve. A higher offered load may be rejected; the rejection is part of the contract and chart.", + "", + "## 11. Publication artifacts", + "", + "- Immutable harness repository commit.", + "- Engine adapters with license-safe patches.", + "- Container and binary digests.", + "- Datasets and expected-result digests.", + "- All configuration files.", + "- Commands and orchestration logs.", + "- Raw samples in an open columnar format.", + "- Plans, profiles, and traces.", + "- System telemetry.", + "- Analysis notebook or script.", + "- Failure and exclusion ledger.", + "- Signed result manifest.", + "- Independent reproduction report.", + "", + "## 12. Competitive strategy", + "", + "Target tenfold wins where architecture creates a structural advantage: compressed local adjacency, factorized property-heavy patterns, resource-bounded embedded operation, fast open/recovery, storage density, S3 request count, stateless read scaling, and total cost for cold large datasets. Target parity and compatibility where ecosystems dominate. Do not spend credibility trying to beat in-memory engines on all-hot algorithms with an S3 cold path.", + "", + "## 13. Stop conditions", + "", + "Do not publish if results depend on unequal durability, missing output materialization, hand-selected query parameters, hidden enterprise features, unreported wrong answers, disabled constraints, different datasets, cache-state ambiguity, a single run, or a competitor configuration rejected by its maintainers as unreasonable.", + "", + "## 14. Sources", + "", + "- [LDBC SNB Interactive](https://ldbcouncil.org/benchmarks/snb/interactive/)", + "- [LDBC Graphalytics](https://ldbcouncil.org/benchmarks/graphalytics/)", + "- [LDBC datasets](https://ldbcouncil.org/benchmarks/snb/datasets/)", + "- [SoK: The Faults in our Graph Benchmarks](https://arxiv.org/abs/2404.00766)", + "", + ] + return ensure_minimum(lines, "the benchmark publication") + + +def scorecard_lines() -> list[str]: + lines = [ + "# 2026 graph-engine landscape scorecard", + "", + f"Research cut: `{RESEARCH_DATE}`", + "Scores are directional engineering assessments, not measured benchmark results.", + "", + "## Scoring rule", + "", + "`strong` means public architecture clearly supports the dimension. `partial` means an adjacent capability exists with important constraints. `weak` means the architecture conflicts with the target. `unknown` means public evidence is insufficient. No numeric total is produced because weights depend on workload and unknowns are not zeros.", + "", + "## Engine summary", + "", + ] + for i, e in enumerate(ENGINES, 1): + remote = "partial" if any(x in e.object_store.lower() for x in ("direct", "object", "lake", "onelake")) and "not" not in e.object_store.lower() else "weak" + distributed = "strong" if any(x in e.distribution.lower() for x in ("shard", "distributed", "scale-out", "partition")) else "partial" if any(x in e.distribution.lower() for x in ("replica", "cluster", "ha")) else "weak" + active = "weak" if any(x in e.status.lower() for x in ("archived", "legacy")) else "strong" + lines += [ + f"### {i}. {e.name}", + "", + f"- Family: {e.family}.", + f"- Lifecycle confidence: {active} — {e.status}.", + f"- Distributed-capacity alignment: {distributed} — {e.distribution}.", + f"- S3-authoritative alignment: {remote} — {e.object_store}.", + f"- Scale evidence: {e.scale}.", + f"- Principal benchmark issue: {e.benchmark}.", + f"- zu decision: {e.verdict}", + "", + ] + lines += [ + "## Structural winners by dimension", + "", + "- Embedded analytical execution: LadybugDB/Kuzu lineage and DuckPGQ.", + "- Sparse matrix traversal: FalkorDB.", + "- Hot mutable in-memory graph: Memgraph.", + "- Cypher ecosystem and mature operational database: Neo4j.", + "- Audited distributed throughput: GraphScope Flex and Huawei GES disclosures.", + "- Mature MPP graph analytics: TigerGraph.", + "- Distributed open graph stores: NebulaGraph, HugeGraph HStore, JanusGraph, Dgraph.", + "- Graph over lake/warehouse authority: PuppyGraph and Fabric Graph.", + "- Standards-integrated relational graph: Spanner Graph, Oracle SQL/PGQ, DuckPGQ.", + "- RDF reasoning and semantic operations: Stardog, GraphDB, Virtuoso, AllegroGraph.", + "- Immutable versioned graph: TerminusDB.", + "- Rust-native emerging graph/vector: HelixDB and SurrealDB; Rust RDF: Oxigraph.", + "", + "## White space", + "", + "No open system in this inventory conclusively combines immutable object-authoritative graph packs, stable logical edge identity, batched frontier range reads, vector/factorized GQL execution, enforced per-query request budgets, independently fenced partition writers, stateless horizontal readers, and FDR-quality cost benchmarks. That combination is zu's opportunity and its verification burden.", + "", + "## Architecture choices rejected", + "", + "- Remote KV call per adjacency entry.", + "- Reusing physical CSR slots as logical edge identity.", + "- Treating a manifest conditional write as a complete writer-fencing protocol.", + "- Claiming distributed ACID across independently published partition roots.", + "- Promising fixed cost from an assumed cache-hit rate.", + "- Benchmarking only query execution while excluding graph build/index time.", + "- Comparing hot in-memory execution with cold remote execution under one label.", + "- Claiming PB scale only by multiplying a compression ratio.", + "- Claiming universal 10x based on a selected latency microbenchmark.", + "", + ] + return ensure_minimum(lines, "the landscape scorecard") + + +def write_doc(name: str, lines: Iterable[str]) -> None: + (ROOT / name).write_text("\n".join(lines).rstrip() + "\n", encoding="utf-8") + + +def main() -> None: + ROOT.mkdir(parents=True, exist_ok=True) + for e in ENGINES: + write_engine(e) + write_doc("000-index.md", index_lines()) + write_doc("system-target-architecture.md", architecture_lines()) + write_doc("system-benchmark-and-10x-claim.md", benchmark_lines()) + write_doc("system-landscape-scorecard.md", scorecard_lines()) + + +if __name__ == "__main__": + main()