delete_entities

Category: knowledge
Access: write
Audience: ordinary (an ordinary user normally calls this directly)

Purpose

Retires named entities from the active knowledge graph. Despite the name, nothing is physically deleted: this is a lifecycle transition (active to voided) covered by the no-delete invariant. Re-creating the same name revives the same entity identity.

Arguments

Required: entityNames.

entityNames. Note: Names that are unknown, already retired, or outside the caller's project scope are silently skipped and contribute zero to the deleted count; there is no error for unmatched names.

Result

JSON object with deleted (count of entities retired by this call).

Boundaries

Scope is enforced per entity: content outside the caller's project grants is silently skipped, never denied loudly, so callers cannot probe foreign projects by name. Operates only inside the caller's profile boundary.

Lifecycle / side effects

Records an audit/history event per entity, then marks it void with voided_at/voided_by stamps. Observations, relations, and aliases are NOT cascaded: they stay in place, resolve as absent while the entity is void, and revive independently. Re-creating an entity with the same name revives the original identity (void stamps retained as last-void evidence; history lives in the audit trail).

Errors

entityNames must be an array of strings (validation error otherwise). Unknown arguments rejected. The operation fails atomically (zero partial voids). deleted: 0 with no error means nothing matched or nothing was visible.

Example

{
  "entityNames": [
    "Stale Vendor"
  ]
}

Result shape:

{
  "deleted": 1
}

A later create_entities with name Stale Vendor revives the same identity rather than duplicating it.