Skip to main content
Troubleshooting · files

Use when

A version shows source date: none, or an answer needs the date that a document states and has none.

Looking for something else?

The time when an entity is true (problem An entity lost its time after an edit). A search that ignores dates (card rule search.8).

​
Signs

  • penumbra files inspect <file> prints source date: none.
  • penumbra files versions <file> lists the version without the words source date.
  • penumbra context entity <entity-id> --json shows no source date under time for an entity from that File.
  • The person asks what is the latest, or what was true on a date, and the passages carry no date.

​
Why it happens

The source date is the date that the document itself states, such as a filing, report or sent date. It is not the upload date. It belongs to one version of a File, and it exists only if someone sends it. An upload, a replace or a new document carries it only when the command names it. A person who uploads in the App sets no date. A replace does not copy the date. The new version starts with no date, even if the old version had one. An extraction pins the date of each File when it starts, and writes that date on the entities that it proposes. An entity that you submitted keeps the date it had then. A later change to the date of the version does not reach it. Search does not use the date to filter or to order passages.

​
What Penumbra does

By itself:
  • Keeps one source date for each File version, with the precision that you send: a year, a month, a day or a full time.
  • Gives a new version a source date only when the request named one. A replace does not copy the date of the old version.
  • Pins the source date of each File when an extraction starts, and writes it on the entities that the extraction proposes.
  • Keeps on a submitted entity the date it had at submit. A later change to the date of the version does not reach the entity.
  • Sends no source date from an upload in the App.
You must:
  • Read the date from the text of the document, not from the upload.
  • Set the date on the exact version, and set it before you extract.
  • Give the date at the precision that the document gives.
Not handled:
  • Search does not order or filter passages by source date.
  • Nothing infers a source date from the text of a document.

​
Do

  1. Find the date in the document: penumbra files text <file>. Use the date the document states. If it states only a month, send only the month.
  2. Set the date on the current version: penumbra files source-date <file> 2024-05-03. For an older version, add --version <version-id>. Read the id from penumbra files versions <file>. To remove a wrong date, run penumbra files source-date <file> --clear. MCP: call update_file with the path of the File and the date. To date an older version, add its version id. A File with no path needs penumbra files place <file> <path> first, or use the CLI.
  3. Send the date when you add a File: penumbra files upload <local-path> --source-date 2024-05-03. For a new edition, run penumbra files replace <file> <local-path> --source-date <date>. For a Markdown document, run penumbra files new <path> --from <file.md> --source-date <date>. MCP: create_markdown takes a source date.
  4. If entities from this File were already submitted, they have no date. Tell the person. If the date matters, extract again from the dated version (recipe extract-files). This is the one case where a second extraction of one version is right (problem new-version-not-extracted). Expect the items to show updates existing (card rule extraction.9). An item that updates an entity that exists writes no time. Read time on the entity after the submit (problem entity-time-lost-after-edit).
  5. When you answer, say the date and its precision. Do not turn a month into a day.

​
Don’t

  • Don’t use the upload date as the source date. It tells the person when the File arrived, not the date of the document.
  • Don’t set the date after you start an extraction and expect the entities to get it. The extraction pinned the dates when it started.
  • Don’t give a day when the document states only a year. Later answers then claim more than the document says.
  • Don’t expect search to order passages by date. Read the dates from penumbra files versions <file> and order the passages yourself (card rule search.8).

​
Check

  • penumbra files inspect <file> prints source date: <date> for the version that you changed.
  • penumbra files versions <file> shows source date <date> on that version.
  • Entities from a new extraction show the date: penumbra context entity <entity-id> --json.
Card file, with rule file.5. Card search, with rule search.8. Recipes bring-in-a-corpus and new-edition. Problems entity-time-lost-after-edit and entities-cite-replaced-version.

​
Keep going

File · Passage and citation · Entity · Bring in a new edition of a document · An entity lost its time after an edit