quack: two-world frontend — describe once, resolve once, canonicalize once, execute numeric

[AdaWorldAPI]

This is a follow-up to #1327 and #1326. It is not an IAM change: no consumer's identity model or numeric substrate moves.

DEVELOPER WORLD
    names / strings / host or source types
          ↓
RESOLUTION MEMBRANE            Draft::bind(&dyn Binder)
    resolve semantics
    canonicalize representation
          ↓
RESOLVED NUMERIC WORLD
    fixed-width numeric identities
    canonical little-endian byte ABI where applicable
          ↓
QUACK                          semantic numeric IR (Query / Filter / Cmp)
          ↓
mask-risc / ndarray

What a developer writes

use lance_graph_quack::bind::{table, FieldRef};

let q = table("users").where_eq("smtp", "alice@x.de").count();   // text allowed here
let bound: Query = q.bind(&binder)?;                              // names + literals resolve ONCE
// From here on: no names, no strings, no catalog, no KV.
let program = lower(&bound)?;                                     // execute as often as needed

// Typed descriptors bind to the same thing:
const SMTP: FieldRef = FieldRef::new("users", "smtp");
table("users").where_(SMTP.eq("alice@x.de")).count()

bind produces exactly what a substrate expert would write by hand:

Query { filter: Filter::and([Filter::plane(Mask(0)), Filter::cmp(Col(0), Cmp::EqU32(id))]), agg: Agg::Count }

Byte order is never something the developer writes, and neither is ENDIAN LITTLE in a future CREATE TABLE users WIDTH 512.

Design

• No ResolvedQuery. quack::Query is already the resolved form: Filter, Cmp, Col and Agg are all fixed-width. The new layer exists only in front of it.
• Canonical resolved ABI. Binding removes textual and schema ambiguity, and physical fixed-width byte contracts are canonical little-endian. Quack's Query remains semantic numeric IR; endian handling belongs only at raw-byte and storage boundaries.
  • Cmp::EqU32(0x12345678) is a number and carries no Endian field.
  • EqU32Strided reads it from the bytes [0x78, 0x56, 0x34, 0x12].
  • Byte arrays (Dn128, facet pattern/care bytes) are order-neutral.
  • Register128 stays four little-endian u32 words.
• quack::bind is the crate's only text-bearing module. tests/string_fence.rs checks that the executable IR and its lowering in lib.rs hold no text types. That scan covers over 1,000 lines and has a can-fire half.
  • The resolved-world invariant during population execution is stronger: no names, no strings, no catalog or label lookup, and no ambiguous byte order.
• Binder is the consumer's resolution membrane: catalog, live plane and codebook. Its codebook never mints. Quack is ID-agnostic after binding. A report CAM ordinal, an IAM ValueId/KeyId and a SAP code all arrive as EqU32(u32), and their meaning stays with the binder.
• Schema uses the same lifecycle: create_table("users").width(512) → Registrar → ResolvedTable { id, width }, with no name kept. No crate owns a table catalog or allocation yet, so Registrar has only a test implementation. This is the missing actuator.
• Same shape as contract + mask-risc: resolve read-mode once per population; 16-byte facet match predicate #1326: SlabDeclaration → resolve_for_context → ResolvedReading. The shared rule is the lifecycle (external ambiguity → once → resolved semantic contract + canonical physical contract); the resolved types stay domain-specific. The full table and the byte-boundary audit are in the board entry.

Byte-boundary audit

Every production reader that turns raw bytes into an integer is already explicit little-endian:

• the ndarray strided kernels: eq_u32_strided_to_mask and the group sum;
• mask-risc's reference interpreter;
• quack's aperture_facet_strided;
• Register128, and the NodeGuid accessors.

NodeRow is all [u8; N], so its pointer casts are order-neutral.

There is one reinterpret: FacetCascade::as_bytes / ref_from_bytes, a compute lens over a native u32. It is not stored (NodeRow::edges is [u8; 16]), and a compile-time target_endian = "little" assertion fences it. It is reported, not changed. No production ABI is intentionally native-endian, so nothing persisted was rewritten.

Proofs (each disable-verified red, then restored)

test	proves	disable
bind::a_text_literal_binds_once_to_the_query_an_expert_writes	4 binder calls at bind, 0 on two executions; bound Query and Program == the hand-written ones	drop the live plane
bind::a_typed_descriptor_binds_to_the_same_query	FieldRef and names bind identically; the dead row is excluded	(same)
bind::binding_fails_in_the_developers_vocabulary_and_never_mints	UnknownTable / Field / Value, KindMismatch, OutOfRange, WrongTable	wrong-table check off; i32 range check off
report/tests/quack_bind.rs	report Catalog + CamLabels as a binder: 1 CAM lookup; after a label rename, the new label binds to the identical query and the old one is unknown	bypass the codebook
dir-sim/tests/quack_bind.rs	KeyId field: two spellings → one query; ValueId field: two spellings → two queries; the key query lowers to exactly key_eq_program(key)	bypass the codebook
quack/tests/string_fence.rs	no text in the executable IR	add a String field to lib.rs
quack/tests/canonical_le.rs	EqU32Strided(0x12345678) matches exactly the records holding [0x78,0x56,0x34,0x12], never the swapped spelling (strides 4 and 16, group path and tail); executor and reference agree; Register128::from_words bytes are read back. Literal byte fixtures, so it cannot pass merely on an LE host	ndarray kernel → from_be_bytes; reference reader → from_be_bytes

The reference-reader disable first came back green. Equal LE and BE row counts let the count comparison tie, so the fixture is now asymmetric.

Totals: quack, report and dir-sim tests pass; contract register128 and mask-risc tests pass. fmt and clippy -D warnings are clean.

Deliberately not here

• No SQL parser; SELECT COUNT(*) FROM users WHERE smtp = '…' would parse into the same Draft.
• No Java migration. Target: View.where → Binder → quack::Query, which retires plan_lower. Answer parity is already proven by lowering_convergence.
• No SAP redesign. The gap is that its forward text → code map is dropped at bind; keeping it cold per batch would give SAP a Binder::code.
• No IAM change. users_with_key can become where_eq over the IAM binder in the test.
• No Endian enum, no universal ABI scalar wrapper, no serialization layer, no shared dictionary implementation, no ContentId move, no persisted catalog.

🤖 Generated with Claude Code

https://claude.ai/code/session_01G22yT6htkcdyXsihxxXdrg

[coderabbitai]

Warning

Review limit reached

Your organization has reached its usage spending cap. Adjust your spending cap in the billing tab.

Next included review available in 24 minutes.

Check out review usage here.

View limit details

Limit details: You’ve used all 2 included reviews currently available. Your 54 included PR review attempts over the past 7 days set your current allowance at 2 reviews per hour.

Learn how review limits work.

Review configuration:

⚙️ Run configuration

• Configuration used: Organization UI
• Review profile: CHILL
• Plan: Essentials
• Run ID: b6be6396-2140-49a9-9ad1-8c864bba9d4c

📥 Commits

Reviewing files that changed from the base of the PR and between 11340e5 and b2c6d45.

📒 Files selected for processing (8)

• .claude/board/entries/2026-10-05-quack-two-world-frontend.md
• .claude/board/entries/README.md
• crates/lance-graph-dir-sim/tests/quack_bind.rs
• crates/lance-graph-quack/src/bind.rs
• crates/lance-graph-quack/src/lib.rs
• crates/lance-graph-quack/tests/canonical_le.rs
• crates/lance-graph-quack/tests/string_fence.rs
• crates/lance-graph-report/tests/quack_bind.rs

• Autopilot · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Warning

Billing warning: we have not been able to collect payment for this subscription for more than 72 hours. Please update the payment method or pay any pending invoices in Billing to avoid service interruption.

---

_{Comment @coderabbitai help to get the list of available commands.}

[cursor]

Bugbot couldn't run - usage limit reached

Bugbot is counted against Cursor usage for this user or team, and this run hit a usage or spend limit.

A user or team admin can review and increase usage limits in the Cursor dashboard.

(requestId: 968ab1ee-c745-443e-b271-15e24c91ec6b)

[AdaWorldAPI]

test-with-coverage failed on d3f4255f, but not in a test: it failed in the Upload coverage to Codecov step, on a TLS handshake (ssl/tls alert handshake failure … SSL alert number 40). The coverage tests themselves passed. The step sets fail_ci_if_error: false, so the job still went red on a failure inside the upload action. This is the same Codecov TLS failure #1327 hit twice, and nothing in this PR touches the upload path. No fix exists on the repo side yet; the head has since moved to b2c6d456, and that run will show whether the failure recurs.

---

Generated by Claude Code