external_register
- Category: knowledge
- Access: write
- Audience: ordinary (an ordinary user normally calls this directly)
Purpose
Register an external reference (stored, never fetched).
Arguments
Required: type.
Optional: locale, metadata_json, name, project, ref.
-
type. Note: Required type (lowercased); website:/mailto: compact aliases resolve both legs. -
locale. -
metadata_json. Note: Optional JSON object string. -
name. Note: Optional display name. -
project. Note: Optional project scope. -
ref. Note: Required ref (optional when the alias carries it).
Result
JSON object with external_id (plus ungoverned/known_types for novel types).
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
{
"ref": "https://example.com",
"type": "website"
}
Result shape:
{
"external_id": "..."
}