From 7dee2363496f9f695b7a86a17fa3a36cbe0fc847 Mon Sep 17 00:00:00 2001
From: Julian Noble <julian@precisium.com.au>
Date: Tue, 21 Jul 2026 16:12:38 +1000
Subject: [PATCH] G-110: correct tarjar .TclSoCache note - the code survives
 in-tree

The prior note claimed no .tclsocache code survives, based on a grep whose
output was head-truncated - the user spotted .TclSoCache inside the vendored
tarjar-2.4.3.tm (itself a tar-format .tm). Corrected with the surviving
locations (vendored tm ~L746/L834, _aside + _build copies, unwrapped
loadscript, c:/tclmodules/main - which also holds the intermediate tarpack
generation) and the actual mechanism as design contrast: per-user
~/.TclSoCache keyed by IN-ARCHIVE PATH (not content), warn-but-load-stale on
size/mtime mismatch, retry-once concurrency. Path-key collisions and stale
loads are exactly what content-hash keying eliminates.

Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com
---
 goals/G-110-sharedlib-extraction-cache.md | 30 ++++++++++++++++-------
 1 file changed, 21 insertions(+), 9 deletions(-)

diff --git a/goals/G-110-sharedlib-extraction-cache.md b/goals/G-110-sharedlib-extraction-cache.md
index dad10143..ad93d1ca 100644
--- a/goals/G-110-sharedlib-extraction-cache.md
+++ b/goals/G-110-sharedlib-extraction-cache.md
@@ -84,12 +84,24 @@ characterization of the existing behaviour), Tcl TIPs 741/709.
 
 - 2026-07-21: drafted and approved (user: "approved - apply both"); win32/
   old-Windows fallback requirement added from the approval message.
-- 2026-07-21 in-house precedent (user recollection): tarjar - modpod's
-  tar-archive-based predecessor - had a shared `.tclsocache` for dlls, though
-  without content-hash keying or copy-out collision handling. No `.tclsocache`
-  code survives in any current tree (verified by grep across the modpod project
-  and shellspy src), so it stands as prior art for the concept rather than
-  reusable code. Old tarjar material lives at c:/tclmodules/main - the user
-  intends to preserve and partly migrate it MANUALLY (explicitly not a goal);
-  tarjar artifacts elsewhere are not free-to-delete (see the modpod-tidy goal
-  when it lands).
+- 2026-07-21 in-house precedent: tarjar - modpod's tar-archive-based
+  predecessor - had a shared `.TclSoCache` for dlls, and THE CODE SURVIVES
+  IN-TREE (an earlier note claimed otherwise from a head-truncated grep -
+  corrected after the user spotted `.TclSoCache` inside the vendored tm):
+  `src/vendormodules/tarjar-2.4.3.tm` (~L746 check_or_make_cached_sofile,
+  ~L834 cachedir), `_aside/tarjar-2.3.tm`, `src/modules/_build/tarjar-2.3.tm`
+  + the unwrapped `#tarjar-tarjar-2.3` loadscript, and at c:/tclmodules/main
+  (which also holds the intermediate 'tarpack' generation, tarpack-1.1.x).
+  Its actual mechanism, worth recording as the design contrast: per-user
+  `~/.TclSoCache/<in-archive-dir>/<tail>` - keyed by the file's IN-ARCHIVE
+  RELATIVE PATH (not content, not origin archive); populate-if-missing with
+  mtime copied from the packaged file; staleness check = size+mtime compare
+  that only WARNS on mismatch and loads the stale cached copy anyway
+  ("remove $sofile and retry"); concurrency = retry-once-after-100ms. The
+  path-key collision class (two archives shipping same-named files; upgraded
+  packages silently loading stale binaries) is precisely what content-hash
+  keying eliminates - tarjar is prior art for the cache-location/persistence
+  half and a demonstration of why the keying half matters. Old tarjar material
+  at c:/tclmodules/main is preserve/partly-migrate, handled MANUALLY by the
+  user (explicitly not a goal); tarjar artifacts elsewhere are not
+  free-to-delete (see the modpod-tidy goal when it lands).