diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index 979abfc3..357d5e81 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -62,7 +62,7 @@ Dependencies point one way: `Core` ← `Core.Windows`, `Data`, `Protocol` ← `S | `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; `EditSettingsAsync`: settings an index edit writes, written to `project.json` under the lease first and put back when the index does not take them), `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); 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`), `ServerProjectHome` (phase 5b: a server sequence's `/projects` over `ChronosClient`; a server out of reach, an expired sign-in, a 503 lease, offline archive or `projects_unreadable`, a 409 `folder_in_use` and a server without the projects are `HomeUnavailableException`, a 404 `sequence`/`project`/`version` and a refused name `ProjectException` (a deleted project's head is 404 `project`), a 422 `too_large` the `TooLarge` outcome, other refusals keep their `ChronosApiException`; `HoldsAsync` reads the version back (`?stored=true`), `FramesStampAsync` from `…/frames/stamp`, version pages read on past a page the server ended early, a 413 the `TooLarge` outcome; its sequences name an archive id made from the server's key), `HomePhotos` (a sequence's photos as positions name them, with the encodings its Replaced tombstones join; the server's frames endpoint and render nodes build the same), what each call changed (`ProjectChangeSet` to `ArchiveServiceOptions.ProjectsChanged`, once the lease is let go: projects made, renamed, deleted or with a new head, compared before and after under the lease, and whether Main's head was written into the sequence's settings), `CatchUpAsync` (the catch-up alone, saying why it cannot run), `ProjectWire` (projects, versions, push outcomes and a home's frames to and from API v1 DTOs, for the server and a client of it) | -| `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; `FollowNameAsync`: the home's name and Main written into the copy at every pull and at a server's `renamed`), `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; a project whose home is a server, `WorkspaceJobs.CopyFromServer`, phase 5b: downloaded through the desktop's session (`ISyncConnector`), never through this PC's archive, the frames of one frames version with the aliases of the server's conversions, each proxy (else the thumbnail standing in, `WorkspaceFrame.FileKind`) hashed as it arrives and checked on the disk, four at a time, the editor's current file never overwritten, resumable from the same checkpoint, a `.thumb` marker beside a thumbnail standing in until the commit, free space checked against the server's proxy sizes) | +| `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; `FollowNameAsync`: the home's name and Main written into the copy at every pull and at a server's `renamed`), `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; a project whose home is a server, `WorkspaceJobs.CopyFromServer`, phase 5b: downloaded through the desktop's session (`ISyncConnector`), never through this PC's archive, the frames of one frames version with the aliases of the server's conversions, each proxy (else the thumbnail standing in, `WorkspaceFrame.FileKind`) hashed as it arrives and checked on the disk, four at a time, the editor's current file never overwritten, resumable from the same checkpoint, a `.thumb` marker beside a thumbnail standing in until the commit, free space checked against the server's proxy sizes); phase 5c: `WorkspaceProject` gains `media/originals/-` (`OriginalName`), the ledger `exports/renders.json` (`WorkspaceRenders`, `WorkspaceRenderEntry`; `ContainedExportFile` keeps every ledger path inside `exports/`), `media.json` format 2 while it holds originals or was cleaned (`WorkspaceMedia.Cleaned`) and the project file format 3 while its media are Originals; `WorkspaceOriginals` (Proxies only's plan and apply, and `ClearOriginals`: every file of `media/originals` hashed and deleted only when the home's frames hold its SHA-256, the rest moved to the trash), `WorkspaceTrash` and `WorkspaceTrashBuilder` (`/.trash`: entries `-` filled under `.incoming--` and renamed when whole, listed with a fingerprint of every file's path, size and time, emptied only by a plan that still matches), `WorkspaceCleaner` (the clean-up of media of projects in step with their home: Clean after, Size limit, the reasons a project is kept in `WorkspaceKeep`, `UnsentRenders`), `WorkspaceMover` (survey, plan fingerprint, the journal `/.move.json` with stages Moving and Switched, rename on one volume or copy and hash-verify across volumes, resume, abandon, clear after the switch), `WorkspaceJobRoots` (internal, in `WorkspaceJobs.cs`: the folder a copy, render or send works in, the one that holds its project now, refused while a move has not switched) and the job parameters `WorkspaceRenderParameters`, `WorkspaceSendParameters`, `WorkspaceMoveParameters` in `WorkspaceJson` | | `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; a server's `projectChanged` passed on as `ProjectChanged`, and null after a lost event stream once the stream is open again and a comparison made after that reached the server: `ISyncRemote.EventsAsync(connected, ct)`), `ProxyCache` and `RemoteSequence` (server sequences opened with proxies), `ISyncRemote` (the server calls; `ChronosSyncRemote` over `ChronosClient`) | ### 2.3 Chronos.App areas @@ -73,11 +73,11 @@ Dependencies point one way: `Core` ← `Core.Windows`, `Data`, `Protocol` ← `S | `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 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; a server home's analyses and renders are the server's jobs over `WorkspaceServerHome(connect, session)`, which connects again when the sign-in changes, a render naming the version the server holds when the project is in step with it), `ServerJobs` (a server sequence's analyses and renders followed through its events, shared by `RemoteSequenceSource` and a server home's `WorkspaceSequenceSource`), 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 or, through `SyncHost.ProjectHome`, the signed-in server as the home (a server it is not signed in to reads as offline; `HomeChanged` from the server's `projectChanged`, texts worded for it by `WorkspaceText.ForHome`); 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) | +| `Workspace` | Owner review 2, R8: `WorkspaceHost` (the desktop's `WorkspaceStore` and `WorkspaceSync` over Settings › Workspace's folder, this PC's archive or, through `SyncHost.ProjectHome`, the signed-in server as the home (a server it is not signed in to reads as offline; `HomeChanged` from the server's `projectChanged`, texts worded for it by `WorkspaceText.ForHome`); 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`; phase 5c partials: `WorkspaceHost.Media` (Copy originals, Proxies only), `.Render` (local renders, Send again), `.Cleanup` (usage, the clean-up after each copy and by schedule, the trash's plan and Empty, the removal's unsent renders and originals) and `.Move` (move plan and job, `IsMoving` gate, `MoveEnded`, the unfinished move)), `WorkspaceFolderChange` (Settings › Workspace › Change…, Move… and Resume, 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; `HasProjects`, `ProjectHome` and `ProjectChanged`, also told with null at each session start and stop: the server as a project home), sync table, `RemoteSequenceApi` | -| `Jobs`, `Settings`, `About` | Job list and buffering, `JobNotices` (which job endings raise a toast, conversions among them; `JobEndings` lets a batch speak once); the schedules of Jobs › Scheduled (`DesktopScheduleHost`: the desktop's `IScheduleHost` and its system schedules `archive-scan`, `index-backup`, `housekeeping`; `CacheTrimStep`, the host's clean-up step; `SchedulesViewModel`, `ScheduleRowViewModel`, `ScheduleEditorViewModel` and `ScheduleDialogs.xaml`, the in-window editor; `ScheduleText`); settings rows (`LogSettingsRows`: Advanced's log rows; `WorkspaceSettingsRows`: Settings › Workspace), encoder and format inventories, `ProcessingTuning` (Settings › Rendering and Analysis applied to each job: parallelism, memory budget, quality), `InterfacePriority`, language catalog, naming preview; `AboutViewModel` (owned by the shell, not a section: Settings › About, the update notice of Settings › Updates and the update check on start), update check and download | +| `Server` | `ServerSession`, `ConnectFlow` (trust on first use), `SyncHost` (sync engine, agent, metered hold (`UploadHold`: uploads, downloads and the workspace's server copies and sends), editor connections, Export Sync; `HasProjects`, `ProjectHome` and `ProjectChanged`, also told with null at each session start and stop: the server as a project home), sync table, `RemoteSequenceApi` | +| `Jobs`, `Settings`, `About` | Job list and buffering, `JobNotices` (which job endings raise a toast, conversions among them; `JobEndings` lets a batch speak once); the schedules of Jobs › Scheduled (`DesktopScheduleHost`: the desktop's `IScheduleHost` and its system schedules `archive-scan`, `index-backup`, `housekeeping`, `workspace-cleanup`; `CacheTrimStep`, `WorkspaceCleanStep` and `WorkspaceTrashStep`, the host's clean-up steps; `SchedulesViewModel`, `ScheduleRowViewModel`, `ScheduleEditorViewModel` and `ScheduleDialogs.xaml`, the in-window editor; `ScheduleText`); settings rows (`LogSettingsRows`: Advanced's log rows; `WorkspaceSettingsRows`: Settings › Workspace), encoder and format inventories, `ProcessingTuning` (Settings › Rendering and Analysis applied to each job: parallelism, memory budget, quality), `InterfacePriority`, language catalog, naming preview; `AboutViewModel` (owned by the shell, not a section: Settings › About, the update notice of Settings › Updates and the update check on start), update check and download | | `Infrastructure` | `AppServices` (composition root; `SequenceReorganized`, raised after each Reorganize step and each sequence a conversion replaced or made, reloads an editor open on that sequence; the archive engine's free space from `VolumeInfo.FreeBytesAt`), `AppSettings`, `AppLogging` (Settings › Advanced › Logs applied to the log files from their first line, a launch that only hands over included, and at every save), `AppEnvironment` (installed or portable), `AppClock` (today's date, frozen by `--capture`), `StartWithWindows` (this copy's sign-in entry), `UiLanguage`, `LiveRegion`, `RenderNodeHost`, `DiagnosticsBundle`, `ShellActions` (BRIEF §8.6), `SingleInstance` (one Chronos per data folder; a later launch hands its file over a named pipe, or waits for a closing one to exit and starts in its place), device monitor | | `DesignTime` | `SampleData`: the archive, jobs and server the screenshots and smoke tests run on, dated from the fixed `SampleData.Now` | @@ -121,7 +121,10 @@ 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, 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 | +| `WorkspaceCopy` | `Workspaces/WorkspaceCopyJobHandler` (via `WorkspaceJobs.CreateHandlers` with `WorkspaceJobOptions`: a sequence's proxies and deep report, and with media Originals each frame's original (phase 5c), into a workspace project's media, high in the priority queue by default; its cancel clean-up as an `ICancelledJobHandler`, which also removes the originals a cancelled copy wrote) | yes | no: it writes into the folder its parameters name | +| `WorkspaceRender` (21) | `Workspaces/WorkspaceRenderJobHandler` (phase 5c, `WorkspaceJobs.Render`: a workspace project rendered from the originals its media hold into `exports/`, each output hashed into `renders.json`, then a `WorkspaceSend` of every unsent render queued; high by default) | yes | no | +| `WorkspaceSend` (22) | `Workspaces/WorkspaceSendJobHandler` (phase 5c, `WorkspaceJobs.Send`: the ledger's unsent renders filed in this PC's archive or uploaded to the server with their project and version, the version pushed first when the home lacks it, idempotent by render id; normal by default; a server send waits while `HoldTransfers` is true) | yes | no | +| `WorkspaceMove` (23) | `Workspaces/WorkspaceMoveJobHandler` over `WorkspaceMover` (phase 5c, `WorkspaceJobs.Move`: the workspace folder moved with its projects after a confirmed plan, journaled, resumable, undone on failure or cancel before its switch; an `ICancelledJobHandler`; high by default) | yes | no | | `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) @@ -187,6 +190,14 @@ deletion is taken only from the projects' trash, read first, a record that canno 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`). +Workspace, phase 5c: a project folder may also hold `media/originals/` and `exports/` with the ledger `renders.json` +(the local renders, their SHA-256, project, version and sent state); beside the project folders the workspace keeps +`workspace.json`, `.trash/` (entries staged as `.incoming--`, then renamed) and, while it moves, the journal +`.move.json` in the folder it leaves. All of it is files: no index table and no migration. Deletions go through the home: +an original goes only when the home's frames, read now, hold its bytes (`WorkspaceOriginals.ClearOriginals`), else into +`.trash`; only the user's Empty… erases `.trash`. Logic lives in `Chronos.Data/Workspaces` (Linux-tested); the App's +`WorkspaceHost` wires settings, the open project, the move gate and the UI. + 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 `ArchiveIngest`, downloaded originals are verified and committed through the local `ArchiveIngest`, and proxies land diff --git a/docs/BRIEF.md b/docs/BRIEF.md index 2b48b909..1d9eec9f 100644 --- a/docs/BRIEF.md +++ b/docs/BRIEF.md @@ -290,9 +290,16 @@ where it lives: this PC's archive (phase 5a) or a server (phase 5b). The home ke 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. +working state, its versions, the sequence's proxies and, when chosen, its originals. Final +renders run where the originals are: at the home, or on this PC for a project whose +originals the workspace holds, each such render then sent home with the project and the +version it shows. A local-only library works the same way, its archive being the home. + +Workspace upkeep (amended 2026-10-26, R8). The workspace removes the media of projects in +step with their home that were not opened for a while or exceed its size limit, keeps in +its own trash what it cannot prove the home holds, and moves to another folder with its +projects only after a plan (§12.3, §12.8). Nothing it removes is the only copy: versions, +unsent work and local renders not sent stay. Server home (amended 2026-10-26, R8). A Chronos Server whose `server/info` lists the `projects` capability is the home of its sequences, with the same rules as this PC's @@ -349,8 +356,12 @@ 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; 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), + 2026-10-26, R7; workspace-copy, stored as 20, the copy of a sequence's proxies (and + originals, when chosen) and deep report into a workspace project's media, run by the + desktop only: amended 2026-10-26, R8; workspace-render, stored as 21, a render on this PC + from the originals a workspace project holds; workspace-send, stored as 22, those renders + sent home with their project and version; workspace-move, stored as 23, the workspace + folder moved with its projects; all three 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). @@ -1194,25 +1205,35 @@ Workspace (amended 2026-10-26, R8; §4.4, §7). Edit opens a sequence of this PC as a project of the workspace, and never writes into the library; a capture (sample data) keeps editing the library. A server sequence opens as a project of the workspace too when its server keeps projects (server home, below); otherwise it opens with proxies as before. -- 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 +- Which project: as Settings › Workspace › *Open project* says (amended 2026-10-26, R8): + *Last used*, the default, the one of that sequence opened last on this PC; *Main*; or + *Ask*, a list of the sequence's projects in the workspace (when it holds two or more), + the last used chosen first. Each opening is remembered for the clean-up. With none of + its projects in the workspace, *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*, or *Originals*: the proxies + plus the originals, to render on this PC; *Default media* chooses first, and *Originals* + is disabled, its tooltip saying why, when the drive lacks room for them), with the copy's + size, the originals' apart, and the drive's free space (*Not enough space* below the size + of the media chosen 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 media 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*. + section: project, name, Main, home, base version, media; format 3 while the media hold + originals, so an older Chronos refuses it; at most 64 MiB), `media/` (`media.json`, + format 2 while it holds originals or was cleaned; `proxies/`; + `originals/-`; `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/` (the renders made on this PC and + their ledger `renders.json`: file, SHA-256, project, version, and whether it was sent), + and the lease `.lock.lease`. Beside the projects: `workspace.json`, `.trash`, and a move's + journal `.move.json` (below). 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). @@ -1236,12 +1257,20 @@ server keeps projects (server home, below); otherwise it opens with proxies as b 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). + - *Copy originals…* (amended 2026-10-26, R8): queues a *Workspace copy* of the originals + besides the proxies. *Proxies only…*: a plan (originals deleted, their size, those kept + in the trash) and a confirmation; each original is deleted only when the library holds + the same bytes, the others go to the workspace's trash. Both are refused while the + project has changes or its jobs run, and their tooltips then say why. - *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/-