ttsc 0.32.1 → 0.33.0

package/cmd/ttsc-cache/stock_go_test.go

@@ -0,0 +1,163 @@
+package main
+
+import (
+  "archive/zip"
+  "bytes"
+  "crypto/sha256"
+  "encoding/hex"
+  "net/url"
+  "os"
+  "os/exec"
+  "path/filepath"
+  "regexp"
+  "runtime"
+  "strings"
+  "testing"
+)
+
+// TestStockGoCacheClient verifies the helper against the actual supported Go client.
+//
+// Verifies: a relocated module and dependency cache reuse exact actions, while a dependency update misses.
+// 1. Build the helper and serve two versions of a dependency from a private file proxy.
+// 2. Build identical modules under distinct paths and empty Go and module caches with one helper store.
+// 3. Compare archive bytes and compile counts, then change the dependency version and require compilation.
+//
+// @evidence contracts/testing.md#behavioral-verification Runs stock go build with GOCACHEPROG through the production helper executable, then observes compiler commands and archive bytes.
+// @evidence contracts/testing.md#independent-expectations Identical source and dependency bytes under -trimpath should request the same actions; a changed dependency version must change the archive and require compilation.
+// @evidence contracts/testing.md#distinguishing-cases Exercises stock Go 1.26 protocol startup, put/get, path quoting, source and module-cache relocation, and a changed dependency version.
+// @evidence contracts/testing.md#execution-ownership The test runs stock Go in temporary directories with a private file proxy and never contacts the network or publishes a release artifact.
+func TestStockGoCacheClient(t *testing.T) {
+  if !supportedGoVersion.MatchString(runtime.Version()) {
+    t.Skip("the helper protocol requires a stock Go 1.26 patch release")
+  }
+  root := filepath.Join(t.TempDir(), "native artifact path with spaces")
+  if err := os.MkdirAll(root, 0700); err != nil {
+    t.Fatal(err)
+  }
+  helper := filepath.Join(root, "cache helper"+exeSuffix())
+  buildHelper := exec.Command("go", "build", "-trimpath", "-o", helper, ".")
+  if output, err := buildHelper.CombinedOutput(); err != nil {
+    t.Fatalf("building cache helper: %v\n%s", err, output)
+  }
+  store := filepath.Join(root, "shared artifact store")
+  program := quoteGoCacheArgument(helper) + " -root " + quoteGoCacheArgument(store)
+  proxy := filepath.Join(root, "private module proxy")
+  for _, version := range []string{"v1.0.0", "v1.0.1"} {
+    directory := filepath.Join(proxy, "example.org", "cache-dep", "@v")
+    if err := os.MkdirAll(directory, 0700); err != nil {
+      t.Fatal(err)
+    }
+    module := []byte("module example.org/cache-dep\n\ngo 1.26\n")
+    info := []byte(`{"Version":"` + version + `","Time":"2026-01-01T00:00:00Z"}`)
+    var archive bytes.Buffer
+    writer := zip.NewWriter(&archive)
+    for name, body := range map[string][]byte{
+      "go.mod": module,
+      "dep.go": []byte("package dep\nfunc Value() string { return \"" + version + "\" }\n"),
+    } {
+      entry, err := writer.Create("example.org/cache-dep@" + version + "/" + name)
+      if err != nil {
+        t.Fatal(err)
+      }
+      if _, err := entry.Write(body); err != nil {
+        t.Fatal(err)
+      }
+    }
+    if err := writer.Close(); err != nil {
+      t.Fatal(err)
+    }
+    for extension, body := range map[string][]byte{
+      ".mod": module, ".info": info, ".zip": archive.Bytes(),
+    } {
+      if err := os.WriteFile(filepath.Join(directory, version+extension), body, 0600); err != nil {
+        t.Fatal(err)
+      }
+    }
+  }
+  proxyPath := filepath.ToSlash(proxy)
+  if !strings.HasPrefix(proxyPath, "/") {
+    proxyPath = "/" + proxyPath
+  }
+  proxyURL := (&url.URL{Scheme: "file", Path: proxyPath}).String()
+  compileCommand := regexp.MustCompile(`(?m)[/\\]compile(?:\.exe)?["']?\s`)
+  var archiveDigests [3]string
+  var compileCounts [3]int
+  for phase, name := range []string{"publisher", "relocated consumer", "updated dependency"} {
+    version := "v1.0.0"
+    if phase == 2 {
+      version = "v1.0.1"
+    }
+    directory := filepath.Join(root, name)
+    if err := os.MkdirAll(directory, 0700); err != nil {
+      t.Fatal(err)
+    }
+    for file, source := range map[string]string{
+      "go.mod":  "module example.org/ttsc-cache-client\n\ngo 1.26\n\nrequire example.org/cache-dep " + version + "\n",
+      "tiny.go": "package tiny\nimport \"example.org/cache-dep\"\nfunc Value() string { return dep.Value() }\n",
+    } {
+      if err := os.WriteFile(filepath.Join(directory, file), []byte(source), 0600); err != nil {
+        t.Fatal(err)
+      }
+    }
+    goCache := filepath.Join(directory, "empty go cache")
+    moduleCache := filepath.Join(directory, "empty module cache")
+    if err := os.MkdirAll(goCache, 0700); err != nil {
+      t.Fatal(err)
+    }
+    if err := os.MkdirAll(moduleCache, 0700); err != nil {
+      t.Fatal(err)
+    }
+    t.Cleanup(func() {
+      clean := exec.Command("go", "clean", "-modcache")
+      clean.Env = append(os.Environ(),
+        "GOMODCACHE="+moduleCache, "GOCACHEPROG=", "GOFLAGS=", "GOTOOLCHAIN=local", "GOWORK=off",
+      )
+      if output, err := clean.CombinedOutput(); err != nil {
+        t.Errorf("cleaning %s private module cache: %v\n%s", name, err, output)
+      }
+    })
+    archive := filepath.Join(directory, "result.a")
+    build := exec.Command("go", "build", "-mod=mod", "-trimpath", "-x", "-o", archive, ".")
+    build.Dir = directory
+    build.Env = append(os.Environ(),
+      "CGO_ENABLED=0", "GOFLAGS=", "GOWORK=off", "GOCACHE="+goCache,
+      "GOMODCACHE="+moduleCache, "GOCACHEPROG="+program,
+      "GOPROXY="+proxyURL, "GOSUMDB=off", "GOTOOLCHAIN=local",
+    )
+    output, err := build.CombinedOutput()
+    if err != nil {
+      t.Fatalf("%s stock Go build: %v\n%s", name, err, output)
+    }
+    if _, err := os.Stat(filepath.Join(moduleCache, "example.org", "cache-dep@"+version, "dep.go")); err != nil {
+      t.Fatalf("%s did not populate its separate dependency cache: %v", name, err)
+    }
+    compileCounts[phase] = len(compileCommand.FindAll(output, -1))
+    raw, err := os.ReadFile(archive)
+    if err != nil {
+      t.Fatal(err)
+    }
+    digest := sha256.Sum256(raw)
+    archiveDigests[phase] = hex.EncodeToString(digest[:])
+  }
+  if compileCounts[0] == 0 || compileCounts[1] != 0 || compileCounts[2] == 0 ||
+    archiveDigests[0] != archiveDigests[1] || archiveDigests[1] == archiveDigests[2] {
+    t.Fatalf("stock Go did not distinguish relocated and updated actions: compiles=%v archives=%v", compileCounts, archiveDigests)
+  }
+}
+
+func exeSuffix() string {
+  if runtime.GOOS == "windows" {
+    return ".exe"
+  }
+  return ""
+}
+
+func quoteGoCacheArgument(value string) string {
+  if !strings.Contains(value, "'") {
+    return "'" + value + "'"
+  }
+  if !strings.Contains(value, "\"") {
+    return "\"" + value + "\""
+  }
+  panic("test path cannot be represented by Go's command quoting")
+}

package/cmd/ttsc-cache/store.go

@@ -0,0 +1,249 @@
+package main
+
+import (
+  "crypto/rand"
+  "crypto/sha256"
+  "encoding/hex"
+  "encoding/json"
+  "errors"
+  "fmt"
+  "io"
+  "os"
+  "path/filepath"
+  "strings"
+
+  "github.com/samchon/ttsc/packages/ttsc/internal/packageartifacts"
+)
+
+type mapping struct {
+  OutputID string `json:"outputID"`
+  Size     int64  `json:"size"`
+}
+
+type artifactStore struct {
+  path        string
+  root        *os.Root
+  base        map[string]packageartifacts.Action
+  packs       map[string]packageartifacts.Pack
+  pins        []*os.File
+  pinned      map[string]bool
+  verified    map[string]bool
+  receiptName string
+}
+
+func openArtifactStore(directory string, manifest *packageartifacts.Manifest) (*artifactStore, error) {
+  if err := os.MkdirAll(directory, 0700); err != nil {
+    return nil, err
+  }
+  info, err := os.Lstat(directory)
+  if err != nil {
+    return nil, err
+  }
+  if !info.IsDir() || info.Mode()&os.ModeSymlink != 0 {
+    return nil, fmt.Errorf("artifact root is not an ordinary directory: %s", directory)
+  }
+  physical, err := filepath.EvalSymlinks(directory)
+  if err != nil {
+    return nil, err
+  }
+  root, err := os.OpenRoot(physical)
+  if err != nil {
+    return nil, err
+  }
+  store := &artifactStore{
+    path: physical, root: root,
+    base:     make(map[string]packageartifacts.Action),
+    packs:    make(map[string]packageartifacts.Pack),
+    pinned:   make(map[string]bool),
+    verified: make(map[string]bool),
+  }
+  for _, name := range []string{"base", "base/packs", "base/staging", "overlay", "overlay/bodies", "overlay/actions", "overlay/staging", "receipts"} {
+    if err := root.Mkdir(name, 0700); err != nil && !errors.Is(err, os.ErrExist) {
+      root.Close()
+      return nil, err
+    }
+    info, err := root.Lstat(name)
+    if err != nil || !info.IsDir() || info.Mode()&os.ModeSymlink != 0 {
+      root.Close()
+      return nil, fmt.Errorf("artifact directory is aliased or unreadable: %s", name)
+    }
+  }
+  if manifest != nil {
+    for _, pack := range manifest.Packs {
+      store.packs[pack.Name] = pack
+    }
+    for _, action := range manifest.Actions {
+      store.base[action.ActionID] = action
+    }
+  }
+  return store, nil
+}
+
+func (store *artifactStore) close() error {
+  var first error
+  for _, file := range store.pins {
+    if err := file.Close(); err != nil && first == nil {
+      first = err
+    }
+  }
+  if err := store.root.Close(); err != nil && first == nil {
+    first = err
+  }
+  return first
+}
+
+func (store *artifactStore) get(actionID string) (mapping, string, bool, error) {
+  index := filepath.ToSlash(filepath.Join("overlay", "actions", actionID))
+  indexFile, err := store.root.Open(index)
+  if err == nil {
+    raw, readErr := io.ReadAll(io.LimitReader(indexFile, 257))
+    closeErr := indexFile.Close()
+    if readErr != nil || closeErr != nil {
+      return mapping{}, "", false, errors.Join(readErr, closeErr)
+    }
+    var value mapping
+    if len(raw) > 256 || json.Unmarshal(raw, &value) != nil || !validID(value.OutputID) || value.Size < 0 {
+      return mapping{}, "", false, fmt.Errorf("invalid overlay mapping for action %s", actionID)
+    }
+    location, err := store.pinBody("overlay", value)
+    if errors.Is(err, os.ErrNotExist) {
+      return mapping{}, "", false, nil
+    }
+    return value, location, err == nil, err
+  }
+  if !errors.Is(err, os.ErrNotExist) {
+    return mapping{}, "", false, err
+  }
+  base, exists := store.base[actionID]
+  if !exists {
+    return mapping{}, "", false, nil
+  }
+  value := mapping{OutputID: base.OutputID, Size: base.BodyLength}
+  pack := store.packs[base.Pack]
+  owner := filepath.ToSlash(filepath.Join("base", "packs", pack.Name+"-"+pack.SHA256))
+  info, err := store.root.Lstat(owner)
+  if errors.Is(err, os.ErrNotExist) {
+    return mapping{}, "", false, nil
+  }
+  if err != nil || !info.IsDir() || info.Mode()&os.ModeSymlink != 0 {
+    return mapping{}, "", false, fmt.Errorf("invalid admitted pack %s", pack.Name)
+  }
+  marker, err := store.root.ReadFile(filepath.ToSlash(filepath.Join(owner, ".complete")))
+  if errors.Is(err, os.ErrNotExist) {
+    return mapping{}, "", false, nil
+  }
+  if err != nil || string(marker) != pack.SHA256+"\n" {
+    return mapping{}, "", false, fmt.Errorf("invalid admission marker for pack %s", pack.Name)
+  }
+  location, err := store.pinBody(owner, value)
+  if errors.Is(err, os.ErrNotExist) {
+    return mapping{}, "", false, nil
+  }
+  return value, location, err == nil, err
+}
+
+func (store *artifactStore) put(actionID, outputID string, size int64, body io.Reader) (string, error) {
+  if !validID(actionID) || !validID(outputID) || size < 0 || size > 512<<20 {
+    return "", errors.New("invalid Go cache put identity or body size")
+  }
+  staging := filepath.ToSlash(filepath.Join("overlay", "staging", randomName()))
+  file, err := store.root.OpenFile(staging, os.O_CREATE|os.O_EXCL|os.O_WRONLY, 0600)
+  if err != nil {
+    return "", err
+  }
+  defer store.root.Remove(staging)
+  hash := sha256.New()
+  written, copyErr := io.CopyN(io.MultiWriter(file, hash), body, size)
+  syncErr := file.Sync()
+  closeErr := file.Close()
+  if copyErr != nil || written != size {
+    return "", fmt.Errorf("incomplete Go cache body: %w", copyErr)
+  }
+  if syncErr != nil {
+    return "", syncErr
+  }
+  if closeErr != nil {
+    return "", closeErr
+  }
+  if hex.EncodeToString(hash.Sum(nil)) != outputID {
+    return "", errors.New("Go cache body differs from its OutputID")
+  }
+  destination := filepath.ToSlash(filepath.Join("overlay", "bodies", outputID))
+  if err := store.root.Link(staging, destination); err != nil && !errors.Is(err, os.ErrExist) {
+    return "", err
+  }
+  value := mapping{OutputID: outputID, Size: size}
+  location, err := store.pinBody("overlay", value)
+  if err != nil {
+    return "", err
+  }
+  data, err := json.Marshal(value)
+  if err != nil {
+    return "", err
+  }
+  indexStage := filepath.ToSlash(filepath.Join("overlay", "staging", randomName()))
+  indexFile, err := store.root.OpenFile(indexStage, os.O_CREATE|os.O_EXCL|os.O_WRONLY, 0600)
+  if err != nil {
+    return "", err
+  }
+  defer store.root.Remove(indexStage)
+  _, writeErr := indexFile.Write(data)
+  syncErr = indexFile.Sync()
+  closeErr = indexFile.Close()
+  if writeErr != nil || syncErr != nil || closeErr != nil {
+    return "", errors.Join(writeErr, syncErr, closeErr)
+  }
+  index := filepath.ToSlash(filepath.Join("overlay", "actions", actionID))
+  if err := store.root.Rename(indexStage, index); err != nil {
+    return "", err
+  }
+  return location, nil
+}
+
+func (store *artifactStore) pinBody(owner string, value mapping) (string, error) {
+  relative := filepath.ToSlash(filepath.Join(owner, "bodies", value.OutputID))
+  info, err := store.root.Lstat(relative)
+  if err != nil {
+    return "", err
+  }
+  if !info.Mode().IsRegular() || info.Size() != value.Size {
+    return "", fmt.Errorf("invalid artifact body %s", relative)
+  }
+  file, err := store.root.Open(relative)
+  if err != nil {
+    return "", err
+  }
+  key := owner + "/" + value.OutputID
+  if !store.verified[key] {
+    hash := sha256.New()
+    count, err := io.Copy(hash, file)
+    if err != nil || count != value.Size || hex.EncodeToString(hash.Sum(nil)) != value.OutputID {
+      file.Close()
+      return "", fmt.Errorf("artifact body failed validation: %s", relative)
+    }
+    store.verified[key] = true
+  }
+  if store.pinned[key] {
+    file.Close()
+  } else {
+    store.pins = append(store.pins, file)
+    store.pinned[key] = true
+  }
+  return filepath.Join(store.path, filepath.FromSlash(relative)), nil
+}
+
+func validID(value string) bool {
+  if len(value) != 64 {
+    return false
+  }
+  _, err := hex.DecodeString(value)
+  return err == nil && value == strings.ToLower(value)
+}
+
+func randomName() string {
+  var value [16]byte
+  if _, err := rand.Read(value[:]); err != nil {
+    panic(err)
+  }
+  return hex.EncodeToString(value[:])
+}

package/cmd/ttsc-cache/store_test.go

@@ -0,0 +1,104 @@
+package main
+
+import (
+  "bytes"
+  "crypto/sha256"
+  "encoding/hex"
+  "os"
+  "path/filepath"
+  "strings"
+  "testing"
+)
+
+// TestArtifactStore verifies the overlay's complete-body and generation contract.
+//
+// Verifies: an action is published only after its OutputID body is valid, and a later put replaces its mapping without invalidating an earlier reader.
+// 1. Put an archive, read it, and put a second body for the same action.
+// 2. Reopen the store and require the new generation while the old body still exists.
+// 3. Reject a bad digest, a truncated body and an aliased body, then treat a missing body after interrupted cleanup as a miss.
+//
+// @evidence contracts/testing.md#behavioral-verification Uses actual owned files and the store's put/get operations, asserting returned bytes and the surviving index after failed writes.
+// @evidence contracts/testing.md#independent-expectations SHA-256 is computed directly from literal body bytes; a second mapping for one ActionID follows stock Go's last-valid-put policy, while invalid bytes cannot match their claimed OutputID.
+// @evidence contracts/testing.md#distinguishing-cases Covers first put, same-action replacement, restart, zero body, wrong digest, truncated input, deduplicated output, body alias rejection and a missing body after partial cleanup; helper protocol and native clean races have separate owners.
+// @evidence contracts/testing.md#execution-ownership This Go unit test owns a temporary directory and calls storage directly; it starts no Go build or external host.
+func TestArtifactStore(t *testing.T) {
+  root := t.TempDir()
+  store, err := openArtifactStore(root, nil)
+  if err != nil {
+    t.Fatal(err)
+  }
+  defer store.close()
+  action := strings.Repeat("a", 64)
+  first := []byte("first archive")
+  second := []byte("second archive")
+  digest := func(body []byte) string {
+    sum := sha256.Sum256(body)
+    return hex.EncodeToString(sum[:])
+  }
+  firstPath, err := store.put(action, digest(first), int64(len(first)), bytes.NewReader(first))
+  if err != nil {
+    t.Fatal(err)
+  }
+  value, location, found, err := store.get(action)
+  if err != nil || !found || location != firstPath || value.OutputID != digest(first) {
+    t.Fatalf("first generation not readable: %+v %q %v %v", value, location, found, err)
+  }
+  secondPath, err := store.put(action, digest(second), int64(len(second)), bytes.NewReader(second))
+  if err != nil {
+    t.Fatal(err)
+  }
+  value, location, found, err = store.get(action)
+  if err != nil || !found || location != secondPath || value.OutputID != digest(second) {
+    t.Fatalf("new generation not readable: %+v %q %v %v", value, location, found, err)
+  }
+  if raw, err := os.ReadFile(firstPath); err != nil || !bytes.Equal(raw, first) {
+    t.Fatalf("old pinned body changed: %q %v", raw, err)
+  }
+  if _, err := store.put(action, digest(first), int64(len(second)), bytes.NewReader(second)); err == nil {
+    t.Fatal("wrong OutputID accepted")
+  }
+  if _, err := store.put(action, digest(first), int64(len(first)), bytes.NewReader(first[:3])); err == nil {
+    t.Fatal("truncated body accepted")
+  }
+  if _, err := store.put(strings.Repeat("b", 64), digest(second), int64(len(second)), bytes.NewReader(second)); err != nil {
+    t.Fatal(err)
+  }
+  empty := []byte{}
+  if _, err := store.put(strings.Repeat("c", 64), digest(empty), 0, bytes.NewReader(empty)); err != nil {
+    t.Fatal(err)
+  }
+  if err := store.close(); err != nil {
+    t.Fatal(err)
+  }
+  reopened, err := openArtifactStore(root, nil)
+  if err != nil {
+    t.Fatal(err)
+  }
+  defer reopened.close()
+  value, location, found, err = reopened.get(action)
+  if err != nil || !found || value.OutputID != digest(second) {
+    t.Fatalf("restart lost last valid generation: %+v %q %v %v", value, location, found, err)
+  }
+  aliasAction := strings.Repeat("d", 64)
+  alias := filepath.Join(root, "overlay", "bodies", digest([]byte("alias")))
+  if err := os.Symlink(secondPath, alias); err == nil {
+    if _, err := reopened.put(aliasAction, digest([]byte("alias")), int64(len("alias")), bytes.NewReader([]byte("alias"))); err == nil {
+      t.Fatal("aliased body accepted")
+    }
+  }
+  if err := reopened.close(); err != nil {
+    t.Fatal(err)
+  }
+  if err := os.Remove(secondPath); err != nil {
+    t.Fatal(err)
+  }
+  recovering, err := openArtifactStore(root, nil)
+  if err != nil {
+    t.Fatal(err)
+  }
+  defer recovering.close()
+  _, _, found, err = recovering.get(action)
+  if err != nil || found {
+    t.Fatalf("an interrupted cleanup's missing body did not become a miss: %v %v", found, err)
+  }
+}

package/cmd/ttsc-cache/tuple.go

@@ -0,0 +1,107 @@
+package main
+
+import (
+  "bytes"
+  "context"
+  "crypto/sha256"
+  "encoding/hex"
+  "encoding/json"
+  "errors"
+  "fmt"
+  "io"
+  "os"
+  "os/exec"
+  "path/filepath"
+  "regexp"
+  "strings"
+  "time"
+
+  "github.com/samchon/ttsc/packages/ttsc/internal/packageartifacts"
+)
+
+func readGoTuple(goBinary string) (packageartifacts.Tuple, error) {
+  var tuple packageartifacts.Tuple
+  if !filepath.IsAbs(goBinary) {
+    return tuple, errors.New("artifact Go executable must be absolute")
+  }
+  info, err := os.Stat(goBinary)
+  if err != nil || !info.Mode().IsRegular() || info.Size() > 256<<20 {
+    return tuple, errors.New("artifact Go executable is missing or too large")
+  }
+  file, err := os.Open(goBinary)
+  if err != nil {
+    return tuple, err
+  }
+  goHash := sha256.New()
+  _, copyErr := io.Copy(goHash, io.LimitReader(file, (256<<20)+1))
+  closeErr := file.Close()
+  if copyErr != nil || closeErr != nil {
+    return tuple, errors.Join(copyErr, closeErr)
+  }
+  output, err := runGoProbe(goBinary, "env", "-json", "GOVERSION", "GOOS", "GOARCH", "GOAMD64", "GOARM", "GOARM64", "GO386", "GOMIPS", "GOMIPS64", "GOPPC64", "GORISCV64", "GOWASM", "CGO_ENABLED", "GOEXPERIMENT", "GOFLAGS")
+  if err != nil {
+    return tuple, err
+  }
+  var values map[string]string
+  if err := json.Unmarshal(output, &values); err != nil {
+    return tuple, fmt.Errorf("decode Go tuple: %w", err)
+  }
+  if values["CGO_ENABLED"] != "0" || values["GOFLAGS"] != "" {
+    return tuple, errors.New("publisher artifacts require effective CGO_ENABLED=0 and no GOFLAGS")
+  }
+  if !supportedGoVersion.MatchString(values["GOVERSION"]) {
+    return tuple, errors.New("publisher cache protocol requires a stock Go 1.26 patch release")
+  }
+  if values["GOVERSION"] == "" || values["GOOS"] == "" || values["GOARCH"] == "" {
+    return tuple, errors.New("Go did not report a complete artifact tuple")
+  }
+  toolHash := sha256.New()
+  for _, name := range []string{"asm", "cgo", "compile", "cover", "link", "vet"} {
+    version, err := runGoProbe(goBinary, "tool", name, "-V=full")
+    if err != nil {
+      return tuple, fmt.Errorf("Go tool %s identity unavailable: %w", name, err)
+    }
+    _, _ = fmt.Fprintf(toolHash, "%s:%d:%s\n", name, len(version), version)
+  }
+  architecture := make(map[string]string)
+  for _, key := range []string{"GOAMD64", "GOARM", "GOARM64", "GO386", "GOMIPS", "GOMIPS64", "GOPPC64", "GORISCV64", "GOWASM"} {
+    if value := values[key]; value != "" {
+      architecture[key] = value
+    }
+  }
+  return packageartifacts.Tuple{
+    GoVersion: values["GOVERSION"], GoToolSHA256: hex.EncodeToString(goHash.Sum(nil)),
+    GOOS: values["GOOS"], GOARCH: values["GOARCH"], Architecture: architecture,
+    CGOEnabled: values["CGO_ENABLED"], GoExperiment: values["GOEXPERIMENT"],
+    BuildFlags: []string{"-trimpath"}, BuildTags: []string{},
+    ToolIDsSHA256: hex.EncodeToString(toolHash.Sum(nil)),
+  }, nil
+}
+
+var supportedGoVersion = regexp.MustCompile(`^go1\.26\.(0|[1-9][0-9]*)$`)
+
+func runGoProbe(goBinary string, arguments ...string) ([]byte, error) {
+  ctx, cancel := context.WithTimeout(context.Background(), 15*time.Second)
+  defer cancel()
+  command := exec.CommandContext(ctx, goBinary, arguments...)
+  output := boundedBuffer{limit: 64 << 10}
+  command.Stdout = &output
+  diagnostic := boundedBuffer{limit: 16 << 10}
+  command.Stderr = &diagnostic
+  if err := command.Run(); err != nil {
+    return nil, fmt.Errorf("stock Go probe %s failed: %w (%s)", strings.Join(arguments, " "), err, strings.TrimSpace(diagnostic.String()))
+  }
+  return output.Bytes(), nil
+}
+
+type boundedBuffer struct {
+  bytes.Buffer
+  limit int
+}
+
+func (buffer *boundedBuffer) Write(value []byte) (int, error) {
+  if len(value) > buffer.limit-buffer.Len() {
+    return 0, errors.New("stock Go identity output is too large")
+  }
+  return buffer.Buffer.Write(value)
+}

package/cmd/ttsc-cache/tuple_test.go

@@ -0,0 +1,62 @@
+package main
+
+import (
+  "crypto/sha256"
+  "encoding/hex"
+  "os"
+  "os/exec"
+  "path/filepath"
+  "runtime"
+  "testing"
+)
+
+// TestReadGoTuple verifies the selected stock-Go tool and effective build mode.
+//
+// Verifies: an eligible native tuple names the actual tool bytes and reported architecture, while unsupported flags and CGO retain source-build selection.
+// 1. Probe the host Go executable with CGO disabled and no ambient GOFLAGS.
+// 2. Compare its digest and version with independent Go and file readings.
+// 3. Set GOFLAGS and CGO independently and require tuple rejection.
+//
+// @evidence contracts/testing.md#behavioral-verification Calls the production tuple probe against the actual installed Go command and observes both eligible fields and rejected environments.
+// @evidence contracts/testing.md#independent-expectations Direct file SHA-256 and runtime's Go version provide independent tool expectations; Go's effective environment, not a caller's guessed default, decides CGO eligibility.
+// @evidence contracts/testing.md#distinguishing-cases Covers a complete CGO=0 tuple, an effective flag override and CGO=1; release manifest authentication is covered by the parser test.
+// @evidence contracts/testing.md#execution-ownership Runs bounded local Go identity probes without building source modules, downloading packages or writing repository files.
+func TestReadGoTuple(t *testing.T) {
+  if !supportedGoVersion.MatchString(runtime.Version()) {
+    t.Skip("the artifact tuple requires a stock Go 1.26 patch release")
+  }
+  goBinary, err := exec.LookPath("go")
+  if err != nil {
+    t.Fatal(err)
+  }
+  goBinary, err = filepath.Abs(goBinary)
+  if err != nil {
+    t.Fatal(err)
+  }
+  t.Setenv("CGO_ENABLED", "0")
+  t.Setenv("GOFLAGS", "")
+  t.Setenv("GOOS", runtime.GOOS)
+  t.Setenv("GOARCH", runtime.GOARCH)
+  t.Setenv("GOTOOLCHAIN", "local")
+  tuple, err := readGoTuple(goBinary)
+  if err != nil {
+    t.Fatal(err)
+  }
+  raw, err := os.ReadFile(goBinary)
+  if err != nil {
+    t.Fatal(err)
+  }
+  digest := sha256.Sum256(raw)
+  if tuple.GoToolSHA256 != hex.EncodeToString(digest[:]) || tuple.GoVersion != runtime.Version() || tuple.GOOS != runtime.GOOS || tuple.GOARCH != runtime.GOARCH || tuple.CGOEnabled != "0" || tuple.ToolIDsSHA256 == "" {
+    t.Fatalf("reported tuple differs from the selected Go tool: %+v", tuple)
+  }
+  t.Setenv("GOFLAGS", "-tags=foreign")
+  if _, err := readGoTuple(goBinary); err == nil {
+    t.Fatal("GOFLAGS override was admitted")
+  }
+  t.Setenv("GOFLAGS", "")
+  t.Setenv("CGO_ENABLED", "1")
+  if _, err := readGoTuple(goBinary); err == nil {
+    t.Fatal("effective CGO mode was admitted")
+  }
+}