Added the visual briefing assistant (#893)

app/MindWork AI Studio/Assistants/VisualBriefing/VisualBriefingStore.Versions.cs

@@ -0,0 +1,633 @@
+using System.Text;
+using System.Text.Json;
+
+namespace AIStudio.Assistants.VisualBriefing;
+
+public sealed partial class VisualBriefingStore
+{
+    /// <summary>
+    /// Defines <c>AddRevisionAsync</c> for the visual briefing feature.
+    /// </summary>
+    public async Task<VisualBriefingRevisionResult> AddRevisionAsync(
+        VisualBriefingRevisionRequest request,
+        CancellationToken token = default)
+    {
+        await this.InitializeAsync(token);
+        var gate = this.GetLock(request.BriefingId);
+        await gate.WaitAsync(token);
+        
+        try
+        {
+            var manifest = await this.LoadRequiredWithoutInitializeAsync(request.BriefingId, token);
+            RefreshSourceStatuses(manifest);
+            if (request.EditMode is not (VisualBriefingEditMode.CHANGE_DESIGN or VisualBriefingEditMode.RECOMPILE) &&
+                manifest.Sources.All(source => source.Kind is not VisualBriefingSourceKind.SOURCE_MATERIAL))
+            {
+                return VisualBriefingRevisionResult.Failure("Please add at least one source material file.");
+            }
+
+            var blockingSources = manifest.Sources
+                .Where(source => source.Status is VisualBriefingSourceStatus.UNREACHABLE or VisualBriefingSourceStatus.TRANSCRIPT_OUTDATED)
+                .ToArray();
+            
+            if (request.EditMode is not (VisualBriefingEditMode.CHANGE_DESIGN or VisualBriefingEditMode.RECOMPILE) &&
+                blockingSources.Length > 0)
+                return VisualBriefingRevisionResult.Failure("One or more sources are missing or have an outdated transcript.");
+
+            var parent = request.ParentRevisionId is null
+                ? null
+                : manifest.Versions.FirstOrDefault(version => version.RevisionId == request.ParentRevisionId);
+            
+            if (request.EditMode is not VisualBriefingEditMode.INITIAL && parent is null)
+                return VisualBriefingRevisionResult.Failure("The selected parent revision no longer exists.");
+            
+            VisualBriefingArtifactParts? parentParts = null;
+            if (parent is not null)
+            {
+                parentParts = request.EditMode switch
+                {
+                    VisualBriefingEditMode.RECOMPILE => await this.ReadVersionPartsForRecompileAsync(manifest.BriefingId, parent.RevisionId, token),
+                    VisualBriefingEditMode.REBUILD => await this.ReadVersionPartsForRebuildAsync(manifest.BriefingId, parent.RevisionId, token),
+                    _ => await this.ReadVersionPartsAsync(manifest.BriefingId, parent.RevisionId, token),
+                };
+                if (parentParts is null)
+                    return VisualBriefingRevisionResult.Failure("The selected parent revision is invalid or damaged.");
+
+                var parentHashes = ComputeSectionHashes(parentParts);
+                if (!string.Equals(parent.DataHash, parentHashes.DataHash, StringComparison.Ordinal) ||
+                    !string.Equals(parent.AssetHash, parentHashes.AssetHash, StringComparison.Ordinal) ||
+                    !string.Equals(parent.TemplateHash, parentHashes.TemplateHash, StringComparison.Ordinal) ||
+                    !string.Equals(parent.CssHash, parentHashes.CssHash, StringComparison.Ordinal) ||
+                    !string.Equals(parent.RuntimeHash, parentHashes.RuntimeHash, StringComparison.Ordinal))
+                    return VisualBriefingRevisionResult.Failure("The selected parent revision does not match its protected section hashes.");
+            }
+
+            var preserveRuntime = request.EditMode is VisualBriefingEditMode.CHANGE_DESIGN or VisualBriefingEditMode.UPDATE_CONTENT;
+            var html = await artifactService.BuildAsync(
+                manifest,
+                request,
+                preserveRuntime ? parentParts?.RuntimeScript : null,
+                preserveRuntime ? parentParts?.EChartsScript : null,
+                token);
+            
+            if (!VisualBriefingArtifactService.TryParse(html, out var parts, out var parseIssue))
+                return VisualBriefingRevisionResult.Failure(parseIssue);
+
+            var hashes = ComputeSectionHashes(parts);
+            if (parent is not null)
+            {
+                if (request.EditMode is VisualBriefingEditMode.CHANGE_DESIGN &&
+                    (!string.Equals(parent.DataHash, hashes.DataHash, StringComparison.Ordinal) ||
+                     !string.Equals(parent.AssetHash, hashes.AssetHash, StringComparison.Ordinal) ||
+                     !string.Equals(parent.RuntimeHash, hashes.RuntimeHash, StringComparison.Ordinal)))
+                    return VisualBriefingRevisionResult.Failure("A design change attempted to modify facts, embedded assets, or the runtime.");
+
+                if (request.EditMode is VisualBriefingEditMode.UPDATE_CONTENT &&
+                    (!string.Equals(parent.TemplateHash, hashes.TemplateHash, StringComparison.Ordinal) ||
+                     !string.Equals(parent.CssHash, hashes.CssHash, StringComparison.Ordinal) ||
+                     !string.Equals(parent.RuntimeHash, hashes.RuntimeHash, StringComparison.Ordinal)))
+                    return VisualBriefingRevisionResult.Failure("A content update attempted to modify the template, CSS, or runtime.");
+
+                if (request.EditMode is VisualBriefingEditMode.RECOMPILE &&
+                    (request.EvidenceArtifactId != parent.EvidenceArtifactId ||
+                     request.PlanArtifactId != parent.PlanArtifactId ||
+                     request.ContentArtifactId != parent.ContentArtifactId ||
+                     !string.Equals(parent.AssetHash, hashes.AssetHash, StringComparison.Ordinal)))
+                    return VisualBriefingRevisionResult.Failure("A recompile attempted to modify semantic artifacts or embedded assets.");
+
+                if (request.EditMode is not VisualBriefingEditMode.RECOMPILE &&
+                    string.Equals(parent.DataHash, hashes.DataHash, StringComparison.Ordinal) &&
+                    string.Equals(parent.AssetHash, hashes.AssetHash, StringComparison.Ordinal) &&
+                    string.Equals(parent.TemplateHash, hashes.TemplateHash, StringComparison.Ordinal) &&
+                    string.Equals(parent.CssHash, hashes.CssHash, StringComparison.Ordinal) &&
+                    string.Equals(parent.RuntimeHash, hashes.RuntimeHash, StringComparison.Ordinal))
+                    return VisualBriefingRevisionResult.Failure("The model response did not change the briefing.");
+            }
+
+            var version = new VisualBriefingVersion
+            {
+                VersionNumber = this.NextVersionNumber(manifest),
+                RevisionId = parts.ExportManifest.RevisionId,
+                ParentRevisionId = request.ParentRevisionId,
+                CreatedAtUtc = parts.ExportManifest.CreatedAtUtc,
+                EditMode = request.EditMode,
+                Instruction = request.Instruction,
+                DocumentHash = parts.DocumentHash,
+                Origin = request.Origin,
+                DataHash = hashes.DataHash,
+                AssetHash = hashes.AssetHash,
+                TemplateHash = hashes.TemplateHash,
+                CssHash = hashes.CssHash,
+                RuntimeHash = hashes.RuntimeHash,
+                ContentArtifactId = request.ContentArtifactId,
+                PresentationArtifactId = request.PresentationArtifactId,
+                EvidenceArtifactId = request.EvidenceArtifactId,
+                PlanArtifactId = request.PlanArtifactId,
+                BuildId = request.BuildId,
+                OperationId = request.OperationId,
+                ModelContributions = request.ModelContributions?.ToList() ?? [],
+            };
+            
+            version.FileName = $"{version.VersionNumber:000000}-{version.RevisionId:D}.html";
+            await WriteTextAtomicAsync(
+                Path.Combine(this.VersionsDirectory(manifest.BriefingId), version.FileName),
+                html,
+                token,
+                overwrite: false);
+            
+            manifest.Versions.Add(version);
+            if (request.EditMode is not (VisualBriefingEditMode.CHANGE_DESIGN or VisualBriefingEditMode.RECOMPILE))
+                foreach (var source in manifest.Sources.Where(source => File.Exists(source.Path)))
+                    ApplyFileSnapshot(source, source.Path);
+            
+            manifest.ModifiedAtUtc = version.CreatedAtUtc;
+            await this.StoreManifestAtomicAsync(manifest, token);
+            return new(true, version, string.Empty);
+        }
+        catch (Exception exception) when (exception is IOException or UnauthorizedAccessException or InvalidDataException or InvalidOperationException)
+        {
+            logger.LogWarning(
+                new EventId((int)VisualBriefingLogEventId.STORE_REJECTED, nameof(VisualBriefingLogEventId.STORE_REJECTED)),
+                "Could not create a visual briefing revision. BriefingId={BriefingId} BuildId={BuildId} OperationId={OperationId} ExceptionType={ExceptionType}",
+                request.BriefingId,
+                request.BuildId,
+                request.OperationId,
+                exception.GetType().Name);
+            
+            var safeIssue = exception is InvalidDataException
+                ? exception.Message
+                : "The visual briefing version could not be stored.";
+            
+            return VisualBriefingRevisionResult.Failure(safeIssue);
+        }
+        finally
+        {
+            gate.Release();
+        }
+    }
+
+    /// <summary>
+    /// Defines <c>GetVersionPathAsync</c> for the visual briefing feature.
+    /// </summary>
+    public async Task<string?> GetVersionPathAsync(Guid briefingId, Guid revisionId, CancellationToken token = default)
+    {
+        var manifest = await this.LoadAsync(briefingId, token);
+        var version = manifest?.Versions.FirstOrDefault(candidate => candidate.RevisionId == revisionId);
+        if (version is null)
+            return null;
+
+        var path = this.VersionPath(briefingId, version);
+        return File.Exists(path) ? path : null;
+    }
+
+    /// <summary>
+    /// Reads a local immutable version that is compatible with the current semantic schema.
+    /// </summary>
+    public Task<VisualBriefingArtifactParts?> ReadVersionPartsAsync(Guid briefingId, Guid revisionId, CancellationToken token = default) =>
+        this.ReadVersionPartsCoreAsync(briefingId, revisionId, requireCurrentSchema: true, token: token);
+
+    /// <summary>
+    /// Reads an intact historical parent for rebuild lineage without requiring its semantic schema
+    /// to match the newly generated revision.
+    /// </summary>
+    /// <param name="briefingId">The briefing identifier.</param>
+    /// <param name="revisionId">The historical parent revision identifier.</param>
+    /// <param name="token">The cancellation token.</param>
+    /// <returns>The verified parent artifact parts, or <see langword="null"/>.</returns>
+    private Task<VisualBriefingArtifactParts?> ReadVersionPartsForRebuildAsync(Guid briefingId, Guid revisionId, CancellationToken token) =>
+        this.ReadVersionPartsCoreAsync(briefingId, revisionId, requireCurrentSchema: false, token: token);
+
+    /// <summary>
+    /// Reads and integrity-checks one local immutable version with the requested schema policy.
+    /// </summary>
+    /// <param name="briefingId">The briefing identifier.</param>
+    /// <param name="revisionId">The revision identifier.</param>
+    /// <param name="requireCurrentSchema">Whether the current semantic schema is required.</param>
+    /// <param name="token">The cancellation token.</param>
+    /// <returns>The verified artifact parts, or <see langword="null"/>.</returns>
+    private async Task<VisualBriefingArtifactParts?> ReadVersionPartsCoreAsync(Guid briefingId, Guid revisionId, bool requireCurrentSchema, CancellationToken token)
+    {
+        var manifest = await this.LoadAsync(briefingId, token);
+        var version = manifest?.Versions.FirstOrDefault(candidate => candidate.RevisionId == revisionId);
+        if (version is null)
+            return null;
+
+        var path = this.VersionPath(briefingId, version);
+        if (!File.Exists(path))
+            return null;
+
+        var html = await File.ReadAllTextAsync(path, token);
+        var parsed = requireCurrentSchema
+            ? VisualBriefingArtifactService.TryParseForRecompile(html, out var parts, out _)
+            : VisualBriefingArtifactService.TryParse(html, out parts, out _);
+
+        if (!parsed || parts.ExportManifest.BriefingId != briefingId || parts.ExportManifest.RevisionId != revisionId || !string.Equals(parts.DocumentHash, version.DocumentHash, StringComparison.OrdinalIgnoreCase))
+            return null;
+
+        return parts;
+    }
+
+    /// <summary>
+    /// Reads a local immutable version for recompilation, accepting an older runtime only when every
+    /// protected section still matches the locally persisted version hashes.
+    /// </summary>
+    /// <param name="briefingId">The briefing identifier.</param>
+    /// <param name="revisionId">The revision identifier.</param>
+    /// <param name="token">The cancellation token.</param>
+    /// <returns>The verified parent artifact parts, or <see langword="null"/>.</returns>
+    internal async Task<VisualBriefingArtifactParts?> ReadVersionPartsForRecompileAsync(
+        Guid briefingId,
+        Guid revisionId,
+        CancellationToken token = default)
+    {
+        var manifest = await this.LoadAsync(briefingId, token);
+        var version = manifest?.Versions.FirstOrDefault(candidate => candidate.RevisionId == revisionId);
+        if (version is null)
+            return null;
+
+        var path = this.VersionPath(briefingId, version);
+        if (!File.Exists(path))
+            return null;
+
+        var html = await File.ReadAllTextAsync(path, token);
+        if (!VisualBriefingArtifactService.TryParseForRecompile(html, out var parts, out _) ||
+            parts.ExportManifest.BriefingId != briefingId ||
+            parts.ExportManifest.RevisionId != revisionId ||
+            !string.Equals(parts.DocumentHash, version.DocumentHash, StringComparison.OrdinalIgnoreCase))
+            return null;
+
+        var hashes = ComputeSectionHashes(parts);
+        return string.Equals(version.DataHash, hashes.DataHash, StringComparison.Ordinal) &&
+               string.Equals(version.AssetHash, hashes.AssetHash, StringComparison.Ordinal) &&
+               string.Equals(version.TemplateHash, hashes.TemplateHash, StringComparison.Ordinal) &&
+               string.Equals(version.CssHash, hashes.CssHash, StringComparison.Ordinal) &&
+               string.Equals(version.RuntimeHash, hashes.RuntimeHash, StringComparison.Ordinal)
+            ? parts
+            : null;
+    }
+
+    /// <summary>
+    /// Opens a validated immutable version for direct streaming.
+    /// </summary>
+    /// <param name="briefingId">The briefing identifier.</param>
+    /// <param name="revisionId">The revision identifier.</param>
+    /// <param name="token">The cancellation token.</param>
+    /// <returns>The positioned stream and parsed artifact, or <see langword="null"/>.</returns>
+    public async Task<(FileStream Stream, VisualBriefingArtifactParts Parts)?> OpenIntegrityCheckedVersionAsync(Guid briefingId, Guid revisionId, CancellationToken token = default)
+    {
+        var manifest = await this.LoadAsync(briefingId, token);
+        var version = manifest?.Versions.FirstOrDefault(candidate => candidate.RevisionId == revisionId);
+        if (version is null)
+            return null;
+
+        var path = this.VersionPath(briefingId, version);
+        if (!File.Exists(path))
+            return null;
+
+        var stream = new FileStream(path, FileMode.Open, FileAccess.Read, FileShare.Read, 65_536, true);
+        try
+        {
+            using var reader = new StreamReader(stream, Encoding.UTF8, true, 65_536, leaveOpen: true);
+            var html = await reader.ReadToEndAsync(token);
+            if (!VisualBriefingArtifactService.TryParse(html, out var parts, out var issue) ||
+                parts.ExportManifest.BriefingId != briefingId ||
+                parts.ExportManifest.RevisionId != revisionId ||
+                !string.Equals(parts.DocumentHash, version.DocumentHash, StringComparison.OrdinalIgnoreCase))
+            {
+                logger.LogWarning(
+                    new EventId((int)VisualBriefingLogEventId.SECURITY_REJECTED, nameof(VisualBriefingLogEventId.SECURITY_REJECTED)),
+                    "Visual briefing document integrity check failed. BriefingId={BriefingId} RevisionId={RevisionId} Issue={Issue}",
+                    briefingId,
+                    revisionId,
+                    string.IsNullOrWhiteSpace(issue) ? "The stored header does not match the requested revision or project manifest." : issue);
+                await stream.DisposeAsync();
+                return null;
+            }
+
+            stream.Position = 0;
+            return (stream, parts);
+        }
+        catch
+        {
+            await stream.DisposeAsync();
+            throw;
+        }
+    }
+
+    /// <summary>
+    /// Defines <c>ImportAsync</c> for the visual briefing feature.
+    /// </summary>
+    public async Task<VisualBriefingImportResult> ImportAsync(string sourcePath, bool importNameConflictAsCopy, CancellationToken token = default)
+    {
+        await this.InitializeAsync(token);
+        var html = await File.ReadAllTextAsync(sourcePath, token);
+        if (!VisualBriefingArtifactService.TryParse(html, out var parts, out var issue))
+            return new(false, Guid.Empty, Guid.Empty, false, false, issue);
+
+        var export = parts.ExportManifest;
+        var existing = await this.LoadAsync(export.BriefingId, token);
+        if (existing is not null && !NamesEqual(existing.Name, export.Name))
+        {
+            if (!importNameConflictAsCopy)
+                return new(false, existing.BriefingId, export.RevisionId, true, false, "The briefing ID exists locally under a different name.");
+
+            return await this.ImportCopyAsync(html, token);
+        }
+
+        if (existing is null)
+        {
+            existing = await this.CreateAsync(
+                export.Name,
+                export.Author,
+                SettingsFromExport(export),
+                export.BriefingId,
+                token);
+        }
+
+        var gate = this.GetLock(existing.BriefingId);
+        await gate.WaitAsync(token);
+        try
+        {
+            existing = await this.LoadRequiredWithoutInitializeAsync(existing.BriefingId, token);
+            var knownRevision = existing.Versions.FirstOrDefault(version => version.RevisionId == export.RevisionId);
+            if (knownRevision is not null)
+            {
+                if (string.Equals(knownRevision.DocumentHash, parts.DocumentHash, StringComparison.OrdinalIgnoreCase))
+                {
+                    var storedVersion = await this.OpenIntegrityCheckedVersionAsync(existing.BriefingId, knownRevision.RevisionId, token);
+                    if (storedVersion is null)
+                    {
+                        await WriteTextAtomicAsync(this.VersionPath(existing.BriefingId, knownRevision), html, token);
+                        var restoredHashes = ComputeSectionHashes(parts);
+                        knownRevision.DataHash = restoredHashes.DataHash;
+                        knownRevision.AssetHash = restoredHashes.AssetHash;
+                        knownRevision.TemplateHash = restoredHashes.TemplateHash;
+                        knownRevision.CssHash = restoredHashes.CssHash;
+                        knownRevision.RuntimeHash = restoredHashes.RuntimeHash;
+                        existing.ModifiedAtUtc = DateTimeOffset.UtcNow;
+                        await this.StoreManifestAtomicAsync(existing, token);
+                    }
+                    else
+                        await storedVersion.Value.Stream.DisposeAsync();
+
+                    return new(true, existing.BriefingId, export.RevisionId, false, true, string.Empty);
+                }
+
+                return new(false, existing.BriefingId, export.RevisionId, false, false, "The revision ID exists with a different document hash.");
+            }
+
+            var hashes = ComputeSectionHashes(parts);
+            (VisualBriefingContentArtifact Content, VisualBriefingPresentationArtifact Presentation)? importedArtifacts = null;
+            
+            if (VisualBriefingArtifactService.TryParseForRecompile(html, out var compatibleParts, out _))
+                importedArtifacts = await this.MaterializeImportedArtifactsAsync(existing.BriefingId, compatibleParts, projectLockHeld: true, token: token);
+            
+            var version = new VisualBriefingVersion
+            {
+                VersionNumber = this.NextVersionNumber(existing),
+                SchemaVersion = export.SchemaVersion,
+                IntermediateArtifactVersion = importedArtifacts is null ? 0 : VisualBriefingVersions.INTERMEDIATE_ARTIFACT,
+                EvidenceContractVersion = importedArtifacts is null ? 0 : VisualBriefingVersions.EVIDENCE_CONTRACT,
+                PlanContractVersion = importedArtifacts is null ? 0 : VisualBriefingVersions.PLAN_CONTRACT,
+                ContentContractVersion = importedArtifacts is null ? 0 : VisualBriefingVersions.CONTENT_CONTRACT,
+                DesignContractVersion = importedArtifacts is null ? 0 : VisualBriefingVersions.DESIGN_CONTRACT,
+                RevisionId = export.RevisionId,
+                ParentRevisionId = export.ParentRevisionId,
+                CreatedAtUtc = export.CreatedAtUtc,
+                EditMode = VisualBriefingEditMode.IMPORT,
+                DocumentHash = parts.DocumentHash,
+                Origin = Path.GetFileName(sourcePath),
+                DataHash = hashes.DataHash,
+                AssetHash = hashes.AssetHash,
+                TemplateHash = hashes.TemplateHash,
+                CssHash = hashes.CssHash,
+                RuntimeHash = hashes.RuntimeHash,
+                ContentArtifactId = importedArtifacts?.Content.ArtifactId,
+                PresentationArtifactId = importedArtifacts?.Presentation.ArtifactId,
+                ModelContributions = importedArtifacts is { } artifacts ?
+                [
+                    new(VisualBriefingModelRole.CONTENT, artifacts.Content.Model),
+                    new(VisualBriefingModelRole.DESIGN, artifacts.Presentation.Model),
+                ] : [],
+            };
+            
+            version.FileName = $"{version.VersionNumber:000000}-{version.RevisionId:D}.html";
+            await WriteTextAtomicAsync(
+                Path.Combine(this.VersionsDirectory(existing.BriefingId), version.FileName),
+                html,
+                token,
+                overwrite: false);
+            
+            existing.Versions.Add(version);
+            existing.ModifiedAtUtc = DateTimeOffset.UtcNow;
+            await this.StoreManifestAtomicAsync(existing, token);
+            return new(true, existing.BriefingId, version.RevisionId, false, false, string.Empty);
+        }
+        finally
+        {
+            gate.Release();
+        }
+    }
+
+    /// <summary>
+    /// Defines <c>ImportCopyAsync</c> for the visual briefing feature.
+    /// </summary>
+    private async Task<VisualBriefingImportResult> ImportCopyAsync(string html, CancellationToken token)
+    {
+        if (!VisualBriefingArtifactService.TryParseForRecompile(html, out var parts, out _))
+            return new(false, Guid.Empty, Guid.Empty, false, false, "This historical briefing can be imported under its original identity, but it cannot be rewritten as a copy with the current compiler.");
+
+        var copyId = Guid.NewGuid();
+        var manifest = await this.CreateAsync(
+            parts.ExportManifest.Name,
+            parts.ExportManifest.Author,
+            SettingsFromExport(parts.ExportManifest),
+            copyId,
+            token);
+        
+        var importedArtifacts = await this.MaterializeImportedArtifactsAsync(
+            manifest.BriefingId,
+            parts,
+            projectLockHeld: false,
+            token: token);
+        
+        var data = RemoveProtectedData(parts.Data);
+        var assets = VisualBriefingData.ExtractAssets(parts.Data);
+        var result = await this.AddRevisionAsync(new(
+            manifest.BriefingId,
+            null,
+            VisualBriefingEditMode.INITIAL,
+            string.Empty,
+            data,
+            parts.TemplateHtml,
+            parts.Css,
+            string.Empty,
+            "Imported copy",
+            importedArtifacts.Content.ArtifactId,
+            importedArtifacts.Presentation.ArtifactId,
+            ModelContributions:
+            [
+                new(VisualBriefingModelRole.CONTENT, importedArtifacts.Content.Model),
+                new(VisualBriefingModelRole.DESIGN, importedArtifacts.Presentation.Model),
+            ],
+            EmbeddedAssets: assets,
+            AssetPlan: importedArtifacts.Content.AssetPlan), token);
+        
+        return result is { Success: true, Version: not null }
+            ? new(true, manifest.BriefingId, result.Version.RevisionId, false, false, string.Empty)
+            : new(false, manifest.BriefingId, Guid.Empty, false, false, result.Issue);
+    }
+
+    /// <summary>
+    /// Materializes local immutable intermediate artifacts from a validated imported standalone version.
+    /// </summary>
+    /// <param name="briefingId">The local briefing identifier.</param>
+    /// <param name="parts">The validated standalone artifact parts.</param>
+    /// <param name="projectLockHeld">Whether the caller already owns the project lock.</param>
+    /// <param name="token">The cancellation token.</param>
+    /// <returns>The local content and presentation artifacts.</returns>
+    private async Task<(VisualBriefingContentArtifact Content, VisualBriefingPresentationArtifact Presentation)> MaterializeImportedArtifactsAsync(
+            Guid briefingId,
+            VisualBriefingArtifactParts parts,
+            bool projectLockHeld,
+            CancellationToken token)
+    {
+        var businessData = VisualBriefingData.RemoveProtectedData(parts.Data);
+        var assetPlan = VisualBriefingData.ExtractAssetPlan(parts.Data);
+        var structuralSignature = VisualBriefingHashing.StructuralSignature(businessData);
+        
+        List<VisualBriefingSourceCoverage> coverage = [];
+        var importedSlots = new List<VisualBriefingSlotValue>
+        {
+            new() { SlotId = "imported_data", Value = businessData },
+        };
+        
+        var content = new VisualBriefingContentArtifact
+        {
+            ArtifactId = Guid.NewGuid(),
+            CreatedAtUtc = DateTimeOffset.UtcNow,
+            Data = businessData,
+            Slots = importedSlots,
+            ResetLabel = "Reset",
+            SourceCoverage = coverage,
+            AssetPlan = assetPlan,
+            StructuralSignature = structuralSignature,
+            Model = "Imported artifact",
+        };
+
+        // An imported briefing carries no charts, controls, formulas, accessibility texts, or source
+        // references. Hashing the artifact itself keeps those empty sections in the right places
+        // without spelling them out as literals here.
+        content.PayloadHash = VisualBriefingPayloadHash.ForContent(content.Slots, content.Charts, content.Controls, content.Formulas, content.AccessibilityTexts,
+            content.SourceReferences, content.ResetLabel, content.SourceCoverage, content.AssetPlan, content.StructuralSignature);
+        
+        var importedLayout = new VisualBriefingLayoutNode
+        {
+            NodeId = "imported",
+            Kind = VisualBriefingLayoutNodeKind.STACK,
+            Children =
+            [
+                new()
+                {
+                    NodeId = "imported_component_node",
+                    Kind = VisualBriefingLayoutNodeKind.COMPONENT,
+                    ComponentId = "imported_component",
+                },
+            ],
+        };
+        
+        var templateHash = VisualBriefingHashing.Compute(parts.TemplateHtml);
+        var cssHash = VisualBriefingHashing.Compute(parts.Css);
+        var presentation = new VisualBriefingPresentationArtifact
+        {
+            ArtifactId = Guid.NewGuid(),
+            CreatedAtUtc = DateTimeOffset.UtcNow,
+            PayloadHash = VisualBriefingPayloadHash.ForPresentation(importedLayout, VisualBriefingDesignProfile.EDITORIAL, templateHash, cssHash),
+            Layout = importedLayout,
+            Profile = VisualBriefingDesignProfile.EDITORIAL,
+            TemplateHtml = parts.TemplateHtml,
+            Css = parts.Css,
+            TemplateHash = templateHash,
+            CssHash = cssHash,
+            Model = "Imported artifact",
+        };
+        
+        if (projectLockHeld)
+        {
+            await this.WriteContentArtifactWithoutLockAsync(briefingId, content, token);
+            await this.WritePresentationArtifactWithoutLockAsync(briefingId, presentation, token);
+        }
+        else
+        {
+            await this.WriteContentArtifactAsync(briefingId, content, token);
+            await this.WritePresentationArtifactAsync(briefingId, presentation, token);
+        }
+        
+        return (content, presentation);
+    }
+
+    /// <summary>
+    /// Defines <c>SettingsFromExport</c> for the visual briefing feature.
+    /// </summary>
+    private static VisualBriefingLocalSettings SettingsFromExport(VisualBriefingExportManifest export) => new()
+    {
+        TargetLanguage = export.TargetLanguage,
+        CustomTargetLanguage = export.CustomTargetLanguage,
+        AudienceProfile = export.AudienceProfile,
+        AudienceAgeGroup = export.AudienceAgeGroup,
+        AudienceOrganizationalLevel = export.AudienceOrganizationalLevel,
+        AudienceExpertise = export.AudienceExpertise,
+        ShowSourceReferences = export.ShowSourceReferences,
+        ProtectionLevel = export.ProtectionLevel,
+        CustomProtectionLevel = export.CustomProtectionLevel,
+    };
+
+    /// <summary>
+    /// Defines <c>RemoveProtectedData</c> for the visual briefing feature.
+    /// </summary>
+    private static JsonElement RemoveProtectedData(JsonElement data) => VisualBriefingData.RemoveProtectedData(data);
+
+    /// <summary>
+    /// Defines <c>ComputeSectionHashes</c> for the visual briefing feature.
+    /// </summary>
+    private static SectionHashes ComputeSectionHashes(VisualBriefingArtifactParts parts)
+    {
+        var businessData = VisualBriefingHashing.CanonicalJson(VisualBriefingData.RemoveProtectedData(parts.Data));
+        var assets = JsonSerializer.Serialize(
+            VisualBriefingData.ExtractAssets(parts.Data),
+            VisualBriefingJson.Canonical);
+        
+        return new(
+            VisualBriefingHashing.Compute(businessData),
+            VisualBriefingHashing.Compute(assets),
+            VisualBriefingHashing.Compute(parts.TemplateHtml),
+            VisualBriefingHashing.Compute(parts.Css),
+            VisualBriefingHashing.Compute(parts.RuntimeScript + (parts.EChartsScript ?? string.Empty)));
+    }
+
+    /// <summary>
+    /// Defines <c>SectionHashes</c> for the visual briefing feature.
+    /// </summary>
+    private sealed record SectionHashes(string DataHash, string AssetHash, string TemplateHash, string CssHash, string RuntimeHash);
+
+    /// <summary>
+    /// Defines <c>ParseVersionNumber</c> for the visual briefing feature.
+    /// </summary>
+    private static int ParseVersionNumber(string fileName) => fileName.Length >= 6 && int.TryParse(fileName.AsSpan(0, 6), out var value) ? value : 0;
+
+    /// <summary>
+    /// Defines <c>NextVersionNumber</c> for the visual briefing feature.
+    /// </summary>
+    private int NextVersionNumber(VisualBriefingManifest manifest)
+    {
+        var manifestMaximum = manifest.Versions.Select(version => version.VersionNumber).DefaultIfEmpty().Max();
+        var diskMaximum = Directory.EnumerateFiles(this.VersionsDirectory(manifest.BriefingId), "*.html")
+            .Select(Path.GetFileName)
+            .Where(fileName => fileName is not null)
+            .Select(fileName => ParseVersionNumber(fileName!))
+            .DefaultIfEmpty()
+            .Max();
+        
+        return Math.Max(manifestMaximum, diskMaximum) + 1;
+    }
+}