H-3572, H-4105: Track Node migrations run, skip already-run migrations

[CiaranMn]

🌟 What is the purpose of this PR?

Start storing the Node API migrations run as part of the HASH instance entity (they create system types and update entities to updated types), and skip those already run.

Migrations are idempotent – this is designed to speed up start-up time by not bothering to go through the process of checking entities that need upgrading (of which there should be none once a migration has run once).

Drive-bys:

1. Update database reset instructions in the README
2. Ensure Block Protocol 'query' and 'has-query' types are seeded as part of migrations.

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

🛡 What tests cover this?

• Migrations are run as part of integration tests.

[cursor]

PR Summary

Track completed ontology migrations on the HASH Instance and skip re-running them; seed BP query types; minor utils/frontend/docs updates.

• Backend/API (migrations):
  • Store completed migration IDs on the HASH Instance via migrationsCompleted property and skip files already processed.
  • New migration 025-add-migrations-completed-to-hash-instance.migration.ts adds the property and upgrades instances.
  • Writes provenance when patching migrationsCompleted.
• System types/IDs:
  • Bump hash-instance to v/2; add systemPropertyTypes.migrationsCompleted.
  • Seed BP types: entity-type/query, entity-type/has-query, and property-type/query (Hash namespace URLs).
• Instance creation/utilities:
  • createHashInstance now requires hashInstanceEntityTypeId; instantiation policy and entity use it.
  • getHashInstance/getHashInstanceFromEntity match by baseUrl (not exact version) and query by type.baseUrl.
• Frontend:
  • GraphQL request helper now catches fetch/JSON errors and returns structured INTERNAL_SERVER_ERROR.
• Docs:
  • Simplify local DB reset steps in README.md.

^{Written by Cursor Bugbot for commit 21b2437. This will update automatically on new commits. Configure here.}

[codecov]

Codecov Report

❌ Patch coverage is 0% with 78 lines in your changes missing coverage. Please review.
✅ Project coverage is 58.09%. Comparing base (56c236f) to head (d6a3636).
⚠️ Report is 4 commits behind head on main.

Files with missing lines	Patch %	Lines
...tem-graph-is-initialized/migrate-ontology-types.ts	0.00%	49 Missing ⚠️
...migrations-completed-to-hash-instance.migration.ts	0.00%	21 Missing ⚠️
...grations/001-create-hash-system-types.migration.ts	0.00%	6 Missing ⚠️
...ate-hash-system-entities-and-web-bots.migration.ts	0.00%	2 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #8187      +/-   ##
==========================================
- Coverage   58.12%   58.09%   -0.04%     
==========================================
  Files        1176     1177       +1     
  Lines      110784   110859      +75     
  Branches     4994     5006      +12     
==========================================
  Hits        64398    64398              
- Misses      45634    45709      +75     
  Partials      752      752              

Flag	Coverage Δ
apps.hash-api	0.00% <0.00%> (ø)

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.

🚀 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.

[cursor]

Bug: Skipped migrations leave migrationState empty, breaking subsequent migrations

When migrations are skipped because they're already completed, the migrationState object is never populated with type version information. The migrationState is only populated when migration functions execute (via utilities like createSystemEntityTypeIfNotExists). Later migrations that use getCurrentHashSystemEntityTypeId or similar functions expect migrationState.entityTypeVersions to contain the current versions, but it will be empty when prior migrations were skipped. This causes failures when deploying new migrations to existing instances where migrations 001-024 are skipped but migration 025 needs to run and look up hashInstance entity type version.

Additional Locations (1)

• apps/hash-api/src/graph/ensure-system-graph-is-initialized/migrate-ontology-types/migrations/025-add-migrations-completed-to-hash-instance.migration.ts#L33-L37

 

[cursor]

Cursor Agent can help with this pull request. Just @cursor in comments and I'll start working on changes in this branch.
_{Learn more about Cursor Agents}