external_link
- Category: knowledge
- Access: write
- Audience: ordinary (an ordinary user normally calls this directly)
Purpose
Link an external to a target (citation).
Arguments
Required: external_id, target_kind, target_ref.
Optional: locale, role.
-
external_id. Note: External id. -
target_kind. Note: claim|entity|task|note|session|debate|question|chunk. -
target_ref. Note: Target reference. -
locale. -
role. Note: Link role (default cites).
Result
JSON object with external_id and link_id (unchanged on duplicate).
Boundaries
Governed types are conductor-registered. Instances are project-scoped; misses and foreign rows read as not found. Refs stored, never fetched.
Lifecycle / side effects
Types immutable once governed. Instances and links accumulate; rows are never deleted.
Errors
Bad shapes/transitions rejected. Failures move nothing (atomic).
Example
{
"external_id": "...",
"target_kind": "task",
"target_ref": "..."
}
Result shape:
{
"link_id": "..."
}