refactor: deterministic literal property targets + indexed WHERE filters

[HexaField]

Summary

Two coupled changes to how resolveLanguage='literal' property values flow through the executor.

Property writes become deterministic. Today, setting a literal-language property routes through LanguageController.expression_create, which signs the value into a literal:json:<envelope> URL containing {author, timestamp, data, proof} — the same author + timestamp the link reifier already carries. The signature varies per write, so writing name = "general" produces a different IRI every time, and exact-match SPARQL filters never hit. This PR drops the wrap: resolve_property_value emits a plain literal:string:X (or :number: / :boolean: / :json: for primitives) URL via literal_encode directly. The reifier remains the single source of truth for per-link provenance.

WHERE filters use the index. With deterministic IRIs in storage, the WHERE builders for the model query layer can emit direct IRI matches (?source <pred> <literal:string:X>) instead of wrapping every target in a custom fn/parse_literal SPARQL function call. Native POS-index probe replaces a per-row function call.

cc @lucksus @data-bot-coasys — lands on top of #803's history. Commit range a9e98ccd..a00b595b iterated this same territory; the 353a7ad7 revert was driven by integration tests that codified the envelope shape, which this PR restructures.

What changed

Writes (executor)

• perspective_instance.rs::resolve_property_value — when resolve_language == "literal", encodes the value directly via literal_encode and returns the plain URL. Other resolveLanguage values (real language controllers — note, image, etc.) still go through expression_create; those produce addressable signed expressions by design.
• languages/literal.rs::literal_decode — no longer wraps primitive return values in a synthetic {author: "<unknown>", timestamp: "<unknown>", data: …, proof: {}} envelope. Returns the raw value. Genuine signed expressions (JSON objects) pass through unchanged.
• core/src/perspectives/SparqlBindings.ts::parseLit — drops the .data extraction branch. With property values now stored as plain literals, the Literal.fromUrl(val).get() result is already the value, and the only objects it returns are real JSON payloads (which we JSON-stringify for display).

Migration

• Restored migrate_signed_envelopes_to_plain_literals (originally landed in a9e98ccd, removed by 353a7ad7). On startup it walks every reifier, finds targets shaped as literal:json:<envelope> whose JSON has data+author+proof, extracts the inner value, and rewrites both the direct triple and the reifier (the reifier IRI hash includes the target, so it must be recomputed). Idempotent — short-circuits at migration_version >= 3. Wired into initialize_from_db after the named-graphs migration.
• Envelope-unwrap branches retained in parse_literal_fn and parse_literal_value so SPARQL queries continue to handle pre-migration data + the small set of expressions that are themselves stored as signed envelopes (e.g. entanglement proofs in the dapp).

Indexed WHERE filters

• model_query/sparql_builder.rs — is_literal_prop equality WHERE filters emit ?source <pred> <literal:string:X_encoded> directly. String / number / boolean / StringArray / NumberArray covered. Ops (gt/lt/between/contains/not) keeps fn/parse_literal since it needs typed comparison.
• Fallback for constructor-default raw IRIs (e.g. state = 'todo://ready' on a resolveLanguage='literal' property — the #803 d3da07d7 case): { ?source <pred> <literal:string:encoded> } UNION { ?source <pred> <raw-iri> }. Both branches are POS-index probes; the planner picks one.
• model_query/projection.rs::build_projection_where_patterns — same transformation for the projection WHERE-clause builder. pred_lookup widened to carry is_literal_prop.

Tests

• tests/js/tests/prolog-and-literals.test.ts — three round-trip assertions flipped from expect(literal.data).to.equal(X) to expect(literal).to.equal(X) to match the new (un-wrapped) Literal.fromUrl().get() return.
• model_query/integration_tests.rs — the helper that built envelope-shaped targets and the tests that asserted query behaviour against them are renamed legacy_envelope_* and now call migrate_signed_envelopes_to_plain_literals before querying (genuine migration tests, not "queries work on envelope storage" tests). Parallel plain_literal_* tests cover the post-migration form.

What did NOT change

• expression.create(value, "literal") still produces signed envelopes wrapped as literal:json:<envelope>. ExpressionClient.get(url)'s envelope fast-path is preserved.
• Agent profile expression API (create_signed_expression for link metadata) is untouched.
• SDNA payload literals (Prolog source strings, SHACL action JSON) — already plain literals before this PR, still plain.
• Multi-user expression-authoring tests — unchanged contract.

Performance

Microbenchmark (bench_indexed_iri_vs_fn_parse_literal_filter in model_query/integration_tests.rs, gated to release builds, scale via WT_BENCH_LINKS) running the two equivalent SPARQL forms against the same literal:string: data on this branch:

n links	indexed direct-IRI	fn/parse_literal FILTER	speedup
1,000	11.4 µs	290.8 µs	25.5×
5,000	12.5 µs	1,476.4 µs	118.4×
10,000	13.5 µs	3,046.1 µs	226.2×
20,000	15.8 µs	6,215.0 µs	394.2×
50,000	39.0 µs	19,436.0 µs	498.8×

Indexed stays flat (POS-index probe — sub-linear in the result count, ~unchanged by the dataset size). FILTER scales linearly because every row materialises through the custom function. Apple Silicon, 5 runs each, warm cache; reproduce with cargo test --release --lib bench_indexed_iri_vs_fn_parse_literal_filter -- --nocapture.

Wind tunnel S8 comparison vs origin/dev was attempted but the cached CUSTOM_DENO_SNAPSHOT.bin produces a V8 magic-number mismatch against fresh executor builds (Check failed: magic_number_ == SerializedData::kMagicNumber), causing the executor to crash on language-runtime init under the wind tunnel's cargo build --release path regardless of branch. That's a tunnel-infrastructure issue unrelated to this PR; the microbench above captures the relevant per-query delta directly.

Test plan

• cargo check --tests clean
• cargo test --lib languages::literal — 4 pass
• cargo test --lib perspectives::model_query::utils — 15 pass
• cargo test --lib perspectives::sparql_store — 78 pass
• cargo test --lib perspectives::model_query — 146 pass (incl. the renamed legacy_envelope_migrated_then_* + new plain_literal_* tests)
• pnpm exec tsc --noEmit (core) — clean
• pnpm exec jest src/Literal.test.ts — 5 pass
• Full CircleCI suite green on this PR
• Wind tunnel s1/s2/s5/s8 + WHERE-heavy scenarios — dev vs this branch
• Integration test runner (tests/js) — full suite
• Manual smoke: spin executor against existing dataset with envelope-encoded literals, verify migration log fires + post-migration query returns expected results

Migration safety

• Idempotent: migration_version >= 3 short-circuits.
• Per-link transactional: each envelope-link replacement is one insert + one delete batch. A crash mid-migration leaves a mix of pre- and post-migration data — both readable thanks to the back-compat envelope-unwrap branches in parse_literal_fn and parse_literal_value.
• Only touches reifier targets where the JSON parses, has .data+.author+.proof, and the new encoded form differs from the old. Won't accidentally rewrite valid literal:json: payloads that aren't envelopes.

Follow-ups

• Typed RDF literals on the wire ("value"^^xsd:string instead of <literal:string:value>) and removing fn/parse_literal registration entirely — tackled in #842, stacked on this PR.
• Pushing last-write-wins / hydration aggregation into SPARQL (currently in Rust) — explored in #846. The straightforward nested-aggregate plan hits an Oxigraph 0.5.8 planner cliff (the warning in ac57680b9 was confirmed empirically at ~23,000× regression). The most plausible unblock is storage-level partitioning from named graphs (#812); re-attempt once that lands and bench whether per-graph scoping flattens the planner working set. Note: SPARQL itself does not have window functions — neither 1.1 nor the W3C 1.2 draft introduces them — so the wait is on Oxigraph planner / dataset semantics, not on a spec change.
• Flux read sites that assumed the envelope shape via .get().data and write sites that produced envelopes via client.expression.create(value, "literal") — handled in coasys/flux#604.

[coderabbitai]

Important

Review skipped

Draft detected.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 819193f5-b23c-4d0c-a9a9-84b3786eb8be

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch refactor/literal-channel-v-separation

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

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