16 KiB
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,RemoveFolderAsyncmoves into.trash/<id>-<ticks>;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;SequenceRenderhas anoriginalsflag. - 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 (
UploadHoldonly filtersUploadCommit). → P3 - Originals from a server:
WorkspaceCopyJobHandlerthrowsErrors.Workspace.OriginalsLater. Building block:SyncTransfers.FetchOriginalAsync(private static; hash-checked, retried, resumable) andISyncRemote.DownloadFrameAsync(…, "original", …);/frames/{id}/originalneeds Edit or RenderNode. → P1 - A render upload carries no project or version (
RenderUploadRequestin Protocol/Uploads.cs;RenderUploads.CompleteAsync). → P3 - Move folder with projects (P6), empty
<workspace>/.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: appendWorkspaceRender = 21,WorkspaceSend = 22,WorkspaceMove = 23;JobWirenamesworkspace-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);WorkspaceOpenProjectenumWorkspaceOpenPolicy { LastUsed, Main, Ask }default LastUsed;WorkspaceOpenedDictionary<Guid, DateTimeOffset>treated likeWorkspaceRecentin Reset / Import / Export (kept by Reset all and Import, left out of Export).WorkspaceFrame(Data/Workspaces/WorkspaceMedia.cs): append optionalOriginal,OriginalSha256,OriginalBytes;ToOriginalFrame(sequenceId)(RelativePath = Original, Missing when null).WorkspaceMedia.Kindcan beoriginals(proxies plus originals).WorkspaceProject:OriginalName(frameId, sha, extension)→originals/<frameId>-<sha8><ext>(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?), ledgerWorkspaceRenders(Format, FormatVersion=1, Entries), atomic Read/Write. - Parameter records in the
WorkspaceJsoncontext:WorkspaceRenderParameters(WorkspaceRoot, ProjectId, ProjectVersionId?, RenderJson, Server?),WorkspaceSendParameters(WorkspaceRoot, ProjectId, RenderIds, Server?),WorkspaceMoveParameters(From, To, PlanFingerprint);WorkspaceJobs.Render/Send/Moverequest builders. CreateHandlers(db, archives, ISyncConnector? servers, WorkspaceJobOptions options)withWorkspaceJobOptions(ProcessingOptions Processing, Func<bool> HoldTransfers, Func<string,string,Task>? Moved); skeleton handlers for Render, Send, Move. Wire in AppServices.- App:
WorkspaceHostbecomespartial; stubsUsageAsync→WorkspaceUsage(MediaBytes, TotalBytes, TrashBytes, TrashItems),PlanTrashAsync/EmptyTrashAsync,PlanMoveAsync(to)/QueueMoveAsync(plan),WorkspaceFolderChange.MoveAsync. - Protocol: append optional
ProjectId,ProjectVersionIdtoRenderUploadRequest. - 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 newTooltips.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/<name>.parthashing as it copies, compare with the home frame's Sha256 (record it if the home has none), rename, checkpointcopy:<frame>:<fv>:originals. Archive source under the read lease as the proxy copy does; server source viaSyncTransfers.FetchOriginalAsyncmadeinternal 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.
CopyFactsAsyncreportsOriginalsBytes(archive frames' Size, or a server'sSequenceDto.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 recordsWorkspaceOpened[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
originalpayload, 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
originalsreports OriginalsLater (DECISIONS).
P2 – Local render, WorkspaceRender = 21
WorkspaceRenderJobHandlermirrorsRenderJobHandler.RunAsync: workspace lease; media.json must be Originals with an original for every placed frame (elseRenderNoOriginalswith the count);SequenceFramesover the originals; parse the head version or the namedProjectVersionIdfromversions/; analysis from media;SequenceRender(..., originals: true, companions: null)intoexports/<name>.partthen rename, unique names,RenderCheckpoint; per output SHA-256 and a ledger entry withRenderId = RenderJobHandler.RenderId(jobId, index); then follow-upWorkspaceSendwith the new ids. ExtractProvenanceAsyncinto a shared internal helper. Cancel deletes.partonly.- 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 likeSyncTransfers.GetExportsAsync(lease, SequenceFolders, unique name, copy, hash read-back,Renders.InsertAsyncwith 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 (422project_mismatch), pass toRenderStore.CommitAsync;RenderDtogains optional project fields. UploadHold: holdUploadCommit,WorkspaceSendandWorkspaceCopyjobs naming aServerwhilePauseUploadsOnMetered && 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. Removesmedia/proxies,media/originals(media.json rewritten with File/Original null, frames stay), and sent files inexports/; neverproject.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/<id>-<ticks>/originals. Policies: Clean after N days (byWorkspaceOpened, 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, stepsworkspace-cleanandworkspace-trash(report only) as App-side cleanup steps likeCacheTrimStep; seeded byDesktopScheduleHost; ScheduleText maps; runs without an archive. The size limit also runs after each WorkspaceCopy (never the project just copied). WorkspaceHost.Cleanup.csfills the P0 stubs. Removal plan:UnsentRendersblocks IsSafe until Send first (queues WorkspaceSend) or Discard;LastOriginalsgo 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.jsonor same-id project folders, too little space, or any workspace job pending or running; fingerprint. - Job: re-check the fingerprint; journal
<from>/.move.json; same volumeDirectory.Moveper project, thenworkspace.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 endMoved(from, to)setsAppSettings.WorkspaceFolderand refreshesWorkspaceHost.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.jsonat 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.