0016 · An export is imported into raw, and a newer export adds versions

Status: Accepted · 2026-10-15. Amends 0004: a raw document can gain a version, from a newer copy of its source and from nothing else.

Context

A new company's CoDNA starts empty, and what it already knows is in Notion, Confluence, an Obsidian vault or Google Drive. codna import reads a markdown tree, but only on the host, which a hosted customer cannot reach. A 2026-10-15 product evaluation chose import from the web as one of the next bets: upload an export, get its pages as a folder, with the folders kept and the links working.

Two questions had to be settled by the user before building, and were:

Which space. Wiki, because a Notion workspace is already curated knowledge? Or raw, because what arrives from outside is evidence, and turning it into knowledge is a separate step?
What a second import of the same export does. A team trying CoDNA keeps writing in Notion for a while and exports again. Skip what is there, make a second copy, or bring the pages up to date?

Decision

Imported pages land in raw, in one folder per import, as evidence. What a team concludes from them is written in wiki and links back, as with any upload (ingestion.md). The uploaded archive is kept byte-for-byte as an ingestion, like every original.

Importing a newer export into the same folder adds a version to each page that changed. Pages are matched by their identity in the source -- a Notion page id, a Confluence page id, a file's path -- recorded as each page is written, so a page is found wherever it has been moved since. A page whose text is the same gets no version. A page new to the export is created beside the others. A page deleted here since stays deleted; a page gone from the export stays as it is. The report lists both. Choosing a different folder makes a fresh copy instead.

This is what ingestion.md listed as deferred, incremental re-ingestion, for imports. It changes 0004 in one respect: a raw document can gain a version, and only from a newer copy of its source. Nobody edits raw, by hand or by agent, any more than before. The import writes the version through ingestion, as ingestion is the only path that writes raw; the revision says Imported again from …, and the earlier text stays in the document's history, which is the audit trail superseding was meant to leave.

Consequences

Every link to an imported page -- from wiki, from another raw page, from an agent's notes -- still reaches it after a re-import, and shows its current text. Superseding with a second document would have left every such link on the old one.
The question "what did the source say on 3 September?" is answered by the page's history rather than by finding the right one of several documents.
A wiki page distilled from an imported page can fall behind it. Nothing tells its author yet; the raw page's history shows what changed, and its backlinks show what was written from it.
Two people importing the same export get two sets of pages, each private to its importer, since matching is per person. Sharing one set is the better answer, and the import offers a folder share for it (0014).
The archive is kept, so images and attachments an import could not bring over can be added later by importing the same archive again into the same folder, once the import can attach files (0015).

Alternatives rejected

Wiki. Closer to how the export is used today: as the company's pages, editable. Rejected by the user: what arrives from outside is evidence first, and keeping it in raw keeps "what we were given" apart from "what we concluded", which is the reason the spaces exist.

A second document per re-import, as 0004 had it for raw. Faithful to "supersede, never change", and it leaves links pointing at the first copy, a pile of near-identical pages for search to rank, and no way to see what changed between two exports short of diffing two documents by hand.

Skipping pages already imported. Simple, and wrong the moment the source changes: a re-import would quietly keep the old text.

Amendment

2026-10-18 — An import keeps its pages' images, as the consequence above foresaw. An image a page shows, or links to, becomes one of the page's own files (0015), in <slug>.files/ beside it, and the page's link points there. What a page cannot hold (an SVG, a file over 20 MB, a kind of file that is not an image) stays a note of its name and is listed in the report with why, as before; so is an image the export does not include, and one shown from the web, which is left showing from there.

Raw is never edited, so a page's files cannot follow it in a later step. A file arrives with the version that names it: its bytes are stored first, and its record is written in the same transaction as that version, through ingestion like the version itself. No version of an imported page names a file it does not hold, and a page that fails to be written takes its files' bytes with it.

A newer export treats images as it treats text. An image whose bytes did not change is the file the page already holds, so a page whose text and pictures are the same still gets no version. An image that changed is a new file beside the old one (diagram-2.png), since files never change, and the earlier version keeps showing the old one. Pages imported before this get their images by importing the same archive into the same folder again, as one new version each.

A PDF attached to a page stays a page of its own, with its text, rather than a file of the page: it is evidence to search, which a file is not.