[feature] Workflow versioning (per-revision IDs) + back-compat policy

[B2JK-Industry]

Friction

A KeeperHub workflow's behavior can change over time — its author edits the steps, swaps integrations, tightens validation. Adapter callers (SBO3L's KH adapter, Devendra's langchain-keeperhub, anyone integrating downstream) have no way to:

• Pin against a specific workflow revision
• Detect that a workflow they were calling has changed shape
• Cleanly roll back to a previous workflow version when a new one breaks

Today the only <id> in the webhook URL is the workflow's identity — not its revision. Submitting against a workflow that silently changed its required envelope shape produces opaque 422s with no way to say "use the version I've actually integration-tested against."

Proposed fix

Two additions:

1. Stable per-revision IDs. When a workflow is edited, KH retains the prior revision and exposes it at /api/workflows/<id>@<revision>/webhook. The bare /api/workflows/<id>/webhook continues to mean "latest" with explicit fall-through documentation.

2. Back-compat policy. Document KH's commitment to revision longevity (e.g. "older revisions remain reachable for 90 days post-supersede; webhook responses for retired revisions return 410 Gone with the migration URL"). Adapter authors then know how to size their pinning + alerting infrastructure.

Context

Filed as part of SBO3L's KeeperHub Builder Feedback round 3 for ETHGlobal Open Agents 2026. Composes with #55 (X-KeeperHub-Schema-Version header) — workflow revision is the orthogonal axis.

[suisuss]

Verified this against the live schema and routes rather than taking the friction description at face value, and the picture is more nuanced than "no versioning exists."

KH already keeps a full edit history internally - every workflow update writes a row to workflow_history with a monotonic version number, a content hash, and a full snapshot, and that history is currently retained indefinitely (there is no cleanup job; rows only disappear if the workflow itself is deleted). There is even a ?version=N read endpoint that returns a historical snapshot. So this is not starting from zero.

What is actually missing is narrower than the issue title suggests: the webhook execution path (POST /api/workflows/<id>/webhook) always runs whatever the workflow's live row currently contains - it never consults workflow_history, and there is no way to address a past revision in that URL. We also compute a content hash of the exact definition each execution ran, but never return it to the caller, so an adapter genuinely has no way to detect drift ahead of the opaque 422 you described. Today the only pinning workaround is duplicating the workflow to a separate id and letting the original evolve independently.

Given that, I don't think this is a straightforward accept. The real decision isn't "should we build revision tracking" - we have the data already - it's whether webhook execution should default to floating-latest (today's behavior, and what every existing integration already assumes) or default to pinned (which would be a breaking change for every current webhook caller unless it's opt-in), and separately, whether replaying an old snapshot is even safe given that a workflow's live dependencies - integration credentials, plugin step contracts - can change underneath an unchanged JSON shape. Formalizing "revisions stay reachable for N days" as an external contract is also a bigger commitment than the current de facto forever-retention, and needs sign-off before we publish it.

I'm taking this to the core team to work through those tradeoffs and will come back to you with where we land. Your <id>@<revision> addressing is a reasonable strawman for that discussion, though if we proceed it will likely follow the ?version= convention we already use elsewhere rather than introduce a new URL shape.