Files
Chronos/docs/plans/phase-5c.md
T
Alby96andClaude Opus 5.5 db389a54f2
CI / Build and test (push) Successful in 9m26s
CI / Windows tests and installer (push) Skipped
CI / YAML check (push) Successful in 8s
Release / Build, test and publish (push) Successful in 14m31s
CI / PostgreSQL 16 integration (push) Successful in 9m53s
CI / PostgreSQL 17 integration (push) Successful in 9m22s
CI / Docker image (push) Successful in 44s
Release / Server image (push) Successful in 1m36s
feat: owner review 2 phase 5c: originals, local render, clean-up and the workspace settings (#18)
Originals in the workspace, local render and send home with provenance, the workspace clean-up, size limit and trash, moving the workspace folder, and the complete Settings › Workspace page (owner review 2, R8, phase 5c). One adversarial review round (35 findings, 32 fixed), a copy-cancel race fixed, 184 strings in all 38 languages.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-authored-by: Alberto Balbo <alberto.balbo.96@gmail.com>
2026-11-04 20:03:52 +01:00

16 KiB
Raw Blame History

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/<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; 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 <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: 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<Guid, DateTimeOffset> 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/<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?), 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<bool> HoldTransfers, Func<string,string,Task>? 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/<name>.part hashing as it copies, compare with the home frame's Sha256 (record it if the home has none), rename, checkpoint copy:<frame>:<fv>: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/<name>.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/<id>-<ticks>/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 <from>/.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.