[lab1207]

Closes #918.

The problem

A U64 parameter bound to a value above i64::MAX was refused at bind time:

params rejected: param 'v': value 18446744073709551615 exceeds current engine range for U64 (max 9223372036854775807)

The literal carrier was a signed 64-bit integer, so every unsigned value above i64::MAX was rejected on the way in — a U64 column holding 18446744073709551615 was unreachable, and a mutation parameter above i64::MAX failed the same way.

The fix

The carrier is widened to i128 and the value is narrowed at a typed boundary, from the declared type:

• Literal::Integer carries an i128 (crates/omnigraph-compiler/src/query/ast.rs), so I32, I64, U32 and U64 share the one spelling and no value is lost on the way in.
• crates/omnigraph-compiler/src/query_input.rs — the bind path — no longer refuses an unsigned value above the signed range; it carries the exact value.
• The engine narrows where a value meets a concrete type: crates/omnigraph/src/engine/typed_value.rs and crates/omnigraph/src/exec/mutation.rs use try_from against the declared type, so an I64 target still refuses a value outside i64 — with the error naming the value and the range.
• crates/omnigraph/src/engine/constant.rs keeps a public constant's whole value instead of refusing a U64 above i64::MAX.

The saved-plan wire form gains one arm: the pinned serde buffers carry no i128, so a wide integer travels as its decimal text (crates/omnigraph-planner/src/mirror.rs, WideInteger). A text that is not an integer refuses the decode instead of becoming another value. The integer arm keeps its form and its meaning, so existing saved plans still decode; a plan that uses the new arm is one no earlier binary could produce.

The frozen v1 engine

This change touches crates/omnigraph-reference-engine — the frozen v1 engine — in two places only: resolve_to_int and the projection literal now narrow a wide value and refuse it, exactly as v1 behaved before, because a value outside v1's i64 range has no v1 meaning. The pinned file hashes in crates/omnigraph-reference-engine/tests/frozen.rs are updated in this pull request, as the change requires, and the v1 behaviour itself is unchanged: narrow, refuse, no new behaviour.

Test

• crates/omnigraph-compiler/src/query_input.rs — the old to_param_rejects_unsigned_values_outside_engine_range is reversed into to_param_keeps_unsigned_values_above_the_signed_range_issue_918 (u64::MAX binds exactly), and a new test binds the decimal string "18446744073709551615" to a declared U64 parameter.
• crates/omnigraph-planner/tests/integration/bound_plan.rs — a_wide_bound_value_reads_back_exactly_issue_918: a saved plan whose value table holds u64::MAX and i64::MIN serializes (the wide value appears as its decimal text) and reads back equal.
• crates/omnigraph-gqt/cases/issue_918_u64_param_above_i64_max.gqt — the end-to-end case: a U64 column seeded with 18446744073709551615, a read with the parameter bound to that value (in the JSON-number form and in the decimal-string form the wire uses) returns exactly the seeded row, a mutation with the same parameter writes a row carrying the full value, and the final read shows both rows with the value intact — exact, not rounded.
• crates/omnigraph-gqt/cases/range_constraint_compares_integers_exactly.gqt — its note said "mutation parameters stop at i64::MAX", which is no longer true; the note is corrected and a step shows a U64 mutation parameter above i64::MAX reaching the @range check.
• docs/user/queries/index.md — the parameter's range joins the declarations paragraph and the decimal-string advice joins the JSON input paragraph. The page was already exactly at the 350-line cap that scripts/check-docs.py enforces, so each fact had to fit an existing paragraph; two pointer sentences that stood alone now close the paragraph they belong with.

Judgement calls, flagged

• BOUND_PLAN_VERSION is bumped to 11. The integer arm keeps its wire form and meaning, so a plan that holds only in-range values still decodes unchanged. The wide_integer arm is new, though, and version 10 has to name one schema: an older reader that meets the arm refuses on the version before it reaches the arm, and says so. Regenerate saved plans; the change ships a breaking note.
• Query-text integer literals are unchanged — still parsed as i64, so 18446744073709551615 written directly in a .gq file is still a parse error. That is a language decision and not part of this issue.
• No public result surface for a value above i64::MAX was added; results still come from Arrow columns, which already carried UInt64 exactly.

Note on validation

I did not build or run anything locally — CI on this pull request is the judge. The change adds no dependency and no new process or filesystem lifecycle.

Model Used

MiniMax M3.1 Flash Free via the opencode agent harness (minimax-m3.1-flash-free)

[ragnorc]

Do not merge this commit. The compiler crate does not build.

The change is the right repair for issue 918 once the two ToParam calls compile. A declared U64 parameter can then carry every value from 0 through 18446744073709551615.

Why

Storage, comparison, range checks, and scan pushdown already accept a full U64. The shared literal carrier was i64. Bind refused 18446744073709551615 before planning, with exceeds current engine range for U64 (max 9223372036854775807).

What this change does

Literal::Integer becomes i128 (crates/omnigraph-compiler/src/query/ast.rs). One spelling still serves I32, I64, U32, and U64. A typed boundary narrows with try_from:

• typed_scalar builds ScalarValue::UInt64 from u64::try_from (crates/omnigraph/src/engine/typed_value.rs).
• literal_to_typed_array does the same for a mutation column and for a UInt64 list (crates/omnigraph/src/exec/mutation.rs).

A declared U64 parameter parses with parse_u64_param and is stored as Literal::Integer(i128::from(value)) (crates/omnigraph-compiler/src/query_input.rs). In Standard mode a JSON number and a decimal string both parse.

The saved-plan mirror keeps the integer arm for a value that fits in i64. A wider value becomes wide_integer and travels as decimal text (crates/omnigraph-planner/src/mirror.rs). Pinned serde has no i128 content arm, so the string is the sound wire form. BOUND_PLAN_VERSION stays 10.

v1 narrows with i64::try_from and refuses any other value (crates/omnigraph-reference-engine/src/projection.rs, literal_to_expr in crates/omnigraph-reference-engine/src/query.rs). The frozen-file pins match those sources.

Blocking

ToParam for isize and ToParam for usize call i128::from(self) (crates/omnigraph-compiler/src/query_input.rs, lines 129 and 159). Rust does not implement From<isize> or From<usize> for i128.

cargo check -p omnigraph-compiler --locked --offline on 202153ab592991e8c2d22040271378ff065bc14c fails with E0277 at both lines (rustc 1.97.1). The failure is in the library, so the workspace cannot build. The checks on this head did not compile the crate (action_required on DST, GQ Logic Tests, and CI).

Replace both calls with i128::try_from. Return the existing parameter error when the conversion fails. On every current Rust target, usize and isize are at most 64 bits, so the conversion keeps every value. On this host, usize::MAX becomes 18446744073709551615 and isize::MIN becomes -9223372036854775808.

The previous impl used i64::try_from, which compiles. i128::from does not.

Optional

1. Extend crates/omnigraph-gqt/cases/issue_918_u64_param_above_i64_max.gqt with the rest of the class. The shipped case checks equality on u64::MAX as a JSON number and as a decimal string, then an insert. After a local compile repair (see Validation), a temporary case also passed these steps:

• The decimal string 9223372036854775808 returns that stored U64.
• A U64 value 9223372036854775808 compared with an I64 property returns no row. That is an exact cast. A float cast would treat 2^63 and i64::MAX as the same value.
• List membership with in and ($vs contains $i.size) selects [u64::MAX, 0].
• update Item set { tag: "hit" } where size = $v affects the u64::MAX row.
• With # traversal: auto (that header makes GQT call ensure_indices), the scan is access index_probe size. Without the header the btree is absent and access stays sequential. The rows stay exact either way.
• 18446744073709551616, JSON -1, and the string "-1" fail with expected unsigned.

Leave expect same as v1 off this case. v1 fails the same query with integer literal is outside the 64-bit range. That is the specified v1 contract.

2. Bump BOUND_PLAN_VERSION when you add wide_integer. A value inside i64 stays on the old arm, so an old plan still decodes. A plan that contains a wide value is still version 10. An older reader of version 10 fails inside cannot read saved bound plan; regenerate it with this version, from the unknown variant, and does not report a version mismatch. The round-trip test bound_plan::a_wide_bound_value_reads_back_exactly_issue_918 passed. A bump makes version 10 name one schema. The issue triage allows the new arm or the bump. I recommend the bump.

3. Two language edges stay on i64. That matches the split in the issue. A query-text integer is still let n: i64 (crates/omnigraph-compiler/src/query/parser.rs, line 1566). A schema @range bound is still an i64. An undeclared Standard parameter above i64::MAX still becomes a float (json_value_to_literal_inferred). JavaScript mode still refuses a numeric U64 above 2^53 and accepts a decimal string. Server, CLI, and GQT call Standard mode.

Liability

One i128 carrier is the durable fix. A second Unsigned variant, or a large U64 carried as a float or a string, would split equality and hashing. The wider carrier costs a few bytes per literal. A query holds few literals. Correctness of the declared range comes first. The extra width is acceptable.

v2 pushdown builds a typed DataFusion value (ScalarValue::UInt64). It does not use Lance's SQL number() parser, which still tries i64, then u64, then f64 in Lance 13.0.0. A later Lance release does not replace this carrier change, and it does not reopen this bug while pushdown stays typed.

Public U64 sums still round to F64 after an exact Decimal128 total (issue 858). This change leaves that contract in place.

The user guide and changelog.d/u64-param-above-i64-max.fixed.md describe the new parameter range and the decimal-string wire form. The changelog link target #declarations-and-parameters matches the heading in docs/user/queries/index.md.

Validation

Reviewed commit: 202153ab592991e8c2d22040271378ff065bc14c. Base used for the before run: b692610c4aa31066cb6a9fd34830f56977288943.

Before, on that base, with the new case file present only for the run:

cargo test -p omnigraph-gqt --locked --test gq_logic_tests issue_918_u64_param_above_i64_max -- --test-threads=4 --nocapture

Result: failed, for the predicted reason. params rejected: param 'v': value 18446744073709551615 exceeds current engine range for U64 (max 9223372036854775807). 0 passed, 1 failed, 412 filtered out, 0.58s.

On the reviewed commit:

cargo check -p omnigraph-compiler --locked --offline failed with E0277 at query_input.rs:129 and :159.

cargo fmt --all --check passed.

The official GQT case cannot run on the unmodified commit, because the crate does not build.

I then applied a local-only i128::try_from repair at those two ToParam impls, ran the tests below, and restored the file. These results are not a pass of commit 202153ab.

• issue_918_u64_param_above_i64_max passed in 0.66s.
• range_constraint_compares_integers_exactly passed in 0.64s, including the new U64 parameter step 9223372036854775808.
• cargo test -p omnigraph-compiler --lib query_input::tests : 17 passed.
• cargo test -p omnigraph-reference-engine --test frozen passed.
• cargo test -p omnigraph-planner --locked --offline --test integration bound_plan::a_wide_bound_value_reads_back_exactly_issue_918 -- --exact passed.
• A temporary class case, removed after the run, passed in 0.72s and included the index probe.
• A temporary v1 comparison showed v2 returning the matching row and v1 failing with integer literal is outside the 64-bit range.

Limitations

I did not run the HTTP server or the CLI as separate processes. Both call json_params_to_param_map in Standard mode, which is the path the GQT case runs. I did not run DST or the full workspace test graph. GitHub checks on this head show action_required for DST, GQ Logic Tests, and CI, so they are not compile evidence. The host is Linux x86_64, rustc 1.97.1. The reported environment was macOS arm64. The From bound is the same on both, and usize is 64 bits on both.

Inline comments that would have been attached:

• crates/omnigraph-compiler/src/query_input.rs:129: i128::from(self) does not compile: From<isize> is not implemented for i128. Use i128::try_from(self) and return the parameter error on failure. The same repair applies to usize on line 159. On current targets the conversion keeps every value.
• crates/omnigraph-compiler/src/query_input.rs:159: i128::from(self) does not compile: From<usize> is not implemented for i128. Use i128::try_from(self) and return the parameter error on failure. Same repair as the isize impl on line 129.

[lab1207]

Thanks — that was the whole build break, and you were right about the cause.

Fixed in 1548786a: ToParam for isize and ToParam for usize now cast (self as i128) instead of calling i128::from(self). The widening is exact, and as i128 is the spelling the workspace already uses for these conversions (crates/omnigraph/src/engine/mutation.rs, crates/omnigraph/src/engine/coerce.rs), so the two arms match the code around them.

I confirmed the trait bounds with the local toolchain rather than from memory:

$ rustc --edition 2021 fromtest.rs
error[E0277]: the trait bound `i128: From<isize>` is not satisfied
  = help: `i128` implements trait `From<T>`:
            From<bool> From<i16> From<i32> From<i64> From<i8>
            From<u16> From<u32> From<u64> From<u8>

so the other i128::from(self) arms (i8, i16, i32, i64, u8, u16, u32, u64) are fine and only the two pointer-sized ones needed the cast.

One limit to be explicit about: I could not run cargo check on the crate here — this machine has no cached crates.io dependencies and the workspace pins a toolchain I did not fetch, so the offline build stops at arrow-array. The change is the two arms the error named, and the trait bounds are verified above; the workspace build itself is CI's to confirm.

[ragnorc]

The compile break is fixed. The parameter change is sound. Do not merge yet. One documentation check is still red.

Why

A declared U64 parameter could not carry a value above i64::MAX. Bind refused 18446744073709551615 before planning. The error was exceeds current engine range for U64 (max 9223372036854775807).

Storage, comparison, range checks, and scan pushdown already accept a full U64. The shared literal carrier was i64.

What this change does

Literal::Integer is now i128 (crates/omnigraph-compiler/src/query/ast.rs). One spelling serves I32, I64, U32, and U64. A typed boundary narrows with try_from.

• typed_scalar builds ScalarValue::UInt64 from u64::try_from (crates/omnigraph/src/engine/typed_value.rs).
• literal_to_typed_array does the same for a mutation column and for a UInt64 list (crates/omnigraph/src/exec/mutation.rs).

A declared U64 parameter parses with parse_u64_param and is stored as Literal::Integer(i128::from(value)) (crates/omnigraph-compiler/src/query_input.rs). In Standard mode a JSON number and a decimal string both parse.

The saved-plan mirror keeps the integer arm for a value that fits in i64. A wider value becomes wide_integer and travels as decimal text (crates/omnigraph-planner/src/mirror.rs). Pinned serde_json 1.0.150 has no i128 content arm (arbitrary_precision is off), so the string is the sound wire form.

v1 narrows with i64::try_from and refuses any other value (crates/omnigraph-reference-engine/src/projection.rs). The frozen-file pins match those sources.

Delta since 202153a

1548786a changes only the two ToParam arms. isize and usize now use self as i128. Rust has no From<isize> or From<usize> for i128. That was the E0277 at the two lines.

On this host, and on every target rustc 1.97 supports, isize and usize are at most 64 bits. The cast keeps every value. usize::MAX becomes 18446744073709551615. isize::MIN becomes -9223372036854775808.

The author said this machine could not run cargo check. This head does compile. CI Lint (clippy) passed. A local rebuild of the head compiler and engine passed the regression below.

Earlier findings

1. Blocking compile break (E0277 on ToParam for isize and ToParam for usize). Resolved. The two arms cast, the crate builds, and the tests below pass.
2. Optional. Extend issue_918_u64_param_above_i64_max.gqt with the rest of the class. Still open. The shipped case covers the issue. A temporary case on this head passed the extra steps and was removed. It is not in the pull request.
3. Optional. Bump BOUND_PLAN_VERSION when adding wide_integer. Still open. The constant in crates/omnigraph-planner/src/bound.rs is still 10.

Blocking

docs/user/queries/index.md has 354 lines. scripts/check-docs.py allows 350 lines for an authored user page unless the page contains docs-check: allow-long-page. The pull request base and current main both have 350 lines. The new paragraph is the 4 added lines.

Check AGENTS.md Links failed on this head. The log says docs/user/queries/index.md: authored user page exceeds 350 lines. CI Gate fails for that job alone (check_agents_md). Every other check on 1548786a passed, including Test Workspace, GQT (ordinary), Lint (clippy), and DST pinned suite.

Shorten the page to 350 lines. Use the reviewed exemption marker only if a reviewer accepts a longer page.

Optional

1. BOUND_PLAN_VERSION stays 10. A value inside i64 stays on the old arm, so an old plan still decodes. A plan that contains wide_integer is still version 10. An older reader fails inside cannot read saved bound plan; regenerate it with this version, from the unknown variant. The error does not name a version mismatch. A bump makes version 10 name one schema. The round-trip test passed either way.

2. The shipped case checks equality on u64::MAX as a JSON number and as a decimal string, then an insert. These extra steps also passed on this head, in a temporary case that was deleted afterward:

• The decimal string 9223372036854775808 returns that stored U64.
• With # traversal: auto, the scan is access index_probe size.
• A U64 value 9223372036854775808 compared with an I64 property returns no row.
• $i.size in $vs with [u64::MAX, 0] selects those two rows.
• update Item set { tag: "hit" } where size = $v affects the u64::MAX row.
• 18446744073709551616, JSON -1, and the string "-1" fail with expected unsigned.

Leave expect same as v1 off this case. On this head, v2 returns the matching row and v1 fails with integer literal is outside the 64-bit range.

Liability

One i128 carrier removes the i64 ceiling for every declared integer parameter. A second Unsigned variant, or a large U64 carried as a float or a string, would split equality and hashing. The wider carrier costs a few bytes per literal. A query holds few literals. Correctness of the declared range comes first.

The new wide_integer arm is one extra wire spelling. It fails closed. Five more integer widths fit in the same carrier. They do not need another literal variant.

v2 pushdown builds ScalarValue::UInt64. Lance 13.0.0 SQL number() still tries i64, then u64, then f64 (lance-datafusion-13.0.0 planner.rs). This path does not call that parser. A later Lance release does not replace this carrier, and it does not reopen this bug while pushdown stays typed.

Public U64 sums still round to F64 after an exact Decimal128 total. This change leaves that contract in place.

A query-text integer is still i64 (crates/omnigraph-compiler/src/query/parser.rs). A schema @range bound is still an i64. An undeclared Standard parameter above i64::MAX still becomes a float. JavaScript mode still refuses a numeric U64 above 2^53 and accepts a decimal string. Server, CLI, and GQT call Standard mode.

Validation

Reviewed commit: 1548786aa1898f6a6c6b62d9bd04980151156a55. Before commit: b692610c4aa31066cb6a9fd34830f56977288943. Host: Linux x86_64, rustc 1.97.1.

Before, on that base, with the new case file present only for the run:

cargo test -p omnigraph-gqt --locked --test gq_logic_tests issue_918_u64_param_above_i64_max -- --test-threads=4 --nocapture

Result: failed, for the predicted reason. params rejected: param 'v': value 18446744073709551615 exceeds current engine range for U64 (max 9223372036854775807). 0 passed, 1 failed, 412 filtered out, 0.59s.

On the reviewed commit, after a rebuild of this head:

• The same command passed in 0.62s. 1 passed.
• range_constraint_compares_integers_exactly passed in 0.63s.
• cargo test -p omnigraph-compiler --locked --lib query_input::tests: 17 passed.
• cargo test -p omnigraph-planner --locked --test integration bound_plan::a_wide_bound_value_reads_back_exactly_issue_918 -- --exact passed.
• cargo test -p omnigraph-reference-engine --locked --test frozen passed.
• The temporary class case passed in 0.63s, including the index probe. It was removed after the run.
• The temporary v1 comparison showed v2 returning the row and v1 failing with integer literal is outside the 64-bit range. It was removed after the run.

CI on this head: Lint (clippy), Format, Test Workspace, GQT (ordinary), GQ Logic Tests, and DST pinned suite passed. Check AGENTS.md Links failed. CI Gate failed because of check_agents_md.

Limitations

I did not run the HTTP server or the CLI as separate processes. Both call json_params_to_param_map in Standard mode, which is the path the GQT case runs. I did not run the full workspace test graph locally. CI Test Workspace passed on this head.

Inline comment on docs/user/queries/index.md line 47 (RIGHT):

This paragraph makes the page 354 lines. scripts/check-docs.py allows 350 lines unless the page contains docs-check: allow-long-page. The base file and current main are both 350 lines. Check AGENTS.md Links fails on this head with authored user page exceeds 350 lines, and CI Gate fails for that job. Shorten the page by 4 lines.

Inline comment on crates/omnigraph-planner/src/mirror.rs line 1408 (RIGHT):

Optional. wide_integer is new and BOUND_PLAN_VERSION is still 10. A value inside i64 stays on the integer arm, so an old plan still decodes. A plan that contains this arm is also version 10. An older reader fails on the unknown variant inside cannot read saved bound plan; regenerate it with this version. The error does not name a version mismatch. Bump the constant so version 10 names one schema.

[lab1207]

Thanks for the detailed review — the compile break is fixed and the parameter change is sound, and I have taken both remaining items.

The documentation check. You were right that the paragraph broke the CI gate: scripts/check-docs.py refuses an authored user page over 350 lines, and docs/user/queries/index.md was already exactly at the cap, so the new paragraph took it to 354 and failed Check AGENTS.md Links.

Each fact now sits in the paragraph that already covers its subject, so nothing had to be cut:

• the parameter's range joins the declarations paragraph, which is where parameter types are described;
• the decimal-string advice joins the JSON input paragraph, which is where JSON input is described.

Two pointer sentences that stood alone as their own paragraphs ("Use full-text search ..." and "See Branches, Commits, and History.") now close the paragraph they belong with. No sentence is dropped from the page — I checked the old page sentence by sentence against the new one, and the only two that differ are the ones this change moves.

$ python scripts/check-docs.py
Documentation OK (386 Markdown files checked).

The page is 349 lines, one under the cap.

The plan version. You are right that version 10 has to name one schema. The integer arm keeps its wire form and meaning, so a plan holding only in-range values still decodes unchanged, but the wide_integer arm is a new wire form: an older reader that meets it refuses on the unknown variant inside cannot read saved bound plan; regenerate it with this version, which does not name a version mismatch. So the envelope is bumped to 11, and an older reader now refuses on the version before it reaches the arm.

The constant's doc comment records what version 11 adds, docs/user/queries/explain.md and docs/dev/execution.md name the new envelope version, and the change ships a breaking note: plans saved with earlier binaries have to be regenerated.

$ python scripts/release_notes.py preview --working-tree
...
- Saved query plans now use envelope version 11, which carries a `U64` parameter above `i64::MAX` as its decimal text. Regenerate plans saved with earlier binaries; older binaries reject version 11 plans.

Validation. I did not build or run anything locally — CI on this pull request is the judge, as before. The documentation checks above are the two Python checks in this repository that need no toolchain, and both pass. The change adds no dependency and no new process or filesystem lifecycle.