docs(plan): phase 5c work packages

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
Alby96andClaude Opus 5.5 committed 2026-11-04 14:31:00 +01:00
1 parent 31df8beb9a
commit 102f28b5df
1 file changed
+181
+181
View File
@@ -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/<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.