BE-921: Batch entity patch reads and writes

[montekki]

🌟 Purpose

patch_entities writes each patch separately. This change resolves patches in input order and persists their combined changes in bulk within one transaction. Repeated entity IDs see earlier edits and retain one result per input.

🔍 Changes

• Lock and load requested histories together, including live history needed to publish a draft. Check permissions and validate each patch against the state produced by preceding patches.
• Track original and resulting temporal rows to combine repeated edits into final updates, insertions, and removals. Close live intervals before publishing drafts, and preserve intermediate editions returned to callers.
• Insert editions, drafts, temporal rows, and type memberships in bulk. Update temporal intervals and provenance in bulk, then populate edition caches.
• Build entity authorization contexts within the Postgres store through the existing context builder, reusing loaded principal data across the batch.
• Document the main functions with brief descriptions of their purpose.

Start review at patch_entities: load, resolve, write, commit. batch/mod.rs resolves patches, history.rs tracks temporal changes, and batch/write.rs persists them.

Validation: 661 store, integration, and authorization tests passed; two were skipped. Coverage includes repeated entities, reverse decision times, draft publication, changed permissions, link dependencies, intermediate edition caches, and rollback. Clippy, rustdoc with warnings denied, formatting, and whitespace checks passed.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
petrinaut	Ready	Preview	Oct 20, 2026 12:59pm UTC

3 Skipped Deployments

Project	Deployment	Actions	Updated
hash	Ignored	Preview	Oct 20, 2026 12:59pm UTC
hashdotdesign-tokens	Ignored	Preview	Oct 20, 2026 12:59pm UTC
petrinaut-docs	Ignored	Preview	Oct 20, 2026 12:59pm UTC

[codecov]

Codecov Report

❌ Patch coverage is 28.26899% with 576 lines in your changes missing coverage. Please review.
✅ Project coverage is 67.96%. Comparing base (8b1cbc2) to head (cdfd1f7).
⚠️ Report is 1 commits behind head on main.

Files with missing lines	Patch %	Lines
...e/src/store/postgres/knowledge/entity/batch/mod.rs	0.00%	304 Missing ⚠️
...src/store/postgres/knowledge/entity/batch/write.rs	0.00%	218 Missing ⚠️
...ore/src/store/postgres/knowledge/entity/history.rs	93.80%	13 Missing and 2 partials ⚠️
...local/graph/postgres-store/src/store/validation.rs	0.00%	15 Missing ⚠️
...cal/graph/postgres-store/src/store/postgres/mod.rs	0.00%	12 Missing ⚠️
...store/src/store/postgres/knowledge/entity/patch.rs	0.00%	11 Missing ⚠️
...s-store/src/store/postgres/knowledge/entity/mod.rs	0.00%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main   #10063      +/-   ##
==========================================
- Coverage   68.03%   67.96%   -0.07%     
==========================================
  Files        2006     2009       +3     
  Lines      206233   206742     +509     
  Branches     8796     8791       -5     
==========================================
+ Hits       140312   140520     +208     
- Misses      64253    64550     +297     
- Partials     1668     1672       +4     

Flag	Coverage Δ
hash-graph	21.07% <ø> (ø)
hash-graph-api	39.82% <ø> (ø)
hash-graph-atlas	80.00% <ø> (-0.01%)	⬇️
hash-graph-postgres-store	31.82% <28.26%> (+0.21%)	⬆️
hashql-compiletest	28.71% <ø> (ø)
hashql-eval	81.55% <ø> (ø)

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[github-actions]

Benchmark results

hash-graph-benches – Integrations

policy_resolution_large

Function	Value	Mean	Flame graphs
resolve_policies_for_actor	user: empty, selectivity: high, policies: 2002	$$26.9 \mathrm{ms} \pm 224 \mathrm{μs}\left({\color{gray}0.754 \mathrm{\%}}\right) $$	Flame Graph
resolve_policies_for_actor	user: empty, selectivity: low, policies: 1	$$3.04 \mathrm{ms} \pm 18.3 \mathrm{μs}\left({\color{gray}-1.260 \mathrm{\%}}\right) $$	Flame Graph
resolve_policies_for_actor	user: empty, selectivity: medium, policies: 1002	$$12.7 \mathrm{ms} \pm 119 \mathrm{μs}\left({\color{gray}0.925 \mathrm{\%}}\right) $$	Flame Graph
resolve_policies_for_actor	user: seeded, selectivity: high, policies: 3314	$$39.0 \mathrm{ms} \pm 389 \mathrm{μs}\left({\color{gray}-0.990 \mathrm{\%}}\right) $$	Flame Graph
resolve_policies_for_actor	user: seeded, selectivity: low, policies: 1	$$12.7 \mathrm{ms} \pm 129 \mathrm{μs}\left({\color{gray}-0.905 \mathrm{\%}}\right) $$	Flame Graph
resolve_policies_for_actor	user: seeded, selectivity: medium, policies: 1527	$$22.6 \mathrm{ms} \pm 199 \mathrm{μs}\left({\color{gray}-1.142 \mathrm{\%}}\right) $$	Flame Graph
resolve_policies_for_actor	user: system, selectivity: high, policies: 2078	$$27.8 \mathrm{ms} \pm 218 \mathrm{μs}\left({\color{gray}0.088 \mathrm{\%}}\right) $$	Flame Graph
resolve_policies_for_actor	user: system, selectivity: low, policies: 1	$$3.35 \mathrm{ms} \pm 21.9 \mathrm{μs}\left({\color{gray}1.58 \mathrm{\%}}\right) $$	Flame Graph
resolve_policies_for_actor	user: system, selectivity: medium, policies: 1033	$$13.7 \mathrm{ms} \pm 105 \mathrm{μs}\left({\color{gray}2.72 \mathrm{\%}}\right) $$	Flame Graph

policy_resolution_medium

Function	Value	Mean	Flame graphs
resolve_policies_for_actor	user: empty, selectivity: high, policies: 102	$$3.37 \mathrm{ms} \pm 30.5 \mathrm{μs}\left({\color{gray}-0.878 \mathrm{\%}}\right) $$	Flame Graph
resolve_policies_for_actor	user: empty, selectivity: low, policies: 1	$$2.66 \mathrm{ms} \pm 19.8 \mathrm{μs}\left({\color{gray}-1.197 \mathrm{\%}}\right) $$	Flame Graph
resolve_policies_for_actor	user: empty, selectivity: medium, policies: 52	$$2.99 \mathrm{ms} \pm 32.1 \mathrm{μs}\left({\color{gray}1.56 \mathrm{\%}}\right) $$	Flame Graph
resolve_policies_for_actor	user: seeded, selectivity: high, policies: 269	$$4.70 \mathrm{ms} \pm 38.3 \mathrm{μs}\left({\color{gray}-0.351 \mathrm{\%}}\right) $$	Flame Graph
resolve_policies_for_actor	user: seeded, selectivity: low, policies: 1	$$3.13 \mathrm{ms} \pm 21.2 \mathrm{μs}\left({\color{gray}-0.083 \mathrm{\%}}\right) $$	Flame Graph
resolve_policies_for_actor	user: seeded, selectivity: medium, policies: 108	$$3.68 \mathrm{ms} \pm 32.3 \mathrm{μs}\left({\color{gray}-0.173 \mathrm{\%}}\right) $$	Flame Graph
resolve_policies_for_actor	user: system, selectivity: high, policies: 133	$$3.98 \mathrm{ms} \pm 32.0 \mathrm{μs}\left({\color{gray}1.09 \mathrm{\%}}\right) $$	Flame Graph
resolve_policies_for_actor	user: system, selectivity: low, policies: 1	$$3.06 \mathrm{ms} \pm 25.1 \mathrm{μs}\left({\color{gray}-0.101 \mathrm{\%}}\right) $$	Flame Graph
resolve_policies_for_actor	user: system, selectivity: medium, policies: 63	$$3.66 \mathrm{ms} \pm 36.8 \mathrm{μs}\left({\color{gray}1.39 \mathrm{\%}}\right) $$	Flame Graph

policy_resolution_none

Function	Value	Mean	Flame graphs
resolve_policies_for_actor	user: empty, selectivity: high, policies: 2	$$2.37 \mathrm{ms} \pm 16.7 \mathrm{μs}\left({\color{gray}0.614 \mathrm{\%}}\right) $$	Flame Graph
resolve_policies_for_actor	user: empty, selectivity: low, policies: 1	$$2.27 \mathrm{ms} \pm 18.3 \mathrm{μs}\left({\color{gray}1.86 \mathrm{\%}}\right) $$	Flame Graph
resolve_policies_for_actor	user: empty, selectivity: medium, policies: 2	$$2.34 \mathrm{ms} \pm 16.3 \mathrm{μs}\left({\color{gray}0.206 \mathrm{\%}}\right) $$	Flame Graph
resolve_policies_for_actor	user: system, selectivity: high, policies: 8	$$2.56 \mathrm{ms} \pm 22.9 \mathrm{μs}\left({\color{gray}-0.814 \mathrm{\%}}\right) $$	Flame Graph
resolve_policies_for_actor	user: system, selectivity: low, policies: 1	$$2.43 \mathrm{ms} \pm 17.9 \mathrm{μs}\left({\color{gray}1.31 \mathrm{\%}}\right) $$	Flame Graph
resolve_policies_for_actor	user: system, selectivity: medium, policies: 3	$$2.58 \mathrm{ms} \pm 19.2 \mathrm{μs}\left({\color{gray}0.608 \mathrm{\%}}\right) $$	Flame Graph

policy_resolution_small

Function	Value	Mean	Flame graphs
resolve_policies_for_actor	user: empty, selectivity: high, policies: 52	$$2.71 \mathrm{ms} \pm 23.9 \mathrm{μs}\left({\color{gray}0.866 \mathrm{\%}}\right) $$	Flame Graph
resolve_policies_for_actor	user: empty, selectivity: low, policies: 1	$$2.48 \mathrm{ms} \pm 16.5 \mathrm{μs}\left({\color{gray}-0.149 \mathrm{\%}}\right) $$	Flame Graph
resolve_policies_for_actor	user: empty, selectivity: medium, policies: 26	$$2.57 \mathrm{ms} \pm 21.9 \mathrm{μs}\left({\color{gray}0.199 \mathrm{\%}}\right) $$	Flame Graph
resolve_policies_for_actor	user: seeded, selectivity: high, policies: 94	$$3.06 \mathrm{ms} \pm 25.3 \mathrm{μs}\left({\color{gray}1.56 \mathrm{\%}}\right) $$	Flame Graph
resolve_policies_for_actor	user: seeded, selectivity: low, policies: 1	$$2.66 \mathrm{ms} \pm 19.6 \mathrm{μs}\left({\color{gray}0.966 \mathrm{\%}}\right) $$	Flame Graph
resolve_policies_for_actor	user: seeded, selectivity: medium, policies: 27	$$2.86 \mathrm{ms} \pm 24.2 \mathrm{μs}\left({\color{gray}0.301 \mathrm{\%}}\right) $$	Flame Graph
resolve_policies_for_actor	user: system, selectivity: high, policies: 66	$$3.00 \mathrm{ms} \pm 28.3 \mathrm{μs}\left({\color{gray}0.488 \mathrm{\%}}\right) $$	Flame Graph
resolve_policies_for_actor	user: system, selectivity: low, policies: 1	$$2.66 \mathrm{ms} \pm 16.8 \mathrm{μs}\left({\color{gray}1.03 \mathrm{\%}}\right) $$	Flame Graph
resolve_policies_for_actor	user: system, selectivity: medium, policies: 29	$$2.89 \mathrm{ms} \pm 23.1 \mathrm{μs}\left({\color{gray}1.17 \mathrm{\%}}\right) $$	Flame Graph

read_scaling_complete

Function	Value	Mean	Flame graphs
entity_by_id;one_depth	1 entities	$$40.2 \mathrm{ms} \pm 256 \mathrm{μs}\left({\color{gray}-0.768 \mathrm{\%}}\right) $$	Flame Graph
entity_by_id;one_depth	10 entities	$$31.8 \mathrm{ms} \pm 245 \mathrm{μs}\left({\color{gray}3.70 \mathrm{\%}}\right) $$	Flame Graph
entity_by_id;one_depth	25 entities	$$34.3 \mathrm{ms} \pm 239 \mathrm{μs}\left({\color{gray}1.73 \mathrm{\%}}\right) $$	Flame Graph
entity_by_id;one_depth	5 entities	$$31.1 \mathrm{ms} \pm 234 \mathrm{μs}\left({\color{gray}4.84 \mathrm{\%}}\right) $$	Flame Graph
entity_by_id;one_depth	50 entities	$$40.3 \mathrm{ms} \pm 266 \mathrm{μs}\left({\color{gray}1.32 \mathrm{\%}}\right) $$	Flame Graph
entity_by_id;two_depth	1 entities	$$48.6 \mathrm{ms} \pm 437 \mathrm{μs}\left({\color{gray}0.851 \mathrm{\%}}\right) $$	Flame Graph
entity_by_id;two_depth	10 entities	$$38.1 \mathrm{ms} \pm 261 \mathrm{μs}\left({\color{gray}-0.349 \mathrm{\%}}\right) $$	Flame Graph
entity_by_id;two_depth	25 entities	$$85.1 \mathrm{ms} \pm 583 \mathrm{μs}\left({\color{gray}1.59 \mathrm{\%}}\right) $$	Flame Graph
entity_by_id;two_depth	5 entities	$$32.0 \mathrm{ms} \pm 193 \mathrm{μs}\left({\color{gray}0.729 \mathrm{\%}}\right) $$	Flame Graph
entity_by_id;two_depth	50 entities	$$250 \mathrm{ms} \pm 1.06 \mathrm{ms}\left({\color{red}7.35 \mathrm{\%}}\right) $$	Flame Graph
entity_by_id;zero_depth	1 entities	$$9.78 \mathrm{ms} \pm 57.3 \mathrm{μs}\left({\color{gray}0.308 \mathrm{\%}}\right) $$	Flame Graph
entity_by_id;zero_depth	10 entities	$$10.1 \mathrm{ms} \pm 71.0 \mathrm{μs}\left({\color{gray}3.42 \mathrm{\%}}\right) $$	Flame Graph
entity_by_id;zero_depth	25 entities	$$9.69 \mathrm{ms} \pm 57.9 \mathrm{μs}\left({\color{gray}-1.797 \mathrm{\%}}\right) $$	Flame Graph
entity_by_id;zero_depth	5 entities	$$9.85 \mathrm{ms} \pm 62.5 \mathrm{μs}\left({\color{gray}1.01 \mathrm{\%}}\right) $$	Flame Graph
entity_by_id;zero_depth	50 entities	$$9.93 \mathrm{ms} \pm 62.1 \mathrm{μs}\left({\color{gray}0.532 \mathrm{\%}}\right) $$	Flame Graph

read_scaling_linkless

Function	Value	Mean	Flame graphs
entity_by_id	1 entities	$$9.88 \mathrm{ms} \pm 59.0 \mathrm{μs}\left({\color{gray}2.54 \mathrm{\%}}\right) $$	Flame Graph
entity_by_id	10 entities	$$9.90 \mathrm{ms} \pm 63.9 \mathrm{μs}\left({\color{gray}2.83 \mathrm{\%}}\right) $$	Flame Graph
entity_by_id	100 entities	$$9.84 \mathrm{ms} \pm 75.6 \mathrm{μs}\left({\color{gray}1.33 \mathrm{\%}}\right) $$	Flame Graph
entity_by_id	1000 entities	$$10.2 \mathrm{ms} \pm 68.3 \mathrm{μs}\left({\color{gray}2.07 \mathrm{\%}}\right) $$	Flame Graph
entity_by_id	10000 entities	$$10.3 \mathrm{ms} \pm 80.7 \mathrm{μs}\left({\color{gray}0.317 \mathrm{\%}}\right) $$	Flame Graph

representative_read_entity

Function	Value	Mean	Flame graphs
entity_by_id	entity type ID: https://blockprotocol.org/@alice/types/entity-type/block/v/1	$$10.2 \mathrm{ms} \pm 65.1 \mathrm{μs}\left({\color{gray}1.40 \mathrm{\%}}\right) $$	Flame Graph
entity_by_id	entity type ID: https://blockprotocol.org/@alice/types/entity-type/book/v/1	$$10.3 \mathrm{ms} \pm 73.9 \mathrm{μs}\left({\color{gray}2.07 \mathrm{\%}}\right) $$	Flame Graph
entity_by_id	entity type ID: https://blockprotocol.org/@alice/types/entity-type/building/v/1	$$10.1 \mathrm{ms} \pm 65.9 \mathrm{μs}\left({\color{gray}0.607 \mathrm{\%}}\right) $$	Flame Graph
entity_by_id	entity type ID: https://blockprotocol.org/@alice/types/entity-type/organization/v/1	$$10.2 \mathrm{ms} \pm 76.9 \mathrm{μs}\left({\color{gray}2.45 \mathrm{\%}}\right) $$	Flame Graph
entity_by_id	entity type ID: https://blockprotocol.org/@alice/types/entity-type/page/v/2	$$10.5 \mathrm{ms} \pm 58.8 \mathrm{μs}\left({\color{red}5.19 \mathrm{\%}}\right) $$	Flame Graph
entity_by_id	entity type ID: https://blockprotocol.org/@alice/types/entity-type/person/v/1	$$10.4 \mathrm{ms} \pm 74.2 \mathrm{μs}\left({\color{gray}3.02 \mathrm{\%}}\right) $$	Flame Graph
entity_by_id	entity type ID: https://blockprotocol.org/@alice/types/entity-type/playlist/v/1	$$10.5 \mathrm{ms} \pm 78.4 \mathrm{μs}\left({\color{gray}4.32 \mathrm{\%}}\right) $$	Flame Graph
entity_by_id	entity type ID: https://blockprotocol.org/@alice/types/entity-type/song/v/1	$$10.2 \mathrm{ms} \pm 64.5 \mathrm{μs}\left({\color{gray}1.07 \mathrm{\%}}\right) $$	Flame Graph
entity_by_id	entity type ID: https://blockprotocol.org/@alice/types/entity-type/uk-address/v/1	$$10.4 \mathrm{ms} \pm 71.4 \mathrm{μs}\left({\color{gray}3.55 \mathrm{\%}}\right) $$	Flame Graph

representative_read_entity_type

Function	Value	Mean	Flame graphs
get_entity_type_by_id	Account ID: bf5a9ef5-dc3b-43cf-a291-6210c0321eba	$$7.41 \mathrm{ms} \pm 50.1 \mathrm{μs}\left({\color{gray}0.966 \mathrm{\%}}\right) $$	Flame Graph

representative_read_multiple_entities

Function	Value	Mean	Flame graphs
entity_by_property	traversal_paths=0	0	$$57.5 \mathrm{ms} \pm 387 \mathrm{μs}\left({\color{gray}1.15 \mathrm{\%}}\right) $$
entity_by_property	traversal_paths=255	1,resolve_depths=inherit:1;values:255;properties:255;links:127;link_dests:126;type:true	$$106 \mathrm{ms} \pm 829 \mathrm{μs}\left({\color{gray}0.827 \mathrm{\%}}\right) $$
entity_by_property	traversal_paths=2	1,resolve_depths=inherit:0;values:0;properties:0;links:0;link_dests:0;type:false	$$64.1 \mathrm{ms} \pm 531 \mathrm{μs}\left({\color{gray}1.57 \mathrm{\%}}\right) $$
entity_by_property	traversal_paths=2	1,resolve_depths=inherit:0;values:0;properties:0;links:1;link_dests:0;type:true	$$72.7 \mathrm{ms} \pm 485 \mathrm{μs}\left({\color{gray}-0.975 \mathrm{\%}}\right) $$
entity_by_property	traversal_paths=2	1,resolve_depths=inherit:0;values:0;properties:2;links:1;link_dests:0;type:true	$$81.5 \mathrm{ms} \pm 584 \mathrm{μs}\left({\color{gray}0.968 \mathrm{\%}}\right) $$
entity_by_property	traversal_paths=2	1,resolve_depths=inherit:0;values:2;properties:2;links:1;link_dests:0;type:true	$$86.2 \mathrm{ms} \pm 615 \mathrm{μs}\left({\color{gray}-1.243 \mathrm{\%}}\right) $$
link_by_source_by_property	traversal_paths=0	0	$$42.2 \mathrm{ms} \pm 399 \mathrm{μs}\left({\color{gray}0.327 \mathrm{\%}}\right) $$
link_by_source_by_property	traversal_paths=255	1,resolve_depths=inherit:1;values:255;properties:255;links:127;link_dests:126;type:true	$$69.4 \mathrm{ms} \pm 583 \mathrm{μs}\left({\color{gray}1.51 \mathrm{\%}}\right) $$
link_by_source_by_property	traversal_paths=2	1,resolve_depths=inherit:0;values:0;properties:0;links:0;link_dests:0;type:false	$$48.5 \mathrm{ms} \pm 326 \mathrm{μs}\left({\color{gray}2.05 \mathrm{\%}}\right) $$
link_by_source_by_property	traversal_paths=2	1,resolve_depths=inherit:0;values:0;properties:0;links:1;link_dests:0;type:true	$$57.7 \mathrm{ms} \pm 532 \mathrm{μs}\left({\color{gray}2.35 \mathrm{\%}}\right) $$
link_by_source_by_property	traversal_paths=2	1,resolve_depths=inherit:0;values:0;properties:2;links:1;link_dests:0;type:true	$$60.1 \mathrm{ms} \pm 461 \mathrm{μs}\left({\color{gray}3.59 \mathrm{\%}}\right) $$
link_by_source_by_property	traversal_paths=2	1,resolve_depths=inherit:0;values:2;properties:2;links:1;link_dests:0;type:true	$$59.5 \mathrm{ms} \pm 409 \mathrm{μs}\left({\color{gray}2.19 \mathrm{\%}}\right) $$

scenarios

Function	Value	Mean	Flame graphs
full_test	query-limited	$$112 \mathrm{ms} \pm 1.05 \mathrm{ms}\left({\color{red}5.70 \mathrm{\%}}\right) $$	Flame Graph
full_test	query-unlimited	$$120 \mathrm{ms} \pm 677 \mathrm{μs}\left({\color{gray}3.87 \mathrm{\%}}\right) $$	Flame Graph
linked_queries	query-limited	$$21.3 \mathrm{ms} \pm 194 \mathrm{μs}\left({\color{gray}0.285 \mathrm{\%}}\right) $$	Flame Graph
linked_queries	query-unlimited	$$493 \mathrm{ms} \pm 1.18 \mathrm{ms}\left({\color{gray}3.78 \mathrm{\%}}\right) $$	Flame Graph