# Draft, publish and lifecycle APIs

createIntegrationDefinitionSource and importIntegrationDefinitionSource create
new native drafts. updateIntegrationDefinitionSource requires id, sourceXML and
the expectedRevision from the last read. A stale revision fails without replacing
the source. Root integration id and version cannot change inside a draft.

validateIntegrationDefinitionSource returns valid, diagnostics, errors, projection
and locations without saving or executing anything. exportIntegrationDefinitionSource
returns the exact authoritative source. integrationAuthoringCatalog returns the
compiler-owned vocabulary, including delegated Workflow and EdgeApp catalogs.

publishIntegrationDraft accepts expectedRevision alongside the draft id. Supply
the revision you reviewed: a concurrent edit rejects publication so you can reload
and review the newer source. Publishing validates the source again, promotes the
draft and moves its parent's
current version pointer atomically. Published versions remain immutable. Creating
an instance pins one published definition and supplies its configuration and bindings.
Start, stop, Action invocation and explicit upgrade use that pinned native version.
Upgrade failures preserve the established failure state and old definition pointer.

Pause, deletion, configuration restarts and upgrades wait for the existing actor
to stop, including an actor running on another platform node. A competing start
cannot run during that installation change. Brief connection interruptions do
not immediately stop a running integration. If shutdown cannot be confirmed,
pause and deletion fail without claiming the instance stopped or deleting it.
A failed upgrade keeps its old definition pointer and reports the failure.
Queued handlers are canceled before the shutdown hook runs. A shutdown-hook
error is reported after the actor has stopped; it does not prevent pause or deletion.

Definitions and instances have distinct authorization and tenant boundaries.
Reading a definition or its catalog requires integrationDefinition read access;
changing a draft or publishing requires the corresponding write permission.