FE-1984: Add a Read entity flow action

[kostandinang]

🌟 Purpose

Adds Read Entity: reads one property of an entity as a plain value, e.g. an email address for a later Send email step.

• Inputs: entityId (an ID, or an item of a stored list) and property, a constant naming the property type base URL and the kind to read it as: Text, Number, Boolean or Date.
• Output: value, of that kind. Missing when the entity has no value, so later steps connected with whenMissing: "skip" are skipped.
• Reads the draft if the ID has a draft ID, otherwise the live entity, as the user running the flow.

🔍 Changes

Where	What
flows/types.ts	KindDeclaredBy and the EntityProperty kind. Start here.
flows/read-entity.ts	EntityProperty (Filter's property subject, limited to four kinds) and its checks.
flows/step-shapes.ts, flows/validate-flow-definition.ts	Resolve a declared kind, so later connections are checked against it.
flows/define-flow.ts	Types value by the declared kind in the typed builder.
process-flow-workflow.ts	Checks the action returns the declared kind.
flow-activities/read-entity-action.ts	The activity, reusing Filter's entity loading and property reading.

🤔 Decisions to review

• A third way for an output to get its kind. Alongside a fixed payloadKind and kindFrom, an output can take the kind a constant input declares (KindDeclaredBy). The validator checks the input is a constant and declares one of the output's kinds. Reusing kindFrom would need a required fallback value, so a missing value could never skip later steps.
• The kind is declared, not looked up. The validator has no ontology access, so the step checks the value's kind when it runs.
• A list is an error, even with one item, so a flow doesn't break when a second value is added.
• An empty string counts as missing, as in Filter.

⚠️ Known issues

• A for-each step can't collect the values into a list, since it only collects outputs that are always present.

🛡 Tests

• Activity, with a mocked graph: each kind (including 0 and false), missing and empty values, missing or unreadable entities, lists and values of the wrong kind.
• Validator and builder: skipping when the value is missing, wrong connections, invalid properties, a non-constant property and an undeclared kind.
• 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 19, 2026 2:55pm UTC
hashdotdesign-tokens	Ready	Preview	Oct 19, 2026 2:55pm UTC
petrinaut	Ready	Preview	Oct 19, 2026 2:55pm UTC
petrinaut-docs	Ready	Preview	Oct 19, 2026 2:55pm UTC

[cursor]

PR Summary

Medium Risk
New flow engine typing/validation paths and graph reads run as the flow user; behavior is well tested but affects how flows wire entity data into later steps.

Overview
Adds a Read entity flow action that loads an entity (draft when the ID includes a draft) and exposes a single property as a scalar Text, Number, Boolean, or Date, using the same empty/missing semantics as Filter so downstream steps can use whenMissing: "skip".

Introduces KindDeclaredBy and the EntityProperty payload kind so an output’s type is fixed by a constant property input (property base URL + declared kind), with validation in step-shapes / validate-flow-definition, typed refs in define-flow, and a runtime kind check in process-flow-workflow. The AI worker registers readEntityAction, which reuses Filter’s entity resolution and exports isEmptyValue for shared “missing” behavior.

Manual flow run UI lists EntityProperty as unsupported for now; activity, validator, and builder tests cover the new action.

^{Reviewed by Cursor Bugbot for commit 6d4b063. Bugbot is set up for automated code reviews on this repo. Configure here.}

[codecov]

Codecov Report

❌ Patch coverage is 79.26829% with 17 lines in your changes missing coverage. Please review.
✅ Project coverage is 68.25%. Comparing base (cfd61d5) to head (6d4b063).
⚠️ Report is 1 commits behind head on main.

Files with missing lines	Patch %	Lines
...h-backend-utils/src/flows/process-flow-workflow.ts	0.00%	7 Missing ⚠️
...cal/hash-isomorphic-utils/src/flows/read-entity.ts	70.00%	6 Missing ⚠️
...cal/hash-isomorphic-utils/src/flows/step-shapes.ts	50.00%	0 Missing and 2 partials ⚠️
...c/activities/flow-activities/read-entity-action.ts	96.55%	0 Missing and 1 partial ⚠️
...bs/@local/hash-isomorphic-utils/src/flows/types.ts	66.66%	0 Missing and 1 partial ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main   #10051      +/-   ##
==========================================
+ Coverage   68.14%   68.25%   +0.10%     
==========================================
  Files        1995     1996       +1     
  Lines      205552   205290     -262     
  Branches     8707     8731      +24     
==========================================
+ Hits       140065   140111      +46     
+ Misses      63823    63510     -313     
- Partials     1664     1669       +5     

Flag	Coverage Δ
apps.hash-ai-worker-ts	7.74% <96.66%> (+0.46%)	⬆️
apps.hash-api	15.58% <ø> (ø)
local.hash-backend-utils	6.22% <0.00%> (-0.01%)	⬇️
local.hash-isomorphic-utils	32.68% <80.00%> (+0.74%)	⬆️

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.