Files
Chronos/docs/plans/phase-5c.md
T
2026-11-04 14:31:00 +01:00

182 lines
16 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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.