From e667ee7203bdd07e0d2256feac06ec9741306ce7 Mon Sep 17 00:00:00 2001 From: napnap75 Date: Mon, 2 Nov 2026 11:12:08 +0100 Subject: [PATCH] archivist: US-01/US-12/US-17 aligned with versioning-optional decision --- archivist/user-stories.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/archivist/user-stories.md b/archivist/user-stories.md index bd1559b..1ac074f 100644 --- a/archivist/user-stories.md +++ b/archivist/user-stories.md @@ -12,9 +12,9 @@ so that the container starts with no configuration file for infrastructure and s Acceptance criteria: -- Given the container starts with all mandatory variables set (`ARCHIVIST_S3_ENDPOINT`, `ARCHIVIST_S3_ACCESS_KEY`, `ARCHIVIST_S3_SECRET_KEY`, `ARCHIVIST_S3_BUCKET`, `ARCHIVIST_ADMIN_EMAIL`, `ARCHIVIST_ADMIN_PASSWORD`), when the application starts, then it connects to the S3 server, verifies the bucket is reachable and versioned, and starts serving HTTP on the configured port. +- Given the container starts with all mandatory variables set (`ARCHIVIST_S3_ENDPOINT`, `ARCHIVIST_S3_ACCESS_KEY`, `ARCHIVIST_S3_SECRET_KEY`, `ARCHIVIST_S3_BUCKET`, `ARCHIVIST_ADMIN_EMAIL`, `ARCHIVIST_ADMIN_PASSWORD`), when the application starts, then it connects to the S3 server, verifies the bucket is reachable, and starts serving HTTP on the configured port; when bucket versioning is disabled, a warning is logged recommending the user to enable it to reduce the risk of losing a file to a bug (the application starts anyway). - Given an optional variable is not set, when the application starts, then it uses its documented default (`ARCHIVIST_S3_USE_SSL=true`, `ARCHIVIST_POLL_INTERVAL=* * * * *`, `ARCHIVIST_HTTP_PORT=8090`). -- Given a mandatory variable is missing or the S3 server is unreachable or the bucket is not versioned, when the application starts, then it exits with a non-zero code and a single explicit error message in the logs naming the faulty variable or resource. +- Given a mandatory variable is missing or the S3 server is unreachable, when the application starts, then it exits with a non-zero code and a single explicit error message in the logs naming the faulty variable or resource. - Given the admin account variables are set, when the application starts for the first time, then the PocketBase admin account is created with these credentials; on subsequent starts it is left unchanged unless the password differs, in which case it is updated. ### US-02 — Load and validate the functional configuration @@ -106,7 +106,7 @@ so that the same file never enters the pipeline twice. Acceptance criteria: - Given an eligible candidate, when it is downloaded, then it is streamed in memory with no disk write and its sha256 is computed on the fly. -- Given the computed sha256 matches an existing `documents` record, when the download completes, then the `inbox/` key is deleted (versioned delete marker), the duplicate is logged in the application logs only (no `document_events` entry, by design), and processing stops for that object. +- Given the computed sha256 matches an existing `documents` record, when the download completes, then the `inbox/` key is deleted (a no-data-loss case — the original with the same content stays filed; with versioning enabled the deleted copy is additionally recoverable via delete markers), the duplicate is logged in the application logs only (no `document_events` entry, by design), and processing stops for that object. - Given the sha256 is new, when the download completes, then processing continues to extraction. ### US-13 — Extract the text page by page @@ -172,7 +172,7 @@ Acceptance criteria: - Given a valid verdict, when filing runs, then the object is copied to `files/` + rendered template (conflict suffix applied if needed), the target existence is verified, and only then is the `inbox/` key deleted; the record's `file_key` is updated to the final, conflict-resolved key. - Given an invalid verdict, when filing runs, then the object is moved to `pending/` with an incremental suffix on name conflict, and the record's `file_key` is updated. - Given a copy or delete fails mid-filing, when the pass ends, then the recovery of US-11 picks the document up on the next poll. -- Given any deletion, when it executes, then it relies on bucket versioning: the data remains recoverable via delete markers. +- Given any deletion, when it executes, then it is final unless bucket versioning is enabled, in which case the data remains recoverable via delete markers. ## Epic: Data visualization (standard PocketBase UI)