delete_observations

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

Purpose

Retires exact observation texts from named entities. Despite the name, nothing is physically removed: this is a lifecycle transition (active to voided) covered by the no-delete invariant, and re-adding the text revives the same identity.

Arguments

Required: deletions.

deletions. Note: Each entry needs entityName plus an observations string list matched by exact text. Unknown entities, unknown texts, and non-string items are silently skipped with zero contribution.

Result

JSON object with deleted (count of observations 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 retired observation, then marks it void with voided stamps. Re-adding the same text revives the original identity (creation evidence untouched; history lives in the audit trail).

Errors

deletions must be an array; entries need a string entityName. Unknown arguments are rejected (strict validator). The operation fails atomically (zero partial voids). deleted 0 with no error means nothing matched or nothing was visible.

Example

{
  "deletions": [
    {
      "entityName": "Acme Print",
      "observations": [
        "Now offers same-day turnaround."
      ]
    }
  ]
}

Result shape:

{
  "deleted": 1
}