feat(projects): workspace projects with linear versions, the local archive as their home

Owner review 2, phase 5a (R8): editing moves out of the library into a workspace on a fast disk, and a
sequence gets several projects, each with a linear version history pushed and pulled like git.

- Core: ProjectSettings keeps members a newer Chronos wrote (Extra) and reads a newer settings format
  read-only; ProjectContent is the portable form of a version (every frame position parked by photo,
  canonical text, SHA-256 content hash); ProjectBundle format 2 adds the workspace section, and a file
  without it is still written as format 1. JobKind.WorkspaceCopy = 20 (19 kept for Convert).
- Data: migration 0009 (projects, project_versions, the render's project columns); ProjectService on
  ArchiveService.Projects keeps projects as sidecars first (.chronos/projects/<id>/), then the index,
  under the sequence lease: create, rename, delete into the projects' trash, history, push with
  fast-forward, idempotent repeat, divergence and hash checks. Main is made from the sequence's settings
  and mirrored both ways, so every older code path keeps working; outside writes become "external"
  versions, a mirror a crash cut short is completed or merged. Full scans and rebuilds take the projects
  back from their sidecars.
- ProjectMerge moves from the App to Data/Projects, merges pending frames photo by photo and replays
  unpushed commits on a moved head.
- Workspaces: WorkspaceStore, WorkspaceSync (checkout, save, commit, push, pull with replay and merge,
  conflicts settled by keep mine / take server / save both, restore, status) and the WorkspaceCopy job
  (proxies copied hash-verified and resumable; originals refused until phase 5c).
- Renders of a project version place its positions on the frames and record the project and version.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
(cherry picked from commit c4c1802884e403db8759ed0501f770a67a047f20)
This commit is contained in:
Alby96 committed 2026-10-27 22:51:32 +01:00
1 parent e3cbe30b29
commit 03d32f18d3
51 files changed
+4917 -108

No files matched your search

+114 -4
View File
@@ -12,18 +12,63 @@ public sealed record BundleArchive(Guid Id, string Name, string? Path);
/// <summary>The sequence a project file applies to: its id, folder (relative to the archive), title and frame count when saved.</summary>
public sealed record BundleSequence(Guid Id, string Folder, string? Title, int Frames);
/// <summary>
/// Where a workspace project's versions live (owner review 2, R8): this PC's archive (<see cref="ArchiveKind"/>, with the
/// archive's id) or a server (<see cref="ServerKind"/>, with its address), and the sequence there.
/// </summary>
public sealed record BundleHome(string Kind, Guid SequenceId, Guid? ArchiveId = null, string? Server = null)
{
public const string ArchiveKind = "archive";
public const string ServerKind = "server";
public bool IsArchive => Kind == ArchiveKind;
}
/// <summary>The version of the home a workspace project was last in step with: its id, number and content hash.</summary>
public sealed record BundleBase(Guid VersionId, int Number, string ContentHash);
/// <summary>What a workspace holds of the sequence's photos: <see cref="Proxies"/> (the default) or <see cref="Originals"/>, at a frames version of the home.</summary>
public sealed record BundleMedia(string Kind, int FramesVersion)
{
public const string Proxies = "proxies";
public const string Originals = "originals";
}
/// <summary>
/// The workspace section of a project file (format 2, owner review 2, R8): the project of the home it belongs to, its
/// name, whether it is the sequence's Main project, the home, the version it was last in step with (none before its
/// first pull) and the media the workspace holds.
/// </summary>
public sealed record BundleWorkspace(Guid ProjectId, string Name, bool IsMain, BundleHome Home, BundleBase? Base, BundleMedia Media);
/// <summary>
/// A <c>.chronos</c> project file (BRIEF §18, file associations): which sequence of which archive, and the project
/// settings to open it with. The photos stay in the archive; opening the file opens that sequence in the editor with
/// these settings. UTF-8 JSON with a format name and version, so a newer file is refused rather than misread:
/// <code>{ "format": "chronos-project", "formatVersion": 1, "saved": …, "archive": { "id", "name", "path" },
/// "sequence": { "id", "folder", "title", "frames" }, "project": { …project.json… } }</code>
/// Format 2 (owner review 2, R8) adds the <see cref="Workspace"/> section of a workspace's working state:
/// <code>"workspace": { "projectId", "name", "isMain", "home": { "kind": "archive"|"server", "server"?, "archiveId"?, "sequenceId" },
/// "base": { "versionId", "number", "contentHash" }?, "media": { "kind": "proxies"|"originals", "framesVersion" } }</code>
/// A file without that section is still written as format 1, so earlier versions of Chronos open it. A format 2 file
/// opens a project of a newer settings format too, read-only (<see cref="IsReadOnly"/>).
/// </summary>
public sealed record ProjectBundle(BundleArchive Archive, BundleSequence Sequence, ProjectSettings Project, DateTimeOffset Saved)
{
public const string Extension = ".chronos";
public const string FormatName = "chronos-project";
public const int CurrentFormatVersion = 1;
/// <summary>The newest format this Chronos reads and writes (2: with a workspace section).</summary>
public const int CurrentFormatVersion = 2;
/// <summary>The format of a file without a workspace section.</summary>
public const int PlainFormatVersion = 1;
/// <summary>The workspace section (format 2); null for a plain project file.</summary>
public BundleWorkspace? Workspace { get; init; }
/// <summary>The settings come from a newer Chronos (<see cref="ProjectSettings.IsNewerFormat"/>): show them, never edit them.</summary>
public bool IsReadOnly => Project.IsNewerFormat;
/// <summary>Project settings take a few kilobytes; a larger file is not a project file.</summary>
public const int MaxBytes = 4 << 20;
@@ -37,7 +82,7 @@ public sealed record ProjectBundle(BundleArchive Archive, BundleSequence Sequenc
{
w.WriteStartObject();
w.WriteString("format", FormatName);
w.WriteNumber("formatVersion", CurrentFormatVersion);
w.WriteNumber("formatVersion", Workspace is null ? PlainFormatVersion : CurrentFormatVersion);
w.WriteString("saved", Saved);
w.WriteStartObject("archive");
w.WriteString("id", Archive.Id);
@@ -50,6 +95,7 @@ public sealed record ProjectBundle(BundleArchive Archive, BundleSequence Sequenc
if (Sequence.Title is not null) w.WriteString("title", Sequence.Title);
w.WriteNumber("frames", Sequence.Frames);
w.WriteEndObject();
if (Workspace is { } workspace) WriteWorkspace(w, workspace);
w.WritePropertyName("project");
// The project as project.json holds it, so both are read by the same tolerant reader.
using (var project = JsonDocument.Parse(Project.ToJson())) project.RootElement.WriteTo(w);
@@ -89,7 +135,8 @@ public sealed record ProjectBundle(BundleArchive Archive, BundleSequence Sequenc
ProjectSettings settings;
try
{
settings = ProjectSettings.FromJson(project.GetRawText());
// A format 1 file refuses newer settings as it always did; a workspace's opens them read-only.
settings = ProjectSettings.FromJson(project.GetRawText(), allowNewer: version >= 2);
}
catch (JsonException ex)
{
@@ -100,7 +147,10 @@ public sealed record ProjectBundle(BundleArchive Archive, BundleSequence Sequenc
new BundleArchive(Id(archive), Text(archive, "name") ?? string.Empty, Text(archive, "path")),
new BundleSequence(Id(sequence), folder, Text(sequence, "title"), frames),
settings,
saved);
saved)
{
Workspace = version >= 2 && root.TryGetProperty("workspace", out var workspace) ? ReadWorkspace(workspace) : null,
};
}
}
@@ -151,6 +201,66 @@ public sealed record ProjectBundle(BundleArchive Archive, BundleSequence Sequenc
return path;
}
private static void WriteWorkspace(Utf8JsonWriter w, BundleWorkspace workspace)
{
w.WriteStartObject("workspace");
w.WriteString("projectId", workspace.ProjectId);
w.WriteString("name", workspace.Name);
w.WriteBoolean("isMain", workspace.IsMain);
w.WriteStartObject("home");
w.WriteString("kind", workspace.Home.Kind);
if (workspace.Home.Server is { } server) w.WriteString("server", server);
if (workspace.Home.ArchiveId is { } archiveId) w.WriteString("archiveId", archiveId);
w.WriteString("sequenceId", workspace.Home.SequenceId);
w.WriteEndObject();
if (workspace.Base is { } basis)
{
w.WriteStartObject("base");
w.WriteString("versionId", basis.VersionId);
w.WriteNumber("number", basis.Number);
w.WriteString("contentHash", basis.ContentHash);
w.WriteEndObject();
}
w.WriteStartObject("media");
w.WriteString("kind", workspace.Media.Kind);
w.WriteNumber("framesVersion", workspace.Media.FramesVersion);
w.WriteEndObject();
w.WriteEndObject();
}
/// <exception cref="InvalidDataException">The section is not a workspace section this Chronos can use.</exception>
private static BundleWorkspace ReadWorkspace(JsonElement section)
{
if (section.ValueKind != JsonValueKind.Object) throw new InvalidDataException("The project file's workspace section is not an object.");
var projectId = OptionalId(section, "projectId") ?? throw new InvalidDataException("The workspace section names no project.");
var home = Section(section, "home");
var kind = Text(home, "kind");
if (kind is not (BundleHome.ArchiveKind or BundleHome.ServerKind)) throw new InvalidDataException($"The workspace's home is of an unknown kind '{kind}'.");
var sequenceId = OptionalId(home, "sequenceId") ?? throw new InvalidDataException("The workspace's home names no sequence.");
BundleBase? basis = null;
if (section.TryGetProperty("base", out var b) && b.ValueKind == JsonValueKind.Object)
{
basis = new BundleBase(
OptionalId(b, "versionId") ?? throw new InvalidDataException("The workspace's base names no version."),
Number(b, "number"),
Text(b, "contentHash") ?? throw new InvalidDataException("The workspace's base has no content hash."));
}
var media = section.TryGetProperty("media", out var m) && m.ValueKind == JsonValueKind.Object
? new BundleMedia(Text(m, "kind") ?? BundleMedia.Proxies, Number(m, "framesVersion"))
: new BundleMedia(BundleMedia.Proxies, 0);
return new BundleWorkspace(projectId, Text(section, "name") ?? string.Empty,
section.TryGetProperty("isMain", out var main) && main.ValueKind == JsonValueKind.True,
new BundleHome(kind, sequenceId, OptionalId(home, "archiveId"), Text(home, "server")), basis, media);
}
private static Guid? OptionalId(JsonElement section, string name) =>
section.TryGetProperty(name, out var value) && value.ValueKind == JsonValueKind.String && value.TryGetGuid(out var guid) && guid != Guid.Empty
? guid
: null;
private static int Number(JsonElement section, string name) =>
section.TryGetProperty(name, out var value) && value.ValueKind == JsonValueKind.Number && value.TryGetInt32(out var number) && number >= 0 ? number : 0;
private static JsonElement Section(JsonElement root, string name)
{
if (!root.TryGetProperty(name, out var section) || section.ValueKind != JsonValueKind.Object)
+145
View File
@@ -0,0 +1,145 @@
using System.Globalization;
using System.Security.Cryptography;
using System.Text;
using System.Text.Json;
using System.Text.Json.Nodes;
namespace Chronos.Core.Project;
/// <summary>
/// The portable form of a project (owner review 2, R8): the settings with every frame position (exclusions, hero, camera
/// keyframes) parked by photo as <see cref="ProjectSettings.PendingFrames"/>, so the same text means the same thing on
/// every copy of the sequence (the archive, a workspace's proxies, a server) whatever frames were inserted or removed
/// since. Project versions store this form; a copy places the positions on its own frames when it opens one
/// (<see cref="Place"/>). The text is canonical (<see cref="Canonical"/>), so equal settings give equal text and an
/// equal <see cref="Hash"/>.
/// </summary>
public static class ProjectContent
{
private static readonly FramePhotos NoFrames = new([]);
/// <summary>
/// The portable form of <paramref name="settingsJson"/>, whose positions name the frames <paramref name="frames"/>
/// (by index). A position naming no frame of <paramref name="frames"/> names nothing and goes. A project of a newer
/// Chronos is only made canonical: its positions are its own business.
/// </summary>
/// <exception cref="JsonException">The text is not a project object.</exception>
public static string ToPortable(string settingsJson, FramePhotos frames)
{
ArgumentNullException.ThrowIfNull(frames);
var canonical = Canonical(settingsJson);
if (FormatOf(canonical) > ProjectSettings.CurrentVersion) return canonical;
// With no frames there is nothing to name: a translation to no frames would keep the positions as they are.
var translated = frames.Count == 0 ? WithoutPositions(canonical) : ProjectSettings.TranslateFramePositions(canonical, frames, NoFrames);
return translated is null ? canonical : Canonical(translated);
}
/// <inheritdoc cref="ToPortable(string, FramePhotos)"/>
public static string ToPortable(ProjectSettings settings, FramePhotos frames)
{
ArgumentNullException.ThrowIfNull(settings);
return ToPortable(settings.ToJson(), frames);
}
/// <summary>
/// The settings of a portable project with its positions placed on <paramref name="frames"/>: each pending frame whose
/// photo a frame holds becomes a position again; those whose photo is not there keep waiting.
/// </summary>
/// <exception cref="JsonException">The text is not a project object.</exception>
public static string Place(string portableJson, FramePhotos frames)
{
ArgumentNullException.ThrowIfNull(frames);
ArgumentNullException.ThrowIfNull(portableJson);
if (FormatOf(portableJson) > ProjectSettings.CurrentVersion) return portableJson;
return ProjectSettings.TranslateFramePositions(portableJson, null, frames) ?? portableJson;
}
/// <summary>
/// The canonical text of a project: read (a newer Chronos's too, its unknown members kept) and written again, its
/// pending frames in a fixed order (by photo) and their capture times as wall-clock values.
/// </summary>
/// <exception cref="JsonException">The text is not a project object.</exception>
public static string Canonical(string json)
{
ArgumentNullException.ThrowIfNull(json);
ProjectSettings settings;
try
{
settings = ProjectSettings.FromJson(json, allowNewer: true);
}
catch (InvalidDataException ex)
{
throw new JsonException(ex.Message, ex);
}
if (settings.PendingFrames is { Count: > 0 } pending)
{
settings = settings with { PendingFrames = [.. pending.Select(Normalized).OrderBy(Key, StringComparer.Ordinal)] };
}
return settings.ToJson();
}
/// <summary>The SHA-256 (lower-case hex) of the UTF-8 bytes of <paramref name="text"/>: a project version's content hash.</summary>
public static string Hash(string text)
{
ArgumentNullException.ThrowIfNull(text);
return Convert.ToHexStringLower(SHA256.HashData(Encoding.UTF8.GetBytes(text)));
}
/// <summary>Whether <paramref name="hash"/> is the content hash of <paramref name="text"/> (any case).</summary>
public static bool Verifies(string text, string? hash) => hash is { Length: 64 } && string.Equals(Hash(text), hash, StringComparison.OrdinalIgnoreCase);
/// <summary>The settings format (<see cref="ProjectSettings.Version"/>) a project's text declares; 1 when it says none or is not a project.</summary>
public static int FormatOf(string? json)
{
if (string.IsNullOrWhiteSpace(json)) return ProjectSettings.CurrentVersion;
try
{
return JsonNode.Parse(json, new JsonNodeOptions { PropertyNameCaseInsensitive = true }) is JsonObject project
&& project["version"] is JsonValue value && value.TryGetValue<int>(out var version) && version > 0
? version
: ProjectSettings.CurrentVersion;
}
catch (Exception ex) when (ex is JsonException or ArgumentException)
{
return ProjectSettings.CurrentVersion;
}
}
/// <summary>
/// A pending frame as the canonical text holds it: its capture time as a wall-clock value, and the frame its keyframes
/// were on left out (0: it is set again when the photo takes its place).
/// </summary>
private static PendingFrame Normalized(PendingFrame frame) => frame with
{
CapturedAt = frame.CapturedAt is { } at ? DateTime.SpecifyKind(at, DateTimeKind.Unspecified) : null,
// Read from a hand-written entry without keyframes, the list is null.
Keyframes = frame.Keyframes is { Count: > 0 } keys ? [.. keys.Select(k => k with { Frame = 0 })] : [],
};
/// <summary>Order of pending frames in the canonical text: by hash, then capture time, size and which copy of the photo.</summary>
private static string Key(PendingFrame frame) => string.Create(CultureInfo.InvariantCulture,
$"{frame.Sha256?.ToLowerInvariant()}|{frame.CapturedAt?.Ticks:D20}|{frame.Size:D20}|{frame.Occurrence:D10}");
/// <summary>A project of a sequence without frames: its positions name nothing.</summary>
private static string? WithoutPositions(string json)
{
if (JsonNode.Parse(json) is not JsonObject project) return null;
var changed = false;
if (project["excludedFrames"] is JsonArray { Count: > 0 } excluded)
{
excluded.Clear();
changed = true;
}
if (project["heroFrame"] is not null)
{
project.Remove("heroFrame");
changed = true;
}
if (project["camera"] is JsonObject camera && camera["keyframes"] is JsonArray { Count: > 0 } keys)
{
keys.Clear();
changed = true;
}
return changed ? project.ToJsonString() : null;
}
}
+56 -2
View File
@@ -78,6 +78,10 @@ public sealed record PendingFrame
[JsonIgnore]
public FramePhoto Photo => new(Sha256, Size, CapturedAt);
/// <summary>Members this Chronos does not know (written by a newer one): kept as they are, so they survive a round trip.</summary>
[JsonExtensionData]
public Dictionary<string, JsonElement>? Extra { get; set; }
}
public sealed record TimingSettings
@@ -91,6 +95,10 @@ public sealed record TimingSettings
public double? FitToSeconds { get; init; }
public IReadOnlyList<CurvePoint> RemapCurve { get; init; } = [new(0, 0), new(1, 1)];
/// <summary>Members this Chronos does not know (written by a newer one): kept as they are, so they survive a round trip.</summary>
[JsonExtensionData]
public Dictionary<string, JsonElement>? Extra { get; set; }
}
public sealed record ExposureSettings
@@ -119,6 +127,10 @@ public sealed record ExposureSettings
/// <remarks>Written even when null: a missing value reads back as the default knee, which would turn "off" on.</remarks>
[JsonIgnore(Condition = JsonIgnoreCondition.Never)]
public double? HighlightKnee { get; init; } = 0.9;
/// <summary>Members this Chronos does not know (written by a newer one): kept as they are, so they survive a round trip.</summary>
[JsonExtensionData]
public Dictionary<string, JsonElement>? Extra { get; set; }
}
public sealed record MotionSettings
@@ -134,6 +146,10 @@ public sealed record MotionSettings
/// <summary>Path smoothing in frames (Gaussian sigma).</summary>
public Auto<double> StabilizeSmoothing { get; init; } = new();
/// <summary>Members this Chronos does not know (written by a newer one): kept as they are, so they survive a round trip.</summary>
[JsonExtensionData]
public Dictionary<string, JsonElement>? Extra { get; set; }
}
public sealed record CameraSettings
@@ -147,6 +163,10 @@ public sealed record CameraSettings
public double OffsetX { get; init; }
public double OffsetY { get; init; }
public IReadOnlyList<CameraKey> Keyframes { get; init; } = [];
/// <summary>Members this Chronos does not know (written by a newer one): kept as they are, so they survive a round trip.</summary>
[JsonExtensionData]
public Dictionary<string, JsonElement>? Extra { get; set; }
}
public sealed record StackSettings
@@ -155,6 +175,10 @@ public sealed record StackSettings
/// <summary>Window (median/mean) or trail length (star trails) in frames.</summary>
public int Length { get; init; } = 9;
/// <summary>Members this Chronos does not know (written by a newer one): kept as they are, so they survive a round trip.</summary>
[JsonExtensionData]
public Dictionary<string, JsonElement>? Extra { get; set; }
}
/// <summary>Values of an export; null fields take the preset's value (BRIEF §11.4: editing any value makes it "Custom").</summary>
@@ -173,6 +197,10 @@ public sealed record ExportOverrides
public int? Quality { get; init; }
public string? RateControl { get; init; }
public string? Encoder { get; init; }
/// <summary>Members this Chronos does not know (written by a newer one): kept as they are, so they survive a round trip.</summary>
[JsonExtensionData]
public Dictionary<string, JsonElement>? Extra { get; set; }
}
public sealed record ExportSettings
@@ -196,6 +224,10 @@ public sealed record ExportSettings
/// unless chosen, as renders travel on request (BRIEF §14.5).
/// </summary>
public bool SyncToServer { get; init; }
/// <summary>Members this Chronos does not know (written by a newer one): kept as they are, so they survive a round trip.</summary>
[JsonExtensionData]
public Dictionary<string, JsonElement>? Extra { get; set; }
}
/// <summary>
@@ -236,6 +268,20 @@ public sealed record ProjectSettings
[JsonIgnore]
public bool HeroPending => PendingFrames?.Any(p => p.Hero) == true;
/// <summary>
/// Members this Chronos does not know (settings a newer Chronos added, such as filters): kept as they are, so a project
/// read and written again loses nothing (owner review 2, R8).
/// </summary>
[JsonExtensionData]
public Dictionary<string, JsonElement>? Extra { get; set; }
/// <summary>
/// Written by a newer Chronos (<see cref="Version"/> above <see cref="CurrentVersion"/>), read with
/// <see cref="FromJson(string, bool)"/> allowing it: shown, never edited, as its known values may mean something else there.
/// </summary>
[JsonIgnore]
public bool IsNewerFormat => Version > CurrentVersion;
public string ToJson() => JsonSerializer.Serialize(this, ProjectJson.Default.ProjectSettings);
/// <summary>
@@ -245,7 +291,15 @@ public sealed record ProjectSettings
/// </summary>
/// <exception cref="JsonException">The text is not a JSON object, or repeats a member.</exception>
/// <exception cref="InvalidDataException">The project was written by a newer Chronos.</exception>
public static ProjectSettings FromJson(string json)
public static ProjectSettings FromJson(string json) => FromJson(json, allowNewer: false);
/// <summary>
/// <see cref="FromJson(string)"/>, reading a project of a newer Chronos too when <paramref name="allowNewer"/>: its
/// known values, its unknown members in <see cref="Extra"/>, and <see cref="IsNewerFormat"/> set (open it read-only).
/// </summary>
/// <exception cref="JsonException">The text is not a JSON object, repeats a member, or a known member has another type.</exception>
/// <exception cref="InvalidDataException">The project was written by a newer Chronos and <paramref name="allowNewer"/> is false.</exception>
public static ProjectSettings FromJson(string json, bool allowNewer)
{
var options = new JsonNodeOptions { PropertyNameCaseInsensitive = true };
var merged = JsonNode.Parse(new ProjectSettings().ToJson(), options)!.AsObject();
@@ -266,7 +320,7 @@ public sealed record ProjectSettings
throw new JsonException("A project must be a JSON object.");
}
var settings = JsonSerializer.Deserialize(merged, ProjectJson.Default.ProjectSettings) ?? new ProjectSettings();
if (settings.Version > CurrentVersion)
if (settings.IsNewerFormat && !allowNewer)
throw new InvalidDataException($"project.json version {settings.Version} is newer than this Chronos ({CurrentVersion}).");
return settings;
}