Skip to main content
Troubleshooting · graph

Use when

You replaced a File that the Graph already has entities from, or you plan to.

Looking for something else?

An entity edited by hand whose citations need confirming (card Citations to confirm). A new edition uploaded as a separate File (problem A new edition is a separate File).

​
Signs

  • penumbra files versions <file> shows a newer version marked current, and older versions without that mark.
  • penumbra context entity <entity-id> prints a from: line with version=<id>. That version is not the current one.
  • Search returns passages from the new version only. The passages that the entities cite no longer appear.
  • The Graph and search give different answers about the same document.

​
Why it happens

A replace adds a new version to the same File. Penumbra reads it in the background. The old version stays current and searchable until the new version is ready. Then the new version becomes current, and the passages of the old version leave search. A citation names the exact version and its content digest. It often names the passage that supported the entity, too. A replace changes none of that. So each entity still points to text that search no longer shows. Nothing compares the old citation with the new text, and nothing extracts the new version by itself. The Graph keeps saying what the old edition said, while search says what the new edition says. Relationships cite versions in the same way.

​
What Penumbra does

By itself:
  • Search reads only the current version of a File.
  • A replace keeps the File id, and the File stays in its collections and in any View that includes it.
  • The old version and its passages stay readable by version id.
  • A citation keeps the exact version that it names.
  • A replace that fails leaves the old version current.
You must:
  • Find the entities that cite the old version.
  • Extract from the new version, and compare it with what you found.
  • Cite a passage of the new version for each entity that stays true.
Not handled:
  • No flag or recheck on entities when their File gets a new version.
  • No extraction of the new version by itself.
  • No command or tool that you can call lists what cites one exact version.
  • The CLI shows the citations of entities. It does not show the citations of relationships.

​
Do

  1. Check that the new version is current: penumbra files versions <file>. If it is not current, wait for it: penumbra files wait <operation-id>. The replace printed the operation id. A failed replace changes nothing here.
  2. Find the entities that cite the File.
    • CLI: penumbra context explore --file-id <file-id> --limit 200 --json. Read the files list of each entity. Keep the entities whose version id is not the current one. Add --cursor <cursor> for the next page.
    • MCP: no tool lists the entities of one File. Call read with the reference of each entity that you know. It shows the version of each citation.
  3. Extract from the new version (recipe extract-files). The run opens its own new workspace: penumbra graph extract --file-id <file-id> --shape "<shape>". An API key or a connected agent waits for approval (problem change-waits-for-approval).
  4. Compare each old entity with the new text and with the new extraction. Decide for each entity: still true, changed, or no longer true.
    • Still true or changed: check the entity out with penumbra graph workspace hydrate "<workspace>" --node <entity-id>. Then change it with penumbra graph workspace modify "<workspace>" <file>, and cite a passage of the new version in the same change (card rule entity.6). MCP: call read on a passage of the new version. It returns a citation token that you give to the change.
    • No longer true: tell the person, and wait for the answer before you delete anything.
    • Relationships cite versions in the same way, and the CLI does not show their citations. Tell the person that you checked entities, not relationships.
  5. Search the Graph for each entity that the new extraction proposes: penumbra graph search "<name>". Use the entity that already exists, not a second copy (problem extraction-duplicates-existing-entity).
  6. Review and submit the workspace (recipe review-and-submit).

​
Don’t

  • Don’t delete entities because their passages left search. The old version still says what it said, and the person may want to keep it.
  • Don’t upload the new edition as a separate File to keep both. Search then returns both, and nothing says which is newer (problem two-editions-two-files).
  • Don’t replace the File again while an extraction of it waits for approval. The approval names the exact version, and Penumbra then refuses the run.
  • Don’t submit the new extraction as it is. It can propose entities that the Graph already has.

​
Check

  • Each entity from this File cites a passage of the current version. Run penumbra context entity <entity-id> and read its from: lines. Or the person has decided to keep that entity on the old version.
Card file. Card rules entity.6 and workspace.8. Recipes new-edition, extract-files and find-stale-entities. Problems two-editions-two-files, new-version-not-extracted and what-cites-this-version.

​
Keep going

File · Entity · Passage and citation · Bring in a new edition of a document