Skip to main content
Troubleshooting · graph

Use when

A File was trashed or purged and the Graph holds entities that cite it, or an entity shows sources that will not open.

Looking for something else?

A File replaced by a new edition (problem Entities still cite a replaced version). A citation that waits for an answer after an edit (card Citations to confirm).

​
Signs

  • penumbra files list --trashed shows a File, and penumbra context explore --file-id <file-id> --json still lists entities whose files hold that File ID.
  • penumbra context entity <entity-id> still prints a from: line for the File. The line does not say that the File is trashed.
  • On MCP, read of the entity ends with a line that says some citations are not shown because their File is not readable. The entity can also say that it has no sources recorded.
  • penumbra context materialize warns with graph_evidence_unavailable for a citation, and the entity appears in the packet without that source.
  • After a purge, penumbra files restore <file-id> is refused with file_content_purged.

​
Why it happens

A trash takes the File out of reads and out of search. A citation names a File, a version and a content digest, and a trash changes none of them. So the entity keeps its citations, and no one can open the text behind them. The Graph does not read the Files side when a File is trashed. It keeps the entity and its citations as they were. The entity can still be right. The person may have trashed the File to tidy the project, or in error, or because the File is wrong. Penumbra cannot tell which.

​
What Penumbra does

By itself:
  • Keeps a trashed File, with its versions, until Penumbra purges it. Restore brings it back.
  • Leaves the entities and relationships that cite the File as they are.
  • Keeps each citation as it was written, with its File, version and content digest.
  • Lists the entity under the File ID in penumbra context explore --file-id.
  • Reads a trashed File as not found, so the exact text behind its citations cannot be opened.
  • Counts such citations on an MCP entity read and does not list them.
  • Leaves such citations out of a packet and warns with graph_evidence_unavailable.
  • Opens the citations again after a restore, with no change to the entity.
You must:
  • Find the entities that cite the File before you trash it, and after.
  • Tell the person which entities lose a readable source, and let the person decide.
Not handled:
  • No flag or recheck on entities when their File is trashed or purged.
  • No notice that tells you a File with entities was trashed.
  • The context commands do not say that a cited File is trashed.
  • After a purge, the File cannot come back, and its citations cannot be opened again.

​
Do

  1. Confirm the state of the File. penumbra files list --trashed lists trashed Files, and penumbra files list --all also shows (purged) in the PATH column. Note the File ID.
  2. List the entities that cite it: penumbra context explore --file-id <file-id> --limit 200 --json. Read the files list of each entity. Add --cursor <cursor> for the next page. MCP: none for this list. Use the CLI.
  3. Keep the entities whose citations all point to trashed or purged Files or to older versions. Recipe find-stale-entities does this for many Files.
  4. Tell the person what you found. Give each entity with its name, its type and the File it cites. Ask what to do with each.
  5. If the person trashed the File by mistake, restore it: penumbra files restore <file-id>. A restore does not wait for approval (card rule file.8). If it is refused with file_content_purged, the File is gone for good.
  6. If another File holds the same fact, cite that File for the entity. Check the entity out in a workspace and stage the change with a citation of the live passage (recipe review-and-submit, card rule citations-to-confirm.11).
  7. If the fact is no longer true, and the person says so, delete the entity: penumbra graph delete <entity-id>. An API key or a connected agent waits for approval (card rule entity.4).

​
Don’t

  • Don’t delete an entity because its File is trashed. A restore brings the source back, and the entity may be right.
  • Don’t restore a File that the person trashed on purpose. Ask first.
  • Don’t read the from: line as proof that the source opens. It names the File even when the File is trashed.
  • Don’t trash a File to remove its entities. Trash leaves the entities in the Graph.

​
Check

  • penumbra files list --trashed no longer lists a File you restored.
  • Or each entity that cited the trashed File cites a live File now.
  • Or the person has decided to keep the entity as it is.
  • On MCP, read of a refreshed entity lists its sources and shows no line about citations that are not shown.
Cards file (rules file.8 and file.9), passage and context. Recipe find-stale-entities. Problems entities-cite-replaced-version and two-editions-two-files.

​
Keep going

File · Passage and citation · Entity · Context · Find entities that rest on an old version or a trashed File · Entities still cite a replaced version · A new edition is a separate File