[kostandinang]

🌟 Purpose

Flows can find entities (#10050) but can only write through persistEntity, which takes a full AI-proposed entity. This adds Create Entity and Update Entity, which write through the graph's own API, so the graph does the validation.

• Create Entity: entityTypeIds (one or more), properties (which may be empty) and an optional draft (default false). properties is the graph's PropertyObjectWithMetadata: values keyed by property type base URL, each with inline metadata (a required dataTypeId, and optionally provenance and confidence). Calls HashEntity.create. Outputs the new entityId, with a draft ID if it's a draft.
• Update Entity: entityId (an ID or an item of a stored list) and propertyPatches, the graph's add/remove/replace patches. Calls entity.patch(). Outputs the same entityId.
• Writes in the run's web as the web's machine, on behalf of the user running the flow, as persistEntity does. Update only changes entities the user can edit, and edits the draft if the ID has one.

🔍 Changes

Where	What it does
flows/property-values.ts	The only checks on our side, run when the flow is defined (for constants) and when the step runs: every value gives a dataTypeId, and each patch targets a whole top-level property. Start here.
flows/action-definitions.ts, flows/types.ts	Define both actions and register the PropertyObjectWithMetadata and PropertyPatch kinds.
update-entity-action.ts, create-entity-action.ts	The activities: check the inputs, then pass them to the graph unchanged.
shared/save-entity.ts, persist-entity-action.ts	The saving actor lookup and retries, moved out of persistEntity so all three share them. No change to persistEntity's behaviour.
generate-uuid.ts	generateUuidFromName, for Create's UUID.

Decisions to review:

• The graph's shapes, not new ones. Metadata is inline, as the graph's create endpoint takes it, rather than in a separate propertyMetadata input. persistEntity's ProposedEntity input isn't reused because it carries AI provenance, claims and link resolution that a value set on a step doesn't have.
• The graph validates. It checks the entity Create makes, or the entity a patch leaves, including required properties (not for drafts). There's no separate check against the type first.
• dataTypeId: null is rejected. The graph would accept it and infer a data type, which fails for a property allowing several data types, or only an abstract one.
• Patches change whole top-level properties, so a retried step changes nothing more. add sets a property, replacing any value. replace fails if the property is missing. remove does nothing if it's already gone. The graph also takes paths inside a value (e.g. a list index), but adding or removing by index isn't safe if Temporal retries the step.
• Create's entity UUID comes from the run and step IDs, so it's the same on every attempt, including Temporal's retries. Each attempt first looks for that entity and outputs it if an earlier attempt created it, so a retry can't create a second entity.
• Create doesn't check the user may create an entity of the given types, as persistEntity doesn't. A run only starts if the user has a role in its web, so Create can't write outside the user's webs. Should it check the types too?

⚠️ Known issues

• Nothing outputs PropertyObjectWithMetadata or PropertyPatch yet, and the run modal doesn't support them, so properties come from constants in the flow definition or flow inputs given programmatically.
• A save the graph rejects comes back as an internal error with the graph's message, less specific than naming each property. retrySave also retries it, as for persistEntity.
• Links are out of scope, and Update Entity can't change an entity's types yet. Both are follow-ups, as is replacing persistEntity with Create Entity.

🛡 Tests

• Create, with a mocked graph: the types and properties passed as given, including several types and no properties; a draft; no entity type IDs, an invalid one, or a value without a data type ID, without creating; a failed save; the same UUID on every attempt; reusing an entity an earlier attempt created.
• Update, with a mocked graph: the patches passed as given; a draft staying a draft; a stored list item; an invalid or other-web entity ID, no patches, a patch inside a property, or a value without a data type ID, without reading the entity; a missing or unreadable entity; one the user can read but not edit; a failed save.
• Validator: each shape rule for constant properties and patches, and flow inputs (checked when the step runs).
• Not yet run end to end through Temporal.

[vercel]

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

Project	Deployment	Actions	Updated
hash	Ready	Preview	Oct 21, 2026 2:55pm UTC
petrinaut	Ready	Preview	Oct 21, 2026 2:55pm UTC

2 Skipped Deployments

Project	Deployment	Actions	Updated
hashdotdesign-tokens	Ignored	Preview	Oct 21, 2026 2:55pm UTC
petrinaut-docs	Skipped		Oct 21, 2026 2:55pm UTC

[codecov]

Codecov Report

❌ Patch coverage is 80.76923% with 25 lines in your changes missing coverage. Please review.
✅ Project coverage is 68.05%. Comparing base (8b1cbc2) to head (f6cb0ab).
⚠️ Report is 10 commits behind head on main.

Files with missing lines	Patch %	Lines
...c/activities/flow-activities/shared/save-entity.ts	0.00%	11 Missing ⚠️
...ctivities/flow-activities/persist-entity-action.ts	0.00%	6 Missing ⚠️
...hash-isomorphic-utils/src/flows/property-values.ts	90.32%	2 Missing and 4 partials ⚠️
.../@local/hash-isomorphic-utils/src/generate-uuid.ts	0.00%	2 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main   #10060      +/-   ##
==========================================
+ Coverage   68.03%   68.05%   +0.02%     
==========================================
  Files        2006     2010       +4     
  Lines      206233   206406     +173     
  Branches     8796     8851      +55     
==========================================
+ Hits       140312   140471     +159     
- Misses      64253    64255       +2     
- Partials     1668     1680      +12     

Flag	Coverage Δ
apps.hash-ai-worker-ts	8.31% <74.24%> (+1.45%)	⬆️
apps.hash-api	15.59% <ø> (ø)
local.hash-backend-utils	6.21% <ø> (ø)
local.hash-isomorphic-utils	33.43% <87.50%> (+1.42%)	⬆️

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.

[semgrep-code-hashintel]

Semgrep found 2 node_md5 findings:

• apps/hash-api/src/mailchimp.ts
  • L41 - Triage
• apps/hash-ai-worker-ts/src/activities/flow-activities/research-entities-action/link-follower-agent/llama-index/index-pdf-file.ts
  • L32 - Triage

🟡 Medium severity issue identified in your code:

MD5 is a a weak hash which is known to have collision. Use a strong hashing function.

Semgrep found 2 crypto-weak-algorithm findings:

• apps/hash-api/src/mailchimp.ts
  • L41 - Triage
• apps/hash-ai-worker-ts/src/activities/flow-activities/research-entities-action/link-follower-agent/llama-index/index-pdf-file.ts
  • L32 - Triage

🟡 Medium severity issue identified in your code:

The use of a weak cryptographic algorithm (e.g., SHA-1 or MD5) has been identified. These algorithms are considered insecure due to vulnerabilities that make them susceptible to collision attacks, allowing attackers to compromise data integrity or security. Replace SHA-1 or MD5 with secure hashing algorithms, such as: SHA-256 or higher (e.g., SHA-3).

View Dataflow Graph

flowchart LR
    classDef invis fill:white, stroke: none
    classDef default fill:#e7f5ff, color:#1c7fd6, stroke: none

    subgraph File0["<b>apps/hash-api/src/mailchimp.ts</b>"]
        direction LR
        %% Source

        subgraph Source
            direction LR

            v0["<a href=https://github.com/hashintel/hash/blob/3cefbe9fafa7c969515d7d2c2dc342aeceaff0f8/apps/hash-api/src/mailchimp.ts#L41 target=_blank style='text-decoration:none; color:#1c7fd6'>[Line: 41] &quot;md5&quot;</a>"]
        end
        %% Intermediate

        %% Sink

        subgraph Sink
            direction LR

            v1["<a href=https://github.com/hashintel/hash/blob/3cefbe9fafa7c969515d7d2c2dc342aeceaff0f8/apps/hash-api/src/mailchimp.ts#L41 target=_blank style='text-decoration:none; color:#1c7fd6'>[Line: 41] &quot;md5&quot;</a>"]
        end
    end
    %% Class Assignment
    Source:::invis
    Sink:::invis

    File0:::invis

    %% Connections

    Source --> Sink

Loading

[CiaranMn]

Some non-blocking comments

[CiaranMn]

One thing this does not support is the creation of links, which additionally must pass linkData.

[kostandinang]

Yes, out of scope here. I'll do it as a follow-up.

[CiaranMn]

Just a note that if there is as UUID collision (generally unlikely unless we have duplicate stepIds or runIds for some reason) this would return some other entity.

I appreciate the PR description says we do this in case there's a Temporal retry. I'm not sure that would happen given that the activity is over once the create call succeeds, but probably fine to leave for now.

[kostandinang]

Only retries of the same step run share a UUID, since for-each branches get their own step IDs. Temporal can still retry after the create succeeds if the worker dies before reporting back, so I'll leave it.

[kostandinang]

Addressed your comments, could you re-approve? The push dismissed your approval.