From fc23ad0eb945671a3509ee22f4c95c37bc8d7bc3 Mon Sep 17 00:00:00 2001
From: Meta Vens <rwvens@hotmail.com>
Date: Thu, 22 Oct 2026 19:46:17 +0200
Subject: [PATCH] Pin CultLib 2.0.0 for builds

Directory.Build.props names CultLibRoot (CULTLIB_ROOT, else the sibling checkout) and pins CultLibRevision to cultlib-unity-v2.0.0 (42dce361). Directory.Build.targets fails the build unless that checkout is at the pin and clean, as Aetheria's guard does. Project references use CultLibRoot.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
---
 Directory.Build.props                         | 10 +++++++
 Directory.Build.targets                       | 30 +++++++++++++++++++
 README.md                                     | 11 +++++++
 .../Aquarium.Epiphany.csproj                  |  4 +--
 4 files changed, 53 insertions(+), 2 deletions(-)
 create mode 100644 Directory.Build.props
 create mode 100644 Directory.Build.targets

diff --git a/Directory.Build.props b/Directory.Build.props
new file mode 100644
index 0000000..c8a3c67
--- /dev/null
+++ b/Directory.Build.props
@@ -0,0 +1,10 @@
+<Project>
+  <PropertyGroup>
+    <CultLibRoot Condition="'$(CultLibRoot)' == '' and '$(CULTLIB_ROOT)' != ''">$(CULTLIB_ROOT)</CultLibRoot>
+    <CultLibRoot Condition="'$(CultLibRoot)' == ''">$(MSBuildThisFileDirectory)..\CultLib</CultLibRoot>
+    <!-- CultLib 2.0.0: tag cultlib-unity-v2.0.0. -->
+    <CultLibRevision>42dce3611a81adc5c5fac54cadbaa5637d6022d3</CultLibRevision>
+    <GitExecutable Condition="'$(GitExecutable)' == '' and Exists('C:\Program Files\Git\cmd\git.exe')">C:\Program Files\Git\cmd\git.exe</GitExecutable>
+    <GitExecutable Condition="'$(GitExecutable)' == ''">git</GitExecutable>
+  </PropertyGroup>
+</Project>
diff --git a/Directory.Build.targets b/Directory.Build.targets
new file mode 100644
index 0000000..46d436a
--- /dev/null
+++ b/Directory.Build.targets
@@ -0,0 +1,30 @@
+<Project>
+  <!-- Builds consume CultLib at one admitted revision. Point CultLibRoot (or CULTLIB_ROOT) at a clean
+       worktree of that revision: git worktree add <path> cultlib-unity-v2.0.0 (detached) (in CultLib). -->
+  <Target Name="VerifyCultLibRevision"
+          BeforeTargets="ResolveProjectReferences"
+          Condition="'$(SkipCultLibRevisionCheck)' != 'true'">
+    <ItemGroup>
+      <_CultLibReference Include="@(ProjectReference)"
+                         Condition="$([System.String]::Copy('%(Filename)').StartsWith('GameCult.')) or '%(Filename)' == 'CultMath'" />
+    </ItemGroup>
+    <Error Condition="'@(_CultLibReference)' != '' and !Exists('$(CultLibRoot)\src\GameCult.Caching\GameCult.Caching.csproj')"
+           Text="CultLibRoot '$(CultLibRoot)' is not a CultLib checkout." />
+    <Exec Condition="'@(_CultLibReference)' != ''"
+          Command="&quot;$(GitExecutable)&quot; -C &quot;$(CultLibRoot)&quot; rev-parse HEAD"
+          ConsoleToMSBuild="true"
+          StandardOutputImportance="Low">
+      <Output TaskParameter="ConsoleOutput" PropertyName="ActualCultLibRevision" />
+    </Exec>
+    <Error Condition="'@(_CultLibReference)' != '' and '$([System.String]::Copy($(ActualCultLibRevision)).Trim())' != '$(CultLibRevision)'"
+           Text="CultLib must be revision $(CultLibRevision) (cultlib-unity-v2.0.0); found $([System.String]::Copy($(ActualCultLibRevision)).Trim()). Set CultLibRoot to a clean worktree of that tag." />
+    <Exec Condition="'@(_CultLibReference)' != ''"
+          Command="&quot;$(GitExecutable)&quot; -C &quot;$(CultLibRoot)&quot; status --porcelain --untracked-files=normal"
+          ConsoleToMSBuild="true"
+          StandardOutputImportance="Low">
+      <Output TaskParameter="ConsoleOutput" PropertyName="CultLibStatus" />
+    </Exec>
+    <Error Condition="'@(_CultLibReference)' != '' and '$([System.String]::Copy($(CultLibStatus)).Trim())' != ''"
+           Text="CultLibRoot '$(CultLibRoot)' must be clean before this repo consumes it." />
+  </Target>
+</Project>
diff --git a/README.md b/README.md
index 6ff7fdc..4c0d8c9 100644
--- a/README.md
+++ b/README.md
@@ -213,3 +213,14 @@ memory.
 - `docs/cult-runtime-surface.md`: client CultCache document surface.
 - `docs/fensalir-dependency.md`: what Aquarium consumes from Fensalir.
 - `state/README.md`: persistent state machinery.
+
+## Building against CultLib
+
+Builds are pinned to CultLib 2.0.0 (tag `cultlib-unity-v2.0.0`, revision `42dce3611a81adc5c5fac54cadbaa5637d6022d3`); the build fails if the CultLib checkout differs or is dirty. Create a pinned worktree and point the build at it:
+
+```powershell
+git -C <CultLib> worktree add --detach <path> cultlib-unity-v2.0.0
+dotnet build -p:CultLibRoot=<path>   # or set CULTLIB_ROOT=<path>
+```
+
+Without an override the sibling `..\CultLib` checkout is used and must itself be at that tag.
diff --git a/src/Aquarium.Epiphany/Aquarium.Epiphany.csproj b/src/Aquarium.Epiphany/Aquarium.Epiphany.csproj
index b138201..1c730e3 100644
--- a/src/Aquarium.Epiphany/Aquarium.Epiphany.csproj
+++ b/src/Aquarium.Epiphany/Aquarium.Epiphany.csproj
@@ -11,8 +11,8 @@
 
   <ItemGroup>
     <ProjectReference Include="..\..\..\Fensalir\src\Aquarium.Engine.Contracts\Aquarium.Engine.Contracts.csproj" />
-    <ProjectReference Include="..\..\..\CultLib\src\GameCult.Caching.MessagePack\GameCult.Caching.MessagePack.csproj" />
-    <ProjectReference Include="..\..\..\CultLib\src\GameCult.Networking\GameCult.Networking.csproj" />
+    <ProjectReference Include="$(CultLibRoot)\src\GameCult.Caching.MessagePack\GameCult.Caching.MessagePack.csproj" />
+    <ProjectReference Include="$(CultLibRoot)\src\GameCult.Networking\GameCult.Networking.csproj" />
   </ItemGroup>
 
   <ItemGroup>