#305: a full pond archive before deletion and before purge #316

opus-5 · 2026-08-01T19:39:08+02:00

opus-5 commented

2026-08-01 19:39:08 +02:00

Implements #305.

The safety prompt was never the gap — typing the pond name is stricter than a confirm dialog and stays untouched. The gap is that the person who deletes the pond loses access the moment they do: it leaves their view, only a Site Admin can bring it back, and the export is no longer reachable for them. So the archive is offered inside the deletion flow, before the button.

What the archive contains

Every page the requester may read, as Markdown (as before).
Every attachment of the pond, not only the embedded ones — an attachment nobody put on a page would otherwise vanish unnoticed, which is the reason this issue exists.
manifest.json: pond settings (effective, defaults filled in — a preservation format must not require its reader to know Dorfteich's defaults), labels, page hierarchy and sort keys, comments, attachment metadata incl. the #199 hash. It extends the #210 manifest rather than adding a second descriptor, and carries an explicit formatVersion.
README.txt — the manifest is for machines; whoever unpacks a folder of Markdown a year from now must not believe they hold a one-click restore.

Format documented in docs/architecture/pond-archive-format.md, including what is deliberately NOT in it (history, permissions, trash).

Decisions worth reviewing

"Complete" describes the RESULT, not the route. A pond admin who may read every page gets complete: true; only an archive that actually leaves pages out is incomplete. The Site-Admin route skips the read filter — an archive taken before an irreversible purge must not depend on which ponds the operator is a member of. My first version conflated the two, and the test caught it.
The omission is named before the download, with its number, in the UI and in the manifest.
Not downloading stays allowed — the finality is stated in text, not enforced. The server cannot tell whether a file arrived anyway.
A plain link, not fetch-into-a-blob. The api streams the ZIP; buffering a whole pond in the tab to draw a progress bar trades memory for cosmetics. The browser reports progress and completion; that the archive is being BUILT is announced in a live region.
Read trail unchanged in kind (ADR 0023): one export event per classified page before any classified byte enters the stream; attachments never travel without their page.
New audit action pond.archived, catalogue v1.7.

Verified by hand, not only asserted

A real pond's archive downloaded and unpacked:

README.txt  manifest.json  pages/{classified-note,every-element,fixture-image}.md  media/<id>.png

The manifest carried the effective settings (8 keys incl. fonts/theme/startPageId), per-page classification, the attachment with its sha256, and the files list. The classified page's Markdown kept its classification: vs_nfd frontmatter and the VS-NfD marking.

Plus: 6 api tests (an unembedded attachment travels; the hierarchy/labels/comments land in the manifest; the preview reports omissions; the audit entry carries the counts; a Site Admin gets a complete archive without pond membership; an ordinary pond admin gets 403 on the admin route), api suite 104 files green, a11y pack 11/11 in both schemes — it now also scans the pond settings screen.

Not done, and why

The Site Admin's purge dialog (#193) exists only as an api endpoint — there is no pond-trash UI in the web app to attach an offer to. The api half (GET /admin/trash/ponds/:id/archive[/preview]) is here and tested, so it becomes a link the day that screen is built. Building it is #193's scope, not this one's.

The "N pages omitted" path is covered by the api's preview logic and unit-level assertions, not by an e2e with a label-restricted reader.

Closes #305

Implements #305. The safety prompt was never the gap — typing the pond name is stricter than a confirm dialog and stays untouched. The gap is that **the person who deletes the pond loses access the moment they do**: it leaves their view, only a Site Admin can bring it back, and the export is no longer reachable for them. So the archive is offered inside the deletion flow, before the button. ## What the archive contains - Every page the requester may read, as Markdown (as before). - **Every attachment of the pond**, not only the embedded ones — an attachment nobody put on a page would otherwise vanish unnoticed, which is the reason this issue exists. - `manifest.json`: pond settings (**effective**, defaults filled in — a preservation format must not require its reader to know Dorfteich's defaults), labels, page hierarchy and sort keys, comments, attachment metadata incl. the #199 hash. It extends the #210 manifest rather than adding a second descriptor, and carries an explicit `formatVersion`. - `README.txt` — the manifest is for machines; whoever unpacks a folder of Markdown a year from now must not believe they hold a one-click restore. Format documented in `docs/architecture/pond-archive-format.md`, including what is deliberately NOT in it (history, permissions, trash). ## Decisions worth reviewing - **"Complete" describes the RESULT, not the route.** A pond admin who may read every page gets `complete: true`; only an archive that actually leaves pages out is incomplete. The Site-Admin route skips the read filter — an archive taken before an irreversible purge must not depend on which ponds the operator is a member of. My first version conflated the two, and the test caught it. - **The omission is named before the download**, with its number, in the UI and in the manifest. - **Not downloading stays allowed** — the finality is stated in text, not enforced. The server cannot tell whether a file arrived anyway. - **A plain link, not fetch-into-a-blob.** The api streams the ZIP; buffering a whole pond in the tab to draw a progress bar trades memory for cosmetics. The browser reports progress and completion; that the archive is being BUILT is announced in a live region. - Read trail unchanged in kind (ADR 0023): one `export` event per classified page before any classified byte enters the stream; attachments never travel without their page. - New audit action `pond.archived`, catalogue **v1.7**. ## Verified by hand, not only asserted A real pond's archive downloaded and unpacked: ``` README.txt manifest.json pages/{classified-note,every-element,fixture-image}.md media/<id>.png ``` The manifest carried the effective settings (8 keys incl. fonts/theme/startPageId), per-page classification, the attachment with its sha256, and the files list. The classified page's Markdown kept its `classification: vs_nfd` frontmatter and the VS-NfD marking. Plus: 6 api tests (an unembedded attachment travels; the hierarchy/labels/comments land in the manifest; the preview reports omissions; the audit entry carries the counts; a Site Admin gets a complete archive without pond membership; an ordinary pond admin gets 403 on the admin route), api suite 104 files green, a11y pack 11/11 in both schemes — it now also scans the pond settings screen. ## Not done, and why The Site Admin's purge dialog (#193) **exists only as an api endpoint** — there is no pond-trash UI in the web app to attach an offer to. The api half (`GET /admin/trash/ponds/:id/archive[/preview]`) is here and tested, so it becomes a link the day that screen is built. Building it is #193's scope, not this one's. The "N pages omitted" path is covered by the api's preview logic and unit-level assertions, not by an e2e with a label-restricted reader. Closes #305

opus-5 added 1 commit 2026-08-01 19:39:08 +02:00

#305 : a full pond archive before deletion and before purge

CI / Lint, typecheck, test (pull_request) Successful in 7m22s

Details

CI / Build container images (pull_request) Successful in 11s

Details

CI / Auth e2e pack (pull_request) Successful in 9m39s

Details

CI / Import/export fidelity gate (pull_request) Successful in 1m4s

Details

1b992c8626

Deleting a pond already had a strict prompt — typing the pond name, stricter
than a confirm dialog. That was never the gap. The gap is that the person who
deletes it loses access the moment they do: the pond leaves their view, only a
Site Admin can bring it back, and the export is no longer reachable for them.
So the archive is offered INSIDE the deletion flow, before the button.

What it contains, and why it is not the existing export:

- Every page the requester may read, as Markdown, as before.
- **Every attachment of the pond**, not only the embedded ones. An
  attachment nobody put on a page would otherwise vanish unnoticed — which
  is the whole reason this issue exists.
- `manifest.json`: pond settings (EFFECTIVE, defaults filled in — a
  preservation format must not require its reader to know Dorfteich's
  defaults), labels, the page hierarchy and sort keys, comments, and
  attachment metadata including the #199 hash so a reader can verify bytes.
  It extends the #210 manifest rather than adding a second descriptor, and
  carries an explicit `formatVersion`.
- `README.txt`, because the manifest is for machines: whoever unpacks a
  folder of Markdown a year from now must not believe they hold a one-click
  restore.

Decisions worth naming:

- **"Complete" describes the RESULT, not the route.** A pond admin who may
  read every page gets `complete: true`; only an archive that actually
  leaves pages out is incomplete. The Site-Admin route skips the read filter
  (an archive taken before an irreversible purge must not depend on which
  ponds the operator happens to be a member of) — those are two different
  questions and the first version of this conflated them.
- **The omission is named before the download**, with its number, in the UI
  and in the manifest. An archive silently missing content is worse than no
  archive, because it ends the search.
- **Not downloading stays allowed.** A pond of test pages should not require
  one, and the server cannot tell whether a file arrived anyway — so the
  finality is stated in text instead of enforced.
- **A plain link, not fetch-into-a-blob.** The api streams the ZIP; buffering
  a whole pond in the tab to draw a progress bar would trade memory for
  cosmetics. The browser reports progress and completion; what it cannot say
  — that the archive is being BUILT — is announced in a live region.
- Read trail unchanged in kind (ADR 0023): one `export` event per classified
  page before any classified byte enters the stream. Attachments never travel
  without their page, so the same events cover them.
- New audit action `pond.archived` (catalogue v1.7) with page and attachment
  counts, omitted pages, and completeness.

Format documented in `docs/architecture/pond-archive-format.md`, including
what is deliberately NOT in it (history, permissions, trash).

Verified by hand, not only asserted: a real pond's archive downloaded and
unpacked — README, manifest, three page files, the media file; the manifest's
effective settings, per-page classification, the VS-NfD frontmatter and
marking preserved in the classified page's Markdown, and the attachment's
sha256 present. Plus six api tests (including that an unembedded attachment
travels and that a Site Admin gets a complete archive without membership) and
the a11y pack 11/11 in both schemes, which now also scans the pond settings
screen.

Not done, because there is nothing to attach it to: the Site Admin's purge
dialog (#193) exists only as an api endpoint — there is no pond-trash UI in
the web app. The api half is here and tested, so it becomes a link when that
screen is built.

fable-5 force-pushed issue-305-pond-archive from 1b992c8626 to 5c03da2ccc

2026-08-01 20:04:57 +02:00

Compare

fable-5 force-pushed issue-305-pond-archive from 5c03da2ccc to 3310ae3926

2026-08-01 20:24:56 +02:00

Compare

opus-5 merged commit 3310ae3926 into main

2026-08-01 20:43:42 +02:00

Sign in to join this conversation.

No reviewers