H-3371, H-3722: Overhaul return behavior for entity validation

[TimDiekmann]

🌟 What is the purpose of this PR?

To allow proper handling of validation errors, this PR completely overhauls how validation errors are returned from the graph. Most notably is that the validation function itself won't error anymore but returned a well-defined structure.

🔍 What does this change?

Add a validation structure which looks similar to this:

export interface EntityValidationReport {
  properties?: PropertyValidationReport;
  link?: LinkValidationReport;
  metadata?: MetadataValidationReport;
}

export interface LinkValidationReport {
  leftEntity?: LinkedEntityError | null;
  rightEntity?: LinkedEntityError | null;
  linkData?: LinkDataStateError | null;
  linkType?: LinkError | null;
  targetType?: LinkTargetError | null;
}

export interface MetadataValidationReport {
  entityTypes?: EntityTypesError | null;
  properties?: any | null;
}

export type LinkedEntityError =
  | { type: "entityRetrieval"; error: Report }
  | { type: "entityTypeRetrieval"; error: Report }
  | { type: "resolveClosedEntityType"; error: Report };

export type LinkError = {
  type: "unexpectedEntityType";
  data: {
    actual: Array<string>;
    expected: Array<string>;
  };
};

export type LinkTargetError = {
  type: "unexpectedEntityType";
  data: {
    actual: Array<string>;
    expected: Array<string>;
  };
};

export type LinkDataStateError =
  | { type: "missing"; error: Report }
  | { type: "unexpected"; error: Report };

export type EntityTypesError =
  | { type: "empty"; error: Report }
  | { type: "entityTypeRetrieval"; error: Report }
  | { type: "resolveClosedEntityType"; error: Report };

export interface PropertyValidationReport {
  error?: Report | null;
}

The properties field in the top level is not adjusted yet. For now it just contains a Report (basically all the errors which could happen in property validation). This will be adjusted in a follow-up PR as the structure of the preprocessor needs to change quite a bit for that.
metadata.properties should include metadata validation for properties which currently does nothing. The OpenAPI generator uses any for this (please don’t ask me why), it should always be empty but was kept to follow the code paths in Rust.

The Graph API endpoint itself are changed so they return { [key: string]: EntityValidationReport } while key is the position of the entity in the parameter (0-based index, but JSON does not support numbers as keys). Any parameter with a failed validation will be reported.
This means:

• createEntities and updateEntity will return the result as previously, but if a validation error happens, the above structure is passed alongside the reports in the response
• validateEntities will always return the map. An empty map means no validation errors.

Pre-Merge Checklist 🚀

🚢 Has this modified a publishable library?

This PR:

• does not modify any publishable blocks or libraries, or modifications do not need publishing

📜 Does this require a change to the docs?

The changes in this PR:

• are internal and do not require a docs change

🕸️ Does this require a change to the Turbo Graph?

The changes in this PR:

• do not affect the execution graph

🐾 Next steps

Overhaul the property validation reporting as well

[codecov]

Codecov Report

Attention: Patch coverage is 0% with 1 line in your changes missing coverage. Please review.

Project coverage is 23.00%. Comparing base (f8c88ed) to head (8f71f79).
Report is 5 commits behind head on main.

Files with missing lines	Patch %	Lines
...i/src/graphql/resolvers/knowledge/entity/entity.ts	0.00%	1 Missing ⚠️

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #5820   +/-   ##
=======================================
  Coverage   23.00%   23.00%           
=======================================
  Files         568      568           
  Lines       19165    19160    -5     
  Branches     2715     2716    +1     
=======================================
  Hits         4408     4408           
+ Misses      14705    14700    -5     
  Partials       52       52           

Flag	Coverage Δ
apps.hash-ai-worker-ts	1.32% <ø> (ø)
apps.hash-api	1.16% <0.00%> (+<0.01%)	⬆️
blockprotocol.type-system	46.42% <ø> (ø)
local.hash-backend-utils	8.80% <ø> (ø)
local.hash-graph-sdk	100.00% <ø> (ø)
local.hash-isomorphic-utils	0.99% <ø> (ø)
local.hash-subgraph	24.54% <ø> (ø)

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

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

[github-actions]

Benchmark results

@rust/hash-graph-benches – Integrations

representative_read_entity

Function	Value	Mean	Flame graphs
entity_by_id	entity type ID: https://blockprotocol.org/@alice/types/entity-type/block/v/1	$$16.2 \mathrm{ms} \pm 160 \mathrm{μs}\left({\color{lightgreen}-28.799 \mathrm{\%}}\right) $$	Flame Graph
entity_by_id	entity type ID: https://blockprotocol.org/@alice/types/entity-type/book/v/1	$$17.0 \mathrm{ms} \pm 187 \mathrm{μs}\left({\color{gray}4.86 \mathrm{\%}}\right) $$	Flame Graph
entity_by_id	entity type ID: https://blockprotocol.org/@alice/types/entity-type/uk-address/v/1	$$16.5 \mathrm{ms} \pm 162 \mathrm{μs}\left({\color{gray}0.333 \mathrm{\%}}\right) $$	Flame Graph
entity_by_id	entity type ID: https://blockprotocol.org/@alice/types/entity-type/playlist/v/1	$$15.7 \mathrm{ms} \pm 140 \mathrm{μs}\left({\color{lightgreen}-6.616 \mathrm{\%}}\right) $$	Flame Graph
entity_by_id	entity type ID: https://blockprotocol.org/@alice/types/entity-type/person/v/1	$$16.1 \mathrm{ms} \pm 185 \mathrm{μs}\left({\color{lightgreen}-5.219 \mathrm{\%}}\right) $$	Flame Graph
entity_by_id	entity type ID: https://blockprotocol.org/@alice/types/entity-type/building/v/1	$$16.1 \mathrm{ms} \pm 226 \mathrm{μs}\left({\color{gray}-1.430 \mathrm{\%}}\right) $$	Flame Graph
entity_by_id	entity type ID: https://blockprotocol.org/@alice/types/entity-type/organization/v/1	$$16.3 \mathrm{ms} \pm 183 \mathrm{μs}\left({\color{gray}4.09 \mathrm{\%}}\right) $$	Flame Graph
entity_by_id	entity type ID: https://blockprotocol.org/@alice/types/entity-type/page/v/2	$$16.7 \mathrm{ms} \pm 164 \mathrm{μs}\left({\color{lightgreen}-16.718 \mathrm{\%}}\right) $$	Flame Graph
entity_by_id	entity type ID: https://blockprotocol.org/@alice/types/entity-type/song/v/1	$$16.8 \mathrm{ms} \pm 219 \mathrm{μs}\left({\color{gray}1.50 \mathrm{\%}}\right) $$	Flame Graph

representative_read_multiple_entities

Function	Value	Mean	Flame graphs
entity_by_property	depths: DT=255, PT=255, ET=255, E=255	$$88.8 \mathrm{ms} \pm 13.6 \mathrm{ms}\left({\color{red}37.3 \mathrm{\%}}\right) $$	Flame Graph
entity_by_property	depths: DT=0, PT=0, ET=0, E=0	$$36.9 \mathrm{ms} \pm 187 \mathrm{μs}\left({\color{gray}-2.098 \mathrm{\%}}\right) $$	Flame Graph
entity_by_property	depths: DT=2, PT=2, ET=2, E=2	$$55.1 \mathrm{ms} \pm 261 \mathrm{μs}\left({\color{gray}-1.026 \mathrm{\%}}\right) $$	Flame Graph
entity_by_property	depths: DT=0, PT=0, ET=0, E=2	$$41.2 \mathrm{ms} \pm 237 \mathrm{μs}\left({\color{gray}-4.164 \mathrm{\%}}\right) $$	Flame Graph
entity_by_property	depths: DT=0, PT=0, ET=2, E=2	$$46.8 \mathrm{ms} \pm 251 \mathrm{μs}\left({\color{gray}-1.738 \mathrm{\%}}\right) $$	Flame Graph
entity_by_property	depths: DT=0, PT=2, ET=2, E=2	$$51.6 \mathrm{ms} \pm 301 \mathrm{μs}\left({\color{gray}-1.339 \mathrm{\%}}\right) $$	Flame Graph
link_by_source_by_property	depths: DT=255, PT=255, ET=255, E=255	$$107 \mathrm{ms} \pm 613 \mathrm{μs}\left({\color{gray}1.80 \mathrm{\%}}\right) $$	Flame Graph
link_by_source_by_property	depths: DT=0, PT=0, ET=0, E=0	$$59.5 \mathrm{ms} \pm 9.25 \mathrm{ms}\left({\color{red}40.8 \mathrm{\%}}\right) $$	Flame Graph
link_by_source_by_property	depths: DT=2, PT=2, ET=2, E=2	$$97.3 \mathrm{ms} \pm 298 \mathrm{μs}\left({\color{gray}-0.162 \mathrm{\%}}\right) $$	Flame Graph
link_by_source_by_property	depths: DT=0, PT=0, ET=0, E=2	$$79.8 \mathrm{ms} \pm 402 \mathrm{μs}\left({\color{gray}-1.029 \mathrm{\%}}\right) $$	Flame Graph
link_by_source_by_property	depths: DT=0, PT=0, ET=2, E=2	$$88.5 \mathrm{ms} \pm 358 \mathrm{μs}\left({\color{gray}-2.104 \mathrm{\%}}\right) $$	Flame Graph
link_by_source_by_property	depths: DT=0, PT=2, ET=2, E=2	$$93.0 \mathrm{ms} \pm 302 \mathrm{μs}\left({\color{gray}-0.204 \mathrm{\%}}\right) $$	Flame Graph

representative_read_entity_type

Function	Value	Mean	Flame graphs
get_entity_type_by_id	Account ID: d4e16033-c281-4cde-aa35-9085bf2e7579	$$1.38 \mathrm{ms} \pm 4.84 \mathrm{μs}\left({\color{gray}-0.212 \mathrm{\%}}\right) $$	Flame Graph

scaling_read_entity_complete_one_depth

Function	Value	Mean	Flame graphs
entity_by_id	50 entities	$$5.24 \mathrm{s} \pm 834 \mathrm{ms}\left({\color{red}1889 \mathrm{\%}}\right) $$	Flame Graph
entity_by_id	5 entities	$$26.5 \mathrm{ms} \pm 225 \mathrm{μs}\left({\color{gray}0.917 \mathrm{\%}}\right) $$	Flame Graph
entity_by_id	1 entities	$$20.2 \mathrm{ms} \pm 159 \mathrm{μs}\left({\color{gray}1.42 \mathrm{\%}}\right) $$	Flame Graph
entity_by_id	10 entities	$$56.3 \mathrm{ms} \pm 230 \mathrm{μs}\left({\color{gray}-0.296 \mathrm{\%}}\right) $$	Flame Graph
entity_by_id	25 entities	$$181 \mathrm{ms} \pm 786 \mathrm{μs}\left({\color{gray}4.25 \mathrm{\%}}\right) $$	Flame Graph

scaling_read_entity_linkless

Function	Value	Mean	Flame graphs
entity_by_id	1 entities	$$1.94 \mathrm{ms} \pm 7.21 \mathrm{μs}\left({\color{gray}1.33 \mathrm{\%}}\right) $$	Flame Graph
entity_by_id	100 entities	$$2.10 \mathrm{ms} \pm 5.72 \mathrm{μs}\left({\color{gray}2.26 \mathrm{\%}}\right) $$	Flame Graph
entity_by_id	10 entities	$$1.93 \mathrm{ms} \pm 3.91 \mathrm{μs}\left({\color{gray}-0.374 \mathrm{\%}}\right) $$	Flame Graph
entity_by_id	1000 entities	$$2.87 \mathrm{ms} \pm 14.9 \mathrm{μs}\left({\color{gray}1.31 \mathrm{\%}}\right) $$	Flame Graph
entity_by_id	10000 entities	$$13.4 \mathrm{ms} \pm 33.7 \mathrm{μs}\left({\color{red}47.4 \mathrm{\%}}\right) $$	Flame Graph

scaling_read_entity_complete_zero_depth

Function	Value	Mean	Flame graphs
entity_by_id	50 entities	$$3.95 \mathrm{ms} \pm 23.6 \mathrm{μs}\left({\color{lightgreen}-21.447 \mathrm{\%}}\right) $$	Flame Graph
entity_by_id	5 entities	$$1.97 \mathrm{ms} \pm 9.19 \mathrm{μs}\left({\color{gray}1.44 \mathrm{\%}}\right) $$	Flame Graph
entity_by_id	1 entities	$$1.94 \mathrm{ms} \pm 7.72 \mathrm{μs}\left({\color{gray}1.35 \mathrm{\%}}\right) $$	Flame Graph
entity_by_id	10 entities	$$2.08 \mathrm{ms} \pm 7.92 \mathrm{μs}\left({\color{gray}-2.578 \mathrm{\%}}\right) $$	Flame Graph
entity_by_id	25 entities	$$3.30 \mathrm{ms} \pm 16.9 \mathrm{μs}\left({\color{red}20.7 \mathrm{\%}}\right) $$	Flame Graph