Skip to content

feat(query): pseudo-attributes across joins and :db/valid-at on the streaming engine (#545) - #595

Merged
adityamukho merged 4 commits into
v3from
feat/545-pseudo-joins
Oct 14, 2026
Merged

adityamukho merged 4 commits into
v3from
feat/545-pseudo-joins

Conversation

@adityamukho

Copy link
Copy Markdown
Collaborator

Part 3 of 3 for #545 (#473, part 3 of 9). Plan: docs/superpowers/plans/2026-10-14-545-joins.md, steps 10–13.

What changes

  • Pseudo-attributes across joins. A per-fact pseudo-attribute pattern (:db/valid-from, :db/valid-to, :db/tx-count, :db/tx-id) reads, as the executor does, the fact of the last pattern with a stored attribute before it in plan order that matched its entity (decision 4). The scans of those patterns fill metadata columns. The pseudo-attribute step then picks one column per row: the latest pattern with the same entity term always matched, and later patterns on other entity terms override it on rows where their entity is join-equal.
  • Which shapes run on the engine. The pattern's entity term is the entity term of an earlier pattern, or no pattern with a stored attribute runs before it. In the second case, and for every :db/valid-at pattern, it joins with every visible fact of its entity, as [e _ _] would, with the metadata or the query's valid time (nil under :any-valid-time) as a column. Other shapes stay on the executor: a pseudo-attribute pattern on an entity that no earlier pattern has as its entity, a _ entity, or an expression that rebinds an entity variable.
  • Follow-up: Pseudo-attribute metadata depends on plan order #594, the plan-order dependence of pseudo-attribute metadata (milestone v3.0.0).
  • New envelope shape join_2_pseudo.

Measurements (#394 envelope, idle server, A/B on separate sockets, swapped between rounds)

join_2_pseudo 100K 1M 10M
p50, v3 → PR 211 ms → 40–58 µs 3.19 s → 55–56 µs 33.8–34.1 s → 56 µs
peak RSS 122 → 4 MiB 857–858 → 4 MiB 6.0–7.5 GiB → 4 MiB

Every other shape is unchanged. At 10M (first 10M run of the PR 2 join shapes): join_2 51 µs / 4 MiB, join_3_selective 2.5 s / 66 MiB, join_3_scan 13.6 s / 59–63 MiB. Release binary is 1,162.8 KiB (+7.6 KiB; the limit is 1,200 KiB).

Tests

  • query::engine::tests oracle matrix: 17 pseudo-attribute join shapes (per-row choice, constant entities, pseudo-attribute patterns planned first, cross products, expressions) and 7 :db/valid-at shapes at every temporal. A mutation that drops the per-row choice fails the oracle.
  • The routing test lists the shapes that stay on the executor.
  • 1503 tests (1493 passing, 10 ignored), unchanged in count. Also clean: --features test-oracle over the whole suite, the engine tests under --features wasm (source order), and clippy for native, wasm, browser and WASI.
  • Codex review raised one finding (a later pattern on another entity term overwriting the metadata). Its query and its mirror agree with the executor natively and under wasm, so it is a false positive; both are now tests.

Docs

CHANGELOG.md, CLAUDE.md, ROADMAP.md, docs/TEST_COVERAGE.md, docs/BENCHMARKS.md. Docs site: project-minigraf/minigraf-docs PR (join rules and pseudo-attributes in the Datalog reference, the streaming-engine section of the architecture page).

No public API change and no new error code, so no binding cascade.

🤖 Generated with Claude Code

https://claude.ai/code/session_01HyLscCUuJ1GQpdAeX79EdR

adityamukho and others added 4 commits October 14, 2026 20:53
…545)

A per-fact pseudo-attribute pattern reads, as the executor does, the
metadata of the last pattern with a stored attribute before it in plan
order that matched its entity: the scans of those patterns fill metadata
columns, and the pseudo-attribute step picks one per row (decision 4 of
the #545 plan). The engine runs it when its entity term is the entity
term of such a pattern, or when no such pattern runs before it; then, and
for every :db/valid-at pattern, it joins with every visible fact of its
entity, as [e _ _] does, with the metadata (or the query's valid time) as
a column. Other shapes stay on the executor; #594 tracks the plan-order
dependence.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01HyLscCUuJ1GQpdAeX79EdR
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01HyLscCUuJ1GQpdAeX79EdR
…other entity term (#545)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01HyLscCUuJ1GQpdAeX79EdR
@codecov

codecov Bot commented Oct 14, 2026

Copy link
Copy Markdown

Codecov Report

❌ Patch coverage is 97.59036% with 4 lines in your changes missing coverage. Please review.

Files with missing lines Patch % Lines
src/query/engine/filter.rs 88.46% 3 Missing ⚠️
src/query/engine/plan.rs 99.21% 1 Missing ⚠️

📢 Thoughts on this report? Let us know!

@adityamukho
adityamukho merged commit de9291c into v3 Oct 14, 2026
26 checks passed
@adityamukho
adityamukho deleted the feat/545-pseudo-joins branch October 14, 2026 16:54
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant