Saving, binding, and failure recovery¶
First use GET to check the original candidate’s saved/bound state, then explicitly choose POST based on binding intent. GET returns a reserved skill_id even when saved=false; only saved establishes save status.
Situation |
Interpretation and next steps |
|---|---|
GET saved=false/bound=false |
No matching saved record found yet. Possessing an ID does not establish that the skill exists. |
GET saved=true/bound=false |
Saved, but no binding was found within this eligible target scope. Check binding intent and eligibility. |
GET saved=true/bound=true |
A skill binding was found in the current target; do not recreate the candidate. |
POST bind_current=false returns bound=false |
This request does not bind or remove existing bindings. GET may still return bound=true. |
POST bind_current=true succeeds |
The skill was saved/reused and bound. The result includes only skill/Workspace/target and bound, without a new version number. |
409 with details.reason SKILL_CREATOR_BINDING_FAILED |
Saving completed but binding failed. Retain details.saved_skill_id, query using the same task/call/digest, then retry binding according to the original intent. |
Timeout or other unknown result |
Query the same candidate identity. Do not create another using a different call_id or treat the error as a complete rollback. |
Saving verifies the candidate in a task-locked tenant transaction and derives the skill ID from workspace/task/call. An existing record is reused only when its archive digest and CreatedBy match; otherwise it conflicts. This is not a general idempotency guarantee for arbitrary users and content.
Binding follows the save transaction and first verifies target update access. Ordinary targets add a skill reference. Package-managed targets preserve explicit resources/custom metadata and load through a new package version, using the expected default version to prevent concurrent overwrites. This may publish a version; it is not guaranteed to append only one reference;
GET is not a repair operation and does not infer other targets’ binding status for read-only/system sources.