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.

Last updated on