Version Pinning

Overview#

Each workflow version has its own margin, hosted compute estimate, and displayed price. Wallet-funded runs use the version selected for that run. A bundle or supported legacy purchase creates a lasting version lock.

Bundles are locked to the version they were purchased with. They only draw when you run that exact version.

Purchase rows may also store a workflow version pin. A null pin means the purchase follows the live active version. When a non-null pin is present, marketplace runs and the public input schema for that buyer use that pinned version.

How pinning works#

When a creator publishes, margin and compute are stored on the version. Those values stay fixed for that version.

A bundle record stores the version it covers. A supported legacy unlock also stores its purchase version. Ordinary wallet-funded access does not create a universal purchase record.

New paid checkout and free claim paths mint or resolve a version at purchase time and write it as the purchase pin. Existing purchases that already have a null pin keep following the live active version forever. That null-follows-active rule is intentional for grandfathered rows.

When you trigger a run, the price comes from the version you selected. Wallet charges and bundle consumption use that version's displayed price.

Choosing a version#

Buyers can switch among available versions in the run UI. Each selection uses that version's current displayed price unless a matching bundle or supported legacy access record supplies a locked price.

Bundle runs remaining only appear when the selected version matches the bundle version.

API version resolution#

POST /runs pins every API-triggered run to one immutable workflow version. Two API callers can hit the same workflow id and end up on different graphs, in this order:

1. Explicit version in the request body. The run executes that exact immutable graph. Owners can select any version; buyers can select the version their purchase pin covers. An unknown or forbidden version returns 403 forbidden.
2. Purchase pin. When version is omitted and the caller's workflow_purchases.workflow_version_id is non-null, the run executes that pinned version. A newer active version does not silently upgrade a pinned buyer.
3. Follow active. When version is omitted and the pin is null, the run executes the workflow's current active_version_id. These callers float with each publish.

GET /workflows/{id} surfaces pinnedVersionId, activeVersionId, and updateAvailable so API integrators can detect drift without polling every run. Buyers who want to re-pin to the newest version can call POST /workflows/{id}/accept-update (requires workflow:write).

Existing purchase rows with a null pin stay grandfathered as follows-active. Only new purchases mint or resolve a version at purchase time.

When creators change prices#

If a creator changes the price on a new version, existing matching bundles and supported legacy purchases retain their recorded version terms.

Wallet-funded buyers can choose the newer available version and pay its displayed price.

Unpublished versions#

Availability of an unpublished version depends on the bundle or supported legacy access record and retained execution data. If it cannot be prepared, the UI shows an error and no run charge starts.

Special cases#

• Remix: The one permitted parent workflow uses the version recorded when the remix is published.
• Takedown: Access to an older version remains subject to product availability and platform policy.

What you see in Edgaze#

• Version selector with per-version displayed prices
• Matching bundle or legacy version highlighted where applicable
• Bundle runs remaining only when the selected version matches
• Error if an unpublished version's graph is missing

Related policies#

• Publish and Price
• Funding Runs
• Remix and Nested Workflows
• Legacy Unlock