fix(kbs): legacy subblock id migration + CI check

[icecrasher321]

Summary

• Existing subblock id for KB was changed leading it to be dropped by serializer.
• Add CI check to prevent changing of IDs like this
• Add migration for subblock ids in the case where it has to be changed / incorrectly changed like this.

Type of Change

• Bug fix
• Other: Linter Improvement

Testing

Tested on old commits.

Checklist

• Code follows project style guidelines
• Self-reviewed my changes
• Tests added/updated and passing
• No new warnings introduced
• I confirm that I have read and agree to the terms outlined in the Contributor License Agreement (CLA)

[vercel]

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

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
docs	Skipped		Mar 5, 2026 8:25pm

[cursor]

PR Summary

Medium Risk
Touches workflow state loading/migration and background persistence of migrated subBlocks, which could affect deployed workflows if the new pipeline has edge cases. Changes are mostly additive and covered by unit tests plus a CI guardrail.

Overview
Fixes a backward-compatibility break where renamed subblock IDs caused deployed/saved block state to be dropped by adding SUBBLOCK_ID_MIGRATIONS and a migrateSubblockIds pass (initially mapping knowledge.knowledgeBaseId → knowledgeBaseSelector).

Refactors workflow loading to run a single applyBlockMigrations pipeline (sanitization, agent message-format migration, credential ID migration, and the new subblock-ID migration) and persists any migrated subBlocks back to workflowBlocks.

Adds a CI step and new script (check-subblock-id-stability.ts) that diffs block definitions against the base ref and fails if any subblock ID was removed without an entry in SUBBLOCK_ID_MIGRATIONS, plus unit tests for the new migration behavior.

^{Written by Cursor Bugbot for commit 47fcf4a. Configure here.}

[greptile-apps]

Greptile Summary

This PR fixes a regression where a renamed subblock ID (knowledgeBaseId → knowledgeBaseSelector) in the knowledge block caused deployed/saved workflows to silently lose their selected knowledge base. The fix introduces a migration layer (subblock-migrations.ts) that rewrites legacy keys at load time, wires it into both workflow-loading paths in persistence/utils.ts, and adds a CI script plus GitHub Actions step to prevent the same class of breakage in the future.

Key changes:

• subblock-migrations.ts: New migration module with SUBBLOCK_ID_MIGRATIONS registry and migrateSubblockIds() mutating helper. Well-structured with good JSDoc.
• persistence/utils.ts: Migration is applied in loadDeployedWorkflowState (in-memory only, not persisted — correct for blob storage) and in loadWorkflowFromNormalizedTables (with a fire-and-forget DB back-write). The back-write loop iterates all blocks unconditionally, unlike the adjacent credential migration which guards writes with a reference check — an inefficiency noted in review.
• check-subblock-id-stability.ts: New CI script that compares the current block registry against the base ref using text parsing. Two fragility issues flagged: the extractSubBlockIds regex requires id: to be the first property inside a subblock object (silently misses IDs otherwise), and typeMatch grabs the first type: '…' in the file which could match a nested type rather than the block-level type — both can produce false negatives in the check.
• subblock-migrations.test.ts: Thorough unit tests covering all relevant edge cases.

Summary: The core migration logic is sound and well-tested. The CI guardrail introduces helpful validation but has two regex fragility issues that should be addressed to ensure the check is truly reliable.

Confidence Score: 3/5

• The core migration logic is correct and well-tested; however, the CI linter has two regex fragility issues that can silently miss ID renames, undermining the reliability of the guardrail being introduced.
• The migration module and its tests are solid (confidence 5/5), and the main bug fix in persistence/utils.ts is correct. However, two issues reduce overall confidence: (1) the CI script's extractSubBlockIds regex silently misses IDs if id: is not the first property, (2) the typeMatch regex may capture the wrong type: if other type declarations appear earlier in the file — both produce false negatives in the ID stability check. Additionally, the persistence loop in loadWorkflowFromNormalizedTables updates all blocks unconditionally, which is inefficient (though not a correctness issue). These concerns are contained to the new CI guardrail and efficiency, not production correctness.
• Pay close attention to apps/sim/scripts/check-subblock-id-stability.ts (regex fragility) and apps/sim/lib/workflows/persistence/utils.ts (unconditional DB writes in lines 393-406).

Sequence Diagram

sequenceDiagram
    participant Client
    participant utils as persistence/utils.ts
    participant credMigrate as migrateCredentialIds
    participant sbMigrate as migrateSubblockIds
    participant DB as workflowBlocks (DB)

    Client->>utils: loadWorkflowFromNormalizedTables(workflowId)
    utils->>DB: fetch blocks
    DB-->>utils: raw blocks
    utils->>credMigrate: migrateCredentialIds(blocks)
    credMigrate-->>utils: credMigratedBlocks
    utils->>sbMigrate: migrateSubblockIds(credMigratedBlocks)
    sbMigrate-->>utils: anyMigrated (boolean)
    alt anyMigrated = true
        utils->>DB: fire-and-forget update ALL blocks (subBlocks + updatedAt)
        Note over utils,DB: ⚠ Updates every block, not just migrated ones
    end
    utils-->>Client: return assembled workflow state

    Client->>utils: loadDeployedWorkflowState(workflowId)
    utils->>DB: fetch deployment blob
    DB-->>utils: JSON state
    utils->>credMigrate: migrateCredentialIds(blocks)
    credMigrate-->>utils: credMigratedBlocks
    utils->>sbMigrate: migrateSubblockIds(credMigratedBlocks)
    Note over utils,sbMigrate: Migration applied in-memory only — not persisted
    utils-->>Client: return migrated state

Loading

_{Last reviewed commit: 8e116d6}

[icecrasher321]

@cursor review

[cursor]

✅ Bugbot reviewed your changes and found no new issues!

Comment @cursor review or bugbot run to trigger another review on this PR