From 102f28b5dfb2eb98d311dccb6da71f161eef8e7f Mon Sep 17 00:00:00 2001 From: Alberto Balbo Date: Wed, 4 Nov 2026 14:31:00 +0100 Subject: [PATCH] docs(plan): phase 5c work packages Co-Authored-By: Claude Opus 5.5 --- docs/plans/phase-5c.md | 181 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 181 insertions(+) create mode 100644 docs/plans/phase-5c.md diff --git a/docs/plans/phase-5c.md b/docs/plans/phase-5c.md new file mode 100644 index 00000000..89e0bdda --- /dev/null +++ b/docs/plans/phase-5c.md @@ -0,0 +1,181 @@ +# Phase 5c plan (owner review 2, R8): originals, local render, clean-up, all Workspace settings + +Working plan for the implementation. Line numbers refer to the tree at the end of phase 5b (commit 31df8beb) and drift. +The highest `JobKind` is `WorkspaceCopy = 20` (src/Chronos.Core/Model/Enums.cs); 5c appends 21–23. No migration: `renders` +already has `project_id`/`project_version_id`, and the workspace state lives in files. + +## A. Already done (do not redo) +- Remove local copy: plan first, refused while work is unsent, Send first / Discard (typed), hash read-back of the home's + head and base before deleting (`WorkspaceHost.PlanRemovalAsync`, `RemoveLocalCopyAsync`, `VerifyHomeAsync`, + `RemoveFolderAsync` moves into `.trash/-`; `WorkspaceRemovalPlan.IsSafe`; `RemoveCopyDialogViewModel`). + Missing: emptying `.trash`. +- Kept versions (default 20, `AppSettings.WorkspaceKeptVersions`, `WorkspaceHost.PruneAsync`, `WorkspaceSettingsRows.KeptChoices`). +- Sync automatically (`AppSettings.WorkspaceAutoSync = true`, checkbox in SettingsView.xaml Workspace page). +- Folder Open / Change… (Change shows a plan, moves nothing: `WorkspaceFolderChange.cs`). Moving with projects is missing. +- Building blocks: `BundleMedia.Originals`; `WorkspaceProject.OriginalsFolder`/`OriginalsDirectory`; + `RenderJobParameters.ProjectId/ProjectVersionId`; `RenderStore.CommitAsync(projectId, projectVersionId)`; server + renders of a project version checked against the sequence; `SequenceRender` has an `originals` flag. +- Last used project: `WorkspaceHost.LastUsedAsync` + `WorkspaceRecent`. Main and Ask policies missing. + +## B. 5a/5b limitations that 5c closes +- Downloads into the workspace are not held on a metered connection (`UploadHold` only filters `UploadCommit`). → P3 +- Originals from a server: `WorkspaceCopyJobHandler` throws `Errors.Workspace.OriginalsLater`. Building block: + `SyncTransfers.FetchOriginalAsync` (private static; hash-checked, retried, resumable) and + `ISyncRemote.DownloadFrameAsync(…, "original", …)`; `/frames/{id}/original` needs Edit or RenderNode. → P1 +- A render upload carries no project or version (`RenderUploadRequest` in Protocol/Uploads.cs; `RenderUploads.CompleteAsync`). → P3 +- Move folder with projects (P6), empty `/.trash` (P4), automatic clean-up and size limit (P4), the rest of + Settings › Workspace (P5). +- Not 5c (leave): address-alias Offline, frames in one answer, History downloading every version, restoring from the + projects' trash. + +## C. Work packages +Order: P0 first. Then P1, P3, P4, P5, P6 (independent files). P2 after P1. P7 last. +i18n: P0 adds every new key in `i18n/en` and `i18n/it` with final text; later packages only reference keys; if one must +add a key it appends at the end of the resx file. + +### P0 – Foundation +- `JobKind`: append `WorkspaceRender = 21`, `WorkspaceSend = 22`, `WorkspaceMove = 23`; `JobWire` names + `workspace-render`, `workspace-send`, `workspace-move`. +- Register: `JobPriorityQueue.DefaultLevels` (Render High, Send Normal, Move High); `SettingsViewModel.PriorityKinds`; + `JobText.CountsFrames` (+WorkspaceRender); `JobNotices.Announces` (+ all three). Not in the server's list + (ServerSettingsStore.cs). +- `AppSettings`: `WorkspaceSizeLimitGb = 100` (0 = none); `WorkspaceDefaultMedia = "proxies"` (BundleMedia constants); + `WorkspaceVersionOnRender = true`; `WorkspaceCleanAfterDays = 30` (0 = never); `WorkspaceOpenProject` enum + `WorkspaceOpenPolicy { LastUsed, Main, Ask }` default LastUsed; `WorkspaceOpened` `Dictionary` + treated like `WorkspaceRecent` in Reset / Import / Export (kept by Reset all and Import, left out of Export). +- `WorkspaceFrame` (Data/Workspaces/WorkspaceMedia.cs): append optional `Original`, `OriginalSha256`, `OriginalBytes`; + `ToOriginalFrame(sequenceId)` (RelativePath = Original, Missing when null). `WorkspaceMedia.Kind` can be `originals` + (proxies plus originals). +- `WorkspaceProject`: `OriginalName(frameId, sha, extension)` → `originals/-` (keep the real + extension, decoders use it); `ExportsDirectory`; `RendersFile = "exports/renders.json"`. +- New `Data/Workspaces/WorkspaceRenders.cs`: `WorkspaceRenderEntry(RenderId, JobId, File, Sha256, Size, PresetName, + Codec, Width, Height, Fps, DurationSeconds, ProjectId, ProjectVersionId?, SettingsHash?, Rendered, State + pending|sent|failed, Sent?, Error?)`, ledger `WorkspaceRenders(Format, FormatVersion=1, Entries)`, atomic Read/Write. +- Parameter records in the `WorkspaceJson` context: `WorkspaceRenderParameters(WorkspaceRoot, ProjectId, + ProjectVersionId?, RenderJson, Server?)`, `WorkspaceSendParameters(WorkspaceRoot, ProjectId, RenderIds, Server?)`, + `WorkspaceMoveParameters(From, To, PlanFingerprint)`; `WorkspaceJobs.Render/Send/Move` request builders. +- `CreateHandlers(db, archives, ISyncConnector? servers, WorkspaceJobOptions options)` with + `WorkspaceJobOptions(ProcessingOptions Processing, Func HoldTransfers, Func? Moved)`; + skeleton handlers for Render, Send, Move. Wire in AppServices. +- App: `WorkspaceHost` becomes `partial`; stubs `UsageAsync` → `WorkspaceUsage(MediaBytes, TotalBytes, TrashBytes, + TrashItems)`, `PlanTrashAsync`/`EmptyTrashAsync`, `PlanMoveAsync(to)`/`QueueMoveAsync(plan)`, + `WorkspaceFolderChange.MoveAsync`. +- Protocol: append optional `ProjectId`, `ProjectVersionId` to `RenderUploadRequest`. +- Strings (en + it, labels ≤ 3 words, every one with a `Tooltips.*` twin): job kinds (Local render, Send render, Move + workspace); Settings.Workspace.* (Move…, Size limit/No limit, Default media/Proxies/Originals, Version on render, Clean + after/Never/Days plural, Open project/Last used/Main/Ask, Trash, Empty…, "{0} used"); Editor.OpenWorkspace.OriginalsSize + "Originals: {0}" and a new `Tooltips.Editor.OpenWorkspace.OriginalsReady` (old "later update" key stops being used); + Workspace.Menu.CopyOriginals "Copy originals…", Workspace.Menu.ProxiesOnly "Proxies only…"; errors Moving, + MoveTargetNotEmpty, MoveSameFolder, OriginalsMissing, RenderNoOriginals, SendHashMismatch, JobsRunning; schedule + Jobs.Schedule.System.WorkspaceCleanup and steps WorkspaceClean / WorkspaceTrash; `Server.PauseMeteredTransfers` "Pause + metered transfers" (new key, keep the old); Workspace.MovePlan.*, Workspace.TrashPlan.*, Workspace.Removal.UnsentRenders + / LastOriginals. +- Tests: priority defaults; settings defaults and Reset/Import/Export of WorkspaceOpened; RenderUploadRequest without + the fields deserializes; 5b media.json without original fields reads; JobWire names. + +### P1 – Originals in the workspace, opening a project +- Copy job: remove the OriginalsLater throw. With Media Originals: proxies first as now, then per frame stream into + `media/originals/.part` hashing as it copies, compare with the home frame's Sha256 (record it if the home has + none), rename, checkpoint `copy:::originals`. Archive source under the read lease as the proxy copy does; + server source via `SyncTransfers.FetchOriginalAsync` made `internal static`. Missing original (file gone, 404, 403): + keep the proxy, `Original = null`, finish with a warning count. +- Space: estimate adds originals not held yet; keep the 512 MiB reserve. `CopyFactsAsync` reports `OriginalsBytes` + (archive frames' Size, or a server's `SequenceDto.TotalBytes`). +- Commit writes the chosen media kind (replace the hard-coded Proxies). +- Proxies only…: plan (files, bytes) with explicit confirmation; before deleting, the home still holds each frame with + the same SHA; originals the home no longer holds go to `.trash`; rewrite media.json Kind Proxies. +- Copy originals…: queue a WorkspaceCopy with Media Originals (existing dedupe). +- Open dialog: originals selectable, default from `WorkspaceDefaultMedia`, originals size and free space, TooLittleSpace + counts originals, Open passes the chosen media. +- SequenceViewModel: pass the media into CheckoutAsync; apply `WorkspaceOpenProject` (LastUsed / Main / Ask); + AskProjectAsync gets copy facts for a server home; each open records `WorkspaceOpened[id] = now`. +- ProjectMenuViewModel: Copy originals… / Proxies only… (by media kind; refused while Modified or jobs run). +- Tests: archive copy with originals (hashes, files), corrupt source refused and .part removed, resume by checkpoint, too + little space, missing original leaves the frame proxied, from a server (FakeSyncRemote `original` payload, 403 + tolerated); dialog default; the three policies; Proxies only refuses when the home lost a frame and trashes it. +- Risks: stream originals, never buffer; older Chronos meeting kind `originals` reports OriginalsLater (DECISIONS). + +### P2 – Local render, `WorkspaceRender = 21` +- `WorkspaceRenderJobHandler` mirrors `RenderJobHandler.RunAsync`: workspace lease; media.json must be Originals with + an original for every placed frame (else `RenderNoOriginals` with the count); `SequenceFrames` over the originals; + parse the head version or the named `ProjectVersionId` from `versions/`; analysis from media; `SequenceRender(..., + originals: true, companions: null)` into `exports/.part` then rename, unique names, `RenderCheckpoint`; per + output SHA-256 and a ledger entry with `RenderId = RenderJobHandler.RenderId(jobId, index)`; then follow-up + `WorkspaceSend` with the new ids. Extract `ProvenanceAsync` into a shared internal helper. Cancel deletes `.part` only. +- Routing (WorkspaceSequenceSource): Originals media → `WorkspaceJobs.Render(...)` with portable settings and head + version id; such requests go to the local engine even for a server home; ListJobsAsync merges the local + Render/Send jobs; `IProjectRenders.RendersLocally`. +- Version on render (`ProjectMenuViewModel.ReadyToRenderAsync`): setting on + Modified → save a version (label + "Render") and sync it when auto sync is on and the home is reachable; off → today's behaviour. +- Editor: WorkspaceRender treated like Render for toast and reload; WorkspaceSend Done = "Sent home"; SequenceJobs and + ServerJobs know both kinds; Renders list shows pending ledger entries as "Not sent". +- Tests (Data, Linux-runnable): renders a preset from originals into exports, ledger SHA and id, follow-up queued, + missing original fails cleanly, cancel leaves no .part, output matches an archive render's frame count and size; + App: Originals routes locally for a server home, Version on render saves first, off still prompts. + +### P3 – Send home (`WorkspaceSend = 22`), server provenance, metered transfers +- `WorkspaceSendJobHandler`, per pending ledger entry: re-hash (mismatch → `SendHashMismatch`, file stays); push the + named version first if the home lacks it (failure → job fails, entry stays pending); archive home: file like + `SyncTransfers.GetExportsAsync` (lease, SequenceFolders, unique name, copy, hash read-back, `Renders.InsertAsync` with + project and version after checking the version belongs to this sequence); server home: + `ISyncRemote.UploadRenderAsync(sequenceId, path, new RenderUploadRequest(..., ProjectId, ProjectVersionId))` (not + UploadCommit). Mark sent; the file stays until clean-up. Idempotent by RenderId. +- Server `RenderUploads.CompleteAsync`: check the project fields against the sequence (422 `project_mismatch`), pass to + `RenderStore.CommitAsync`; `RenderDto` gains optional project fields. +- `UploadHold`: hold `UploadCommit`, `WorkspaceSend` and `WorkspaceCopy` jobs naming a `Server` while + `PauseUploadsOnMetered && MeteredNetwork.IsMetered()`; archive-home copies never held. Server screen checkbox uses + "Pause metered transfers". +- Tests: archive-home send files the render with project and version; changed file refused; unpushed version pushed + first; retry; duplicate harmless; server upload with fields stores them, foreign version 422, without fields as + before; UploadHold pauses server copy and send when metered, not an archive copy. + +### P4 – Clean-up, size limit, workspace trash +- `WorkspaceCleaner`: eligible = StatusAsync InSync with the home asked (not Offline), not open, no + Copy/Render/Send/Move job pending or running, no pending ledger render. Removes `media/proxies`, `media/originals` + (media.json rewritten with File/Original null, frames stay), and sent files in `exports/`; never `project.chronos`, + `versions/`, `sync.json`, `analysis.json`. An original is deleted only when the home still holds the same frame with + the same SHA; otherwise it goes to `.trash/-/originals`. Policies: Clean after N days (by + `WorkspaceOpened`, fallback the bundle's Saved), Size limit (LRU while above). 0 disables. Report with skipped reasons. +- `WorkspaceTrash`: Plan (items, bytes, dates, fingerprint over names, sizes, mtimes) and Empty(plan) only if the + fingerprint still matches; the UI asks for the item count typed. Schedules and the size limit never empty the trash. +- Schedule: system key `workspace-cleanup`, daily 04:30, steps `workspace-clean` and `workspace-trash` (report only) as + App-side cleanup steps like `CacheTrimStep`; seeded by `DesktopScheduleHost`; ScheduleText maps; runs without an + archive. The size limit also runs after each WorkspaceCopy (never the project just copied). +- `WorkspaceHost.Cleanup.cs` fills the P0 stubs. Removal plan: `UnsentRenders` blocks IsSafe until Send first (queues + WorkspaceSend) or Discard; `LastOriginals` go to `.trash`. +- Tests: each skip reason, original the home lost goes to trash, LRU order, Clean after with fallback, trash untouched by + clean-up and Empty refuses a stale fingerprint; schedule seeded once, step without an archive, removal plan counts + unsent renders. + +### P5 – Settings › Workspace page +Rows in order: Folder (path, Open, Change…, Move… showing P6's plan; "{0} used"); Size limit (25, 50, 100, 200, 500, +1000 GB, No limit); Default media (Proxies, Originals); Sync automatically; Version on render; Kept versions; Clean +after (7, 14, 30, 60, 90 days, Never); Open project (Last used, Main, Ask); Trash ("{n} items, {size}", Empty… with the +plan dialog and typed confirmation, disabled when empty). Search keys, Reset restores defaults, every control has a +tooltip. Tests: rows read/write and Reset; the screen smoke test (page builds, tooltips). + +### P6 – Move the workspace folder, `WorkspaceMove = 23` +- Plan: projects, bytes, free space at the target, unsent or Modified projects as a warning; refused when the target is + inside the source or the same, already holds `workspace.json` or same-id project folders, too little space, or any + workspace job pending or running; fingerprint. +- Job: re-check the fingerprint; journal `/.move.json`; same volume `Directory.Move` per project, then + `workspace.json`, then `.trash`; other volume copy each file, hash both sides, delete the source only after every file + of that project verified; checkpoint per file; resume from the journal. At the end `Moved(from, to)` sets + `AppSettings.WorkspaceFolder` and refreshes `WorkspaceHost.Root`; delete the journal. On failure the source stays the + truth and unverified partial copies are removed. +- App: while moving, sync and open are refused (`Errors.Workspace.Moving`); MoveAsync closes the open project first; a + leftover `.move.json` at start raises a notice to resume. +- Tests: same-volume, cross-volume (injected flag), a corrupt copy never deletes the source, resume, refusals; App: the + setting switches only on success, the workspace is gated while moving. + +### P7 – Documentation +DECISIONS rows (originals media and naming, local render and ledger, send home idempotence, server provenance fields, +metered transfers covering downloads, clean-up eligibility and originals rule, trash fingerprint, workspace-cleanup key, +move journal, Open project policy, defaults, no migration, no GPR companions); BRIEF §4.4, §12.3, §12.7, §12.8, §14.3, +§14.5; CHANGELOG [Unreleased] (remove the 5b limitations 5c closes; metered now pauses downloads); STATUS; ARCHITECTURE +job table; request files (owner review 2 row 5c, owner review 3 phase 2). + +## D. Cross-cutting rules +- BRIEF rule 8: every deletion is a plan, derived data, or preceded by a home SHA read-back; trash when in doubt. +- Mixed versions: older clients see kind `originals` (OriginalsLater); older servers ignore the provenance fields. +- Logic in Chronos.Data (Linux-testable); the App wires it.