appendix: 23 Code-Ausschnitte aus dem Houston-Repository

Pin nixpkgs to the revision used by itc.componentware: the channel version
ships a latexminted that crashes on Python 3.14, which made every listing
fail and sent latexmk into an endless error prompt. Also force
nonstopmode/halt-on-error so a broken listing can never loop again.

figures/code/document-key.cs

@@ -0,0 +1,41 @@
+using System.Diagnostics.CodeAnalysis;
+using System.Text;
+
+namespace Houston.Model.Documents;
+
+/// <summary>
+/// Full S3 object key of a customer document, including the customer/organization prefix.
+/// </summary>
+public readonly record struct DocumentKey(OrgSlug Org, DocumentType? Type, DocumentName Name)
+{
+    public static bool TryFromS3Key(string key, [NotNullWhen(true)] out DocumentKey? result)
+    {
+        result = null;
+
+        if (key.EndsWith('/')) return false;
+
+        var parts = key.Split('/', StringSplitOptions.RemoveEmptyEntries);
+
+        if (parts.Contains("..")) return false;
+
+        result = parts switch
+        {
+            [var org, var name] when OrgSlug.TryFromFolderName(org, out var slug)
+                => new(slug.Value, null, new(name)),
+            [var org, var type, var name] when OrgSlug.TryFromFolderName(org, out var slug)
+                => new(slug.Value, DocumentTypeExtensions.ParseStorageFolderName(type), new(name)),
+            _ => null,
+        };
+
+        return result is not null;
+    }
+
+    public override string ToString()
+    {
+        StringBuilder result = new();
+        result.Append(Org.ToString());
+        if (Type is { } type) result.Append(type.StorageFolderName).Append('/');
+        result.Append(Name);
+        return result.ToString();
+    }
+}