feat(issue-94): optional transactions and version-control layers

README.md

@@ -41,6 +41,7 @@ package built from `doublets-rs`.
 - [docs/HOW-IT-WORKS.md](docs/HOW-IT-WORKS.md): deeper explanation of query processing, references, import/export, triggers, and the WebAssembly workbench.
 - [docs/case-studies/issue-71/README.md](docs/case-studies/issue-71/README.md): evidence and analysis behind the original documentation refresh.
 - [docs/case-studies/issue-92/README.md](docs/case-studies/issue-92/README.md): evidence and analysis behind the dual CLI + library packaging and unified API documentation site.
+- [docs/case-studies/issue-94/README.md](docs/case-studies/issue-94/README.md): evidence and analysis for the optional transactions and version-control layers.
 
 ### API references
 

csharp/.changeset/issue-94-transactions-and-version-control.md

@@ -0,0 +1,16 @@
+---
+'Foundation.Data.Doublets.Cli': minor
+---
+
+Added optional transactions and version-control layers (issue #94). The
+new `TransactionsDecorator` records each Create/Update/Delete as a
+reversible transition in a sidecar doublets store and exposes
+`BeginTransaction()` / `Commit()` / `Rollback()` plus three retention
+policies (`infinite`, `sized:<n>`, `chunked:<n>:<dir>`) and two commit
+modes (`sync`, `async`). The new `VersionControlDecorator` adds
+branching, tagging, and time-travel checkout over that log. The CLI
+surfaces both layers through `--transactions`, `--transactions-file`,
+`--commit-mode`, `--retention`, `--log`, `--vc`, `--vc-file`,
+`--branch`, `--branch-from`, `--checkout`, `--tag`, `--list-branches`,
+and `--list-tags`. When no flag is passed, behaviour is byte-identical
+to the existing CLI — no sidecar is written and no extra cost is paid.

csharp/Foundation.Data.Doublets.Cli.Library/NamedTypesDecorator.cs

@@ -2,6 +2,7 @@
 using System.Collections;
 using System.Collections.Generic;
 using System.Numerics;
+using System.Reflection;
 using Platform.Delegates;
 using Platform.Memory;
 using Platform.Data;
@@ -12,7 +13,7 @@
 
 namespace Foundation.Data.Doublets.Cli
 {
-    public class NamedTypesDecorator<TLinkAddress> : LinksDecoratorBase<TLinkAddress>, INamedTypesLinks<TLinkAddress>, IPinnedTypes<TLinkAddress>
+    public class NamedTypesDecorator<TLinkAddress> : LinksDecoratorBase<TLinkAddress>, INamedTypesLinks<TLinkAddress>, IPinnedTypes<TLinkAddress>, IDisposable
         where TLinkAddress : struct,
             IUnsignedNumber<TLinkAddress>,
             IComparisonOperators<TLinkAddress, TLinkAddress, bool>,
@@ -24,6 +25,8 @@ public class NamedTypesDecorator<TLinkAddress> : LinksDecoratorBase<TLinkAddress
         public readonly PinnedTypesDecorator<TLinkAddress> PinnedTypesDecorator;
         public readonly NamedLinks<TLinkAddress> NamedLinks;
         public readonly string NamedLinksDatabaseFileName;
+        private readonly ILinks<TLinkAddress> _namedLinksFacade;
+        private bool _disposed;
 
         public static ILinks<TLinkAddress> MakeLinks(string databaseFilename)
         {
@@ -53,6 +56,7 @@ public NamedTypesDecorator(PinnedTypesDecorator<TLinkAddress> pinnedTypesDecorat
             var namesMemory = new FileMappedResizableDirectMemory(namesDatabaseFilename, UnitedMemoryLinks<TLinkAddress>.DefaultLinksSizeStep);
             var namesLinks = new UnitedMemoryLinks<TLinkAddress>(namesMemory, UnitedMemoryLinks<TLinkAddress>.DefaultLinksSizeStep, namesConstants, IndexTreeType.Default);
             var decoratedNamesLinks = namesLinks.DecorateWithAutomaticUniquenessAndUsagesResolution();
+            _namedLinksFacade = decoratedNamesLinks;
             NamedLinks = new UnicodeStringStorage<TLinkAddress>(decoratedNamesLinks).NamedLinks;
             NamedLinksDatabaseFileName = namesDatabaseFilename;
         }
@@ -62,6 +66,52 @@ public NamedTypesDecorator(string databaseFilename, bool tracingEnabled = false)
         {
         }
 
+        public void Dispose()
+        {
+            if (_disposed) return;
+            _disposed = true;
+            DisposeLinksFacade(_namedLinksFacade);
+            DisposeLinksFacade(PinnedTypesDecorator);
+        }
+
+        private static void DisposeLinksFacade(object? facade)
+        {
+            var visited = new HashSet<object>(ReferenceEqualityComparer.Instance);
+            DisposeLinksFacade(facade, visited);
+        }
+
+        private static void DisposeLinksFacade(object? facade, HashSet<object> visited)
+        {
+            if (facade is null || !visited.Add(facade))
+            {
+                return;
+            }
+
+            foreach (var inner in EnumerateInnerLinks(facade))
+            {
+                DisposeLinksFacade(inner, visited);
+            }
+
+            if (facade is IDisposable disposable)
+            {
+                disposable.Dispose();
+            }
+        }
+
+        private static IEnumerable<object?> EnumerateInnerLinks(object facade)
+        {
+            for (var type = facade.GetType(); type is not null; type = type.BaseType)
+            {
+                foreach (var field in type.GetFields(BindingFlags.Instance | BindingFlags.Public | BindingFlags.NonPublic | BindingFlags.DeclaredOnly))
+                {
+                    if (typeof(ILinks<TLinkAddress>).IsAssignableFrom(field.FieldType))
+                    {
+                        yield return field.GetValue(facade);
+                    }
+                }
+            }
+        }
+
         public IEnumerator<TLinkAddress> GetEnumerator()
         {
             return PinnedTypesDecorator.GetEnumerator();