From 86185c422a6ed7b9682cc4337d5cdf157901f3f6 Mon Sep 17 00:00:00 2001 From: Alberto Balbo Date: Tue, 3 Nov 2026 16:01:07 +0100 Subject: [PATCH] docs: phase 5a in BRIEF, DECISIONS, CHANGELOG, STATUS and ARCHITECTURE Co-Authored-By: Claude Opus 5.5 --- docs/ARCHITECTURE.md | 19 +- docs/BRIEF.md | 219 ++++++++++++++++++++- docs/CHANGELOG.md | 71 +++++++ docs/DECISIONS.md | 56 +++++- docs/STATUS.md | 20 +- docs/requests/2026-10-26-owner-review-2.md | 4 +- 6 files changed, 359 insertions(+), 30 deletions(-) diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index 62655b12..4c77b59e 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -55,14 +55,14 @@ Dependencies point one way: `Core` ← `Core.Windows`, `Data`, `Protocol` ← `S |---|---| | `Sqlite`, `Postgres` | SQLite P/Invoke binding (winsqlite3 / libsqlite3), in-house PostgreSQL wire protocol v3 client with pool and LISTEN | | `Migrations/{sqlite,postgres}/NNNN_name.sql` | Embedded, applied in one transaction at open (`MigrationRunner`) | -| `Repositories` | `ChronosDatabase` facade: archives, sequences, frames, tags, renders, jobs, cards, users, tokens, uploads, render nodes, settings, audit, schedules (`ScheduleRepository`: system rows seeded without overwriting edits and never deleted, the compare-and-set claim of a run), tombstones of removed photos (`FrameRemovalRepository`, `frame_removals`, written from the sidecar's `removed` list), `SequenceRepository.GetStampAsync` (a digest of what a Reorganize plans from in the index) and `GetConvertStampAsync` (with what a conversion plans from: its photos' count, sizes, formats, pixel sizes and the flags that decide), `JobRepository.ListPendingTargetsAsync` (the targets of pending jobs of a kind, also of those created before a time), `RenderRepository.RebaseFolderAsync` (the export paths that follow a moved folder); projects and their versions (`ProjectRepository`, `projects`, `project_versions`: rows derived from the projects' sidecars, a head advanced by compare-and-set, Main's last mirror); `DatabaseBackups` (`VACUUM INTO` copies of an SQLite index into `backups` next to it, every copy keeping as many as the backup schedules keep (`KeptAsync`), the newest copy that seeds the `index-backup` schedule (`Newest`, `SystemSchedule.LastDone`), restore staged for the next start and carried out before the index opens, so it also recovers one that no longer opens) | -| `Jobs` | `JobEngine` (one job at a time; reviews the priority queue and makes a lower running job yield, requeued with its checkpoint; no history purge, the housekeeping schedule's clean-up does it), `JobPriorityQueue` (a level per job kind, the claim order, settings round trip), `IJobHandler`, `IJobHandlerProvider`, `JobContext` (progress, checkpoints, follow-up jobs that never interrupt their parent), `JobThroughput`/`JobEta` (rate and bounded time left) | +| `Repositories` | `ChronosDatabase` facade: archives, sequences, frames, tags, renders, jobs, cards, users, tokens, uploads, render nodes, settings, audit, schedules (`ScheduleRepository`: system rows seeded without overwriting edits and never deleted, the compare-and-set claim of a run), tombstones of removed photos (`FrameRemovalRepository`, `frame_removals`, written from the sidecar's `removed` list), `SequenceRepository.GetStampAsync` (a digest of what a Reorganize plans from in the index) and `GetConvertStampAsync` (with what a conversion plans from: its photos' count, sizes, formats, pixel sizes and the flags that decide), `JobRepository.ListPendingTargetsAsync` (the targets of pending jobs of a kind, also of those created before a time), `RenderRepository.RebaseFolderAsync` (the export paths that follow a moved folder); projects and their versions (`ProjectRepository`, `projects`, `project_versions`: rows derived from the projects' sidecars, a head advanced by compare-and-set, Main's last mirror); `JobRepository.ListPendingAsync` (the queued, running and paused jobs of a kind and target, full rows); `FrameRepository.CountNamedAsync` (hashed frames and a checksum of their hashes, for a home's frames stamp); `DatabaseBackups` (`VACUUM INTO` copies of an SQLite index into `backups` next to it, every copy keeping as many as the backup schedules keep (`KeptAsync`), the newest copy that seeds the `index-backup` schedule (`Newest`, `SystemSchedule.LastDone`), restore staged for the next start and carried out before the index opens, so it also recovers one that no longer opens) | +| `Jobs` | `JobEngine` (one job at a time; reviews the priority queue and makes a lower running job yield, requeued with its checkpoint; no history purge, the housekeeping schedule's clean-up does it), `JobPriorityQueue` (a level per job kind, the claim order, settings round trip), `IJobHandler`, `IJobHandlerProvider`, `JobContext` (progress, checkpoints, follow-up jobs that never interrupt their parent), `JobThroughput`/`JobEta` (rate and bounded time left), `ICancelledJobHandler` (a handler's clean-up after a cancel: `JobEngine.CancelAsync` calls it for a paused or failed job no handler runs, and waits first for a paused job's run that has not ended) | | `Scheduling` | `Scheduler` (one per host: seeds the host's system schedules, claims due runs by compare-and-set, catch-up, clock changes, create/edit/reset/delete/run now as API v1 DTOs), `ScheduleRecurrence` (the in-house `every:`/`daily:`/`weekly:`/`monthly:` form, wall-clock times across DST), `ScheduleActions` (action names, parameters, availability, the archive jobs a run queues), `IScheduleHost` and `SystemSchedule` (what the server and the desktop supply), `ScheduleOutcome`, `ScheduleMapping` (model ↔ DTO) | | `Housekeeping` | `BackupJobHandler`, `CleanupJobHandler`, `ICleanupStep` with the shared steps (`CleanupSteps`: job history, audit log, trash report that never deletes); hosts add their own steps through `ArchiveServiceOptions.CleanupSteps` | | `Archiving` | `ArchiveService` (create/adopt/open, archive settings written to `archive.json` then the index, `ArchiveSettings.CheckTemplates` and `TemplateRuleException` holding a template given anew to the template rules; `UnderLeaseAsync`: a write under a sequence's lease with its row read under it), `ArchiveIndexer` (scan, rebuild; a sequence found in another folder takes its exports' paths along; a full scan or a rebuild takes the projects' sidecars back too), `ArchiveIngest` (uploads and imports, named through `FrameNaming`; content a conversion replaced is a duplicate of the frame holding its conversion; a restore or a replacement not settled yet refuses the batch), `ImportService`, `ArchiveVerifier`, `ArchiveImages` (thumbnail and proxy passes, several photos at once through `OrderedWork`, which hands results back in frame order), `FrameTiers` (decode tier, `PreviewOnly`/`Undecodable` flags and preview size of frames, written to sidecar and index by the light analysis, deep analysis, renders and image passes), `GprCompanions` (the JPEG of each GoPro GPR, found in the index when an import kept it in another sequence), `ArchiveMaintenance` (also a conversion job's staging and journals, by the job's state; those of a job this index does not know go together, by age), `MassRenamer` (mass rename and Reorganize: the dry run reads each sidecar for a file template; each step checked under its leases before anything of it moves (where its sequences are, what is inside and at its new folder, a sidecar of a newer format, the title it was planned from when it changes it or names the folder or files after it), then the folder, with the sequences of the plan an earlier step left as they were inside it (taken along, their title and file names kept), every index row (the frame paths and render paths of the exports inside it, a file or an image-sequence folder, its own unless the export is still at the old place and another sequence's when it moved with it, follow it in one transaction; a sidecar that cannot be read or written then still has its row follow, and fails the step), then the files under the plan's journal in `journal/` (a sequence whose photos changed since, such as one still receiving them, or whose files are found changed or in use or have their new names taken keeps its file names, the renames being pinned by digest, and the step and the plan go on); the journal keeps the tally of the whole plan, and a plan its job held (paused, cancelled or failed) is left to that job, only its half-done file renames completed at an archive open, which completes any other plan an interruption left and tells each sequence changed; the file renames of a step: sidecar, a sequence whose sidecar cannot be read staying as it is with every folder around it, index (`FrameRepository.RenameFilesAsync`) and the sequence's journal), `SequenceFolders` (`Holds`: the folder the index has for a sequence is there and its sidecar names no other sequence; every writer into a sequence's folder asks it), `SequenceTrash` (delete into the archive's hidden trash with a dry run, restore; the folder moves back when the index step fails; lists sequence and photo entries; `SequenceTrash.Empty`: the emptying's dry run, fingerprint and erase, each entry checked against its fingerprint again under its lease, `TrashKept` with its `TrashKeptReason` for each entry kept; `SequenceTrash.Replaced`: where a replaced entry's conversions are, read from the archive's sidecars (in the index's or the entry's folder, in the trash, else by one `SidecarWalk` of the archive per dry run or emptying) through their replaced tombstones, a conversion deleted only on the archive's word (a tombstone, the trash, or an `ErasureRecord` in `trash/.erased/`, written when an emptying erases a deleted sequence a replaced entry still needs), `TrashEntry.ConversionDeleted` in the dry run and its fingerprint, the erase weighed under the entry's and the sequence's leases once the sequence is settled; `BusyAsync`: what running and paused jobs hold, but the job asking, from `JobRepository.ListHoldsAsync`), `FrameTrash` (photos of a sequence into `trash/photos` with a dry run, a journal that undoes an interrupted deletion whose entry stays unlisted until its sidecar is written, tombstones (a photo never hashed is hashed as it goes; one whose original is missing goes without a file or tombstone; a frame that stays and may be a twin is hashed, its hash kept), positions parked and placed back, proxies and thumbnails moved to follow their frames; `FrameTrash.Restore`: restore re-hashes each file and says why each kept photo stayed (`KeptReason`), under a journal of its own into the sequence that another writer settles only under the entry's lease, into a new sequence through the ingest when theirs is gone, each original staged inside its own entry and the record rewritten after each photo filed; a replaced entry swaps back while its converted frames are unchanged (`SwapBackAsync`); `FrameTrash.Replace`: the files of frames swapped in place, same ids and indices, the old files into one `Replaced` entry with their replacements' hashes, a copy of `analysis.json` and the job's id, the incoming files named never onto a file there, tombstones aliasing old content to new, under `.chronos/replace.pending.json` (its phase and the new names: the next writer completes it when the sidecar lists them, else undoes it; `EnsureReplaced`: the writers of a sequence's frames wait for one not settled); `ReplaceMissingAsync`: a frame missing here takes its photo back in another encoding, nothing to the trash; `FollowUps`: the passes a swap cleared), `MassConverter` (conversion's dry run: busy sequences (running and paused jobs, pending conversions), offline and unreadable ones, the space against `ArchiveServiceOptions.FreeSpace` for the archive root and its staging folder; `QueueAsync`: a confirmed plan's job queued under a process lock, its confirmed photos written first into `journal/convert-.photos` (`ConfirmedPhotos`) under the job's id, a second conversion of its sequences refused, `ConversionQueuedException`; the job, a sequence at a time: under its lease, settled, planned again and held to the confirmed photos (`Confirmed`, `Held`), pinned in `journal/convert-.pins` (`PinLog`); stage A converts into `staging/convert-/` with `OrderedWork`, the space watched before each photo, counting every photo still being written (`SpaceWatch`), each staged file appended to `journal/convert-.staged` (`StagedLog`); stage B per sequence, all or nothing: replace through `FrameTrash.ReplaceAsync` (the sequence's folder read again under its lease, as every writer does), or a new sequence through the ingest with the source's tags, rating, notes and project (a retry finishes the copy the journal names; a source another done conversion copied since is `Superseded`); `ConvertJournal` (`convert-.json`: each sequence's outcome and whether its passes were queued); each sequence replaced or made told, and its passes queued, as it completes), job handlers | | `Processing` | `ProcessingService`, `SequenceAnalyser`, `DeepReports` (a saved deep report while it still describes the frames), `SequenceRender`, `ProjectStore`, `ProjectBundles` (a `.chronos` file for a sequence, and the sequence a file names), `RenderNodeClient`, job handlers | -| `Projects` | `ProjectService` (`ArchiveService.Projects`: the projects of this PC's sequences as a home, under the sequence's lease and only in a folder that holds the sequence (`SequenceFolders.Holds`; otherwise `SequenceFolderMovedException`: reads answer from the index, writes are refused): list, create, rename, delete into `projects/.trash`, history, push with fast-forward / idempotent repeat / divergence / hash and portability checks; each call first catches up: the sidecars into the index (`ProjectIndexer`, also run by full scans and rebuilds; a version file a push left past its record adopted, a stray one moved to `versions/.stray`), Main made from the sequence's settings, settings another path wrote appended to Main as an `external` version, a mirror a crash cut short completed or merged; a push to Main mirrored into `project.json` and the settings with the settings version check), `ProjectSidecars` (record and immutable version files, the settings as a JSON string checked against their hash), `ProjectMerge` (three-way merge member by member, pending frames merged photo by photo, conflicts, `Replay` of local commits on a moved head), `IProjectHome` and `ArchiveProjectHome` (the home a workspace pushes to and pulls from, a project or version the index lacks looked for in the sidecars first; the server's comes in phase 5b), `HomePhotos` (a sequence's photos as positions name them, with the encodings its Replaced tombstones join) | -| `Workspaces` | `WorkspaceStore` (a folder outside the library: `workspace.json`, one folder per project, no index), `WorkspaceProject` (`project.chronos` working state, `media/` with `media.json`, `proxies/.jpg` and `analysis.json`, `versions/`, `sync.json` for a restore or a conflict, `exports/`, the lease `.lock.lease`), `WorkspaceSync` (checkout, open, save, commit, push, pull with replay and merge, conflicts settled by keep mine, take server or save both, restore, status), `WorkspaceCopyJobHandler` (`WorkspaceJobs.Copy`, registered by the desktop only: the archive only read, from a folder that holds the sequence; a workspace inside a library refused; the archive's current proxies copied, the others made in the workspace, each hash-verified, resumable from a checkpoint of its frames version; the encodings conversions joined kept in `media.json`; the working state's positions moved by frame where frames stay, by photo where they came or went) | +| `Projects` | `ProjectService` (`ArchiveService.Projects`: the projects of this PC's sequences as a home, under the sequence's lease and only in a folder that holds the sequence (`SequenceFolders.Holds`; otherwise `SequenceFolderMovedException`: reads answer from the index, writes are refused); reads wait 3 s for the lease, then answer from the index; a read-only archive is read without writing (an index-only Main written back once it takes writes): list, create, rename, delete (the folder into `projects/.trash` first, then the deleted record; never Main), history, head (NotFound once deleted), `StoredAsync` (a version file read back and checked), push with fast-forward / idempotent repeat / divergence / hash, portability, strict format and 64 MiB checks; each call first catches up: the sidecars into the index, Main made from the sequence's settings, settings another path wrote appended to Main as an `external` version or, with a push whose mirror was cut short, merged into one `merge` version where they win, a mirror never written over `project.json` settings it has not taken in (`MovedSharedAsync`), records behind the index healed (`HealAsync`, `UpdatedAfter`), projects the archive lost written back (`WriteBackAsync`); a push to Main mirrored into `project.json` and the settings with the settings version check), `ProjectIndexer` (the reconcile, also run by full scans and rebuilds: the projects' trash read before the live folders, so a deletion wins and the live folder's late version files move beside it; a record that cannot be read held back, never taken for a deletion; a lost record written again from the index only once its folder settled (`RecordSettle`, 2 minutes) and no trash folder holds it back (`TrashRecordGrace`, 1 day); a creation cut before its record left as it is; a version file a push left past its record adopted, a stray one moved to `versions/.stray`; `BehindAsync`, one rule for a record behind the index; `SettleMainAsync` and `SwapMainAsync`, one Main from the records, passed in one transaction), `ProjectSidecars` (record and immutable version files, the settings as a JSON string checked against their hash, `MaxVersionBytes` 64 MiB refused before writing), `ProjectMerge` (three-way merge member by member, pending frames merged photo by photo, conflicts, `Replay` of local commits on a moved head; `NewerSettingsException` rather than merge a newer format), `IProjectHome` and `ArchiveProjectHome` (the home a workspace pushes to and pulls from: `HoldsAsync` reads a version back, `FramesStampAsync` says when the frames changed, an offline archive or busy lease is `HomeUnavailableException`; the server's comes in phase 5b), `HomePhotos` (a sequence's photos as positions name them, with the encodings its Replaced tombstones join) | +| `Workspaces` | `WorkspaceStore` (a folder outside the library: `workspace.json` written atomically, one folder per project, no index; a leftover folder holding only stale lease files removed on listing), `WorkspaceProject` (`project.chronos` working state, `media/` with `media.json`, `proxies/.jpg` (and `-.jpg` while a copy replaces one) and `analysis.json`, `versions/` with `.replaced` (versions set aside, pruned by age and count) and `.replaced.since`, `sync.json` for a conflict, a restore or the journal of a replay or a Save both, `exports/`, the lease `.lock.lease`; `UnreadableVersions`), `WorkspaceMedia` (`NamedAsAt`: the media learn the home's hashes and aliases), `WorkspaceSync` (checkout, open under the lease, save, commit, push, pull with replay and merge, the base in `project.chronos` as every write's commit point, `SettleAsync` finishing or undoing a cut push, replay or Save both, conflicts settled by keep mine, take server or save both only as shown, restore, status with Gone, Damaged and `MediaOutdated`, the home's frames read again only when their stamp moved), `WorkspaceCopyJobHandler` (`WorkspaceJobs.Copy` and `CopyFactsAsync`, registered by the desktop only: the archive only read, from a folder that holds the sequence; a workspace inside a library refused; the archive's current proxies copied, the others made in the workspace, each hash-verified, resumable from a checkpoint of its frames version and folder, free space checked against its estimate plus 512 MiB; the encodings conversions joined kept in `media.json`; the working state's positions moved by frame where frames stay, by photo where they came or went; a cancelled first copy's media cleared under the project's lease only when no other copy of the project waits or runs, through `ICancelledJobHandler` too) | | `Sync` | `SyncService` (sync table of one server: compare, link by content through the aliases, settle conflicts, enqueue transfers), `SyncRules` (status, settings merge and differences, the proxies this PC can send, aliases followed; no I/O), `SyncTombstones` (photos either side removed are not offered back; the replaced tombstones of both sides join the encodings of one photo, union-find, each compared as the smallest SHA-256 among them, a deletion covering them all; immutable once made), `SyncPositions` (the settings' frame positions translated by photo to the frames of the copy they go to), `SyncLinkStore` (`sync_links`, `sync_state`), `SyncTransfers` and `SyncJobHandler` (resumable, hash-verified uploads and downloads as jobs; downloads commit through the archive ingest, and a frame missing here whose photo the server holds in another encoding takes that file through `FrameTrash.ReplaceMissingAsync`; job log lines from the catalog), `SyncAgent` (background comparison, server events, backoff, offline proxies), `ProxyCache` and `RemoteSequence` (server sequences opened with proxies), `ISyncRemote` (the server calls; `ChronosSyncRemote` over `ChronosClient`) | ### 2.3 Chronos.App areas @@ -72,8 +72,8 @@ Dependencies point one way: `Core` ← `Core.Windows`, `Data`, `Protocol` ← `S | `Shell` | `MainWindow` (rail and its shortcuts, taskbar progress), `ShellViewModel` (rail, sections, first run), `OsNotifications` (toasts as Windows notifications while the window is minimised or in the background), dialogs, `ErrorText` (the sentence of an error toast), `ScreenCapture` (`--capture` scenes), `SectionTemplates.xaml` (view model → view) | | `Sections` | One `XxxView.xaml` + `XxxViewModel` per screen: Welcome, Library, Sequence (the Edit section: the editor, `SequencePickerView` choosing in place a project of the workspace or a sequence of the library, the in-window dialogs of the workspace, and the opening of this PC's sequences as workspace projects: the project opened last, else "Open in workspace", the checkout and the copy job followed until it opens), Import, Archive, Jobs (two tabs, Queue and Scheduled: `SchedulesView` shows `Jobs/SchedulesViewModel`), Server, Settings (its last page is About) | | `Library` | Filter, facets, pager, timeline, saved views, quick and mass actions (`MassActions`: Reorganize and Convert for the sequences of one archive), remote cards and thumbnails, thumbnail cache, list export | -| `Editor` | `EditorSession` (project, undo/redo, saving, merges through `Data/Projects/ProjectMerge`), `ISequenceSource` (`LocalSequenceSource`, `RemoteSequenceSource`, `WorkspaceSequenceSource`: a workspace project over its media, the working state saved in `project.chronos` under the project's lease and merged, renders at the home with the portable settings through `IProjectRenders`), the steps of the Edit path (`EditPath`: their order, each step's state, the step of each finding, the memory of the step shown; tabs Analysis, Frames, Exposure, Motion, Camera, Time, Stack, Export), `PreviewRenderer`, `ExportPlanner`, `ExportSync`, `SavedCopies`, `SequenceJobs`, `ProjectFiles` (save and open `.chronos` project files: format 2 opens its workspace project, format 1 gives its settings to Main) | -| `Workspace` | Owner review 2, R8: `WorkspaceHost` (the desktop's `WorkspaceStore` and `WorkspaceSync` over Settings › Workspace's folder, this PC's archive as the home; checkout and copy, status, Save version with the sync after it, sync, resolve, restore, history, new, rename, delete, the plan and removal of a local copy whose unsent work goes to `/.trash`, pruning past Kept versions), `ProjectMenuViewModel` (the title's ▾: state chip, the menu, Update media; `IWorkspaceUi` is what it asks of the section), `WorkspaceDialogs` (Open in workspace, project name, Save version, History, conflict, Remove local copy; `WorkspaceDialogs.xaml`), `WorkspaceProjectItem` (a picker row), `WorkspaceText` (states, versions, failures) | +| `Editor` | `EditorSession` (project, undo/redo, saving, merges through `Data/Projects/ProjectMerge`), `ISequenceSource` (`LocalSequenceSource`, `RemoteSequenceSource`, `WorkspaceSequenceSource`: a workspace project over its media, the working state saved in `project.chronos` under the project's lease and merged photo by photo in the portable form (`Merge`, a setting both sides changed asked through `ProjectConflictException`), `ReadOnlyChanged` for a project of a newer Chronos, an unstored edit kept aside in `versions/.replaced` (`SetAsideAsync`), renders at the home with the portable settings through `IProjectRenders`, naming a version only while none waits to be sent), the steps of the Edit path (`EditPath`: their order, each step's state, the step of each finding, the memory of the step shown; tabs Analysis, Frames, Exposure, Motion, Camera, Time, Stack, Export), `PreviewRenderer`, `ExportPlanner`, `ExportSync`, `SavedCopies`, `SequenceJobs`, `ProjectFiles` (save and open `.chronos` project files: format 2 opens its workspace project, format 1 gives its settings to Main) | +| `Workspace` | Owner review 2, R8: `WorkspaceHost` (the desktop's `WorkspaceStore` and `WorkspaceSync` over Settings › Workspace's folder, this PC's archive as the home; checkout and copy with its size and free space, status, Save version with the sync after it, sync, resolve, restore, history, open, new, rename, delete, the plan and removal of a local copy whose files but the media go to `/.trash` (put back whole when a move fails), pruning past Kept versions after `HoldsAsync`, copies a newer Chronos wrote or that cannot be read listed as such and never changed, a folder inside a library refused, `PlanFolderAsync` and `UseFolderAsync`), `WorkspaceFolderChange` (Settings › Workspace › Change… and the refused folder's Choose folder), `ProjectMenuViewModel` (the title's ▾: state chip read again after edits, the menu, Update media; `IWorkspaceUi` is what it asks of the section, `ShowDialogWhenFree` holding a background conflict until the open dialog closes), `WorkspaceDialogs` (Open in workspace with unreadable projects listed disabled, project name, Save version, History, conflict, a format conflict offering only Save both, Remove local copy with its typed confirmations; `WorkspaceDialogs.xaml`), `WorkspaceProjectItem` (a picker row), `WorkspaceText` (states, versions, authors, failures) | | `Import` | `CardPool` (inserted cards, remembered cards, folders), camera profiles, plans and choices, destinations (archive, folder, server through `ServerImportSink`), card actions (verified delete, format, eject) | | `Archive` | `CurrentArchive`, `ArchiveTree`, figures for the charts, maintenance reports, Reorganize (`ReorganizeDialogViewModel`: folder, file and title templates each with its switch, the dry run, Apply queues the `move` job of that plan; `ReorganizePlans`: each template's check, the plan as rows and a summary; `ReorganizeOffer`: per archive, the templates Settings › Archive's toast offers, joined while that archive's toast is up), Convert (`ConvertDialogViewModel`: format, JPEG quality and a mode chosen at every run, the dry run made once per format and quality, Apply behind the mode's confirmation queues the `convert` job of that plan through `MassConverter.QueueAsync`; `ConvertPlans`: the plan as rows in the mode's words, a summary, the space line, the Replace confirmation that types the number of photos and the New sequence one that counts the photos not copied; `ConvertUndo`: the Undo the Jobs screen's toast offers when Replace conversions end, which restores the `Replaced` trash entries their jobs made, by the job's id), retag, delete and trash dialogs (`SequenceDeletion`, `DeletePlans`, `TrashEmptyPlans`: Empty… behind a dry run and a typed confirmation, every entry whose conversion was deleted named first), `ArchiveFailures` | | `Server` | `ServerSession`, `ConnectFlow` (trust on first use), `SyncHost` (sync engine, agent, metered hold, editor connections, Export Sync), sync table, `RemoteSequenceApi` | @@ -121,7 +121,7 @@ Dependencies point one way: `Core` ← `Core.Windows`, `Data`, `Protocol` ← `S | `EmptyTrash` | `Archiving/Jobs/EmptyTrashJobHandler` (erases exactly a confirmed plan's trash entries; refuses a stale fingerprint) | yes | yes | | `Move` | `Archiving/Jobs/MoveJobHandler` (Reorganize, `MoveJobParameters`: the templates, the sequences and the confirmed fingerprint; plans again from the templates, applies the plan only while it is the one confirmed, holds it when paused, cancelled or failed, keeps it while the archive is offline, tells each sequence changed as its step completes) | yes | yes | | `Convert` | `Archiving/Jobs/ConvertJobHandler` (mass conversion through `MassConverter`, `ConvertJobParameters`: the target, quality and mode, the sequences with their frames version and the digest of the photos confirmed, whose ids wait in `journal/convert-.photos`, and the fingerprint; targets are the sequences; settles what a crash left, refuses short space, converts each sequence all or nothing, the confirmed photos alone, resumes from its journal, tells each sequence `converted` or `created` and queues the passes it needs as it completes) | yes | yes (formats and files the server cannot decode natively are skipped: convert on a PC) | -| `WorkspaceCopy` | `Workspaces/WorkspaceCopyJobHandler` (via `WorkspaceJobs.CreateHandlers`: a sequence's proxies and deep report into a workspace project's media; originals refused until phase 5c) | yes | no: it writes into the folder its parameters name | +| `WorkspaceCopy` | `Workspaces/WorkspaceCopyJobHandler` (via `WorkspaceJobs.CreateHandlers`: a sequence's proxies and deep report into a workspace project's media, high in the priority queue by default; its cancel clean-up as an `ICancelledJobHandler`; originals refused until phase 5c) | yes | no: it writes into the folder its parameters name | | `Adopt` | none: done synchronously (`ArchiveService` actions) | — | — | A job engine claims only kinds it has handlers for. Light analysis is queued by the engine (`JobContext` follow-up) @@ -182,7 +182,10 @@ replayed on them (`ProjectMerge.Replay`) and the working state merged, and setti conflict for the user. Main's head is the sequence's own settings (mirrored both ways), so analyses, the Library's quick renders and server sync keep reading `project.json` and the index's settings; other projects never leave their home. The desktop's Edit opens only workspace projects (`App/Workspace`): it edits their working state, and a render of one runs -at the home with its portable settings, recording the project and the version. +at the home with its portable settings, recording the project and the version. The archive's sidecars stay the truth: a +deletion is taken only from the projects' trash, read first, a record that cannot be read holds its project back, and the +index heals the records it is ahead of. In a workspace the base in `project.chronos` is the commit point of every +write, so a cut push, replay or Save both is finished or undone by the next sync (`SettleAsync`). Sync (desktop ↔ server, BRIEF §14.5) reuses the same paths: `SyncService` compares the local index with the server's listing (settings and tags carry version counters), uploads go through the chunked protocol into the server's diff --git a/docs/BRIEF.md b/docs/BRIEF.md index 0873c56d..68b91fef 100644 --- a/docs/BRIEF.md +++ b/docs/BRIEF.md @@ -283,6 +283,17 @@ sequence manifest atomically (write temp → fsync → rename). | Server-connected | server archive; local proxies/thumbs cache | server DB via API; local SQLite caches only | server (managed formats), render nodes (MP4), or this PC after downloading originals | | Mixed | both; each sequence has an `origin` and a `sync state` | both | as above | +Workspace and projects (amended 2026-10-26, R8). The desktop edits in a **workspace**, a folder +on a fast disk outside every library (default `%LOCALAPPDATA%\Chronos\workspace`, or +`.\data\workspace` for a portable copy), never inside the library. A sequence's **home** is +where it lives: this PC's archive (phase 5a) or a server (phase 5b). The home keeps the +sequence's **projects**: Main, which is the sequence's own settings, and other named sets of +edits ("4K landscape", "Vertical social"), each with a linear history of versions pushed and +pulled like git, with no branches. The workspace holds a working copy of a project: its +working state, its versions and the sequence's proxies (originals from phase 5c). Final +renders run where the originals are. A local-only library works the same way, its archive +being the home. + --- ## 5. Domain model @@ -303,7 +314,23 @@ Primary entities (identical concepts in SQLite and PostgreSQL; ids are UUIDv7 st preview info (offset/length), light stats (mean log-luminance, clip fractions) once analysed, flags (missing, corrupt, duplicate, excluded). - **Render** — id, sequence id, preset name, settings JSON, output relative path, codec, - width, height, fps, duration, bytes, created, produced by (client id / server / node). + width, height, fps, duration, bytes, created, produced by (client id / server / node), + project id and project version id (the project and version rendered, the version only + when the home holds it with the settings rendered; amended 2026-10-26, R8). +- **Project** (amended 2026-10-26, R8) — id, sequence id, name (1–60 characters, unique + among the sequence's live projects), is main (one live Main per sequence), head version + id and number, mirrored version id and mirrored settings version (Main: the version and + the settings version of its last mirror into the sequence's settings), created by, + created, updated, deleted. Derived from the project's sidecars (§7) and rebuilt from them. +- **ProjectVersion** (amended 2026-10-26, R8) — id (UUIDv7 made by the client), project + id, parent id, number (1…, unique per project), kind (commit, merge, restore, imported, + external), author, client name, note, settings JSON in the portable form (every frame + position parked by photo, canonical text, stored as text and never re-encoded), content + hash (SHA-256 of that text's UTF-8 bytes), settings format, frames version, restored + from, created, stored (when the home took it; none while only a workspace has it). + Immutable once stored. +- **Workspace** (amended 2026-10-26, R8) — no table: a folder that describes itself + (`workspace.json` and one folder per project, §12.3). - **Job** — id, kind (scan, rebuild, verify, light-analyse, deep-analyse, proxies, thumbs, render, import, upload-commit, maintenance; backup, cleanup, and the read-only duplicates and orphans reports; empty-trash, stored as 18, which erases exactly the trash @@ -313,7 +340,9 @@ Primary entities (identical concepts in SQLite and PostgreSQL; ids are UUIDv7 st and holds the rest of it when paused, cancelled or failed: amended 2026-10-26, R7; convert, stored as 19, a conversion of exactly the photos a confirmed plan lists, its targets the sequences, each converted all or nothing into its own frames or a new sequence: amended - 2026-10-26, R7), target ids, state (queued, running, paused, done, failed, cancelled), + 2026-10-26, R7; workspace-copy, stored as 20, the copy of a sequence's proxies and deep + report into a workspace project's media, run by the desktop only: amended 2026-10-26, R8), + target ids, state (queued, running, paused, done, failed, cancelled), progress (done/total, fps, eta), log tail, created by, node id, attempts, error, schedule id (the schedule that queued it; amended 2026-10-26, R10). - **Schedule** (amended 2026-10-26, R10) — id, system key (set, and unique, on a host's @@ -348,7 +377,9 @@ Indexes: `frame(sequence_id, index)`, `frame(sha256)`, `frame(captured_at)`, `sequence(archive_id, first_capture)`, `sequence(camera_model)`, tags, jobs by state and by schedule, `schedules(enabled, next_run)` (amended 2026-10-26, R10), `frame_removals(sequence_id, sha256)` (the key) and `frame_removals(sha256)` (migration 0008; -amended 2026-10-26, R6). +amended 2026-10-26, R6), `projects(sequence_id, name)` and `projects(sequence_id)` where +Main, both on live rows only, `project_versions(project_id, number)` (migration 0009, with +`renders.project_id` and `renders.project_version_id`; amended 2026-10-26, R8). Paging everywhere (keyset pagination on `(first_capture, id)`). --- @@ -437,7 +468,8 @@ The archive is the source of truth; the database is an index that can be rebuilt │ └── .chronos/ │ ├── sequence.json sidecar manifest (below) │ ├── analysis.json full deep-analysis report -│ ├── project.json render settings (the "project") +│ ├── project.json render settings (the "project"; Main's head, below) +│ ├── projects/ /project.json + versions/000001-.json …; .trash/: deleted projects (below; amended 2026-10-26, R8) │ ├── thumbs.pack packed thumbnails (one file per sequence, indexed; avoids 100k tiny files on SMB) │ ├── rename-files.json the file renames of a Reorganize a crash interrupted (below; amended 2026-10-26, R7) │ └── *.pending.json journals of an ingest, a photo deletion, a frame replacement (replace.pending.json, a conversion or its undo; amended 2026-10-26, R7) or a restore a crash interrupted (below) @@ -595,6 +627,49 @@ moves each original into the trash, New sequence leaves it where it is. job this index does not know (another host's on a shared archive) keeps both while any of their files was written within 90 days, then both go. +Projects (amended 2026-10-26, R8; §5, §12.3, §14.5). A sequence's projects live in its +`.chronos/projects/`, and the sidecars are the truth: a full scan or a rebuild takes them +back into the index, and every project operation first brings the index in line with them, +under the sequence's lease (a read waits at most 3 s for it, then answers from the index). +- `/project.json` is the record (`chronos-project-record` v1: id, sequence id, + name, is Main, head `{id, number}`, `mirrored` `{id, number}` for Main, created, created + by, updated, deleted). Its `updated` time never goes back: each write stamps now or 1 ms + past the record it replaces. Older builds ignore `mirrored`. +- `/versions/000001-.json` holds one immutable version + (`chronos-project-version` v1), its settings as a JSON string checked against its content + hash. A version file is at most 64 MiB, refused before it is written. A version is + written first, then the record, then the index in one transaction; a version file past + its record that follows the head is adopted, any other moved to `versions/.stray`. + Nothing is ever deleted. +- A deletion moves the project's folder into `projects/.trash/-`, then writes + the deleted record there. Main cannot be deleted. The projects' trash is never emptied + by Chronos (Empty trash does not see it); it leaves with its sequence's folder. +- A deletion is never inferred from a missing folder or a record that cannot be read: only + a record that says deleted, or a folder in the projects' trash, deletes. The trash is read + before the live folders, so a deletion is never undone; a version another PC pushed into + the live folder before the deletion reached it is moved beside the deleted record, into + the trash folder's `versions/`, never deleted. A record that cannot be read holds + its project back: listed as the index has it, nothing written for it, writes refused + until it reads again. +- Main mirrors the sequence's settings: its head is written to `project.json` and to the + index's settings, so analyses, the Library, renders and server sync keep reading them. + Main is made lazily, from the settings as they are, the first time a project of the + sequence is asked for. Settings another path writes (an older Chronos, the API, an + analysis, sync) become an *external* version of Main at the next project operation; a + mirror a crash cut short is completed, and if the settings also moved meanwhile, one + *merge* version is made in which the settings written meanwhile win where both changed. + A mirror never writes over settings written in `project.json` since this index last knew + what it held: it takes them in first. +- The index heals the sidecars from what it knows: a project whose folder is gone is + written back from the index; a record behind the index (a projects folder put back from + a backup) gets the missing version files, then the index's head and, when it is older, + the index's name; a record that is lost is written again from the index only once the + folder has looked the same for 2 minutes and no trash folder holds the project, so a + record a sync tool is still bringing wins. A folder with versions and no record, of a + project no index knows, is a creation cut short: it holds nothing back and is left as it + is. One Main per sequence is decided from the records (the oldest that says Main); any + other becomes an ordinary project with every version kept. + Rules: originals are immutable (never rewritten; edits are settings; a conversion takes an original out of its sequence only into the trash, amended 2026-10-26, R7); every write of a sidecar goes to a temp file, `fsync`, rename; the folder name is derived from templates at @@ -1030,11 +1105,15 @@ player smoke test on Windows CI. hero, keyframes) wait as pending frames until a restore brings the photos back, and the others follow their photos without a settings edit. *Delete…* still moves whole sequences into the archive's trash, which lists photo entries too (§12.5). +- Open (a card, the Archive manager's Open, Jobs' Open; amended 2026-10-26, R8) opens a + sequence of this PC in Edit as a project of the workspace (§12.3): the project of that + sequence opened last on this PC, else *Open in workspace* asks which. A server-only + sequence still opens with proxies (§14.5) until the server home (phase 5b). -### 12.3 Edit (amended 2026-10-16, R7; formerly "Sequence editor") +### 12.3 Edit (amended 2026-10-16, R7; formerly "Sequence editor"; amended 2026-10-26, R8) ``` -│ ← Harbour sunset ▾ · 3,600 frames · Canon EOS R5 · 2 s interval · 2 h 00 m [Analyse] [Optimise all] [Render ▾] │ +│ ← Harbour sunset ▾ · [Main ● In sync ▾] · 3,600 frames · Canon EOS R5 · 2 s · 2 h 00 m [Analyse] [Optimise all] [Render ▾] │ │ ✓ Analysis ── ▲ Frames ── ✓ Exposure ── ✓ Motion ── ✓ Camera ── ✓ Time ── ⑦ Stack ── ⑧ Export │ ← the path ├──────────────────────────────────────────────────────────────────┬──────────────────────────────────┤ │ ┌──────────────────────────────────────────────────────────────┐ │ Exposure │ @@ -1056,7 +1135,12 @@ player smoke test on Windows CI. sequence whose proxies are still coming, or one that cannot open, leaves it open), its last edit saved first, or discarded on the user's word and then never written. The Library, Jobs, the Server screen, project files and the command line still open - sequences in Edit; ← goes back to the Library. + sequences in Edit; ← goes back to the Library. Amended 2026-10-26, R8: the picker has two + groups, *Workspace* (the workspace's projects, the one saved last first, each with its + state chip read from its home after the list shows) above *Library*; the search filters + both, and Enter opens a library match, a project only when no sequence matches. A + Workspace row's context menu and the Delete key offer *Remove local copy*, also for a copy + that cannot open. - The steps form a guided path, freely navigable: **Analysis** (every finding of the analyses with the step that deals with it; light, flicker, exposure steps received, shake and flagged frames; Analyse), **Frames** (virtualized table: index, time, @@ -1086,6 +1170,85 @@ player smoke test on Windows CI. - While a job runs on this sequence, settings that would change the rules mid-render are disabled; viewing tools stay live. +Workspace (amended 2026-10-26, R8; §4.4, §7). Edit opens a sequence of this PC's archive only +as a project of the workspace, and never writes into the library; a capture (sample data) +keeps editing the library, and a server sequence keeps opening with proxies until phase 5b. +- Which project: the one of that sequence opened last on this PC. Otherwise *Open in + workspace* asks: **Project** (an existing one, Main first, made from the sequence's + settings as they are; or New, with a name of 1–60 characters unique in the sequence) and + **Media** (*Proxies*; *Originals* is disabled until phase 5c and its tooltip says why), + with the copy's size and the drive's free space (*Not enough space* below the size plus + 0.5 GB). A Main this Chronos cannot read (saved by a newer Chronos, or damaged) is listed + disabled with the reason; asked for alone, or with nothing else to offer, it is refused at + once, a damaged one offering *Remove local copy*. The project is then checked out and its + proxies copied by a *Workspace copy* job, followed like a server sequence's proxies (the + picker line, a toast with a Jobs link); it opens when the copy is done, and the open + sequence stays open meanwhile. +- The workspace folder holds `workspace.json` and one folder per project: + `project.chronos` (the working state, a project file of format 2 with a `workspace` + section: project, name, Main, home, base version, media; at most 64 MiB), `media/` + (`media.json`, `proxies/`, `analysis.json`), `versions/` (the versions taken from the + home and those not sent yet; `versions/.replaced` keeps every version a sync replaced), + `sync.json` (a conflict, a restore, or the journal of a sync under way), `exports/`, and + the lease `.lock.lease`. A workspace folder inside a library is refused before anything + is written, with *Choose folder*. +- The editor writes only the working state, atomically under the project's lease a moment + after each edit, merged photo by photo with what a sync or a copy wrote. Where a sync and + the editor changed the same setting, it asks (keep mine, take the library's). +- Beside the title, the project button (its name; Main in the UI language) with a state + chip: In sync, Changed, Not sent, Library newer, Conflict, Offline, No media, Syncing, + Not in library (the home deleted it: its copy can only be discarded), Damaged (a version + saved here cannot be read: nothing is saved, sent or taken until it is repaired from the + home's copy). The chip is read again a moment after each edit. Its ▾ menu: + - *Save version…* (Ctrl+S): a note, Enter saves. With Sync automatically on, the version + is sent at once. + - *Sync*: take the library's new versions, then send yours. A push whose parent is the + library's head goes straight in; otherwise the library's versions are taken, yours are + replayed on them (a version that changes nothing once replayed is not sent) and the + working state is merged setting by setting, pending frames photo by photo. + - *History…*: the versions, newest first: number, kind (Saved, Merged, Restored, + Imported, Outside change), the PC, time, note, Not sent or Current. *Compare* lists the + settings that differ from now (heroes, exclusions and keyframes by name, several photos + counted); *Restore* makes a version the project as one undo step, unsaved changes saved + as a version first, and a toast offers Undo. + - *Open project…* (another project of the home), *New project…* (from this project's + last version in the library), *Rename…*, *Delete project…* (never Main; confirmed; it + sends everything first, then the project goes to the library's project trash with all + its versions). + - *Remove local copy…*: a plan (files, size, versions not sent, unsaved changes, + conflict). *Remove* only when everything is in the library, whose head and the base are + read back and checked against their hashes first; *Send first* sends what is missing, + then removes; *Discard changes* asks for the project's name to be typed. The copy's + files, every one but the media, go to `/.trash/-